An open source design system that's fully customizable and agent ready
TypeScript
test(theme): fail when a prop that selects painted styles never reaches themeProps() (#10147)
Cindy Zhang83b99dd45c3f
diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.tsindex aea8e3b597..c9adc04b0e 100644--- a/packages/core/src/theme/themingTargets.test.ts+++ b/packages/core/src/theme/themingTargets.test.ts@@ -2,11 +2,14 @@/* eslint-disable @typescript-eslint/no-require-imports *//**- * @file Guards `theming.targets` against the real `themeProps()` call sites (#3741).+ * @file Guards `theming.targets` against the real `themeProps()` call sites,+ * and guards that each prop that selects painted styles reaches+ * `themeProps()`.* @input Core/Lab component sources (*.tsx/*.ts), their `{Name}.doc.mjs`* files, and the Lab promotion-candidate manifest.- * @output Vitest failures naming each undocumented class / visual prop on the- * stable Core surface or a capability-participating Lab component.+ * @output Vitest failures naming each undocumented class / visual prop, and+ * each painted prop axis that no `themeProps()` call passes, on the stable+ * Core surface or a capability-participating Lab component.* @position Sibling of derivedVarRegistry.test.ts, which already validates the* OTHER fields of the same `theming` block (`vars`, `derived`). `targets` was* the one field with no machine check, so it drifted — twice (#3652, #3680).@@ -324,6 +327,396 @@ describe('extractThemeTargets', () => {});});+// ---------------------------------------------------------------------------+// Painted prop axes: a prop that selects painted styles must reach themeProps()+// ---------------------------------------------------------------------------++/**+ * The shared catalog of style keys that a target can guarantee to a theme. A+ * style map that sets one of these keys paints, so a prop that selects from it+ * is a visual axis. A map that sets none of them, for example a gap scale,+ * changes only layout and does not need a selector.+ */+const GUARANTEED_STYLE_KEYS: ReadonlySet<string> = new Set([+ // Paint+ 'color',+ 'backgroundColor',+ 'opacity',+ 'outlineColor',+ 'outlineOffset',+ 'outlineStyle',+ 'outlineWidth',+ 'boxShadow',+ 'textShadow',+ // Border and shape+ 'borderColor',+ 'borderStyle',+ 'borderWidth',+ 'borderRadius',+ // Typography+ 'fontFamily',+ 'fontSize',+ 'fontStyle',+ 'fontWeight',+ 'letterSpacing',+ 'lineHeight',+ 'textAlign',+ 'textDecorationColor',+ 'textDecorationLine',+ 'textDecorationStyle',+ 'textDecorationThickness',+ 'textTransform',+ // Padding+ 'padding',+ 'paddingBlock',+ 'paddingBlockStart',+ 'paddingBlockEnd',+ 'paddingInline',+ 'paddingInlineStart',+ 'paddingInlineEnd',+]);++interface UnreflectedStyleAxis {+ /** The function that destructures the prop, e.g. 'ChatComposer'. */+ component: string;+ /** The prop name, not its local binding, e.g. 'elevation'. */+ prop: string;+ /** The `stylex.create()` map the prop indexes, e.g. 'elevationStyles'. */+ styleMap: string;+ line: number;+}++type FunctionNode =+ ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction;++function isFunctionNode(node: ts.Node): node is FunctionNode {+ return (+ ts.isFunctionDeclaration(node) ||+ ts.isFunctionExpression(node) ||+ ts.isArrowFunction(node)+ );+}++function isStylexCall(node: ts.Node, method: string): boolean {+ return (+ ts.isCallExpression(node) &&+ ts.isPropertyAccessExpression(node.expression) &&+ ts.isIdentifier(node.expression.expression) &&+ node.expression.expression.text === 'stylex' &&+ node.expression.name.text === method+ );+}++/** Names of the `stylex.create()` maps in a file that set a guaranteed key. */+function paintingStyleMaps(sourceFile: ts.SourceFile): Set<string> {+ const maps = new Set<string>();+ const visit = (node: ts.Node): void => {+ if (+ ts.isVariableDeclaration(node) &&+ ts.isIdentifier(node.name) &&+ node.initializer != null &&+ isStylexCall(node.initializer, 'create')+ ) {+ const [namespaces] = (node.initializer as ts.CallExpression).arguments;+ const paints =+ namespaces != null &&+ ts.isObjectLiteralExpression(namespaces) &&+ namespaces.properties.some(+ namespace =>+ ts.isPropertyAssignment(namespace) &&+ ts.isObjectLiteralExpression(namespace.initializer) &&+ namespace.initializer.properties.some(+ style =>+ style.name != null &&+ (ts.isIdentifier(style.name) ||+ ts.isStringLiteralLike(style.name)) &&+ GUARANTEED_STYLE_KEYS.has(style.name.text),+ ),+ );+ if (paints) {+ maps.add(node.name.text);+ }+ }+ ts.forEachChild(node, visit);+ };+ visit(sourceFile);+ return maps;+}++/**+ * Local binding -> prop name for the props a function destructures, from its+ * first parameter or from `const {...} = props` at the top of its body.+ */+function destructuredProps(fn: FunctionNode): Map<string, string> {+ const bindings = new Map<string, string>();+ const read = (pattern: ts.ObjectBindingPattern): void => {+ for (const element of pattern.elements) {+ if (element.dotDotDotToken != null || !ts.isIdentifier(element.name)) {+ continue;+ }+ const propName = element.propertyName ?? element.name;+ if (ts.isIdentifier(propName) || ts.isStringLiteralLike(propName)) {+ bindings.set(element.name.text, propName.text);+ }+ }+ };+ const [first] = fn.parameters;+ if (first == null) {+ return bindings;+ }+ if (ts.isObjectBindingPattern(first.name)) {+ read(first.name);+ } else if (+ ts.isIdentifier(first.name) &&+ fn.body != null &&+ ts.isBlock(fn.body)+ ) {+ const propsName = first.name.text;+ for (const statement of fn.body.statements) {+ if (!ts.isVariableStatement(statement)) {+ continue;+ }+ for (const declaration of statement.declarationList.declarations) {+ if (+ ts.isObjectBindingPattern(declaration.name) &&+ declaration.initializer != null &&+ ts.isIdentifier(declaration.initializer) &&+ declaration.initializer.text === propsName+ ) {+ read(declaration.name);+ }+ }+ }+ }+ return bindings;+}++function functionName(fn: FunctionNode): string {+ if (fn.name != null) {+ return fn.name.text;+ }+ const {parent} = fn;+ if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {+ return parent.name.text;+ }+ return '(anonymous)';+}++/**+ * Each prop that indexes a painting style map inside `stylex.props()` while no+ * `themeProps()` call in the same function passes that prop. A theme can then+ * restyle the target but cannot tell the prop's values apart.+ *+ * A function that destructures props is one component. A nested function that+ * destructures its own props is a separate component and is checked by+ * itself; a nested callback that does not, such as a render callback, belongs+ * to the function around it.+ */+function findUnreflectedStyleAxes(+ sourceText: string,+ fileName = 'source.tsx',+): UnreflectedStyleAxis[] {+ const sourceFile = ts.createSourceFile(+ fileName,+ sourceText,+ ts.ScriptTarget.Latest,+ /* setParentNodes */ true,+ fileName.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,+ );+ const paintingMaps = paintingStyleMaps(sourceFile);+ const findings: UnreflectedStyleAxis[] = [];++ const checkComponent = (fn: FunctionNode, props: Map<string, string>) => {+ const reflected = new Set<string>();+ let reflectsUnknownKeys = false;+ const lookups: Omit<UnreflectedStyleAxis, 'component'>[] = [];++ const visit = (node: ts.Node, isInStyleCall: boolean): void => {+ if (+ node !== fn &&+ isFunctionNode(node) &&+ destructuredProps(node).size > 0+ ) {+ return;+ }+ if (+ ts.isCallExpression(node) &&+ ts.isIdentifier(node.expression) &&+ node.expression.text === 'themeProps'+ ) {+ const propsArg = node.arguments[1];+ if (propsArg != null && ts.isObjectLiteralExpression(propsArg)) {+ for (const property of propsArg.properties) {+ const keys = ts.isSpreadAssignment(property)+ ? conditionalSpreadKeys(property.expression)+ : property.name != null &&+ (ts.isIdentifier(property.name) ||+ ts.isStringLiteralLike(property.name))+ ? [property.name.text]+ : null;+ if (keys == null) {+ reflectsUnknownKeys = true;+ } else {+ keys.forEach(key => reflected.add(key));+ }+ }+ } else if (propsArg != null) {+ reflectsUnknownKeys = true;+ }+ }+ const isStyleCall = isInStyleCall || isStylexCall(node, 'props');+ if (+ isStyleCall &&+ ts.isElementAccessExpression(node) &&+ ts.isIdentifier(node.expression) &&+ paintingMaps.has(node.expression.text) &&+ ts.isIdentifier(node.argumentExpression)+ ) {+ const prop = props.get(node.argumentExpression.text);+ if (prop != null) {+ lookups.push({+ prop,+ styleMap: node.expression.text,+ line:+ sourceFile.getLineAndCharacterOfPosition(node.getStart()).line ++ 1,+ });+ }+ }+ ts.forEachChild(node, child => visit(child, isStyleCall));+ };+ visit(fn, false);++ // An opaque props bag may carry the prop; reading it would be a guess.+ if (reflectsUnknownKeys) {+ return;+ }+ const component = functionName(fn);+ for (const lookup of lookups) {+ if (!reflected.has(lookup.prop)) {+ findings.push({component, ...lookup});+ }+ }+ };++ const visit = (node: ts.Node): void => {+ if (isFunctionNode(node)) {+ const props = destructuredProps(node);+ if (props.size > 0) {+ checkComponent(node, props);+ }+ }+ ts.forEachChild(node, visit);+ };+ visit(sourceFile);+ return findings;+}++describe('findUnreflectedStyleAxes', () => {+ it('flags a painted axis that no themeProps() call passes', () => {+ const source = `+ const elevationStyles = stylex.create({low: {boxShadow: 'x'}});+ export function Banner({container, status, elevation = 'low'}) {+ return (+ <div {...stylex.props(styles.root, elevationStyles[elevation])}>+ <div {...mergeProps(themeProps('banner', {container, status}))} />+ </div>+ );+ }+ `;+ expect(findUnreflectedStyleAxes(source)).toEqual([+ {+ component: 'Banner',+ prop: 'elevation',+ styleMap: 'elevationStyles',+ line: 5,+ },+ ]);+ });++ it('accepts the axis once a themeProps() call passes it', () => {+ const source = `+ const elevationStyles = stylex.create({low: {boxShadow: 'x'}});+ export function Card({elevation}) {+ return <div {...mergeProps(themeProps('card', {elevation}), stylex.props(elevationStyles[elevation]))} />;+ }+ `;+ expect(findUnreflectedStyleAxes(source)).toEqual([]);+ });++ it('matches the prop name, not its local binding', () => {+ const source = `+ const radiusStyles = stylex.create({3: {borderRadius: 'x'}});+ export function Skeleton({radius: radiusProp = 3}) {+ return <div {...mergeProps(themeProps('skeleton', {radius: radiusProp}), stylex.props(radiusStyles[radiusProp]))} />;+ }+ export function Broken({radius: radiusProp = 3}) {+ return <div {...mergeProps(themeProps('broken'), stylex.props(radiusStyles[radiusProp]))} />;+ }+ `;+ expect(+ findUnreflectedStyleAxes(source).map(f => `${f.component}.${f.prop}`),+ ).toEqual(['Broken.radius']);+ });++ it('reads props destructured from a props parameter', () => {+ const source = `+ const sizeStyles = stylex.create({sm: {fontSize: 'x'}});+ export function Code(props) {+ const {size} = props;+ return <code {...mergeProps(themeProps('code'), stylex.props(size && sizeStyles[size]))} />;+ }+ `;+ expect(+ findUnreflectedStyleAxes(source).map(f => `${f.component}.${f.prop}`),+ ).toEqual(['Code.size']);+ });++ it('ignores a map that sets only layout keys', () => {+ const source = `+ const gapStyles = stylex.create({2: {gap: 'x'}});+ export function List({gap}) {+ return <div {...mergeProps(themeProps('list'), stylex.props(gapStyles[gap]))} />;+ }+ `;+ expect(findUnreflectedStyleAxes(source)).toEqual([]);+ });++ it('ignores a lookup keyed by a value that is not a prop', () => {+ const source = `+ const sizeStyles = stylex.create({sm: {fontSize: 'x'}});+ export function Field({label}) {+ const size = useContextSize();+ return <div {...mergeProps(themeProps('field'), stylex.props(sizeStyles[size]))}>{label}</div>;+ }+ `;+ expect(findUnreflectedStyleAxes(source)).toEqual([]);+ });++ it('counts a lookup inside a render callback for the function around it', () => {+ const source = `+ const itemSizeStyles = stylex.create({md: {paddingBlock: 'x'}});+ export function Menu({items, size}) {+ const renderItem = item => <div {...stylex.props(itemSizeStyles[size])}>{item}</div>;+ return <div {...themeProps('menu')}>{items.map(renderItem)}</div>;+ }+ `;+ expect(+ findUnreflectedStyleAxes(source).map(f => `${f.component}.${f.prop}`),+ ).toEqual(['Menu.size']);+ });++ it('skips a function whose themeProps() keys it cannot read', () => {+ const source = `+ const sizeStyles = stylex.create({sm: {fontSize: 'x'}});+ export function Opaque({size, ...rest}) {+ return <div {...mergeProps(themeProps('opaque', rest), stylex.props(sizeStyles[size]))} />;+ }+ `;+ expect(findUnreflectedStyleAxes(source)).toEqual([]);+ });+});+// ---------------------------------------------------------------------------// Discovery: every component dir's rendered classes vs its documented targets// ---------------------------------------------------------------------------@@ -341,6 +734,8 @@ interface ComponentInfo {packageName: 'core' | 'lab' | 'richtext';dir: string;sites: ThemeTargetSite[];+ /** Absolute paths of the source files in `dir`, without tests. */+ sourceFiles: string[];/** The doc blocks that carry theming.targets, by the key they live under. */docBlocks: {key: 'docs' | 'docsZh'; file: string; targets: DocTarget[]}[];}@@ -485,7 +880,13 @@ function discoverComponents(continue;}- results.push({packageName, dir, sites, docBlocks});+ results.push({+ packageName,+ dir,+ sites,+ sourceFiles: sourceFiles.map(f => join(dirPath, f)),+ docBlocks,+ });}return results;}@@ -494,12 +895,14 @@ function discoverComponents(// The guard// ---------------------------------------------------------------------------+const participatingComponents = [+ ...discoverComponents(CORE_SRC_DIR, 'core'),+ ...discoverComponents(LAB_SRC_DIR, 'lab', LAB_PROMOTION_DIRS),+ ...discoverComponents(RICHTEXT_SRC_DIR, 'richtext'),+];+describe('theming.targets matches the themeProps() call sites', () => {- const components = [- ...discoverComponents(CORE_SRC_DIR, 'core'),- ...discoverComponents(LAB_SRC_DIR, 'lab', LAB_PROMOTION_DIRS),- ...discoverComponents(RICHTEXT_SRC_DIR, 'richtext'),- ];+ const components = participatingComponents;it('finds participating Core and Lab components', () => {// A refactor that renames themeProps or drops the Lab package from this@@ -587,3 +990,76 @@ describe('theming.targets matches the themeProps() call sites', () => {}}});++/**+ * Painted axes that do not reach themeProps() yet. Each key is+ * `Component.prop`; each value says why. Remove the entry when the axis+ * reaches themeProps(). A stale entry fails the guard.+ */+const UNREFLECTED_STYLE_AXIS_EXCEPTIONS: ReadonlyMap<string, string> = new Map([+ [+ 'BaseTypeahead.size',+ 'The size pads the result row, and the result row has no target. The ' ++ 'missing row target is a recorded reachability gap.',+ ],+ [+ 'ChatComposer.elevation',+ 'The composer body paints the elevation but has no target. How to expose ' ++ 'the body to themes is an open owner decision.',+ ],+ [+ 'Code.size',+ 'The code target paints the size. Adding the prop to its themeProps() ' ++ 'call is a product change that ships separately.',+ ],+ [+ 'Skeleton.radius',+ 'The skeleton target paints the radius. Adding the prop to its ' ++ 'themeProps() call is a product change that ships separately.',+ ],+]);++describe('every painted prop axis reaches themeProps()', () => {+ const findings = participatingComponents.flatMap(+ ({packageName, dir, sourceFiles}) =>+ sourceFiles+ .filter(file => !file.includes('.stories.'))+ .flatMap(file =>+ findUnreflectedStyleAxes(readFileSync(file, 'utf-8'), file).map(+ finding => ({+ ...finding,+ key: `${finding.component}.${finding.prop}`,+ where: `${packageName}/${dir}/${basename(file)}:${finding.line}`,+ }),+ ),+ ),+ );++ it('reflects every painted axis or lists it as an exception', () => {+ const unexplained = findings+ .filter(finding => !UNREFLECTED_STYLE_AXIS_EXCEPTIONS.has(finding.key))+ .map(+ finding =>+ `${finding.where}: ${finding.component} selects painted styles ` ++ `with \`${finding.styleMap}[${finding.prop}]\`, but no themeProps() ` ++ `call passes \`${finding.prop}\`. A theme cannot select the ` ++ `\`${finding.prop}\` values. Add \`${finding.prop}\` to the ` ++ `themeProps() call on the target that paints it. If no target ` ++ `paints it, add an UNREFLECTED_STYLE_AXIS_EXCEPTIONS entry that ` ++ `says why.`,+ );+ expect(unexplained).toEqual([]);+ });++ it('has no stale exceptions', () => {+ const found = new Set(findings.map(finding => finding.key));+ const stale = [...UNREFLECTED_STYLE_AXIS_EXCEPTIONS.keys()].filter(+ key => !found.has(key),+ );+ expect(+ stale,+ 'These exceptions no longer match an unreflected painted axis. ' ++ 'Remove them.',+ ).toEqual([]);+ });+});