@astryxdesign/cli 0.4.7 → 0.5.0-canary.055e75f

package/foundation/discovery/theming-targets.test.mjs

@@ -0,0 +1,245 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The enumerability guard for component theming targets.
+ *
+ * A theming target is only useful if a theme author can find it. These tests
+ * run against the REAL core docs and fail if any component's targets stop
+ * being enumerable — a doc that moves out of the scanned tree, a target shape
+ * that stops being read, or a component whose Theming table says one thing
+ * while `theme targets` says another. That divergence is the failure the
+ * listing exists to prevent: a target list that can drift from the components
+ * is worse than no list.
+ *
+ * The public vars a target carries get the same treatment, one step further:
+ * being enumerable is not the same as being settable. A documented var no
+ * component reads compiles to a declaration that never applies (#5012), and a
+ * var the component writes inline outranks every cascade layer, so no theme can
+ * reach it (#4530). Both shipped. Neither is visible in the generated theme CSS
+ * — the artifact the jsdom suites assert on — so the wiring is checked here
+ * against source. Whether the cascade then lands the value on the element is a
+ * browser fact and no jsdom test can stand in for it.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findCoreDir} from '../fs/paths.mjs';
+import {
+  discoverComponents,
+  findComponentReadme,
+} from './component-discovery.mjs';
+import {loadComponentDoc} from './component-loader.mjs';
+import {
+  collectThemingTargets,
+  collectThemingVars,
+  targetsByKey,
+} from './theming-targets.mjs';
+
+const coreDir = /** @type {string} */ (findCoreDir(process.cwd()));
+const coreSrc = path.join(coreDir, 'src');
+
+/** @type {Promise<import('./theming-targets.mjs').ThemingTarget[]>} */
+const enumerated = collectThemingTargets(coreSrc);
+
+describe('collectThemingTargets', () => {
+  it('enumerates the whole surface, not a handful', async () => {
+    const targets = await enumerated;
+    expect(targets.length).toBeGreaterThan(100);
+    expect(new Set(targets.map(t => t.component)).size).toBeGreaterThan(50);
+  });
+
+  it('drops the namespace prefix so each key is what defineTheme takes', async () => {
+    for (const t of await enumerated) {
+      expect(t.className).toBe(`astryx-${t.key}`);
+      expect(t.component).toBeTruthy();
+    }
+  });
+
+  it('carries the props and states a target reflects', async () => {
+    const targets = await enumerated;
+    expect(targets.find(t => t.key === 'switch-thumb')).toEqual({
+      key: 'switch-thumb',
+      className: 'astryx-switch-thumb',
+      component: 'Switch',
+      props: ['size'],
+      states: ['checked'],
+    });
+  });
+
+  it('is sorted by key, so a diff of two runs is readable', async () => {
+    const keys = (await enumerated).map(t => t.key);
+    expect(keys).toEqual([...keys].sort((a, b) => a.localeCompare(b)));
+  });
+
+  // The listing and `theme build`'s override validation read this one
+  // enumeration. `targetsByKey` is the shape validation wants: props and
+  // states merged, because both are legal override keys.
+  it('collapses to the override keys, merging the components that share one', async () => {
+    const byKey = targetsByKey(await enumerated);
+    expect(byKey['switch']).toEqual(['size', 'checked', 'disabled']);
+    // `radio` is documented by both Indicator and RadioList.
+    const radio = (await enumerated).filter(t => t.key === 'radio');
+    expect(radio.length).toBeGreaterThan(1);
+    for (const t of radio) {
+      for (const name of [...t.props, ...t.states]) {
+        expect(byKey['radio']).toContain(name);
+      }
+    }
+  });
+
+  it('every component doc that declares targets has them enumerated', async () => {
+    const targets = await enumerated;
+    /** @type {Map<string, Set<string>>} key -> props+states */
+    const byKey = new Map(
+      Object.entries(targetsByKey(targets)).map(([k, v]) => [k, new Set(v)]),
+    );
+
+    const names = Object.values(discoverComponents(coreDir)).flat();
+    /** @type {string[]} */
+    const missing = [];
+    /** @type {Set<string>} */
+    const seenDocs = new Set();
+    let checked = 0;
+
+    for (const name of names) {
+      const docPath = findComponentReadme(coreDir, name);
+      if (!docPath || seenDocs.has(docPath)) continue;
+      seenDocs.add(docPath);
+
+      /** @type {any} */
+      let doc;
+      try {
+        doc = await loadComponentDoc(docPath);
+      } catch {
+        continue;
+      }
+
+      for (const target of doc?.theming?.targets || []) {
+        if (typeof target?.className !== 'string') continue;
+        checked++;
+        const key = target.className.replace(/^astryx-/, '');
+        const known = byKey.get(key);
+        if (!known) {
+          missing.push(`${name}: ${target.className} is not enumerable`);
+          continue;
+        }
+        for (const prop of [
+          ...(target.visualProps || []),
+          ...(target.states || []),
+        ]) {
+          if (!known.has(prop)) {
+            missing.push(`${name}: ${target.className} lost "${prop}"`);
+          }
+        }
+      }
+    }
+
+    expect(checked).toBeGreaterThan(100);
+    expect(missing).toEqual([]);
+  }, 60_000);
+});
+
+// ---------------------------------------------------------------------------
+// Public vars — enumerable is not the same as settable
+// ---------------------------------------------------------------------------
+
+/** @type {Promise<import('./theming-targets.mjs').ThemingVar[]>} */
+const enumeratedVars = collectThemingVars(coreSrc);
+
+/** Every non-test source file under a component directory. */
+function sourcesIn(dir) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+      out.push(...sourcesIn(path.join(dir, entry.name)));
+      continue;
+    }
+    if (!/\.tsx?$/.test(entry.name)) continue;
+    if (/\.(test|stories)\.tsx?$/.test(entry.name)) continue;
+    out.push(path.join(dir, entry.name));
+  }
+  return out;
+}
+
+/**
+ * The text of every inline style a file writes — `style={{…}}` objects and
+ * `setProperty` calls. A custom property written from either outranks every
+ * cascade layer, so a theme cannot reach it.
+ */
+function inlineStyleText(src) {
+  const chunks = [];
+  for (const m of src.matchAll(/style=\{\{/g)) {
+    const end = src.indexOf('}}', m.index);
+    chunks.push(src.slice(m.index, end === -1 ? src.length : end));
+  }
+  for (const m of src.matchAll(/setProperty\(\s*'[^']+'/g)) chunks.push(m[0]);
+  return chunks.join('\n');
+}
+
+describe('collectThemingVars', () => {
+  it('enumerates the public vars and drops the private plumbing', async () => {
+    const names = (await enumeratedVars).map(v => v.name);
+    expect(names.length).toBeGreaterThan(0);
+    expect(names.every(n => !n.startsWith('--_'))).toBe(true);
+    expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b)));
+    expect(names).toEqual([...new Set(names)]);
+  });
+
+  it('carries the component and the documented default', async () => {
+    const indent = (await enumeratedVars).find(
+      v => v.name === '--tree-list-indent',
+    );
+    expect(indent).toMatchObject({
+      name: '--tree-list-indent',
+      component: 'TreeList',
+      default: 'var(--spacing-4)',
+    });
+  });
+
+  // #5012: the theme docs advertised `--button-press-scale`, which no component
+  // ever read. A theme setting it compiled to a declaration nothing consumed,
+  // and nothing failed — the var was in the docs, so every existence check
+  // passed. Reading it is the minimum that makes a documented var mean anything.
+  it('every documented var is read by the component that documents it', async () => {
+    /** @type {string[]} */
+    const unread = [];
+    for (const v of await enumeratedVars) {
+      const read = sourcesIn(v.dir).some(f =>
+        fs.readFileSync(f, 'utf-8').includes(`var(${v.name}`),
+      );
+      if (!read) unread.push(`${v.component}: nothing reads var(${v.name})`);
+    }
+    expect(
+      unread,
+      `A documented public var no component reads compiles to a declaration ` +
+        `that never applies (#5012). Either wire it up or drop it from the doc.`,
+    ).toEqual([]);
+  });
+
+  // #4530: TreeList's indent was an inline `margin-inline-start` on the element
+  // carrying the theme target. An inline declaration outranks every cascade
+  // layer, so `@layer astryx-theme` could not reach it — the var was real, read,
+  // and documented, and still unsettable. The fix moved it into a StyleX rule.
+  it('no documented var is written inline, where no theme can outrank it', async () => {
+    /** @type {string[]} */
+    const clobbered = [];
+    for (const v of await enumeratedVars) {
+      for (const f of sourcesIn(v.dir)) {
+        if (inlineStyleText(fs.readFileSync(f, 'utf-8')).includes(v.name)) {
+          clobbered.push(
+            `${v.component}: ${path.basename(f)} sets ${v.name} inline`,
+          );
+        }
+      }
+    }
+    expect(
+      clobbered,
+      `An inline custom property beats every cascade layer, so a theme setting ` +
+        `it through @layer astryx-theme is silently ignored (#4530). Declare it ` +
+        `in a StyleX rule instead.`,
+    ).toEqual([]);
+  });
+});

package/foundation/response/response-types.doc.mjs

@@ -153,7 +153,7 @@ export const doc = {
     {
       value: 'template.cdn',
       description:
-        'A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+        'A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.',
     },
 
     // hook
@@ -197,7 +197,12 @@ export const doc = {
     {
       value: 'theme.template',
       description:
-        'A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.',
+        'A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.',
+    },
+    {
+      value: 'theme.targets',
+      description:
+        'The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',
     },
 
     // upgrade

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.7",
+  "version": "0.5.0-canary.055e75f",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -87,10 +87,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.5.0-canary.055e75f",
+    "@astryxdesign/core": "0.5.0-canary.055e75f",
+    "@astryxdesign/lab": "0.5.0-canary.055e75f",
+    "@astryxdesign/theme-neutral": "0.5.0-canary.055e75f",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -108,10 +108,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.5.0-canary.055e75f",
+    "@astryxdesign/core": "0.5.0-canary.055e75f",
+    "@astryxdesign/lab": "0.5.0-canary.055e75f",
+    "@astryxdesign/theme-neutral": "0.5.0-canary.055e75f",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/assets/templates/blocks/components/Stepper/StepperHorizontal.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'Stepper',
-  name: 'Stepper — Horizontal Progress',
-  displayName: 'Stepper — Horizontal Progress',
-  description:
-    'A horizontal separated stepper: each step owns a segment of the progress bar above its label. Filled segments track how far the flow has progressed.',
-  isReady: true,
-  aspectRatio: 16 / 9,
-  componentsUsed: ['Stepper'],
-};

package/assets/templates/blocks/components/Stepper/StepperHorizontal.tsx

@@ -1,24 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
-
-export default function StepperHorizontal() {
-  const [active, setActive] = useState(1);
-  return (
-    <div style={{width: '100%', maxWidth: 600}}>
-      <Stepper
-        activeStep={active}
-        orientation="horizontal"
-        onStepClick={setActive}>
-        <Step step={0} label="Workspace" />
-        <Step step={1} label="Team" />
-        <Step step={2} label="Integrations" />
-        <Step step={3} label="Import" />
-        <Step step={4} label="Launch" />
-      </Stepper>
-    </div>
-  );
-}

package/assets/templates/blocks/components/Stepper/StepperMultiStepForm.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'Stepper',
-  name: 'Stepper — Multi-Step Form',
-  displayName: 'Stepper — Multi-Step Form',
-  description:
-    'A vertical stepper driving a multi-step form. Each step renders its own fields in the content slot for the active step, with Back/Continue buttons advancing activeStep.',
-  isReady: true,
-  aspectRatio: 4 / 3,
-  componentsUsed: ['Stepper', 'TextInput', 'Button', 'Text'],
-};

package/assets/templates/blocks/components/Stepper/StepperMultiStepForm.tsx

@@ -1,92 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
-import {TextInput} from '@astryxdesign/core/TextInput';
-import {Button} from '@astryxdesign/core/Button';
-import {Text} from '@astryxdesign/core/Text';
-
-export default function StepperMultiStepForm() {
-  const [active, setActive] = useState(0);
-  return (
-    <div style={{width: '100%', maxWidth: 480}}>
-      <Stepper
-        activeStep={active}
-        orientation="vertical"
-        onStepClick={setActive}>
-        <Step step={0} label="Project details" indicator="number">
-          {active === 0 && (
-            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
-              <TextInput
-                label="Project name"
-                placeholder="My awesome project"
-                value=""
-              />
-              <TextInput
-                label="Repository URL"
-                placeholder="https://github.com/..."
-                value=""
-              />
-              <div>
-                <Button
-                  label="Continue"
-                  variant="primary"
-                  onClick={() => setActive(1)}
-                />
-              </div>
-            </div>
-          )}
-        </Step>
-        <Step step={1} label="Environment" indicator="number">
-          {active === 1 && (
-            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
-              <TextInput label="Node version" placeholder="20" value="" />
-              <TextInput
-                label="Build command"
-                placeholder="npm run build"
-                value=""
-              />
-              <div style={{display: 'flex', gap: 8}}>
-                <Button
-                  label="Back"
-                  variant="secondary"
-                  onClick={() => setActive(0)}
-                />
-                <Button
-                  label="Continue"
-                  variant="primary"
-                  onClick={() => setActive(2)}
-                />
-              </div>
-            </div>
-          )}
-        </Step>
-        <Step step={2} label="Deploy" indicator="number">
-          {active === 2 && (
-            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
-              <Text type="body">
-                Ready to deploy. This creates a production build and pushes to
-                your configured hosting.
-              </Text>
-              <div style={{display: 'flex', gap: 8}}>
-                <Button
-                  label="Back"
-                  variant="secondary"
-                  onClick={() => setActive(1)}
-                />
-                <Button
-                  label="Deploy now"
-                  variant="primary"
-                  onClick={() => setActive(3)}
-                />
-              </div>
-            </div>
-          )}
-        </Step>
-        <Step step={3} label="Done" indicator="number" />
-      </Stepper>
-    </div>
-  );
-}

package/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.doc.mjs

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
-  type: 'block',
-  exampleFor: 'Stepper',
-  name: 'Stepper — Vertical Onboarding',
-  displayName: 'Stepper — Vertical Onboarding',
-  description:
-    'A vertical stepper for an onboarding flow, with a label and description per step. The auto indicator shows a check for completed steps, a ring for the current step, and a number for upcoming ones.',
-  isReady: true,
-  aspectRatio: 4 / 3,
-  componentsUsed: ['Stepper'],
-};

package/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.tsx

@@ -1,40 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
-
-export default function StepperVerticalOnboarding() {
-  const [active, setActive] = useState(2);
-  return (
-    <div style={{width: '100%', maxWidth: 400}}>
-      <Stepper
-        activeStep={active}
-        orientation="vertical"
-        onStepClick={setActive}>
-        <Step
-          step={0}
-          label="Create workspace"
-          description="Name and configure your workspace"
-        />
-        <Step
-          step={1}
-          label="Invite team members"
-          description="Add collaborators by email"
-        />
-        <Step
-          step={2}
-          label="Set up integrations"
-          description="Connect Slack, GitHub, Jira"
-        />
-        <Step
-          step={3}
-          label="Import data"
-          description="Bring in existing projects"
-        />
-        <Step step={4} label="Launch" description="Go live with your team" />
-      </Stepper>
-    </div>
-  );
-}