An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file CodeBlock.tsx
* @input Uses React, StyleX, theme tokens, CSS Custom Highlight API, SyntaxTheme
* provider, and the theme's `code-block-copy` icon slot
* @output Exports CodeBlock component and CodeBlockProps
* @position Core implementation; read-only syntax-highlighted code display
*/
import {
useInsertionEffect,
useEffect,
useId,
useRef,
useState,
useCallback,
useMemo,
type CSSProperties,
} from 'react';
import * as React from 'react';
import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
radiusVars,
typographyVars,
fontWeightVars,
typeScaleVars,
borderVars,
durationVars,
easeVars,
focusVars,
} from '../theme/tokens.stylex';
import {isRenderable, mergeProps, rtlStyles} from '../utils';
import {useClipboardCopy} from '../hooks/useClipboard';
import {useScrollableArea} from '../hooks/useScrollableArea';
import {Icon} from '../Icon';
import {ComponentIcon} from '../Icon/ComponentIcon';
import {IconButton} from '../IconButton';
import type {DiffLineKind} from './tokenizer';
import {
tokenize,
tokenizeAsync,
splitDiffLines,
flatTokensToLines,
SYNC_TOKENIZE_THRESHOLD,
} from './tokenizer';
import type {CodeLanguageInput, SyntaxToken, TokenLine} from './tokenizer';
import type {CodeLanguage} from './grammar';
import {
isCustomCodeLanguage,
languageKey,
languageLabel as languageWord,
sameCodeLanguage,
} from './grammar';
import {ensureHighlightStyles} from './highlightStyles';
import {applyHighlightRangesChunked} from './highlightRanges';
import {themeProps} from '../utils/themeProps';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {SyntaxTheme, type SyntaxThemeDefinition} from '../theme/syntax';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/CodeBlock/CodeBlock.generated';
registerEnglishFallback(english);
// ---------------------------------------------------------------------------
// Styles
// ---------------------------------------------------------------------------
const containerStyles = stylex.create({
card: {
borderRadius: radiusVars['--radius-element'],
borderWidth: borderVars['--border-width'],
borderStyle: 'solid',
borderColor: colorVars['--color-border'],
},
section: {
borderRadius: 0,
borderWidth: 0,
borderStyle: 'none',
borderColor: 'transparent',
// Transparent background so the block blends into the surface it's
// embedded in (a card or panel) instead of painting its own muted layer,
// which would compound with a muted parent into a darker grey. Override
// the syntax-background var so both the root and the sticky header inherit
// it. Consumers can still set an explicit background via xstyle.
'--color-syntax-background': 'transparent',
},
});
const dynamicStyles = stylex.create({
width: (value: string) => ({
width: value,
minWidth: value === 'fit-content' ? 'min(100%, 400px)' : null,
maxWidth: value === 'fit-content' ? '100%' : null,
}),
// Width of the line-number column, sized to the widest number. `ch` is the
// advance of "0" in the (monospace) code font, so N digits => N ch. Set on
// <code>; `--_codeblock-gutter-width` is unregistered so it inherits (with its var()
// substituted) down to the line divs that read it for their grid track.
gutterWidth: (digits: number) => ({
'--_codeblock-gutter-width': `${digits}ch`,
}),
});
// Light reveal so the leading chevron eases into view instead of popping in.
// Growing the chevron's own footprint (width + inline margin) from zero slides
// the title into place instead of snapping it over, and clipping keeps the
// glyph from spilling while it's mid-reveal.
const chevronReveal = stylex.keyframes({
from: {
width: 0,
marginInlineEnd: 0,
opacity: 0,
},
to: {
width: '14px',
marginInlineEnd: spacingVars['--spacing-1'],
opacity: 1,
},
});
const styles = stylex.create({
root: {
position: 'relative',
isolation: 'isolate',
display: 'flex',
flexDirection: 'column',
margin: 0,
backgroundColor: 'var(--color-syntax-background)',
overflow: 'hidden',
},
// The viewport is a flex item of the column root. Its implied min-height
// would be its content while it fits (the shared capability keeps it
// `overflow: clip` then), so a root sized from outside could never make it
// shrink and scroll; 0 lets the root's bound reach it.
viewport: {
minHeight: 0,
},
// The root clips (overflow: hidden, for its corners), so the viewport's
// keyboard ring sits inside its own box instead of around it.
viewportFocusRingInset: {
outlineOffset: {
default: null,
':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
},
},
// With no header, Copy sits in its own inline-end column beside the code
// viewport rather than over it, so no line, scrolled or wrapped, runs under
// the button. The column is as wide as its content; the single row still
// lets a root sized from outside bound the viewport.
rootCorner: {
display: 'grid',
gridTemplateColumns: 'minmax(0, 1fr) auto',
gridTemplateRows: 'minmax(0, 1fr)',
},
headerRow: {
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
paddingInline: spacingVars['--spacing-4'],
backgroundColor: 'var(--color-syntax-background)',
position: 'sticky',
top: 0,
zIndex: 1,
},
header: {
display: 'flex',
alignItems: 'center',
flex: 1,
minWidth: 0,
// Reset default <button> appearance for the collapsible title control.
padding: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
color: 'inherit',
font: 'inherit',
textAlign: 'start',
},
headerWithDivider: {
paddingBlock: spacingVars['--spacing-2'],
borderBottomWidth: borderVars['--border-width'],
borderBottomStyle: 'solid',
borderBottomColor: colorVars['--color-border'],
},
headerCompact: {
paddingBlock: spacingVars['--spacing-2'],
},
headerTitle: {
display: 'flex',
alignItems: 'center',
fontSize: typeScaleVars['--text-supporting-size'],
fontFamily: typographyVars['--font-family-code'],
fontWeight: fontWeightVars['--font-weight-medium'],
color: 'var(--color-syntax-comment)',
margin: 0,
lineHeight: typeScaleVars['--text-supporting-leading'],
},
codeWrapper: {
display: 'flex',
minWidth: 'fit-content',
},
codeWrapperCompact: {
marginBlockStart: `calc(-1 * ${spacingVars['--spacing-2']})`,
},
collapseGrid: {
display: 'grid',
gridTemplateRows: '1fr',
transitionProperty: 'grid-template-rows',
transitionDuration: durationVars['--duration-medium'],
transitionTimingFunction: easeVars['--ease-standard'],
},
collapseGridCollapsed: {
gridTemplateRows: '0fr',
},
collapseInner: {
overflow: 'hidden',
minHeight: 0,
},
collapseChevron: {
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
width: '14px',
height: '14px',
marginInlineEnd: spacingVars['--spacing-1'],
overflow: 'hidden',
color: 'var(--color-syntax-comment)',
animationName: {
default: chevronReveal,
'@media (prefers-reduced-motion: reduce)': 'none',
},
animationDuration: durationVars['--duration-medium'],
animationTimingFunction: easeVars['--ease-standard'],
},
// Applied to the chevron <Icon> (via `xstyle`): the glyph is the element that
// rotates and the element a theme targets, so one selector reaches both.
collapseChevronIcon: {
transitionProperty: 'transform',
transitionDuration: durationVars['--duration-fast'],
transitionTimingFunction: easeVars['--ease-standard'],
},
collapseChevronExpanded: {
// Leading disclosure convention (matches TreeList/Table): the resting
// chevronRight points right (>) when collapsed; rotate it down (v) when
// expanded.
transform: 'rotate(90deg)',
},
headerCollapsible: {
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
userSelect: 'none',
// Restore a keyboard-only focus ring with the standard token/offset so this
// disclosure control matches the rest of the system (Collapsible, TabMenu);
// otherwise it falls back to the inconsistent UA default outline.
},
code: {
display: 'block',
flex: 1,
// The block grows to its longest line, so a row's paint (diff tint,
// highlightLines) spans the full scroll width instead of stopping at the
// viewport edge when the reader scrolls a long line.
minWidth: 'max-content',
paddingBlock: spacingVars['--spacing-3'],
paddingInline: spacingVars['--spacing-4'],
margin: 0,
fontFamily: typographyVars['--font-family-code'],
color: 'var(--color-syntax-variable)',
tabSize: 2,
whiteSpace: 'pre',
wordBreak: 'normal',
overflowWrap: 'normal',
},
codeWrapped: {
// Wrapped lines never overflow, and max-content would stop them wrapping.
minWidth: 'auto',
whiteSpace: 'pre-wrap',
wordBreak: 'break-all',
overflowWrap: 'break-word',
},
// With line numbers on, the <code> element hosts the full-height divider
// between the number gutter and the code. It spans the code's block padding
// too (inset-block: 0), so the rule reaches the top and bottom edges the way
// the old separate gutter column did. The numbers themselves are drawn per
// line (see `lineNumbered`) — a separate column can't track wrap height.
codeNumbered: {
position: 'relative',
'::after': {
content: '""',
position: 'absolute',
insetBlock: 0,
insetInlineStart: `calc(${spacingVars['--spacing-4']} + var(--_codeblock-gutter-width) + ${spacingVars['--spacing-3']})`,
width: 0,
borderInlineStartWidth: borderVars['--border-width'],
borderInlineStartStyle: 'solid',
borderInlineStartColor: colorVars['--color-border'],
pointerEvents: 'none',
},
},
line: {
lineHeight: typeScaleVars['--text-code-leading'],
},
// Per-line number gutter: a two-column grid ([number] [code]). The number is
// a ::before generated from the data-line attribute. Because the number and
// its code occupy one grid row, the row grows to fit wrapped code while the
// number stays pinned to the row's first visual line (alignSelf: start) —
// this is what keeps numbers aligned when isWrapped wraps a line.
lineNumbered: {
display: 'grid',
gridTemplateColumns: 'var(--_codeblock-gutter-width) 1fr',
columnGap: `calc(${spacingVars['--spacing-3']} + ${borderVars['--border-width']} + ${spacingVars['--spacing-4']})`,
'::before': {
content: 'attr(data-line)',
gridColumn: '1',
alignSelf: 'start',
textAlign: 'end',
color: 'var(--color-syntax-punctuation)',
userSelect: 'none',
fontFamily: typographyVars['--font-family-code'],
},
},
// In span mode the tokens are wrapped in this element so they form a single
// grid item in column 2 (otherwise each token span would flow into its own
// grid cell). minWidth:0 lets it shrink so long lines wrap within the track.
lineContent: {
minWidth: 0,
},
lineChunk: {
contentVisibility: 'auto',
},
lineHighlighted: {
backgroundColor: colorVars['--color-accent-muted'],
marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,
paddingInline: spacingVars['--spacing-4'],
},
// Diff change rows: the whole row is tinted so added and removed lines read
// at a glance; the text keeps its ordinary colour, which stays readable on
// the tint where the semantic text colours would not, and the leading +/-
// glyph stays in the text as the cue that needs no colour. A caller's
// highlightLines row is declared after these and keeps its background.
// A changed row's margin reads the change: the tint runs under the gutter
// cell too (the row spans the full width), and the line number and the
// glyph take the row's marker slot. The code — tokens and plain runs alike
// — keeps the syntax theme's colours, so an identifier looks the same on a
// changed row as on a context row.
lineAdded: {
backgroundColor: 'var(--color-syntax-added)',
marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,
paddingInline: spacingVars['--spacing-4'],
'::before': {color: 'var(--color-syntax-added-marker)'},
},
lineRemoved: {
backgroundColor: 'var(--color-syntax-removed)',
marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,
paddingInline: spacingVars['--spacing-4'],
'::before': {color: 'var(--color-syntax-removed-marker)'},
},
// Hunk and file headers stay visible but quiet: a muted row with secondary
// text, never change paint.
lineDiffHeader: {
backgroundColor: 'var(--color-syntax-diff-header)',
// The syntax theme's own secondary colour: text-secondary in the default
// theme, the theme's punctuation colour in a defined one.
color: 'var(--color-syntax-punctuation)',
marginInline: `calc(-1 * ${spacingVars['--spacing-4']})`,
paddingInline: spacingVars['--spacing-4'],
},
// The glyph column: the +, - or space of every line sits in its own track
// before the code, so the code column starts at the same inline offset on
// every line and the content's indentation reads exactly as written. The
// glyph is laid out as text but not selectable; the copy button still
// copies the original source with its glyphs.
lineDiff: {
display: 'grid',
gridTemplateColumns: '1ch 1fr',
columnGap: spacingVars['--spacing-2'],
},
// With line numbers the gutter's gap (which the full-height divider sits
// in) has to stay between the number and the marker, so the grid has no
// gap of its own and the marker carries both gaps as margins.
lineDiffNumbered: {
// `auto`, not `1ch`: the marker's gap margins have to widen its track.
gridTemplateColumns: 'var(--_codeblock-gutter-width) auto 1fr',
columnGap: 0,
},
// The glyph is the source's own text: read by assistive technology, kept
// out of a drag selection (copy returns the exact source anyway).
diffMarker: {
color: colorVars['--color-text-secondary'],
userSelect: 'none',
whiteSpace: 'pre',
},
diffMarkerNumbered: {
marginInlineStart: `calc(${spacingVars['--spacing-3']} + ${borderVars['--border-width']} + ${spacingVars['--spacing-4']})`,
marginInlineEnd: spacingVars['--spacing-2'],
},
// On a tinted row the glyph is the cue a reader without colour depends on,
// so it takes the row's marker slot like the line number does.
diffMarkerAdded: {
color: 'var(--color-syntax-added-marker)',
},
diffMarkerRemoved: {
color: 'var(--color-syntax-removed-marker)',
},
sizeSm: {
fontSize: typeScaleVars['--text-supporting-size'],
},
sizeMd: {
fontSize: typeScaleVars['--text-code-size'],
},
copyButton: {
// The copy control is a ghost IconButton (Button owns its own padding,
// radius, and hover surface); this only tints the resting glyph to the
// muted syntax-comment colour so it blends into the header/corner. A theme
// reaches it via the `code-block-copy-button` target on the Button.
color: 'var(--color-syntax-comment)',
},
// The controls of a headerless block: caller controls, then Copy, in the
// second column (cornerClusterMd/Sm give its height).
cornerCluster: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-1'],
alignSelf: 'start',
marginInline: spacingVars['--spacing-2'],
},
// The header's controls: caller controls, then Copy.
headerControls: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-1'],
flexShrink: 0,
},
// The cluster is exactly as tall as the first line's row (its block padding
// on both sides plus its line box), and centres its controls in it, so any
// control height sits on the first line: a one-line block reads as one row
// with even space above and below, and a block that grows keeps its
// controls where they were.
cornerClusterMd: {
blockSize: `calc(2 * ${spacingVars['--spacing-3']} + ${typeScaleVars['--text-code-size']} * ${typeScaleVars['--text-code-leading']})`,
},
cornerClusterSm: {
blockSize: `calc(2 * ${spacingVars['--spacing-3']} + ${typeScaleVars['--text-supporting-size']} * ${typeScaleVars['--text-code-leading']})`,
},
});
// ---------------------------------------------------------------------------
// Line rendering
// ---------------------------------------------------------------------------
const LINE_CHUNK_SIZE = 20;
const LINE_CHUNK_THRESHOLD = 100;
/**
* Memoized chunk component — cheaper than memoizing every individual line.
*/
const CodeChunk = React.memo(function CodeChunk({
lines,
startIndex,
startLineNumber,
highlightSet,
diffKinds,
renderLineContent,
lineNumbers,
}: {
lines: string[];
startIndex: number;
startLineNumber: number;
highlightSet: Set<number> | null;
diffKinds: ReadonlyArray<DiffLineKind> | null;
renderLineContent: (line: string, lineIndex: number) => React.ReactNode;
lineNumbers: boolean;
}) {
return (
<>
{lines.map((line, j) => {
const i = startIndex + j;
const lineNumber = startLineNumber + i;
const diffKind = diffKinds?.[i];
return (
<div
key={i}
data-line={lineNumber}
data-diff={diffKind === 'context' ? undefined : diffKind}
{...stylex.props(
styles.line,
lineNumbers && styles.lineNumbered,
diffKinds != null && styles.lineDiff,
diffKinds != null && lineNumbers && styles.lineDiffNumbered,
diffKind === 'added' && styles.lineAdded,
diffKind === 'removed' && styles.lineRemoved,
diffKind === 'header' && styles.lineDiffHeader,
// Last on purpose: a highlight replaces a diff tint rather than
// stacking on it, so tokens keep their single-paint contrast.
(highlightSet?.has(lineNumber) ?? false) &&
styles.lineHighlighted,
)}>
{renderLineContent(line, i)}
</div>
);
})}
</>
);
});
function renderLines(
lines: string[],
highlightSet: Set<number> | null,
diffKinds: ReadonlyArray<DiffLineKind> | null,
renderLineContent: (line: string, lineIndex: number) => React.ReactNode,
lineNumbers: boolean,
startLineNumber: number,
chunkSize: number = LINE_CHUNK_SIZE,
): React.ReactNode {
chunkSize = Math.max(1, Math.floor(chunkSize));
if (lines.length < LINE_CHUNK_THRESHOLD) {
return (
<CodeChunk
lines={lines}
startIndex={0}
startLineNumber={startLineNumber}
highlightSet={highlightSet}
diffKinds={diffKinds}
renderLineContent={renderLineContent}
lineNumbers={lineNumbers}
/>
);
}
const chunks: React.ReactNode[] = [];
for (let start = 0; start < lines.length; start += chunkSize) {
const end = Math.min(start + chunkSize, lines.length);
const chunkLines = lines.slice(start, end);
const estimatedHeight = `${chunkLines.length}lh`;
chunks.push(
<div
key={start}
{...mergeProps(stylex.props(styles.lineChunk), {
style: {containIntrinsicBlockSize: `auto ${estimatedHeight}`},
})}>
<CodeChunk
lines={chunkLines}
startIndex={start}
startLineNumber={startLineNumber}
highlightSet={highlightSet}
diffKinds={diffKinds}
renderLineContent={renderLineContent}
lineNumbers={lineNumbers}
/>
</div>,
);
}
return chunks;
}
// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------
export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
ref?: React.Ref<HTMLPreElement>;
code: string;
/**
* The code's language: a built-in identifier such as `'rust'`, or a
* language value — a module imported on its own, such as `graphql` from
* `@astryxdesign/core/CodeBlock/languages/graphql`, or one made with
* `createCodeLanguage`. A string selects only a built-in grammar; the label
* shows the string, or the value's `name`.
* @default 'plaintext'
*/
language?: string | CodeLanguage;
title?: string;
hasLanguageLabel?: boolean;
hasLineNumbers?: boolean;
/**
* First line's number in the source file. The gutter shows file
* coordinates (`startLineNumber + index`) instead of starting at 1, so a
* code excerpt reads with its real line numbers. `highlightLines` uses the
* same file coordinates. Values below 1 clamp to 1.
* @default 1
*/
startLineNumber?: number;
/** 1-indexed line numbers to highlight, in the same file coordinates as the gutter (see `startLineNumber`). Out-of-range entries render no highlight. */
highlightLines?: number[];
/**
* Render the code as a unified diff over `language`: lines starting with
* `+` are added, `-` removed, `@@` is a hunk header (a `--- `/`+++ ` pair
* directly before one is a file header), anything else is context; the
* label reads `diff` or `<language> diff`. The glyph sits in its own column and the rest of every line
* keeps the language's syntax highlighting. Copy still returns the exact
* source, glyphs included.
*/
isDiff?: boolean;
hasCopyButton?: boolean;
onCopy?: () => void;
/**
* Called once with the rejection when the clipboard write fails. The copy
* control then shows a cross and is named and announced as the localized
* "Failed to copy value to clipboard."; the error itself is not shown.
*/
onCopyError?: (error: unknown) => void;
/**
* Your own controls, shown just before Copy: in the header when the block
* has one, otherwise beside the code in the top inline-end corner, never
* over it. It never creates a header, and activating it never collapses the
* block. You own each control's label, state, and action; ghost `sm`
* IconButtons match Copy's size and variant.
*/
endContent?: React.ReactNode;
isWrapped?: boolean;
maxHeight?: number | string;
isCollapsible?: boolean;
collapsibleThreshold?: number;
size?: 'sm' | 'md';
/**
* Width of the code block. Accepts any CSS width value.
* - `'fit-content'` (default): shrinks to the width of the longest line (with a min-width floor).
* - `'100%'`: stretches to fill the parent container width.
* - Any valid CSS width string (e.g. `'600px'`, `'50vw'`).
* @default 'fit-content'
*/
width?: string;
/**
* Container presentation style.
* - `'card'` (default): border-radius and border with the muted syntax
* background — standalone card look.
* - `'section'`: no border-radius, no border, and a transparent background
* so the block blends into the card or panel it's embedded in. Set an
* explicit background via `xstyle` if you need one.
* @default 'card'
*/
container?: 'card' | 'section';
/**
* @deprecated Pass a custom language as `language` instead:
* `language={createCodeLanguage({name, identifiers, tokenize})}` takes this
* same function as `tokenize`. Still works exactly as released and wins
* over `language`'s grammar; `astryx upgrade` rewrites static uses.
*/
tokenizer?: (
code: string,
language: string,
) => {type: string; start: number; end: number}[];
highlightMode?: 'auto' | 'ranges' | 'spans';
/**
* Per-instance syntax theme override. Shorthand for wrapping this block in
* `<SyntaxTheme theme={...}>` — accepts a preset from
* `@astryxdesign/core/theme/syntax` or a theme created with
* `defineSyntaxTheme()`. Without it, the block uses the theme-level syntax
* colors from the nearest SyntaxTheme ancestor or `defineTheme({ syntax })`.
*/
syntaxTheme?: SyntaxThemeDefinition;
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
function hasHighlightAPI(): boolean {
return (
typeof CSS !== 'undefined' &&
'highlights' in CSS &&
typeof Highlight !== 'undefined'
);
}
/**
* Safari supports the Highlight API JS objects but has rendering issues
* with ::highlight() in code blocks. Detect Safari (WebKit without Chrome)
* so we can fall back to spans.
*/
function isSafari(): boolean {
if (typeof navigator === 'undefined') {
return false;
}
const ua = navigator.userAgent;
return ua.includes('AppleWebKit') && !ua.includes('Chrome');
}
/**
* Hook: per-line tokens with sync/async + custom tokenizer compat.
*/
function useTokenLines(
code: string,
languageProp: CodeLanguageInput,
customTokenizer?: CodeBlockProps['tokenizer'],
): TokenLine[] {
// Keep one language while it paints the same, so an inline
// `createCodeLanguage({...})` — the form the `tokenizer` codemod writes —
// tokenizes once, as `tokenizer` did (adjusting state during render).
const [language, setLanguage] = useState(languageProp);
if (!sameCodeLanguage(language, languageProp)) {
setLanguage(languageProp);
}
const [asyncTokenResult, setAsyncTokenResult] = useState<{
code: string;
language: CodeLanguageInput;
tokens: TokenLine[];
} | null>(null);
const syncTokens = useMemo(() => {
if (customTokenizer) {
return flatTokensToLines(
customTokenizer(code, languageWord(language)),
code,
);
}
// A custom language paints synchronously at any length, as `tokenizer`
// does, so the codemod's rewrite keeps the same first paint (FR13).
if (
code.length >= SYNC_TOKENIZE_THRESHOLD &&
!isCustomCodeLanguage(language)
) {
return null;
}
return tokenize(code, language);
}, [code, language, customTokenizer]);
// Synchronizes long code with a scheduler-yielding tokenize task: it starts
// when the code, language, or tokenizer changes, and the
// cleanup aborts the previous one.
useEffect(() => {
if (
code.length < SYNC_TOKENIZE_THRESHOLD ||
customTokenizer ||
isCustomCodeLanguage(language)
) {
return;
}
const abortController = new AbortController();
async function tokenizeLargeCode() {
try {
const tokens = await tokenizeAsync(
code,
language,
abortController.signal,
);
if (!abortController.signal.aborted) {
setAsyncTokenResult({code, language, tokens});
}
} catch {
if (!abortController.signal.aborted) {
setAsyncTokenResult({code, language, tokens: []});
}
}
}
void tokenizeLargeCode();
return () => {
abortController.abort();
};
}, [code, language, customTokenizer]);
if (syncTokens != null) {
return syncTokens;
}
if (
asyncTokenResult?.code === code &&
asyncTokenResult.language === language
) {
return asyncTokenResult.tokens;
}
return [];
}
// ---------------------------------------------------------------------------
// Span-mode code element
// ---------------------------------------------------------------------------
function buildSpanLine(
lineText: string,
tokens: SyntaxToken[],
): React.ReactNode {
if (tokens.length === 0) {
return lineText || '\u200b';
}
const parts: React.ReactNode[] = [];
let cursor = 0;
for (const token of tokens) {
if (token.start > cursor) {
parts.push(lineText.slice(cursor, token.start));
}
const end = Math.min(token.end, lineText.length);
parts.push(
<span
key={`${token.start}-${token.type}`}
className={`astryx-token-${token.type} xds-token-${token.type}`}>
{lineText.slice(token.start, end)}
</span>,
);
cursor = end;
}
if (cursor < lineText.length) {
parts.push(lineText.slice(cursor));
}
return parts.length > 0 ? parts : '\u200b';
}
function SpanCodeContent({
lines,
tokenLines,
highlightSet,
diffKinds,
diff,
isWrapped,
sizeStyle,
hasLineNumbers,
maxDigits,
startLineNumber,
}: {
lines: string[];
tokenLines: TokenLine[];
highlightSet: Set<number> | null;
diffKinds: ReadonlyArray<DiffLineKind> | null;
diff: ReturnType<typeof splitDiffLines> | null;
isWrapped: boolean;
sizeStyle: stylex.StyleXStyles;
hasLineNumbers: boolean;
maxDigits: number;
startLineNumber: number;
}) {
// Syncs the document's ::highlight() stylesheet. The rules go in one time,
// before layout reads.
useInsertionEffect(() => {
ensureHighlightStyles();
}, []);
const renderLineContent = useCallback(
(line: string, lineIndex: number): React.ReactNode => {
const tokens = tokenLines[lineIndex] ?? [];
if (diff) {
// Header rows show their raw text; every other row shows its glyph in
// the marker column and the base-language tokens of the rest.
const kind = diff.kinds[lineIndex];
const content = kind === 'header' ? line : diff.content[lineIndex];
return (
<>
<span
data-diff-marker=""
{...stylex.props(
styles.diffMarker,
hasLineNumbers && styles.diffMarkerNumbered,
kind === 'added' && styles.diffMarkerAdded,
kind === 'removed' && styles.diffMarkerRemoved,
)}>
{diff.glyphs[lineIndex] || ' '}
</span>
<span {...stylex.props(styles.lineContent)}>
{kind === 'header'
? content || '\u200b'
: buildSpanLine(content, tokens)}
</span>
</>
);
}
// Wrap tokens in a single element so they occupy one grid cell when line
// numbers are on (see `lineNumbered`); an inline span is a no-op when off.
return (
<span {...stylex.props(styles.lineContent)}>
{buildSpanLine(line, tokens)}
</span>
);
},
[tokenLines, diff, hasLineNumbers],
);
return (
<code
{...stylex.props(
styles.code,
sizeStyle,
isWrapped && styles.codeWrapped,
hasLineNumbers && styles.codeNumbered,
hasLineNumbers && dynamicStyles.gutterWidth(maxDigits),
)}>
{renderLines(
lines,
highlightSet,
diffKinds,
renderLineContent,
hasLineNumbers,
startLineNumber,
)}
</code>
);
}
// ---------------------------------------------------------------------------
// Range-mode code element
// ---------------------------------------------------------------------------
function RangeCodeContent({
lines,
tokenLines,
highlightSet,
diffKinds,
isWrapped,
sizeStyle,
hasLineNumbers,
maxDigits,
startLineNumber,
}: {
lines: string[];
tokenLines: TokenLine[];
highlightSet: Set<number> | null;
diffKinds: ReadonlyArray<DiffLineKind> | null;
isWrapped: boolean;
sizeStyle: stylex.StyleXStyles;
hasLineNumbers: boolean;
maxDigits: number;
startLineNumber: number;
}) {
const codeRef = useRef<HTMLElement>(null);
// Insert the ::highlight() rules before the commit's layout reads, as the
// span path does. Inserted later, the new rules restyle the whole document
// a second time after any layout read in the same commit has already
// styled it, which on a long page full of code blocks costs a full style
// recalculation.
useInsertionEffect(() => {
if (hasHighlightAPI()) {
ensureHighlightStyles();
}
}, []);
// Syncs the CSS.highlights registry with the token ranges. It applies them in
// chunks.
useEffect(() => {
if (!hasHighlightAPI()) {
return;
}
const codeEl = codeRef.current;
if (!codeEl || tokenLines.length === 0) {
return;
}
return applyHighlightRangesChunked(codeEl, tokenLines);
}, [tokenLines]);
// Range mode keeps the line's text as a bare text node (its firstChild) so
// applyHighlightRangesChunked can map token offsets onto it \u2014 no wrapper. The
// number ::before is a pseudo-element, so it never becomes a child node here.
const renderLineContent = useCallback(
(line: string): React.ReactNode => line || '\u200b',
[],
);
return (
<code
ref={codeRef}
{...stylex.props(
styles.code,
sizeStyle,
isWrapped && styles.codeWrapped,
hasLineNumbers && styles.codeNumbered,
hasLineNumbers && dynamicStyles.gutterWidth(maxDigits),
)}>
{renderLines(
lines,
highlightSet,
diffKinds,
renderLineContent,
hasLineNumbers,
startLineNumber,
)}
</code>
);
}
// ---------------------------------------------------------------------------
// Main component
// ---------------------------------------------------------------------------
/**
* Read-only code display with syntax highlighting, line numbers,
* and optional copy button.
*
* @example
* ```
* <CodeBlock code="const x = 42;" language="javascript" />
* ```
*/
export function CodeBlock({
code,
language = 'plaintext',
title,
hasLanguageLabel = true,
hasLineNumbers = false,
startLineNumber = 1,
highlightLines,
isDiff = false,
hasCopyButton = true,
onCopy,
onCopyError,
endContent,
isWrapped = false,
maxHeight,
isCollapsible = false,
collapsibleThreshold = 10,
size = 'md',
width: widthProp = 'fit-content',
container = 'card',
tokenizer: customTokenizer,
highlightMode = 'auto',
syntaxTheme,
xstyle,
className,
style,
ref,
...props
}: CodeBlockProps) {
const t = useComponentTranslator();
// Owns the clipboard write, the transient copied flag, its reset timer, and
// the polite copy announcement (a swapped aria-label alone is not reliably
// announced) — shared with Timestamp via the same hook.
// A failed write shows a cross for as long as a copy shows the check, and
// is named and announced as the localized failure (Owner decision, Nov 6
// 2026). The error itself goes only to `onCopyError`.
const {
copy,
isCopied: copied,
isFailed: copyFailed,
} = useClipboardCopy({
announce: t('@astryx.codeBlock.copied'),
announceFailure: t('@astryx.codeBlock.copyFailed'),
onError: onCopyError,
});
const useSpans =
isDiff ||
highlightMode === 'spans' ||
(highlightMode === 'auto' && !hasHighlightAPI()) ||
(highlightMode === 'auto' && isSafari());
const lines = useMemo(() => {
const l = code.split('\n');
if (l.length > 1 && l[l.length - 1] === '') {
l.pop();
}
return l;
}, [code]);
// In diff mode the base language sees the code with the glyph column set
// aside, so a `tsx` diff still highlights as `tsx` on every line; headers
// contribute an empty line and are rendered as their raw text.
const diff = useMemo(
() => (isDiff ? splitDiffLines(lines) : null),
[isDiff, lines],
);
const tokenLines = useTokenLines(
diff ? diff.content.join('\n') : code,
language,
customTokenizer,
);
const diffKinds = diff?.kinds ?? null;
// File coordinates for the gutter and highlights. Values below 1 clamp to
// 1 so the gutter never shows a 0 or negative line number.
const effectiveStartLineNumber =
Number.isFinite(startLineNumber) && startLineNumber > 1
? Math.floor(startLineNumber)
: 1;
const highlightSet = useMemo(
() => (highlightLines ? new Set(highlightLines) : null),
[highlightLines],
);
const handleCopy = useCallback(async () => {
const didCopy = await copy(code);
if (didCopy) {
onCopy?.();
}
}, [code, copy, onCopy]);
const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
// Digits in the largest visible line number — sizes the gutter column width.
const maxLineDigits = String(
effectiveStartLineNumber + lines.length - 1,
).length;
// With the diff layer on, the label and viewport name say so: `diff` over
// plaintext, `tsx diff` over a language — so a diff keeps its header,
// collapse control, and a name that still matches a `diff` fence.
// A language value labels with its `name` and reflects its first
// identifier as `data-language`, so theme selectors keep matching (FR13).
const languageName = languageWord(language);
const languageAttr = languageKey(language);
const languageLabel = !hasLanguageLabel
? null
: isDiff
? languageName === 'plaintext'
? 'diff'
: `${languageName} diff`
: languageName !== 'plaintext'
? languageName
: null;
const showHeader = title != null || languageLabel != null;
// A collapsed body must never outlive the visible header that controls it.
const canCollapse =
showHeader && isCollapsible && lines.length >= collapsibleThreshold;
const collapseControl = useMemo(
() => (canCollapse ? {} : null),
[canCollapse],
);
const [collapsedControl, setCollapsedControl] = useState<object | null>(null);
const isCollapsed =
collapseControl != null && collapsedControl === collapseControl;
const toggleCollapsed = useCallback(() => {
setCollapsedControl(current =>
current === collapseControl ? null : collapseControl,
);
}, [collapseControl]);
// Links the collapsible header to the code region it shows/hides so assistive
// tech can move from the button to its controlled content (disclosure
// pattern). The region stays mounted when collapsed (CSS grid animation), so
// this is always a resolvable reference — aria-controls can be unconditional.
const regionId = useId();
// The code viewport enters the Tab order only while its content actually
// overflows (AST-025 FR12–FR13): the shared scroll capability measures
// both axes, keeps focus where it is when overflow goes away, and owns the
// overflow declarations. role="group" (not "region") so several code
// blocks on a page don't create duplicate same-named landmarks.
const {getViewportProps, getContentProps} = useScrollableArea({
axis: 'both',
keyboardAccess: {
owner: 'viewport',
role: 'group',
label: languageLabel ?? t('@astryx.codeBlock.code'),
},
});
const scrollStyle: CSSProperties | undefined =
maxHeight != null
? {
maxHeight:
typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
}
: undefined;
// Caller controls render before Copy; together they are the block's controls,
// in the header when there is one and in the corner cluster otherwise.
const hasEndContent = isRenderable(endContent);
const hasControls = hasCopyButton || hasEndContent;
const copyButtonEl = hasCopyButton ? (
<IconButton
variant="ghost"
size="sm"
icon={
<ComponentIcon
slot="code-block-copy"
state={{copied: copied && !copyFailed}}
fallback={{
icon: copyFailed ? 'close' : copied ? 'check' : 'copy',
size: 'sm',
}}
color="inherit"
/>
}
// A visible "Copy" hover/focus hint via Button's built-in tooltip. It
// stays "Copy" after copying — the copy → check icon flip is the
// confirmation — and says the failure while a failed copy shows. The
// aria-label swaps to the localized "Copied" or failure text, backed by
// the announcement.
tooltip={
copyFailed
? t('@astryx.codeBlock.copyFailed')
: t('@astryx.codeBlock.copyCode')
}
label={
copyFailed
? t('@astryx.codeBlock.copyFailed')
: copied
? t('@astryx.codeBlock.copied')
: t('@astryx.codeBlock.copyCode')
}
onClick={e => {
// Stop propagation so copying does not toggle the collapsible header.
e.stopPropagation();
void handleCopy();
}}
xstyle={styles.copyButton}
{...themeProps('code-block-copy-button')}
/>
) : null;
const headerEl = showHeader ? (
<div
{...mergeProps(
themeProps('code-block-header', {
size,
language: languageAttr,
container,
}),
stylex.props(
styles.headerRow,
hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
),
)}>
<div
role={canCollapse ? 'button' : undefined}
tabIndex={canCollapse ? 0 : undefined}
aria-expanded={canCollapse ? !isCollapsed : undefined}
aria-controls={canCollapse ? regionId : undefined}
aria-label={
canCollapse && !title?.trim() && !languageLabel
? t('@astryx.codeBlock.code')
: undefined
}
onClick={canCollapse ? toggleCollapsed : undefined}
onKeyDown={
canCollapse
? (e: React.KeyboardEvent) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
toggleCollapsed();
}
}
: undefined
}
{...focusOutlineProps.focusVisible(
styles.header,
canCollapse && styles.headerCollapsible,
)}>
<span
{...mergeProps(
themeProps('code-block-title', {size, language: languageAttr}),
stylex.props(styles.headerTitle),
)}>
{canCollapse && (
// The collapsed chevron points toward the inline end, so it mirrors
// in RTL (design:bidirectionality DR4). The mirror sits on this box
// so the glyph's own rotation still eases: rotated down when
// expanded, a mirrored glyph still points down.
<span {...stylex.props(styles.collapseChevron, rtlStyles.mirror)}>
<Icon
icon="chevronRight"
size="xsm"
color="inherit"
xstyle={[
styles.collapseChevronIcon,
!isCollapsed && styles.collapseChevronExpanded,
]}
/>
</span>
)}
{title}
{title && languageLabel ? ' — ' : ''}
{languageLabel}
</span>
</div>
{hasControls ? (
<div {...stylex.props(styles.headerControls)}>
{hasEndContent ? endContent : null}
{copyButtonEl}
</div>
) : null}
</div>
) : null;
const codeBody = (
<div
{...getViewportProps<HTMLDivElement>({
// A tab stop while the code overflows: the shared ring, which a theme
// restyles through the focus-outline tokens.
...focusOutlineProps.focusVisible(
styles.viewport,
styles.viewportFocusRingInset,
),
style: scrollStyle,
})}>
<div
{...getContentProps<HTMLDivElement>(
stylex.props(
styles.codeWrapper,
showHeader && !hasLineNumbers && styles.codeWrapperCompact,
),
)}>
{useSpans ? (
<SpanCodeContent
lines={lines}
tokenLines={tokenLines}
highlightSet={highlightSet}
diffKinds={diffKinds}
diff={diff}
isWrapped={isWrapped}
sizeStyle={sizeStyle}
hasLineNumbers={hasLineNumbers}
maxDigits={maxLineDigits}
startLineNumber={effectiveStartLineNumber}
/>
) : (
<RangeCodeContent
lines={lines}
tokenLines={tokenLines}
highlightSet={highlightSet}
diffKinds={diffKinds}
isWrapped={isWrapped}
sizeStyle={sizeStyle}
hasLineNumbers={hasLineNumbers}
maxDigits={maxLineDigits}
startLineNumber={effectiveStartLineNumber}
/>
)}
</div>
</div>
);
const block = (
<pre
ref={ref}
{...mergeProps(
themeProps('code-block', {size, language: languageAttr, container}),
stylex.props(
styles.root,
hasControls && !showHeader && styles.rootCorner,
dynamicStyles.width(widthProp),
containerStyles[container],
xstyle,
),
className,
style,
)}
{...props}>
{headerEl}
{canCollapse ? (
<div
id={regionId}
// While collapsed, the region is only hidden visually (0fr grid
// row); inert also removes it from the tab order and accessibility
// tree so keyboard users cannot Tab into the invisible scroll
// container (a tab stop while it overflows). aria-controls pointing at an inert
// element remains a valid, resolvable reference.
inert={isCollapsed ? true : undefined}
{...stylex.props(
styles.collapseGrid,
isCollapsed && styles.collapseGridCollapsed,
)}>
<div {...stylex.props(styles.collapseInner)}>{codeBody}</div>
</div>
) : (
codeBody
)}
{hasControls && !showHeader ? (
<div
{...stylex.props(
styles.cornerCluster,
size === 'sm' ? styles.cornerClusterSm : styles.cornerClusterMd,
)}>
{hasEndContent ? endContent : null}
{copyButtonEl}
</div>
) : null}
</pre>
);
return syntaxTheme ? (
<SyntaxTheme theme={syntaxTheme}>{block}</SyntaxTheme>
) : (
block
);
}
CodeBlock.displayName = 'CodeBlock';