An open source design system that's fully customizable and agent ready
TypeScript
feat(CodeBlock): diff layer over any language (isDiff) with defaulted syntax-theme slots (#7389)
Cindy Zhangb32d73f95273
diff --git a/.changeset/cli-docs-syntax-diff-slots.md b/.changeset/cli-docs-syntax-diff-slots.mdnew file mode 100644index 0000000000..0c4f34e76a--- /dev/null+++ b/.changeset/cli-docs-syntax-diff-slots.md@@ -0,0 +1,6 @@+---+'@astryxdesign/cli': patch+---++[docs] The generated token docs list the five diff row slots of the syntax vocabulary — `--color-syntax-added`, `--color-syntax-removed`, `--color-syntax-diff-header`, `--color-syntax-added-marker`, `--color-syntax-removed-marker` — with their defaults, so `astryx docs tokens` describes nineteen syntax slots.+@cixzhangdiff --git a/.changeset/codeblock-diff-language.md b/.changeset/codeblock-diff-language.mdnew file mode 100644index 0000000000..fd787e32d5--- /dev/null+++ b/.changeset/codeblock-diff-language.md@@ -0,0 +1,12 @@+---+'@astryxdesign/core': patch+---++[feat] `CodeBlock` gains `isDiff`, a diff layer over any `language`, and Markdown renders a ```diff fence as tinted diff rows instead of plain text.++With `isDiff`, lines starting with `+` sit on a success-tinted row, `-` on an error-tinted row, `@@` hunk headers (and a `--- `/`+++ ` file-header pair directly before one) on a quiet muted row, and the rest of every line keeps the language's syntax highlighting. The glyph renders in its own column so the code's indentation lines up on every row and stays in the copied text. A changed row's margin reads the change: the tint runs under the line-number gutter too and spans the full scroll width of a long line, and the line number and the glyph take the row's marker colour, while the code keeps the syntax theme's colours. These are five new syntax-theme slots — `--color-syntax-added`, `--color-syntax-removed`, `--color-syntax-diff-header` (row paints, defaulting to `--color-success-muted` and `--color-error-muted` at 25% strength and to `--color-background-muted`; a defined syntax theme that leaves the header paint unset gets none, its header rows sitting on its own background in its punctuation colour) and `--color-syntax-added-marker`, `--color-syntax-removed-marker` (defaulting to `--color-text-green` and `--color-text-red` in the default syntax theme; a defined syntax theme that leaves them unset keeps its own line-number colour) — so existing and custom syntax themes need no change and may override them.++Markdown maps a ```diff-<lang> fence to the layer over `<lang>` (labelled `<lang> diff`) and a ```diff fence to the layer over plaintext (labelled `diff`), so a diff keeps its header, copy button, disclosure, and a viewport name that still says `diff`.++A ```diff fence that should stay plain text can use ```text. A custom `components.code` renderer is unchanged: it keeps receiving the fence's leading word characters in `language` (`diff` for both ```diff and ```diff-tsx, as today), so an existing `language === 'diff'` check still matches, and receives nothing new.+@cixzhangdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 9ba938f2c6..9a1ef28980 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -1353,6 +1353,15 @@ jobs:--project chromium \--output table-min-width-output+ # A CodeBlock diff row's tint has to follow a long line to the end of its+ # scroll width; jsdom has no layout, so only a real engine shows whether+ # the paint stops at the viewport edge when the reader scrolls.+ - name: Run CodeBlock diff row paint contract+ run: |+ pnpm exec playwright test \+ packages/core/src/CodeBlock/__tests__/DiffRowPaint.a11y.chromium.spec.ts \+ --project chromium \+ --output codeblock-diff-row-paint-output# A CodeBlock viewport is a Tab stop only while its code overflows; jsdom# has no layout, so only a real engine shows the stop appear with a wide# or capped block and stay away from a short one.diff --git a/apps/storybook/stories/CodeBlock.stories.tsx b/apps/storybook/stories/CodeBlock.stories.tsxindex 3c26236828..8530a85127 100644--- a/apps/storybook/stories/CodeBlock.stories.tsx+++ b/apps/storybook/stories/CodeBlock.stories.tsx@@ -97,6 +97,50 @@ export const WithHighlightedLines: Story = {},};+/**+ * The diff layer over a language: `+` lines sit on a success-tinted row and+ * `-` lines on an error-tinted row, the `@@` header is a quiet row, and the+ * rest of every line keeps the language's syntax highlighting. The glyph has+ * its own column, so the code's indentation lines up on every row, and copy+ * returns the exact source with its glyphs. Markdown gets this from a+ * ```diff-tsx fence.+ */+export const Diff: Story = {+ args: {+ language: 'tsx',+ isDiff: true,+ title: 'Button.tsx',+ hasLineNumbers: true,+ code: `@@ -12,7 +12,7 @@ export function Button({children, ...props}: ButtonProps) {+ return (+ <button+- className="astryx-button"++ className="astryx-button astryx-button-primary"+ type="button"+ {...props}>+ {children}`,+ },+};++/**+ * A diff whose changed lines run past the viewport: the row tint and the+ * gutter tint must follow the line to the end of the scroll width, not stop at+ * the visible edge. Toggle `isWrapped` to see the same rows wrapped instead.+ */+export const DiffLongLines: Story = {+ args: {+ language: 'tsx',+ isDiff: true,+ hasLineNumbers: true,+ isWrapped: false,+ code: `@@ -1,3 +1,3 @@+ export function Button({children, ...props}: ButtonProps) {+- return <button className="astryx-button" type="button" aria-label="A deliberately long accessible label that pushes this changed line well past the width of a phone-sized viewport" {...props}>{children}</button>;++ return <button className="astryx-button astryx-button-primary" type="button" aria-label="A deliberately long accessible label that pushes this changed line well past the width of a phone-sized viewport" {...props}>{children}</button>;+ }`,+ },+};+/*** The code viewport is a keyboard stop only while its content overflows.* This story starts fitting; the browser contract widens the code and capsdiff --git a/packages/cli/assets/docs/tree/tokens-syntax.doc.mjs b/packages/cli/assets/docs/tree/tokens-syntax.doc.mjsindex 4364e41eba..4eb9bfc2f7 100644--- a/packages/cli/assets/docs/tree/tokens-syntax.doc.mjs+++ b/packages/cli/assets/docs/tree/tokens-syntax.doc.mjs@@ -88,6 +88,26 @@ export const docs = {["--color-syntax-background","var(--color-background-muted)"+ ],+ [+ "--color-syntax-added",+ "color-mix(in srgb, var(--color-success-muted) 25%, transparent)"+ ],+ [+ "--color-syntax-removed",+ "color-mix(in srgb, var(--color-error-muted) 25%, transparent)"+ ],+ [+ "--color-syntax-diff-header",+ "var(--color-background-muted)"+ ],+ [+ "--color-syntax-added-marker",+ "var(--color-text-green)"+ ],+ [+ "--color-syntax-removed-marker",+ "var(--color-text-red)"]]}diff --git a/packages/cli/assets/docs/tree/tokens.doc.mjs b/packages/cli/assets/docs/tree/tokens.doc.mjsindex 5c5551ddd9..97dce488cd 100644--- a/packages/cli/assets/docs/tree/tokens.doc.mjs+++ b/packages/cli/assets/docs/tree/tokens.doc.mjs@@ -2,7 +2,7 @@// AUTO-GENERATED — do not edit manually.// Run: node scripts/generate-token-docs.mjs-// Total: 258 tokens across 15 categories.+// Total: 263 tokens across 15 categories./** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */export const docs = {diff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjsindex 6db8b5abdb..6c16592a89 100644--- a/packages/core/src/CodeBlock/CodeBlock.doc.mjs+++ b/packages/core/src/CodeBlock/CodeBlock.doc.mjs@@ -56,6 +56,13 @@ export const docs = {type: 'number[]',description: '1-indexed line numbers to highlight.',},+ {+ name: 'isDiff',+ type: 'boolean',+ default: 'false',+ description:+ 'Render the code as a unified diff over `language`: lines starting with + are added, - removed, @@ is a hunk header (a `--- `/`+++ ` file-header pair directly before one is a header too), anything else is context. The language label reads `diff` or `<language> diff`. The glyph sits in its own column and the rest of each line keeps syntax highlighting; copy returns the exact source. Markdown ```diff and ```diff-<lang> fences set this.',+ },{name: 'hasCopyButton',type: 'boolean',diff --git a/packages/core/src/CodeBlock/CodeBlock.test.tsx b/packages/core/src/CodeBlock/CodeBlock.test.tsxindex 8152701d07..32022f2af5 100644--- a/packages/core/src/CodeBlock/CodeBlock.test.tsx+++ b/packages/core/src/CodeBlock/CodeBlock.test.tsx@@ -121,6 +121,84 @@ describe('CodeBlock', () => {expect(screen.getByRole('group')).toHaveStyle({maxHeight: '0px'});});+ describe('diff layer', () => {+ const diff =+ '@@ -1,2 +1,2 @@\n- const a = 1;\n+ const a = 2;\n const b = 3;';++ it('marks added, removed and header rows and leaves context unmarked', () => {+ const {container} = render(+ <CodeBlock code={diff} language="typescript" isDiff />,+ );+ const rows = container.querySelectorAll('[data-line]');+ expect(rows).toHaveLength(4);+ expect(rows[0].getAttribute('data-diff')).toBe('header');+ expect(rows[1].getAttribute('data-diff')).toBe('removed');+ expect(rows[2].getAttribute('data-diff')).toBe('added');+ expect(rows[3].getAttribute('data-diff')).toBeNull();+ });++ it('puts the glyph in its own marker column and keeps base-language tokens past it', () => {+ const {container} = render(+ <CodeBlock code={diff} language="typescript" isDiff />,+ );+ const rows = container.querySelectorAll('[data-line]');+ const marker = (row: Element) =>+ row.querySelector('[data-diff-marker]')?.textContent;+ expect(marker(rows[1])).toBe('-');+ expect(marker(rows[2])).toBe('+');+ // The glyph is the source's own text, so assistive technology reads it.+ expect(rows[1].querySelector('[data-diff-marker]')).not.toHaveAttribute(+ 'aria-hidden',+ );+ expect(marker(rows[3])).toBe(' ');+ // The code column starts after the glyph on every line: the removed and+ // context lines' content keeps its own two-space indentation.+ const content = (row: Element) =>+ row.querySelectorAll('span')[1]?.textContent;+ expect(content(rows[1])).toBe(' const a = 1;');+ expect(content(rows[3])).toBe(' const b = 3;');+ // `const` is a keyword on changed and context lines alike.+ expect(rows[1].querySelector('.astryx-token-keyword')).not.toBeNull();+ expect(rows[3].querySelector('.astryx-token-keyword')).not.toBeNull();+ });++ it('keeps the header and names the viewport diff / tsx diff', () => {+ const {rerender} = render(<CodeBlock code={diff} isDiff />);+ expect(screen.getByRole('group', {name: 'diff'})).toBeInTheDocument();+ expect(screen.getByText('diff')).toBeInTheDocument();+ rerender(<CodeBlock code={diff} language="tsx" isDiff />);+ expect(screen.getByRole('group', {name: 'tsx diff'})).toBeInTheDocument();+ expect(screen.getByText('tsx diff')).toBeInTheDocument();+ });++ it('copies the exact source, glyphs included', () => {+ render(<CodeBlock code={diff} language="typescript" isDiff />);+ fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));+ expect(navigator.clipboard.writeText).toHaveBeenCalledWith(diff);+ });++ it('composes with highlightLines and does nothing without isDiff', () => {+ const {container, rerender} = render(+ <CodeBlock+ code={diff}+ language="typescript"+ isDiff+ highlightLines={[2]}+ />,+ );+ expect(+ container+ .querySelector('[data-diff="removed"]')+ ?.getAttribute('data-line'),+ ).toBe('2');+ rerender(<CodeBlock code={diff} language="typescript" />);+ expect(container.querySelector('[data-diff]')).toBeNull();+ expect(+ container.querySelector('[data-line] [aria-hidden="true"]'),+ ).toBeNull();+ });+ });+it('copies code when the copy button is clicked', () => {render(<CodeBlock code="const x = 1;" language="javascript" />);const copyButton = screen.getByRole('button', {name: 'Copy code'});diff --git a/packages/core/src/CodeBlock/CodeBlock.tsx b/packages/core/src/CodeBlock/CodeBlock.tsxindex 49fabbc72b..e586e63746 100644--- a/packages/core/src/CodeBlock/CodeBlock.tsx+++ b/packages/core/src/CodeBlock/CodeBlock.tsx@@ -37,9 +37,11 @@ import {useClipboard} from '../hooks/useClipboard';import {useScrollableArea} from '../hooks/useScrollableArea';import {Icon} from '../Icon';import {IconButton} from '../IconButton';+import type {DiffLineKind} from './tokenizer';import {tokenize,tokenizeAsync,+ splitDiffLines,flatTokensToLines,SYNC_TOKENIZE_THRESHOLD,} from './tokenizer';@@ -232,6 +234,10 @@ const styles = stylex.create({code: {display: 'block',flex: 1,+ // The block grows to its longest line, so a row's paint (diff tint,+ // highlightLines) spans the full scroll width instead of stopping at the+ // viewport edge when the reader scrolls a long line.+ minWidth: 'max-content',paddingBlock: spacingVars['--spacing-3'],paddingInline: spacingVars['--spacing-4'],margin: 0,@@ -243,6 +249,8 @@ const styles = stylex.create({overflowWrap: 'normal',},codeWrapped: {+ // Wrapped lines never overflow, and max-content would stop them wrapping.+ minWidth: 'auto',whiteSpace: 'pre-wrap',wordBreak: 'break-all',overflowWrap: 'break-word',@@ -302,6 +310,75 @@ const styles = stylex.create({marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,paddingInline: spacingVars['--spacing-4'],},+ // Diff change rows: the whole row is tinted so added and removed lines read+ // at a glance; the text keeps its ordinary colour, which stays readable on+ // the tint where the semantic text colours would not, and the leading +/-+ // glyph stays in the text as the cue that needs no colour. A caller's+ // highlightLines row is declared after these and keeps its background.+ // A changed row's margin reads the change: the tint runs under the gutter+ // cell too (the row spans the full width), and the line number and the+ // glyph take the row's marker slot. The code — tokens and plain runs alike+ // — keeps the syntax theme's colours, so an identifier looks the same on a+ // changed row as on a context row.+ lineAdded: {+ backgroundColor: 'var(--color-syntax-added)',+ marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,+ paddingInline: spacingVars['--spacing-4'],+ '::before': {color: 'var(--color-syntax-added-marker)'},+ },+ lineRemoved: {+ backgroundColor: 'var(--color-syntax-removed)',+ marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,+ paddingInline: spacingVars['--spacing-4'],+ '::before': {color: 'var(--color-syntax-removed-marker)'},+ },+ // Hunk and file headers stay visible but quiet: a muted row with secondary+ // text, never change paint.+ lineDiffHeader: {+ backgroundColor: 'var(--color-syntax-diff-header)',+ // The syntax theme's own secondary colour: text-secondary in the default+ // theme, the theme's punctuation colour in a defined one.+ color: 'var(--color-syntax-punctuation)',+ marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,+ paddingInline: spacingVars['--spacing-4'],+ },+ // The glyph column: the +, - or space of every line sits in its own track+ // before the code, so the code column starts at the same inline offset on+ // every line and the content's indentation reads exactly as written. The+ // glyph is laid out as text but not selectable; the copy button still+ // copies the original source with its glyphs.+ lineDiff: {+ display: 'grid',+ gridTemplateColumns: '1ch 1fr',+ columnGap: spacingVars['--spacing-2'],+ },+ // With line numbers the gutter's gap (which the full-height divider sits+ // in) has to stay between the number and the marker, so the grid has no+ // gap of its own and the marker carries both gaps as margins.+ lineDiffNumbered: {+ // `auto`, not `1ch`: the marker's gap margins have to widen its track.+ gridTemplateColumns: 'var(--_codeblock-gutter-width) auto 1fr',+ columnGap: 0,+ },+ // The glyph is the source's own text: read by assistive technology, kept+ // out of a drag selection (copy returns the exact source anyway).+ diffMarker: {+ color: colorVars['--color-text-secondary'],+ userSelect: 'none',+ whiteSpace: 'pre',+ },+ diffMarkerNumbered: {+ marginInlineStart: `calc(${spacingVars['--spacing-3']} + ${borderVars['--border-width']} + ${spacingVars['--spacing-4']})`,+ marginInlineEnd: spacingVars['--spacing-2'],+ },+ // On a tinted row the glyph is the cue a reader without colour depends on,+ // so it takes the row's marker slot like the line number does.+ diffMarkerAdded: {+ color: 'var(--color-syntax-added-marker)',+ },+ diffMarkerRemoved: {+ color: 'var(--color-syntax-removed-marker)',+ },sizeSm: {fontSize: typeScaleVars['--text-supporting-size'],},@@ -336,12 +413,14 @@ const CodeChunk = React.memo(function CodeChunk({lines,startIndex,highlightSet,+ diffKinds,renderLineContent,lineNumbers,}: {lines: string[];startIndex: number;highlightSet: Set<number> | null;+ diffKinds: ReadonlyArray<DiffLineKind> | null;renderLineContent: (line: string, lineIndex: number) => React.ReactNode;lineNumbers: boolean;}) {@@ -349,13 +428,22 @@ const CodeChunk = React.memo(function CodeChunk({<>{lines.map((line, j) => {const i = startIndex + j;+ const diffKind = diffKinds?.[i];return (<divkey={i}data-line={i + 1}+ data-diff={diffKind === 'context' ? undefined : diffKind}{...stylex.props(styles.line,lineNumbers && styles.lineNumbered,+ diffKinds != null && styles.lineDiff,+ diffKinds != null && lineNumbers && styles.lineDiffNumbered,+ diffKind === 'added' && styles.lineAdded,+ diffKind === 'removed' && styles.lineRemoved,+ diffKind === 'header' && styles.lineDiffHeader,+ // Last on purpose: a highlight replaces a diff tint rather than+ // stacking on it, so tokens keep their single-paint contrast.(highlightSet?.has(i + 1) ?? false) && styles.lineHighlighted,)}>{renderLineContent(line, i)}@@ -369,6 +457,7 @@ const CodeChunk = React.memo(function CodeChunk({function renderLines(lines: string[],highlightSet: Set<number> | null,+ diffKinds: ReadonlyArray<DiffLineKind> | null,renderLineContent: (line: string, lineIndex: number) => React.ReactNode,lineNumbers: boolean,chunkSize: number = LINE_CHUNK_SIZE,@@ -381,6 +470,7 @@ function renderLines(lines={lines}startIndex={0}highlightSet={highlightSet}+ diffKinds={diffKinds}renderLineContent={renderLineContent}lineNumbers={lineNumbers}/>@@ -403,6 +493,7 @@ function renderLines(lines={chunkLines}startIndex={start}highlightSet={highlightSet}+ diffKinds={diffKinds}renderLineContent={renderLineContent}lineNumbers={lineNumbers}/>@@ -424,6 +515,15 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {hasLanguageLabel?: boolean;hasLineNumbers?: boolean;highlightLines?: number[];+ /**+ * Render the code as a unified diff over `language`: lines starting with+ * `+` are added, `-` removed, `@@` is a hunk header (a `--- `/`+++ ` pair+ * directly before one is a file header), anything else is context; the+ * label reads `diff` or `<language> diff`. The glyph sits in its own column and the rest of every line+ * keeps the language's syntax highlighting. Copy still returns the exact+ * source, glyphs included.+ */+ isDiff?: boolean;hasCopyButton?: boolean;onCopy?: () => void;isWrapped?: boolean;@@ -598,6 +698,8 @@ function SpanCodeContent({lines,tokenLines,highlightSet,+ diffKinds,+ diff,isWrapped,sizeStyle,hasLineNumbers,@@ -606,6 +708,8 @@ function SpanCodeContent({lines: string[];tokenLines: TokenLine[];highlightSet: Set<number> | null;+ diffKinds: ReadonlyArray<DiffLineKind> | null;+ diff: ReturnType<typeof splitDiffLines> | null;isWrapped: boolean;sizeStyle: stylex.StyleXStyles;hasLineNumbers: boolean;@@ -618,6 +722,31 @@ function SpanCodeContent({const renderLineContent = useCallback((line: string, lineIndex: number): React.ReactNode => {const tokens = tokenLines[lineIndex] ?? [];+ if (diff) {+ // Header rows show their raw text; every other row shows its glyph in+ // the marker column and the base-language tokens of the rest.+ const kind = diff.kinds[lineIndex];+ const content = kind === 'header' ? line : diff.content[lineIndex];+ return (+ <>+ <span+ data-diff-marker=""+ {...stylex.props(+ styles.diffMarker,+ hasLineNumbers && styles.diffMarkerNumbered,+ kind === 'added' && styles.diffMarkerAdded,+ kind === 'removed' && styles.diffMarkerRemoved,+ )}>+ {diff.glyphs[lineIndex] || ' '}+ </span>+ <span {...stylex.props(styles.lineContent)}>+ {kind === 'header'+ ? content || '\u200b'+ : buildSpanLine(content, tokens)}+ </span>+ </>+ );+ }// Wrap tokens in a single element so they occupy one grid cell when line// numbers are on (see `lineNumbered`); an inline span is a no-op when off.return (@@ -626,7 +755,7 @@ function SpanCodeContent({</span>);},- [tokenLines],+ [tokenLines, diff, hasLineNumbers],);return (@@ -638,7 +767,13 @@ function SpanCodeContent({hasLineNumbers && styles.codeNumbered,hasLineNumbers && dynamicStyles.gutterWidth(maxDigits),)}>- {renderLines(lines, highlightSet, renderLineContent, hasLineNumbers)}+ {renderLines(+ lines,+ highlightSet,+ diffKinds,+ renderLineContent,+ hasLineNumbers,+ )}</code>);}@@ -651,6 +786,7 @@ function RangeCodeContent({lines,tokenLines,highlightSet,+ diffKinds,isWrapped,sizeStyle,hasLineNumbers,@@ -659,6 +795,7 @@ function RangeCodeContent({lines: string[];tokenLines: TokenLine[];highlightSet: Set<number> | null;+ diffKinds: ReadonlyArray<DiffLineKind> | null;isWrapped: boolean;sizeStyle: stylex.StyleXStyles;hasLineNumbers: boolean;@@ -698,7 +835,13 @@ function RangeCodeContent({hasLineNumbers && styles.codeNumbered,hasLineNumbers && dynamicStyles.gutterWidth(maxDigits),)}>- {renderLines(lines, highlightSet, renderLineContent, hasLineNumbers)}+ {renderLines(+ lines,+ highlightSet,+ diffKinds,+ renderLineContent,+ hasLineNumbers,+ )}</code>);}@@ -723,6 +866,7 @@ export function CodeBlock({hasLanguageLabel = true,hasLineNumbers = false,highlightLines,+ isDiff = false,hasCopyButton = true,onCopy,isWrapped = false,@@ -750,6 +894,7 @@ export function CodeBlock({});const useSpans =+ isDiff ||highlightMode === 'spans' ||(highlightMode === 'auto' && !hasHighlightAPI()) ||(highlightMode === 'auto' && isSafari());@@ -762,8 +907,19 @@ export function CodeBlock({return l;}, [code]);- const tokenLines = useTokenLines(code, language, customTokenizer);-+ // In diff mode the base language sees the code with the glyph column set+ // aside, so a `tsx` diff still highlights as `tsx` on every line; headers+ // contribute an empty line and are rendered as their raw text.+ const diff = useMemo(+ () => (isDiff ? splitDiffLines(lines) : null),+ [isDiff, lines],+ );+ const tokenLines = useTokenLines(+ diff ? diff.content.join('\n') : code,+ language,+ customTokenizer,+ );+ const diffKinds = diff?.kinds ?? null;const highlightSet = useMemo(() => (highlightLines ? new Set(highlightLines) : null),[highlightLines],@@ -779,8 +935,18 @@ export function CodeBlock({const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;// Digits in the largest line number — sizes the gutter column width.const maxLineDigits = String(lines.length).length;- const languageLabel =- hasLanguageLabel && language !== 'plaintext' ? language : null;+ // With the diff layer on, the label and viewport name say so: `diff` over+ // plaintext, `tsx diff` over a language — so a diff keeps its header,+ // collapse control, and a name that still matches a `diff` fence.+ const languageLabel = !hasLanguageLabel+ ? null+ : isDiff+ ? language === 'plaintext'+ ? 'diff'+ : `${language} diff`+ : language !== 'plaintext'+ ? language+ : null;const showHeader = title != null || languageLabel != null;// A collapsed body must never outlive the visible header that controls it.@@ -927,6 +1093,8 @@ export function CodeBlock({lines={lines}tokenLines={tokenLines}highlightSet={highlightSet}+ diffKinds={diffKinds}+ diff={diff}isWrapped={isWrapped}sizeStyle={sizeStyle}hasLineNumbers={hasLineNumbers}@@ -937,6 +1105,7 @@ export function CodeBlock({lines={lines}tokenLines={tokenLines}highlightSet={highlightSet}+ diffKinds={diffKinds}isWrapped={isWrapped}sizeStyle={sizeStyle}hasLineNumbers={hasLineNumbers}diff --git a/packages/core/src/CodeBlock/__tests__/DiffRowPaint.a11y.chromium.spec.ts b/packages/core/src/CodeBlock/__tests__/DiffRowPaint.a11y.chromium.spec.tsnew file mode 100644index 0000000000..7f2df7731d--- /dev/null+++ b/packages/core/src/CodeBlock/__tests__/DiffRowPaint.a11y.chromium.spec.ts@@ -0,0 +1,93 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file DiffRowPaint.a11y.chromium.spec.ts+ * @input Built CodeBlock diff story with lines longer than a phone viewport+ * @output Browser evidence that a changed row's paint spans the full scroll width+ * @position CodeBlock FR9 proof: row paint follows a scrolled line, and wraps+ */++import {expect, test, type Page} from '@playwright/test';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++let storybook: StaticServer;+test.beforeAll(async () => {+ storybook = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+});+test.afterAll(async () => {+ await storybook?.close();+});++async function mount(page: Page, wrapped: boolean) {+ await page.setViewportSize({width: 390, height: 700});+ await page.goto(+ `${storybook.origin}/iframe.html?id=core-codeblock--diff-long-lines&viewMode=story&args=isWrapped:${wrapped}`,+ );+ await expect(page.locator('[data-diff="added"]')).toHaveCount(1);+}++/** The painted rows, the scroll container, and the widths that matter. */+async function measure(page: Page) {+ return page.evaluate(() => {+ const scroller = document.querySelector('[role="group"]') as HTMLElement;+ const rows = ['added', 'removed'].map(kind => {+ const row = document.querySelector(+ `[data-diff="${kind}"]`,+ ) as HTMLElement;+ const rect = row.getBoundingClientRect();+ return {+ kind,+ width: Math.round(rect.width),+ lines: Math.round(+ rect.height / parseFloat(getComputedStyle(row).lineHeight),+ ),+ };+ });+ return {+ clientWidth: scroller.clientWidth,+ scrollWidth: scroller.scrollWidth,+ rows,+ };+ });+}++test("a changed row's paint spans the full scroll width of a long line", async ({+ page,+}) => {+ await mount(page, false);+ const before = await measure(page);+ // The line really overflows a phone viewport.+ expect(before.scrollWidth).toBeGreaterThan(before.clientWidth + 100);+ // Each painted row is as wide as the scrollable content, not the viewport.+ for (const row of before.rows) {+ expect(row.width).toBeGreaterThanOrEqual(before.scrollWidth - 1);+ }+ // Scrolled to the end, the rows still cover what is on screen.+ await page.evaluate(() => {+ const scroller = document.querySelector('[role="group"]') as HTMLElement;+ scroller.scrollLeft = scroller.scrollWidth;+ });+ const after = await measure(page);+ for (const row of after.rows) {+ expect(row.width).toBeGreaterThanOrEqual(after.scrollWidth - 1);+ }+});++test('in wrapped mode the rows wrap and still paint their full width', async ({+ page,+}) => {+ await mount(page, true);+ const m = await measure(page);+ // Nothing scrolls: the long line wrapped.+ expect(m.scrollWidth).toBeLessThanOrEqual(m.clientWidth + 1);+ for (const row of m.rows) {+ expect(row.lines).toBeGreaterThan(1);+ expect(row.width).toBeGreaterThanOrEqual(m.clientWidth - 1);+ }+});diff --git a/packages/core/src/CodeBlock/tokenizer.test.ts b/packages/core/src/CodeBlock/tokenizer.test.tsindex e9d250fd54..7035dc1520 100644--- a/packages/core/src/CodeBlock/tokenizer.test.ts+++ b/packages/core/src/CodeBlock/tokenizer.test.ts@@ -6,6 +6,9 @@ import {tokenizeAsync,tokenizeStreaming,flatTokensToLines,+ diffLineKind,+ parseFenceLanguage,+ splitDiffLines,} from './tokenizer';import type {TokenLine} from './tokenizer';@@ -166,3 +169,112 @@ describe('flatTokensToLines', () => {expect(result[1]).toContainEqual({type: 'number', start: 8, end: 9});});});++describe('diffLineKind', () => {+ it('classifies unified-diff lines by their first character', () => {+ expect(diffLineKind('+added line')).toBe('added');+ expect(diffLineKind('-removed line')).toBe('removed');+ expect(diffLineKind(' context line')).toBe('context');+ expect(diffLineKind('')).toBe('context');+ });++ it('keeps hunk headers out of the change rows; a lone --- or +++ is a change', () => {+ expect(diffLineKind('@@ -1,3 +1,4 @@')).toBe('header');+ expect(diffLineKind('--- a/file.ts')).toBe('removed');+ expect(diffLineKind('+++ b/file.ts')).toBe('added');+ // Lines with no glyph are context, whatever tool wrote them.+ expect(diffLineKind('diff --git a/x b/x')).toBe('context');+ expect(diffLineKind('index 83db48f..bf269f4 100644')).toBe('context');+ });++ it('splits the glyph column from the code the base language sees', () => {+ const {kinds, glyphs, content} = splitDiffLines([+ '@@ -1 +1 @@',+ '- const a = 1;',+ '+ const a = 2;',+ ' const b = 3;',+ '',+ ]);+ expect(kinds).toEqual(['header', 'removed', 'added', 'context', 'context']);+ expect(glyphs).toEqual(['', '-', '+', ' ', '']);+ expect(content).toEqual([+ '',+ ' const a = 1;',+ ' const a = 2;',+ ' const b = 3;',+ '',+ ]);+ });++ it('treats a ---/+++ pair directly before @@ as a file header anywhere, and keeps unindented context whole', () => {+ const {kinds, glyphs, content} = splitDiffLines([+ '--- a/x.ts',+ '+++ b/x.ts',+ '@@ -1 +1 @@',+ '--x;',+ '---',+ '+++y;',+ 'plain',+ '--- a/y.ts',+ '+++ b/y.ts',+ '@@ -1 +1 @@',+ '-old',+ ]);+ expect(kinds).toEqual([+ 'header',+ 'header',+ 'header',+ 'removed',+ 'removed',+ 'added',+ 'context',+ 'header',+ 'header',+ 'header',+ 'removed',+ ]);+ expect(glyphs.slice(0, 7)).toEqual(['', '', '', '-', '-', '+', '']);+ expect(content.slice(3, 7)).toEqual(['-x;', '--', '++y;', 'plain']);+ // No hunk after the pair: both lines are changes, not headers.+ expect(splitDiffLines(['--- gone', '+++ here', ' same']).kinds).toEqual([+ 'removed',+ 'added',+ 'context',+ ]);+ // A hunk ending in `---i;` / `+++i;` right before the next `@@` is code,+ // not a file header: the header form has a space after the signs.+ expect(+ splitDiffLines(['@@ -1 +1 @@', '---i;', '+++i;', '@@ -9 +9 @@', ' x'])+ .kinds,+ ).toEqual(['header', 'removed', 'added', 'header', 'context']);+ expect(diffLineKind('--- a/x.ts')).toBe('removed');+ expect(diffLineKind('--- a/x.ts', {isFileHeader: true})).toBe('header');+ });++ it('tokenizes the code past the glyph with the base language', () => {+ const {content} = splitDiffLines(['-const a = 1;', '+const a = 2;']);+ const lines = tokenize(content.join('\n'), 'typescript');+ expect(lines[0][0]).toEqual({type: 'keyword', start: 0, end: 5});+ expect(lines[1][0]).toEqual({type: 'keyword', start: 0, end: 5});+ });++ it('reads fence info strings: diff, diff-<lang>, and a plain language (patch is just a language)', () => {+ expect(parseFenceLanguage('diff')).toEqual({+ language: 'plaintext',+ isDiff: true,+ });+ expect(parseFenceLanguage('patch')).toEqual({+ language: 'patch',+ isDiff: false,+ });+ expect(parseFenceLanguage('diff-tsx')).toEqual({+ language: 'tsx',+ isDiff: true,+ });+ expect(parseFenceLanguage('tsx')).toEqual({language: 'tsx', isDiff: false});+ expect(parseFenceLanguage(undefined)).toEqual({+ language: 'plaintext',+ isDiff: false,+ });+ });+});diff --git a/packages/core/src/CodeBlock/tokenizer.ts b/packages/core/src/CodeBlock/tokenizer.tsindex 94e158ebae..10732c7c13 100644--- a/packages/core/src/CodeBlock/tokenizer.ts+++ b/packages/core/src/CodeBlock/tokenizer.ts@@ -313,6 +313,112 @@ function buildLanguagePatterns(lang: string): {}}+// ---------------------------------------------------------------------------+// Diff lines+// ---------------------------------------------------------------------------++/** How a unified-diff line reads: what it adds, removes, frames, or keeps. */+export type DiffLineKind = 'added' | 'removed' | 'header' | 'context';++/**+ * Read a Markdown fence info string the way CodeBlock renders it: `diff` is+ * the diff layer over plaintext, `diff-<lang>` (the common convention) is the+ * diff layer over `<lang>`, anything else is a language.+ */+export function parseFenceLanguage(info: string | undefined): {+ language: string;+ isDiff: boolean;+} {+ const value = (info ?? '').trim();+ if (value === 'diff') {+ return {language: 'plaintext', isDiff: true};+ }+ const layered = /^diff-(.+)$/.exec(value);+ if (layered) {+ return {language: layered[1], isDiff: true};+ }+ return {language: value || 'plaintext', isDiff: false};+}++/**+ * Split a diff into the glyph column and the code the base language sees:+ * every added, removed, or space-led context line loses its first character+ * (the `+`, `-`, or space); a context line with no leading space keeps all+ * of it; header lines contribute an empty line so offsets stay per line.+ */+export function splitDiffLines(lines: ReadonlyArray<string>): {+ kinds: DiffLineKind[];+ glyphs: string[];+ content: string[];+} {+ const kinds: DiffLineKind[] = [];+ const glyphs: string[] = [];+ const content: string[] = [];+ const fileHeaders = fileHeaderLines(lines);+ lines.forEach((line, index) => {+ const kind = diffLineKind(line, {isFileHeader: fileHeaders.has(index)});+ kinds.push(kind);+ if (kind === 'header') {+ glyphs.push('');+ content.push('');+ } else if (kind === 'context' && !line.startsWith(' ')) {+ // A context line without its leading space (an unindented diff, or+ // an empty line) has no glyph: the marker column is empty and the+ // whole line is code.+ glyphs.push('');+ content.push(line);+ } else {+ glyphs.push(line.slice(0, 1));+ content.push(line.slice(1));+ }+ });+ return {kinds, glyphs, content};+}++/**+ * Classify one line of a unified diff by its first character: `+` added,+ * `-` removed, `@@` header, anything else context. A `--- ` line (with its+ * space) directly followed by a `+++ ` line and then an `@@` line is a file+ * header (both lines), wherever it occurs; every other `---`/`+++` line is+ * removed or added, so a removed line that starts with `--` — `---i;`+ * included — is never misread. The glyph is part of the text and is never+ * removed.+ */+export function diffLineKind(+ line: string,+ {isFileHeader = false}: {isFileHeader?: boolean} = {},+): DiffLineKind {+ if (line.startsWith('@@') || isFileHeader) {+ return 'header';+ }+ if (line.startsWith('+')) {+ return 'added';+ }+ if (line.startsWith('-')) {+ return 'removed';+ }+ return 'context';+}++/**+ * The indexes of the `--- `/`+++ ` lines (unified-diff form, with the space)+ * that form a file header directly before an `@@`; `---i;` is a change.+ */+export function fileHeaderLines(lines: ReadonlyArray<string>): Set<number> {+ const headers = new Set<number>();+ for (let i = 0; i + 2 < lines.length; i++) {+ if (+ lines[i].startsWith('--- ') &&+ lines[i + 1].startsWith('+++ ') &&+ lines[i + 2].startsWith('@@')+ ) {+ headers.add(i);+ headers.add(i + 1);+ }+ }+ return headers;+}+// ---------------------------------------------------------------------------// Core tokenizer// ---------------------------------------------------------------------------diff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsxindex 5fa385afef..bccaf0eec3 100644--- a/packages/core/src/Markdown/Markdown.test.tsx+++ b/packages/core/src/Markdown/Markdown.test.tsx@@ -326,6 +326,44 @@ describe('Markdown', () => {expect(pre).toBeInTheDocument();});+ it('renders a diff-<lang> fence as a diff over that language, and diff over plaintext', () => {+ const {container, rerender} = render(+ <Markdown>{'```diff-js\n-const x = 1;\n+const x = 2;\n```'}</Markdown>,+ );+ expect(container.querySelector('[data-diff="removed"]')).not.toBeNull();+ expect(container.querySelector('[data-diff="added"]')).not.toBeNull();+ // `const` keeps its js highlighting past the glyph.+ expect(+ container.querySelector('[data-diff="added"] .astryx-token-keyword'),+ ).not.toBeNull();+ rerender(<Markdown>{'```diff\n-old\n+new\n```'}</Markdown>);+ expect(container.querySelectorAll('[data-diff]')).toHaveLength(2);+ expect(container.querySelector('.astryx-token-keyword')).toBeNull();+ rerender(<Markdown>{'```js\n-const x = 1;\n```'}</Markdown>);+ expect(container.querySelector('[data-diff]')).toBeNull();+ });++ it('hands a custom code renderer the leading word as today and nothing new', () => {+ type CodeProps = {code: string; language?: string};+ const seen: CodeProps[] = [];+ const Code = (props: CodeProps) => {+ seen.push(props);+ return <pre data-testid="custom">{props.code}</pre>;+ };+ render(+ <Markdown components={{code: Code}}>+ {+ '```diff-tsx\n-a\n+b\n```\n\n```diff\n-a\n```\n\n```tsx\nconst x = 1;\n```'+ }+ </Markdown>,+ );+ // The leading word characters, as today: a diff-tsx fence is `diff`.+ expect(seen.map(p => p.language)).toEqual(['diff', 'diff', 'tsx']);+ for (const props of seen) {+ expect(Object.keys(props).sort()).toEqual(['code', 'language']);+ }+ });+it('renders links with correct href', () => {render(<Markdown>{'[click](https://example.com)'}</Markdown>);const link = screen.getByText('click');diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsxindex 5d64d54532..d9b47e3825 100644--- a/packages/core/src/Markdown/Markdown.tsx+++ b/packages/core/src/Markdown/Markdown.tsx@@ -27,6 +27,7 @@ import {} from '../theme/tokens.stylex';import type {TextDisplay} from '../theme/types';import {CodeBlock, Code} from '../CodeBlock';+import {parseFenceLanguage} from '../CodeBlock/tokenizer';import {CheckboxList} from '../CheckboxList/CheckboxList';import {CheckboxListItem} from '../CheckboxList/CheckboxListItem';import {Blockquote} from '../Blockquote/Blockquote';@@ -1475,7 +1476,20 @@ function renderBlock(case 'code': {// Track codeblock content in cursor for accurate character countingcursor.offset += node.value.length;- const language = getMarkdownAstLegacyCodeLanguage(node) ?? 'plaintext';+ // `diff-<lang>` fences are the diff layer over <lang>; `diff` is the+ // layer over plaintext. The legacy language is the info+ // string's leading word characters, which stops at the hyphen, so the+ // diff mapping reads the whole first word and then applies the same+ // word rule to the language it names.+ const legacyLanguage =+ getMarkdownAstLegacyCodeLanguage(node) ?? 'plaintext';+ const fence = parseFenceLanguage(node.lang ?? legacyLanguage);+ const isDiff = fence.isDiff;+ // The language under the diff layer; the default CodeBlock renders it.+ const diffLanguage = isDiff+ ? fence.language.match(/^\w*/)?.[0] || 'plaintext'+ : undefined;+ const language = diffLanguage ?? legacyLanguage;// A semantic-fence proposal claims its fence before the host's code// renderer (spec:AST-036 FR17). The host renderer, or the default Code// block without one, draws every unclaimed fence and is the fallback@@ -1485,7 +1499,10 @@ function renderBlock(<CodeBlockCompkey={index}code={node.value}- language={language}+ // A supplied renderer's contract is unchanged: it keeps receiving+ // the leading word characters (`diff` for a `diff-tsx` fence, as+ // today) and nothing new; only the default path maps the layer.+ language={legacyLanguage}{...lineProp}/>) : (@@ -1504,6 +1521,7 @@ function renderBlock(<CodeBlockcode={node.value}language={language}+ isDiff={isDiff}isCollapsiblexstyle={[contentWidthValue != nulldiff --git a/packages/core/src/theme/syntax/SyntaxTheme.tsx b/packages/core/src/theme/syntax/SyntaxTheme.tsxindex 35a491b58a..e7ea7fffa8 100644--- a/packages/core/src/theme/syntax/SyntaxTheme.tsx+++ b/packages/core/src/theme/syntax/SyntaxTheme.tsx@@ -20,6 +20,8 @@ import {type SyntaxThemeTokenKey,} from './defineSyntaxTheme';import {useMediaQuery} from '../../hooks/useMediaQuery';+import {useTheme} from '../useTheme';+import {formatColor, parseColor} from '../../utils/color';// =============================================================================// Context@@ -59,6 +61,22 @@ export interface UseSyntaxThemeReturn {// Hook// =============================================================================+/** The strength of the default diff row paints: the muted tokens at 25%. */+const DIFF_TINT_STRENGTH = 0.25;++/**+ * The colour `color-mix(in srgb, <colour> <strength>, transparent)` paints, as+ * a value a canvas can use. Returns undefined for a colour the shared parser+ * does not read (the CSS default then stands).+ */+function mixWithTransparent(+ colour: string,+ strength: number,+): string | undefined {+ const parsed = parseColor(colour);+ return parsed ? formatColor({...parsed, a: parsed.a * strength}) : undefined;+}+/*** Access the current syntax theme's token values, resolved for the active* color mode. Returns null if no SyntaxTheme provider is present.@@ -74,6 +92,7 @@ export interface UseSyntaxThemeReturn {*/export function useSyntaxTheme(): UseSyntaxThemeReturn | null {const ctx = use(SyntaxThemeContext);+ const page = useTheme();const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');const effectiveMode: 'light' | 'dark' = prefersDark ? 'dark' : 'light';@@ -83,13 +102,35 @@ export function useSyntaxTheme(): UseSyntaxThemeReturn | null {}const resolved: Partial<Record<SyntaxThemeTokenKey, string>> = {};for (const key of ALL_SYNTAX_KEYS) {- resolved[key] = resolveSyntaxTokenForMode(- ctx.theme.__inputTokens[key],- effectiveMode,- );+ const input = ctx.theme.__inputTokens[key];+ if (input !== undefined) {+ resolved[key] = resolveSyntaxTokenForMode(input, effectiveMode);+ }+ }+ // A diff row slot the theme did not set follows its CSS default; a canvas+ // consumer needs a colour it can paint, so the marker slots take the+ // theme's own resolved punctuation colour and the row paints derive from+ // the enclosing page theme's resolved tokens (the same mix the CSS+ // default makes), never from a probe outside the nearest Theme.+ for (const key of ALL_SYNTAX_KEYS) {+ if (resolved[key] !== undefined) {+ continue;+ }+ const fallback = ctx.theme.tokens[key] ?? '';+ if (key === 'added-marker' || key === 'removed-marker') {+ resolved[key] = resolved.punctuation ?? fallback;+ } else if (key === 'added' || key === 'removed') {+ const base = page.token(+ key === 'added' ? '--color-success-muted' : '--color-error-muted',+ );+ resolved[key] =+ mixWithTransparent(base, DIFF_TINT_STRENGTH) ?? fallback;+ } else {+ resolved[key] = fallback;+ }}return resolved as Record<SyntaxThemeTokenKey, string>;- }, [ctx, effectiveMode]);+ }, [ctx, effectiveMode, page]);if (!ctx || !tokens) {return null;diff --git a/packages/core/src/theme/syntax/defineSyntaxTheme.diff.test.ts b/packages/core/src/theme/syntax/defineSyntaxTheme.diff.test.tsnew file mode 100644index 0000000000..fd784170c2--- /dev/null+++ b/packages/core/src/theme/syntax/defineSyntaxTheme.diff.test.ts@@ -0,0 +1,91 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it, vi} from 'vitest';+import {+ defineSyntaxTheme,+ REQUIRED_SYNTAX_KEYS,+ syntaxThemeStyle,+ syntaxThemeToCSS,+} from './defineSyntaxTheme';+import {syntaxTokenDefaults} from './tokens';+import {dracula} from './presets';++const base = Object.fromEntries(+ REQUIRED_SYNTAX_KEYS.map(key => [key, '#123456']),+) as Parameters<typeof defineSyntaxTheme>[0]['tokens'];++describe('diff row slots in a syntax theme', () => {+ it('are optional: a theme that sets none keeps the semantic defaults', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const theme = defineSyntaxTheme({name: 't', tokens: base});+ expect(warn).not.toHaveBeenCalled();+ expect(theme.tokens.added).toBe(+ syntaxTokenDefaults['--color-syntax-added'],+ );+ expect(theme.tokens.removed).toBe(+ syntaxTokenDefaults['--color-syntax-removed'],+ );+ // A defined theme that sets no header paint gets none: the header row+ // sits on the theme's own background with punctuation text.+ expect(theme.tokens['diff-header']).toBe('transparent');+ // A theme that sets no marker colour keeps its own line-number colour.+ expect(theme.tokens['added-marker']).toBe(+ 'var(--color-syntax-punctuation)',+ );+ expect(theme.tokens['removed-marker']).toBe(+ 'var(--color-syntax-punctuation)',+ );+ warn.mockRestore();+ });++ it('may be overridden to harmonize with the theme', () => {+ const theme = defineSyntaxTheme({+ name: 't',+ tokens: {...base, added: ['#e6ffed', '#1b3a24'], removed: '#ffeef0'},+ });+ expect(theme.tokens.added).toBe('light-dark(#e6ffed, #1b3a24)');+ expect(theme.tokens.removed).toBe('#ffeef0');+ expect(theme.tokens['diff-header']).toBe('transparent');+ });++ it('skips unset diff slots in the CSS and style output of a hand-built definition', () => {+ const tokens = {...dracula.tokens};+ delete (tokens as Partial<typeof tokens>).added;+ delete (tokens as Partial<typeof tokens>)['added-marker'];+ const theme = {...dracula, tokens};+ expect(syntaxThemeToCSS(theme)).not.toContain('undefined');+ expect(syntaxThemeToCSS(theme)).not.toContain('--color-syntax-added:');+ expect(syntaxThemeStyle(theme)).not.toHaveProperty('--color-syntax-added');+ expect(syntaxThemeStyle(theme)).toHaveProperty('--color-syntax-removed');+ });++ it('leaves the shipped presets valid without them: row paints default, markers follow punctuation', () => {+ expect(dracula.tokens.added).toBe(+ syntaxTokenDefaults['--color-syntax-added'],+ );+ expect(dracula.tokens['added-marker']).toBe(+ 'var(--color-syntax-punctuation)',+ );+ expect(dracula.tokens['removed-marker']).toBe(+ 'var(--color-syntax-punctuation)',+ );+ });++ it('defaults derive from the semantic tokens, never a literal colour', () => {+ expect(syntaxTokenDefaults['--color-syntax-added']).toBe(+ 'color-mix(in srgb, var(--color-success-muted) 25%, transparent)',+ );+ expect(syntaxTokenDefaults['--color-syntax-removed']).toBe(+ 'color-mix(in srgb, var(--color-error-muted) 25%, transparent)',+ );+ expect(syntaxTokenDefaults['--color-syntax-diff-header']).toBe(+ 'var(--color-background-muted)',+ );+ expect(syntaxTokenDefaults['--color-syntax-added-marker']).toBe(+ 'var(--color-text-green)',+ );+ expect(syntaxTokenDefaults['--color-syntax-removed-marker']).toBe(+ 'var(--color-text-red)',+ );+ });+});diff --git a/packages/core/src/theme/syntax/defineSyntaxTheme.ts b/packages/core/src/theme/syntax/defineSyntaxTheme.tsindex c7dc9973e7..54fa834b40 100644--- a/packages/core/src/theme/syntax/defineSyntaxTheme.ts+++ b/packages/core/src/theme/syntax/defineSyntaxTheme.ts@@ -11,7 +11,11 @@* @see https://github.com/facebook/astryx/issues/1148*/-import {syntaxTokenDefaults, type SyntaxTokenName} from './tokens';+import {+ syntaxTokenDefaults,+ DIFF_SYNTAX_TOKEN_NAMES,+ type SyntaxTokenName,+} from './tokens';import {devWarn} from '../../utils/devWarning';// =============================================================================@@ -33,7 +37,12 @@ export type SyntaxThemeTokenKey =| 'attribute'| 'property'| 'punctuation'- | 'background';+ | 'background'+ | DiffSyntaxThemeTokenKey;++/** The diff row slots a syntax theme MAY set; unset ones keep their defaults. */+export type DiffSyntaxThemeTokenKey =+ 'added' | 'removed' | 'diff-header' | 'added-marker' | 'removed-marker';/*** Token value — either a single string or a [light, dark] tuple.@@ -41,14 +50,28 @@ export type SyntaxThemeTokenKey =*/export type SyntaxTokenValue = string | [light: string, dark: string];-/** Token map for defineSyntaxTheme input — values can be strings or tuples. */+/**+ * Token map for defineSyntaxTheme input — values can be strings or tuples.+ * The diff row slots are optional: a theme that sets none keeps the defaults+ * (semantic success/error muted tints and the muted surface).+ */export type SyntaxThemeTokenInput = Record<- SyntaxThemeTokenKey,+ Exclude<SyntaxThemeTokenKey, DiffSyntaxThemeTokenKey>,SyntaxTokenValue->;+> &+ Partial<Record<DiffSyntaxThemeTokenKey, SyntaxTokenValue>>;-/** Resolved token map — all values are CSS strings (tuples resolved to light-dark()). */-export type SyntaxThemeTokenMap = Record<SyntaxThemeTokenKey, string>;+/**+ * Resolved token map — all values are CSS strings (tuples resolved to+ * light-dark()). The diff row slots are optional here as in the input, so a+ * map written before they existed still type-checks; an unset slot renders+ * its default.+ */+export type SyntaxThemeTokenMap = Record<+ Exclude<SyntaxThemeTokenKey, DiffSyntaxThemeTokenKey>,+ string+> &+ Partial<Record<DiffSyntaxThemeTokenKey, string>>;/** Input to defineSyntaxTheme. */export interface SyntaxThemeInput {@@ -81,6 +104,22 @@ export const ALL_SYNTAX_KEYS: SyntaxThemeTokenKey[] = Object.keys(syntaxTokenDefaults,).map(k => k.replace(CSS_PREFIX, '') as SyntaxThemeTokenKey);+const DIFF_KEYS = new Set<SyntaxThemeTokenKey>(+ DIFF_SYNTAX_TOKEN_NAMES.map(+ name => name.replace(CSS_PREFIX, '') as SyntaxThemeTokenKey,+ ),+);++/** The marker slots: unset in a theme, they follow that theme's punctuation. */+const MARKER_KEYS = new Set<SyntaxThemeTokenKey>([+ 'added-marker',+ 'removed-marker',+]);++/** The keys every syntax theme must set: everything but the diff rows. */+export const REQUIRED_SYNTAX_KEYS: SyntaxThemeTokenKey[] =+ ALL_SYNTAX_KEYS.filter(key => !DIFF_KEYS.has(key));+// =============================================================================// Helpers// =============================================================================@@ -138,19 +177,37 @@ export function resolveSyntaxTokenForMode(export function defineSyntaxTheme(input: SyntaxThemeInput,): SyntaxThemeDefinition {- const missing = ALL_SYNTAX_KEYS.filter(key => !(key in input.tokens));+ const missing = REQUIRED_SYNTAX_KEYS.filter(key => !(key in input.tokens));if (missing.length > 0) {devWarn('defineSyntaxTheme',`"${input.name}": missing tokens: ${missing.join(', ')}. ` +- `All 14 syntax tokens are required.`,+ `All ${REQUIRED_SYNTAX_KEYS.length} syntax colour tokens are required; ` ++ `the diff row slots (added, removed, diff-header, added-marker, removed-marker) are optional.`,);}- // Resolve tuples to light-dark() CSS strings+ // Resolve tuples to light-dark() CSS strings. An unset diff row paint keeps+ // its default so every existing theme renders a readable diff unchanged; an+ // unset marker slot takes this theme's own line-number colour (its+ // punctuation token) rather than the page theme's green and red, and an+ // unset header paint is none at all (the header row sits on this theme's+ // own background with punctuation text), so number, glyph, and header+ // text stay legible on this theme's background in every page mode — the+ // glyph's shape carries the meaning where the colour does not.const resolved: Partial<SyntaxThemeTokenMap> = {};for (const key of ALL_SYNTAX_KEYS) {- resolved[key] = resolveTokenValue(input.tokens[key]);+ const value = (+ input.tokens as Partial<Record<SyntaxThemeTokenKey, SyntaxTokenValue>>+ )[key];+ resolved[key] =+ value !== undefined+ ? resolveTokenValue(value)+ : MARKER_KEYS.has(key)+ ? 'var(--color-syntax-punctuation)'+ : key === 'diff-header'+ ? 'transparent'+ : syntaxTokenDefaults[toCSSProperty(key)];}return {@@ -170,14 +227,17 @@ export function syntaxThemeStyle(): Record<string, string> {const vars: Record<string, string> = {};for (const key of ALL_SYNTAX_KEYS) {- vars[toCSSProperty(key)] = theme.tokens[key];+ // An unset diff slot is left to its default rather than written empty.+ const value = theme.tokens[key];+ if (value !== undefined) vars[toCSSProperty(key)] = value;}return vars;}/** Convert a syntax theme to CSS declarations (no selector wrapper). */export function syntaxThemeToCSS(theme: SyntaxThemeDefinition): string {- return ALL_SYNTAX_KEYS.map(- key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';',- ).join('\n ');+ // An unset diff slot is left to its default rather than written `undefined`.+ return ALL_SYNTAX_KEYS.filter(key => theme.tokens[key] !== undefined)+ .map(key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';')+ .join('\n ');}diff --git a/packages/core/src/theme/syntax/index.ts b/packages/core/src/theme/syntax/index.tsindex 5407065d3e..dbe6b84f0c 100644--- a/packages/core/src/theme/syntax/index.ts+++ b/packages/core/src/theme/syntax/index.ts@@ -14,7 +14,11 @@export {syntaxTokenDefaults} from './tokens';export type {SyntaxTokenName} from './tokens';-export {defineSyntaxTheme, syntaxThemeStyle, syntaxThemeToCSS} from './defineSyntaxTheme';+export {+ defineSyntaxTheme,+ syntaxThemeStyle,+ syntaxThemeToCSS,+} from './defineSyntaxTheme';export type {SyntaxThemeDefinition,SyntaxThemeInput,diff --git a/packages/core/src/theme/syntax/tokens.ts b/packages/core/src/theme/syntax/tokens.tsindex a457a56f9b..aa55a84fad 100644--- a/packages/core/src/theme/syntax/tokens.ts+++ b/packages/core/src/theme/syntax/tokens.ts@@ -13,8 +13,11 @@* colors automatically adapt to any theme's color system. Themes can also* set an explicit syntax theme via defineTheme({ syntax: dracula }).*- * 14-token architecture validated against 11 community code themes.- * All themes map cleanly to these 14 slots.+ * 14 token colours and the code background, validated against 11 community+ * code themes — all of them map cleanly to those slots — plus five diff row+ * slots (added, removed, header paints; added and removed markers) that default+ * to semantic tokens, so a syntax theme that does not set them keeps a+ * readable diff.** @see https://github.com/facebook/astryx/issues/1148*/@@ -51,6 +54,33 @@ export const syntaxTokenDefaults = {'--color-syntax-punctuation': 'var(--color-text-secondary)',// background -> muted surface'--color-syntax-background': 'var(--color-background-muted)',+ // Diff rows (CodeBlock isDiff): whole-row tints behind unchanged syntax+ // colours. Added/removed derive from the semantic success/error muted+ // tokens at 25% strength: at full strength the secondary-grey syntax+ // tokens (operator, punctuation, comment) fall under 4.5:1 on the tints+ // in light; at 25% every default token clears it on both schemes with+ // margin while the tint still reads against the plain row. Header rows+ // (@@, and ---/+++ before the first hunk) sit on the muted surface.+ '--color-syntax-added':+ 'color-mix(in srgb, var(--color-success-muted) 25%, transparent)',+ '--color-syntax-removed':+ 'color-mix(in srgb, var(--color-error-muted) 25%, transparent)',+ '--color-syntax-diff-header': 'var(--color-background-muted)',+ // The margin of a changed row — its line number and +/- glyph — in the+ // default theme's tinted-text tokens, made for tinted surfaces; a defined+ // syntax theme that leaves them unset follows its own punctuation colour+ // (see defineSyntaxTheme). Code text keeps the syntax theme's colours.+ '--color-syntax-added-marker': 'var(--color-text-green)',+ '--color-syntax-removed-marker': 'var(--color-text-red)',} as const;export type SyntaxTokenName = keyof typeof syntaxTokenDefaults;++/** The five diff row slots: optional in a syntax theme, defaulted when unset. */+export const DIFF_SYNTAX_TOKEN_NAMES = [+ '--color-syntax-added',+ '--color-syntax-removed',+ '--color-syntax-diff-header',+ '--color-syntax-added-marker',+ '--color-syntax-removed-marker',+] as const satisfies ReadonlyArray<SyntaxTokenName>;diff --git a/packages/core/src/theme/syntax/useSyntaxTheme.diff.test.tsx b/packages/core/src/theme/syntax/useSyntaxTheme.diff.test.tsxnew file mode 100644index 0000000000..c9364239ac--- /dev/null+++ b/packages/core/src/theme/syntax/useSyntaxTheme.diff.test.tsx@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file useSyntaxTheme.diff.test.tsx+ * @input A SyntaxTheme provider with a preset that sets no diff slots+ * @output The hook hands a canvas consumer paintable colours for every slot+ * @position Diff slot resolution for the imperative (canvas) path+ */++import {render} from '@testing-library/react';+import {describe, expect, it} from 'vitest';+import {SyntaxTheme, useSyntaxTheme} from './SyntaxTheme';+import {dracula} from './presets';+import {parseColor} from '../../utils/color';++function Probe({onTokens}: {onTokens: (t: Record<string, string>) => void}) {+ const syntax = useSyntaxTheme();+ if (syntax) onTokens(syntax.tokens);+ return null;+}++describe('useSyntaxTheme diff slots', () => {+ it("resolves unset marker slots to the theme's own punctuation colour", () => {+ let tokens: Record<string, string> = {};+ render(+ <SyntaxTheme theme={dracula}>+ <Probe onTokens={t => (tokens = t)} />+ </SyntaxTheme>,+ );+ expect(tokens.punctuation).toMatch(/^#|^rgb/);+ expect(tokens['added-marker']).toBe(tokens.punctuation);+ expect(tokens['removed-marker']).toBe(tokens.punctuation);+ // The row paints derive from the page theme's resolved muted tokens at+ // the default strength, as rgba() a canvas can paint.+ expect(tokens.added).toMatch(/^rgba\(\d+, \d+, \d+, 0\.\d+\)$/);+ expect(tokens.removed).toMatch(/^rgba\(\d+, \d+, \d+, 0\.\d+\)$/);+ expect(parseColor(tokens.added)?.a).toBeCloseTo(0.2 * 0.25, 3);+ expect(tokens['diff-header']).toBe('transparent');+ });+});