An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Markdown.tsx
* @input Markdown string, canonical AST, optional plugins and custom renderers;
* static document lists permit outside counter paint through ordered and
* unordered ancestors. Flow-task
* bodies use per-item first-line markers; paragraph-only task lists retain
* their CheckboxList representation.
* @output Exports Markdown component, MarkdownProps, and renderer contracts
* @position Core implementation; renders markdown as Astryx components
*/
import {Suspense, useMemo, useRef, useState} from 'react';
import type React from 'react';
import {Fragment} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
radiusVars,
typeScaleVars,
typographyVars,
fontWeightVars,
borderVars,
durationVars,
easeVars,
} from '../theme/tokens.stylex';
import type {TextDisplay} from '../theme/types';
import {CodeBlock, Code} from '../CodeBlock';
import {parseFenceLanguage} from '../CodeBlock/tokenizer';
import {listedLanguage, sameCodeLanguageList} from '../CodeBlock/grammar';
import type {CodeLanguage} from '../CodeBlock/grammar';
import {CheckboxList} from '../CheckboxList/CheckboxList';
import {CheckboxListItem} from '../CheckboxList/CheckboxListItem';
import {Blockquote} from '../Blockquote/Blockquote';
import {List} from '../List/List';
import {ListItem} from '../List/ListItem';
import {ListMarkerScope, type ListMarker} from '../List/ListContext';
import {Table} from '../Table/Table';
import {TableRow} from '../Table/TableRow';
import {TableCell} from '../Table/TableCell';
import {TableHeaderCell} from '../Table/TableHeaderCell';
import {TableHeader} from '../Table/TableHeader';
import {TableBody} from '../Table/TableBody';
import {mergeProps} from '../utils';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {useStreamingText} from '../hooks/useStreamingText';
import {computeBoundaries, computeSegments} from './streaming';
import type {BaseProps} from '../BaseProps';
import {useTheme} from '../theme/useTheme';
import {Citation} from '../Citation/Citation';
import type {CitationSource} from '../Citation/Citation';
import {useLinkComponent} from '../Link/useLinkComponent';
import type {LinkComponentType} from '../Link/types';
import {
parseInlineAst,
parseMarkdownAst,
parseMarkdownAstIncremental,
createIncrementalState,
trimStreamingArtifacts,
} from './parser';
import type {IncrementalState, MathParseOptions, ParseOptions} from './parser';
import {getMarkdownAstLegacyCodeLanguage, markdownAstText} from './ast';
import {
blockDirection,
innerDirectionScope,
type BlockDirectionScope,
} from './blockDirection';
import type {
MarkdownAstBlockContent,
MarkdownAstPhrasingContent,
MarkdownAstPosition,
MarkdownAstTable,
MarkdownAstTableAlignment,
} from './ast';
import {
applyMarkdownTransforms,
getMarkdownExtensionRenderer,
markdownExtensionText,
prepareMarkdownPlugins,
reportMarkdownPluginFailure,
} from './plugins/protocol';
import {getMarkdownFenceProposal} from './plugins/semanticFence';
import {
MarkdownPluginBoundary,
renderMarkdownPluginNode,
} from './plugin-renderer/MarkdownPluginNodeRenderer';
import type {
MarkdownExtensionNode,
MarkdownPluginEntry,
PreparedMarkdownPlugins,
} from './plugins/protocol';
import {sanitizeMarkdownLinkUrl, sanitizeMarkdownUrl} from './url';
import {
projectMarkdownHeadings,
type MarkdownHeadingProjection,
} from './headingProjection';
import {
HeadingLinksRenderer,
headingLinksHeadingStyle,
} from './plugins/HeadingLinksRenderer';
import {themeProps} from '../utils/themeProps';
import type {TranslatorFn} from '../i18n';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import {useDirection} from '../i18n/useDirection';
import english from '../i18n/generated-english/Markdown/Markdown.generated';
registerEnglishFallback(english);
type SyncReactNode = Exclude<React.ReactNode, Promise<unknown>>;
type RenderExtensionNode = MarkdownExtensionNode;
type RenderInlineNode = MarkdownAstPhrasingContent<RenderExtensionNode>;
type RenderBlockNode = MarkdownAstBlockContent<RenderExtensionNode>;
// spec:AST-061 DEC-6: a list nested inside n lists, of either kind, draws the
// marker at n modulo 3.
const BULLET_MARKERS: readonly [ListMarker, ListMarker, ListMarker] = [
'disc',
'circle',
'square',
];
const NUMBER_MARKERS: readonly [ListMarker, ListMarker, ListMarker] = [
'decimal',
'lower-alpha',
'lower-roman',
];
type RenderTable = MarkdownAstTable<RenderExtensionNode>;
// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------
/**
* A plugin that transforms text patterns into custom React elements
* inside Markdown. Applied to parsed text nodes only — code blocks,
* inline code, math, and other non-prose contexts are unaffected.
*
* Follows Lexical's TextMatchTransformer architecture:
* - `pattern` for initial regex matching
* - `getEndIndex` for programmatic boundary refinement
* - `render` for producing the replacement element
*/
export interface MarkdownInlinePlugin {
/** Regex with global flag. Matched against text nodes only. */
pattern: RegExp;
/**
* Optional: refine the match boundary after the regex hits.
* Return the end index, or false to reject the match.
* Default: match.index + match[0].length
*/
getEndIndex?: (text: string, match: RegExpMatchArray) => number | false;
/** Render the match as a React element. */
render: (match: RegExpMatchArray, key: string) => React.ReactNode;
}
/**
* 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 type MarkdownSource = CitationSource;
/**
* A block's 1-based, inclusive source lines, given to `components` block
* renderers while `markdownSourceLinesPlugin` is installed.
*/
export interface MarkdownSourceLines {
readonly start: number;
readonly end: number;
}
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;
sourceLines?: MarkdownSourceLines;
}>;
inlineCode?: React.ComponentType<{children: string}>;
/**
* Renders opt-in `$…$` and `$$…$$` math. Supplying this renderer enables
* math parsing; Astryx passes the raw expression and does not execute it.
*/
math?: React.ComponentType<{
value: string;
display: 'inline' | 'block';
/** Present for block math only, while source lines are recorded. */
sourceLines?: MarkdownSourceLines;
}>;
citation?: React.ComponentType<{
source: CitationSource;
number: number;
variant: 'label' | 'number';
}>;
link?: React.ComponentType<{href: string; children: React.ReactNode}>;
heading?: React.ComponentType<{
level: 1 | 2 | 3 | 4 | 5 | 6;
children: React.ReactNode;
/**
* Generated stable id for this heading, matching Markdown-derived Outline.
* Released output supplies it to root headings; createMarkdownHeadingLinks()
* expands the shared allocator to headings nested in blockquotes and lists.
* Custom renderers own their output and should apply the id they receive.
*/
id?: string;
sourceLines?: MarkdownSourceLines;
}>;
paragraph?: React.ComponentType<{
children: React.ReactNode;
sourceLines?: MarkdownSourceLines;
}>;
image?: React.ComponentType<{
src: string;
alt: string;
sourceLines?: MarkdownSourceLines;
}>;
blockquote?: React.ComponentType<{
children: React.ReactNode;
sourceLines?: MarkdownSourceLines;
}>;
hr?: React.ComponentType<{sourceLines?: MarkdownSourceLines}>;
}
/** A block node's recorded source lines, if the parse recorded them. */
function blockSourceLines(node: {
readonly position?: MarkdownAstPosition;
}): MarkdownSourceLines | undefined {
const start = node.position?.start.line;
const end = node.position?.end.line;
return start == null || end == null ? undefined : {start, end};
}
/** The stamps a default block element carries for its source lines. */
function sourceLineAttributes(lines: MarkdownSourceLines | undefined):
| {
readonly 'data-source-line': string;
readonly 'data-source-line-end': string;
}
| undefined {
return lines == null
? undefined
: {
'data-source-line': String(lines.start),
'data-source-line-end': String(lines.end),
};
}
export interface MarkdownProps<
Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],
> extends BaseProps<HTMLElement> {
ref?: React.Ref<HTMLDivElement> | React.Ref<HTMLSpanElement>;
children: string;
/**
* Display type. Markdown defaults to block.
* Use 'inline' for markdown spans embedded inside surrounding text.
* @default 'block'
*/
display?: TextDisplay;
density?: 'default' | 'compact';
/**
* The HTML heading level that markdown `#` maps to.
* Shifts all heading levels down to fit the surrounding page hierarchy.
* E.g. headingLevelStart={3} renders `#` as h3, `##` as h4, `###` as h5.
* Levels that would exceed h6 are clamped to h6.
* @default 1
*/
headingLevelStart?: 1 | 2 | 3 | 4 | 5 | 6;
isStreaming?: boolean;
onLinkClick?: (
href: string,
event: React.MouseEvent<HTMLAnchorElement>,
) => void | false; // eslint-disable-line @typescript-eslint/no-invalid-void-type
/**
* 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, MarkdownSource>;
/**
* 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';
/**
* Max width for prose content (paragraphs, headings, lists, blockquotes).
* Tables and code blocks are unconstrained and can expand to the full
* container width. Use for readable line lengths in wide layouts.
*
* @example
* ```
* <Markdown contentWidth={640}>{text}</Markdown>
* ```
*/
contentWidth?: number | string;
/**
* Alignment of prose content within the container when `contentWidth`
* is narrower than the available space.
* - 'start': left-aligned (default)
* - 'center': centered
* @default 'start'
*/
contentAlign?: 'start' | 'center';
components?: Partial<MarkdownComponents>;
/**
* Plugins that transform text patterns into custom React elements.
* Applied to text nodes after parsing — code blocks, inline code, and math
* are unaffected. Patterns are matched in order; first match wins
* for overlapping ranges.
*/
/** Ordered syntax, immutable transforms, and typed extension renderers. */
plugins?: Plugins;
/**
* Legacy text-match renderers. Unchanged and independent from `plugins`.
*/
inlinePlugins?: MarkdownInlinePlugin[];
/**
* Opt-in autolinking of bare URLs and emails inside text.
* - `'gfm'` — GitHub-Flavored Markdown autolink-literal rules:
* `https?://…`, `www.…`, `<scheme:url>`, `<email>`, and bare
* `user@host` all become `<a>` links. Trailing sentence punctuation
* (`?!.,:*_~`) and unbalanced trailing `)` are excluded; matches inside
* code spans, code blocks, existing links, and image alt text are
* skipped.
*
* Default behavior (option unset) is unchanged — bare URLs render as
* literal text.
*/
autolink?: 'gfm';
/**
* CodeBlock language values a fence may name: each one imported on its
* own, such as `graphql` from `@astryxdesign/core/CodeBlock/languages/graphql`,
* or made with `createCodeLanguage`. A fence whose language word is one of
* a listed value's identifiers renders with that value, ahead of a built-in
* with the same identifier; a later entry wins. Without it, fences render
* as they do today.
*/
codeLanguages?: ReadonlyArray<CodeLanguage>;
}
// ---------------------------------------------------------------------------
// Styles
// ---------------------------------------------------------------------------
const ALIGN_MARGIN: Record<string, string> = {
start: '0',
center: 'auto',
};
const BLOCK_ALIGN_MARGIN: Record<string, string | null> = {
start: null,
center: 'auto',
};
const dynamicStyles = stylex.create({
proseWidth: (maxWidth: string) => ({
maxWidth,
}),
proseAlign: (marginInline: string) => ({
marginInline,
}),
blockWidth: (minWidth: string) => ({
minWidth: `min(${minWidth}, 100%)`,
}),
blockAlign: (marginInline: string) => ({
marginInline,
}),
cellMinWidth: (minWidth: string) => ({
minWidth,
}),
});
const cellAlignStyles = stylex.create({
start: {textAlign: 'start'},
center: {textAlign: 'center'},
end: {textAlign: 'end'},
});
/**
* Cell sizing for Markdown's own default Table part, layered over Table's
* wrap-mode defaults.
*
* Table sizes wrap-mode cells with `max-width: 0` + `word-break: break-word`,
* and its header cell also applies nowrap + ellipsis. Those defaults zero every
* column's min-content contribution, so automatic layout divides the container
* equally: a six-column Markdown table squashes to a few characters per cell,
* identifiers split mid-word, header labels ellipsize, and nothing ever
* overflows into the Scroll region that exists to take the width.
*
* Here the cell reports an honest min-content, the header wraps instead of
* truncating, and `box-sizing: content-box` makes the per-column `ch` floor a
* floor on the text box rather than on the padded border box — so the floor
* means the same number of characters at every density, with no padding
* arithmetic to keep in sync with Table's own tokens.
*
* Data-driven `Table` keeps its released wrap mode; only Markdown's part is
* restyled.
*/
const markdownTableCellStyles = stylex.create({
cell: {
boxSizing: 'content-box',
maxWidth: 'none',
overflow: 'visible',
overflowWrap: 'break-word',
paddingBlock: spacingVars['--spacing-2'],
paddingInline: spacingVars['--spacing-2'],
wordBreak: 'normal',
},
headerCell: {
boxSizing: 'content-box',
maxWidth: 'none',
overflow: 'visible',
overflowWrap: 'break-word',
paddingBlock: spacingVars['--spacing-2'],
paddingInline: spacingVars['--spacing-2'],
textOverflow: 'clip',
whiteSpace: 'normal',
wordBreak: 'normal',
},
// Inline Code sets `word-break: break-word` so a long token cannot widen a
// paragraph. Inside a table cell that same rule zeroes the token's
// min-content and splits an identifier across lines; the cell keeps it whole
// and lets the column carry the width instead.
code: {
wordBreak: 'normal',
},
// A cell that reads against its table draws the column rule on the table's
// inline-end side, which is the cell's own inline-start.
ruleOnTableEnd: {
borderInlineEndWidth: 0,
borderInlineStartWidth: {
default: borderVars['--border-width'],
':last-child': '0',
},
borderInlineStartStyle: 'solid',
borderInlineStartColor: colorVars['--color-border'],
},
// The grid's outer edge. `dividers="grid"` draws the lines *between* cells
// and stops at the table's rim, so without this the top, bottom, and sides
// stay open and the grid reads as unfinished. On the table element, not the
// wrapper, so `border-collapse: collapse` merges it with the cell lines
// into one 1px rule rather than doubling up at the edge.
tableOuterEdge: {
borderWidth: borderVars['--border-width'],
borderStyle: 'solid',
borderColor: colorVars['--color-border'],
},
});
/**
* Default inline-code renderer inside Markdown table cells. Used only when the
* consumer supplies no `components.inlineCode`; a custom renderer owns its own
* wrapping rules.
*/
function MarkdownTableCellCode({children}: {children: string}) {
return <Code xstyle={markdownTableCellStyles.code}>{children}</Code>;
}
const styles = stylex.create({
root: {
fontFamily: typographyVars['--font-family-body'],
color: colorVars['--color-text-primary'],
lineHeight: typeScaleVars['--text-body-leading'],
fontSize: typeScaleVars['--text-body-size'],
width: '100%',
maxWidth: '100%',
minWidth: 0,
overflowWrap: 'break-word',
},
inlineRoot: {
display: 'inline',
width: 'auto',
maxWidth: 'none',
fontFamily: 'inherit',
color: 'inherit',
lineHeight: 'inherit',
fontSize: 'inherit',
},
// Headings
headingBase: {
fontFamily: typographyVars['--font-family-heading'],
color: colorVars['--color-text-primary'],
},
h1: {
fontSize: typeScaleVars['--text-heading-1-size'],
fontWeight: typeScaleVars['--text-heading-1-weight'],
lineHeight: typeScaleVars['--text-heading-1-leading'],
},
h2: {
fontSize: typeScaleVars['--text-heading-2-size'],
fontWeight: typeScaleVars['--text-heading-2-weight'],
lineHeight: typeScaleVars['--text-heading-2-leading'],
},
h3: {
fontSize: typeScaleVars['--text-heading-3-size'],
fontWeight: typeScaleVars['--text-heading-3-weight'],
lineHeight: typeScaleVars['--text-heading-3-leading'],
},
h4: {
fontSize: typeScaleVars['--text-heading-4-size'],
fontWeight: typeScaleVars['--text-heading-4-weight'],
lineHeight: typeScaleVars['--text-heading-4-leading'],
},
h5: {
fontSize: typeScaleVars['--text-heading-5-size'],
fontWeight: typeScaleVars['--text-heading-5-weight'],
lineHeight: typeScaleVars['--text-heading-5-leading'],
},
h6: {
fontSize: typeScaleVars['--text-heading-6-size'],
fontWeight: typeScaleVars['--text-heading-6-weight'],
lineHeight: typeScaleVars['--text-heading-6-leading'],
},
// Block spacing — per element type, default density
spacingHeadingMajorDefault: {
marginBlockStart: spacingVars['--spacing-6'],
marginBlockEnd: spacingVars['--spacing-3'],
},
spacingHeadingMinorDefault: {
marginBlockStart: spacingVars['--spacing-4'],
marginBlockEnd: spacingVars['--spacing-2'],
},
spacingParagraphDefault: {
marginBlockStart: spacingVars['--spacing-3'],
marginBlockEnd: spacingVars['--spacing-3'],
},
spacingCodeblockDefault: {
marginBlockStart: spacingVars['--spacing-4'],
marginBlockEnd: spacingVars['--spacing-4'],
},
spacingBlockquoteDefault: {
marginBlockStart: spacingVars['--spacing-4'],
marginBlockEnd: spacingVars['--spacing-4'],
},
spacingListDefault: {
marginBlockStart: spacingVars['--spacing-3'],
marginBlockEnd: spacingVars['--spacing-3'],
},
spacingTableDefault: {
marginBlockStart: spacingVars['--spacing-4'],
marginBlockEnd: spacingVars['--spacing-4'],
},
spacingHrDefault: {
marginBlockStart: spacingVars['--spacing-6'],
marginBlockEnd: spacingVars['--spacing-6'],
},
spacingImageDefault: {
marginBlockStart: spacingVars['--spacing-3'],
marginBlockEnd: spacingVars['--spacing-3'],
},
// Block spacing — per element type, compact density
spacingHeadingMajorCompact: {
marginBlockStart: spacingVars['--spacing-4'],
marginBlockEnd: spacingVars['--spacing-2'],
},
spacingHeadingMinorCompact: {
marginBlockStart: spacingVars['--spacing-3'],
marginBlockEnd: spacingVars['--spacing-1'],
},
spacingParagraphCompact: {
marginBlockStart: spacingVars['--spacing-1'],
marginBlockEnd: spacingVars['--spacing-1'],
},
spacingCodeblockCompact: {
marginBlockStart: spacingVars['--spacing-2'],
marginBlockEnd: spacingVars['--spacing-2'],
},
spacingBlockquoteCompact: {
marginBlockStart: spacingVars['--spacing-2'],
marginBlockEnd: spacingVars['--spacing-2'],
},
spacingListCompact: {
marginBlockStart: spacingVars['--spacing-1'],
marginBlockEnd: spacingVars['--spacing-1'],
},
spacingTableCompact: {
marginBlockStart: spacingVars['--spacing-2'],
marginBlockEnd: spacingVars['--spacing-2'],
},
spacingHrCompact: {
marginBlockStart: spacingVars['--spacing-3'],
marginBlockEnd: spacingVars['--spacing-3'],
},
spacingImageCompact: {
marginBlockStart: spacingVars['--spacing-2'],
marginBlockEnd: spacingVars['--spacing-2'],
},
noMarginBlockStart: {
marginBlockStart: 0,
},
noMarginBlockEnd: {
marginBlockEnd: 0,
},
// Table
codeBlockWrapper: {
maxWidth: '100%',
},
tableWrapper: {
// No `overflow-x` here: Table's own Scroll region (`table-scroll-wrapper`)
// is the table's scroller, and this block is exactly as wide as it, so a
// second scroll container would only add a dead focus stop.
maxWidth: '100%',
'--container-padding-inline-start': '0px',
'--container-padding-inline-end': '0px',
'--container-padding-block-start': '0px',
'--container-padding-block-end': '0px',
},
// Static Markdown lists never host swipe actions. Let outside counter ink
// paint through both ordered and unordered ancestors; general List and
// swipe-capable rows retain their own inline clip (component:List FR9).
blockIndent: {
marginInline: `calc(-1 * ${spacingVars['--spacing-2']})`,
overflowInline: 'visible',
},
// Numbered document lists keep their ordinary text inset regardless of
// counter width, matching RichText's native outside markers (AST-061 FR11).
// These rows have no swipe actions: unlike general List, their outside ink
// may paint past the gutter instead of being clipped at a finite threshold.
markerGutter: {
marginInlineStart: `calc(-1 * (${spacingVars['--spacing-2']} + ${spacingVars['--spacing-4']}))`,
paddingInlineStart: spacingVars['--spacing-4'],
},
// HR
hr: {
borderWidth: 0,
borderTopWidth: borderVars['--border-width'],
borderTopStyle: 'solid',
borderTopColor: colorVars['--color-border'],
},
// Image
image: {
maxWidth: '100%',
borderRadius: radiusVars['--radius-element'],
},
// Inline
bold: {
fontWeight: fontWeightVars['--font-weight-semibold'],
},
strikethrough: {
color: colorVars['--color-text-secondary'],
},
link: {
color: colorVars['--color-text-accent'],
textDecoration: 'underline',
},
});
// ---------------------------------------------------------------------------
// Streaming fade-in animation
// Parse a CSS duration string (e.g. "175ms", "0.15s") to milliseconds.
function parseDuration(value: string): number | null {
const ms = value.match(/^([\d.]+)ms$/);
if (ms) {
return parseFloat(ms[1]);
}
const s = value.match(/^([\d.]+)s$/);
if (s) {
return parseFloat(s[1]) * 1000;
}
return null;
}
// ---------------------------------------------------------------------------
const streamingStyles = stylex.create({
fadeIn: {
opacity: 1,
transitionProperty: 'opacity',
// Collapse the entry fade to an instant swap under reduced motion. The
// 0s duration makes the @starting-style opacity jump non-animated (the
// media query can't nest inside @starting-style), mirroring the
// conditional-duration form in Spinner (Spinner.tsx).
transitionDuration: {
default: durationVars['--duration-medium'],
'@media (prefers-reduced-motion: reduce)': '0s',
},
transitionTimingFunction: easeVars['--ease-standard'],
'@starting-style': {
opacity: 0,
},
},
});
/**
* Mutable cursor threaded through the render tree during streaming.
* Tracks how many text characters we've visited so far. When `offset`
* crosses `boundary`, newly rendered content is wrapped in a fade-in span.
*/
interface StreamingCursor {
/** Characters visited so far in this render pass */
offset: number;
/** Recent boundary positions (up to 3), oldest first.
* Text before boundaries[0] is fully visible (no animation).
* Text between boundaries[i] and boundaries[i+1] gets its own fade span.
* Text after the last boundary is the newest chunk. */
boundaries: number[];
/** Whether streaming fade is active */
active: boolean;
}
/**
* Count the total text characters in inline nodes without rendering.
* Used to advance the cursor past a block that will be faded as a whole unit.
*/
function countInlineTextLength(nodes: ReadonlyArray<RenderInlineNode>): number {
let len = 0;
for (const node of nodes) {
switch (node.type) {
case 'text':
len += node.value.length;
break;
case 'inlineCode':
len += node.value.length;
break;
case 'inlineMath':
len += node.value.length;
break;
case 'image':
len += node.alt.length;
break;
case 'strong':
case 'emphasis':
case 'delete':
case 'link':
len += countInlineTextLength(node.children);
break;
case 'break':
len += 1;
break;
case 'citation':
len += 1;
break;
case 'extension':
len += node.source?.length ?? 0;
break;
}
}
return len;
}
/**
* Count total text characters in a block node tree.
*/
function countBlockTextLength(nodes: ReadonlyArray<RenderBlockNode>): number {
let len = 0;
for (const node of nodes) {
switch (node.type) {
case 'heading':
case 'paragraph':
len += countInlineTextLength(node.children);
break;
case 'code':
len += node.value.length;
break;
case 'math':
len += node.value.length;
break;
case 'blockquote':
len += countBlockTextLength(node.children);
break;
case 'list':
for (const item of node.children) {
len += countBlockTextLength(item.children);
}
break;
case 'table':
for (const row of node.children) {
for (const cell of row.children) {
len += countInlineTextLength(cell.children);
}
}
break;
case 'extension':
len += node.source?.length ?? 0;
break;
case 'thematicBreak':
break;
case 'image':
len += node.alt.length;
break;
}
}
return len;
}
const headingStyles = {
1: styles.h1,
2: styles.h2,
3: styles.h3,
4: styles.h4,
5: styles.h5,
6: styles.h6,
} as const;
// ---------------------------------------------------------------------------
// ---------------------------------------------------------------------------
// Inline plugin matching
// ---------------------------------------------------------------------------
type InlinePluginSegment =
| {type: 'text'; content: string}
| {type: 'plugin'; element: React.ReactNode; matchLength: number};
/**
* Find all plugin matches in a text string and split it into segments
* of plain text and plugin-rendered elements.
*
* Algorithm mirrors `findMatches` in `useLinkify`:
* 1. Run each plugin's regex against the text
* 2. Check getEndIndex if provided (default: match.index + match[0].length)
* 3. If getEndIndex returns false, skip the match
* 4. Collect all non-overlapping matches, sorted by start (first match wins)
* 5. Split into text/plugin segments
*/
function applyInlinePlugins(
text: string,
plugins: MarkdownInlinePlugin[],
): InlinePluginSegment[] {
interface RawMatch {
start: number;
end: number;
match: RegExpMatchArray;
plugin: MarkdownInlinePlugin;
}
const allMatches: RawMatch[] = [];
for (const plugin of plugins) {
// Reset lastIndex instead of cloning — avoids allocation per call.
// Safe because text nodes are processed sequentially (no interleaving).
plugin.pattern.lastIndex = 0;
let m: RegExpExecArray | null;
while ((m = plugin.pattern.exec(text)) !== null) {
let end: number;
if (plugin.getEndIndex) {
const result = plugin.getEndIndex(text, m);
if (result === false) {
continue;
}
end = result;
} else {
end = m.index + m[0].length;
}
allMatches.push({
start: m.index,
end,
match: m,
plugin,
});
}
}
// Sort by start position (stable sort preserves plugin order for same position)
allMatches.sort((a, b) => a.start - b.start);
// Remove overlapping matches (first wins)
const resolved: RawMatch[] = [];
let lastEnd = 0;
for (const m of allMatches) {
if (m.start >= lastEnd) {
resolved.push(m);
lastEnd = m.end;
}
}
if (resolved.length === 0) {
return [{type: 'text', content: text}];
}
const segments: InlinePluginSegment[] = [];
let cursor = 0;
for (let i = 0; i < resolved.length; i++) {
const m = resolved[i];
// Text before this match
if (m.start > cursor) {
segments.push({type: 'text', content: text.slice(cursor, m.start)});
}
// Plugin element
segments.push({
type: 'plugin',
element: m.plugin.render(m.match, `plugin-${i}`),
matchLength: m.end - m.start,
});
cursor = m.end;
}
// Remaining text
if (cursor < text.length) {
segments.push({type: 'text', content: text.slice(cursor)});
}
return segments;
}
function useStableMarkdownSyntaxEntries(
plugins: PreparedMarkdownPlugins | undefined,
): ReadonlyArray<MarkdownPluginEntry> | undefined {
const identity = plugins?.syntaxIdentity ?? '';
const syntaxEntriesRef = useRef<
| {
identity: string;
entries: ReadonlyArray<MarkdownPluginEntry> | undefined;
}
| undefined
>(undefined);
if (
syntaxEntriesRef.current == null ||
syntaxEntriesRef.current.identity !== identity
) {
syntaxEntriesRef.current = {
identity,
entries:
plugins == null || identity === '' ? undefined : plugins.syntaxEntries,
};
}
return syntaxEntriesRef.current.entries;
}
// ---------------------------------------------------------------------------
// Inline renderer
// ---------------------------------------------------------------------------
/**
* Wrap a text string with a fade-in span for the portion that is "new".
* If the entire string is old, returns it as-is. If partially new, splits
* into [old, <span fade>new</span>]. If entirely new, wraps the whole thing.
*/
/** Check if a cursor offset is in the "new" (animating) region */
function wrapTextWithFade(
content: string,
cursor: StreamingCursor,
key: string | number,
): SyncReactNode {
const startOffset = cursor.offset;
cursor.offset += content.length;
if (!cursor.active) {
return content;
}
const segments = computeSegments(
content,
startOffset,
cursor.boundaries,
key,
);
if (segments == null) {
return content;
}
const nodes = segments.map(seg =>
seg.fading ? (
<span key={seg.key} {...stylex.props(streamingStyles.fadeIn)}>
{seg.text}
</span>
) : (
<span key={seg.key}>{seg.text}</span>
),
);
return <span key={`wrap-${key}`}>{nodes}</span>;
}
/**
* 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, MarkdownSource>;
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: RenderInlineNode,
index: number,
onLinkClick: MarkdownProps['onLinkClick'] | undefined,
cursor: StreamingCursor,
citationCtx: CitationContext | null,
linkComponent: LinkComponentType = 'a',
inlinePlugins?: MarkdownInlinePlugin[],
components?: Partial<MarkdownComponents>,
preparedPlugins?: PreparedMarkdownPlugins,
): SyncReactNode {
switch (node.type) {
case 'text': {
if (inlinePlugins && inlinePlugins.length > 0) {
const segments = applyInlinePlugins(node.value, inlinePlugins);
// If no plugin matched, fall through to the normal path
// O(1) guard: applyInlinePlugins returns a single text segment when
// nothing matched — skip the plugin path entirely in that case.
if (!(segments.length === 1 && segments[0].type === 'text')) {
const result: React.ReactNode[] = [];
for (let i = 0; i < segments.length; i++) {
const seg = segments[i];
if (seg.type === 'text') {
result.push(
wrapTextWithFade(seg.content, cursor, `${index}-seg-${i}`),
);
} else {
// Plugin segment — advance cursor by matchLength
cursor.offset += seg.matchLength;
result.push(
<Fragment key={`plugin-${index}-${i}`}>{seg.element}</Fragment>,
);
}
}
return <Fragment key={index}>{result}</Fragment>;
}
}
return wrapTextWithFade(node.value, cursor, index);
}
case 'strong':
return (
<strong key={index} {...stylex.props(styles.bold)}>
{node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</strong>
);
case 'emphasis':
return (
<em key={index}>
{node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</em>
);
case 'delete':
return (
<del key={index} {...stylex.props(styles.strikethrough)}>
{node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</del>
);
case 'inlineCode': {
// Track code content length for cursor but don't split inside code
cursor.offset += node.value.length;
const InlineCodeComp = components?.inlineCode;
const codeEl = InlineCodeComp ? (
<InlineCodeComp key={index}>{node.value}</InlineCodeComp>
) : (
<Code key={index}>{node.value}</Code>
);
return codeEl;
}
case 'inlineMath': {
const MathComp = components?.math;
if (MathComp == null) {
return wrapTextWithFade(`$${node.value}$`, cursor, index);
}
cursor.offset += node.value.length;
return <MathComp key={index} value={node.value} display="inline" />;
}
case 'link': {
const safeHref = sanitizeMarkdownLinkUrl(node.url);
if (safeHref == null) {
// Unsafe URL — render as plain text
return (
<span key={index}>
{node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</span>
);
}
const LinkComp = components?.link;
if (LinkComp) {
return (
<LinkComp key={index} href={safeHref}>
{node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</LinkComp>
);
}
const isExternal =
safeHref.startsWith('https://') || safeHref.startsWith('http://');
const handleClick = onLinkClick
? (e: React.MouseEvent<HTMLAnchorElement>) => {
const result = onLinkClick(safeHref, e);
if (result === false) {
e.preventDefault();
}
}
: undefined;
// Use linkComponent for internal links, native <a> for external links.
// Framework routers (Next.js, React Router) handle internal navigation;
// external links with target="_blank" should use a plain anchor.
const LinkTag = isExternal ? 'a' : linkComponent;
return (
<LinkTag
key={index}
href={safeHref}
onClick={handleClick}
{...(isExternal
? {target: '_blank', rel: 'noopener noreferrer'}
: {})}
{...stylex.props(styles.link)}>
{node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</LinkTag>
);
}
case 'image': {
const safeSrc = sanitizeMarkdownUrl(node.url);
if (safeSrc == null) {
return <span key={index}>[{node.alt}]</span>;
}
const ImageComp = components?.image;
if (ImageComp) {
return <ImageComp key={index} src={safeSrc} alt={node.alt} />;
}
return (
<img
key={index}
src={safeSrc}
alt={node.alt}
{...stylex.props(styles.image)}
/>
);
}
case 'extension':
return renderMarkdownPluginNode(
preparedPlugins,
node,
wrapTextWithFade(
node.source ?? markdownExtensionText(preparedPlugins, node),
cursor,
index,
),
index,
);
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] ?? {
title: node.sourceId,
};
const citVariant = citationCtx.style === 'number' ? 'number' : 'label';
const CitationComp = components?.citation;
const chip = CitationComp ? (
<CitationComp
key={index}
source={source}
number={num}
variant={citVariant}
/>
) : (
<Citation
key={index}
source={source}
number={num}
variant={citVariant}
/>
);
return chip;
}
}
}
// ---------------------------------------------------------------------------
// Block spacing helper
// ---------------------------------------------------------------------------
function getElementSpacing(
node: RenderBlockNode,
density: 'default' | 'compact',
): StyleXStyles {
const compact = density === 'compact';
switch (node.type) {
case 'heading':
return node.depth <= 3
? compact
? styles.spacingHeadingMajorCompact
: styles.spacingHeadingMajorDefault
: compact
? styles.spacingHeadingMinorCompact
: styles.spacingHeadingMinorDefault;
case 'paragraph':
return compact
? styles.spacingParagraphCompact
: styles.spacingParagraphDefault;
case 'code':
case 'math':
return compact
? styles.spacingCodeblockCompact
: styles.spacingCodeblockDefault;
case 'blockquote':
return compact
? styles.spacingBlockquoteCompact
: styles.spacingBlockquoteDefault;
case 'list':
return compact ? styles.spacingListCompact : styles.spacingListDefault;
case 'table':
return compact ? styles.spacingTableCompact : styles.spacingTableDefault;
case 'extension':
return compact
? styles.spacingParagraphCompact
: styles.spacingParagraphDefault;
case 'thematicBreak':
return compact ? styles.spacingHrCompact : styles.spacingHrDefault;
case 'image':
return compact ? styles.spacingImageCompact : styles.spacingImageDefault;
}
}
// ---------------------------------------------------------------------------
// Block renderer
// ---------------------------------------------------------------------------
/**
* Content-derived width floors for a Markdown table's columns, in `ch`.
*
* Once the cells stop clamping themselves (see `markdownTableCellStyles`),
* automatic table layout already gives every column its min-content — the
* longest unbreakable token — so no identifier can split mid-word. That floor
* is honest but not readable: a prose column's longest word is short, so six
* prose columns in a narrow container still wrap one word per line. The
* readable floor lets a column's longest cell wrap to about two lines instead,
* scaled by that cell's own length and bounded so a table of short columns
* still fits its container.
*
* A header label adds its own floor, so a short-bodied column stays as wide as
* its label reads on one line, up to a cap past which the label wraps rather
* than widening the column further.
*
* The floors are `ch`, not `px`: they follow the reader's font size, and with
* `box-sizing: content-box` on the cells they are floors on the text box, so
* cell padding does not eat into them. Exact tuning lives here, not in the
* spec.
*/
const TABLE_COLUMN_MIN_CH = 4;
const TABLE_COLUMN_MAX_CH = 24;
const TABLE_COLUMN_TARGET_LINES = 2;
const TABLE_HEADER_ONE_LINE_MAX_CH = 20;
function computeTableColumnMinWidths(node: RenderTable): number[] {
const [header, ...rows] = node.children;
if (header == null) {
return [];
}
return header.children.map((cell, colIdx) => {
const headerLen = countInlineTextLength(cell.children);
let maxLen = headerLen;
for (const row of rows) {
const rowCell = row.children[colIdx];
if (rowCell != null) {
const len = countInlineTextLength(rowCell.children);
if (len > maxLen) {
maxLen = len;
}
}
}
// Body floor: the longest cell wraps to about TARGET_LINES lines.
const bodyFloor = Math.ceil(maxLen / TABLE_COLUMN_TARGET_LINES);
// Header floor: the label reads on one line up to the one-line cap.
const headerFloor = Math.min(headerLen, TABLE_HEADER_ONE_LINE_MAX_CH);
return Math.min(
TABLE_COLUMN_MAX_CH,
Math.max(TABLE_COLUMN_MIN_CH, bodyFloor, headerFloor),
);
});
}
/**
* The alignment and column-rule styles for a Markdown table cell. For a cell
* that reads against its table, the table's start is the cell's end, so an
* explicit alignment and the rule swap logical sides.
*/
function tableCellSideStyles(
align: MarkdownAstTableAlignment | undefined,
isAgainstTable: boolean,
): ReadonlyArray<StyleXStyles | false> {
return [
align === 'center' && cellAlignStyles.center,
align === 'right' &&
(isAgainstTable ? cellAlignStyles.start : cellAlignStyles.end),
align === 'left' && isAgainstTable && cellAlignStyles.end,
isAgainstTable && markdownTableCellStyles.ruleOnTableEnd,
];
}
function renderBlock(
node: RenderBlockNode,
index: number,
blockCount: number,
density: 'default' | 'compact',
headingLevelStart: 1 | 2 | 3 | 4 | 5 | 6,
onLinkClick: MarkdownProps['onLinkClick'] | undefined,
cursor: StreamingCursor,
citationCtx: CitationContext | null,
contentWidthValue: string | null,
contentAlign: 'start' | 'center',
linkComponent: LinkComponentType = 'a',
inlinePlugins: MarkdownInlinePlugin[] | undefined,
components: Partial<MarkdownComponents> | undefined,
preparedPlugins: PreparedMarkdownPlugins | undefined,
t: TranslatorFn,
// Language values fences may name (component:Markdown FR30).
codeLanguages: ReadonlyArray<CodeLanguage> | undefined,
headingProjection?: MarkdownHeadingProjection,
// How many lists enclose this block (spec:AST-061 DEC-6).
listDepth = 0,
directionScope?: BlockDirectionScope,
): SyncReactNode {
const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
const blockAlignStyle =
blockAlignMargin != null
? dynamicStyles.blockAlign(blockAlignMargin)
: null;
const spacing = getElementSpacing(node, density);
const isFirst = index === 0;
const isLast = index === blockCount - 1;
// Source lines exist only while the source-lines plugin is installed
// (module:Markdown/sourceLines); otherwise no block reads them.
const recordsSourceLines = preparedPlugins?.sourceLines === true;
const sourceLines = recordsSourceLines ? blockSourceLines(node) : undefined;
const lineStamps = sourceLineAttributes(sourceLines);
const lineProp = sourceLines == null ? null : {sourceLines};
switch (node.type) {
case 'heading': {
const level = Math.min(node.depth + headingLevelStart - 1, 6) as
1 | 2 | 3 | 4 | 5 | 6;
const headingChildren = node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
);
const headingId = headingProjection?.ids.get(node);
const headingLabel = headingProjection?.labels.get(node) ?? '';
const permalinkUrl = headingProjection?.permalinkUrls.get(node);
const HeadingComp = components?.heading;
if (HeadingComp) {
return (
<HeadingComp key={index} level={level} id={headingId} {...lineProp}>
{headingChildren}
</HeadingComp>
);
}
const Tag = `h${level}` as const;
if (permalinkUrl == null || headingId == null) {
return (
<Tag
key={index}
id={headingId}
dir={blockDirection(node, directionScope)}
{...mergeProps(
themeProps('markdown-heading', {density, level}),
stylex.props(
styles.headingBase,
headingStyles[level],
spacing,
contentWidthValue != null
? dynamicStyles.proseWidth(contentWidthValue)
: null,
contentAlign !== 'start'
? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
: null,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}
{...lineStamps}>
{headingChildren}
</Tag>
);
}
return (
<HeadingLinksRenderer
key={index}
dir={blockDirection(node, directionScope)}
headingId={headingId}
headingLabel={headingLabel}
permalinkUrl={permalinkUrl}
contentWidth={contentWidthValue}
contentAlign={contentAlign}
headingTextStyle={[styles.headingBase, headingStyles[level]]}
blockSpacingStyle={[
spacing,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
]}>
<Tag
id={headingId}
{...mergeProps(
themeProps('markdown-heading', {density, level}),
stylex.props(
styles.headingBase,
headingLinksHeadingStyle,
headingStyles[level],
),
)}
{...lineStamps}>
{headingChildren}
</Tag>
</HeadingLinksRenderer>
);
}
case 'paragraph': {
const paraChildren = node.children.map((c, i) =>
renderInline(
c,
i,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
);
const ParagraphComp = components?.paragraph;
if (ParagraphComp) {
return (
<ParagraphComp key={index} {...lineProp}>
{paraChildren}
</ParagraphComp>
);
}
// Markdown paragraphs render as <div>, not <p>: inline content can
// include block-level nodes (images, custom inline components), and a
// <p> would reparent them, desyncing SSR markup from the hydrated DOM.
// Block spacing comes from token-based StyleX margins, so the rendered
// appearance is unchanged. role="paragraph" re-exposes the paragraph
// role in the accessibility tree (a pure ARIA hint — it does not trigger
// the parser's block-child reparenting) so prose semantics are preserved
// without the <p> composition hazard. Consumers who want a real <p>
// element can still pass components={{paragraph: 'p'}}.
return (
<div
key={index}
role="paragraph"
dir={blockDirection(node, directionScope)}
{...mergeProps(
themeProps('markdown-paragraph', {density}),
stylex.props(
spacing,
contentWidthValue != null
? dynamicStyles.proseWidth(contentWidthValue)
: null,
contentAlign !== 'start'
? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
: null,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}
{...lineStamps}>
{paraChildren}
</div>
);
}
case 'code': {
// Track codeblock content in cursor for accurate character counting
cursor.offset += node.value.length;
// `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 fenceWord = diffLanguage ?? legacyLanguage;
// A listed language value claims its identifiers ahead of a built-in
// with the same identifier (component:Markdown FR30).
const language = listedLanguage(codeLanguages, fenceWord) ?? fenceWord;
// 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;
const fallback = CodeBlockComp ? (
<CodeBlockComp
key={index}
code={node.value}
// 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}
/>
) : (
<div
key={index}
{...mergeProps(
themeProps('markdown-codeblock', {density}),
stylex.props(
spacing,
styles.codeBlockWrapper,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}
{...lineStamps}>
<CodeBlock
code={node.value}
language={language}
isDiff={isDiff}
isCollapsible
// Long lines wrap rather than scroll sideways, as they do in
// RichText, so a reader sees whole lines and the read/edit switch
// moves no block (spec:AST-061 FR5, DEC-9).
isWrapped
xstyle={[
contentWidthValue != null
? dynamicStyles.blockWidth(contentWidthValue)
: undefined,
blockAlignStyle,
]}
/>
</div>
);
const proposal = getMarkdownFenceProposal(node);
if (proposal == null) {
return fallback;
}
const renderer = getMarkdownExtensionRenderer(
preparedPlugins,
proposal.node,
);
if (renderer == null) {
return fallback;
}
try {
const rendered = renderer.render({node: proposal.node});
// eslint-disable-next-line @astryx/no-nullish-jsx-guard -- a plugin renderer's '' is its output; only null, undefined or a boolean asks for the readable fallback
if (rendered == null || typeof rendered === 'boolean') {
return fallback;
}
return (
<MarkdownPluginBoundary
key={index}
pluginName={proposal.node.plugin}
resetKey={proposal.node}
resetRenderer={renderer.render}
fallback={fallback}>
<Suspense fallback={fallback}>{rendered}</Suspense>
</MarkdownPluginBoundary>
);
} catch (error) {
reportMarkdownPluginFailure(proposal.node.plugin, 'render', error);
return fallback;
}
}
case 'math': {
cursor.offset += node.value.length;
const MathComp = components?.math;
if (MathComp == null) {
return (
<div key={index} role="paragraph">
{`$$${node.value}$$`}
</div>
);
}
return (
<MathComp
key={index}
value={node.value}
display="block"
{...lineProp}
/>
);
}
case 'blockquote': {
const BlockquoteComp = components?.blockquote;
if (BlockquoteComp) {
const bqC = node.children.map((c, i) =>
renderBlock(
c,
i,
node.children.length,
density,
headingLevelStart,
onLinkClick,
cursor,
citationCtx,
contentWidthValue,
contentAlign,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
t,
codeLanguages,
headingProjection,
listDepth,
directionScope,
),
);
return (
<BlockquoteComp key={index} {...lineProp}>
{bqC}
</BlockquoteComp>
);
}
return (
<Blockquote
key={index}
dir={blockDirection(node, directionScope)}
{...themeProps('markdown-blockquote', {density})}
{...lineStamps}
xstyle={[
spacing,
contentWidthValue != null
? dynamicStyles.proseWidth(contentWidthValue)
: undefined,
contentAlign !== 'start'
? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
: undefined,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
]}>
{node.children.map((c, i) =>
renderBlock(
c,
i,
node.children.length,
density,
headingLevelStart,
onLinkClick,
cursor,
citationCtx,
contentWidthValue,
contentAlign,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
t,
codeLanguages,
headingProjection,
listDepth,
innerDirectionScope(node, directionScope),
),
)}
</Blockquote>
);
}
case 'list': {
// Preserve the released CheckboxList representation for paragraph-only
// pure task lists. Flow/nested task bodies use the shared per-item marker
// path below, which owns first-line placement and static outside paint.
const isTaskList =
node.children.length > 0 &&
node.children.every(
item =>
item.checked != null &&
item.children.every(block => block.type === 'paragraph'),
);
if (isTaskList) {
// Extract labels from task items — render as rich inline content
const checkedValues = node.children
.map((item, i) => ({item, key: `task-${i}`}))
.filter(({item}) => item.checked)
.map(({key}) => key);
return (
<div
key={index}
{...mergeProps(
themeProps('markdown-list', {density}),
stylex.props(
spacing,
contentWidthValue != null
? dynamicStyles.proseWidth(contentWidthValue)
: null,
contentAlign !== 'start'
? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
: null,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}>
<CheckboxList
label={t('@astryx.markdown.taskList')}
isLabelHidden
value={checkedValues}
containerXstyle={styles.blockIndent}
isReadOnly
density="compact">
{node.children.map((item, i) => {
const firstChild = item.children[0];
const isInline =
item.children.length === 1 &&
firstChild?.type === 'paragraph';
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
renderInline(
c,
j,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</>
) : (
<>
{item.children.map((c, j) =>
renderBlock(
c,
j,
item.children.length,
density,
headingLevelStart,
onLinkClick,
cursor,
citationCtx,
contentWidthValue,
contentAlign,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
t,
codeLanguages,
headingProjection,
listDepth + 1,
innerDirectionScope(item, directionScope),
),
)}
</>
);
return (
<CheckboxListItem
// eslint-disable-next-line @eslint-react/no-array-index-key -- markdown task items are rendered from positional AST nodes
key={i}
value={`task-${i}`}
label={label}
dir={blockDirection(item, directionScope)}
{...(recordsSourceLines
? sourceLineAttributes(blockSourceLines(item))
: undefined)}
/>
);
})}
</CheckboxList>
</div>
);
}
return (
<div
key={index}
{...mergeProps(
themeProps('markdown-list', {density}),
stylex.props(
spacing,
contentWidthValue != null
? dynamicStyles.proseWidth(contentWidthValue)
: null,
contentAlign !== 'start'
? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
: null,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}>
<List
listStyle={node.ordered ? 'decimal' : 'disc'}
density="compact"
start={node.ordered ? node.start : undefined}
xstyle={[styles.blockIndent, node.ordered && styles.markerGutter]}>
{node.children.map((item, i) => {
const firstChild = item.children[0];
const isInline =
item.children.length === 1 && firstChild?.type === 'paragraph';
// Check if this entire list item is "new" — if so, fade the
// whole item as a block instead of fading individual text spans.
const label = isInline ? (
<>
{firstChild.children.map((c, j) =>
renderInline(
c,
j,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</>
) : (
<>
{item.children.map((c, j) =>
renderBlock(
c,
j,
item.children.length,
density,
headingLevelStart,
onLinkClick,
cursor,
citationCtx,
contentWidthValue,
contentAlign,
linkComponent,
inlinePlugins,
components,
preparedPlugins,
t,
codeLanguages,
headingProjection,
listDepth + 1,
innerDirectionScope(item, directionScope),
),
)}
</>
);
// Each task item on this shared list path keeps its checked state
// (FR23): it shows a read-only checkbox where its marker
// would be, named by its text.
const firstParagraph = item.children.find(
block => block.type === 'paragraph',
);
const task =
item.checked == null
? undefined
: {
isChecked: item.checked,
label:
firstParagraph?.type === 'paragraph'
? markdownAstText(
firstParagraph.children,
extension =>
markdownExtensionText(
preparedPlugins,
extension,
),
)
: t('@astryx.markdown.taskList'),
};
const itemDirection = blockDirection(item, directionScope);
// A numbered item that reads against its list keeps its counter
// beside its own text, so its text never widens the counter
// column that the other rows share.
const readsAgainstList =
node.ordered &&
itemDirection != null &&
directionScope != null &&
itemDirection !== directionScope.around;
return (
<ListMarkerScope
// eslint-disable-next-line @eslint-react/no-array-index-key -- markdown list items are rendered from positional AST nodes
key={i}
marker={
(node.ordered ? NUMBER_MARKERS : BULLET_MARKERS)[
listDepth % 3
]
}
task={task}
hasMarkerGutter={node.ordered}
isOutsideNumberColumns={readsAgainstList}>
<ListItem
label={label}
dir={itemDirection}
{...(recordsSourceLines
? sourceLineAttributes(blockSourceLines(item))
: undefined)}
/>
</ListMarkerScope>
);
})}
</List>
</div>
);
}
case 'table': {
const colMinWidths = computeTableColumnMinWidths(node);
// A cell whose text reads against its table keeps the table's sides: the
// column rule and an explicit alignment resolve in the table's
// direction, not the cell's.
const readsAgainstTable = (
cell: Parameters<typeof blockDirection>[0],
): boolean => {
const cellDirection = blockDirection(cell, directionScope);
return (
cellDirection != null &&
directionScope != null &&
cellDirection !== directionScope.around
);
};
const [header, ...rows] = node.children;
// Inline code inside a cell keeps its token whole, through the same
// `components` seam consumers use. A supplied renderer owns its own
// wrapping and is left alone.
const cellComponents: Partial<MarkdownComponents> | undefined =
components?.inlineCode != null
? components
: {...components, inlineCode: MarkdownTableCellCode};
return (
<div
key={index}
// No role, name, or tab stop here: Table's Scroll region owns the
// table's horizontal overflow, its accessible name, and its
// conditional keyboard focusability. This block only carries
// spacing, sizing, and alignment.
{...mergeProps(
themeProps('markdown-table', {density}),
stylex.props(
styles.tableWrapper,
spacing,
contentWidthValue != null
? dynamicStyles.blockWidth(contentWidthValue)
: null,
BLOCK_ALIGN_MARGIN[contentAlign] != null
? dynamicStyles.blockAlign(BLOCK_ALIGN_MARGIN[contentAlign])
: null,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}
{...lineStamps}>
<Table
dividers="grid"
textOverflow="wrap"
xstyle={markdownTableCellStyles.tableOuterEdge}>
<TableHeader>
<TableRow>
{header?.children.map((h, i) => (
<TableHeaderCell
// eslint-disable-next-line @eslint-react/no-array-index-key -- markdown table columns are positional by definition
key={i}
dir={blockDirection(h, directionScope)}
xstyle={[
markdownTableCellStyles.headerCell,
dynamicStyles.cellMinWidth(`${colMinWidths[i]}ch`),
...tableCellSideStyles(
node.align[i],
readsAgainstTable(h),
),
]}>
{h.children.map((c, j) =>
renderInline(
c,
j,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
cellComponents,
preparedPlugins,
),
)}
</TableHeaderCell>
))}
</TableRow>
</TableHeader>
<TableBody>
{rows.map((row, i) => {
const cells = row.children.map((cell, j) => (
<TableCell
// eslint-disable-next-line @eslint-react/no-array-index-key -- markdown table cells are positional by row and column
key={j}
dir={blockDirection(cell, directionScope)}
xstyle={[
markdownTableCellStyles.cell,
...tableCellSideStyles(
node.align[j],
readsAgainstTable(cell),
),
]}>
{cell.children.map((c, k) =>
renderInline(
c,
k,
onLinkClick,
cursor,
citationCtx,
linkComponent,
inlinePlugins,
cellComponents,
preparedPlugins,
),
)}
</TableCell>
));
return (
<TableRow
// eslint-disable-next-line @eslint-react/no-array-index-key -- markdown table rows are rendered from positional AST nodes
key={i}>
{cells}
</TableRow>
);
})}
</TableBody>
</Table>
</div>
);
}
case 'extension': {
const content = renderMarkdownPluginNode(
preparedPlugins,
node,
wrapTextWithFade(
node.source ?? markdownExtensionText(preparedPlugins, node),
cursor,
index,
),
);
return (
<div
key={index}
{...stylex.props(
spacing,
contentWidthValue != null
? dynamicStyles.proseWidth(contentWidthValue)
: null,
contentAlign !== 'start'
? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
: null,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
)}>
{content}
</div>
);
}
case 'thematicBreak': {
const HrComp = components?.hr;
if (HrComp) {
return <HrComp key={index} {...lineProp} />;
}
return (
<hr
key={index}
{...mergeProps(
themeProps('markdown-hr', {density}),
stylex.props(
styles.hr,
spacing,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}
{...lineStamps}
/>
);
}
case 'image': {
const safeSrc = sanitizeMarkdownUrl(node.url);
if (safeSrc == null) {
return (
<div
key={index}
{...mergeProps(
themeProps('markdown-image', {density}),
stylex.props(
spacing,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}
{...lineStamps}>
[{node.alt}]
</div>
);
}
const ImageComp = components?.image;
if (ImageComp) {
return (
<ImageComp key={index} src={safeSrc} alt={node.alt} {...lineProp} />
);
}
return (
<div
key={index}
{...mergeProps(
themeProps('markdown-image', {density}),
stylex.props(
spacing,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
),
)}
{...lineStamps}>
<img src={safeSrc} alt={node.alt} {...stylex.props(styles.image)} />
</div>
);
}
}
}
// ---------------------------------------------------------------------------
// Component
// ---------------------------------------------------------------------------
/**
* Renders a markdown string as Astryx components. Supports streaming with
* smooth fade-in animation via isStreaming.
*
* @example
* ```
* <Markdown>
* {'# Hello\n\nThis is **bold** and _italic_ text.\n\n- Item one\n- Item two'}
* </Markdown>
* ```
*/
export function Markdown<
const Plugins extends ReadonlyArray<MarkdownPluginEntry> = readonly [],
>({
ref,
children,
display = 'block',
density = 'default',
headingLevelStart = 1,
isStreaming = false,
onLinkClick,
sources,
citationStyle = 'label',
contentWidth = 680,
contentAlign = 'start',
components,
plugins,
inlinePlugins,
autolink,
codeLanguages: codeLanguagesProp,
xstyle,
className,
style,
id: rootId,
'data-testid': testId,
...props
}: MarkdownProps<Plugins>): React.ReactElement {
const t = useComponentTranslator();
const direction = useDirection();
// Keep one list while it names the same values, so an inline
// `codeLanguages={[…]}` does not re-render every block on each parent
// render (adjusting state during render, not in an Effect).
const [codeLanguages, setCodeLanguages] = useState(codeLanguagesProp);
if (!sameCodeLanguageList(codeLanguages, codeLanguagesProp)) {
setCodeLanguages(codeLanguagesProp);
}
const LinkComponent = useLinkComponent();
// Links read the caller's handler when clicked, so a handler recreated on
// every caller render does not invalidate the memoized document below.
// Only whether a handler exists changes the rendered links.
const onLinkClickRef = useRef(onLinkClick);
useIsomorphicLayoutEffect(() => {
onLinkClickRef.current = onLinkClick;
});
const hasLinkClick = onLinkClick != null;
const stableOnLinkClick = useMemo<MarkdownProps['onLinkClick']>(
() =>
hasLinkClick
? (href, event) => onLinkClickRef.current?.(href, event)
: undefined,
[hasLinkClick],
);
// 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],
);
const preparedPlugins = useMemo(() => {
if (plugins == null) {
return undefined;
}
try {
return prepareMarkdownPlugins(plugins);
} catch (error) {
reportMarkdownPluginFailure('configuration', 'transform', error);
return undefined;
}
}, [plugins]);
const syntaxPlugins = useStableMarkdownSyntaxEntries(preparedPlugins);
const hasMathRenderer = components?.math != null;
const legacyParseOptions = useMemo<
ParseOptions<ReadonlyArray<MarkdownPluginEntry>>
>(
() => ({sourceIds, autolink, plugins: syntaxPlugins}),
[sourceIds, autolink, syntaxPlugins],
);
const mathParseOptions = useMemo<
MathParseOptions<ReadonlyArray<MarkdownPluginEntry>>
>(
() => ({sourceIds, autolink, math: true, plugins: syntaxPlugins}),
[sourceIds, autolink, syntaxPlugins],
);
// Smooth bursty streamed chunks into a steady character-by-character reveal.
// When not streaming, the hook returns children unchanged (no-op).
const smoothedText = useStreamingText(children, isStreaming);
const incrementalStateRef = useRef<IncrementalState<boolean>>(
createIncrementalState<boolean>(),
);
// Reset incremental cache when parser-affecting component options toggle —
// cached settled blocks were parsed with the previous setting.
const prevAutolinkRef = useRef(autolink);
const prevMathRef = useRef(hasMathRenderer);
if (
prevAutolinkRef.current !== autolink ||
prevMathRef.current !== hasMathRenderer
) {
incrementalStateRef.current = createIncrementalState<boolean>();
prevAutolinkRef.current = autolink;
prevMathRef.current = hasMathRenderer;
}
const parsedBlocks = useMemo(() => {
if (display === 'inline') {
return [];
}
if (isStreaming) {
if (smoothedText === '') {
incrementalStateRef.current = createIncrementalState<boolean>();
return [];
}
const options = hasMathRenderer ? mathParseOptions : legacyParseOptions;
const input = trimStreamingArtifacts(smoothedText, options);
return (
hasMathRenderer
? parseMarkdownAstIncremental(
input,
incrementalStateRef.current,
mathParseOptions,
)
: parseMarkdownAstIncremental(
input,
incrementalStateRef.current,
legacyParseOptions,
)
).children;
}
return (
hasMathRenderer
? parseMarkdownAst(children, mathParseOptions)
: parseMarkdownAst(children, legacyParseOptions)
).children;
}, [
display,
smoothedText,
children,
isStreaming,
hasMathRenderer,
mathParseOptions,
legacyParseOptions,
]);
const transformSource = isStreaming
? trimStreamingArtifacts(
smoothedText,
hasMathRenderer ? mathParseOptions : legacyParseOptions,
)
: children;
const blocks = useMemo(
() =>
applyMarkdownTransforms(
{type: 'root', children: parsedBlocks},
preparedPlugins,
transformSource,
!isStreaming,
'block',
).children,
[parsedBlocks, preparedPlugins, transformSource, isStreaming],
);
// Resolve one post-transform projection for Markdown and derived Outline.
// The default remains root-only; installed first-party modules own any
// alternative projection returned through this narrow integration seam.
const headingProjection = useMemo(() => {
if (display === 'inline' || blocks.length === 0) {
return undefined;
}
return projectMarkdownHeadings(
{type: 'root', children: blocks},
preparedPlugins,
);
}, [display, blocks, preparedPlugins]);
const parsedInlineNodes = useMemo(() => {
if (display !== 'inline') {
return [];
}
const options = hasMathRenderer ? mathParseOptions : legacyParseOptions;
const input = isStreaming
? trimStreamingArtifacts(smoothedText, options)
: children;
return hasMathRenderer
? parseInlineAst(input, mathParseOptions)
: parseInlineAst(input, legacyParseOptions);
}, [
display,
smoothedText,
children,
isStreaming,
hasMathRenderer,
mathParseOptions,
legacyParseOptions,
]);
const inlineTransformSource = isStreaming
? trimStreamingArtifacts(
smoothedText,
hasMathRenderer ? mathParseOptions : legacyParseOptions,
)
: children;
const inlineNodes = useMemo(() => {
if (display !== 'inline') {
return [];
}
const transformed = applyMarkdownTransforms(
{
type: 'root',
children: [{type: 'paragraph', children: parsedInlineNodes}],
},
preparedPlugins,
inlineTransformSource,
!isStreaming,
'inline',
);
const paragraph = transformed.children[0];
return paragraph?.type === 'paragraph'
? [...paragraph.children]
: parsedInlineNodes;
}, [
display,
parsedInlineNodes,
preparedPlugins,
inlineTransformSource,
isStreaming,
]);
// Track recent boundaries for stacked fade-in animation.
// The number of spans needed = ceil(animationDuration / tickInterval).
// useStreamingText ticks every ~tickMs, and the fade runs for
// --duration-fast-max. We compute the span count dynamically so the
// oldest span has just finished animating when it gets evicted.
const {token} = useTheme();
const maxSpans = useMemo(() => {
const duration = parseDuration(token('--duration-fast-max')) ?? 230;
const tick = parseDuration(token('--duration-fast-min'));
// Tick interval mirrors useStreamingText's timing: base / 10
const tickMs = tick != null ? Math.max(4, Math.round(tick / 10)) : 50;
return Math.min(Math.ceil(duration / tickMs), 12);
}, [token]);
const prevBlocksRef = useRef<ReadonlyArray<RenderBlockNode>>([]);
const prevInlineNodesRef = useRef<ReadonlyArray<RenderInlineNode>>([]);
const boundariesRef = useRef<number[]>([]);
const smoothedLen = smoothedText.length;
const boundaries = useMemo(() => {
void smoothedLen; // dep trigger
const prevLen =
display === 'inline'
? countInlineTextLength(prevInlineNodesRef.current)
: countBlockTextLength(prevBlocksRef.current);
const next = computeBoundaries(boundariesRef.current, prevLen, maxSpans);
boundariesRef.current = next;
return next;
}, [display, smoothedLen, maxSpans]);
const contentWidthValue = contentWidth
? typeof contentWidth === 'number'
? `${contentWidth}px`
: contentWidth
: null;
// The block document is the expensive part of a long Markdown render. It
// depends only on these inputs, so a caller re-render that changes none of
// them returns the same elements and React skips the whole subtree. The
// cursor and citation numbering are rebuilt inside, from the start of the
// document, exactly as a full render builds them.
const renderedBlocks = useMemo(() => {
if (display === 'inline') {
return null;
}
const blockCursor: StreamingCursor = {
offset: 0,
boundaries,
active: isStreaming,
};
// Numbers are assigned in encounter order during rendering.
const blockCitationCtx: CitationContext | null = sources
? {sources, numberMap: new Map(), nextNumber: 1, style: citationStyle}
: null;
return blocks.map((block, i) =>
renderBlock(
block,
i,
blocks.length,
density,
headingLevelStart,
stableOnLinkClick,
blockCursor,
blockCitationCtx,
contentWidthValue,
contentAlign,
LinkComponent,
inlinePlugins,
components,
preparedPlugins,
t,
codeLanguages,
headingProjection,
undefined,
{provider: direction, around: direction},
),
);
}, [
display,
blocks,
boundaries,
isStreaming,
sources,
citationStyle,
density,
headingLevelStart,
stableOnLinkClick,
contentWidthValue,
contentAlign,
LinkComponent,
inlinePlugins,
components,
preparedPlugins,
t,
headingProjection,
codeLanguages,
direction,
]);
if (display === 'inline') {
const cursor: StreamingCursor = {
offset: 0,
boundaries,
active: isStreaming,
};
// Numbers are assigned in encounter order during rendering.
const citationCtx: CitationContext | null = sources
? {sources, numberMap: new Map(), nextNumber: 1, style: citationStyle}
: null;
const renderedInline = (
<span
ref={ref}
// Consumer props first: what the component sets for itself wins.
{...props}
id={rootId}
data-testid={testId}
{...mergeProps(
themeProps('markdown', {density}),
stylex.props(styles.root, styles.inlineRoot, xstyle),
className,
style,
)}>
{inlineNodes.map((node, i) =>
renderInline(
node,
i,
stableOnLinkClick,
cursor,
citationCtx,
LinkComponent,
inlinePlugins,
components,
preparedPlugins,
),
)}
</span>
);
// Store current inline nodes for next render's boundary calculation.
prevInlineNodesRef.current = inlineNodes;
prevBlocksRef.current = [];
return renderedInline;
}
const rendered = (
<div
ref={ref as React.Ref<HTMLDivElement>}
// Consumer props first: what the component sets for itself — the
// document role included — wins.
{...props}
id={rootId}
role="document"
data-testid={testId}
{...mergeProps(
themeProps('markdown', {density}),
stylex.props(styles.root, xstyle),
className,
style,
)}>
{renderedBlocks}
</div>
);
// Store current blocks for next render's boundary calculation.
// This ref write is safe under StrictMode: both invocations produce the same
// blocks (same smoothedText → same useMemo result), so both write the same value.
prevBlocksRef.current = blocks;
prevInlineNodesRef.current = [];
return rendered;
}
Markdown.displayName = 'Markdown';