@exegia/corpora-ui 0.19.0 → 0.20.0

package/dist-lib/components/blocks/nav/sidebar/__tests__/use-ai-sidebar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/blocks/nav/sidebar/ai-sidebar.d.ts

@@ -1,2 +1,11 @@
-import { AISidebarProps } from './type';
-export declare function AISidebar({ renderIcon, renderMenu, renderActionsTrigger, ariaLabel, className, ...options }: AISidebarProps): import("react").JSX.Element;
+import { AISidebarComponentProps } from './type';
+/**
+ * Resource tree for the app rail: nested rows with drag-and-drop reorder,
+ * inline rename, per-row action menus and full keyboard navigation.
+ *
+ * Two ways to drive it. Pass the data and handlers as props and the block
+ * owns its state, or hold a `useAISidebar` controller and pass it as
+ * `controller` — the same rendering, but select, expand, rename, reorder
+ * and menu state are then callable from anywhere in your app.
+ */
+export declare function AISidebar(props: AISidebarComponentProps): import("react").JSX.Element;

package/dist-lib/components/blocks/nav/sidebar/type.d.ts

@@ -17,7 +17,10 @@ export interface SidebarResourceMenuControls {
     close: () => void;
     rename: () => void;
 }
-export interface AISidebarProps {
+/** Options for `useAISidebar`. `items`, `activeId` and `expandedIds` are
+ * each controlled when passed and hook-owned via their `default*` twin
+ * otherwise. */
+export interface UseAISidebarOptions {
     items?: SidebarResource[];
     defaultItems?: SidebarResource[];
     onItemsChange?: (items: SidebarResource[]) => void;
@@ -28,7 +31,77 @@ export interface AISidebarProps {
     activeId?: string | null;
     defaultActiveId?: string | null;
     onActiveChange?: (id: string) => void;
+    expandedIds?: string[];
     defaultExpandedIds?: string[];
+    onExpandedChange?: (ids: string[]) => void;
+}
+/** Everything the sidebar can do, callable from outside the block — a
+ * toolbar, a command palette, a route change. Returned by `useAISidebar`
+ * and accepted by `<AISidebar controller={…} />`. */
+export interface AISidebarController {
+    items: SidebarResource[];
+    /** Visible rows in order, each with its depth and parent id. */
+    flat: FlatResource[];
+    getItem: (id: string) => SidebarResource | undefined;
+    selectedId: string | null;
+    select: (id: string) => void;
+    expandedIds: ReadonlySet<string>;
+    isExpanded: (id: string) => boolean;
+    expand: (id: string) => void;
+    collapse: (id: string) => void;
+    toggleExpanded: (id: string) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    /** Open every ancestor of `id`, leaving the rest of the tree alone. */
+    reveal: (id: string) => void;
+    /** Roving-focus target. `focus` also moves DOM focus to the row. */
+    focusedId: string | null;
+    focus: (id: string) => void;
+    renamingId: string | null;
+    startRename: (id: string) => void;
+    cancelRename: () => void;
+    /** Commit a rename and leave rename mode. Applied optimistically and
+     * rolled back if `onRename` rejects. Blank and unchanged labels are
+     * dropped. */
+    rename: (id: string, label: string) => void;
+    menuOpenId: string | null;
+    openMenu: (id: string) => void;
+    closeMenu: () => void;
+    /** Reorder, applied optimistically and rolled back if `onMove` rejects.
+     * Refuses moves the data forbids (into itself, into a non-container). */
+    move: (move: SidebarResourceMove) => Promise<void>;
+    /** A move is in flight — further moves are refused until it settles. */
+    movePending: boolean;
+    /** Live-region text for the last move or rename outcome. */
+    announcement: string;
+    /** @internal Row wiring the view threads through — drag state, the
+     * hover pill and roving keyboard nav all belong to the rendering. */
+    dnd: AISidebarDndState;
+    hover: AISidebarHoverState;
+    onRowKeyDown: (event: KeyboardEvent<HTMLDivElement>, row: FlatResource) => void;
+    setRowRef: (id: string, node: HTMLDivElement | null) => void;
+}
+/** @internal */
+export interface AISidebarDndState {
+    draggingId: string | null;
+    dropTarget: DropTarget | null;
+    onRootDragOver: (event: DragEvent<HTMLDivElement>) => void;
+    onDrop: (event: DragEvent<HTMLDivElement>) => void;
+    onRowDragStart: (event: DragEvent<HTMLDivElement>, id: string) => void;
+    onRowDragEnd: () => void;
+    onRowDragOver: (event: DragEvent<HTMLDivElement>, row: FlatResource) => void;
+}
+/** @internal */
+export interface AISidebarHoverState {
+    hoveredId: string | null;
+    /** Shared motion layoutId that lets the pill travel between rows. */
+    layoutId: string;
+    onRowHover: (id: string, hovered: boolean) => void;
+    clear: () => void;
+}
+export interface AISidebarProps extends UseAISidebarOptions {
+    /** Never set on the data form — `controller` selects the other one. */
+    controller?: never;
     renderIcon?: (item: SidebarResource) => ReactNode;
     renderMenu?: (item: SidebarResource, controls: SidebarResourceMenuControls) => ReactNode;
     /**
@@ -39,6 +112,15 @@ export interface AISidebarProps {
     ariaLabel?: string;
     className?: string;
 }
+/** Presentational props, shared by both forms of `<AISidebar>`. */
+export type AISidebarViewProps = Pick<AISidebarProps, "renderIcon" | "renderMenu" | "renderActionsTrigger" | "ariaLabel" | "className">;
+/** Drive the block from a `useAISidebar` controller instead of raw props —
+ * the controller carries the data and every handler. */
+export interface AISidebarControllerProps extends AISidebarViewProps {
+    controller: AISidebarController;
+}
+/** Either form: raw props, or a `useAISidebar` controller. */
+export type AISidebarComponentProps = AISidebarProps | AISidebarControllerProps;
 export interface FlatResource {
     item: SidebarResource;
     depth: number;

package/dist-lib/components/blocks/nav/sidebar/use-ai-sidebar.d.ts

@@ -1,31 +1,22 @@
-import { DragEvent, KeyboardEvent } from 'react';
-import { AISidebarProps, DropTarget, FlatResource } from './type.ts';
-export type UseAISidebarOptions = Pick<AISidebarProps, "items" | "defaultItems" | "onItemsChange" | "onMove" | "onMoveError" | "onRename" | "activeId" | "defaultActiveId" | "onActiveChange" | "defaultExpandedIds">;
-export declare function useAISidebar({ items, defaultItems, onItemsChange, onMove, onMoveError, onRename, activeId, defaultActiveId, onActiveChange, defaultExpandedIds, }: UseAISidebarOptions): {
-    flat: FlatResource[];
-    selectedId: string | null;
-    expandedIds: Set<string>;
-    focusedId: string | null;
-    setFocusedId: import('react').Dispatch<import('react').SetStateAction<string | null>>;
-    draggingId: string | null;
-    dropTarget: DropTarget | null;
-    hoveredId: string | null;
-    hoverLayoutId: string;
-    handleRowHover: (id: string, hovered: boolean) => void;
-    clearHover: () => void;
-    menuOpenId: string | null;
-    renamingId: string | null;
-    setRenamingId: import('react').Dispatch<import('react').SetStateAction<string | null>>;
-    announcement: string;
-    select: (id: string) => void;
-    toggle: (id: string) => void;
-    handleKeyDown: (event: KeyboardEvent<HTMLDivElement>, row: FlatResource) => void;
-    handleRootDragOver: (event: DragEvent<HTMLDivElement>) => void;
-    handleDrop: (event: DragEvent<HTMLDivElement>) => void;
-    handleRowDragStart: (event: DragEvent<HTMLDivElement>, id: string) => void;
-    handleRowDragEnd: () => void;
-    handleRowDragOver: (event: DragEvent<HTMLDivElement>, targetRow: FlatResource) => void;
-    commitRename: (row: FlatResource, label: string) => void;
-    handleMenuOpenChange: (row: FlatResource, open: boolean) => void;
-    setRowRef: (id: string, node: HTMLDivElement | null) => void;
-};
+import { AISidebarController, UseAISidebarOptions } from './type.ts';
+export type { UseAISidebarOptions };
+/**
+ * The AI sidebar's headless controller — every behaviour the block
+ * performs, callable from outside it: select, expand/collapse (one row,
+ * every row, or just the ancestors of one), move focus, rename, open a
+ * row's action menu, reorder.
+ *
+ * `items`, `activeId` and `expandedIds` are each controlled when passed
+ * and hook-owned via their `default*` twin otherwise. Reorder and rename
+ * are applied to the data optimistically either way and rolled back if
+ * `onMove`/`onRename` rejects, so a consumer never reduces the tree
+ * itself — `moveResource` and `renameResource` are exported for the ones
+ * who keep their data elsewhere.
+ *
+ * ```tsx
+ * const sidebar = useAISidebar({ defaultItems: resources })
+ * <AISidebar controller={sidebar} />
+ * <Button onClick={sidebar.collapseAll}>Collapse all</Button>
+ * ```
+ */
+export declare function useAISidebar(options: UseAISidebarOptions): AISidebarController;

package/dist-lib/components/blocks/nav/sidebar/utils.d.ts

@@ -6,6 +6,11 @@ export declare const ROW_REVEAL: {
 export declare function canContain(item: SidebarResource): boolean;
 export declare function flattenResources(items: SidebarResource[], expanded: Set<string>, depth?: number, parentId?: string | null): FlatResource[];
 export declare function findResource(items: SidebarResource[], id: string): SidebarResource | undefined;
+/** Ids of every ancestor of `id` (nearest last); empty when absent. */
+export declare function ancestorIdsOf(items: SidebarResource[], id: string): string[];
+/** Ids of every row that can hold children and has some — the set
+ * `expandAll` opens. */
+export declare function expandableIdsOf(items: SidebarResource[]): string[];
 export declare function containsResource(item: SidebarResource, id: string): boolean;
 export declare function removeResource(items: SidebarResource[], id: string): {
     items: SidebarResource[];

package/dist-lib/components/blocks/scaffold/constants.d.ts

@@ -5,6 +5,11 @@ export declare const SCAFFOLD_INSPECTOR_WIDTH = 272;
 /** Most panels the canvas holds at once — omit Actions' `onAdd` when the
  * count reaches it so the Add segment hides. */
 export declare const SCAFFOLD_PANEL_CAPACITY = 3;
+/** Narrowest a panel may render, in px. When the canvas can't grant every
+ * panel this width, the scaffold hides panels until the rest fit. */
+export declare const SCAFFOLD_PANEL_MIN_WIDTH = 320;
+/** Gap in px between side-by-side panels on the canvas (`gap-2`). */
+export declare const SCAFFOLD_CANVAS_GAP = 8;
 /** Gap in px between the drawer/actions and the viewport edges. */
 export declare const SCAFFOLD_EDGE_GUTTER = 10;
 /** Vertical room in px reserved above the canvas for the actions cluster. */

package/dist-lib/components/blocks/scaffold/scaffold-canvas.d.ts

@@ -3,5 +3,7 @@ import * as React from "react";
 /**
  * The panel row below the action cluster: 8px gutters, 8px gaps, panels
  * side by side. Key each `Scaffold.Panel` child so closes animate out.
+ * Measures its own width and hides id'd panels (oldest activation first)
+ * whenever it can't grant each one `SCAFFOLD_PANEL_MIN_WIDTH`.
  */
 export declare function ScaffoldCanvas({ className, children, ...rest }: ScaffoldCanvasProps): React.ReactElement;

package/dist-lib/components/blocks/scaffold/scaffold-panel.d.ts

@@ -7,4 +7,4 @@ import * as React from "react";
  * the two cards with a layout morph — the strip glides up and grows into the
  * primary slot while the primary card shrinks down into the strip.
  */
-export declare function ScaffoldPanel({ children, SecondaryPanel, onSwap, onCloseSecondary, name, swapLabel, sound, className, }: ScaffoldPanelProps): React.ReactElement;
+export declare function ScaffoldPanel({ id, children, SecondaryPanel, onSwap, onCloseSecondary, name, swapLabel, sound, className, }: ScaffoldPanelProps): React.ReactElement;

package/dist-lib/components/blocks/scaffold/scaffold-tab.d.ts

@@ -5,5 +5,10 @@ import * as React from "react";
  * affordance. Render one per open panel as Actions children, keyed —
  * closes animate out of the pill. Omit `onClose` on the last remaining
  * panel's tab; the canvas keeps at least one panel open.
+ *
+ * With `panelId` (matching a `Scaffold.Panel`'s `id`), the tab also fronts
+ * that panel's visibility: a hidden panel dims its tab behind an eye-off
+ * icon, and pressing the label toggles the panel — showing one past
+ * capacity hides the least-recently-activated panel in its place.
  */
-export declare function ScaffoldTab({ children, onClose, closeLabel, sound, className, ...rest }: ScaffoldTabProps): React.ReactElement;
+export declare function ScaffoldTab({ children, panelId, onClose, closeLabel, sound, className, ...rest }: ScaffoldTabProps): React.ReactElement;

package/dist-lib/components/blocks/scaffold/type.d.ts

@@ -7,6 +7,25 @@ export interface ScaffoldContextValue {
     inspectorWidth: number;
     setInspectorOpen: (open: boolean) => void;
     toggleInspector: () => void;
+    /** How many panels currently fit side by side, from the measured canvas
+     * width at `SCAFFOLD_PANEL_MIN_WIDTH` per panel (1..`SCAFFOLD_PANEL_CAPACITY`). */
+    panelCapacity: number;
+    /** Ids of id'd panels the scaffold is currently hiding — auto-hidden by
+     * capacity pressure or toggled away from a tab. */
+    hiddenPanelIds: readonly string[];
+    isPanelHidden: (id: string) => boolean;
+    /** Show/hide an id'd panel. Showing past capacity auto-hides the
+     * least-recently-activated visible panel; the last visible one never hides. */
+    togglePanelVisibility: (id: string) => void;
+    /** Id of the panel whose tab the pointer is resting on — the canvas
+     * spotlights it by fading every other id'd panel to 0.35 opacity. */
+    hoveredPanelId: string | null;
+    /** @internal Tabs report pointer enter/leave on their label. */
+    setPanelHovered: (id: string, hovered: boolean) => void;
+    /** @internal Canvas reports its ordered panel ids. */
+    registerPanelIds: (ids: readonly string[]) => void;
+    /** @internal Canvas reports its measured width. */
+    setCanvasWidth: (width: number) => void;
 }
 export interface ScaffoldRootProps extends ComponentProps<"div"> {
     /** Controlled inspector state — pair with `onInspectorOpenChange`, or
@@ -41,6 +60,11 @@ export interface ScaffoldActionsProps extends MotionSafe<Omit<ComponentProps<"di
 }
 export type TScaffoldPanelChild<T extends ScaffoldSubPanelProps = ScaffoldSubPanelProps> = ReactElement<T, React.JSXElementConstructor<T>>;
 export interface ScaffoldPanelProps {
+    /** Stable id opting the panel into responsive hiding: the canvas hides
+     * id'd panels when it can't grant each `SCAFFOLD_PANEL_MIN_WIDTH`, and a
+     * `Scaffold.Tab` with the matching `panelId` reflects and toggles it.
+     * Omitted, the panel always renders. */
+    id?: string;
     /** The panel's content, rendered in a card with a drop shadow. */
     children: ReactNode;
     /** The panel's content, rendered in a card with a drop shadow. */
@@ -64,6 +88,10 @@ export interface ScaffoldPanelProps {
 export interface ScaffoldTabProps extends MotionSafe<Omit<ComponentProps<"div">, "children">> {
     /** The tab's label. */
     children?: ReactNode;
+    /** Id of the panel this tab fronts (`Scaffold.Panel`'s `id`). The tab
+     * then shows whether the panel is hidden and pressing its label toggles
+     * visibility — showing past capacity hides another panel in its place. */
+    panelId?: string;
     /** Renders the tab's close button. The button renders only while this
      * is present — omit it to pin the tab, e.g. on the last remaining
      * panel (the canvas keeps at least one open). */

package/dist-lib/components/blocks/scaffold/use-panel-visibility.d.ts

@@ -0,0 +1,19 @@
+export interface PanelVisibility {
+    /** How many panels currently fit side by side (1..capacity cap). */
+    panelCapacity: number;
+    /** Ids of panels currently hidden (auto + user), for tabs to reflect. */
+    hiddenPanelIds: readonly string[];
+    isPanelHidden: (id: string) => boolean;
+    togglePanelVisibility: (id: string) => void;
+    /** Id of the panel whose tab is hovered — the canvas spotlights it. */
+    hoveredPanelId: string | null;
+    /** @internal Tabs report pointer enter/leave on their label. */
+    setPanelHovered: (id: string, hovered: boolean) => void;
+    /** @internal Canvas reports its ordered panel ids each render. */
+    registerPanelIds: (ids: readonly string[]) => void;
+    /** @internal Canvas reports its measured width. */
+    setCanvasWidth: (width: number) => void;
+}
+/** Owns which panels are hidden as the canvas gains and loses room.
+ * Lives in `Scaffold.Root`; Canvas and Tab reach it through context. */
+export declare function usePanelVisibility(): PanelVisibility;

package/dist-lib/components/blocks/scaffold/utils.d.ts

@@ -1,6 +1,12 @@
 import { Variants } from 'motion/react';
 import { ClassNameValue } from 'tailwind-merge';
 import { TSubPanelVariant } from './type.ts';
+/**
+ * How many panels fit on a canvas of `width` px, granting each
+ * `SCAFFOLD_PANEL_MIN_WIDTH` plus the gaps between them. Clamped to
+ * [1, SCAFFOLD_PANEL_CAPACITY]; an unmeasured canvas (`null`) fits the cap.
+ */
+export declare function getPanelCapacity(width: number | null): number;
 /** Desktop backdrop the whole scaffold sits on — a soft warm-gray wash. */
 export declare const scaffoldBackgroundClass: ClassNameValue;
 /** Card surface shared by a panel's primary area and secondary strip. */

package/dist-lib/components/composed/tree/__tests__/tree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/composed/tree/__tests__/use-tree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/composed/tree/constants.d.ts

@@ -0,0 +1,35 @@
+import { Transition, Variants } from 'motion/react';
+/** `--ease-smooth-out` as a motion/react easing tuple. */
+export declare const TREE_EASE: readonly [0.22, 1, 0.36, 1];
+/** Branch open — `--duration-fast` territory (accordion open). */
+export declare const TREE_OPEN_DURATION = 0.25;
+/** Branch close — quicker than open, per open/close asymmetry. */
+export declare const TREE_CLOSE_DURATION = 0.15;
+/** Chevron flip and label fades. */
+export declare const TREE_MICRO_DURATION = 0.15;
+/** Sidebar rail label reveal/hide when `collapsed` flips. */
+export declare const TREE_COLLAPSE_DURATION = 0.2;
+/** The collapsed rail's width in px — an icon row plus its padding. Kept in
+ * sync with the `w-11` resting class the rail falls back to before its
+ * expanded width has been measured. */
+export declare const RAIL_COLLAPSED_WIDTH = 44;
+/** Rail label text fade — starts as the width growth is finishing, so the
+ * label never reads as clipped mid-grow. */
+export declare const TREE_LABEL_REVEAL_DELAY = 0.01;
+/** A branch's children group: grows open with a soft stagger, folds shut
+ * faster. Height rides layout ("auto"), paint fades. */
+export declare const TREE_BRANCH_VARIANTS: Variants;
+/** Branch close — a plain target, NOT the "closed" variant label: a
+ * labeled exit orchestrates every variant child and AnimatePresence then
+ * waits on the whole subtree before unmounting. */
+export declare const TREE_BRANCH_EXIT: {
+    height: number;
+    opacity: number;
+    transition: {
+        duration: number;
+        ease: readonly [0.22, 1, 0.36, 1];
+    };
+};
+/** One row inside an opening branch — a short blurred rise. */
+export declare const TREE_ROW_VARIANTS: Variants;
+export declare const TREE_MICRO_TRANSITION: Transition;

package/dist-lib/components/composed/tree/index.d.ts

@@ -0,0 +1,4 @@
+export { Tree } from './tree';
+export { useTree } from './use-tree';
+export { moveNode, renameNode } from './utils';
+export type { TreeController, TreeControllerProps, TreeDataProps, TreeDropPosition, TreeNode, TreeProps, TreeVariant, UseTreeOptions, } from './type';

package/dist-lib/components/composed/tree/tree-context.d.ts

@@ -0,0 +1,4 @@
+import { TreeContextValue } from './type';
+import * as React from "react";
+export declare const TreeContext: React.Context<TreeContextValue | null>;
+export declare function useTreeContext(): TreeContextValue;

package/dist-lib/components/composed/tree/tree-node.d.ts

@@ -0,0 +1,7 @@
+import { TreeNode } from './type';
+import * as React from "react";
+export interface TreeRowProps {
+    node: TreeNode;
+    depth: number;
+}
+export declare function TreeRow({ node, depth }: TreeRowProps): React.ReactElement;

package/dist-lib/components/composed/tree/tree.d.ts

@@ -0,0 +1,19 @@
+import { TreeProps } from './type';
+import * as React from "react";
+/**
+ * A nested item tree with four shapes: `navigation` (app nav — 3-level
+ * data promotes the top level to collapsible section names), `toc`
+ * (routes on top, in-page `#` anchors at the leaves), `sidebar` (a
+ * single-level rail that collapses to icons) and `files` (a compact file
+ * explorer with rename, drag-and-drop and trailing row actions).
+ *
+ * Two ways to drive it. Data-driven like the sidebar block: pass `items`,
+ * wire `onNavigate` into your router. Or hold a `useTree` controller and
+ * pass it as `tree` — same rendering, but expand, collapse, select, rename
+ * and reorder are then callable from anywhere in your app.
+ *
+ * Branches expand with a soft height morph and row stagger; the rail's
+ * labels fold away when `collapsed` flips. Arrow keys walk visible rows,
+ * expand and collapse; F2 renames in `files`.
+ */
+export declare function Tree(props: TreeProps): React.ReactElement;

package/dist-lib/components/composed/tree/type.d.ts

@@ -0,0 +1,192 @@
+import type * as React from "react";
+/** One node in the tree. Nesting depth carries meaning per variant — see
+ * `TreeProps["variant"]`. */
+export interface TreeNode {
+    id: string;
+    label: string;
+    /** Leading icon. Required in practice for `sidebar` — it is all that
+     * remains of a row while the rail is collapsed. */
+    icon?: React.ReactNode;
+    /** Renders an anchor. Without one the row is a button; `toc` leaves
+     * default to `#{id}` so they scroll to the matching heading. */
+    href?: string;
+    target?: "_blank" | "_self" | "_parent" | "_top";
+    disabled?: boolean;
+    /** Start expanded. Ancestors of `activeId` expand regardless. */
+    defaultOpen?: boolean;
+    /** Trailing hint — a count, a "New" pill. */
+    badge?: React.ReactNode;
+    /** Fires on selection, before the tree-level `onNavigate`. */
+    onSelect?: () => void;
+    children?: TreeNode[];
+}
+export type TreeVariant = "navigation" | "toc" | "sidebar" | "files";
+/** Where a dragged row lands relative to its drop target. */
+export type TreeDropPosition = "before" | "after" | "inside";
+interface TreeBaseProps {
+    items: TreeNode[];
+    /** Never set on the data form — `tree` selects the controller form. */
+    tree?: never;
+    /** `id` of the current entry — matches any depth. Its ancestors expand. */
+    activeId?: string;
+    /** Fires for every selection (rows and leaves alike), after the row's
+     * anchor default — wire your router's navigate here. */
+    onNavigate?: (node: TreeNode) => void;
+    /** Expand/collapse cues. Silent until `bindSounds()`. */
+    sound?: boolean;
+    ariaLabel?: string;
+    className?: string;
+}
+interface TreeReadonlyProps {
+    collapsed?: never;
+    onMove?: never;
+    onRename?: never;
+    renderTrailing?: never;
+}
+/** Drive the tree from a `useTree` controller instead of raw props. The
+ * controller carries the variant, the data and every handler; only the
+ * presentational props stay here. */
+export interface TreeControllerProps {
+    tree: TreeController;
+    items?: never;
+    ariaLabel?: string;
+    className?: string;
+    /** Row actions revealed on hover/focus (`files` only — ignored by the
+     * other variants, which the controller form cannot type-gate). */
+    renderTrailing?: (node: TreeNode) => React.ReactNode;
+}
+/** Either form: raw props, or a `useTree` controller via `tree`. */
+export type TreeProps = TreeDataProps | TreeControllerProps;
+/** The four shapes a Tree takes. Editing props only exist on `files`;
+ * `collapsed` only on `sidebar` — the union is the contract. */
+export type TreeDataProps = TreeBaseProps & (({
+    /** Nested app navigation. With 3 levels of nodes the top level
+     * becomes collapsible section names (styled as headings, not
+     * links); with 2 it renders plain link rows. */
+    variant: "navigation";
+} & TreeReadonlyProps) | ({
+    /** Table of contents: top-level nodes are routes, leaf nodes are
+     * in-page anchors (`#{id}` unless the node carries an `href`). */
+    variant: "toc";
+} & TreeReadonlyProps) | ({
+    /** Single-level icon rail. `collapsed` shrinks rows to their
+     * leading icon; nested children are ignored. */
+    variant: "sidebar";
+    collapsed?: boolean;
+} & Omit<TreeReadonlyProps, "collapsed">) | {
+    /** File explorer: only leaves navigate, folders toggle. Compact
+     * spacing; rename, drag-and-drop and trailing actions enabled. */
+    variant: "files";
+    /** Enables drag-and-drop. Reorder `items` yourself: `parentId`
+     * `null` means the root list, `index` is the slot among the new
+     * siblings (computed on the list without the dragged node). */
+    onMove?: (id: string, parentId: string | null, index: number) => void;
+    /** Enables inline rename (double-click or F2). */
+    onRename?: (id: string, label: string) => void;
+    /** Row actions revealed on hover/focus — a menu, a delete icon. */
+    renderTrailing?: (node: TreeNode) => React.ReactNode;
+    collapsed?: never;
+});
+/** Options for `useTree`. Each of `items`, `activeId` and `collapsed` is
+ * controlled when passed and hook-owned when its `default*` twin is used
+ * instead. */
+export interface UseTreeOptions {
+    /** Which shape the tree takes — gates rename/reorder (`files`) and the
+     * collapsible rail (`sidebar`). */
+    variant: TreeVariant;
+    /** Controlled data. With it, `rename`/`move` only report the edit unless
+     * you also pass `onItemsChange`. */
+    items?: TreeNode[];
+    /** Hook-owned data — `rename` and `move` apply the edit themselves. */
+    defaultItems?: TreeNode[];
+    /** Next tree after a `rename`/`move`. Also enables self-applying edits
+     * on top of controlled `items`. */
+    onItemsChange?: (items: TreeNode[]) => void;
+    /** Controlled selection. Ancestors of the active node expand. */
+    activeId?: string;
+    defaultActiveId?: string;
+    /** Fires for every selection (rows and leaves alike), after the node's
+     * own `onSelect` — wire your router's navigate here. */
+    onNavigate?: (node: TreeNode) => void;
+    /** Start with these ids expanded instead of the `defaultOpen` set. */
+    defaultExpandedIds?: Iterable<string>;
+    onExpandedChange?: (ids: string[]) => void;
+    /** Controlled rail fold (`sidebar` only). */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Enables rename (`files`). Not needed when the hook owns the data. */
+    onRename?: (id: string, label: string) => void;
+    /** Enables drag-and-drop (`files`). `parentId` `null` means the root
+     * list, `index` is the slot among the new siblings (computed on the list
+     * without the moved node). Not needed when the hook owns the data. */
+    onMove?: (id: string, parentId: string | null, index: number) => void;
+    /** Expand/collapse cues. Silent until `bindSounds()`. */
+    sound?: boolean;
+}
+/** Everything the tree can do, callable from outside the component.
+ * Returned by `useTree` and accepted by `<Tree tree={…} />`. */
+export interface TreeController {
+    variant: TreeVariant;
+    items: TreeNode[];
+    /** `navigation` with 3 levels of nodes — depth 0 renders as sections. */
+    sectioned: boolean;
+    /** Ids of the section headings, empty unless `sectioned`. Pass one to
+     * `expand`/`collapse`/`toggleExpanded` to work a whole section. */
+    sectionIds: string[];
+    sound: boolean;
+    getNode: (id: string) => TreeNode | null;
+    expandedIds: ReadonlySet<string>;
+    isExpanded: (id: string) => boolean;
+    expand: (id: string) => void;
+    collapse: (id: string) => void;
+    toggleExpanded: (id: string) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    /** Open every ancestor of `id`, leaving the rest of the tree alone. */
+    reveal: (id: string) => void;
+    /** Rail folded to icons — always `false` outside `sidebar`. */
+    collapsed: boolean;
+    setCollapsed: (collapsed: boolean) => void;
+    toggleCollapsed: () => void;
+    activeId?: string;
+    /** Select a node: runs its `onSelect`, then `onNavigate`. Inert on
+     * disabled and unknown nodes. */
+    select: (id: string) => void;
+    /** Whether rename is wired up at all (`files` + a handler or owned data). */
+    canRename: boolean;
+    /** Rename target id, `null` while idle. */
+    renamingId: string | null;
+    startRename: (id: string) => void;
+    cancelRename: () => void;
+    /** Commit a rename and leave rename mode. Blank or unchanged labels are
+     * dropped. */
+    rename: (id: string, label: string) => void;
+    /** Whether reorder is wired up at all. */
+    canMove: boolean;
+    move: (id: string, parentId: string | null, index: number) => void;
+    dnd: TreeDndContextValue;
+}
+/** @internal What a row needs from the root, threaded through context so
+ * the recursive rows stay prop-light. */
+export interface TreeContextValue {
+    tree: TreeController;
+    renderTrailing?: (node: TreeNode) => React.ReactNode;
+}
+/** @internal Drag state shared by every row (all `null`/no-op outside
+ * `files`). */
+export interface TreeDndContextValue {
+    enabled: boolean;
+    draggedId: string | null;
+    /** Row the pointer is over and where the drop would land. */
+    dropTarget: {
+        id: string;
+        position: TreeDropPosition;
+    } | null;
+    onRowDragStart: (event: React.DragEvent, id: string) => void;
+    onRowDragOver: (event: React.DragEvent, node: TreeNode) => void;
+    onRowDragLeave: (event: React.DragEvent) => void;
+    onRowDrop: (event: React.DragEvent, node: TreeNode) => void;
+    onRowDragEnd: () => void;
+}
+export {};

package/dist-lib/components/composed/tree/use-tree-dnd.d.ts

@@ -0,0 +1,7 @@
+import { TreeDndContextValue, TreeNode, UseTreeOptions } from './type';
+/** Owns drag state for the `files` variant: which row is in flight, which
+ * row the pointer rests on and where the drop would land. Everything is
+ * component state — `dataTransfer` is set for interop but never read, so
+ * the flow also works where the store is unavailable (tests, some
+ * webviews). Without `onMove` every handler is inert. */
+export declare function useTreeDnd(items: readonly TreeNode[], onMove: UseTreeOptions["onMove"]): TreeDndContextValue;

package/dist-lib/components/composed/tree/use-tree.d.ts

@@ -0,0 +1,20 @@
+import { TreeController, UseTreeOptions } from './type';
+/**
+ * The tree's headless controller — every behaviour the component exposes,
+ * callable from outside it: expand/collapse (a node, a section, the whole
+ * tree), fold the `sidebar` rail, select a node, rename, reorder.
+ *
+ * Each piece of state is controlled-or-uncontrolled in the usual React
+ * shape: pass `items`/`activeId`/`collapsed` to own it yourself, or
+ * `defaultItems`/`defaultActiveId`/`defaultCollapsed` to let the hook. When
+ * the hook owns `items` (or you pass `onItemsChange`), `rename` and `move`
+ * apply the edit to the data themselves — otherwise they only report it
+ * through `onRename`/`onMove` and you reduce the tree yourself.
+ *
+ * ```tsx
+ * const tree = useTree({ variant: "files", defaultItems: files })
+ * <Tree tree={tree} />
+ * <Button onClick={tree.collapseAll}>Collapse all</Button>
+ * ```
+ */
+export declare function useTree(options: UseTreeOptions): TreeController;