An open source design system that's fully customizable and agent ready
TypeScript
fix(CodeBlock): syntax highlighting missing on scroll + perf improvements (#1221)
Cindy Zhang4756b4119477
diff --git a/apps/sandbox/package.json b/apps/sandbox/package.jsonindex 99819d3838..0450d61244 100644--- a/apps/sandbox/package.json+++ b/apps/sandbox/package.json@@ -3,6 +3,7 @@"version": "0.0.1","private": true,"scripts": {+ "build:deps": "yarn workspace @xds/core build && yarn workspace @xds/theme-default build && yarn workspace @xds/theme-neutral build && yarn workspace @xds/theme-brutalist build && yarn workspace @xds/theme-meta build && yarn workspace @xds/theme-whatsapp build && yarn workspace @xds/theme-daily build","predev": "node ../../scripts/sync-templates.js","dev": "next dev","prebuild": "node ../../scripts/sync-templates.js",diff --git a/apps/sandbox/src/app/(fullscreen)/pages/codeblock-perf/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/codeblock-perf/page.tsxnew file mode 100644index 0000000000..bda7c23d40--- /dev/null+++ b/apps/sandbox/src/app/(fullscreen)/pages/codeblock-perf/page.tsx@@ -0,0 +1,363 @@+'use client';++import * as React from 'react';+import {useState, useCallback, useRef, useEffect} from 'react';+import {XDSCodeBlock} from '@xds/core/CodeBlock';+import {XDSText, XDSHeading} from '@xds/core/Text';+import {XDSHStack, XDSVStack} from '@xds/core/Stack';+import {XDSButton} from '@xds/core/Button';+import {XDSBadge} from '@xds/core/Badge';+import {XDSCard} from '@xds/core/Card';+import {XDSAppShell} from '@xds/core/AppShell';+import {XDSSection} from '@xds/core/Section';+import {XDSGrid} from '@xds/core/Grid';+import {+ XDSSegmentedControl,+ XDSSegmentedControlItem,+} from '@xds/core/SegmentedControl';++// ---------------------------------------------------------------------------+// Code generation+// ---------------------------------------------------------------------------++function generateCode(lines: number): string {+ const parts: string[] = [+ "import {useState, useEffect, useCallback, useMemo, useRef} from 'react';",+ "import type {ReactNode, CSSProperties} from 'react';",+ '',+ '// Auto-generated stress test code',+ `// ${lines} lines of TypeScript`,+ '',+ ];++ for (let i = 0; i < lines - 6; i++) {+ const mod = i % 12;+ switch (mod) {+ case 0:+ parts.push(`interface Model${i} {`);+ break;+ case 1:+ parts.push(` id: string;`);+ break;+ case 2:+ parts.push(` value: number;`);+ break;+ case 3:+ parts.push(`}`);+ break;+ case 4:+ parts.push('');+ break;+ case 5:+ parts.push(+ `async function fetch${i}(url: string): Promise<Model${i - 5}> {`,+ );+ break;+ case 6:+ parts.push(` const response = await fetch(url);`);+ break;+ case 7:+ parts.push(+ ` if (!response.ok) throw new Error("HTTP " + response.status);`,+ );+ break;+ case 8:+ parts.push(` return response.json(); // line ${i}`);+ break;+ case 9:+ parts.push(`}`);+ break;+ case 10:+ parts.push('');+ break;+ case 11:+ parts.push(`// Section ${Math.floor(i / 12) + 1}`);+ break;+ }+ }+ return parts.join('\n');+}++// ---------------------------------------------------------------------------+// Perf measurement+// ---------------------------------------------------------------------------++interface PerfMetrics {+ mountMs: number | null;+ renderCount: number;+ lastRenderMs: number | null;+ scrollFps: number | null;+ scrollFrameDrops: number;+}++function usePerfMetrics() {+ const [metrics, setMetrics] = useState<PerfMetrics>({+ mountMs: null,+ renderCount: 0,+ lastRenderMs: null,+ scrollFps: null,+ scrollFrameDrops: 0,+ });++ const mountStart = useRef(performance.now());+ const renderCount = useRef(0);++ renderCount.current += 1;++ useEffect(() => {+ const elapsed = performance.now() - mountStart.current;+ setMetrics({+ mountMs: elapsed,+ renderCount: renderCount.current,+ lastRenderMs: elapsed,+ scrollFps: null,+ scrollFrameDrops: 0,+ });+ }, []);++ const scrollRef = useRef<HTMLDivElement>(null);+ const scrollState = useRef({+ frames: 0,+ drops: 0,+ startTime: 0,+ rafId: 0,+ measuring: false,+ lastFrameTime: 0,+ });++ const runScrollTest = useCallback(() => {+ const el = scrollRef.current;+ if (!el) return;++ const scrollContainer =+ el.querySelector<HTMLElement>('[style*="max-height"]') ??+ el.querySelector<HTMLElement>('pre');+ if (!scrollContainer) return;++ scrollContainer.scrollTop = 0;+ const s = scrollState.current;+ s.frames = 0;+ s.drops = 0;+ s.startTime = performance.now();+ s.measuring = true;+ s.lastFrameTime = performance.now();++ function tick() {+ if (!s.measuring) return;+ const now = performance.now();+ s.frames++;+ if (now - s.lastFrameTime > 20) s.drops++;+ s.lastFrameTime = now;+ s.rafId = requestAnimationFrame(tick);+ }+ s.rafId = requestAnimationFrame(tick);++ const totalScroll =+ scrollContainer.scrollHeight - scrollContainer.clientHeight;+ const duration = 2000;+ const start = performance.now();++ function step() {+ const elapsed = performance.now() - start;+ const progress = Math.min(elapsed / duration, 1);+ const eased = 1 - Math.pow(1 - progress, 3);+ scrollContainer!.scrollTop = totalScroll * eased;++ if (progress < 1) {+ requestAnimationFrame(step);+ } else {+ requestAnimationFrame(() => {+ s.measuring = false;+ cancelAnimationFrame(s.rafId);+ const totalElapsed = performance.now() - s.startTime;+ if (totalElapsed > 0 && s.frames > 0) {+ const fps = Math.round((s.frames / totalElapsed) * 1000);+ setMetrics(m => ({+ ...m,+ scrollFps: fps,+ scrollFrameDrops: s.drops,+ }));+ }+ });+ }+ }+ requestAnimationFrame(step);+ }, []);++ return {metrics, scrollRef, runScrollTest};+}++// ---------------------------------------------------------------------------+// Metrics display+// ---------------------------------------------------------------------------++function metricVariant(+ value: number | null,+ thresholds?: {good: number; warn: number},+): 'green' | 'orange' | 'red' | 'neutral' {+ if (value == null || !thresholds) return 'neutral';+ if (value <= thresholds.good) return 'green';+ if (value <= thresholds.warn) return 'orange';+ return 'red';+}++function formatMetric(value: number | null, unit: string): string {+ if (value == null) return '\u2014';+ return `${value.toFixed(1)}${unit}`;+}++function Metric({+ label,+ value,+ unit,+ thresholds,+}: {+ label: string;+ value: number | null;+ unit: string;+ thresholds?: {good: number; warn: number};+}) {+ return (+ <XDSHStack gap={1} vAlign="center">+ <XDSBadge variant={metricVariant(value, thresholds)} label={label} />+ <XDSText type="code">{formatMetric(value, unit)}</XDSText>+ </XDSHStack>+ );+}++function MetricsBar({+ metrics,+ onScrollTest,+}: {+ metrics: PerfMetrics;+ onScrollTest: () => void;+}) {+ return (+ <XDSHStack gap={3} vAlign="center" wrap="wrap">+ <Metric+ label="mount"+ value={metrics.mountMs}+ unit="ms"+ thresholds={{good: 50, warn: 200}}+ />+ <Metric+ label="render"+ value={metrics.lastRenderMs}+ unit="ms"+ thresholds={{good: 16, warn: 50}}+ />+ <Metric label="renders" value={metrics.renderCount} unit="" />+ <Metric+ label="scroll fps"+ value={metrics.scrollFps}+ unit=""+ thresholds={{good: 120, warn: 55}}+ />+ <Metric label="drops" value={metrics.scrollFrameDrops} unit="" />+ <XDSButton+ size="sm"+ variant="secondary"+ label="Scroll test"+ onClick={onScrollTest}+ />+ </XDSHStack>+ );+}++// ---------------------------------------------------------------------------+// Panel (one code block + its metrics)+// ---------------------------------------------------------------------------++function PerfPanel({+ mode,+ label,+ lineCount,+ maxHeight,+}: {+ mode: 'ranges' | 'spans';+ label: string;+ lineCount: number;+ maxHeight: number;+}) {+ const code = React.useMemo(() => generateCode(lineCount), [lineCount]);+ const {metrics, scrollRef, runScrollTest} = usePerfMetrics();++ return (+ <XDSVStack gap={3}>+ <XDSHStack gap={2} vAlign="center">+ <XDSText type="label">{label}</XDSText>+ <XDSBadge label={mode} />+ </XDSHStack>+ <XDSCard padding={3} variant="muted">+ <MetricsBar metrics={metrics} onScrollTest={runScrollTest} />+ </XDSCard>+ <div ref={scrollRef}>+ <XDSCodeBlock+ code={code}+ language="typescript"+ title={`${lineCount.toLocaleString()} lines`}+ hasLineNumbers+ maxHeight={maxHeight}+ highlightMode={mode}+ />+ </div>+ </XDSVStack>+ );+}++// ---------------------------------------------------------------------------+// Page+// ---------------------------------------------------------------------------++const LINE_OPTIONS = ['100', '500', '1000', '2000', '5000'];++export default function CodeBlockPerfPage() {+ const [lineCount, setLineCount] = useState('1000');++ return (+ <XDSAppShell contentPadding={4} height="fill">+ <XDSVStack gap={4}>+ <XDSVStack gap={1}>+ <XDSHeading level={2}>CodeBlock Performance</XDSHeading>+ <XDSText type="body" color="secondary">+ Compare CSS Highlight API (ranges) vs span-based rendering side by+ side.+ </XDSText>+ </XDSVStack>++ <XDSSection variant="wash" padding={3} dividers={['bottom']}>+ <XDSSegmentedControl+ label="Line count"+ value={lineCount}+ onChange={setLineCount}+ size="sm">+ {LINE_OPTIONS.map(n => (+ <XDSSegmentedControlItem+ key={n}+ value={n}+ label={Number(n).toLocaleString()}+ />+ ))}+ </XDSSegmentedControl>+ </XDSSection>++ <XDSGrid columns={2} gap={4}>+ <PerfPanel+ key={`ranges-${lineCount}`}+ mode="ranges"+ label="CSS Highlight API"+ lineCount={Number(lineCount)}+ maxHeight={500}+ />+ <PerfPanel+ key={`spans-${lineCount}`}+ mode="spans"+ label="Span-based"+ lineCount={Number(lineCount)}+ maxHeight={500}+ />+ </XDSGrid>+ </XDSVStack>+ </XDSAppShell>+ );+}diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.tsindex 219015e72f..d52b6f14c8 100644--- a/apps/sandbox/src/app/sandboxPages.ts+++ b/apps/sandbox/src/app/sandboxPages.ts@@ -120,6 +120,12 @@ export const categories: SandboxCategory[] = [description:'CodePen-style playground with code panels and live XDS preview',},+ {+ name: 'CodeBlock Perf',+ href: '/pages/codeblock-perf/',+ description:+ 'Compare highlight modes and scroll performance'+ },],},];diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.tsx b/packages/core/src/CodeBlock/XDSCodeBlock.tsxindex f8452de3d8..baeb2454bd 100644--- a/packages/core/src/CodeBlock/XDSCodeBlock.tsx+++ b/packages/core/src/CodeBlock/XDSCodeBlock.tsx@@ -20,6 +20,7 @@ import {useCallback,useMemo,} from 'react';+import * as React from 'react';import type {XDSBaseProps} from '../XDSBaseProps';import * as stylex from '@stylexjs/stylex';import {@@ -35,7 +36,8 @@ import {import {xdsClassName, mergeProps} from '../utils';import {tokenize, tokenizeAsync, SYNC_TOKENIZE_THRESHOLD} from './tokenizer';import type {Token} from './tokenizer';-import {ensureHighlightStyles, TOKEN_TYPES} from './highlightStyles';+import {ensureHighlightStyles} from './highlightStyles';+import {applyHighlightRangesChunked} from './highlightRanges';// ---------------------------------------------------------------------------// Styles@@ -109,8 +111,9 @@ const styles = stylex.create({},line: {lineHeight: typeScaleVars['--text-code-leading'],+ },+ lineChunk: {contentVisibility: 'auto',- containIntrinsicBlockSize: 'auto 1lh',},lineHighlighted: {backgroundColor: colorVars['--color-accent-muted'],@@ -151,52 +154,110 @@ const styles = stylex.create({},});+// ---------------------------------------------------------------------------+// Line rendering (shared)+// ---------------------------------------------------------------------------++const LINE_CHUNK_SIZE = 20;+const LINE_CHUNK_THRESHOLD = 100;++/**+ * Memoized line component to avoid re-rendering unchanged lines.+ */+const CodeLine = React.memo(function CodeLine({+ lineIndex,+ isHighlighted,+ children,+}: {+ lineIndex: number;+ isHighlighted: boolean;+ children: React.ReactNode;+}) {+ return (+ <div+ data-line={lineIndex + 1}+ {...stylex.props(styles.line, isHighlighted && styles.lineHighlighted)}>+ {children}+ </div>+ );+});++function renderLines(+ lines: string[],+ highlightSet: Set<number> | null,+ renderLineContent: (line: string, lineIndex: number) => React.ReactNode,+ chunkSize: number = LINE_CHUNK_SIZE,+): React.ReactNode {+ chunkSize = Math.max(1, Math.floor(chunkSize));++ const renderLine = (line: string, i: number) => (+ <CodeLine+ key={i}+ lineIndex={i}+ isHighlighted={highlightSet?.has(i + 1) ?? false}>+ {renderLineContent(line, i)}+ </CodeLine>+ );++ if (lines.length < LINE_CHUNK_THRESHOLD) {+ return lines.map(renderLine);+ }++ 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}+ {...stylex.props(styles.lineChunk)}+ style={{containIntrinsicBlockSize: `auto ${estimatedHeight}`}}>+ {chunkLines.map((line, j) => renderLine(line, start + j))}+ </div>,+ );+ }+ return chunks;+}+// ---------------------------------------------------------------------------// Props// ---------------------------------------------------------------------------export interface XDSCodeBlockProps extends XDSBaseProps<HTMLPreElement> {- /** Ref forwarded to the root <pre> element */ref?: React.Ref<HTMLPreElement>;- /** The code string to display */code: string;- /** Language for syntax highlighting. @default "plaintext" */language?: string;- /** Filename/label in header bar */title?: string;- /**- * Show the language name in the header bar.- * @default true- */hasLanguageLabel?: boolean;- /** Show line number gutter. @default false */hasLineNumbers?: boolean;- /** 1-indexed lines to highlight. */highlightLines?: number[];- /** Show copy-to-clipboard button. @default true */hasCopyButton?: boolean;- /** Callback after copy */onCopy?: () => void;- /** Wrap long lines vs horizontal scroll. @default false */isWrapped?: boolean;- /** Max height before scrolling */maxHeight?: number | string;- /** Text size. @default "md" */size?: 'sm' | 'md';- /** Custom tokenizer override */tokenizer?: (code: string,language: string,) => Array<{type: string; start: number; end: number}>;}+/**+ * Internal-only props for testing and performance tuning.+ * Not part of the public API — used by the sandbox perf page.+ * @internal+ */+interface XDSCodeBlockInternalProps extends XDSCodeBlockProps {+ /** @internal Force a specific highlighting strategy. */+ highlightMode?: 'auto' | 'ranges' | 'spans';+}+// ---------------------------------------------------------------------------// Helpers// ----------------------------------------------------------------------------/**- * Check if CSS Custom Highlight API is available.- */function hasHighlightAPI(): boolean {return (typeof CSS !== 'undefined' &&@@ -205,43 +266,51 @@ function hasHighlightAPI(): boolean {);}-/**- * Build span-based highlighted line content from tokens.- *- * Splits a line into segments: plain text between tokens gets rendered- * as bare text nodes, tokens get wrapped in <span className="xds-token-{type}">.- */+// ---------------------------------------------------------------------------+// Span-mode code element+// ---------------------------------------------------------------------------++function findFirstTokenIndex(tokens: Token[], lineStart: number): number {+ let lo = 0;+ let hi = tokens.length;+ while (lo < hi) {+ const mid = (lo + hi) >>> 1;+ if (tokens[mid].end <= lineStart) {+ lo = mid + 1;+ } else {+ hi = mid;+ }+ }+ return lo;+}+function buildSpanLine(lineText: string,lineStart: number,tokens: Token[],+ searchStart: number,): React.ReactNode {if (tokens.length === 0) {return lineText || '\u200b';}const lineEnd = lineStart + lineText.length;-- // Filter tokens that overlap this line- const lineTokens = tokens.filter(t => t.start < lineEnd && t.end > lineStart);-- if (lineTokens.length === 0) {- return lineText || '\u200b';- }-const parts: React.ReactNode[] = [];let cursor = lineStart;+ let hasTokens = false;- for (const token of lineTokens) {+ for (let i = searchStart; i < tokens.length; i++) {+ const token = tokens[i];+ if (token.start >= lineEnd) break;+ if (token.end <= lineStart) continue;++ hasTokens = true;const tStart = Math.max(token.start, lineStart);const tEnd = Math.min(token.end, lineEnd);- // Plain text before this tokenif (tStart > cursor) {parts.push(lineText.slice(cursor - lineStart, tStart - lineStart));}-- // Token spanparts.push(<spankey={`${tStart}-${token.type}`}@@ -249,99 +318,53 @@ function buildSpanLine({lineText.slice(tStart - lineStart, tEnd - lineStart)}</span>,);-cursor = tEnd;}- // Remaining plain text after last token- if (cursor < lineEnd) {- parts.push(lineText.slice(cursor - lineStart));- }-+ if (!hasTokens) return lineText || '\u200b';+ if (cursor < lineEnd) parts.push(lineText.slice(cursor - lineStart));return parts.length > 0 ? parts : '\u200b';}-// ----------------------------------------------------------------------------// Component-// ----------------------------------------------------------------------------/**- * A read-only syntax-highlighted code block.- *- * Uses the CSS Custom Highlight API for zero-DOM-overhead syntax coloring.- * Falls back to span-based rendering in browsers without support, or when- * `highlightMode="spans"` is explicitly set.- *- * @example- * ```- * <XDSCodeBlock- * code={`const x = 42;`}- * language="typescript"- * hasLineNumbers- * />- * ```+ * Span-mode: tokenizes code and renders lines with <span> tokens.+ * Only mounts when highlightMode resolves to spans.*/-export function XDSCodeBlock({+function SpanCodeContent({code,- language = 'plaintext',- title,- hasLanguageLabel = true,- hasLineNumbers = false,- highlightLines,- hasCopyButton = true,- onCopy,- isWrapped = false,- maxHeight,- size = 'md',- tokenizer: customTokenizer,- xstyle,- className,- style,- ref,- ...props-}: XDSCodeBlockProps) {- const codeRef = useRef<HTMLElement>(null);- const instanceId = useId();- const [copied, setCopied] = useState(false);-- // Auto-detect: use CSS Custom Highlight API when available, fall back to spans- const useSpans = !hasHighlightAPI();-- // For span mode: we need tokens to render. Small code is tokenized sync,- // large code is tokenized async.+ language,+ lines,+ lineOffsets,+ highlightSet,+ isWrapped,+ sizeStyle,+ customTokenizer,+}: {+ code: string;+ language: string;+ lines: string[];+ lineOffsets: number[];+ highlightSet: Set<number> | null;+ isWrapped: boolean;+ sizeStyle: stylex.StyleXStyles;+ customTokenizer?: XDSCodeBlockProps['tokenizer'];+}) {const [asyncTokens, setAsyncTokens] = useState<Token[] | null>(null);- const lines = code.split('\n');- // Remove trailing empty line from code that ends with newline- if (lines.length > 1 && lines[lines.length - 1] === '') {- lines.pop();- }-- const highlightSet = highlightLines ? new Set(highlightLines) : null;-- const handleCopy = useCallback(() => {- navigator.clipboard.writeText(code).then(() => {- setCopied(true);- onCopy?.();- setTimeout(() => setCopied(false), 2000);- });- }, [code, onCopy]);+ useLayoutEffect(() => {+ ensureHighlightStyles();+ }, []);- // Compute tokens for span modeconst syncTokens = useMemo(() => {- if (!useSpans) return null;if (code.length >= SYNC_TOKENIZE_THRESHOLD) return null;const tok = customTokenizer ?? tokenize;return tok(code, language);- }, [useSpans, code, language, customTokenizer]);+ }, [code, language, customTokenizer]);- // Async tokenization for span mode with large codeuseEffect(() => {- if (!useSpans) return;if (code.length < SYNC_TOKENIZE_THRESHOLD) return;const abortController = new AbortController();-tokenizeAsync(code, language, abortController.signal).then(tokens => {if (!abortController.signal.aborted) {setAsyncTokens(tokens);@@ -352,32 +375,72 @@ export function XDSCodeBlock({abortController.abort();setAsyncTokens(null);};- }, [useSpans, code, language, customTokenizer]);+ }, [code, language, customTokenizer]);const spanTokens = syncTokens ?? asyncTokens ?? [];- // Apply CSS Custom Highlight API ranges — small code (sync, layout effect)- useLayoutEffect(() => {- if (useSpans) return;- if (code.length >= SYNC_TOKENIZE_THRESHOLD) return;- if (!hasHighlightAPI()) return;+ const tokenSearchStarts = useMemo(() => {+ if (spanTokens.length === 0) return null;+ const starts = new Array<number>(lines.length);+ for (let i = 0; i < lines.length; i++) {+ starts[i] = findFirstTokenIndex(spanTokens, lineOffsets[i]);+ }+ return starts;+ }, [spanTokens, lines.length, lineOffsets]);- ensureHighlightStyles();+ function renderLineContent(line: string, lineIndex: number): React.ReactNode {+ return buildSpanLine(+ line,+ lineOffsets[lineIndex],+ spanTokens,+ tokenSearchStarts?.[lineIndex] ?? 0,+ );+ }- const codeEl = codeRef.current;- if (!codeEl) return;+ return (+ <code+ {...stylex.props(+ styles.code,+ sizeStyle,+ isWrapped && styles.codeWrapped,+ )}>+ {renderLines(lines, highlightSet, renderLineContent)}+ </code>+ );+}- const tok = customTokenizer ?? tokenize;- const tokens = tok(code, language);- if (tokens.length === 0) return;+// ---------------------------------------------------------------------------+// Range-mode code element+// ---------------------------------------------------------------------------- return applyHighlightRanges(codeEl, tokens);- }, [useSpans, code, language, customTokenizer, instanceId]);+/**+ * Range-mode: renders plain text lines, applies CSS Custom Highlight API+ * ranges in a non-blocking effect. Only mounts when highlightMode+ * resolves to ranges.+ */+function RangeCodeContent({+ code,+ language,+ lines,+ highlightSet,+ isWrapped,+ sizeStyle,+ customTokenizer,+}: {+ code: string;+ language: string;+ lines: string[];+ highlightSet: Set<number> | null;+ isWrapped: boolean;+ sizeStyle: stylex.StyleXStyles;+ customTokenizer?: XDSCodeBlockProps['tokenizer'];+}) {+ const codeRef = useRef<HTMLElement>(null);+ const instanceId = useId();- // Apply CSS Custom Highlight API ranges — large code (async, regular effect)+ // Apply highlight ranges in a non-blocking effect so the code text+ // is visible and scrollable immediately. Colors appear a frame later.useEffect(() => {- if (useSpans) return;- if (code.length < SYNC_TOKENIZE_THRESHOLD) return;if (!hasHighlightAPI()) return;ensureHighlightStyles();@@ -385,27 +448,120 @@ export function XDSCodeBlock({const codeEl = codeRef.current;if (!codeEl) return;+ if (code.length < SYNC_TOKENIZE_THRESHOLD) {+ const tok = customTokenizer ?? tokenize;+ const tokens = tok(code, language);+ if (tokens.length === 0) return;+ return applyHighlightRangesChunked(codeEl, tokens);+ }+const abortController = new AbortController();let cleanup: (() => void) | undefined;tokenizeAsync(code, language, abortController.signal).then(tokens => {if (abortController.signal.aborted) return;if (tokens.length === 0) return;- cleanup = applyHighlightRanges(codeEl, tokens);+ cleanup = applyHighlightRangesChunked(codeEl, tokens);});return () => {abortController.abort();cleanup?.();};- }, [useSpans, code, language, customTokenizer, instanceId]);+ }, [code, language, customTokenizer, instanceId]);- // Ensure styles are injected for span mode too- useLayoutEffect(() => {- if (useSpans) {- ensureHighlightStyles();+ function renderLineContent(line: string): React.ReactNode {+ return line || '\u200b';+ }++ return (+ <code+ ref={codeRef}+ {...stylex.props(+ styles.code,+ sizeStyle,+ isWrapped && styles.codeWrapped,+ )}>+ {/* No content-visibility chunking in range mode — TreeWalker+ can't see text nodes inside content-visibility: auto divs,+ so highlight ranges would be missing for off-screen lines. */}+ {renderLines(lines, highlightSet, renderLineContent, Infinity)}+ </code>+ );+}++// ---------------------------------------------------------------------------+// Main component+// ---------------------------------------------------------------------------++/**+ * A read-only syntax-highlighted code block.+ *+ * Uses the CSS Custom Highlight API for zero-DOM-overhead syntax coloring.+ * Falls back to span-based rendering in browsers without support, or when+ * `highlightMode="spans"` is explicitly set.+ *+ * @example+ * ```+ * <XDSCodeBlock+ * code={`const x = 42;`}+ * language="typescript"+ * hasLineNumbers+ * />+ * ```+ */+export function XDSCodeBlock({+ code,+ language = 'plaintext',+ title,+ hasLanguageLabel = true,+ hasLineNumbers = false,+ highlightLines,+ hasCopyButton = true,+ onCopy,+ isWrapped = false,+ maxHeight,+ size = 'md',+ tokenizer: customTokenizer,+ highlightMode = 'auto',+ xstyle,+ className,+ style,+ ref,+ ...props+}: XDSCodeBlockInternalProps) {+ const [copied, setCopied] = useState(false);++ const useSpans =+ highlightMode === 'spans' ||+ (highlightMode === 'auto' && !hasHighlightAPI());++ const {lines, lineOffsets} = useMemo(() => {+ const l = code.split('\n');+ if (l.length > 1 && l[l.length - 1] === '') {+ l.pop();+ }+ const offsets = new Array<number>(l.length);+ let offset = 0;+ for (let i = 0; i < l.length; i++) {+ offsets[i] = offset;+ offset += l[i].length + 1;}- }, [useSpans]);+ return {lines: l, lineOffsets: offsets};+ }, [code]);++ const highlightSet = useMemo(+ () => (highlightLines ? new Set(highlightLines) : null),+ [highlightLines],+ );++ const handleCopy = useCallback(() => {+ navigator.clipboard.writeText(code).then(() => {+ setCopied(true);+ onCopy?.();+ setTimeout(() => setCopied(false), 2000);+ });+ }, [code, onCopy]);const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;const gutterSizeStyle = size === 'sm' ? styles.gutterSm : styles.gutterMd;@@ -457,21 +613,6 @@ export function XDSCodeBlock({</button>) : null;- // Build line content: spans mode renders tokens inline, highlight mode- // renders plain text (CSS Highlight API colors it via ranges).- function renderLineContent(line: string, lineIndex: number): React.ReactNode {- if (!useSpans) {- return line || '\u200b';- }- // Calculate the character offset of this line in the full code string.- // Each previous line + 1 for the \n separator.- let lineStart = 0;- for (let i = 0; i < lineIndex; i++) {- lineStart += lines[i].length + 1;- }- return buildSpanLine(line, lineStart, spanTokens);- }-return (<preref={ref}@@ -505,25 +646,28 @@ export function XDSCodeBlock({))}</div>)}- <code- ref={codeRef}- {...stylex.props(- styles.code,- sizeStyle,- isWrapped && styles.codeWrapped,- )}>- {lines.map((line, i) => (- <div- key={i}- data-line={i + 1}- {...stylex.props(- styles.line,- highlightSet?.has(i + 1) && styles.lineHighlighted,- )}>- {renderLineContent(line, i)}- </div>- ))}- </code>+ {useSpans ? (+ <SpanCodeContent+ code={code}+ language={language}+ lines={lines}+ lineOffsets={lineOffsets}+ highlightSet={highlightSet}+ isWrapped={isWrapped}+ sizeStyle={sizeStyle}+ customTokenizer={customTokenizer}+ />+ ) : (+ <RangeCodeContent+ code={code}+ language={language}+ lines={lines}+ highlightSet={highlightSet}+ isWrapped={isWrapped}+ sizeStyle={sizeStyle}+ customTokenizer={customTokenizer}+ />+ )}</div></div>{!showHeader && copyButtonEl}@@ -532,100 +676,3 @@ export function XDSCodeBlock({}XDSCodeBlock.displayName = 'XDSCodeBlock';--// ----------------------------------------------------------------------------// Shared highlight range application-// -----------------------------------------------------------------------------/**- * Apply CSS Custom Highlight API ranges to a code element.- * Returns a cleanup function that removes the ranges.- */-function applyHighlightRanges(- codeEl: HTMLElement,- tokens: Token[],-): () => void {- // Group tokens by type- const tokensByType = new Map<string, Token[]>();- for (const token of tokens) {- const existing = tokensByType.get(token.type);- if (existing) {- existing.push(token);- } else {- tokensByType.set(token.type, [token]);- }- }-- // Build text node mapping using TreeWalker — same approach as CodeEditor.- const walker = document.createTreeWalker(codeEl, NodeFilter.SHOW_TEXT);- const textNodes: Array<{node: Text; start: number}> = [];- let charOffset = 0;-- let currentNode = walker.nextNode();- while (currentNode) {- const text = currentNode as Text;- const content = text.textContent ?? '';- if (content === '\u200b') {- charOffset += 1;- } else {- textNodes.push({node: text, start: charOffset});- charOffset += content.length + 1;- }- currentNode = walker.nextNode();- }-- function findPosition(offset: number): {node: Text; offset: number} | null {- for (let i = textNodes.length - 1; i >= 0; i--) {- const entry = textNodes[i];- if (offset >= entry.start) {- const localOffset = offset - entry.start;- if (localOffset <= (entry.node.textContent?.length ?? 0)) {- return {node: entry.node, offset: localOffset};- }- return null;- }- }- return null;- }-- const myRanges: Range[] = [];-- for (const tokenType of TOKEN_TYPES) {- const typedTokens = tokensByType.get(tokenType);- if (!typedTokens || typedTokens.length === 0) continue;-- const name = `xds-${tokenType}`;- let highlight = CSS.highlights.get(name);- if (!highlight) {- highlight = new Highlight();- CSS.highlights.set(name, highlight);- }-- for (const token of typedTokens) {- const startPos = findPosition(token.start);- const endPos = findPosition(token.end);- if (!startPos || !endPos) continue;-- try {- const range = new Range();- range.setStart(startPos.node, startPos.offset);- range.setEnd(endPos.node, endPos.offset);- highlight.add(range);- myRanges.push(range);- } catch {- // Skip invalid ranges- }- }- }-- return () => {- for (const range of myRanges) {- for (const tokenType of TOKEN_TYPES) {- const highlight = CSS.highlights.get(`xds-${tokenType}`);- if (highlight) {- highlight.delete(range);- }- }- }- };-}diff --git a/packages/core/src/CodeBlock/highlightRanges.test.ts b/packages/core/src/CodeBlock/highlightRanges.test.tsnew file mode 100644index 0000000000..a40b49f420--- /dev/null+++ b/packages/core/src/CodeBlock/highlightRanges.test.ts@@ -0,0 +1,203 @@+/**+ * @file highlightRanges.test.ts+ * Tests for binary search, text node mapping, and range application.+ */++import {describe, it, expect, beforeEach, afterEach} from 'vitest';+import {buildTextNodeMap, applyHighlightRanges} from './highlightRanges';++// ---------------------------------------------------------------------------+// DOM helpers+// ---------------------------------------------------------------------------++function makeCodeEl(lines: string[]): HTMLElement {+ const code = document.createElement('code');+ for (const line of lines) {+ const div = document.createElement('div');+ div.textContent = line || '\u200b';+ code.appendChild(div);+ }+ document.body.appendChild(code);+ return code;+}++afterEach(() => {+ document.body.innerHTML = '';+});++// ---------------------------------------------------------------------------+// buildTextNodeMap+// ---------------------------------------------------------------------------++describe('buildTextNodeMap', () => {+ it('maps single-line code', () => {+ const el = makeCodeEl(['const x = 1;']);+ const nodes = buildTextNodeMap(el);++ expect(nodes).toHaveLength(1);+ expect(nodes[0].start).toBe(0);+ expect(nodes[0].node.textContent).toBe('const x = 1;');+ });++ it('maps multi-line code with correct offsets', () => {+ const el = makeCodeEl(['hello', 'world']);+ const nodes = buildTextNodeMap(el);++ expect(nodes).toHaveLength(2);+ expect(nodes[0].start).toBe(0);+ expect(nodes[1].start).toBe(6); // "hello"(5) + 1 for \n+ });++ it('handles empty lines (zero-width space)', () => {+ const el = makeCodeEl(['hello', '', 'world']);+ const nodes = buildTextNodeMap(el);++ // ZWSP nodes not included in array+ expect(nodes).toHaveLength(2);+ expect(nodes[0].start).toBe(0);+ expect(nodes[1].start).toBe(7); // "hello"(5) + \n(1) + ZWSP(1)+ });++ it('returns empty for empty element', () => {+ const el = document.createElement('code');+ document.body.appendChild(el);+ expect(buildTextNodeMap(el)).toHaveLength(0);+ });++ it('offset accounts for multiple consecutive empty lines', () => {+ const el = makeCodeEl(['a', '', '', 'b']);+ const nodes = buildTextNodeMap(el);++ expect(nodes).toHaveLength(2);+ expect(nodes[0].start).toBe(0); // "a"+ expect(nodes[1].start).toBe(4); // "a"(1) + \n(1) + ZWSP(1) + ZWSP(1)+ });+});++// ---------------------------------------------------------------------------+// applyHighlightRanges+// ---------------------------------------------------------------------------++describe('applyHighlightRanges', () => {+ let mockHighlights: Map<string, Set<Range>>;++ beforeEach(() => {+ mockHighlights = new Map();++ if (typeof CSS === 'undefined') {+ (globalThis as Record<string, unknown>).CSS = {};+ }+ (CSS as Record<string, unknown>).highlights = {+ get(name: string) {+ return mockHighlights.get(name);+ },+ set(name: string, highlight: Set<Range>) {+ mockHighlights.set(name, highlight);+ },+ };++ (globalThis as Record<string, unknown>).Highlight =+ class MockHighlight extends Set<Range> {};+ });++ afterEach(() => {+ delete (CSS as Record<string, unknown>).highlights;+ delete (globalThis as Record<string, unknown>).Highlight;+ });++ it('creates ranges for tokens', () => {+ const el = makeCodeEl(['const x = 1;']);+ const tokens = [+ {type: 'keyword', start: 0, end: 5},+ {type: 'variable', start: 6, end: 7},+ {type: 'number', start: 10, end: 11},+ ];++ const cleanupFn = applyHighlightRanges(el, tokens);++ expect(mockHighlights.has('xds-keyword')).toBe(true);+ expect(mockHighlights.has('xds-variable')).toBe(true);+ expect(mockHighlights.has('xds-number')).toBe(true);+ expect(mockHighlights.get('xds-keyword')!.size).toBe(1);+ expect(mockHighlights.get('xds-variable')!.size).toBe(1);+ expect(mockHighlights.get('xds-number')!.size).toBe(1);++ cleanupFn();+ });++ it('handles multi-line tokens', () => {+ const el = makeCodeEl(['const x = 1;', 'let y = 2;']);+ const tokens = [+ {type: 'keyword', start: 0, end: 5},+ {type: 'keyword', start: 14, end: 17},+ ];++ const cleanupFn = applyHighlightRanges(el, tokens);+ expect(mockHighlights.get('xds-keyword')!.size).toBe(2);+ cleanupFn();+ });++ it('skips tokens with out-of-bounds offsets', () => {+ const el = makeCodeEl(['hello']);+ const tokens = [+ {type: 'keyword', start: 0, end: 5},+ {type: 'keyword', start: 100, end: 105},+ ];++ const cleanupFn = applyHighlightRanges(el, tokens);+ expect(mockHighlights.get('xds-keyword')!.size).toBe(1);+ cleanupFn();+ });++ it('cleanup removes all ranges', () => {+ const el = makeCodeEl(['const x = 1;']);+ const tokens = [+ {type: 'keyword', start: 0, end: 5},+ {type: 'number', start: 10, end: 11},+ ];++ const cleanupFn = applyHighlightRanges(el, tokens);+ expect(mockHighlights.get('xds-keyword')!.size).toBe(1);+ expect(mockHighlights.get('xds-number')!.size).toBe(1);++ cleanupFn();++ expect(mockHighlights.get('xds-keyword')!.size).toBe(0);+ expect(mockHighlights.get('xds-number')!.size).toBe(0);+ });++ it('returns no-op cleanup for empty tokens', () => {+ const el = makeCodeEl(['hello']);+ const cleanupFn = applyHighlightRanges(el, []);++ // No highlights created for unused types+ expect(mockHighlights.size).toBe(0);++ // Should not throw+ cleanupFn();+ });++ it('handles tokens across empty lines', () => {+ // "if (x)\n\n return y;"+ const el = makeCodeEl(['if (x)', '', ' return y;']);+ const tokens = [+ {type: 'keyword', start: 0, end: 2},+ {type: 'keyword', start: 10, end: 16},+ ];++ const cleanupFn = applyHighlightRanges(el, tokens);+ expect(mockHighlights.get('xds-keyword')!.size).toBe(2);+ cleanupFn();+ });++ it('registers highlights for arbitrary token types', () => {+ const el = makeCodeEl(['hello']);+ const tokens = [{type: 'made_up_type', start: 0, end: 5}];++ const cleanupFn = applyHighlightRanges(el, tokens);+ expect(mockHighlights.has('xds-made_up_type')).toBe(true);+ expect(mockHighlights.get('xds-made_up_type')!.size).toBe(1);+ cleanupFn();+ expect(mockHighlights.get('xds-made_up_type')!.size).toBe(0);+ });+});diff --git a/packages/core/src/CodeBlock/highlightRanges.ts b/packages/core/src/CodeBlock/highlightRanges.tsnew file mode 100644index 0000000000..0196edbb33--- /dev/null+++ b/packages/core/src/CodeBlock/highlightRanges.ts@@ -0,0 +1,313 @@+/**+ * @file highlightRanges.ts+ * @input Code element, tokens array, CSS Custom Highlight API+ * @output Creates/removes highlight Range objects for syntax coloring+ * @position Shared utility consumed by XDSCodeBlock (ranges mode)+ */++import type {Token} from './tokenizer';+import {ensureHighlightStyles} from './highlightStyles';++// ---------------------------------------------------------------------------+// Text node mapping+// ---------------------------------------------------------------------------++interface TextNodeEntry {+ node: Text;+ start: number;+}++/**+ * Walk a code element's text nodes and build a sorted map of+ * character offsets. Each entry maps a Text node to its starting+ * offset in the original code string.+ *+ * Zero-width spaces (empty-line placeholders) count as 1 character+ * to stay aligned with the tokenizer's newline-separated offsets.+ */+export function buildTextNodeMap(codeEl: HTMLElement): TextNodeEntry[] {+ const walker = document.createTreeWalker(codeEl, NodeFilter.SHOW_TEXT);+ const textNodes: TextNodeEntry[] = [];+ let charOffset = 0;++ let currentNode = walker.nextNode();+ while (currentNode) {+ const text = currentNode as Text;+ const content = text.textContent ?? '';+ if (content === '\u200b') {+ charOffset += 1;+ } else {+ textNodes.push({node: text, start: charOffset});+ charOffset += content.length + 1;+ }+ currentNode = walker.nextNode();+ }+ return textNodes;+}++// ---------------------------------------------------------------------------+// Binary search+// ---------------------------------------------------------------------------++/**+ * Binary search for the Text node containing a character offset.+ * Returns the node and the local offset within that node, or null+ * if the offset falls outside any mapped node.+ */+function findPosition(+ textNodes: TextNodeEntry[],+ offset: number,+): {node: Text; offset: number} | null {+ let lo = 0;+ let hi = textNodes.length - 1;++ while (lo <= hi) {+ const mid = (lo + hi) >>> 1;+ const entry = textNodes[mid];+ if (offset < entry.start) {+ hi = mid - 1;+ } else if (+ mid + 1 < textNodes.length &&+ offset >= textNodes[mid + 1].start+ ) {+ lo = mid + 1;+ } else {+ const localOffset = offset - entry.start;+ if (localOffset <= (entry.node.textContent?.length ?? 0)) {+ return {node: entry.node, offset: localOffset};+ }+ return null;+ }+ }+ return null;+}++// ---------------------------------------------------------------------------+// Dynamic ::highlight() style injection+// ---------------------------------------------------------------------------++/**+ * Track which token types already have a ::highlight() CSS rule.+ * Known types are injected statically by ensureHighlightStyles();+ * unknown types (e.g. from a Shiki adapter) get rules injected lazily.+ */+const registeredHighlightTypes = new Set<string>();+let dynamicStyleSheet: CSSStyleSheet | null = null;++/**+ * Ensure a ::highlight(xds-{type}) CSS rule exists for the given token type.+ * For the built-in types this is a no-op (static sheet covers them).+ * For unknown types, injects a rule that maps to a --color-syntax-{type}+ * custom property, falling back to currentColor.+ */+function ensureHighlightType(tokenType: string): void {+ if (registeredHighlightTypes.has(tokenType)) return;+ registeredHighlightTypes.add(tokenType);++ // Static styles cover the built-in types; only inject for unknown ones+ ensureHighlightStyles();+ if (typeof document === 'undefined') return;++ if (!dynamicStyleSheet) {+ const style = document.createElement('style');+ style.setAttribute('data-xds-highlight-dynamic', '');+ document.head.appendChild(style);+ dynamicStyleSheet = style.sheet!;+ }++ const name = `xds-${tokenType}`;+ const colorVar = `var(--color-syntax-${tokenType}, currentColor)`;+ dynamicStyleSheet.insertRule(+ `.xds-codeblock ::highlight(${name}), .xds-codeeditor ::highlight(${name}) { color: ${colorVar}; }`,+ );+}++// ---------------------------------------------------------------------------+// Range application+// ---------------------------------------------------------------------------++/**+ * Apply CSS Custom Highlight API ranges to a code element.+ *+ * Derives token types from the tokens themselves (not a hardcoded list),+ * so custom tokenizers (e.g. Shiki adapters) can produce arbitrary+ * scope names and they'll be registered automatically.+ *+ * Groups tokens by type, resolves each token's character offsets to+ * DOM Range objects via binary search over the text node map, and+ * registers them with the global CSS.highlights registry.+ *+ * Returns a cleanup function that removes all created ranges.+ */+/**+ * Tokens per chunk when applying ranges progressively.+ * Smaller = more responsive, larger = fewer frames to full color.+ */+const RANGE_CHUNK_SIZE = 200;++/**+ * Resolve a flat list of tokens into Highlight entries, returning+ * the ranges and their associated Highlight objects for cleanup.+ */+function resolveTokenRanges(+ tokens: Token[],+ textNodes: TextNodeEntry[],+): Array<{range: Range; highlight: Highlight}> {+ // Group tokens by type+ const tokensByType = new Map<string, Token[]>();+ for (const token of tokens) {+ const existing = tokensByType.get(token.type);+ if (existing) {+ existing.push(token);+ } else {+ tokensByType.set(token.type, [token]);+ }+ }++ const results: Array<{range: Range; highlight: Highlight}> = [];++ for (const [tokenType, typedTokens] of tokensByType) {+ ensureHighlightType(tokenType);++ const name = `xds-${tokenType}`;+ let highlight = CSS.highlights.get(name);+ if (!highlight) {+ highlight = new Highlight();+ CSS.highlights.set(name, highlight);+ }++ for (const token of typedTokens) {+ const startPos = findPosition(textNodes, token.start);+ const endPos = findPosition(textNodes, token.end);+ if (!startPos || !endPos) continue;++ try {+ const range = new Range();+ range.setStart(startPos.node, startPos.offset);+ range.setEnd(endPos.node, endPos.offset);+ highlight.add(range);+ results.push({range, highlight});+ } catch {+ // Skip invalid ranges (detached nodes, out-of-bounds offsets)+ }+ }+ }++ return results;+}++function cleanupRanges(+ ranges: Array<{range: Range; highlight: Highlight}>,+): void {+ for (const {range, highlight} of ranges) {+ highlight.delete(range);+ }+}++/**+ * Apply CSS Custom Highlight API ranges synchronously.+ * Best for small token sets (< RANGE_CHUNK_SIZE).+ * Returns a cleanup function that removes all created ranges.+ */+export function applyHighlightRanges(+ codeEl: HTMLElement,+ tokens: Token[],+): () => void {+ const textNodes = buildTextNodeMap(codeEl);+ const myRanges = resolveTokenRanges(tokens, textNodes);++ return function cleanup() {+ cleanupRanges(myRanges);+ };+}++/**+ * Apply CSS Custom Highlight API ranges in chunks, yielding to the+ * browser between batches via requestAnimationFrame. Colors appear+ * progressively over a few frames instead of blocking the main thread.+ *+ * Returns a cleanup function that cancels pending work and removes+ * all ranges applied so far.+ */+export function applyHighlightRangesChunked(+ codeEl: HTMLElement,+ tokens: Token[],+ chunkSize: number = RANGE_CHUNK_SIZE,+): () => void {+ // For small token sets, apply synchronously — no chunking overhead+ if (tokens.length <= chunkSize) {+ return applyHighlightRanges(codeEl, tokens);+ }++ const textNodes = buildTextNodeMap(codeEl);++ // Pre-group tokens by type and resolve highlights once+ const tokensByType = new Map<+ string,+ {tokens: Token[]; highlight: Highlight}+ >();+ for (const token of tokens) {+ let entry = tokensByType.get(token.type);+ if (!entry) {+ ensureHighlightType(token.type);+ const name = `xds-${token.type}`;+ let highlight = CSS.highlights.get(name);+ if (!highlight) {+ highlight = new Highlight();+ CSS.highlights.set(name, highlight);+ }+ entry = {tokens: [], highlight};+ tokensByType.set(token.type, entry);+ }+ entry.tokens.push(token);+ }++ // Flatten to a single ordered list for chunked iteration+ const allEntries: Array<{token: Token; highlight: Highlight}> = [];+ for (const {tokens: typedTokens, highlight} of tokensByType.values()) {+ for (const token of typedTokens) {+ allEntries.push({token, highlight});+ }+ }++ const myRanges: Array<{range: Range; highlight: Highlight}> = [];+ let cursor = 0;+ let rafId = 0;+ let cancelled = false;++ function processChunk() {+ if (cancelled) return;++ const end = Math.min(cursor + chunkSize, allEntries.length);+ for (let i = cursor; i < end; i++) {+ const {token, highlight} = allEntries[i];+ const startPos = findPosition(textNodes, token.start);+ const endPos = findPosition(textNodes, token.end);+ if (!startPos || !endPos) continue;++ try {+ const range = new Range();+ range.setStart(startPos.node, startPos.offset);+ range.setEnd(endPos.node, endPos.offset);+ highlight.add(range);+ myRanges.push({range, highlight});+ } catch {+ // Skip invalid ranges+ }+ }+ cursor = end;++ if (cursor < allEntries.length) {+ rafId = requestAnimationFrame(processChunk);+ }+ }++ // Start first chunk synchronously for immediate partial coloring+ processChunk();++ return function cleanup() {+ cancelled = true;+ cancelAnimationFrame(rafId);+ cleanupRanges(myRanges);+ };+}