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.tsxnew file mode 100644index 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.tsxindex 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 = (<divrole="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.tsindex 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.tsindex 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.tsindex 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  ---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-parsestate.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 deltaconst 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;