An open source design system that's fully customizable and agent ready
TypeScript
perf(codeblock): enable content-visibility chunking for range mode, eliminate stylesheet mutations (#1457)
Cindy Zhang1af9dcef6a0b
diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.tsx b/packages/core/src/CodeBlock/XDSCodeBlock.tsxindex 16b41f5604..84ea00d799 100644--- a/packages/core/src/CodeBlock/XDSCodeBlock.tsx+++ b/packages/core/src/CodeBlock/XDSCodeBlock.tsx@@ -382,10 +382,7 @@ function useTokenLines(// Span-mode code element// ----------------------------------------------------------------------------function buildSpanLine(- lineText: string,- tokens: Token[],-): React.ReactNode {+function buildSpanLine(lineText: string, tokens: Token[]): React.ReactNode {if (tokens.length === 0) {return lineText || '\u200b';}@@ -493,7 +490,7 @@ function RangeCodeContent({sizeStyle,isWrapped && styles.codeWrapped,)}>- {renderLines(lines, highlightSet, renderLineContent, Infinity)}+ {renderLines(lines, highlightSet, renderLineContent)}</code>);}@@ -568,22 +565,41 @@ export function XDSCodeBlock({: undefined;const copyIcon = copied ? (- <svg width="1em" height="1em" viewBox="0 0 24 24" fill="none"- stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">+ <svg+ width="1em"+ height="1em"+ viewBox="0 0 24 24"+ fill="none"+ stroke="currentColor"+ strokeWidth={1.5}+ strokeLinecap="round"+ strokeLinejoin="round"><path d="M5 13l4 4L19 7" /></svg>) : (- <svg width="1em" height="1em" viewBox="0 0 24 24" fill="none"- stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">+ <svg+ width="1em"+ height="1em"+ viewBox="0 0 24 24"+ fill="none"+ stroke="currentColor"+ strokeWidth={1.5}+ strokeLinecap="round"+ strokeLinejoin="round"><path d="M8 4v12a2 2 0 002 2h8a2 2 0 002-2V7.242a2 2 0 00-.602-1.43L16.083 2.57A2 2 0 0014.685 2H10a2 2 0 00-2 2z" /><path d="M16 18v2a2 2 0 01-2 2H6a2 2 0 01-2-2V9a2 2 0 012-2h2" /></svg>);const copyButtonEl = hasCopyButton ? (- <button type="button" onClick={handleCopy}+ <button+ type="button"+ onClick={handleCopy}aria-label={copied ? 'Copied' : 'Copy code'}- {...stylex.props(styles.copyButton, !showHeader && styles.copyButtonAbsolute)}>+ {...stylex.props(+ styles.copyButton,+ !showHeader && styles.copyButtonAbsolute,+ )}>{copyIcon}</button>) : null;@@ -594,14 +610,16 @@ export function XDSCodeBlock({tabIndex={canCollapse ? 0 : undefined}aria-expanded={canCollapse ? !isCollapsed : undefined}onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}- onKeyDown={canCollapse- ? (e: React.KeyboardEvent) => {- if (e.key === 'Enter' || e.key === ' ') {- e.preventDefault();- setIsCollapsed(prev => !prev);+ onKeyDown={+ canCollapse+ ? (e: React.KeyboardEvent) => {+ if (e.key === 'Enter' || e.key === ' ') {+ e.preventDefault();+ setIsCollapsed(prev => !prev);+ }}- }- : undefined}+ : undefined+ }{...stylex.props(styles.header,hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,@@ -612,10 +630,11 @@ export function XDSCodeBlock({{title && languageLabel ? ' — ' : ''}{languageLabel}{canCollapse && (- <span {...stylex.props(- styles.collapseChevron,- isCollapsed && styles.collapseChevronCollapsed,- )}>+ <span+ {...stylex.props(+ styles.collapseChevron,+ isCollapsed && styles.collapseChevronCollapsed,+ )}><XDSIcon icon="chevronDown" size="xsm" color="inherit" /></span>)}@@ -625,12 +644,23 @@ export function XDSCodeBlock({) : null;const codeBody = (- <div ref={scrollContainerRef} {...stylex.props(styles.scrollContainer)} style={scrollStyle}>- <div {...stylex.props(styles.codeWrapper, showHeader && !hasLineNumbers && styles.codeWrapperCompact)}>+ <div+ ref={scrollContainerRef}+ {...stylex.props(styles.scrollContainer)}+ style={scrollStyle}>+ <div+ {...stylex.props(+ styles.codeWrapper,+ showHeader && !hasLineNumbers && styles.codeWrapperCompact,+ )}>{hasLineNumbers && (- <div {...stylex.props(styles.gutter, gutterSizeStyle)} aria-hidden="true">+ <div+ {...stylex.props(styles.gutter, gutterSizeStyle)}+ aria-hidden="true">{lines.map((_, i) => (- <div key={i} {...stylex.props(styles.gutterLine)}>{i + 1}</div>+ <div key={i} {...stylex.props(styles.gutterLine)}>+ {i + 1}+ </div>))}</div>)}@@ -658,11 +688,20 @@ export function XDSCodeBlock({return (<preref={ref}- {...mergeProps(xdsClassName('codeblock', {size, language}), stylex.props(styles.root, xstyle), className, style)}+ {...mergeProps(+ xdsClassName('codeblock', {size, language}),+ stylex.props(styles.root, xstyle),+ className,+ style,+ )}{...props}>{headerEl}{canCollapse ? (- <div {...stylex.props(styles.collapseGrid, isCollapsed && styles.collapseGridCollapsed)}>+ <div+ {...stylex.props(+ styles.collapseGrid,+ isCollapsed && styles.collapseGridCollapsed,+ )}><div {...stylex.props(styles.collapseInner)}>{codeBody}</div></div>) : (diff --git a/packages/core/src/CodeBlock/highlightRanges.ts b/packages/core/src/CodeBlock/highlightRanges.tsindex 68a1984dfa..e8ed72bbea 100644--- a/packages/core/src/CodeBlock/highlightRanges.ts+++ b/packages/core/src/CodeBlock/highlightRanges.ts@@ -10,20 +10,38 @@*/import type {Token, TokenLine} from './tokenizer';-import {ensureHighlightStyles} from './highlightStyles';+import {ensureHighlightStyles, TOKEN_TYPES} from './highlightStyles';++/**+ * contentvisibilityautostatechange event — not yet in all TS DOM libs.+ */+interface ContentVisibilityAutoStateChangeEvent extends Event {+ readonly skipped: boolean;+}++interface CheckVisibilityOptions {+ checkVisibilityCSS?: boolean;+ contentVisibilityAuto?: boolean;+}// ---------------------------------------------------------------------------// Dynamic ::highlight() style injection// ----------------------------------------------------------------------------const registeredHighlightTypes = new Set<string>();+/**+ * Pre-seeded with all built-in token types — the static stylesheet in+ * highlightStyles.ts already has ::highlight() rules for these. Only+ * truly unknown types trigger dynamic insertRule, avoiding unnecessary+ * stylesheet mutations and style recalcs.+ */+const registeredHighlightTypes = new Set<string>(TOKEN_TYPES);let dynamicStyleSheet: CSSStyleSheet | null = null;/**- * Ensure a ::highlight(xds-{type}) CSS rule exists for the given token type.- * Static styles cover the built-in types; only injects for unknown ones.+ * Inject a dynamic ::highlight() rule for an unknown token type.+ * Built-in types are pre-seeded and never reach this path.*/-function ensureHighlightType(tokenType: string): void {+function ensureDynamicHighlightType(tokenType: string): void {if (registeredHighlightTypes.has(tokenType)) return;registeredHighlightTypes.add(tokenType);@@ -45,18 +63,31 @@ function ensureHighlightType(tokenType: string): void {}// ----------------------------------------------------------------------------// Per-type Highlight cache+// Per-type Highlight lookup// ----------------------------------------------------------------------------function getOrCreateHighlight(tokenType: string): Highlight {- ensureHighlightType(tokenType);- const name = `xds-${tokenType}`;- let highlight = CSS.highlights.get(name);- if (!highlight) {- highlight = new Highlight();- CSS.highlights.set(name, highlight);- }- return highlight;+/**+ * Build a local Highlight cache for the duration of a single+ * apply pass. Avoids calling CSS.highlights.get() per-token+ * (one Map lookup per type instead of per token).+ */+function createHighlightResolver(): (tokenType: string) => Highlight {+ const cache = new Map<string, Highlight>();+ return (tokenType: string): Highlight => {+ let highlight = cache.get(tokenType);+ if (highlight) return highlight;++ ensureDynamicHighlightType(tokenType);++ const name = `xds-${tokenType}`;+ highlight = CSS.highlights.get(name);+ if (!highlight) {+ highlight = new Highlight();+ CSS.highlights.set(name, highlight);+ }+ cache.set(tokenType, highlight);+ return highlight;+ };}// ---------------------------------------------------------------------------@@ -77,6 +108,7 @@ function applyLineRanges(lineDiv: Element,tokens: Token[],results: RangeEntry[],+ resolve: (tokenType: string) => Highlight,): void {if (tokens.length === 0) return;@@ -93,7 +125,7 @@ function applyLineRanges(const start = Math.min(token.start, textLength);const end = Math.min(token.end, textLength);- const highlight = getOrCreateHighlight(token.type);+ const highlight = resolve(token.type);try {const range = new Range();@@ -114,59 +146,165 @@ function cleanupRanges(ranges: RangeEntry[]): void {}// ----------------------------------------------------------------------------// Chunked application+// Chunked application with lazy content-visibility support// ---------------------------------------------------------------------------const LINE_CHUNK_SIZE = 50;/**- * Apply CSS Custom Highlight API ranges for all lines. Processes- * lines in chunks via requestAnimationFrame so colors appear- * progressively without blocking the main thread.+ * Apply ranges for all [data-line] divs inside a container element.+ * Returns the RangeEntry[] so the caller can clean them up later.+ */+function applyRangesToContainer(+ container: Element,+ tokenLines: TokenLine[],+ globalLineOffset: number,+ resolve: (tokenType: string) => Highlight,+): RangeEntry[] {+ const results: RangeEntry[] = [];+ const lineDivs = container.querySelectorAll('[data-line]');+ for (let i = 0; i < lineDivs.length; i++) {+ const tokenIndex = globalLineOffset + i;+ const tokens = tokenLines[tokenIndex];+ if (tokens && tokens.length > 0) {+ applyLineRanges(lineDivs[i], tokens, results, resolve);+ }+ }+ return results;+}++/**+ * Apply CSS Custom Highlight API ranges lazily as content-visibility+ * chunks scroll into view. Visible chunks get ranges immediately;+ * offscreen chunks get ranges when `contentvisibilityautostatechange`+ * fires. Ranges are removed when chunks scroll back offscreen to+ * keep memory usage proportional to the viewport.+ *+ * For small files (no chunk wrappers / below LINE_CHUNK_THRESHOLD),+ * all lines are direct children and get ranges immediately.*- * @param codeEl - The <code> element containing line divs+ * @param codeEl - The <code> element containing line divs (possibly inside chunk wrappers)* @param tokenLines - Per-line token arrays from the tokenizer- * @returns Cleanup function that cancels pending work and removes ranges+ * @returns Cleanup function that removes all ranges and event listeners*/export function applyHighlightRangesChunked(codeEl: HTMLElement,tokenLines: TokenLine[],- chunkSize: number = LINE_CHUNK_SIZE,): () => void {ensureHighlightStyles();- // Collect all line divs with data-line attribute- const lineDivs = codeEl.querySelectorAll('[data-line]');- const myRanges: RangeEntry[] = [];- let cursor = 0;- let rafId = 0;- let cancelled = false;-- function processChunk() {- if (cancelled) return;+ const resolve = createHighlightResolver();++ // Detect chunk wrappers — direct children of <code> that contain [data-line] divs.+ // If there are no wrappers (small file), lines are direct children.+ const chunkWrappers: Element[] = [];+ const chunkLineOffsets: number[] = [];+ let lineCount = 0;++ for (let i = 0; i < codeEl.children.length; i++) {+ const child = codeEl.children[i];+ const lineDivs = child.querySelectorAll('[data-line]');+ if (+ lineDivs.length > 0 &&+ child.tagName === 'DIV' &&+ !child.hasAttribute('data-line')+ ) {+ // This is a chunk wrapper+ chunkWrappers.push(child);+ chunkLineOffsets.push(lineCount);+ lineCount += lineDivs.length;+ }+ }- const end = Math.min(cursor + chunkSize, lineDivs.length);- for (let i = cursor; i < end; i++) {- const lineDiv = lineDivs[i];+ // No chunk wrappers — small file, apply all ranges directly+ if (chunkWrappers.length === 0) {+ const allRanges: RangeEntry[] = [];+ const lineDivs = codeEl.querySelectorAll('[data-line]');+ for (let i = 0; i < lineDivs.length; i++) {const tokens = tokenLines[i];if (tokens && tokens.length > 0) {- applyLineRanges(lineDiv, tokens, myRanges);+ applyLineRanges(lineDivs[i], tokens, allRanges, resolve);}}- cursor = end;+ return () => cleanupRanges(allRanges);+ }- if (cursor < lineDivs.length) {- rafId = requestAnimationFrame(processChunk);+ // Chunked path — lazy application per chunk+ const chunkRanges = new Map<Element, RangeEntry[]>();+ const listeners = new Map<Element, EventListener>();++ function applyChunk(wrapper: Element, index: number) {+ if (chunkRanges.has(wrapper)) return; // already applied+ const ranges = applyRangesToContainer(+ wrapper,+ tokenLines,+ chunkLineOffsets[index],+ resolve,+ );+ chunkRanges.set(wrapper, ranges);+ }++ function removeChunk(wrapper: Element) {+ const ranges = chunkRanges.get(wrapper);+ if (ranges) {+ cleanupRanges(ranges);+ chunkRanges.delete(wrapper);}}- // First chunk synchronously for immediate partial coloring- processChunk();+ for (let i = 0; i < chunkWrappers.length; i++) {+ const wrapper = chunkWrappers[i];++ const handler = (e: Event) => {+ // contentvisibilityautostatechange fires with .skipped = true when+ // the element goes offscreen, false when it becomes visible.+ const skipped = (e as ContentVisibilityAutoStateChangeEvent).skipped;+ if (skipped) {+ removeChunk(wrapper);+ } else {+ applyChunk(wrapper, i);+ }+ };++ wrapper.addEventListener('contentvisibilityautostatechange', handler);+ listeners.set(wrapper, handler);++ // Apply immediately to chunks that are currently visible.+ // A chunk with content-visibility: auto that is onscreen will have+ // its content rendered — check via checkVisibility if available,+ // otherwise apply eagerly for the first screen's worth.+ const el = wrapper as HTMLElement & {+ checkVisibility?: (opts?: CheckVisibilityOptions) => boolean;+ };+ if (typeof el.checkVisibility === 'function') {+ if (+ el.checkVisibility({+ checkVisibilityCSS: true,+ contentVisibilityAuto: true,+ })+ ) {+ applyChunk(wrapper, i);+ }+ } else {+ // Fallback: apply first few chunks synchronously (likely visible)+ if (i < 5) {+ applyChunk(wrapper, i);+ }+ }+ }return function cleanup() {- cancelled = true;- cancelAnimationFrame(rafId);- cleanupRanges(myRanges);+ // Remove all event listeners+ for (const [wrapper, handler] of listeners) {+ wrapper.removeEventListener('contentvisibilityautostatechange', handler);+ }+ listeners.clear();++ // Clean up all active ranges+ for (const ranges of chunkRanges.values()) {+ cleanupRanges(ranges);+ }+ chunkRanges.clear();};}@@ -182,6 +320,7 @@ export function applyHighlightRangesBatch(): RangeEntry[] {ensureHighlightStyles();+ const resolve = createHighlightResolver();const lineDivs = codeEl.querySelectorAll('[data-line]');const results: RangeEntry[] = [];@@ -192,7 +331,7 @@ export function applyHighlightRangesBatch(const lineDiv = lineDivs[divIndex];const tokens = tokenLines[i];if (tokens && tokens.length > 0) {- applyLineRanges(lineDiv, tokens, results);+ applyLineRanges(lineDiv, tokens, results, resolve);}}