Skip to content

Commit 6cdbf76

Browse files
authored
feat(web): expose each chat message as a heading for screen readers (pingdotgg#11199)
1 parent 68c2277 commit 6cdbf76

4 files changed

Lines changed: 78 additions & 2 deletions

File tree

‎apps/web/src/components/ChatMarkdown.test.tsx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -694,6 +694,28 @@ describe("ChatMarkdown artifact-template cards", () => {
694694
});
695695
});
696696

697+
describe("ChatMarkdown heading levels", () => {
698+
it("exposes headings below the host heading without changing their tags", () => {
699+
const html = renderToStaticMarkup(
700+
<ChatMarkdown
701+
cwd="/tmp/project"
702+
text={"# Top\n\n## Section\n\n###### Fine print"}
703+
headingLevelOffset={3}
704+
/>,
705+
);
706+
707+
expect(html).toContain('<h1 aria-level="4">Top</h1>');
708+
expect(html).toContain('<h2 aria-level="5">Section</h2>');
709+
expect(html).toContain('<h6 aria-level="6">Fine print</h6>');
710+
});
711+
712+
it("leaves heading levels alone when the markdown is not nested", () => {
713+
const html = renderToStaticMarkup(<ChatMarkdown cwd="/tmp/project" text="# Top" />);
714+
715+
expect(html).toContain("<h1>Top</h1>");
716+
});
717+
});
718+
697719
describe("shouldUseMarkdownFileBrowserPrimaryAction", () => {
698720
it("uses the browser when it is the only available primary action", () => {
699721
expect(

‎apps/web/src/components/ChatMarkdown.tsx‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,11 @@ import React, {
7171
useState,
7272
type ReactNode,
7373
} from "react";
74-
import type { Components, Options as ReactMarkdownOptions } from "react-markdown";
74+
import type {
75+
Components,
76+
ExtraProps as ReactMarkdownExtraProps,
77+
Options as ReactMarkdownOptions,
78+
} from "react-markdown";
7579
import ReactMarkdown from "react-markdown";
7680
import { toHtml } from "hast-util-to-html";
7781
import { createIncrementalMarkdownPlugin } from "../markdown-incremental";
@@ -216,6 +220,10 @@ interface ChatMarkdownProps {
216220
extraRemarkPlugins?: NonNullable<ReactMarkdownOptions["remarkPlugins"]>;
217221
/** Renders a `t3-context://` link as a chip; without it the link shows its label as text. */
218222
renderContextReference?: ((reference: ChatMarkdownContextReference) => ReactNode) | undefined;
223+
/** Levels added to each markdown heading in the accessibility tree so the
224+
text nests under the heading that introduces it, such as a chat message's
225+
author. Rendered tags and their styling are unchanged. */
226+
headingLevelOffset?: number | undefined;
219227
}
220228

221229
export interface ChatMarkdownContextReference {
@@ -2217,6 +2225,7 @@ function useChatMarkdownState({
22172225
imageBaseDir,
22182226
onImageExpand,
22192227
renderContextReference,
2228+
headingLevelOffset = 0,
22202229
}: ChatMarkdownProps) {
22212230
const { resolvedTheme } = useTheme();
22222231
const [localMediaPreview, setLocalMediaPreview] = useState<ExpandedImagePreview | null>(null);
@@ -2615,6 +2624,7 @@ function useChatMarkdownState({
26152624
expandMedia,
26162625
fileLinkChip,
26172626
renderContextReference,
2627+
headingLevelOffset,
26182628
imageBaseDir,
26192629
inlineCodeFileLinkMetaByText,
26202630
isStreaming,
@@ -2643,6 +2653,7 @@ function useChatMarkdownState({
26432653
expandMedia,
26442654
fileLinkChip,
26452655
renderContextReference,
2656+
headingLevelOffset,
26462657
imageBaseDir,
26472658
inlineCodeFileLinkMetaByText,
26482659
isStreaming,
@@ -2679,8 +2690,33 @@ const ChatMarkdownRendererContext = React.createContext<
26792690
ReturnType<typeof useChatMarkdownState>["componentState"]
26802691
>(null!);
26812692

2693+
// Screen readers take a heading's level from its tag, which would let a `#` in a
2694+
// message outrank the heading placed above it. Override only the exposed level:
2695+
// the tag keeps driving the stylesheet and copy-as-markdown.
2696+
function markdownHeadingRenderer(level: 1 | 2 | 3 | 4 | 5 | 6) {
2697+
const Tag = `h${level}` as const;
2698+
return function MarkdownHeading({
2699+
node: _node,
2700+
...props
2701+
}: ComponentProps<typeof Tag> & ReactMarkdownExtraProps) {
2702+
const { headingLevelOffset } = use(ChatMarkdownRendererContext);
2703+
return (
2704+
<Tag
2705+
{...props}
2706+
aria-level={headingLevelOffset > 0 ? Math.min(level + headingLevelOffset, 6) : undefined}
2707+
/>
2708+
);
2709+
};
2710+
}
2711+
26822712
// Keep component types stable when streaming changes the message state.
26832713
const CHAT_MARKDOWN_COMPONENTS = {
2714+
h1: markdownHeadingRenderer(1),
2715+
h2: markdownHeadingRenderer(2),
2716+
h3: markdownHeadingRenderer(3),
2717+
h4: markdownHeadingRenderer(4),
2718+
h5: markdownHeadingRenderer(5),
2719+
h6: markdownHeadingRenderer(6),
26842720
div: function MarkdownDiv({ node, children, ...props }) {
26852721
const { onUseArtifactTemplate } = use(ChatMarkdownRendererContext);
26862722
const artifactTemplate = artifactTemplateFromHastProperties(node?.properties);

‎apps/web/src/components/chat/MessagesTimeline.tsx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1455,6 +1455,16 @@ function UserVideoAttachment({ file }: { readonly file: ChatFileAttachment }) {
14551455
);
14561456
}
14571457

1458+
// Screen readers skim a transcript by heading, so every message announces its
1459+
// author as one. The thread title in ChatHeader is an <h2>; headings written
1460+
// inside a message are exposed below this level. Visually hidden and excluded
1461+
// from selection so sighted users and copied text are unaffected.
1462+
const MESSAGE_HEADING_LEVEL = 3;
1463+
1464+
function MessageAuthorHeading({ children }: { children: string }) {
1465+
return <h3 className="sr-only select-none">{children}</h3>;
1466+
}
1467+
14581468
function UserTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message" }> }) {
14591469
const ctx = use(TimelineRowCtx);
14601470
const { onImageExpand, onFileOpen } = ctx;
@@ -1614,6 +1624,7 @@ function UserTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message"
16141624
return (
16151625
<div className="group flex flex-col items-end gap-1">
16161626
<div className="relative max-w-[80%] rounded-2xl bg-message p-3 text-message-foreground">
1627+
<MessageAuthorHeading>You</MessageAuthorHeading>
16171628
{(regularImages.length > 0 || userVideos.length > 0) && (
16181629
<div className="mb-2 grid max-w-[210px] grid-cols-2 gap-2">
16191630
{regularImages.map((image) => (
@@ -1845,6 +1856,7 @@ function AssistantTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "mess
18451856
return (
18461857
<>
18471858
<div className="relative min-w-0 px-1 py-0.5">
1859+
<MessageAuthorHeading>T3 Code</MessageAuthorHeading>
18481860
<AssistantCitationSource
18491861
messageId={row.message.id}
18501862
{...(ctx.threadRef ? { threadRef: ctx.threadRef } : {})}
@@ -1859,6 +1871,7 @@ function AssistantTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "mess
18591871
isStreaming={Boolean(row.message.streaming)}
18601872
lineBreaks={shouldPreserveAssistantLineBreaks(messageText)}
18611873
skills={ctx.skills}
1874+
headingLevelOffset={MESSAGE_HEADING_LEVEL}
18621875
onUseArtifactTemplate={ctx.onUseArtifactTemplate}
18631876
onImageExpand={ctx.onImageExpand}
18641877
/>
@@ -3214,6 +3227,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
32143227
lineBreaks
32153228
parseRawHtml={false}
32163229
renderContextReference={props.renderContextReference}
3230+
headingLevelOffset={MESSAGE_HEADING_LEVEL}
32173231
/>
32183232
);
32193233
});

‎apps/web/src/components/chat/ProposedPlanCard.tsx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,9 @@ export const ProposedPlanCard = memo(function ProposedPlanCard({
150150
<div className="flex flex-wrap items-center justify-between gap-3">
151151
<div className="flex min-w-0 items-center gap-2">
152152
<Badge variant="secondary">Plan</Badge>
153-
<p className="truncate text-sm font-medium text-foreground">{title}</p>
153+
{/* Same heading level as the message author headings in the timeline,
154+
so a plan's own headings nest beneath it in the outline. */}
155+
<h3 className="truncate text-sm font-medium text-foreground">{title}</h3>
154156
</div>
155157
<Menu>
156158
<MenuTrigger
@@ -177,13 +179,15 @@ export const ProposedPlanCard = memo(function ProposedPlanCard({
177179
cwd={cwd}
178180
threadRef={threadRef}
179181
isStreaming={false}
182+
headingLevelOffset={3}
180183
/>
181184
) : (
182185
<ChatMarkdown
183186
text={displayedPlanMarkdown}
184187
cwd={cwd}
185188
threadRef={threadRef}
186189
isStreaming={false}
190+
headingLevelOffset={3}
187191
/>
188192
)}
189193
{canCollapse && !expanded ? (

0 commit comments

Comments
 (0)