Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Markdown): add inline citation support (#1179)

Cindy Zhange082d70bb5ae
diff --git a/apps/storybook/stories/MarkdownCitations.stories.tsx b/apps/storybook/stories/MarkdownCitations.stories.tsx
new file mode 100644
index 0000000000..14980e4d31
--- /dev/null
+++ b/apps/storybook/stories/MarkdownCitations.stories.tsx
@@ -0,0 +1,183 @@
+import {useState, useEffect, useCallback} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSMarkdown} from '@xds/core/Markdown';
+import type {XDSMarkdownSource} from '@xds/core/Markdown';
+import {XDSButton} from '@xds/core/Button';
+
+const meta: Meta<typeof XDSMarkdown> = {
+ title: 'Components/XDSMarkdown/Citations',
+ component: XDSMarkdown,
+ tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSMarkdown>;
+
+// ---------------------------------------------------------------------------
+// Shared sources
+// ---------------------------------------------------------------------------
+
+const SEARCH_SOURCES: Record<string, XDSMarkdownSource> = {
+ abc1: {
+ title: 'Tokyo - Wikipedia',
+ url: 'https://en.wikipedia.org/wiki/Tokyo',
+ icon: 'https://en.wikipedia.org/favicon.ico',
+ },
+ def2: {
+ title: 'Japan Statistics Bureau - Population',
+ url: 'https://www.stat.go.jp/english/',
+ },
+ ghi3: {
+ title: 'World Population Review',
+ url: 'https://worldpopulationreview.com/world-cities/tokyo-population',
+ },
+ jkl4: {
+ title: 'Reuters — Tokyo GDP',
+ url: 'https://www.reuters.com/markets/',
+ icon: 'https://www.reuters.com/favicon.ico',
+ },
+ mno5: {
+ title: 'UN Urbanization Prospects',
+ url: 'https://population.un.org/wup/',
+ },
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+const BRACKET_MD = [
+ '## Tokyo Overview',
+ '',
+ 'Tokyo is the capital of Japan with a population of over 14 million[abc1].',
+ "It's the most populous metropolitan area in the world[def2][ghi3].",
+ '',
+ '### Economy',
+ '',
+ "Tokyo's GDP exceeds $1.9 trillion, making it the largest city economy globally[jkl4].",
+ 'The metropolitan area is expected to remain the most populous urban agglomeration through 2035[mno5].',
+ '',
+ '### Key Facts',
+ '',
+ '- Population: 13.96 million (city proper)[abc1]',
+ '- Metro area: 37.4 million[def2]',
+ '- GDP: $1.93 trillion[jkl4]',
+ '',
+ 'For more details, see the [full Wikipedia article](https://en.wikipedia.org/wiki/Tokyo).',
+].join('\n');
+
+export const BracketNotation: Story = {
+ name: 'Bracket [id]',
+ args: {
+ children: BRACKET_MD,
+ sources: SEARCH_SOURCES,
+ density: 'compact',
+ headingLevelStart: 3,
+ },
+};
+
+const FULLWIDTH_MD = [
+ '## Search Results',
+ '',
+ 'Tokyo has a population of over 14 million\u3010abc1\u3011.',
+ 'The greater Tokyo area houses 37 million people\u3010def2\u3011\u3010ghi3\u3011.',
+ '',
+ "The city's economy is the largest in the world\u3010jkl4\u3011,",
+ 'and urbanization trends suggest continued growth\u3010mno5\u3011.',
+].join('\n');
+
+export const FullwidthNotation: Story = {
+ name: 'Fullwidth \u3010id\u3011',
+ args: {
+ children: FULLWIDTH_MD,
+ sources: SEARCH_SOURCES,
+ density: 'compact',
+ headingLevelStart: 3,
+ },
+};
+
+export const NoCitations: Story = {
+ name: 'No Sources (passthrough)',
+ args: {
+ children:
+ 'Text with [abc1] bracket markers but no sources prop.\n\nThey render as plain text.',
+ },
+};
+
+const STREAMING_CITATION_MD = [
+ '## AI Research Summary',
+ '',
+ 'Large language models have shown remarkable capabilities in recent years[abc1].',
+ 'Scaling laws suggest continued improvement with more compute[def2].',
+ '',
+ '### Key Findings',
+ '',
+ '- Models above 100B parameters show emergent abilities[ghi3]',
+ '- Fine-tuning remains critical for task-specific performance[jkl4]',
+ '- Safety alignment is an active area of research[mno5]',
+ '',
+ 'These results have broad implications for the field.',
+].join('\n');
+
+export const StreamingWithCitations: Story = {
+ name: 'Streaming',
+ render: () => {
+ const text = STREAMING_CITATION_MD;
+ const [charIndex, setCharIndex] = useState(0);
+ const [isStreaming, setIsStreaming] = useState(true);
+ const [key, setKey] = useState(0);
+
+ useEffect(() => {
+ if (!isStreaming) return;
+ if (charIndex >= text.length) {
+ setIsStreaming(false);
+ return;
+ }
+ const chunkSize = Math.floor(Math.random() * 8) + 2;
+ const delay = 30 + Math.random() * 60;
+ const timer = setTimeout(() => {
+ setCharIndex(prev => Math.min(prev + chunkSize, text.length));
+ }, delay);
+ return () => clearTimeout(timer);
+ }, [charIndex, isStreaming, text]);
+
+ const replay = useCallback(() => {
+ setCharIndex(0);
+ setIsStreaming(true);
+ setKey(k => k + 1);
+ }, []);
+
+ return (
+ <div>
+ <div
+ style={{
+ marginBlockEnd: 12,
+ display: 'flex',
+ gap: 8,
+ alignItems: 'center',
+ }}>
+ <XDSButton
+ label="Replay"
+ variant="secondary"
+ size="sm"
+ onClick={replay}
+ isDisabled={isStreaming}
+ />
+ <span style={{fontSize: 12, color: '#666'}}>
+ {isStreaming
+ ? `Streaming... ${charIndex}/${text.length}`
+ : 'Complete'}
+ </span>
+ </div>
+ <XDSMarkdown
+ key={key}
+ isStreaming={isStreaming}
+ density="compact"
+ headingLevelStart={3}
+ sources={SEARCH_SOURCES}>
+ {text.slice(0, charIndex)}
+ </XDSMarkdown>
+ </div>
+ );
+ },
+};
diff --git a/packages/core/src/Markdown/XDSMarkdown.tsx b/packages/core/src/Markdown/XDSMarkdown.tsx
index 706b53f79c..6982160b95 100644
--- a/packages/core/src/Markdown/XDSMarkdown.tsx
+++ b/packages/core/src/Markdown/XDSMarkdown.tsx
@@ -41,6 +41,20 @@ import type {BlockNode, InlineNode, IncrementalState} from './parser';
// Props
// ---------------------------------------------------------------------------
+/**
+ * A citation source referenced inline in the markdown via `[id]` or `【id】`.
+ * When `sources` is provided, bracket content matching a source key is rendered
+ * as a compact superscript citation pill instead of plain text.
+ */
+export interface XDSMarkdownSource {
+ /** Human-readable title for the source. */
+ title?: string;
+ /** URL to navigate to when the citation is clicked. */
+ url?: string;
+ /** Optional favicon or icon URL to display in the citation pill. */
+ icon?: string;
+}
+
export interface XDSMarkdownProps {
ref?: React.Ref<HTMLDivElement>;
children: string;
@@ -58,6 +72,18 @@ export interface XDSMarkdownProps {
href: string,
event: React.MouseEvent<HTMLAnchorElement>,
) => void | false;
+ /**
+ * Citation sources keyed by ID. When provided, `[id]` and `【id】` markers
+ * in the markdown that match a key are rendered as citation chips.
+ */
+ sources?: Record<string, XDSMarkdownSource>;
+ /**
+ * How citations are displayed inline.
+ * - `'label'` (default) — chip with source title text, icon, and border
+ * - `'number'` — compact numbered badge (1, 2, 3…)
+ * @default 'label'
+ */
+ citationStyle?: 'label' | 'number';
xstyle?: StyleXStyles;
className?: string;
style?: React.CSSProperties;
@@ -251,6 +277,92 @@ const styles = stylex.create({
':hover': 'underline',
},
},
+ // Citation chip — inline capsule matching XDSTextCitation treatment
+ citation: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ verticalAlign: 'baseline',
+ height: spacingVars['--spacing-5'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: typeScaleVars['--text-supporting-weight'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ color: colorVars['--color-text-secondary'],
+ borderRadius: radiusVars['--radius-element'],
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ paddingInline: spacingVars['--spacing-2'],
+ marginInlineStart: spacingVars['--spacing-0-5'],
+ textDecoration: 'none',
+ cursor: 'pointer',
+ transitionProperty: 'background-color, border-color, color',
+ transitionDuration: durationVars['--duration-fast-max'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ maxWidth: '15em',
+ overflow: 'hidden',
+ },
+ citationWithIcon: {
+ paddingInlineStart: spacingVars['--spacing-0-5'],
+ },
+ citationLabel: {
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ minWidth: 0,
+ },
+ // Number mode — compact superscript badge
+ citationNumber: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ verticalAlign: 'super',
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ color: colorVars['--color-text-accent'],
+ backgroundColor: colorVars['--color-accent-muted'],
+ borderRadius: radiusVars['--radius-full'],
+ minWidth: spacingVars['--spacing-5'],
+ height: spacingVars['--spacing-5'],
+ paddingInline: spacingVars['--spacing-1'],
+ textDecoration: 'none',
+ cursor: 'pointer',
+ transitionProperty: 'background-color',
+ transitionDuration: durationVars['--duration-fast-max'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ citationNumberHover: {
+ backgroundColor: {
+ ':hover': colorVars['--color-overlay-hover'],
+ },
+ },
+ citationHover: {
+ backgroundColor: {
+ ':hover': colorVars['--color-overlay-hover'],
+ },
+ color: {
+ ':hover': colorVars['--color-text-primary'],
+ },
+ },
+ citationIconWrap: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: spacingVars['--spacing-4'],
+ height: spacingVars['--spacing-4'],
+ borderRadius: radiusVars['--radius-full'],
+ backgroundColor: colorVars['--color-background-surface'],
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ overflow: 'hidden',
+ flexShrink: 0,
+ },
+ citationIcon: {
+ width: spacingVars['--spacing-3'],
+ height: spacingVars['--spacing-3'],
+ },
});
// ---------------------------------------------------------------------------
@@ -309,6 +421,9 @@ function countInlineTextLength(nodes: InlineNode[]): number {
case 'break':
len += 1;
break;
+ case 'citation':
+ len += 1;
+ break;
}
}
return len;
@@ -414,11 +529,32 @@ function wrapTextWithFade(
);
}
+/**
+ * Context for citation rendering, threaded through the inline/block render tree.
+ * Tracks which sources have been cited and assigns sequential display numbers.
+ */
+interface CitationContext {
+ sources: Record<string, XDSMarkdownSource>;
+ numberMap: Map<string, number>;
+ nextNumber: number;
+ style: 'label' | 'number';
+}
+
+function getCitationNumber(ctx: CitationContext, sourceId: string): number {
+ let num = ctx.numberMap.get(sourceId);
+ if (num == null) {
+ num = ctx.nextNumber++;
+ ctx.numberMap.set(sourceId, num);
+ }
+ return num;
+}
+
function renderInline(
node: InlineNode,
index: number,
onLinkClick: XDSMarkdownProps['onLinkClick'] | undefined,
cursor: StreamingCursor,
+ citationCtx: CitationContext | null,
): React.ReactNode {
switch (node.type) {
case 'text':
@@ -426,19 +562,25 @@ function renderInline(
case 'bold':
return (
<strong key={index} {...stylex.props(styles.bold)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
+ {node.children.map((c, i) =>
+ renderInline(c, i, onLinkClick, cursor, citationCtx),
+ )}
</strong>
);
case 'italic':
return (
<em key={index}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
+ {node.children.map((c, i) =>
+ renderInline(c, i, onLinkClick, cursor, citationCtx),
+ )}
</em>
);
case 'strikethrough':
return (
<del key={index} {...stylex.props(styles.strikethrough)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
+ {node.children.map((c, i) =>
+ renderInline(c, i, onLinkClick, cursor, citationCtx),
+ )}
</del>
);
case 'code': {
@@ -463,7 +605,7 @@ function renderInline(
return (
<span key={index}>
{node.children.map((c, i) =>
- renderInline(c, i, onLinkClick, cursor),
+ renderInline(c, i, onLinkClick, cursor, citationCtx),
)}
</span>
);
@@ -486,7 +628,9 @@ function renderInline(
? {target: '_blank', rel: 'noopener noreferrer'}
: {})}
{...stylex.props(styles.link)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
+ {node.children.map((c, i) =>
+ renderInline(c, i, onLinkClick, cursor, citationCtx),
+ )}
</a>
);
}
@@ -505,6 +649,77 @@ function renderInline(
case 'break':
cursor.offset += 1;
return <br key={index} />;
+ case 'citation': {
+ cursor.offset += 1;
+ if (!citationCtx) {
+ // No sources provided — render as plain text
+ return <span key={index}>[{node.sourceId}]</span>;
+ }
+ const num = getCitationNumber(citationCtx, node.sourceId);
+ const source = citationCtx.sources[node.sourceId];
+ const title = source?.title ?? node.sourceId;
+ const href = source?.url;
+ const icon = source?.icon;
+ const Tag = href ? 'a' : 'span';
+ const linkProps = href
+ ? {
+ href,
+ target: '_blank' as const,
+ rel: 'noopener noreferrer' as const,
+ title,
+ }
+ : {title};
+
+ const isNew = cursor.active && cursor.offset >= cursor.boundary;
+ const isNumberMode = citationCtx.style === 'number';
+
+ const chip = isNumberMode ? (
+ <Tag
+ key={index}
+ role="doc-noteref"
+ aria-label={`Citation ${num}: ${title}`}
+ {...linkProps}
+ {...stylex.props(
+ styles.citationNumber,
+ href != null && styles.citationNumberHover,
+ )}>
+ {num}
+ </Tag>
+ ) : (
+ <Tag
+ key={index}
+ role="doc-noteref"
+ aria-label={`Citation ${num}: ${title}`}
+ {...linkProps}
+ {...stylex.props(
+ styles.citation,
+ icon != null && styles.citationWithIcon,
+ href != null && styles.citationHover,
+ )}>
+ {icon && (
+ <span {...stylex.props(styles.citationIconWrap)}>
+ <img
+ src={icon}
+ alt=""
+ aria-hidden="true"
+ {...stylex.props(styles.citationIcon)}
+ />
+ </span>
+ )}
+ <span {...stylex.props(styles.citationLabel)}>{title}</span>
+ </Tag>
+ );
+
+ return isNew ? (
+ <span
+ key={`fade-cite-${index}`}
+ {...stylex.props(streamingStyles.fadeIn)}>
+ {chip}
+ </span>
+ ) : (
+ chip
+ );
+ }
}
}
@@ -561,6 +776,7 @@ function renderBlock(
headingLevelStart: 1 | 2 | 3 | 4 | 5 | 6,
onLinkClick: XDSMarkdownProps['onLinkClick'] | undefined,
cursor: StreamingCursor,
+ citationCtx: CitationContext | null,
): React.ReactNode {
const spacing = getElementSpacing(node, density);
const isFirst = index === 0;
@@ -586,7 +802,9 @@ function renderBlock(
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
+ {node.children.map((c, i) =>
+ renderInline(c, i, onLinkClick, cursor, citationCtx),
+ )}
</Tag>
);
}
@@ -599,7 +817,9 @@ function renderBlock(
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
)}>
- {node.children.map((c, i) => renderInline(c, i, onLinkClick, cursor))}
+ {node.children.map((c, i) =>
+ renderInline(c, i, onLinkClick, cursor, citationCtx),
+ )}
</p>
);
case 'codeblock': {
@@ -636,6 +856,7 @@ function renderBlock(
headingLevelStart,
onLinkClick,
cursor,
+ citationCtx,
),
)}
</blockquote>
@@ -678,7 +899,7 @@ function renderBlock(
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
- renderInline(c, j, onLinkClick, cursor),
+ renderInline(c, j, onLinkClick, cursor, citationCtx),
)}
</>
) : (
@@ -692,6 +913,7 @@ function renderBlock(
headingLevelStart,
onLinkClick,
cursor,
+ citationCtx,
),
)}
</>
@@ -747,7 +969,7 @@ function renderBlock(
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
- renderInline(c, j, onLinkClick, cursor),
+ renderInline(c, j, onLinkClick, cursor, citationCtx),
)}
</>
) : (
@@ -761,6 +983,7 @@ function renderBlock(
headingLevelStart,
onLinkClick,
cursor,
+ citationCtx,
),
)}
</>
@@ -809,7 +1032,7 @@ function renderBlock(
alignStyle(node.alignments[i]),
)}>
{h.children.map((c, j) =>
- renderInline(c, j, onLinkClick, cursor),
+ renderInline(c, j, onLinkClick, cursor, citationCtx),
)}
</th>
))}
@@ -827,7 +1050,7 @@ function renderBlock(
alignStyle(node.alignments[j]),
)}>
{cell.children.map((c, k) =>
- renderInline(c, k, onLinkClick, cursor),
+ renderInline(c, k, onLinkClick, cursor, citationCtx),
)}
</td>
));
@@ -908,11 +1131,19 @@ export function XDSMarkdown({
headingLevelStart = 1,
isStreaming = false,
onLinkClick,
+ sources,
+ citationStyle = 'label',
xstyle,
className,
style,
'data-testid': testId,
}: XDSMarkdownProps): React.ReactElement {
+ // Derive the set of source IDs for the parser (stable across renders when sources don't change)
+ const sourceIds = useMemo(
+ () => (sources ? new Set(Object.keys(sources)) : undefined),
+ [sources],
+ );
+
// Smooth bursty streamed chunks into a steady character-by-character reveal.
// When not streaming, the hook returns children unchanged (no-op).
const smoothedText = useXDSStreamingText(children, isStreaming);
@@ -930,10 +1161,14 @@ export function XDSMarkdown({
return [];
}
const input = trimStreamingArtifacts(smoothedText);
- return parseMarkdownIncremental(input, incrementalState.current);
+ return parseMarkdownIncremental(
+ input,
+ incrementalState.current,
+ sourceIds,
+ );
}
- return parseMarkdown(children);
- }, [smoothedText, children, isStreaming]);
+ return parseMarkdown(children, sourceIds);
+ }, [smoothedText, children, isStreaming, sourceIds]);
// Build the streaming cursor for this render pass.
// The boundary is where "old" text ends and "new" text begins.
@@ -943,6 +1178,12 @@ export function XDSMarkdown({
active: isStreaming,
};
+ // Build citation context — numbers are assigned in encounter order during rendering.
+ // This is recreated each render so numbering stays consistent with the AST.
+ const citationCtx: CitationContext | null = sources
+ ? {sources, numberMap: new Map(), nextNumber: 1, style: citationStyle}
+ : null;
+
const rendered = (
<div
role="document"
@@ -963,6 +1204,7 @@ export function XDSMarkdown({
headingLevelStart,
onLinkClick,
cursor,
+ citationCtx,
),
)}
</div>
diff --git a/packages/core/src/Markdown/index.ts b/packages/core/src/Markdown/index.ts
index e9baab6797..0c7c57637f 100644
--- a/packages/core/src/Markdown/index.ts
+++ b/packages/core/src/Markdown/index.ts
@@ -7,7 +7,7 @@
*/
export {XDSMarkdown} from './XDSMarkdown';
-export type {XDSMarkdownProps} from './XDSMarkdown';
+export type {XDSMarkdownProps, XDSMarkdownSource} from './XDSMarkdown';
export {
parseMarkdown,
diff --git a/packages/core/src/Markdown/parser.test.ts b/packages/core/src/Markdown/parser.test.ts
index 539c377b8a..279d06a3c2 100644
--- a/packages/core/src/Markdown/parser.test.ts
+++ b/packages/core/src/Markdown/parser.test.ts
@@ -11,7 +11,10 @@ describe('parseInline', () => {
const result = parseInline('**bold text**');
expect(result[0].type).toBe('bold');
if (result[0].type === 'bold') {
- expect(result[0].children[0]).toEqual({type: 'text', content: 'bold text'});
+ expect(result[0].children[0]).toEqual({
+ type: 'text',
+ content: 'bold text',
+ });
}
});
@@ -19,7 +22,10 @@ describe('parseInline', () => {
const result = parseInline('*italic text*');
expect(result[0].type).toBe('italic');
if (result[0].type === 'italic') {
- expect(result[0].children[0]).toEqual({type: 'text', content: 'italic text'});
+ expect(result[0].children[0]).toEqual({
+ type: 'text',
+ content: 'italic text',
+ });
}
});
@@ -51,7 +57,9 @@ describe('parseInline', () => {
});
it('parses mixed inline formatting', () => {
- const result = parseInline('Hello **bold** and *italic* with `code` and [link](url)');
+ const result = parseInline(
+ 'Hello **bold** and *italic* with `code` and [link](url)',
+ );
expect(result.length).toBeGreaterThanOrEqual(5);
});
@@ -71,7 +79,10 @@ describe('parseInline', () => {
expect(result[0].children).toHaveLength(1);
expect(result[0].children[0].type).toBe('italic');
if (result[0].children[0].type === 'italic') {
- expect(result[0].children[0].children[0]).toEqual({type: 'text', content: 'bold italic'});
+ expect(result[0].children[0].children[0]).toEqual({
+ type: 'text',
+ content: 'bold italic',
+ });
}
}
});
@@ -260,7 +271,8 @@ describe('parseMarkdown', () => {
});
it('parses table alignment', () => {
- const input = '| Left | Center | Right |\n| :--- | :---: | ---: |\n| a | b | c |';
+ const input =
+ '| Left | Center | Right |\n| :--- | :---: | ---: |\n| a | b | c |';
const result = parseMarkdown(input);
expect(result[0].type).toBe('table');
if (result[0].type === 'table') {
@@ -366,3 +378,143 @@ describe('parseMarkdown', () => {
expect(parseMarkdown('_ _ _')[0].type).toBe('hr');
});
});
+
+// ---------------------------------------------------------------------------
+// Citation parsing
+// ---------------------------------------------------------------------------
+
+describe('citation parsing', () => {
+ const sourceIds = new Set(['abc1', 'def2', 'src3']);
+
+ describe('bracket notation [id]', () => {
+ it('parses a bracket citation when sourceId matches', () => {
+ const result = parseInline('Tokyo is large[abc1].', sourceIds);
+ expect(result).toEqual([
+ {type: 'text', content: 'Tokyo is large'},
+ {type: 'citation', sourceId: 'abc1'},
+ {type: 'text', content: '.'},
+ ]);
+ });
+
+ it('parses multiple bracket citations', () => {
+ const result = parseInline('Fact[abc1][def2].', sourceIds);
+ expect(result).toEqual([
+ {type: 'text', content: 'Fact'},
+ {type: 'citation', sourceId: 'abc1'},
+ {type: 'citation', sourceId: 'def2'},
+ {type: 'text', content: '.'},
+ ]);
+ });
+
+ it('does NOT treat [id] as citation when id is not in sourceIds', () => {
+ const result = parseInline('Use [PID] here.', sourceIds);
+ expect(result.some(n => n.type === 'citation')).toBe(false);
+ });
+
+ it('does NOT treat [text](url) as citation', () => {
+ const result = parseInline(
+ '[click here](https://example.com)',
+ sourceIds,
+ );
+ expect(result).toEqual([
+ {
+ type: 'link',
+ href: 'https://example.com',
+ children: [{type: 'text', content: 'click here'}],
+ },
+ ]);
+ });
+
+ it('handles citation next to link', () => {
+ const result = parseInline(
+ 'See [link](https://example.com)[abc1].',
+ sourceIds,
+ );
+ expect(result[0]).toEqual({type: 'text', content: 'See '});
+ expect(result[1]).toEqual({
+ type: 'link',
+ href: 'https://example.com',
+ children: [{type: 'text', content: 'link'}],
+ });
+ expect(result[2]).toEqual({type: 'citation', sourceId: 'abc1'});
+ });
+
+ it('ignores brackets when no sourceIds provided', () => {
+ const result = parseInline('Text [abc1] here.');
+ expect(result.some(n => n.type === 'citation')).toBe(false);
+ });
+ });
+
+ describe('fullwidth bracket notation 【id】', () => {
+ it('parses a fullwidth bracket citation', () => {
+ const result = parseInline('Data【abc1】.', sourceIds);
+ expect(result).toEqual([
+ {type: 'text', content: 'Data'},
+ {type: 'citation', sourceId: 'abc1'},
+ {type: 'text', content: '.'},
+ ]);
+ });
+
+ it('parses consecutive fullwidth citations', () => {
+ const result = parseInline('Info【abc1】【def2】end.', sourceIds);
+ expect(result).toEqual([
+ {type: 'text', content: 'Info'},
+ {type: 'citation', sourceId: 'abc1'},
+ {type: 'citation', sourceId: 'def2'},
+ {type: 'text', content: 'end.'},
+ ]);
+ });
+
+ it('preserves fullwidth brackets when id is not in sourceIds', () => {
+ const result = parseInline('Keep【hello world】.', sourceIds);
+ expect(result.some(n => n.type === 'citation')).toBe(false);
+ });
+ });
+
+ describe('mixed formats', () => {
+ it('handles both bracket and fullwidth in same text', () => {
+ const result = parseInline('A[abc1] B【def2】.', sourceIds);
+ expect(result).toEqual([
+ {type: 'text', content: 'A'},
+ {type: 'citation', sourceId: 'abc1'},
+ {type: 'text', content: ' B'},
+ {type: 'citation', sourceId: 'def2'},
+ {type: 'text', content: '.'},
+ ]);
+ });
+ });
+
+ describe('block-level threading', () => {
+ it('detects citations inside paragraphs', () => {
+ const blocks = parseMarkdown('Tokyo is big[abc1].', sourceIds);
+ expect(blocks).toHaveLength(1);
+ if (blocks[0].type === 'paragraph') {
+ expect(blocks[0].children.some(n => n.type === 'citation')).toBe(true);
+ }
+ });
+
+ it('detects citations inside list items', () => {
+ const blocks = parseMarkdown('- Item[abc1]\n- Item[def2]', sourceIds);
+ expect(blocks).toHaveLength(1);
+ if (blocks[0].type === 'list') {
+ const firstItem = blocks[0].items[0].children[0];
+ if (firstItem.type === 'paragraph') {
+ expect(firstItem.children.some(n => n.type === 'citation')).toBe(
+ true,
+ );
+ }
+ }
+ });
+
+ it('detects citations inside table cells', () => {
+ const md = '| A | B |\n|---|---|\n| data[abc1] | ok |';
+ const blocks = parseMarkdown(md, sourceIds);
+ expect(blocks).toHaveLength(1);
+ if (blocks[0].type === 'table') {
+ expect(
+ blocks[0].rows[0][0].children.some(n => n.type === 'citation'),
+ ).toBe(true);
+ }
+ });
+ });
+});
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index 375b167499..154711ac4c 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -17,6 +17,7 @@ export type InlineNode =
| {type: 'code'; content: string}
| {type: 'link'; href: string; children: InlineNode[]}
| {type: 'image'; src: string; alt: string}
+ | {type: 'citation'; sourceId: string}
| {type: 'break'};
export type BlockNode =
@@ -64,7 +65,45 @@ function isWordChar(ch: string | undefined): boolean {
// Inline parser
// ---------------------------------------------------------------------------
-export function parseInline(text: string): InlineNode[] {
+/**
+ * Match a fullwidth bracket citation 【id】 at position `i`.
+ * Returns the sourceId and end index, or null if no match.
+ */
+function matchFullwidthCitation(
+ text: string,
+ i: number,
+ sourceIds: ReadonlySet<string> | undefined,
+): {sourceId: string; end: number} | null {
+ if (!sourceIds || text[i] !== '\u3010') return null;
+ const closeIndex = text.indexOf('\u3011', i + 1);
+ if (closeIndex === -1) return null;
+ const id = text.slice(i + 1, closeIndex);
+ if (id.length === 0 || !sourceIds.has(id)) return null;
+ return {sourceId: id, end: closeIndex + 1};
+}
+
+/**
+ * Match a bracket citation [id] at position `i`.
+ * Only matches if the id exists in sourceIds and is NOT followed by `(` (link).
+ */
+function matchBracketCitation(
+ text: string,
+ i: number,
+ sourceIds: ReadonlySet<string> | undefined,
+): {sourceId: string; end: number} | null {
+ if (!sourceIds || text[i] !== '[') return null;
+ const closeIndex = text.indexOf(']', i + 1);
+ if (closeIndex === -1) return null;
+ if (text[closeIndex + 1] === '(') return null;
+ const id = text.slice(i + 1, closeIndex);
+ if (id.length === 0 || !sourceIds.has(id)) return null;
+ return {sourceId: id, end: closeIndex + 1};
+}
+
+export function parseInline(
+ text: string,
+ sourceIds?: ReadonlySet<string>,
+): InlineNode[] {
const nodes: InlineNode[] = [];
let i = 0;
@@ -88,6 +127,16 @@ export function parseInline(text: string): InlineNode[] {
}
}
+ // --- Citation: fullwidth 【id】 ---
+ {
+ const citation = matchFullwidthCitation(text, i, sourceIds);
+ if (citation) {
+ nodes.push({type: 'citation', sourceId: citation.sourceId});
+ i = citation.end;
+ continue;
+ }
+ }
+
// --- Image ![alt](src) ---
if (text[i] === '!' && text[i + 1] === '[') {
const altClose = text.indexOf(']', i + 2);
@@ -105,6 +154,16 @@ export function parseInline(text: string): InlineNode[] {
}
}
+ // --- Citation: bracket [id] (before link — link requires `(` after `]`) ---
+ {
+ const citation = matchBracketCitation(text, i, sourceIds);
+ if (citation) {
+ nodes.push({type: 'citation', sourceId: citation.sourceId});
+ i = citation.end;
+ continue;
+ }
+ }
+
// --- Link [text](url) ---
if (text[i] === '[') {
const textClose = text.indexOf(']', i + 1);
@@ -114,7 +173,7 @@ export function parseInline(text: string): InlineNode[] {
nodes.push({
type: 'link',
href: text.slice(textClose + 2, urlClose),
- children: parseInline(text.slice(i + 1, textClose)),
+ children: parseInline(text.slice(i + 1, textClose), sourceIds),
});
i = urlClose + 1;
continue;
@@ -142,7 +201,7 @@ export function parseInline(text: string): InlineNode[] {
children: [
{
type: 'italic',
- children: parseInline(text.slice(i + 3, closeIndex)),
+ children: parseInline(text.slice(i + 3, closeIndex), sourceIds),
},
],
});
@@ -169,7 +228,7 @@ export function parseInline(text: string): InlineNode[] {
) {
nodes.push({
type: 'bold',
- children: parseInline(text.slice(i + 2, closeIndex)),
+ children: parseInline(text.slice(i + 2, closeIndex), sourceIds),
});
i = closeIndex + 2;
continue;
@@ -183,7 +242,7 @@ export function parseInline(text: string): InlineNode[] {
if (closeIndex !== -1) {
nodes.push({
type: 'strikethrough',
- children: parseInline(text.slice(i + 2, closeIndex)),
+ children: parseInline(text.slice(i + 2, closeIndex), sourceIds),
});
i = closeIndex + 2;
continue;
@@ -204,7 +263,7 @@ export function parseInline(text: string): InlineNode[] {
) {
nodes.push({
type: 'italic',
- children: parseInline(text.slice(i + 1, closeIndex)),
+ children: parseInline(text.slice(i + 1, closeIndex), sourceIds),
});
i = closeIndex + 1;
continue;
@@ -214,7 +273,7 @@ export function parseInline(text: string): InlineNode[] {
// --- Plain text (with line-break detection) ---
let end = i + 1;
- while (end < text.length && !'*_~`[!\\\n'.includes(text[end])) end++;
+ while (end < text.length && !'*_~`[!\\\n\u3010'.includes(text[end])) end++;
const content = text.slice(i, end);
@@ -307,9 +366,10 @@ function splitTableRow(line: string): string[] {
function parseTable(
lines: string[],
lineIndex: number,
+ sourceIds?: ReadonlySet<string>,
): {node: BlockNode; nextIndex: number} {
const headers: TableCellNode[] = splitTableRow(lines[lineIndex]).map(
- cell => ({children: parseInline(cell)}),
+ cell => ({children: parseInline(cell, sourceIds)}),
);
const alignments: TableAlignment[] = splitTableRow(lines[lineIndex + 1]).map(
cell => {
@@ -334,7 +394,7 @@ function parseTable(
) {
rows.push(
splitTableRow(lines[rowIndex]).map(cell => ({
- children: parseInline(cell),
+ children: parseInline(cell, sourceIds),
})),
);
rowIndex++;
@@ -349,6 +409,7 @@ function parseList(
lines: string[],
startIndex: number,
ordered: boolean,
+ sourceIds?: ReadonlySet<string>,
): {node: BlockNode; nextIndex: number} {
const items: ListItemNode[] = [];
const baseIndent = getIndent(lines[startIndex]);
@@ -396,7 +457,7 @@ function parseList(
itemText += '\n' + deindented.join('\n');
}
- items.push({checked, children: parseMarkdown(itemText)});
+ items.push({checked, children: parseMarkdown(itemText, sourceIds)});
}
return {node: {type: 'list', ordered, start, items}, nextIndex: index};
}
@@ -405,7 +466,10 @@ function parseList(
// Main block parser
// ---------------------------------------------------------------------------
-export function parseMarkdown(input: string): BlockNode[] {
+export function parseMarkdown(
+ input: string,
+ sourceIds?: ReadonlySet<string>,
+): BlockNode[] {
const lines = input.split('\n');
const blocks: BlockNode[] = [];
let index = 0;
@@ -439,7 +503,7 @@ export function parseMarkdown(input: string): BlockNode[] {
blocks.push({
type: 'heading',
level: headingMatch[1].length as 1 | 2 | 3 | 4 | 5 | 6,
- children: parseInline(headingMatch[2]),
+ children: parseInline(headingMatch[2], sourceIds),
});
index++;
continue;
@@ -466,7 +530,7 @@ export function parseMarkdown(input: string): BlockNode[] {
line.includes('|') &&
isTableSeparator(lines[index + 1])
) {
- const tableResult = parseTable(lines, index);
+ const tableResult = parseTable(lines, index, sourceIds);
blocks.push(tableResult.node);
index = tableResult.nextIndex;
continue;
@@ -484,14 +548,14 @@ export function parseMarkdown(input: string): BlockNode[] {
}
blocks.push({
type: 'blockquote',
- children: parseMarkdown(quoteLines.join('\n')),
+ children: parseMarkdown(quoteLines.join('\n'), sourceIds),
});
continue;
}
// --- Unordered list ---
if (/^ {0,9}[-*+] /.test(line)) {
- const listResult = parseList(lines, index, false);
+ const listResult = parseList(lines, index, false, sourceIds);
blocks.push(listResult.node);
index = listResult.nextIndex;
continue;
@@ -499,7 +563,7 @@ export function parseMarkdown(input: string): BlockNode[] {
// --- Ordered list ---
if (/^ {0,9}\d+\. /.test(line)) {
- const listResult = parseList(lines, index, true);
+ const listResult = parseList(lines, index, true, sourceIds);
blocks.push(listResult.node);
index = listResult.nextIndex;
continue;
@@ -518,7 +582,7 @@ export function parseMarkdown(input: string): BlockNode[] {
}
blocks.push({
type: 'paragraph',
- children: parseInline(paraLines.join('\n')),
+ children: parseInline(paraLines.join('\n'), sourceIds),
});
}
return blocks;
@@ -736,6 +800,7 @@ function trimUnsettledStructural(text: string): string {
export function parseMarkdownIncremental(
input: string,
state: IncrementalState,
+ sourceIds?: ReadonlySet<string>,
): BlockNode[] {
if (input === '') {
state.prevInput = '';
@@ -751,7 +816,7 @@ export function parseMarkdownIncremental(
if (boundary < 0) {
// Inside an unclosed fence or no blank-line boundary — full re-parse
state.prevInput = input;
- return parseMarkdown(input);
+ return parseMarkdown(input, sourceIds);
}
const settledText = lines.slice(0, boundary).join('\n');
@@ -769,14 +834,16 @@ export function parseMarkdownIncremental(
) {
// Settled portion grew — parse only the new delta
const delta = settledText.slice(state.settledText.length);
- const deltaBlocks = parseMarkdown(delta);
+ const deltaBlocks = parseMarkdown(delta, sourceIds);
settledBlocks = [...state.settledBlocks, ...deltaBlocks];
} else {
// Content before the boundary changed — full re-parse of settled portion
- settledBlocks = parseMarkdown(settledText);
+ settledBlocks = parseMarkdown(settledText, sourceIds);
}
- const unsettledBlocks = unsettledText ? parseMarkdown(unsettledText) : [];
+ const unsettledBlocks = unsettledText
+ ? parseMarkdown(unsettledText, sourceIds)
+ : [];
state.settledText = settledText;
state.settledBlocks = settledBlocks;