@astryxdesign/core 0.1.7-canary.fb9c68c → 0.1.7

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

@@ -1,253 +0,0 @@
-// 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/useTableTreeData.doc.mjs

@@ -1,75 +0,0 @@
-// 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

@@ -1,98 +0,0 @@
-// 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/postinstall.test.mjs

@@ -1,71 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Guardrail tests for the @astryxdesign/core postinstall nudge (layer 1).
- *
- * The marker check mirrors the CLI's single source of truth (core can't import
- * the CLI). Tests that it detects the marker across EVERY agent-doc location
- * (incl. Hermes) + legacy markers, and that the nudge decision matrix is correct.
- */
-
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import {isAstryxInitialized, shouldNudge} from '../scripts/postinstall.mjs';
-
-const MARKER = '<!-- ASTRYX:START -->';
-
-let tmp;
-beforeEach(() => {
-  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-postinstall-'));
-});
-afterEach(() => {
-  fs.rmSync(tmp, {recursive: true, force: true});
-});
-function write(rel, body) {
-  const p = path.join(tmp, rel);
-  fs.mkdirSync(path.dirname(p), {recursive: true});
-  fs.writeFileSync(p, body);
-}
-
-describe('core postinstall — isAstryxInitialized (mirrors CLI contract)', () => {
-  it('is false in an empty project', () => {
-    expect(isAstryxInitialized(tmp)).toBe(false);
-  });
-
-  it.each(['AGENTS.md', 'CLAUDE.md', '.claude/CLAUDE.md', '.cursorrules', '.hermes.md', 'HERMES.md'])(
-    'detects the marker in %s',
-    file => {
-      write(file, `# doc\n${MARKER}\nbody`);
-      expect(isAstryxInitialized(tmp)).toBe(true);
-    },
-  );
-
-  it('detects the legacy XDS marker', () => {
-    write('AGENTS.md', '<!-- XDS:START -->');
-    expect(isAstryxInitialized(tmp)).toBe(true);
-  });
-});
-
-describe('core postinstall — shouldNudge', () => {
-  const DEP = '/proj/node_modules/@astryxdesign/core/scripts/postinstall.mjs';
-  const NPX = '/Users/x/.npm/_npx/a1/node_modules/@astryxdesign/core/scripts/postinstall.mjs';
-  const REPO = '/repo/packages/core/scripts/postinstall.mjs';
-
-  it('nudges for a real dependency install when not set up', () => {
-    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: false})).toBe(true);
-  });
-  it('quiet in the monorepo/source', () => {
-    expect(shouldNudge({scriptPath: REPO, npmCommand: 'install', isSetUp: false})).toBe(false);
-  });
-  it('quiet during npx transient install (_npx path)', () => {
-    expect(shouldNudge({scriptPath: NPX, npmCommand: 'install', isSetUp: false})).toBe(false);
-  });
-  it('quiet during npx (npm_command=exec)', () => {
-    expect(shouldNudge({scriptPath: DEP, npmCommand: 'exec', isSetUp: false})).toBe(false);
-  });
-  it('quiet once set up', () => {
-    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: true})).toBe(false);
-  });
-});