Skip to content

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

TypeScript

fix(cli): correct theme-build component keys for multi-word components (#4467)

Cindy Zhang0321eada8106
diff --git a/.changeset/cli-theme-multiword-component-keys.md b/.changeset/cli-theme-multiword-component-keys.md
new file mode 100644
index 0000000000..545c314f94
--- /dev/null
+++ b/.changeset/cli-theme-multiword-component-keys.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx theme build`: component-override keys for multi-word components (TextInput, DateInput, NumberInput, DropdownMenu, SideNav, TopNav, etc.) now match the hyphenated class the component actually renders. The known-component registry used de-hyphenated keys, so overrides authored against them emitted dead selectors (`.astryx-textinput` instead of `.astryx-text-input`) that silently never applied (#4109).
+
+@cixzhang
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index 340f5f3a81..42a65da800 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -602,8 +602,8 @@ ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedThem
* @type {Record<string, string[]>}
*/
const KNOWN_COMPONENTS = {
- appshell: ['position'],
- aspectratio: [],
+ 'app-shell': ['position'],
+ 'aspect-ratio': [],
avatar: ['size'],
badge: ['variant', 'color'],
banner: ['container', 'status'],
@@ -612,15 +612,15 @@ const KNOWN_COMPONENTS = {
calendar: [],
card: ['variant'],
center: [],
- checkboxinput: [],
+ 'checkbox-input': [],
collapsible: [],
- dateinput: [],
+ 'date-input': [],
dialog: ['variant', 'position'],
divider: ['variant', 'orientation'],
- dropdownmenu: [],
+ 'dropdown-menu': [],
'empty-state': [],
field: [],
- formlayout: [],
+ 'form-layout': [],
grid: ['align'],
heading: ['level'],
icon: ['size', 'color'],
@@ -629,16 +629,16 @@ const KNOWN_COMPONENTS = {
layout: [],
link: ['color'],
list: ['type', 'density'],
- mobilenav: [],
- moremenu: [],
+ 'mobile-nav': [],
+ 'more-menu': [],
navicon: [],
- numberinput: [],
+ 'number-input': [],
pagination: ['variant'],
progressbar: ['variant', 'size'],
- radiolist: ['orientation'],
+ 'radio-list': ['orientation'],
section: ['variant'],
selector: ['type', 'size', 'color'],
- sidenav: [],
+ 'side-nav': [],
skeleton: [],
slider: ['orientation'],
spinner: ['size'],
@@ -646,14 +646,14 @@ const KNOWN_COMPONENTS = {
statusdot: ['variant', 'size'],
switch: [],
table: [],
- tablist: ['type'],
+ 'tab-list': ['type'],
text: ['type', 'color'],
textarea: [],
- textinput: [],
- timeinput: [],
+ 'text-input': [],
+ 'time-input': [],
token: ['color'],
tokenizer: [],
- topnav: [],
+ 'top-nav': [],
typeahead: ['type', 'size', 'color'],
};
diff --git a/packages/cli/cli/commands/build-theme.registry.test.mjs b/packages/cli/cli/commands/build-theme.registry.test.mjs
new file mode 100644
index 0000000000..30008691b6
--- /dev/null
+++ b/packages/cli/cli/commands/build-theme.registry.test.mjs
@@ -0,0 +1,187 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for issue #4109: theme-build component-override keys
+ * must match the class names components actually render.
+ *
+ * `astryx theme build` emits a component override as a `.astryx-<key>` rule,
+ * where `<key>` is the theme's `components` key passed through verbatim
+ * (generateThemeRules re-adds the `astryx-` prefix). The CLI's KNOWN_COMPONENTS
+ * registry is what the validator accepts and what its "Did you mean?" hints
+ * point authors toward — so every registry key MUST correspond to a class a
+ * component really renders, or the emitted rule is a dead selector that
+ * silently does nothing.
+ *
+ * The registry had de-hyphenated keys for every multi-word component
+ * (`textinput`, `dateinput`, `numberinput`, `timeinput`, `appshell`,
+ * `aspectratio`, `checkboxinput`, `dropdownmenu`, `formlayout`, `mobilenav`,
+ * `moremenu`, `radiolist`, `sidenav`, `tablist`, `topnav`), while the
+ * components render the hyphenated class (`astryx-text-input`, etc.). Authors
+ * following the registry shipped dead `.astryx-textinput` rules.
+ *
+ * Source of truth = the class the component renders, captured in each
+ * component's `{Name}.doc.mjs` `theming.targets[].className` (itself guarded
+ * against the real `themeProps()`/`stableClassName()` call sites by
+ * packages/core/src/theme/themingTargets.test.ts).
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CORE_SRC = path.resolve(HERE, '../../../core/src');
+const BUILD_THEME_SRC = path.resolve(HERE, '../../api/theme/build/build.mjs');
+
+/**
+ * Extract the KNOWN_COMPONENTS registry keys from the build-theme source.
+ * Reading the source (rather than importing the un-exported constant) keeps
+ * this test decoupled from the module's private surface.
+ */
+function knownComponentKeys() {
+ const src = fs.readFileSync(BUILD_THEME_SRC, 'utf8');
+ const start = src.indexOf('const KNOWN_COMPONENTS = {');
+ expect(start).toBeGreaterThan(-1);
+ const end = src.indexOf('};', start);
+ const block = src.slice(start, end);
+ const keys = new Set();
+ const re = /^\s*'?([a-z][a-z0-9-]*)'?\s*:/gm;
+ let m;
+ while ((m = re.exec(block)) !== null) {
+ keys.add(m[1]);
+ }
+ return keys;
+}
+
+/**
+ * The set of real override keys: every `theming.targets[].className` across the
+ * component docs, with the `astryx-` prefix stripped. This is the canonical
+ * source of truth for what selectors the theme build should emit.
+ */
+function realOverrideKeys() {
+ const keys = new Set();
+ for (const dir of fs.readdirSync(CORE_SRC, {withFileTypes: true})) {
+ if (!dir.isDirectory()) continue;
+ const docFile = path.join(CORE_SRC, dir.name, `${dir.name}.doc.mjs`);
+ if (!fs.existsSync(docFile)) continue;
+ const text = fs.readFileSync(docFile, 'utf8');
+ const themingIdx = text.indexOf('theming');
+ if (themingIdx === -1) continue;
+ const scoped = text.slice(themingIdx);
+ const re = /className:\s*'astryx-([a-z0-9-]+)'/g;
+ let m;
+ while ((m = re.exec(scoped)) !== null) {
+ keys.add(m[1]);
+ }
+ }
+ return keys;
+}
+
+/**
+ * The stable classes components ACTUALLY render: the literal first argument of
+ * every `themeProps('<class>', …)` and `stableClassName('<class>')` call across
+ * the core `.tsx` source (excluding tests). This is the truest source of truth
+ * — the doc `theming.targets` are hand-authored metadata that can drift from
+ * it, so both the registry and the targets are validated against these
+ * literals. Every call site uses a plain string literal (no dynamic/
+ * interpolated names), so this is fully static.
+ */
+function renderedClassLiterals() {
+ const classes = new Set();
+ const walk = dir => {
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walk(full);
+ } else if (entry.name.endsWith('.tsx') && !entry.name.endsWith('.test.tsx')) {
+ const text = fs.readFileSync(full, 'utf8');
+ for (const re of [
+ /themeProps\(\s*'([^']+)'/g,
+ /stableClassName\(\s*'([^']+)'/g,
+ ]) {
+ let m;
+ while ((m = re.exec(text)) !== null) {
+ classes.add(m[1]);
+ }
+ }
+ }
+ }
+ };
+ walk(CORE_SRC);
+ return classes;
+}
+
+describe('theme-build KNOWN_COMPONENTS registry (#4109)', () => {
+ // `layer` is a layout/anchor concept with no rendered `astryx-layer`
+ // class or doc target; it predates and is unrelated to #4109.
+ const allowedWithoutTarget = new Set(['layer']);
+
+ it('every registry key is a class documented as a theming target', () => {
+ const known = knownComponentKeys();
+ const real = realOverrideKeys();
+
+ const dead = [...known].filter(
+ k => !real.has(k) && !allowedWithoutTarget.has(k),
+ );
+ expect(dead).toEqual([]);
+ });
+
+ it('every registry key is a class a component actually renders (themeProps literal)', () => {
+ // Validate the registry against the TRUE source of truth — the literal
+ // passed to themeProps()/stableClassName() in the component source — not
+ // just the hand-authored doc targets. This catches a de-hyphenated key
+ // even if the docs were (wrongly) kept in agreement with it.
+ const known = knownComponentKeys();
+ const rendered = renderedClassLiterals();
+
+ const dead = [...known].filter(
+ k => !rendered.has(k) && !allowedWithoutTarget.has(k),
+ );
+ expect(dead).toEqual([]);
+ });
+
+ it('every documented theming target is backed by a real themeProps literal', () => {
+ // Guards the two "sources of truth" against drift: a component whose
+ // themeProps() arg and doc target className disagree would be a latent bug
+ // that the registry checks above could not catch (they'd validate against
+ // whichever side happened to match). `theming.targets[].className` is
+ // hand-authored; themeProps()/stableClassName() literals are what actually
+ // renders — they must agree.
+ const targets = realOverrideKeys();
+ const rendered = renderedClassLiterals();
+
+ const orphanTargets = [...targets].filter(k => !rendered.has(k));
+ expect(orphanTargets).toEqual([]);
+ });
+});
+
+describe('theme build emits a live TextInput selector (#4109)', () => {
+ let tmpDir;
+ beforeAll(() => {
+ ensureCoreBuilt();
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-4109-'));
+ }, 200_000);
+
+ it('emits .astryx-text-input (the rendered class), not the dead .astryx-textinput', async () => {
+ const themeFile = path.join(tmpDir, 'theme.mjs');
+ const outFile = path.join(tmpDir, 'theme.css');
+ fs.writeFileSync(
+ themeFile,
+ `export default {\n` +
+ ` name: 'input-4109',\n` +
+ ` tokens: {},\n` +
+ ` components: { 'text-input': { base: { borderRadius: '16px' } } },\n` +
+ `};\n`,
+ );
+
+ await runCli(['theme', 'build', themeFile, '-o', outFile]);
+ const css = fs.readFileSync(outFile, 'utf8');
+
+ expect(css).toContain('.astryx-text-input');
+ expect(css).not.toContain('.astryx-textinput');
+ });
+});