Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/apps/storybook/stories/Markdown.stories.tsx b/apps/storybook/stories/Markdown.stories.tsx
index 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.mjs
index 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.tsx
index 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 counting
cursor.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} />
+ ) : (
<div
key={index}
{...mergeProps(
diff --git a/packages/core/src/Markdown/plugins/semanticFence.test.tsx b/packages/core/src/Markdown/plugins/semanticFence.test.tsx
index 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 --&gt; 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', () => {