@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

package/src/Table/plugins/tree/useTableTreeState.tsx

@@ -0,0 +1,253 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableTreeState.tsx
+ * @input React
+ * @output Exports useTableTreeState hook and config/result types
+ * @position Tree state helper; owns the expanded set + flattens nested data.
+ *   Pairs with useTableTreeData (the headless tree plugin).
+ *
+ * Modeled after useTableSortableState — a convenience layer that owns state
+ * (controlled or uncontrolled) and produces both the visible flattened rows
+ * and a ready-to-use config for the headless plugin. Data shaping stays
+ * outside the render pipeline: Table always receives exactly the rows it
+ * renders, so collapsed subtrees are unmounted, not hidden.
+ */
+
+import {useCallback, useMemo, useRef, useState} from 'react';
+import type {
+  TableTreeRowMeta,
+  UseTableTreeDataConfig,
+} from './useTableTreeData';
+
+// =============================================================================
+// Config
+// =============================================================================
+
+export interface UseTableTreeStateConfig<T extends Record<string, unknown>> {
+  /** Nested data: rows may carry child rows under `childrenKey`. */
+  data: T[];
+  /** Row ID accessor: property name, or a function returning a unique id. */
+  idKey: (keyof T & string) | ((item: T) => string | number);
+  /**
+   * Property holding each row's children array.
+   * @default 'children'
+   */
+  childrenKey?: string;
+  /** Initial expanded row ids for uncontrolled mode. Ignored when `expandedIds` is provided. */
+  defaultExpandedIds?: Iterable<string>;
+  /**
+   * Controlled set of expanded row ids. When provided, the hook uses this
+   * instead of internal state. Pair with `onExpandedIdsChange`.
+   */
+  expandedIds?: ReadonlySet<string>;
+  /** Called with the next expanded set whenever expansion changes. */
+  onExpandedIdsChange?: (ids: ReadonlySet<string>) => void;
+  /**
+   * Should this row show an expander? Overrides the default
+   * "has a non-empty children array" check — use for lazy loading, where a
+   * row is expandable before its children have been fetched.
+   */
+  isItemExpandable?: (item: T) => boolean;
+  /**
+   * Sort each sibling group independently during flattening. Children always
+   * stay directly under their parent — sorting never crosses levels. Pass
+   * `applySort` from `useTableSortableState` to compose with column sorting.
+   */
+  sortSiblings?: (siblings: T[]) => T[];
+  /** Indent step per level, forwarded to useTableTreeData. */
+  indent?: 'sm' | 'md' | 'lg';
+  /** Column that carries the tree affordance, forwarded to useTableTreeData. */
+  treeColumnKey?: string;
+}
+
+// =============================================================================
+// Result
+// =============================================================================
+
+export interface UseTableTreeStateResult<T extends Record<string, unknown>> {
+  /** The flattened, currently-visible rows. Pass to `<Table data>`. */
+  visibleData: T[];
+  /** Ready-to-use config for useTableTreeData. */
+  treeConfig: UseTableTreeDataConfig<T>;
+  /** The current expanded row ids. */
+  expandedIds: ReadonlySet<string>;
+  /** Expand every expandable row in the tree. */
+  expandAll: () => void;
+  /** Collapse every row. */
+  collapseAll: () => void;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useTableTreeState<T extends Record<string, unknown>>(
+  config: UseTableTreeStateConfig<T>,
+): UseTableTreeStateResult<T> {
+  const {
+    data,
+    idKey,
+    childrenKey = 'children',
+    defaultExpandedIds,
+    expandedIds: controlledExpandedIds,
+    onExpandedIdsChange,
+    isItemExpandable,
+    sortSiblings,
+    indent,
+    treeColumnKey,
+  } = config;
+
+  const getId = useCallback(
+    (item: T): string =>
+      typeof idKey === 'function' ? String(idKey(item)) : String(item[idKey]),
+    [idKey],
+  );
+
+  const getChildren = useCallback(
+    (item: T): T[] => {
+      const children = item[childrenKey];
+      return Array.isArray(children) ? (children as T[]) : [];
+    },
+    [childrenKey],
+  );
+
+  const getIsExpandable = useCallback(
+    (item: T): boolean =>
+      isItemExpandable ? isItemExpandable(item) : getChildren(item).length > 0,
+    [isItemExpandable, getChildren],
+  );
+
+  // Internal state (used in uncontrolled mode)
+  const [internalExpandedIds, setInternalExpandedIds] = useState<
+    ReadonlySet<string>
+  >(() => new Set(defaultExpandedIds));
+
+  // Resolve controlled vs uncontrolled
+  const isControlled = controlledExpandedIds !== undefined;
+  const expandedIds = isControlled
+    ? controlledExpandedIds
+    : internalExpandedIds;
+
+  // Stable refs so callbacks don't churn on inline-prop identity changes
+  const expandedIdsRef = useRef(expandedIds);
+  expandedIdsRef.current = expandedIds;
+  const onExpandedIdsChangeRef = useRef(onExpandedIdsChange);
+  onExpandedIdsChangeRef.current = onExpandedIdsChange;
+
+  const commitExpandedIds = useCallback(
+    (next: ReadonlySet<string>) => {
+      // Advance the ref immediately so a second commit in the same React
+      // batch (e.g. two onToggleItem calls in one event handler) builds
+      // on this one instead of the pre-batch set. The ref re-syncs from
+      // the resolved state on the next render either way.
+      expandedIdsRef.current = next;
+      if (!isControlled) {
+        setInternalExpandedIds(next);
+      }
+      onExpandedIdsChangeRef.current?.(next);
+    },
+    [isControlled],
+  );
+
+  // Flatten: depth-first walk emitting only visible rows, collecting per-row
+  // meta ({level, hasChildren, isExpanded}) in the same pass. Children mount
+  // only when their parent is expanded, so collapsed subtrees stay unmounted.
+  // `path` holds the ids on the current ancestor chain: an edge pointing back
+  // at an ancestor is skipped instead of recursing forever. Sibling arrays
+  // are copied before sortSiblings so an in-place sorter can't reorder the
+  // consumer's data.
+  const {visibleData, metaMap} = useMemo(() => {
+    const rows: T[] = [];
+    const meta = new Map<string, TableTreeRowMeta>();
+    const path = new Set<string>();
+    const walk = (items: T[], level: number) => {
+      const siblings = sortSiblings ? sortSiblings([...items]) : items;
+      for (const item of siblings) {
+        const id = getId(item);
+        if (path.has(id)) {
+          continue; // cyclic edge — this row is its own ancestor
+        }
+        const hasChildren = getIsExpandable(item);
+        const isExpanded = hasChildren && expandedIds.has(id);
+        rows.push(item);
+        meta.set(id, {id, level, hasChildren, isExpanded});
+        if (isExpanded) {
+          path.add(id);
+          walk(getChildren(item), level + 1);
+          path.delete(id);
+        }
+      }
+    };
+    walk(data, 0);
+    return {visibleData: rows, metaMap: meta};
+  }, [data, expandedIds, getId, getChildren, getIsExpandable, sortSiblings]);
+
+  // Every expandable row id across the whole tree, including collapsed
+  // subtrees (drives expandAll and the migration no-op flag). Same
+  // ancestor-chain guard as the flatten walk.
+  const allExpandableIds = useMemo(() => {
+    const idsAcc: string[] = [];
+    const path = new Set<string>();
+    const walk = (items: T[]) => {
+      for (const item of items) {
+        const id = getId(item);
+        if (path.has(id)) {
+          continue;
+        }
+        if (getIsExpandable(item)) {
+          idsAcc.push(id);
+        }
+        path.add(id);
+        walk(getChildren(item));
+        path.delete(id);
+      }
+    };
+    walk(data);
+    return idsAcc;
+  }, [data, getId, getChildren, getIsExpandable]);
+
+  const hasExpandableRows = allExpandableIds.length > 0;
+
+  const onToggleItem = useCallback(
+    (item: T) => {
+      const id = getId(item);
+      const next = new Set(expandedIdsRef.current);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      commitExpandedIds(next);
+    },
+    [getId, commitExpandedIds],
+  );
+
+  const expandAll = useCallback(() => {
+    commitExpandedIds(new Set(allExpandableIds));
+  }, [commitExpandedIds, allExpandableIds]);
+
+  const collapseAll = useCallback(() => {
+    commitExpandedIds(new Set());
+  }, [commitExpandedIds]);
+
+  const getRowMeta = useCallback(
+    (item: T): TableTreeRowMeta | undefined => metaMap.get(getId(item)),
+    [metaMap, getId],
+  );
+
+  const treeConfig = useMemo(
+    (): UseTableTreeDataConfig<T> => ({
+      getRowMeta,
+      onToggleItem,
+      hasExpandableRows,
+      indent,
+      treeColumnKey,
+    }),
+    [getRowMeta, onToggleItem, hasExpandableRows, indent, treeColumnKey],
+  );
+
+  return {visibleData, treeConfig, expandedIds, expandAll, collapseAll};
+}

package/src/Table/useBaseTablePlugins.ts

@@ -18,12 +18,15 @@
  * Canonical order:
  *   1. columnSettings — column filtering (future: transformColumns)
  *   2. sort           — header cell sort controls
- *   3. selection      — checkbox column + row selection
- *   4. pagination     — pagination controls around the table
+ *   3. tree           — indent + expander on the tree column
+ *   4. selection      — checkbox column + row selection
+ *   5. pagination     — pagination controls around the table
  *
  * Rationale:
  * - columnSettings filters columns before sort/selection see them
  * - sort adds header cell UI before selection adds its header column
+ * - tree wraps the first *user* column before selection prepends its
+ *   checkbox column, so the expander never lands in the checkbox column
  * - selection adds its column after sort so the checkbox header
  *   doesn't get a sort button
  * - pagination wraps the table in context last (outermost provider)
@@ -46,6 +49,7 @@ import type {TablePlugin} from './types';
 const PLUGIN_ORDER: ReadonlyArray<string> = [
   'columnSettings',
   'sort',
+  'tree',
   'selection',
   'pagination',
 ];

package/src/Table/useTableTreeData.doc.mjs

@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableTreeData',
+  subComponentOf: 'Table',
+  displayName: 'useTableTreeData',
+  description:
+    'Headless tree plugin for Table: renders nested rows with per-level indentation and expand/collapse chevrons in the tree column (the first column by default), and reflects hierarchy on body rows via aria-level and aria-expanded. Composable with the other Table plugins: the canonical plugin order places tree before selection, so the checkbox column lands left of the indented tree column. Feed it the treeConfig from useTableTreeState, or construct the config directly for server-driven or pre-flattened trees. When no row is expandable (flat data), every transform is a pass-through and the table renders identically to one without the plugin. Known limitation: the tree column wraps its cell content, so textOverflow="truncate" tooltips do not apply within the tree column.',
+  props: [
+    {
+      name: 'getRowMeta',
+      type: '(item: T) => TableTreeRowMeta | undefined',
+      description:
+        'Structural meta for a visible row: {id, level (0-based), hasChildren, isExpanded}.',
+      required: true,
+    },
+    {
+      name: 'onToggleItem',
+      type: '(item: T) => void',
+      description: 'Toggle a row\'s expansion.',
+      required: true,
+    },
+    {
+      name: 'hasExpandableRows',
+      type: 'boolean',
+      description:
+        'Whether any row in the dataset is expandable. When false the plugin is a no-op: no expanders, no indent, no tree ARIA.',
+      required: true,
+    },
+    {
+      name: 'indent',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        'Indent step per level, mapped to the spacing-3 / spacing-4 / spacing-6 tokens.',
+      default: "'md'",
+    },
+    {
+      name: 'treeColumnKey',
+      type: 'string',
+      description:
+        'Column that carries the indent + expander. Defaults to the first column.',
+    },
+  ],
+  examples: [
+    {
+      label: 'File tree with expandable folders',
+      code: `const {visibleData, treeConfig} = useTableTreeState({
+  data: files,          // rows may nest under 'children'
+  idKey: 'id',
+  defaultExpandedIds: ['src'],
+});
+const tree = useTableTreeData(treeConfig);
+
+<Table data={visibleData} columns={columns} idKey="id" plugins={{tree}} />;`,
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableTreeData',
+  displayName: 'useTableTreeData',
+  description:
+    'Headless tree plugin: indent + expander chevron on the tree column (first column by default), aria-level/aria-expanded on body rows. Canonical plugin order puts tree before selection (checkbox column lands left of tree column). Consume treeConfig from useTableTreeState, or construct directly for server-driven trees. hasExpandableRows=false => full no-op (flat-data migration).',
+  propDescriptions: {
+    getRowMeta:
+      'structural meta per visible row: {id, level (0-based), hasChildren, isExpanded}',
+    onToggleItem: 'toggle row expansion',
+    hasExpandableRows: 'false => plugin is a no-op (no expanders/indent/ARIA)',
+    indent:
+      "indent step per level: 'sm' | 'md' | 'lg' (spacing-3/4/6). Defaults to 'md'.",
+    treeColumnKey: 'column carrying indent + expander. Defaults to first column.',
+  },
+};

package/src/Table/useTableTreeState.doc.mjs

@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableTreeState',
+  subComponentOf: 'Table',
+  displayName: 'useTableTreeState',
+  description:
+    'State management companion for useTableTreeData. Owns the expanded set (controlled or uncontrolled) and flattens nested data into the visible row array; collapsed subtrees are unmounted, not hidden, so the table body contains exactly the visible rows. Returns expandAll/collapseAll helpers and a ready-to-use config for the tree plugin. Note: because collapsed rows unmount, cell-local React state inside collapsed subtrees is lost on collapse; lift state that must survive.',
+  props: [
+    {
+      name: 'data',
+      type: 'T[]',
+      description:
+        'Nested data: rows may carry child rows under childrenKey. Flat data (no children anywhere) makes the plugin a no-op, so it can be adopted before the data becomes hierarchical.',
+      required: true,
+    },
+    {
+      name: 'idKey',
+      type: '(keyof T & string) | ((item: T) => string | number)',
+      description:
+        'Row ID accessor: property name or function returning a unique id.',
+      required: true,
+    },
+    {
+      name: 'childrenKey',
+      type: 'string',
+      description: 'Property holding each row\'s children array.',
+      default: "'children'",
+    },
+    {
+      name: 'defaultExpandedIds',
+      type: 'Iterable<string>',
+      description:
+        'Initial expanded row ids for uncontrolled mode. Ignored when expandedIds is provided.',
+    },
+    {
+      name: 'expandedIds',
+      type: 'ReadonlySet<string>',
+      description:
+        'Controlled set of expanded row ids. Pair with onExpandedIdsChange.',
+    },
+    {
+      name: 'onExpandedIdsChange',
+      type: '(ids: ReadonlySet<string>) => void',
+      description:
+        'Called with the next expanded set whenever expansion changes (both modes). In lazy-loading setups, trigger the children fetch here.',
+    },
+    {
+      name: 'isItemExpandable',
+      type: '(item: T) => boolean',
+      description:
+        'Should this row show an expander? Overrides the default non-empty-children check; use for lazy loading, where a row is expandable before its children have been fetched.',
+    },
+    {
+      name: 'sortSiblings',
+      type: '(siblings: T[]) => T[]',
+      description:
+        'Sort each sibling group independently during flattening; children always stay directly under their parent. Pass applySort from useTableSortableState to compose with column sorting.',
+    },
+    {
+      name: 'indent',
+      type: "'sm' | 'md' | 'lg'",
+      description:
+        'Indent step per level (spacing-3 / spacing-4 / spacing-6), forwarded to useTableTreeData.',
+      default: "'md'",
+    },
+    {
+      name: 'treeColumnKey',
+      type: 'string',
+      description:
+        'Column that carries the indent + expander, forwarded to useTableTreeData. Defaults to the first column.',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableTreeState',
+  displayName: 'useTableTreeState',
+  description:
+    'State companion for useTableTreeData. Owns expanded set (controlled or uncontrolled), flattens nested data to visible rows (collapsed subtrees unmounted, not hidden). Returns {visibleData, treeConfig, expandedIds, expandAll, collapseAll}. Cell-local state in collapsed subtrees is lost on collapse; lift state that must survive.',
+  propDescriptions: {
+    data: 'nested data; rows carry child rows under childrenKey. Flat data => plugin is a no-op.',
+    idKey: 'row ID accessor: property name or fn returning unique id',
+    childrenKey: "property holding children array. Defaults to 'children'.",
+    defaultExpandedIds: 'initial expanded ids (uncontrolled)',
+    expandedIds: 'controlled expanded set; pair with onExpandedIdsChange',
+    onExpandedIdsChange:
+      'called with next expanded set on change (both modes); trigger lazy children fetch here',
+    isItemExpandable:
+      'overrides non-empty-children expandability check (lazy loading)',
+    sortSiblings:
+      'sorts each sibling group during flattening; pass applySort from useTableSortableState',
+    indent: "indent step per level: 'sm' | 'md' | 'lg'. Defaults to 'md'.",
+    treeColumnKey: 'column carrying indent + expander. Defaults to first column.',
+  },
+};

package/src/TextArea/TextArea.doc.mjs

@@ -116,7 +116,7 @@ export const docs = {
       name: 'startIcon',
       type: 'IconType',
       description:
-        'Icon component rendered inside the leading edge of the textarea wrapper. See `npx astryx docs icons` for valid semantic names.',
+        'Icon component rendered inside the leading edge of the textarea wrapper. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'hasSpellCheck',

package/src/TextInput/TextInput.doc.mjs

@@ -106,7 +106,7 @@ export const docs = {
       name: 'startIcon',
       type: 'IconType',
       description:
-        'SVG icon component displayed at the start of the input. See `npx astryx docs icons` for valid semantic names.',
+        'SVG icon component displayed at the start of the input. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'status',

package/src/Toolbar/Toolbar.tsx

@@ -239,6 +239,7 @@ export function Toolbar({
   const hasCenterContent = centerContent != null;
   const hasStartContent = startContent != null;
   const hasEndContent = endContent != null;
+  const hasBottomDivider = dividers?.includes('bottom') ?? false;
 
   const gapVar = spacingVars[spacingStepToVar[gap]] as string;
 
@@ -316,9 +317,15 @@ export function Toolbar({
               orientation === 'vertical' && styles.vertical,
               sizeStyles.base,
               dynamicStyles.gap(gapVar),
-              dynamicStyles.tabIndicatorBottom(
-                `calc(-1 * (${blockPaddingVarForSize[size]}${dividers?.includes('bottom') ? ' + 1px' : ''}))`,
-              ),
+              // Only drop the tab indicator through the toolbar's block padding
+              // onto the rail when a bottom divider is actually present.
+              // Without a divider, leave `--_tab-indicator-bottom` unset so a
+              // nested TabList's indicator keeps its own default (hugging the
+              // tab) instead of floating down into the toolbar's padding.
+              hasBottomDivider &&
+                dynamicStyles.tabIndicatorBottom(
+                  `calc(-1 * (${blockPaddingVarForSize[size]} + 1px))`,
+                ),
             ),
           )}
           {...props}>

package/src/TreeList/TreeList.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TreeList} from './TreeList';
 import type {TreeListItemData} from './TreeListTypes';
@@ -251,6 +251,37 @@ describe('TreeList', () => {
     expect(screen.getByText('Leaf')).toBeInTheDocument();
   });
 
+  // ===========================================================================
+  // Focus-visible outline scoping (regression: focusing a parent row must not
+  // leak the ring onto descendant rows — see #4130)
+  // ===========================================================================
+
+  it('scopes the focus-visible outline to the focused row, not its descendants', () => {
+    render(<TreeList items={deepItems} />);
+    const root = screen.getByText('Root').closest('li')!;
+    const mid = screen.getByText('Mid').closest('li')!;
+    const leaf = screen.getByText('Leaf').closest('li')!;
+
+    // A keydown before .focus() establishes keyboard modality so jsdom's
+    // :focus-visible heuristic applies deterministically, regardless of
+    // pointer events left over from other tests in this file.
+    fireEvent.keyDown(document.body, {key: 'Tab'});
+    root.focus();
+    expect(root).toHaveFocus();
+
+    expect(
+      getComputedStyle(root).getPropertyValue('--_tree-focus-outline'),
+    ).toContain('solid');
+    // Mid and Leaf are DOM descendants of Root's <li> (nested <ul role="group">
+    // subtrees) — their own outline var must stay unset, not inherit Root's.
+    expect(
+      getComputedStyle(mid).getPropertyValue('--_tree-focus-outline'),
+    ).toBe('none');
+    expect(
+      getComputedStyle(leaf).getPropertyValue('--_tree-focus-outline'),
+    ).toBe('none');
+  });
+
   // ===========================================================================
   // Interactive items
   // ===========================================================================

package/src/TreeList/TreeListItem.tsx

@@ -29,7 +29,6 @@ import {mergeProps} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity} from './TreeListTypes';
-import {treeItemScope} from './treeListItem.markers.stylex';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
@@ -47,6 +46,19 @@ const styles = stylex.create({
     // The treeitem row is the roving-tabindex focus owner; suppress the
     // native focus ring in favor of the row's :focus-visible outline below.
     outline: 'none',
+    // Publish this row's own focus state as an inheritable CSS variable
+    // instead of matching it via an ancestor selector. Every nested <li>
+    // redeclares these vars (default: 'none' / '0'), so a descendant row's
+    // default shadows an ancestor's active value — the ring can never leak
+    // past the nearest containing treeitem, however deep the tree nests.
+    '--_tree-focus-outline': {
+      default: 'none',
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    '--_tree-focus-outline-offset': {
+      default: '0',
+      ':focus-visible': '2px',
+    },
   },
   childGroup: {
     margin: 0,
@@ -86,17 +98,14 @@ const styles = stylex.create({
   },
   focusVisibleOutline: {
     outline: {
-      default: 'none',
-      // Focus lives on the treeitem row (the <li>) via roving tabindex.
-      // Scoped to the row's OWN treeitem so focusing a parent does not leak
-      // the ring onto descendant rows. Also support inner focusable actions.
-      [stylex.when.ancestor(':focus-visible', treeItemScope)]:
-        `2px solid ${colorVars['--color-accent']}`,
+      // Reads the row's own --_tree-focus-outline (published on the <li> in
+      // `wrapper`), which resolves to the nearest containing treeitem only.
+      default: 'var(--_tree-focus-outline, none)',
+      // Also support inner focusable actions.
       ':has(:focus-visible)': `2px solid ${colorVars['--color-accent']}`,
     },
     outlineOffset: {
-      default: '0',
-      [stylex.when.ancestor(':focus-visible', treeItemScope)]: '2px',
+      default: 'var(--_tree-focus-outline-offset, 0)',
       ':has(:focus-visible)': '2px',
     },
   },
@@ -451,7 +460,7 @@ export function TreeListItem({
       data-tree-id={id}
       data-tree-level={nestedLevel + 1}
       data-tree-disabled={isDisabled || undefined}
-      {...stylex.props(styles.wrapper, treeItemScope)}>
+      {...stylex.props(styles.wrapper)}>
       <div {...stylex.props(styles.treeBranches)}>
         <TreeListBranches
           ancestorsIsLast={ancestorsIsLast}

package/src/docs-script.test.mjs

@@ -3,12 +3,13 @@
 /**
  * @file Subprocess smoke tests for the zero-dependency docs script.
  *
- * `docs.mjs` resolves the package directory from `import.meta.url`. Using
- * `new URL(...).pathname` there breaks on Windows (drive-letter paths come
- * back as `/D:/...`), which made `--list` print nothing and component
- * lookups crash with ENOENT. These tests spawn the script as a real
- * subprocess from a neutral cwd, so resolution can only come from the
- * module URL, and assert it finds the component catalog on every platform.
+ * `docs.mjs` no longer prints component docs itself — it intentionally
+ * redirects to the Astryx CLI (`npx @astryxdesign/cli init`) so agents and
+ * humans converge on the CLI + `init` rather than a stale bundled snapshot.
+ * These tests spawn the script as a real subprocess from a neutral cwd and
+ * assert that, regardless of the arguments passed, it prints the redirect
+ * banner and exits 0 instead of rendering a component catalog or per-component
+ * docs.
  */
 
 import {describe, it, expect} from 'vitest';
@@ -29,22 +30,26 @@ function runDocs(args) {
   });
 }
 
-describe('docs.mjs component discovery', () => {
-  it('--list discovers the component catalog', () => {
+describe('docs.mjs redirects to the Astryx CLI', () => {
+  it('redirects to the CLI instead of printing a component catalog for --list', () => {
     const r = runDocs(['--list']);
     expect(r.error).toBeUndefined();
     expect(r.signal).toBeNull();
     expect(r.status).toBe(0);
-    expect(r.stdout).toMatch(/\bButton\b/);
-    expect(r.stdout).toMatch(/\bDialog\b/);
+    // Prints the redirect banner, not a component list.
+    expect(r.stdout).toMatch(/docs are served by the Astryx CLI/);
+    expect(r.stdout).toMatch(/npx @astryxdesign\/cli init/);
+    expect(r.stdout).toMatch(/npx @astryxdesign\/cli component --list/);
   });
 
-  it('renders docs for a single component', () => {
+  it('redirects to the CLI instead of rendering docs for a single component', () => {
     const r = runDocs(['Button']);
     expect(r.error).toBeUndefined();
     expect(r.signal).toBeNull();
     expect(r.status).toBe(0);
-    expect(r.stdout).toMatch(/^# Button$/m);
-    expect(r.stdout).toMatch(/## Props/);
+    // A pure redirect: it must not render the component's docs.
+    expect(r.stdout).not.toMatch(/^# Button$/m);
+    expect(r.stdout).not.toMatch(/## Props/);
+    expect(r.stdout).toMatch(/npx @astryxdesign\/cli component <Name>/);
   });
 });