An open source design system that's fully customizable and agent ready
TypeScript
fix(Markdown): a semantic fence claims its fence before components.code (#7284)
Cindy Zhangaf37350ac9af
diff --git a/.changeset/markdown-fence-claims-before-code.md b/.changeset/markdown-fence-claims-before-code.mdnew file mode 100644index 0000000000..a7475f2e49--- /dev/null+++ b/.changeset/markdown-fence-claims-before-code.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] `Markdown` renders a fence that a `createMarkdownFenceTransform` plugin claims through that plugin even when `components.code` is supplied. A host that drew its own code blocks lost every semantic fence, so a diagram or chart fence showed as code. `components.code` now renders every fence no plugin claims, and stays the fallback when a claimed fence's renderer declines, throws, or suspends. Hosts with only one of the two render as before.++@cixzhangdiff --git a/apps/storybook/stories/Markdown.stories.tsx b/apps/storybook/stories/Markdown.stories.tsxindex e008707058..7f61eb4a0e 100644--- a/apps/storybook/stories/Markdown.stories.tsx+++ b/apps/storybook/stories/Markdown.stories.tsx@@ -982,6 +982,39 @@ export const SemanticFence: Story = {),};+function StoryHostCode({code, language}: {code: string; language?: string}) {+ return (+ <figure+ aria-label={`Host code renderer: ${language ?? 'plaintext'}`}+ style={{+ margin: '12px 0',+ padding: 12,+ border: '1px dashed currentColor',+ borderRadius: 8,+ }}>+ <figcaption style={{fontSize: 12, marginBottom: 8}}>+ Host code renderer · {language ?? 'plaintext'}+ </figcaption>+ <pre style={{margin: 0}}>{code}</pre>+ </figure>+ );+}++export const SemanticFenceWithCodeRenderer: Story = {+ name: 'Semantic Fence With Code Renderer',+ render: () => (+ <div style={{maxWidth: 680}}>+ <Markdown+ plugins={[markdownSemanticFenceDemoPlugin]}+ components={{code: StoryHostCode}}>+ {+ '# Build flow\n\nThe fence plugin claims `diagram` fences, so they render through the plugin even though the host supplies its own code renderer:\n\n```diagram Checkout to deploy\nCheckout --> Test --> Deploy\n```\n\nEvery fence no plugin claims renders through the host code renderer:\n\n```ts\nconst stage = "deploy";\n```'+ }+ </Markdown>+ </div>+ ),+};+const decorationSource ='# Release notes\n\nThe parser now streams incrementally.\n\nEverything else is unchanged.';diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjsindex ff172865c4..6d76b35579 100644--- a/packages/core/src/Markdown/Markdown.doc.mjs+++ b/packages/core/src/Markdown/Markdown.doc.mjs@@ -275,7 +275,7 @@ export const docs = {{guidance: true,description:- 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',+ 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. A claimed fence renders through that plugin even when components.code is supplied; components.code renders every unclaimed fence and is the fallback when the plugin renderer declines, throws, or suspends, and without it the accessible, copyable CodeBlock is that fallback.',},{guidance: true,@@ -795,7 +795,7 @@ export const docsZh = {{guidance: true,description:- 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',+ 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. A claimed fence renders through that plugin even when components.code is supplied; components.code renders every unclaimed fence and is the fallback when the plugin renderer declines, throws, or suspends, and without it the accessible, copyable CodeBlock is that fallback.',},{guidance: true,@@ -897,7 +897,7 @@ export const docsDense = {{guidance: true,description:- 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',+ 'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. A claimed fence renders through that plugin even when components.code is supplied; components.code renders every unclaimed fence and is the fallback when the plugin renderer declines, throws, or suspends, and without it the accessible, copyable CodeBlock is that fallback.',},{guidance: true,diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsxindex 6f66b41384..927c2b97cf 100644--- a/packages/core/src/Markdown/Markdown.tsx+++ b/packages/core/src/Markdown/Markdown.tsx@@ -147,6 +147,10 @@ export interface MarkdownInlinePlugin {export type MarkdownSource = CitationSource;export interface MarkdownComponents {+ /**+ * Renders every fenced code block that no semantic-fence plugin claims, and+ * a claimed fence whose plugin renderer declines, throws, or suspends.+ */code?: React.ComponentType<{code: string; language?: string}>;inlineCode?: React.ComponentType<{children: string}>;/**@@ -1408,13 +1412,14 @@ function renderBlock(// Track codeblock content in cursor for accurate character countingcursor.offset += node.value.length;const language = getMarkdownAstLegacyCodeLanguage(node) ?? 'plaintext';+ // 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+ // when the claiming renderer is absent, declines, throws, or suspends.const CodeBlockComp = components?.code;- if (CodeBlockComp) {- return (- <CodeBlockComp key={index} code={node.value} language={language} />- );- }- const fallback = (+ const fallback = CodeBlockComp ? (+ <CodeBlockComp key={index} code={node.value} language={language} />+ ) : (<divkey={index}{...mergeProps(diff --git a/packages/core/src/Markdown/plugins/semanticFence.test.tsx b/packages/core/src/Markdown/plugins/semanticFence.test.tsxindex 607a4ac16c..acfb3bfb5f 100644--- a/packages/core/src/Markdown/plugins/semanticFence.test.tsx+++ b/packages/core/src/Markdown/plugins/semanticFence.test.tsx@@ -270,12 +270,121 @@ describe('createMarkdownFenceTransform', () => {});});- it('lets components.code win without invoking the proposal renderer', () => {- const renderFence = vi.fn(() => <div>Semantic</div>);+ it('renders a claimed fence through its plugin and an unclaimed fence through components.code', () => {+ const renderFence = vi.fn(() => <div data-testid="semantic">Semantic</div>);const plugin = createFencePlugin('override-fences', renderFence);+ const codeOverride = vi.fn(+ ({code, language}: {code: string; language?: string}) => (+ <div data-testid="code-override">+ {language}: {code}+ </div>+ ),+ );++ render(+ <Markdown plugins={[plugin]} components={{code: codeOverride}}>+ {'```diagram\nstart --> finish\n```\n\n```ts\nconst x = 1;\n```'}+ </Markdown>,+ );++ expect(screen.getByTestId('semantic')).toHaveTextContent('Semantic');+ expect(renderFence).toHaveBeenCalledOnce();+ expect(screen.getAllByTestId('code-override')).toHaveLength(1);+ expect(screen.getByTestId('code-override')).toHaveTextContent(+ 'ts: const x = 1;',+ );+ expect(codeOverride.mock.calls.map(([props]) => props.language)).toEqual([+ 'ts',+ ]);+ });++ it('falls back to components.code when a claimed fence is declined or its renderer returns nothing', () => {+ const CodeOverride = ({code}: {code: string; language?: string}) => (+ <div data-testid="code-override">Override: {code}</div>+ );+ const declining = createFencePlugin(+ 'declining-override-fences',+ () => <div>Semantic</div>,+ () => null,+ );+ const empty = createFencePlugin('empty-override-fences', () => null);+ const source = '```diagram\nstart --> finish\n```';++ const {rerender} = render(+ <Markdown plugins={[declining]} components={{code: CodeOverride}}>+ {source}+ </Markdown>,+ );+ expect(screen.getByTestId('code-override')).toHaveTextContent(+ 'Override: start --> finish',+ );++ rerender(+ <Markdown plugins={[empty]} components={{code: CodeOverride}}>+ {source}+ </Markdown>,+ );+ expect(screen.getByTestId('code-override')).toHaveTextContent(+ 'Override: start --> finish',+ );+ expect(document.querySelector('pre')).toBeNull();+ });++ it('falls back to components.code when a claimed fence renderer throws', () => {+ const CodeOverride = ({code}: {code: string; language?: string}) => (+ <div data-testid="code-override">Override: {code}</div>+ );+ const throwing = createFencePlugin('throwing-override-fences', () => {+ throw new Error('broken semantic fence');+ });+ const descendant = createFencePlugin('descendant-override-fences', () => (+ <ThrowingFenceChild />+ ));+ const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const error = vi.spyOn(console, 'error').mockImplementation(() => {});+ const source = '```diagram\nstart --> finish\n```';++ const {rerender} = render(+ <Markdown plugins={[throwing]} components={{code: CodeOverride}}>+ {source}+ </Markdown>,+ );+ expect(screen.getByTestId('code-override')).toHaveTextContent(+ 'Override: start --> finish',+ );++ rerender(+ <Markdown plugins={[descendant]} components={{code: CodeOverride}}>+ {source}+ </Markdown>,+ );+ expect(screen.getByTestId('code-override')).toHaveTextContent(+ 'Override: start --> finish',+ );+ expect(+ renderToString(+ <Markdown plugins={[descendant]} components={{code: CodeOverride}}>+ {source}+ </Markdown>,+ ),+ ).toContain('Override: <!-- -->start --> finish');++ warning.mockRestore();+ error.mockRestore();+ });++ it('shows components.code while a claimed fence renderer suspends', () => {const CodeOverride = ({code}: {code: string; language?: string}) => (<div data-testid="code-override">Override: {code}</div>);+ const pending = new Promise<never>(() => {});+ function Suspending(): never {+ // eslint-disable-next-line @typescript-eslint/only-throw-error+ throw pending;+ }+ const plugin = createFencePlugin('suspending-override-fences', () => (+ <Suspending />+ ));render(<Markdown plugins={[plugin]} components={{code: CodeOverride}}>@@ -286,7 +395,6 @@ describe('createMarkdownFenceTransform', () => {expect(screen.getByTestId('code-override')).toHaveTextContent('Override: start --> finish',);- expect(renderFence).not.toHaveBeenCalled();});it('uses CodeBlock for undeclared or declined fences', () => {