@astryxdesign/cli 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @xds/cli
 
+# 0.4.1
+
+#### Fixes
+
+- `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 (#4778).
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+
+---
+
 # 0.4.0
 
 #### Breaking Changes

package/api/template/template.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'One entry point for the template family: with no name it lists the discovered ' +
     "templates; with a name it returns that template's source, a layout skeleton, or " +
     'scaffolds it into the project. Templates are discovered across core, external ' +
-    'packages, and integrations, so the same id can appear in more than one place — ' +
+    'packages, and integrations, so the same id can appear in more than one place; ' +
     'narrow an ambiguous name with type and/or package.',
   importPath: '@astryxdesign/cli/api',
   signature:
@@ -110,7 +110,7 @@ export const doc = {
     },
     {
       code: 'ERR_AMBIGUOUS_TEMPLATE',
-      when: 'the name matches more than one template across kinds/packages — narrow it with type and/or package',
+      when: 'the name matches more than one template across kinds/packages; narrow it with type and/or package',
     },
     {
       code: 'ERR_NO_SOURCE',

package/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}`,
           );

package/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"'),
+    ]);
+  });
+});

package/assets/docs/internationalization.doc.mjs

@@ -359,7 +359,7 @@ function SaveButton() {
         {
           type: 'heading',
           level: 4,
-          text: '2. Directional icons — mirror with CSS, not a name-swap',
+          text: '2. Directional icons: mirror with CSS, not a name-swap',
         },
         {
           type: 'prose',
@@ -384,7 +384,7 @@ function NextButton() {
         {
           type: 'heading',
           level: 4,
-          text: '3. Behavioral logic — read the DOM lazily, on the event',
+          text: '3. Behavioral logic: read the DOM lazily, on the event',
         },
         {
           type: 'prose',
@@ -393,7 +393,7 @@ function NextButton() {
         {
           type: 'heading',
           level: 4,
-          text: '4. useDirection() context — the last resort',
+          text: '4. useDirection() context: the last resort',
         },
         {
           type: 'prose',

package/assets/docs/tokens.doc.mjs

@@ -3,7 +3,7 @@
 // AUTO-GENERATED — do not edit manually.
 // Source: packages/core/src/theme/tokens.stylex.ts
 // Run: node scripts/generate-token-docs.mjs
-// Total: 184 tokens across 12 categories.
+// Total: 188 tokens across 13 categories.
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
 
@@ -561,6 +561,40 @@ export const docs = {
       ],
       "previewType": "border-line"
     },
+    {
+      "title": "Focus Tokens",
+      "content": [
+        {
+          "type": "prose",
+          "text": "The keyboard focus ring, shared by every component that draws one. Override these to restyle focus across the system."
+        },
+        {
+          "type": "table",
+          "headers": [
+            "Token",
+            "Value"
+          ],
+          "rows": [
+            [
+              "--focus-outline-width",
+              "2px"
+            ],
+            [
+              "--focus-outline-style",
+              "solid"
+            ],
+            [
+              "--focus-outline-color",
+              "var(--color-accent)"
+            ],
+            [
+              "--focus-outline-offset",
+              "3px"
+            ]
+          ]
+        }
+      ]
+    },
     {
       "title": "Radius Tokens",
       "content": [

package/authoring/integration/integration.doc.mjs

@@ -60,7 +60,7 @@ export const doc = {
     {
       type: 'prose',
       text:
-        "Identity — the integration's name and version — comes from the " +
+        "Identity, the integration's name and version, comes from the " +
         "package's package.json, not from this manifest. The manifest only " +
         'declares where the CLI finds each kind of artifact.',
     },

package/clients/cli/commands/build-theme.registry.test.mjs

@@ -74,6 +74,15 @@ function renderedClassLiterals() {
             classes.add(m[1]);
           }
         }
+        // A component can also name its popup SURFACE — an element usePopover
+        // owns, so the class cannot be rendered from the component itself.
+        // `surfaceTarget: 'x'` puts `astryx-x` on that surface, which makes it
+        // just as rendered as a direct themeProps() call.
+        const surfaceRe = /surfaceTarget:\s*'([^']+)'/g;
+        let sm;
+        while ((sm = surfaceRe.exec(text)) !== null) {
+          classes.add(sm[1]);
+        }
         // Renamed targets emit their old name too, via themeProps'
         // `legacyNames`. Those classes are just as rendered as the primary
         // one, so a doc entry for the old name is still backed by real output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",