@astryxdesign/cli 0.3.0-canary.fc1c3f3 → 0.3.0-canary.fcbc342

package/assets/codemods/transforms/next/rename-dropdown-menu-radio-dot-target.mjs

@@ -0,0 +1,152 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: rename the removed `dropdown-menu-radio-dot` theme target
+ *
+ * The menu radio's dot is no longer drawn by DropdownMenuRadioItem. That row
+ * now renders the shared radio indicator, so its dot is the indicator's dot and
+ * carries `radio-indicator-dot` (plus the legacy `radio-dot`) instead of the
+ * menu-specific `dropdown-menu-radio-dot`, which is gone.
+ *
+ * Runtime themes are not validated: a theme keyed on the old target keeps
+ * compiling and simply stops matching, with no error anywhere. That silence is
+ * why this rename needs a codemod rather than a changelog line.
+ *
+ * The rename is NOT scope-preserving, and that cannot be fixed here — there is
+ * no menu-only dot element left to address. `radio-indicator-dot` reaches every
+ * radio dot in the app, including RadioList's. So every rewritten site also
+ * gets a TODO comment (api.report is a stub; comments are the only warning
+ * channel) telling the author to check whether the rule was meant to be
+ * menu-only, and pointing at the containing-target route if it was.
+ */
+
+export const meta = {
+  title: 'Rename the removed dropdown-menu-radio-dot theme target',
+  description:
+    'Renames the `dropdown-menu-radio-dot` theme target (and the ' +
+    '`astryx-dropdown-menu-radio-dot` class it rendered) to ' +
+    '`radio-indicator-dot` / `astryx-radio-indicator-dot`. Menu radios draw ' +
+    'the shared radio indicator now, so the menu-specific dot target no ' +
+    'longer exists. The new target is app-wide rather than menu-only, so each ' +
+    'rewritten site gets a TODO comment to confirm that widening is intended.',
+  pr: '#4712',
+};
+
+const OLD_TARGET = 'dropdown-menu-radio-dot';
+const NEW_TARGET = 'radio-indicator-dot';
+const OLD_CLASS = `astryx-${OLD_TARGET}`;
+const NEW_CLASS = `astryx-${NEW_TARGET}`;
+
+const TODO_COMMENT =
+  ' TODO(astryx upgrade): `dropdown-menu-radio-dot` became `radio-indicator-dot`,' +
+  ' which styles EVERY radio dot, not just the ones in a menu. If this rule was' +
+  ' meant to be menu-only, scope it under the containing `dropdown-menu-radio`' +
+  ' target instead of this one. ';
+
+/**
+ * Rewrite one string value, or return null when it holds nothing to rename.
+ *
+ * Handles the target name on its own (a theme's `components` key) and the
+ * rendered class inside a larger string (a selector such as
+ * `.astryx-dropdown-menu-radio-dot`, or a className list).
+ *
+ * @param {string} value
+ * @returns {string | null}
+ */
+function renameIn(value) {
+  if (value === OLD_TARGET) {
+    return NEW_TARGET;
+  }
+  if (value.includes(OLD_CLASS)) {
+    return value.split(OLD_CLASS).join(NEW_CLASS);
+  }
+  return null;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  // Cheap bail-out: most files in a consumer repo mention neither name.
+  if (!file.source.includes(OLD_TARGET)) {
+    return undefined;
+  }
+
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  /** Attach the widening warning once to the nearest statement-ish node. */
+  function attachTodo(/** @type {any} */ path) {
+    // The property (or its statement) reads better than the bare literal, and
+    // matches where a human would look for the note.
+    const host =
+      path.parent?.node?.type === 'ObjectProperty' ||
+      path.parent?.node?.type === 'Property'
+        ? path.parent.node
+        : path.node;
+    if (!host.comments) {
+      host.comments = [];
+    }
+    if (
+      host.comments.some((/** @type {any} */ c) => c.value === TODO_COMMENT)
+    ) {
+      return;
+    }
+    host.comments.push(j.commentBlock(TODO_COMMENT, true, false));
+  }
+
+  root
+    .find(j.StringLiteral)
+    .forEach((/** @type {any} */ path) => {
+      const renamed = renameIn(path.node.value);
+      if (renamed == null) {
+        return;
+      }
+      path.node.value = renamed;
+      attachTodo(path);
+      hasChanges = true;
+    });
+
+  // Older parsers surface string literals as `Literal`.
+  root.find(j.Literal).forEach((/** @type {any} */ path) => {
+    if (typeof path.node.value !== 'string') {
+      return;
+    }
+    const renamed = renameIn(path.node.value);
+    if (renamed == null) {
+      return;
+    }
+    path.node.value = renamed;
+    if (typeof path.node.raw === 'string') {
+      path.node.raw = path.node.raw
+        .split(OLD_TARGET)
+        .join(NEW_TARGET);
+    }
+    attachTodo(path);
+    hasChanges = true;
+  });
+
+  // Template literals carry the class in CSS strings: `.${OLD_CLASS} > span`.
+  root.find(j.TemplateElement).forEach((/** @type {any} */ path) => {
+    const cooked = path.node.value?.cooked;
+    if (typeof cooked !== 'string') {
+      return;
+    }
+    const renamed = renameIn(cooked);
+    if (renamed == null) {
+      return;
+    }
+    path.node.value.cooked = renamed;
+    path.node.value.raw = path.node.value.raw
+      .split(OLD_CLASS)
+      .join(NEW_CLASS)
+      .split(OLD_TARGET)
+      .join(NEW_TARGET);
+    hasChanges = true;
+  });
+
+  return hasChanges ? root.toSource({quote: 'single'}) : undefined;
+}

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-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/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/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`',
           ],
         },
       ],