An open source design system that's fully customizable and agent ready
TypeScript
feat(codeblock): add startLineNumber prop for excerpts (#8854)
Nenad Božidarevića3dab7afd12e
diff --git a/.changeset/codeblock-adds-startlinenumber-so-code-excerpts--amwn.md b/.changeset/codeblock-adds-startlinenumber-so-code-excerpts--amwn.mdnew file mode 100644index 0000000000..c7f2dfb0d3--- /dev/null+++ b/.changeset/codeblock-adds-startlinenumber-so-code-excerpts--amwn.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[feat] CodeBlock adds startLineNumber so code excerpts show real file line numbers+@nbozidarevicdiff --git a/apps/storybook/stories/CodeBlock.stories.tsx b/apps/storybook/stories/CodeBlock.stories.tsxindex 81e9cdb67a..18bd278b54 100644--- a/apps/storybook/stories/CodeBlock.stories.tsx+++ b/apps/storybook/stories/CodeBlock.stories.tsx@@ -498,3 +498,23 @@ export const Collapsible: Story = {isCollapsible: true,},};++/**+ * A code excerpt: N lines around a point of interest, with the gutter+ * showing the lines' real file numbers. highlightLines uses the same file+ * coordinates, so the point of interest stays emphasized.+ */+export const Excerpt: Story = {+ args: {+ code: ` const response = await fetch(\`/api/users/\${id}\`);+ if (!response.ok) {+ throw new Error(\`HTTP \${response.status}\`);+ }+ return response.json();`,+ language: 'typescript',+ title: 'useUser.ts — lines 40–44',+ hasLineNumbers: true,+ startLineNumber: 40,+ highlightLines: [42],+ },+};diff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjsindex 60f20047f5..05de6ecefe 100644--- a/packages/core/src/CodeBlock/CodeBlock.doc.mjs+++ b/packages/core/src/CodeBlock/CodeBlock.doc.mjs@@ -51,10 +51,18 @@ export const docs = {description: 'Show a line number gutter.',default: 'false',},+ {+ name: 'startLineNumber',+ type: 'number',+ description:+ 'First line number shown in the gutter. The gutter shows file coordinates (startLineNumber + index) so a code excerpt reads with its real line numbers. highlightLines uses the same file coordinates. Values below 1 clamp to 1.',+ default: '1',+ },{name: 'highlightLines',type: 'number[]',- description: '1-indexed line numbers to highlight.',+ description:+ '1-indexed line numbers to highlight, in the same file coordinates as the gutter (see startLineNumber). Out-of-range entries render no highlight.',},{name: 'isDiff',diff --git a/packages/core/src/CodeBlock/CodeBlock.startLineNumber.test.tsx b/packages/core/src/CodeBlock/CodeBlock.startLineNumber.test.tsxnew file mode 100644index 0000000000..571c583b9b--- /dev/null+++ b/packages/core/src/CodeBlock/CodeBlock.startLineNumber.test.tsx@@ -0,0 +1,121 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file CodeBlock.startLineNumber.test.tsx+ * @input Uses vitest, @testing-library/react, CodeBlock component+ * @output Unit tests for the CodeBlock startLineNumber excerpt offset+ * @position Testing; validates startLineNumber gutter and highlight mapping+ *+ * SYNC: When CodeBlock.tsx changes, update tests to match new behavior+ */++import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';+import {render, screen, fireEvent} from '@testing-library/react';+import {CodeBlock} from './CodeBlock';+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';++const EXCERPT = ['const a = 1;', 'const b = 2;', 'const c = 3;'].join('\n');++function lineNumbers(container: HTMLElement): (string | null)[] {+ return Array.from(container.querySelectorAll('[data-line]')).map(row =>+ row.getAttribute('data-line'),+ );+}++function rowClasses(container: HTMLElement): string[] {+ return Array.from(container.querySelectorAll('[data-line]')).map(+ row => (row as HTMLElement).className,+ );+}++describe('CodeBlock startLineNumber', () => {+ beforeEach(() => {+ Object.assign(navigator, {+ clipboard: {writeText: vi.fn().mockResolvedValue(undefined)},+ });+ });++ afterEach(() => {+ __resetLiveRegionsForTest();+ });++ it('numbers the gutter from 1 by default', () => {+ const {container} = render(+ <CodeBlock code={EXCERPT} language="plaintext" hasLineNumbers />,+ );+ expect(lineNumbers(container)).toEqual(['1', '2', '3']);+ });++ it('shows file coordinates in the gutter from startLineNumber', () => {+ const {container} = render(+ <CodeBlock+ code={EXCERPT}+ language="plaintext"+ hasLineNumbers+ startLineNumber={40}+ />,+ );+ expect(lineNumbers(container)).toEqual(['40', '41', '42']);+ });++ it('interprets highlightLines in the same file coordinates', () => {+ const {container} = render(+ <CodeBlock+ code={EXCERPT}+ language="plaintext"+ hasLineNumbers+ startLineNumber={40}+ highlightLines={[42]}+ />,+ );+ const classes = rowClasses(container);+ expect(classes).toHaveLength(3);+ // The third rendered line (file line 42) carries the highlight paint,+ // the first two share the unhighlighted row classes.+ expect(classes[0]).toBe(classes[1]);+ expect(classes[2]).not.toBe(classes[0]);+ });++ it('clamps a startLineNumber below 1 to 1', () => {+ const {container} = render(+ <CodeBlock+ code={EXCERPT}+ language="plaintext"+ hasLineNumbers+ startLineNumber={0}+ />,+ );+ expect(lineNumbers(container)).toEqual(['1', '2', '3']);+ });++ it('treats out-of-range highlightLines as a no-op without crashing', () => {+ const {container} = render(+ <CodeBlock+ code={EXCERPT}+ language="plaintext"+ hasLineNumbers+ startLineNumber={40}+ highlightLines={[1, 2, 39, 43, 100]}+ />,+ );+ expect(lineNumbers(container)).toEqual(['40', '41', '42']);+ // No row is highlighted: every row shares the same classes.+ const classes = rowClasses(container);+ expect(classes[0]).toBe(classes[1]);+ expect(classes[1]).toBe(classes[2]);+ });++ it('keeps copy exact while offsetting the gutter', () => {+ const {container} = render(+ <CodeBlock+ code={EXCERPT}+ language="plaintext"+ hasLineNumbers+ startLineNumber={40}+ />,+ );+ expect(lineNumbers(container)).toEqual(['40', '41', '42']);+ fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));+ expect(navigator.clipboard.writeText).toHaveBeenCalledWith(EXCERPT);+ });+});diff --git a/packages/core/src/CodeBlock/CodeBlock.tsx b/packages/core/src/CodeBlock/CodeBlock.tsxindex 303229aac0..cca7c43123 100644--- a/packages/core/src/CodeBlock/CodeBlock.tsx+++ b/packages/core/src/CodeBlock/CodeBlock.tsx@@ -456,6 +456,7 @@ const LINE_CHUNK_THRESHOLD = 100;const CodeChunk = React.memo(function CodeChunk({lines,startIndex,+ startLineNumber,highlightSet,diffKinds,renderLineContent,@@ -463,6 +464,7 @@ const CodeChunk = React.memo(function CodeChunk({}: {lines: string[];startIndex: number;+ startLineNumber: number;highlightSet: Set<number> | null;diffKinds: ReadonlyArray<DiffLineKind> | null;renderLineContent: (line: string, lineIndex: number) => React.ReactNode;@@ -472,11 +474,12 @@ const CodeChunk = React.memo(function CodeChunk({<>{lines.map((line, j) => {const i = startIndex + j;+ const lineNumber = startLineNumber + i;const diffKind = diffKinds?.[i];return (<divkey={i}- data-line={i + 1}+ data-line={lineNumber}data-diff={diffKind === 'context' ? undefined : diffKind}{...stylex.props(styles.line,@@ -488,7 +491,8 @@ const CodeChunk = React.memo(function CodeChunk({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(i + 1) ?? false) && styles.lineHighlighted,+ (highlightSet?.has(lineNumber) ?? false) &&+ styles.lineHighlighted,)}>{renderLineContent(line, i)}</div>@@ -504,6 +508,7 @@ function renderLines(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));@@ -513,6 +518,7 @@ function renderLines(<CodeChunklines={lines}startIndex={0}+ startLineNumber={startLineNumber}highlightSet={highlightSet}diffKinds={diffKinds}renderLineContent={renderLineContent}@@ -536,6 +542,7 @@ function renderLines(<CodeChunklines={chunkLines}startIndex={start}+ startLineNumber={startLineNumber}highlightSet={highlightSet}diffKinds={diffKinds}renderLineContent={renderLineContent}@@ -566,6 +573,15 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {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@@ -792,6 +808,7 @@ function SpanCodeContent({sizeStyle,hasLineNumbers,maxDigits,+ startLineNumber,}: {lines: string[];tokenLines: TokenLine[];@@ -802,6 +819,7 @@ function SpanCodeContent({sizeStyle: stylex.StyleXStyles;hasLineNumbers: boolean;maxDigits: number;+ startLineNumber: number;}) {useInsertionEffect(() => {ensureHighlightStyles();@@ -861,6 +879,7 @@ function SpanCodeContent({diffKinds,renderLineContent,hasLineNumbers,+ startLineNumber,)}</code>);@@ -879,6 +898,7 @@ function RangeCodeContent({sizeStyle,hasLineNumbers,maxDigits,+ startLineNumber,}: {lines: string[];tokenLines: TokenLine[];@@ -888,6 +908,7 @@ function RangeCodeContent({sizeStyle: stylex.StyleXStyles;hasLineNumbers: boolean;maxDigits: number;+ startLineNumber: number;}) {const codeRef = useRef<HTMLElement>(null);@@ -939,6 +960,7 @@ function RangeCodeContent({diffKinds,renderLineContent,hasLineNumbers,+ startLineNumber,)}</code>);@@ -963,6 +985,7 @@ export function CodeBlock({title,hasLanguageLabel = true,hasLineNumbers = false,+ startLineNumber = 1,highlightLines,isDiff = false,hasCopyButton = true,@@ -1019,6 +1042,12 @@ export function CodeBlock({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],@@ -1032,8 +1061,10 @@ export function CodeBlock({}, [code, copy, onCopy]);const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;- // Digits in the largest line number — sizes the gutter column width.- const maxLineDigits = String(lines.length).length;+ // 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.@@ -1219,6 +1250,7 @@ export function CodeBlock({sizeStyle={sizeStyle}hasLineNumbers={hasLineNumbers}maxDigits={maxLineDigits}+ startLineNumber={effectiveStartLineNumber}/>) : (<RangeCodeContent@@ -1230,6 +1262,7 @@ export function CodeBlock({sizeStyle={sizeStyle}hasLineNumbers={hasLineNumbers}maxDigits={maxLineDigits}+ startLineNumber={effectiveStartLineNumber}/>)}</div>