@astryxdesign/cli 0.4.6 → 0.4.7-canary.20bae6c

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

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {Button} from '@astryxdesign/core/Button';
+import {Text} from '@astryxdesign/core/Text';
+import {Card} from '@astryxdesign/core/Card';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+
+export default function StepperCustomContent() {
+  const [active, setActive] = useState(0);
+  // The content slot takes any node, not just form fields — a panel, a summary,
+  // a notice. Gating it on `active` is what makes the flow expand a step at a
+  // time.
+  return (
+    <div style={{width: 680}}>
+      <Stepper
+        activeStep={active}
+        orientation="vertical"
+        onStepClick={setActive}>
+        <Step
+          step={0}
+          label="Project details"
+          description="Name it and point us at the source"
+          indicator="number">
+          {active === 0 && (
+            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+              <div style={{display: 'flex', gap: 12}}>
+                <TextInput
+                  label="Project name"
+                  placeholder="My awesome project"
+                  value=""
+                  width="100%"
+                />
+                <TextInput
+                  label="Repository URL"
+                  placeholder="https://github.com/..."
+                  value=""
+                  width="100%"
+                />
+              </div>
+              <div>
+                <Button
+                  label="Continue"
+                  variant="primary"
+                  onClick={() => setActive(1)}
+                />
+              </div>
+            </div>
+          )}
+        </Step>
+        <Step
+          step={1}
+          label="Review the build"
+          description="What we detected from your default branch"
+          indicator="number">
+          {active === 1 && (
+            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+              <Card variant="muted" padding={3}>
+                <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
+                  <div
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: 8,
+                    }}>
+                    <Text type="label">Next.js 15</Text>
+                    <Badge variant="success" label="Detected" />
+                  </div>
+                  <Text type="supporting">
+                    Build command <code>next build</code> · Output{' '}
+                    <code>.next</code> · Node 20
+                  </Text>
+                </div>
+              </Card>
+              <div style={{display: 'flex', gap: 8}}>
+                <Button
+                  label="Back"
+                  variant="secondary"
+                  onClick={() => setActive(0)}
+                />
+                <Button
+                  label="Looks right"
+                  variant="primary"
+                  onClick={() => setActive(2)}
+                />
+              </div>
+            </div>
+          )}
+        </Step>
+        <Step
+          step={2}
+          label="Deploy"
+          description="Ships to production"
+          indicator="number">
+          {active === 2 && (
+            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+              <Banner
+                status="info"
+                title="First deploy takes a few minutes"
+                description="Later deploys reuse the build cache and finish in under a minute."
+              />
+              <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="Live" indicator="number" />
+      </Stepper>
+    </div>
+  );
+}

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

@@ -7,7 +7,7 @@ export const doc = {
   name: 'Stepper — Indicator Modes',
   displayName: 'Stepper — Indicator Modes',
   description:
-    'The indicator prop side by side: auto (check when done, ring when current, number ahead), always-number, and a custom icon per step.',
+    'The indicator prop side by side: none (the bar and label carry the progress on their own), auto (check when done, ring when current, number ahead), always-number, and a custom icon per step.',
   isReady: true,
   aspectRatio: 4 / 3,
   componentsUsed: ['Stepper', 'Text', 'Icon'],

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

@@ -3,7 +3,7 @@
 'use client';
 
 import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
 import {Text} from '@astryxdesign/core/Text';
 import {Icon} from '@astryxdesign/core/Icon';
 
@@ -11,6 +11,18 @@ export default function StepperIndicatorModes() {
   const [active, setActive] = useState(2);
   return (
     <div style={{display: 'flex', gap: 48, flexWrap: 'wrap'}}>
+      <div style={{maxWidth: 220}}>
+        <Text type="label">None</Text>
+        <Stepper
+          activeStep={active}
+          orientation="vertical"
+          onStepClick={setActive}>
+          <Step step={0} label="Account" indicator="none" />
+          <Step step={1} label="Profile" indicator="none" />
+          <Step step={2} label="Settings" indicator="none" />
+          <Step step={3} label="Review" indicator="none" />
+        </Stepper>
+      </div>
       <div style={{maxWidth: 220}}>
         <Text type="label">Auto</Text>
         <Stepper
@@ -44,22 +56,22 @@ export default function StepperIndicatorModes() {
           <Step
             step={0}
             label="Account"
-            icon={<Icon icon="info" size="sm" />}
+            indicator={<Icon icon="info" size="sm" />}
           />
           <Step
             step={1}
             label="Profile"
-            icon={<Icon icon="search" size="sm" />}
+            indicator={<Icon icon="search" size="sm" />}
           />
           <Step
             step={2}
             label="Settings"
-            icon={<Icon icon="wrench" size="sm" />}
+            indicator={<Icon icon="wrench" size="sm" />}
           />
           <Step
             step={3}
             label="Review"
-            icon={<Icon icon="check" size="sm" />}
+            indicator={<Icon icon="check" size="sm" />}
           />
         </Stepper>
       </div>

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

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — On-Track Horizontal',
+  displayName: 'Stepper — On-Track Horizontal',
+  description:
+    'The on-track layout in horizontal orientation: instead of sitting beside the label, each indicator is slotted into the connector itself, so the numbered nodes read as beads on one continuous line. Labels center under their node.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Stepper'],
+};

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

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+
+export default function StepperOnTrackHorizontal() {
+  const [active, setActive] = useState(2);
+  return (
+    <div style={{width: 560}}>
+      <Stepper
+        activeStep={active}
+        orientation="horizontal"
+        indicatorPosition="on-track"
+        onStepClick={setActive}>
+        <Step step={0} label="Workspace" indicator="number" />
+        <Step step={1} label="Team" indicator="number" />
+        <Step step={2} label="Integrations" indicator="number" />
+        <Step step={3} label="Import" indicator="number" />
+        <Step step={4} label="Launch" indicator="number" />
+      </Stepper>
+    </div>
+  );
+}

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

@@ -7,8 +7,8 @@ export const doc = {
   name: 'Stepper — On-Track Vertical',
   displayName: 'Stepper — On-Track Vertical',
   description:
-    'The on-track layout in vertical orientation: indicators sit inline on a continuous connector rail, with each label and description beside its node.',
+    'The on-track layout in vertical orientation: indicators sit inline on a continuous connector rail, with each label and description beside its node. Compare with the separated layout, where the indicator sits alongside its own bar segment instead of on a shared rail.',
   isReady: true,
   aspectRatio: 4 / 3,
-  componentsUsed: ['Stepper'],
+  componentsUsed: ['Stepper', 'Step'],
 };

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

@@ -3,7 +3,7 @@
 'use client';
 
 import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
 
 export default function StepperOnTrackVertical() {
   const [active, setActive] = useState(2);

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

@@ -7,7 +7,7 @@ export const doc = {
   name: 'Stepper — Checkout Progress',
   displayName: 'Stepper — Checkout Progress',
   description:
-    'A horizontal on-track stepper for a checkout flow: numbered nodes sit on a continuous connector, with completed and current steps filled. Click any step to jump.',
+    'The default stepper: a horizontal track where every step owns an equal segment of the progress bar above its label. The default auto indicator resolves itself per step — a check once the step is done, a ring on the current step, a number for the ones still ahead. Click any step to jump.',
   isReady: true,
   isShowcase: true,
   aspectRatio: 16 / 9,

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

@@ -3,7 +3,7 @@
 'use client';
 
 import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
 
 export default function StepperShowcase() {
   const [active, setActive] = useState(2);
@@ -12,13 +12,12 @@ export default function StepperShowcase() {
       <Stepper
         activeStep={active}
         orientation="horizontal"
-        indicatorPosition="on-track"
         onStepClick={setActive}>
-        <Step step={0} label="Cart" indicator="number" />
-        <Step step={1} label="Shipping" indicator="number" />
-        <Step step={2} label="Payment" indicator="number" />
-        <Step step={3} label="Review" indicator="number" />
-        <Step step={4} label="Confirm" indicator="number" />
+        <Step step={0} label="Cart" />
+        <Step step={1} label="Shipping" />
+        <Step step={2} label="Payment" />
+        <Step step={3} label="Review" />
+        <Step step={4} label="Confirm" />
       </Stepper>
     </div>
   );

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

@@ -3,7 +3,7 @@
 'use client';
 
 import {useState} from 'react';
-import {Stepper, Step} from '@astryxdesign/lab';
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
 
 export default function StepperStatus() {
   const [active, setActive] = useState(3);

package/assets/templates/pages/mixed-gallery/page.tsx

@@ -36,7 +36,11 @@ const clipStyle: CSSProperties = {
 // 3 columns on desktop, dropping straight to 1 column below 720px (no 2-col
 // middle state). minmax(0, 1fr) (not 1fr) so tracks split evenly and ignore the
 // images' intrinsic min-width. The hero spans 2 columns on desktop, then fills
-// the row once it's single-column.
+// the row once it's single-column — and switches from 3:1 to 3:2 with a plain
+// aspect-ratio override. AspectRatio's ratio is a class-level declaration in
+// @layer astryx-base, and this <style> tag is unlayered, so the override wins
+// regardless of specificity — every stacked tile is uniform without rendering
+// the hero twice.
 const GALLERY_CSS = `
 .mixed-gallery-grid {
   display: grid;
@@ -52,6 +56,7 @@ const GALLERY_CSS = `
   }
   .mixed-gallery-hero {
     grid-column: 1 / -1;
+    aspect-ratio: 3 / 2;
   }
 }
 `;
@@ -134,9 +139,13 @@ export default function MixedGalleryTemplate() {
                 of three. Every tile is 3:2 except the hero, which is 3:1 so that
                 (being 2 columns wide) it matches the row height exactly. All
                 rows are therefore the same height. Responsive via @container:
-                3 columns → 1 column at ≤720px. */}
+                3 columns → 1 column at ≤720px, where the hero drops to 3:2 so
+                the stacked tiles are uniform. */}
             <div className="mixed-gallery-grid">
-              {/* Hero — spans 2 columns; 3:1 keeps it level with the sidebar */}
+              {/* Hero — spans 2 columns; 3:1 keeps it level with the sidebar.
+                  Stacked, the unlayered aspect-ratio override switches it to
+                  3:2 (see GALLERY_CSS) — one element, no duplicate hero
+                  markup. */}
               <GalleryCard
                 image={IMAGES[0]}
                 ratio={3 / 1}

package/assets/templates/themes/neutral/neutralTheme.ts

@@ -24,7 +24,8 @@
  *   icon   = T30         / T80
  *   text   = T30         / T80
  *
- * All 9 saturated badge values pass WCAG AA (5.6–9.6 contrast range).
+ * All 9 saturated badge values pass WCAG AA against their label (>= 4.5:1);
+ * `scripts/check-badge-contrast.test.mjs` holds every theme to that.
  *
  * Only overrides tokens that differ from the defaults.
  */
@@ -432,10 +433,14 @@ export const neutralTheme = defineTheme({
         color: '#171717',
       },
       'variant:error': {
-        // Light: T55 #e33f4a (palette saturated stop)
+        // Light: T58 #c9303a. The T55 stop #e33f4a pairs with white at only
+        //        4.14:1 — the label is 12px/500, so AA wants 4.5, not the 3:1
+        //        large-text allowance. One tonal step down holds the hue
+        //        (OKLCH H 21.9 -> 22.8, C 0.200 -> 0.189) and reaches 5.29:1.
         // Dark : T60 stop from dark-mode tonal palette of Tailwind red-600
-        //        source #dc2626 (kept on H=27 alarm-red rather than coral)
-        backgroundColor: 'light-dark(#e33f4a, #ff705d)',
+        //        source #dc2626 (kept on H=27 alarm-red rather than coral).
+        //        Dark text on it is 6.60:1 and unchanged.
+        backgroundColor: 'light-dark(#c9303a, #ff705d)',
         color: 'light-dark(#ffffff, #171717)',
       },
 
@@ -500,7 +505,7 @@ export const neutralTheme = defineTheme({
     //
     //   success → badge success bg  (green T45 / dark-ramp T60)
     //   warning → badge warning bg  (yellow T85, same hex both modes)
-    //   error   → badge error bg    (red T55 / dark-ramp T60)
+    //   error   → badge error bg    (red T58 / dark-ramp T60)
     //   accent  → badge info bg     (blue T50 / dark-ramp T60) — the
     //             StatusDot "accent" is the info/attention color, so it
     //             pairs with the info badge rather than --color-accent
@@ -515,7 +520,7 @@ export const neutralTheme = defineTheme({
     statusdot: {
       'variant:success': {backgroundColor: 'light-dark(#198100, #64af4c)'},
       'variant:warning': {backgroundColor: '#ffce2f'},
-      'variant:error': {backgroundColor: 'light-dark(#e33f4a, #ff705d)'},
+      'variant:error': {backgroundColor: 'light-dark(#c9303a, #ff705d)'},
       'variant:accent': {backgroundColor: 'light-dark(#0074e2, #6d9cfe)'},
     },
 
@@ -611,8 +616,8 @@ export const neutralTheme = defineTheme({
         '--color-warning': '#ffce2f',
       },
       'variant:error': {
-        // Red T55 saturated stop (= variant:error badge bg)
-        '--color-error': '#e33f4a',
+        // Red T58 saturated stop (= variant:error badge bg)
+        '--color-error': '#c9303a',
       },
     },
 

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

@@ -38,6 +38,7 @@ import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {themeAdd} from '../../../api/theme/add/add.mjs';
 import {themeTemplate} from '../../../api/theme/template/template.mjs';
 import {themeList} from '../../../api/theme/list/list.mjs';
+import {themeTargets} from '../../../api/theme/targets/targets.mjs';
 import {themeBuild, importSpecifier} from '../../../api/theme/build/build.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as themeGroup} from './theme.doc.mjs';
@@ -45,10 +46,12 @@ import {doc as themeBuildCommand} from './theme-build.doc.mjs';
 import {doc as themeListCommand} from './theme-list.doc.mjs';
 import {doc as themeAddCommand} from './theme-add.doc.mjs';
 import {doc as themeTemplateCommand} from './theme-template.doc.mjs';
+import {doc as themeTargetsCommand} from './theme-targets.doc.mjs';
 import {doc as themeBuildFn} from '../../../api/theme/themeBuild.doc.mjs';
 import {doc as themeListFn} from '../../../api/theme/themeList.doc.mjs';
 import {doc as themeAddFn} from '../../../api/theme/themeAdd.doc.mjs';
 import {doc as themeTemplateFn} from '../../../api/theme/themeTemplate.doc.mjs';
+import {doc as themeTargetsFn} from '../../../api/theme/themeTargets.doc.mjs';
 
 /**
  * Path to this CLI's real entry (clients/cli/bin/astryx.mjs), resolved from
@@ -194,6 +197,36 @@ function printThemeList(themes) {
   );
 }
 
+/**
+ * Render the targets as one greppable line each, under an aligned header. A
+ * `records()` block would be five lines per target — over a thousand for the
+ * full surface, which is the view this command exists to make readable.
+ * @param {import('../../../api/theme/theme.type.mjs').ThemeTargetEntry[]} targets
+ * @returns {string}
+ */
+function formatTargetsTable(targets) {
+  const rows = targets.map(t => ({
+    key: t.key,
+    component: t.component,
+    props: t.props.join(', ') || '-',
+    states: t.states.join(', ') || '-',
+  }));
+  const head = {key: 'key', component: 'component', props: 'props', states: 'states'};
+  const width = (/** @type {'key'|'component'|'props'} */ field) =>
+    [head, ...rows].reduce((max, r) => Math.max(max, r[field].length), 0);
+  const w = {key: width('key'), component: width('component'), props: width('props')};
+  const line = (/** @type {typeof head} */ r) =>
+    [
+      r.key.padEnd(w.key),
+      r.component.padEnd(w.component),
+      r.props.padEnd(w.props),
+      r.states,
+    ]
+      .join('  ')
+      .trimEnd();
+  return [line(head), ...rows.map(line)].join('\n');
+}
+
 /**
  * @param {import('commander').Command} program
  */
@@ -225,6 +258,18 @@ export function registerTheme(program) {
     },
   });
 
+  // Theming questions are asked at `theme`, but per-component overrides live
+  // under `component`. Without this pointer the group reads as a build-tool
+  // menu, and the component targets are unreachable from the noun the user
+  // started at.
+  theme.addHelpText(
+    'after',
+    `\nComponent style overrides:\n` +
+      `  ${getCliInvocation()} theme targets            Every themeable class, with its props and states\n` +
+      `  ${getCliInvocation()} component <Name>         One component's theming table\n` +
+      `  ${getCliInvocation()} docs theme               How component overrides work\n`,
+  );
+
   defineCommand(theme, themeBuildCommand, {
     fn: themeBuildFn,
     action: async (
@@ -502,4 +547,44 @@ export function registerTheme(program) {
       );
     },
   });
+
+  defineCommand(theme, themeTargetsCommand, {
+    fn: themeTargetsFn,
+    action: async (/** @type {string | undefined} */ filter) => {
+      const json = program.opts().json || false;
+
+      /** @type {import('../../../api/theme/theme.type.mjs').ThemeTargetsResponse} */
+      let result;
+      try {
+        result = await themeTargets(filter, {cwd: process.cwd()});
+      } catch (e) {
+        const err =
+          /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {
+          suggestions: err.suggestions || [],
+          code: err.code,
+        });
+        return;
+      }
+
+      if (json) return jsonOut(result);
+
+      const run = getCliInvocation();
+      const {targets, componentCount} = result.data;
+      emit(
+        section(
+          'Theming targets',
+          `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}`,
+        ),
+        text(formatTargetsTable(targets)),
+        text(
+          [
+            `Each key goes under \`components\` in defineTheme; it paints \`.astryx-<key>\`.`,
+            `Props take a value (\`variant:secondary\`); states are written bare (\`checked\`).`,
+            `One component in full: ${run} component <Name>`,
+          ].join('\n'),
+        ),
+      );
+    },
+  });
 }

package/clients/cli/commands/dialog-adaptive-template.test.mjs

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {component} from '../../../api/component/component.mjs';
+
+const CWD = {cwd: '.'};
+
+// Resolves built-in block templates by walking the source tree.
+const SCAN_TIMEOUT = 30_000;
+
+describe(
+  'Dialog adaptive presentation template',
+  () => {
+    it('is listed as a Dialog example block', async () => {
+      const result = await component('Dialog', {
+        ...CWD,
+        blocks: true,
+      });
+      const exampleNames = result.data.examples.map(b => b.name);
+      expect(exampleNames).toContain('DialogAdaptivePresentation');
+    });
+  },
+  SCAN_TIMEOUT,
+);

package/clients/cli/commands/theme-targets.behavior.test.mjs

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CLI behavior for `astryx theme targets`.
+ *
+ * The API leaf is covered by api/theme/targets/targets.test.mjs; what is only
+ * reachable here is the terminal binding — the table a human reads, the JSON
+ * envelope a lint script reads, and the route into component overrides from
+ * `theme --help`, which is where the question gets asked.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+describe('astryx theme targets', () => {
+  it('prints one greppable line per target, with props and states', async () => {
+    const {status, stdout} = await runCli(['theme', 'targets', 'Switch']);
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^switch\s+Switch\s+size\s+checked, disabled$/m);
+    expect(stdout).toMatch(/^switch-thumb\s+Switch\s+size\s+checked$/m);
+    expect(stdout).toMatch(/3 across 1 component/);
+  });
+
+  it('lists the whole surface when unfiltered', async () => {
+    const {status, stdout} = await runCli(['theme', 'targets']);
+
+    expect(status).toBe(0);
+    const rows = stdout.split('\n').filter(l => /^[a-z][a-z0-9-]*\s{2,}/.test(l));
+    expect(rows.length).toBeGreaterThan(100);
+    expect(stdout).toMatch(/^button\s/m);
+    expect(stdout).toMatch(/^switch-thumb\s/m);
+  }, 30_000);
+
+  it('returns a theme.targets envelope under --json', async () => {
+    const {status, stdout} = await runCli(['--json', 'theme', 'targets', 'Switch']);
+
+    expect(status).toBe(0);
+    const payload = JSON.parse(stdout);
+    expect(payload.type).toBe('theme.targets');
+    expect(payload.data.targets).toContainEqual({
+      key: 'switch-thumb',
+      className: 'astryx-switch-thumb',
+      component: 'Switch',
+      props: ['size'],
+      states: ['checked'],
+    });
+  });
+
+  it('fails a filter that matches nothing', async () => {
+    const {status, stderr} = await runCli(['theme', 'targets', 'nosuchthing']);
+
+    expect(status).toBe(1);
+    expect(stderr).toMatch(/No theming target matches "nosuchthing"/);
+  });
+
+  it('routes a theming question from `theme --help` to component overrides', async () => {
+    const {stdout} = await runCli(['theme', '--help']);
+
+    expect(stdout).toMatch(/Component style overrides:/);
+    expect(stdout).toMatch(/theme targets/);
+    expect(stdout).toMatch(/component <Name>/);
+  });
+});

package/clients/cli/commands/theme-targets.doc.mjs

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx theme targets`. The terminal binding of the
+ * `themeTargets()` function (referenced via `fn`); its args map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'theme targets',
+  displayName: 'astryx theme targets',
+  namespace: 'cli',
+  summary: 'List the component theming targets a theme can override',
+  description:
+    'Prints every `defineTheme` components key across the system: the stable class it paints, ' +
+    'the component that declares it, and the props and states that are legal override keys ' +
+    'under it. This is the whole themeable surface in one command — what auditing a theme, or ' +
+    'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
+    'component to assemble. Pass a component name to scope it; pass any substring to search ' +
+    'keys. `--json` for a list a repo can lint its own theme against.',
+  fn: 'themeTargets',
+  args: [{name: 'filter', param: 'filter', required: false}],
+  examples: [
+    {label: 'The whole themeable surface', cli: 'astryx theme targets'},
+    {label: "One component's targets", cli: 'astryx theme targets Switch'},
+    {label: 'Search keys', cli: 'astryx theme targets thumb'},
+    {label: 'For a lint or an audit script', cli: 'astryx --json theme targets'},
+  ],
+  exitCodes: [
+    {code: 0, when: 'success'},
+    {code: 1, when: 'a filter matches no target, or core cannot be resolved'},
+  ],
+  related: ['component', 'theme build', 'theme template'],
+};

package/clients/cli/commands/theme-template.doc.mjs

@@ -16,9 +16,9 @@ export const doc = {
   namespace: 'cli',
   summary: 'Write the annotated theme template into your project',
   description:
-    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +
     'defineTheme field, the token families, the component override syntax, and how a theme is ' +
-    'consumed — naming the CLI command that prints the authoritative reference for each. Read ' +
+    'consumed, naming the CLI command that prints the authoritative reference for each. Read ' +
     'it, copy what you need into your own theme file, delete it. Use `theme add <slug>` instead ' +
     'to start from a theme we ship. Leaves an existing file untouched unless --overwrite.',
   fn: 'themeTemplate',