Skip to content

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

TypeScript

fix(cli): load theming target states in theme-build override validation (#4778)

Cindy Zhangfff841294946
diff --git a/.changeset/theme-build-state-keys.md b/.changeset/theme-build-state-keys.md
new file mode 100644
index 0000000000..858d651db3
--- /dev/null
+++ b/.changeset/theme-build-state-keys.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx theme build` no longer warns `Unknown prop` for documented state override keys. Component docs declare state-driven selectors under `theming.targets[].states` (`radio` → `checked`/`disabled`, `calendar-day` → `today`/`selected`, …), but override validation only loaded `visualProps`, so the state syntax the Theming Infrastructure wiki documents — `components: {radio: {checked: {...}}}` — warned on every build. The CSS was always generated correctly; only the warning was wrong. 30 targets across core were affected.
+
+@cixzhang
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index 8c4719b439..39200d77ca 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -815,7 +815,11 @@ ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedThem
// =============================================================================
/**
- * Load known theme target keys and visual props from core component docs.
+ * Load known theme target keys from core component docs: the visual props AND
+ * the runtime states each target reflects. Both are legal override keys — the
+ * Theming Infrastructure wiki documents `radio: {checked}` and
+ * `'calendar-day': {today, selected}` alongside `button: {'variant:secondary'}`
+ * — so validation has to know both or documented syntax warns as unknown.
* Returns null when docs are unavailable so validation can skip unknown-key
* warnings rather than guessing from a second registry.
*
@@ -854,9 +858,10 @@ async function loadKnownComponents() {
if (typeof className !== 'string') continue;
const key = className.replace(/^astryx-/, '');
if (!key) continue;
- const props = Array.isArray(target.visualProps)
- ? target.visualProps.filter((/** @type {unknown} */ p) => typeof p === 'string')
- : [];
+ const props = [target.visualProps, target.states]
+ .filter(list => Array.isArray(list))
+ .flat()
+ .filter((/** @type {unknown} */ p) => typeof p === 'string');
targets[key] = [...new Set([...(targets[key] || []), ...props])];
}
}
@@ -922,7 +927,8 @@ async function validateComponentOverrides(themeDef) {
continue;
}
- // Check prop names in prop:value keys
+ // Check prop/state names in the override keys. A key is either `base`, a
+ // `prop:value` pair (possibly `+`-joined), or a bare state name.
const knownProps = knownComponents[component];
for (const key of Object.keys(rules)) {
if (key === 'base') continue;
@@ -934,8 +940,8 @@ async function validateComponentOverrides(themeDef) {
if (prop && !knownProps.includes(prop)) {
const hint =
knownProps.length > 0
- ? ` Known props: ${knownProps.join(', ')}`
- : ' This component has no variant props.';
+ ? ` Known props/states: ${knownProps.join(', ')}`
+ : ' This component has no variant props or states.';
warnings.push(
`Unknown prop "${prop}" on component "${component}".${hint}`,
);
diff --git a/packages/cli/api/theme/build/build.test.mjs b/packages/cli/api/theme/build/build.test.mjs
index 1d27f7895d..905226a8c3 100644
--- a/packages/cli/api/theme/build/build.test.mjs
+++ b/packages/cli/api/theme/build/build.test.mjs
@@ -222,3 +222,54 @@ describe('themeBuild() — check mode', () => {
expect(result?.data.stale).toEqual([]);
});
});
+
+describe('themeBuild() — component override validation', () => {
+ it('accepts documented state keys without an "Unknown prop" warning', async () => {
+ // The state-key syntax the Theming Infrastructure wiki documents —
+ // `radio: {checked}`, `calendar-day: {today, selected}` — is declared in
+ // each component's doc under `theming.targets[].states`, not
+ // `visualProps`. `loadKnownComponents()` read only `visualProps`, so every
+ // one of these warned "Unknown prop": documented syntax that looked broken.
+ const themeFile = path.join(tmpDir, 'states.mjs');
+ fs.writeFileSync(
+ themeFile,
+ `export default {
+ name: 'states',
+ tokens: {'--color-bg': '#0a0a0a'},
+ components: {
+ radio: {
+ checked: {borderColor: 'var(--color-accent)'},
+ 'checked+disabled': {opacity: '0.5'},
+ },
+ 'calendar-day': {
+ today: {fontWeight: '700'},
+ selected: {backgroundColor: 'var(--color-accent)'},
+ },
+ },
+ };\n`,
+ );
+
+ const result = await themeBuild('states.mjs', {}, {cwd: tmpDir});
+
+ expect(result?.data.warnings).toEqual([]);
+ });
+
+ it('still warns on a key that is neither a visual prop nor a state', async () => {
+ // Widening the known set to states must not turn the guard off.
+ const themeFile = path.join(tmpDir, 'bogus.mjs');
+ fs.writeFileSync(
+ themeFile,
+ `export default {
+ name: 'bogus',
+ tokens: {'--color-bg': '#0a0a0a'},
+ components: {radio: {notAState: {opacity: '0.5'}}},
+ };\n`,
+ );
+
+ const result = await themeBuild('bogus.mjs', {}, {cwd: tmpDir});
+
+ expect(result?.data.warnings).toEqual([
+ expect.stringContaining('Unknown prop "notAState" on component "radio"'),
+ ]);
+ });
+});