@astryxdesign/cli 0.3.0-canary.e9fc2bb → 0.3.0-canary.ee705d8

package/assets/codemods/transforms/v0.3.0/migrate-table-rowexpansion-to-tree.mjs

@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Migrate tree-mode useTableRowExpansion to the tree plugin
+ *
+ * useTableRowExpansion is now a detail-panel plugin (renderExpanded). Its old
+ * tree mode (child rows that reuse the parent columns) moved to
+ * useTableTreeData + useTableTreeState, and useTableRowExpansionState was
+ * removed. This codemod rewrites the standard tree pattern:
+ *
+ *   const {data, expansionConfig} = useTableRowExpansionState({
+ *     baseData, getChildren, getRowKey, expandedKeys, setExpandedKeys,
+ *   });
+ *   const expansion = useTableRowExpansion(expansionConfig);
+ *
+ * into:
+ *
+ *   const {visibleData: data, treeConfig} = useTableTreeState({
+ *     data: baseData, childrenKey: 'children', idKey: getRowKey, ...
+ *   });
+ *   const expansion = useTableTreeData(treeConfig);
+ *
+ * Files that use the new detail-panel API (renderExpanded, no
+ * useTableRowExpansionState import) are left untouched.
+ */
+
+export const meta = {
+  title: 'Migrate tree-mode useTableRowExpansion to the tree plugin',
+  description:
+    'Rewrites the removed useTableRowExpansionState tree pattern to useTableTreeState + useTableTreeData. Detail-panel usage (renderExpanded) is left untouched.',
+  pr: '#4612',
+};
+
+const IMPORT_SOURCES = new Set([
+  '@astryxdesign/core',
+  '@astryxdesign/core/Table',
+  '@xds/core',
+  '@xds/core/Table',
+]);
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  // Only act on files importing the removed state hook. Detail-panel-only
+  // usage (useTableRowExpansion alone) is the new API and must be left alone.
+  let stateLocal = null;
+  let pluginLocal = null;
+  /** @type {any[]} */
+  const importPaths = [];
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (spec.type !== 'ImportSpecifier') continue;
+      if (spec.imported.name === 'useTableRowExpansionState') {
+        stateLocal = spec.local?.name ?? spec.imported.name;
+        importPaths.push(path);
+      }
+      if (spec.imported.name === 'useTableRowExpansion') {
+        pluginLocal = spec.local?.name ?? spec.imported.name;
+      }
+    }
+  });
+  if (!stateLocal) return undefined;
+
+  let hasChanges = false;
+
+  // --- 1. Rewrite the state hook call + its config object ---
+  root
+    .find(j.CallExpression, {callee: {name: stateLocal}})
+    .forEach((/** @type {any} */ path) => {
+      const arg = path.node.arguments[0];
+      if (!arg || arg.type !== 'ObjectExpression') return;
+
+      /** @type {any} */
+      let getChildrenValue = null;
+      const nextProps = [];
+      for (const prop of arg.properties) {
+        const key =
+          prop.key?.name ?? (prop.key?.value ? String(prop.key.value) : null);
+        if (key === 'baseData') {
+          nextProps.push(j.property('init', j.identifier('data'), prop.value));
+        } else if (key === 'getChildren') {
+          getChildrenValue = prop.value;
+          // childrenKey is emitted below (default 'children').
+        } else if (key === 'getRowKey') {
+          nextProps.push(j.property('init', j.identifier('idKey'), prop.value));
+        } else if (key === 'getIsItemExpandable') {
+          nextProps.push(
+            j.property('init', j.identifier('isItemExpandable'), prop.value),
+          );
+        } else if (key === 'expandedKeys' || key === 'setExpandedKeys') {
+          // The tree state hook owns expansion internally (uncontrolled) or
+          // via expandedIds/onExpandedIdsChange (controlled). The 1:1
+          // controlled mapping is not mechanical, so these are dropped and a
+          // guidance comment is attached below.
+          continue;
+        } else {
+          nextProps.push(prop);
+        }
+      }
+
+      // childrenKey: derive the literal when getChildren is the canonical
+      // `item => item.children` / `item.children ?? []`; otherwise keep the
+      // default and let the guidance comment flag it.
+      nextProps.splice(
+        1,
+        0,
+        j.property('init', j.identifier('childrenKey'), j.literal('children')),
+      );
+
+      arg.properties = nextProps;
+      path.node.callee = j.identifier('useTableTreeState');
+      hasChanges = true;
+
+      // Rename the destructured result: data -> visibleData (aliased back to
+      // the local name), expansionConfig -> treeConfig.
+      const declarator = path.parent.node;
+      if (
+        declarator.type === 'VariableDeclarator' &&
+        declarator.id.type === 'ObjectPattern'
+      ) {
+        for (const p of declarator.id.properties) {
+          if (p.type !== 'ObjectProperty' && p.type !== 'Property') continue;
+          const kName = p.key?.name;
+          if (kName === 'data') {
+            // {data} -> {visibleData: data}
+            p.key = j.identifier('visibleData');
+            if (p.shorthand) {
+              p.shorthand = false;
+              p.value = j.identifier('data');
+            }
+          } else if (kName === 'expansionConfig') {
+            // {expansionConfig} -> {treeConfig} (keep it shorthand).
+            p.key = j.identifier('treeConfig');
+            if (p.value?.type === 'Identifier') {
+              p.value = j.identifier('treeConfig');
+              p.shorthand = true;
+            }
+          }
+        }
+      }
+
+      // Attach a one-line migration note as a leading comment on the
+      // statement, so a human confirms the expansion-state wiring.
+      const stmt = path.parent.parent.node;
+      if (stmt && !stmt.comments) {
+        stmt.comments = [
+          j.commentLine(
+            ' astryx-migration: verify tree expansion state. useTableTreeState',
+            true,
+            false,
+          ),
+          j.commentLine(
+            ' is uncontrolled by default; pass defaultExpandedIds, or',
+            true,
+            false,
+          ),
+          j.commentLine(
+            ' expandedIds + onExpandedIdsChange for the old controlled set.',
+            true,
+            false,
+          ),
+        ];
+      }
+      void getChildrenValue;
+    });
+
+  // --- 2. Swap the plugin call: useTableRowExpansion(cfg) -> useTableTreeData(cfg) ---
+  if (pluginLocal) {
+    root
+      .find(j.CallExpression, {callee: {name: pluginLocal}})
+      .forEach((/** @type {any} */ path) => {
+        // Rename the argument identifier expansionConfig -> treeConfig.
+        const a = path.node.arguments[0];
+        if (a && a.type === 'Identifier' && a.name === 'expansionConfig') {
+          path.node.arguments[0] = j.identifier('treeConfig');
+        }
+        path.node.callee = j.identifier('useTableTreeData');
+        hasChanges = true;
+      });
+  }
+
+  if (!hasChanges) return undefined;
+
+  // --- 3. Fix imports: drop the removed hooks, add the tree hooks ---
+  for (const path of importPaths) {
+    const specs = path.node.specifiers.filter(
+      (/** @type {any} */ s) =>
+        !(
+          s.type === 'ImportSpecifier' &&
+          (s.imported.name === 'useTableRowExpansionState' ||
+            s.imported.name === 'useTableRowExpansion')
+        ),
+    );
+    const existing = new Set(
+      specs.map((/** @type {any} */ s) => s.imported?.name),
+    );
+    if (!existing.has('useTableTreeState')) {
+      specs.push(j.importSpecifier(j.identifier('useTableTreeState')));
+    }
+    if (!existing.has('useTableTreeData')) {
+      specs.push(j.importSpecifier(j.identifier('useTableTreeData')));
+    }
+    path.node.specifiers = specs;
+  }
+
+  return root.toSource({quote: 'single'});
+}

package/assets/docs/getting-started.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
+          code: 'Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
         },
       ],
     },
@@ -34,13 +34,13 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Add the core package, a theme, and the CLI to your existing project.',
+          text: 'Add the core package and its `@stylexjs/stylex` peer dependency, plus a theme and the CLI.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli`,
+          code: `npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral @astryxdesign/cli`,
         },
         {
           type: 'prose',

package/assets/templates/blocks/components/Stepper/StepperHorizontal.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 — 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

@@ -0,0 +1,24 @@
+// 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/StepperIndicatorModes.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 — 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.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper', 'Text', 'Icon'],
+};

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

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+import {Text} from '@astryxdesign/core/Text';
+import {Icon} from '@astryxdesign/core/Icon';
+
+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">Auto</Text>
+        <Stepper
+          activeStep={active}
+          orientation="vertical"
+          onStepClick={setActive}>
+          <Step step={0} label="Account" />
+          <Step step={1} label="Profile" />
+          <Step step={2} label="Settings" />
+          <Step step={3} label="Review" />
+        </Stepper>
+      </div>
+      <div style={{maxWidth: 220}}>
+        <Text type="label">Number</Text>
+        <Stepper
+          activeStep={active}
+          orientation="vertical"
+          onStepClick={setActive}>
+          <Step step={0} label="Account" indicator="number" />
+          <Step step={1} label="Profile" indicator="number" />
+          <Step step={2} label="Settings" indicator="number" />
+          <Step step={3} label="Review" indicator="number" />
+        </Stepper>
+      </div>
+      <div style={{maxWidth: 220}}>
+        <Text type="label">Custom icon</Text>
+        <Stepper
+          activeStep={active}
+          orientation="vertical"
+          onStepClick={setActive}>
+          <Step
+            step={0}
+            label="Account"
+            icon={<Icon icon="info" size="sm" />}
+          />
+          <Step
+            step={1}
+            label="Profile"
+            icon={<Icon icon="search" size="sm" />}
+          />
+          <Step
+            step={2}
+            label="Settings"
+            icon={<Icon icon="wrench" size="sm" />}
+          />
+          <Step
+            step={3}
+            label="Review"
+            icon={<Icon icon="check" size="sm" />}
+          />
+        </Stepper>
+      </div>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperMultiStepForm.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 — 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

@@ -0,0 +1,92 @@
+// 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/StepperOnTrackVertical.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 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.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper'],
+};

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

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperOnTrackVertical() {
+  const [active, setActive] = useState(2);
+  return (
+    <div style={{width: '100%', maxWidth: 400}}>
+      <Stepper
+        activeStep={active}
+        orientation="vertical"
+        indicatorPosition="on-track"
+        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>
+  );
+}

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

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  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.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Stepper'],
+};

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

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperShowcase() {
+  const [active, setActive] = useState(2);
+  return (
+    <div style={{width: '100%', maxWidth: 640}}>
+      <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" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperStatus.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 — Validation Status',
+  displayName: 'Stepper — Validation Status',
+  description:
+    'Semantic status per step in a verification flow: success shows a green check, error a red glyph, accent the in-progress step. Status sets the indicator color and glyph only — never the connector — and is announced to assistive tech as text.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper'],
+};

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

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperStatus() {
+  const [active, setActive] = useState(3);
+  return (
+    <div style={{width: '100%', maxWidth: 400}}>
+      <Stepper
+        activeStep={active}
+        orientation="vertical"
+        onStepClick={setActive}>
+        <Step
+          step={0}
+          label="Email verified"
+          description="you@example.com"
+          status="success"
+        />
+        <Step
+          step={1}
+          label="Phone verified"
+          description="+1 (555) 012-3456"
+          status="success"
+        />
+        <Step
+          step={2}
+          label="Identity document"
+          description="Passport upload failed"
+          status="error"
+        />
+        <Step
+          step={3}
+          label="Address verification"
+          description="Pending review"
+          status="accent"
+        />
+        <Step
+          step={4}
+          label="Background check"
+          isOptional
+          description="Skipped"
+        />
+        <Step step={5} label="Account activated" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.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 — 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'],
+};