Skip to content

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.md
new file mode 100644
index 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
+@nbozidarevic
diff --git a/apps/storybook/stories/CodeBlock.stories.tsx b/apps/storybook/stories/CodeBlock.stories.tsx
index 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.mjs
index 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.tsx
new file mode 100644
index 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.tsx
index 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 (
<div
key={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(
<CodeChunk
lines={lines}
startIndex={0}
+ startLineNumber={startLineNumber}
highlightSet={highlightSet}
diffKinds={diffKinds}
renderLineContent={renderLineContent}
@@ -536,6 +542,7 @@ function renderLines(
<CodeChunk
lines={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>