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.mdnew file mode 100644index 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).+@AKnassadiff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjsindex 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.tsxindex 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.tsxindex 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 = (<preref={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.mjsindex 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.mjsindex 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.mjsindex 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.tsnew file mode 100644index 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.mjsindex 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.tsindex 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