@astryxdesign/cli 0.3.0-canary.b8cfd19 → 0.3.0-canary.ccb5ca9

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

@@ -0,0 +1,201 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} = await import(
+    '../migrate-table-rowexpansion-to-tree.mjs'
+  );
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+function normalize(str) {
+  return str
+    .replace(/\s+/g, ' ')
+    .replace(/\{\s+/g, '{')
+    .replace(/\s+\}/g, '}')
+    .trim();
+}
+
+describe('migrate-table-rowexpansion-to-tree', () => {
+  it('rewrites the useTableRowExpansionState import to useTableTreeState', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@astryxdesign/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('useTableRowExpansionState');
+    expect(output).toContain('useTableTreeState');
+    expect(output).toContain('useTableTreeData');
+  });
+
+  it('maps baseData to data and getChildren to childrenKey', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@astryxdesign/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    const n = normalize(output);
+    expect(n).toContain('data: tree');
+    expect(n).toContain("childrenKey: 'children'");
+    expect(output).not.toContain('baseData');
+    expect(output).not.toContain('getChildren');
+  });
+
+  it('maps getRowKey to idKey preserving the accessor function', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@astryxdesign/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    const n = normalize(output);
+    expect(n).toContain('idKey: item => item.id');
+    expect(output).not.toContain('getRowKey');
+  });
+
+  it('swaps the useTableRowExpansion plugin call for useTableTreeData', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@astryxdesign/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    // The state hook now returns treeConfig; the plugin consumes it.
+    expect(output).toContain('treeConfig');
+    expect(output).toContain('useTableTreeData(treeConfig)');
+    expect(output).not.toMatch(/useTableRowExpansion\(/);
+  });
+
+  it('maps getIsItemExpandable to isItemExpandable', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@astryxdesign/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    getIsItemExpandable: item => item.type === 'folder',
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    expect(output).toContain('isItemExpandable');
+    expect(output).not.toContain('getIsItemExpandable');
+  });
+
+  it('leaves the new detail-panel usage (renderExpanded) untouched', async () => {
+    const input = `import {Table, useTableRowExpansion} from '@astryxdesign/core';
+function C() {
+  const expansion = useTableRowExpansion({
+    expandedKeys,
+    onToggle,
+    getRowKey: item => item.id,
+    renderExpanded: item => <Details item={item} />,
+  });
+  return <Table data={rows} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    // No useTableRowExpansionState import here, and renderExpanded present:
+    // this is the new detail-panel API. The codemod must not touch it.
+    expect(output).toBe(input);
+  });
+
+  it('does not touch files that never imported the row-expansion hooks', async () => {
+    const input = `import {Table, useTableSelection} from '@astryxdesign/core';
+const t = <Table data={rows} columns={cols} idKey="id" />;`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('supports the @xds/core import source alias', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@xds/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    expect(output).toContain('useTableTreeState');
+    expect(output).not.toContain('useTableRowExpansionState');
+  });
+
+  it('emits treeConfig as a shorthand (not treeConfig: treeConfig)', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@astryxdesign/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('treeConfig: treeConfig');
+    expect(normalize(output)).toContain('visibleData: data');
+  });
+
+  it('leaves a migration guidance comment about expansion state', async () => {
+    const input = `import {Table, useTableRowExpansion, useTableRowExpansionState} from '@astryxdesign/core';
+function C() {
+  const {data, expansionConfig} = useTableRowExpansionState({
+    baseData: tree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+  const expansion = useTableRowExpansion(expansionConfig);
+  return <Table data={data} columns={cols} idKey="id" plugins={{expansion}} />;
+}`;
+    const output = await applyTransform(input);
+    expect(output).toContain('astryx-migration');
+    expect(output).toContain('defaultExpandedIds');
+  });
+});

package/assets/codemods/transforms/v0.3.0/index.mjs

@@ -40,6 +40,9 @@ import migrateLabCodeBlockImports, {
 import removeThemeTransitionTokenImports, {
   meta as removeThemeTransitionTokenImportsMeta,
 } from './remove-theme-transition-token-imports.mjs';
+import migrateTableRowExpansionToTree, {
+  meta as migrateTableRowExpansionToTreeMeta,
+} from './migrate-table-rowexpansion-to-tree.mjs';
 
 export default [
   {
@@ -87,4 +90,9 @@ export default [
     transform: removeThemeTransitionTokenImports,
     meta: removeThemeTransitionTokenImportsMeta,
   },
+  {
+    name: 'migrate-table-rowexpansion-to-tree',
+    transform: migrateTableRowExpansionToTree,
+    meta: migrateTableRowExpansionToTreeMeta,
+  },
 ];

package/assets/codemods/transforms/v0.3.0/migrate-grid-minchildwidth-to-columns.mjs

@@ -49,11 +49,10 @@ export default function transformer(file, api) {
         a.type === 'JSXAttribute' && a.name?.name === 'minChildWidth',
     );
     if (!minAttr) return;
-    const hasColumns = attrs.some(
+    const columnsAttr = attrs.find(
       (/** @type {any} */ a) =>
         a.type === 'JSXAttribute' && a.name?.name === 'columns',
     );
-    if (hasColumns) return;
 
     let minWidthExpr;
     if (
@@ -67,6 +66,43 @@ export default function transformer(file, api) {
       return;
     }
 
+    if (columnsAttr) {
+      // Both `columns` and `minChildWidth` are present. This is only safely
+      // migratable when `columns` is a numeric literal (e.g. `columns={3}`).
+      //
+      // In the old (0.2.0) Grid runtime, when both props were set and
+      // `columns` was a number, `minChildWidth` dominated and the numeric
+      // `columns` became a *max column cap* with `auto-fit`:
+      //   repeat(auto-fit, minmax(minChildWidth, 1fr)) capped at `columns`.
+      // The 0.3.0 `columns` object models this exactly as
+      //   {minWidth, max, repeat: 'fit'}.
+      // So the lossless rewrite is:
+      //   <Grid columns={3} minChildWidth={280}>
+      //     -> <Grid columns={{minWidth: 280, max: 3, repeat: 'fit'}}>
+      //
+      // If `columns` is already an object or a non-numeric/dynamic
+      // expression, the combined behavior is genuinely ambiguous, so we
+      // bail and leave it unmigrated (it surfaces separately).
+      const columnsValue = columnsAttr.value;
+      if (columnsValue?.type !== 'JSXExpressionContainer') return;
+      const columnsExpr = columnsValue.expression;
+      const isNumericLiteral =
+        (columnsExpr?.type === 'NumericLiteral' ||
+          columnsExpr?.type === 'Literal') &&
+        typeof columnsExpr.value === 'number';
+      if (!isNumericLiteral) return;
+
+      const columnsObject = j.objectExpression([
+        j.property('init', j.identifier('minWidth'), minWidthExpr),
+        j.property('init', j.identifier('max'), j.literal(columnsExpr.value)),
+        j.property('init', j.identifier('repeat'), j.literal('fit')),
+      ]);
+      columnsAttr.value = j.jsxExpressionContainer(columnsObject);
+      attrs.splice(attrs.indexOf(minAttr), 1);
+      hasChanges = true;
+      return;
+    }
+
     const columnsObject = j.objectExpression([
       j.property('init', j.identifier('minWidth'), minWidthExpr),
       j.property('init', j.identifier('repeat'), j.literal('fit')),

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/browser-support.doc.mjs

@@ -15,7 +15,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Astryx is built on modern web platform features: the Popover API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
+          text: 'Astryx is built on modern web platform features: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
         },
         {
           type: 'prose',
@@ -73,7 +73,7 @@ export const docs = {
               'Baseline 2026: the tightest requirement.',
             ],
             [
-              'Popover API',
+              '[`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
               'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
               'Baseline 2025.',
             ],
@@ -86,7 +86,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The gap that matters is between Tier 1 and Tier 2: the Popover API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
         },
       ],
     },
@@ -112,7 +112,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
         },
       ],
     },
@@ -123,7 +123,7 @@ export const docs = {
           type: 'list',
           style: 'do',
           items: [
-            'Components never throw on missing platform APIs. Where a browser lacks the Popover API, layers fall back to plain visibility instead of crashing.',
+            'Components never throw on missing platform APIs. Where a browser lacks the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
             'Tier 1 and Tier 2 are officially supported and tested.',
             'Non-layered components render correctly down to Tier 2.',
           ],
@@ -192,7 +192,7 @@ const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
         },
         {
           type: 'prose',
-          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the Popover API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
         },
       ],
     },

package/assets/docs/icons.doc.mjs

@@ -114,9 +114,9 @@ export const brandTheme = defineTheme({
           type: 'list',
           style: 'ordered',
           items: [
-            'Add the name to IconName type in packages/core/src/Icon/globalIconRegistry.tsx',
-            'Add the default SVG to packages/core/src/Icon/defaultIcons.tsx',
-            'Add a row to the Available Names table in packages/cli/docs/icons.doc.mjs',
+            'Add the name to IconName type in `packages/core/src/Icon/globalIconRegistry.tsx`',
+            'Add the default SVG to `packages/core/src/Icon/defaultIcons.tsx`',
+            'Add a row to the Available Names table in `packages/cli/assets/docs/icons.doc.mjs`',
           ],
         },
       ],

package/assets/docs/illustrations.doc.mjs

@@ -40,7 +40,7 @@ export const docs = {
             'Keep illustrations consistent in style across the product.',
             'Use simple, flat illustrations that work in both light and dark mode.',
             'Size illustrations proportionally to the container, typically 120\u2013240px.',
-            'Center illustrations with supporting text below.',
+            'Place illustrations centered with supporting text below.',
           ],
         },
         {
@@ -59,7 +59,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Center illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
+          text: 'Place illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
         },
         {
           type: 'code',

package/assets/docs/internationalization.doc.mjs

@@ -300,7 +300,7 @@ export default function App() {
       content: [
         {
           type: 'prose',
-          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
+          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Turn it on in development to catch hardcoded astryx strings and layout issues caused by longer text.',
         },
         {
           type: 'code',

package/assets/docs/layout.doc.dense.mjs

@@ -64,7 +64,7 @@ export const docsDense = {
             'no Card-wrapped list items (card soup)',
             'no stacked full-width Cards as page structure',
             'no Cards in Cards',
-            'no decorative Badge — counts/enums only; StatusDot/Token for status',
+            'no decorative Badge: counts/enums only; StatusDot/Token for status',
           ],
         },
       ],

package/assets/docs/migration.doc.mjs

@@ -350,7 +350,7 @@ if (getComputedStyle(button).paddingInline === '0px') {
             'Run the app in light and dark mode and check that surfaces, borders, text, icons, hover states, focus rings, and status colors flow together.',
             'Open the command palette from the shell, type into it, select items by keyboard, and confirm focus returns to the trigger.',
             'Check the SideNav at collapsed, expanded, active, hover, nested, and mobile states.',
-            'Verify settings popovers and dialogs in jsdom and in a real browser because native dialog and Popover APIs may need test shims.',
+            'Verify settings popovers and dialogs in jsdom and in a real browser because the native dialog and [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) APIs may need test shims.',
             'Search for leftover hardcoded Tailwind colors, arbitrary hex values, and one-off hover colors after each route migration.',
             'Run component tests, build, and at least one browser screenshot pass for each migrated route.',
           ],

package/assets/docs/principles.doc.mjs

@@ -39,7 +39,7 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
-            'Layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
+            'Page layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
             'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
             'StyleX or Tailwind for custom styling; both are first-class (see \`astryx docs styling\`)',
             'Semantic tokens, not hardcoded values (see \`astryx docs tokens\`)',

package/assets/docs/styling-libraries.doc.mjs

@@ -56,7 +56,7 @@ export const docs = {
               '`@astryxdesign/core/tailwind-theme.css`',
             ],
             [
-              'Token resolver APIs',
+              'Design token resolver APIs',
               'JavaScript needs token values for charts, canvas, SVG, or config objects',
               "`resolveThemeToken(theme, '--color-data-categorical-blue', {mode})`",
             ],

package/assets/docs/styling.doc.mjs

@@ -22,10 +22,10 @@ export const docs = {
           type: 'table',
           headers: ['Approach', 'Use for', 'Example'],
           rows: [
-            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', 'const styles = stylex.create(...); <Button xstyle={styles.save} />'],
-            ['Tailwind utilities', 'Layout, wrappers, and utility styling', 'className="flex gap-3 p-4"'],
-            ['className', 'Integrating with external CSS or Tailwind on components', 'className="my-card shadow-lg"'],
-            ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "colors.surface = 'var(--color-background-surface)'"],
+            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', '`const styles = stylex.create(...); <Button xstyle={styles.save} />`'],
+            ['Tailwind utilities', 'Page layout, wrappers, and utility styling', '`className="flex gap-3 p-4"`'],
+            ['className', 'Integrating with external CSS or Tailwind on components', '`className="my-card shadow-lg"`'],
+            ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "`colors.surface = 'var(--color-background-surface)'`"],
           ],
         },
         {