Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docs): stop doc prose referencing nonexistent props (#3503)

AKfce2e7bac10d
diff --git a/.changeset/codeblock-syntaxtheme-prop.md b/.changeset/codeblock-syntaxtheme-prop.md
new file mode 100644
index 0000000000..9e09c95351
--- /dev/null
+++ b/.changeset/codeblock-syntaxtheme-prop.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] CodeBlock: new `syntaxTheme` prop for per-instance syntax theme overrides. Shorthand for wrapping a single block in `<SyntaxTheme theme={...}>` — accepts a preset from `@astryxdesign/core/theme/syntax` or a theme created with `defineSyntaxTheme()` (#3360).
+@AKnassa
diff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjs
index 4b55b31e62..8a220e7db1 100644
--- a/packages/core/src/CodeBlock/CodeBlock.doc.mjs
+++ b/packages/core/src/CodeBlock/CodeBlock.doc.mjs
@@ -90,6 +90,11 @@ export const docs = {
type: '(code: string, language: string) => Array<{type: string; start: number; end: number}>',
description: 'Custom tokenizer override for unsupported languages.',
},
+ {
+ name: 'syntaxTheme',
+ type: 'SyntaxThemeDefinition',
+ description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',
+ },
{
name: 'isCollapsible',
type: 'boolean',
diff --git a/packages/core/src/CodeBlock/CodeBlock.test.tsx b/packages/core/src/CodeBlock/CodeBlock.test.tsx
index 721e845498..6a0db662a7 100644
--- a/packages/core/src/CodeBlock/CodeBlock.test.tsx
+++ b/packages/core/src/CodeBlock/CodeBlock.test.tsx
@@ -3,7 +3,7 @@
/**
* @file CodeBlock.test.tsx
* @input Uses vitest, @testing-library/react, CodeBlock component
- * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y)
+ * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y, syntaxTheme)
* @position Testing; validates CodeBlock implementation
*
* SYNC: When CodeBlock.tsx changes, update tests to match new behavior
@@ -12,6 +12,7 @@
import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
import {CodeBlock} from './CodeBlock';
+import {dracula} from '../theme/syntax';
// A code sample long enough to exceed the default collapsible threshold (10).
const LONG_CODE = Array.from(
@@ -112,4 +113,26 @@ describe('CodeBlock', () => {
fireEvent.click(header);
expect(header).toHaveAttribute('aria-expanded', 'false');
});
+
+ it('applies a per-instance syntax theme via the syntaxTheme prop', () => {
+ const {container} = render(
+ <CodeBlock
+ code="const x = 1;"
+ language="javascript"
+ syntaxTheme={dracula}
+ />,
+ );
+ const wrapper = container.querySelector('[data-astryx-syntax-theme]');
+ expect(wrapper).not.toBeNull();
+ expect(wrapper).toHaveAttribute('data-astryx-syntax-theme', 'dracula');
+ expect(wrapper!.querySelector('pre')).not.toBeNull();
+ });
+
+ it('renders no syntax theme wrapper when syntaxTheme is not set', () => {
+ const {container} = render(
+ <CodeBlock code="const x = 1;" language="javascript" />,
+ );
+ expect(container.querySelector('[data-astryx-syntax-theme]')).toBeNull();
+ expect(container.firstElementChild?.tagName).toBe('PRE');
+ });
});
diff --git a/packages/core/src/CodeBlock/CodeBlock.tsx b/packages/core/src/CodeBlock/CodeBlock.tsx
index ce40a74c77..0a3cde4945 100644
--- a/packages/core/src/CodeBlock/CodeBlock.tsx
+++ b/packages/core/src/CodeBlock/CodeBlock.tsx
@@ -3,7 +3,7 @@
'use client';
/**
* @file CodeBlock.tsx
- * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API
+ * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API, SyntaxTheme provider
* @output Exports CodeBlock component and CodeBlockProps
* @position Core implementation; read-only syntax-highlighted code display
*/
@@ -43,6 +43,7 @@ import type {SyntaxToken, TokenLine} from './tokenizer';
import {ensureHighlightStyles} from './highlightStyles';
import {applyHighlightRangesChunked} from './highlightRanges';
import {themeProps} from '../utils/themeProps';
+import {SyntaxTheme, type SyntaxThemeDefinition} from '../theme/syntax';
// ---------------------------------------------------------------------------
// Styles
@@ -382,6 +383,14 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
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;
}
// ---------------------------------------------------------------------------
@@ -633,6 +642,7 @@ export function CodeBlock({
container = 'card',
tokenizer: customTokenizer,
highlightMode = 'auto',
+ syntaxTheme,
xstyle,
className,
style,
@@ -802,7 +812,7 @@ export function CodeBlock({
</div>
);
- return (
+ const block = (
<pre
ref={ref}
{...mergeProps(
@@ -832,6 +842,12 @@ export function CodeBlock({
{!showHeader && copyButtonEl}
</pre>
);
+
+ return syntaxTheme ? (
+ <SyntaxTheme theme={syntaxTheme}>{block}</SyntaxTheme>
+ ) : (
+ block
+ );
}
CodeBlock.displayName = 'CodeBlock';
diff --git a/packages/core/src/Layout/LayoutContent.doc.mjs b/packages/core/src/Layout/LayoutContent.doc.mjs
index 6f38c5cec0..56a862a4e2 100644
--- a/packages/core/src/Layout/LayoutContent.doc.mjs
+++ b/packages/core/src/Layout/LayoutContent.doc.mjs
@@ -14,6 +14,12 @@ export const docs = {
type: 'ReactNode',
description: 'Content.',
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description:
+ 'Internal padding using the spacing scale. Overrides the default padding from the layout container.',
+ },
{
name: 'isScrollable',
type: 'boolean',
@@ -44,6 +50,11 @@ export const docsZh = {
type: 'ReactNode',
description: '内容。',
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description: '使用间距比例的内边距。覆盖布局容器的默认内边距。',
+ },
{
name: 'isScrollable',
type: 'boolean',
@@ -70,6 +81,7 @@ export const docsDense = {
description: 'Scrollable main content area.',
propDescriptions: {
children: 'Content.',
+ padding: 'Internal padding on spacing scale. Overrides layout container default.',
isScrollable: 'Enable scrollable overflow.',
label: 'Accessible label for landmark element.',
role: 'ARIA landmark role.',
diff --git a/packages/core/src/Layout/LayoutPanel.doc.mjs b/packages/core/src/Layout/LayoutPanel.doc.mjs
index 074faa70dd..6dd4068554 100644
--- a/packages/core/src/Layout/LayoutPanel.doc.mjs
+++ b/packages/core/src/Layout/LayoutPanel.doc.mjs
@@ -20,6 +20,12 @@ export const docs = {
description: 'Border on the appropriate edge.',
default: 'false',
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description:
+ 'Internal padding using the spacing scale. Overrides the default padding from the layout container.',
+ },
{
name: 'isScrollable',
type: 'boolean',
@@ -36,6 +42,18 @@ export const docs = {
type: 'AriaRole',
description: 'ARIA landmark role.',
},
+ {
+ name: 'width',
+ type: 'number | string',
+ description:
+ 'Width of the panel. Numbers are treated as pixels, strings are used as-is. Ignored when resizable is provided; the hook controls width.',
+ },
+ {
+ name: 'resizable',
+ type: 'ResizableProps',
+ description:
+ 'Resize props from useResizable(). When provided, the hook drives the panel width and a ResizeHandle should be placed adjacent to the panel.',
+ },
],
};
@@ -56,6 +74,11 @@ export const docsZh = {
description: '相应边缘的边框。',
default: 'false',
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description: '使用间距比例的内边距。覆盖布局容器的默认内边距。',
+ },
{
name: 'isScrollable',
type: 'boolean',
@@ -72,6 +95,18 @@ export const docsZh = {
type: 'AriaRole',
description: 'ARIA 地标角色。',
},
+ {
+ name: 'width',
+ type: 'number | string',
+ description:
+ '面板宽度。数字按像素处理,字符串按原样使用。提供 resizable 时忽略,宽度由 hook 控制。',
+ },
+ {
+ name: 'resizable',
+ type: 'ResizableProps',
+ description:
+ '来自 useResizable() 的调整大小属性。提供时面板宽度由 hook 驱动,应在面板旁放置 ResizeHandle。',
+ },
],
};
@@ -83,8 +118,13 @@ export const docsDense = {
propDescriptions: {
children: 'Panel content.',
hasDivider: 'Border on appropriate edge.',
+ padding: 'Internal padding on spacing scale. Overrides layout container default.',
isScrollable: 'Enable scrollable overflow.',
label: 'Accessible label for landmark element.',
role: 'ARIA landmark role.',
+ width:
+ 'Panel width. Numbers = pixels, strings as-is. Ignored when resizable provided; hook controls width.',
+ resizable:
+ 'Resize props from useResizable(). Hook drives panel width; place ResizeHandle adjacent.',
},
};
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 07e88056fd..cd31a59f9f 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -102,6 +102,12 @@ export const docs = {
description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',
default: 'false',
},
+ {
+ name: 'resizable',
+ type: 'boolean | { defaultWidth?: number; minWidth?: number; maxWidth?: number; autoSaveId?: string; onWidthChange?: (width: number) => void }',
+ description: 'Enables a resize handle at the inline-end edge. true for defaults (260px initial, 180-480px range), or a ResizableConfig object (defaultWidth, minWidth, maxWidth, autoSaveId for localStorage persistence, onWidthChange). The handle is hidden while collapsed.',
+ default: 'false',
+ },
{
name: 'handleRef',
type: 'Ref<SideNavImperativeCollapseHandle>',
diff --git a/packages/core/src/docPropReferences.test.ts b/packages/core/src/docPropReferences.test.ts
new file mode 100644
index 0000000000..7c35ddc9fe
--- /dev/null
+++ b/packages/core/src/docPropReferences.test.ts
@@ -0,0 +1,178 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * @file Guards doc prose against docs/source prop mismatches (#3360).
+ *
+ * Scans every {Name}.doc.mjs for prose phrases like "the foo prop on Bar"
+ * and verifies the referenced prop is documented on the referenced
+ * component. Doc prose is LLM training signal: a reference to a prop that
+ * doesn't exist steers codegen toward hallucinated APIs (#3360 shipped a
+ * bullet pointing at a nonexistent CodeBlock syntaxTheme prop).
+ *
+ * A reference to a missing prop is allowed only when the same string
+ * explicitly negates it ("no such prop exists" / "does not exist"), the
+ * corrective-bullet pattern used to counter known hallucinations.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readdirSync} from 'fs';
+import {join, relative} from 'path';
+
+const SRC_DIR = __dirname;
+
+type DocModule = {
+ docs?: {
+ name?: string;
+ props?: {name: string}[];
+ components?: {name?: string; props?: {name: string}[]}[];
+ };
+};
+
+/**
+ * Props intentionally omitted from doc props[]: PropDoc in docs-types.ts
+ * says to skip internal/styling props, so prose may reference them even
+ * though no doc lists them.
+ */
+const UNIVERSAL_PROPS = new Set([
+ 'xstyle',
+ 'className',
+ 'style',
+ 'ref',
+ 'data-testid',
+]);
+
+/**
+ * Matches prose like "the foo prop on Bar", "foo prop of Bar", and
+ * conjunction targets: "foo prop on Bar or Baz". Group 1 is the prop
+ * (camelCase, lowercase first letter), group 2 the component name list.
+ */
+const PROP_REF_PATTERN =
+ /\b([a-z][A-Za-z0-9]*) prop (?:on|of) (?:the )?([A-Z][A-Za-z0-9]*(?:(?:,(?: and| or)?| and| or) [A-Z][A-Za-z0-9]*)*)/g;
+
+/** A same-string negation marks the reference as a deliberate counter-signal. */
+const NEGATION_PATTERN = /no such prop|does not exist|doesn't exist/i;
+
+function findDocFiles(dir: string): string[] {
+ const files: string[] = [];
+ for (const entry of readdirSync(dir, {withFileTypes: true})) {
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ files.push(...findDocFiles(full));
+ } else if (entry.name.endsWith('.doc.mjs')) {
+ files.push(full);
+ }
+ }
+ return files;
+}
+
+/** Collect every string value reachable from a doc module export. */
+function collectStrings(value: unknown, out: string[]): void {
+ if (typeof value === 'string') {
+ out.push(value);
+ } else if (Array.isArray(value)) {
+ for (const item of value) {
+ collectStrings(item, out);
+ }
+ } else if (value && typeof value === 'object') {
+ for (const item of Object.values(value)) {
+ collectStrings(item, out);
+ }
+ }
+}
+
+const docFiles = findDocFiles(SRC_DIR);
+
+// Component name → documented prop names, from every doc file's props[]
+// (single and sub-component docs) and inline components[] entries.
+const documentedProps = new Map<string, Set<string>>();
+for (const file of docFiles) {
+ const mod = require(file) as DocModule;
+ const docs = mod.docs;
+ if (!docs) {
+ continue;
+ }
+ const entries = [
+ {name: docs.name, props: docs.props},
+ ...(docs.components || []),
+ ];
+ for (const {name, props} of entries) {
+ if (!name || !Array.isArray(props)) {
+ continue;
+ }
+ const set = documentedProps.get(name) || new Set<string>();
+ for (const prop of props) {
+ set.add(prop.name);
+ }
+ documentedProps.set(name, set);
+ }
+}
+
+interface Violation {
+ file: string;
+ component: string;
+ prop: string;
+ excerpt: string;
+}
+
+function findViolations(): Violation[] {
+ const violations: Violation[] = [];
+ for (const file of docFiles) {
+ const strings: string[] = [];
+ collectStrings(require(file), strings);
+ for (const text of strings) {
+ let match;
+ while ((match = PROP_REF_PATTERN.exec(text)) !== null) {
+ const [, prop, componentList] = match;
+ if (UNIVERSAL_PROPS.has(prop) || NEGATION_PATTERN.test(text)) {
+ continue;
+ }
+ for (const component of componentList.split(
+ /,(?: and| or)?| and | or /,
+ )) {
+ const name = component.trim();
+ if (!name) {
+ continue;
+ }
+ const known = documentedProps.get(name);
+ if (known && !known.has(prop)) {
+ violations.push({
+ file: relative(SRC_DIR, file),
+ component: name,
+ prop,
+ excerpt: text.slice(
+ Math.max(0, match.index - 40),
+ match.index + match[0].length + 20,
+ ),
+ });
+ }
+ }
+ }
+ }
+ }
+ return violations;
+}
+
+describe('doc prose prop references', () => {
+ it('sanity: discovers doc files and documented components', () => {
+ expect(docFiles.length).toBeGreaterThan(0);
+ expect(documentedProps.size).toBeGreaterThan(0);
+ });
+
+ it('every "X prop on Y" reference names a documented prop of Y', () => {
+ const violations = findViolations();
+ expect(
+ violations,
+ violations
+ .map(
+ v =>
+ `${v.file} references prop "${v.prop}" on ${v.component}, ` +
+ `which does not document it (…${v.excerpt}…). Either the prop ` +
+ `doesn't exist (fix the prose; negate with "no such prop ` +
+ `exists" if countering a known hallucination) or it exists in ` +
+ `source but is missing from the component's doc props[] (add it).`,
+ )
+ .join('\n'),
+ ).toEqual([]);
+ });
+});
diff --git a/packages/core/src/theme/SyntaxTheme.doc.mjs b/packages/core/src/theme/SyntaxTheme.doc.mjs
index ab792c4cc5..f00eb6237e 100644
--- a/packages/core/src/theme/SyntaxTheme.doc.mjs
+++ b/packages/core/src/theme/SyntaxTheme.doc.mjs
@@ -50,9 +50,9 @@ export const docs = {
'Syntax themes support light-dark() tuples: each token can have different values for light and dark mode, resolved automatically by the color scheme.',
},
{
- guidance: false,
+ guidance: true,
description:
- 'Wrap individual CodeBlock instances with SyntaxTheme: use the syntaxTheme prop on CodeBlock directly for per-instance overrides.',
+ 'For a single CodeBlock, pass the syntaxTheme prop directly — it is shorthand for wrapping that block in SyntaxTheme. Use the SyntaxTheme wrapper when theming a whole region of code components.',
},
],
},
@@ -96,9 +96,9 @@ export const docsDense = {
'Syntax themes support light-dark() tuples: each token can have different values for light/dark mode, resolved automatically by color scheme.',
},
{
- guidance: false,
+ guidance: true,
description:
- 'Wrap individual CodeBlock instances w/ SyntaxTheme: use syntaxTheme prop on CodeBlock directly for per-instance overrides instead.',
+ 'Single CodeBlock: pass syntaxTheme prop (shorthand for wrapping in SyntaxTheme). Whole region of code components: wrap w/ SyntaxTheme.',
},
],
},
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index 76c35306f2..7c5d8167fa 100644
--- a/packages/core/src/theme/defineTheme.ts
+++ b/packages/core/src/theme/defineTheme.ts
@@ -56,14 +56,8 @@ import {
generateTypeScaleComponents,
type TypeScaleConfig,
} from './expandTypeScale';
-import {
- expandMotionScale,
- type MotionScaleConfig,
-} from './expandMotionScale';
-import {
- expandRadiusScale,
- type RadiusScaleConfig,
-} from './expandRadiusScale';
+import {expandMotionScale, type MotionScaleConfig} from './expandMotionScale';
+import {expandRadiusScale, type RadiusScaleConfig} from './expandRadiusScale';
import {expandColorScale, type ColorScaleConfig} from './expandColorScale';
import type {DomainTokenName} from './domainTokens';
@@ -153,10 +147,7 @@ export type StyleOverrides = Record<string, string | Record<string, string>>;
* }
* ```
*/
-export type ComponentStyleMap = Record<
- string,
- Record<string, StyleOverrides>
->;
+export type ComponentStyleMap = Record<string, Record<string, StyleOverrides>>;
/** Input to defineTheme */
export interface DefineThemeInput {
@@ -287,7 +278,7 @@ export interface DefineThemeInput {
/**
* Default syntax highlighting theme for code components.
* Sets --color-syntax-* tokens at the theme root. Can be overridden
- * per-region via SyntaxTheme or per-instance via syntaxTheme prop.
+ * per-region (or per-instance) by wrapping in SyntaxTheme.
*
* @example
* ```tsx