@exegia/corpora-ui 0.19.0 → 0.21.0

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

@@ -0,0 +1,160 @@
+import { Atom } from 'jotai';
+import { TreeConfig, TreeDropPosition, TreeDropTarget, TreeHandlers, TreeInstanceId, TreeNode, TreeSeed, TreeState, TreeVariant } from './type';
+/** What a tree reads as before `useTree` publishes its options. */
+export declare const DEFAULT_TREE_CONFIG: TreeConfig;
+/**
+ * A string-keyed atom family.
+ *
+ * `jotai/utils`' `atomFamily` is deprecated for Jotai v3, and we need only
+ * the string-keyed case with a `remove` — so this stays in-house rather than
+ * adding `jotai-family` as a second Jotai package to keep version-aligned.
+ * Dropping a key lets the store's WeakMap release that instance's state.
+ */
+type Family<AtomType> = ((id: TreeInstanceId) => AtomType) & {
+    remove: (id: TreeInstanceId) => void;
+};
+/** @internal */
+export declare const treeConfigAtom: Family<import('jotai').PrimitiveAtom<TreeConfig> & {
+    init: TreeConfig;
+}>;
+/** @internal Refreshed every commit; nothing subscribes, so it is free. */
+export declare const treeHandlersAtom: Family<import('jotai').PrimitiveAtom<TreeHandlers> & {
+    init: TreeHandlers;
+}>;
+/** The tree's current data — hook-owned, or the projection of a controlled
+ * `items` prop. */
+export declare const treeItemsAtom: Family<import('jotai').PrimitiveAtom<TreeNode[]> & {
+    init: TreeNode[];
+}>;
+export declare const treeActiveIdAtom: Family<import('jotai').PrimitiveAtom<string | undefined> & {
+    init: string | undefined;
+}>;
+export declare const treeExpandedIdsAtom: Family<import('jotai').PrimitiveAtom<ReadonlySet<string>> & {
+    init: ReadonlySet<string>;
+}>;
+/** Raw rail fold. Read `treeCollapsedAtom` for the variant-masked value. */
+export declare const treeRailCollapsedAtom: Family<import('jotai').PrimitiveAtom<boolean> & {
+    init: boolean;
+}>;
+export declare const treeRenamingIdAtom: Family<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+export declare const treeDraggedIdAtom: Family<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+export declare const treeDropTargetAtom: Family<import('jotai').PrimitiveAtom<TreeDropTarget | null> & {
+    init: TreeDropTarget | null;
+}>;
+/** @internal The only items atom `useTree` may subscribe to: empty while a
+ * controlled `items` prop owns the data, so the projection write never feeds
+ * back into the render that produced it. An inline `items={[…]}` array is a
+ * new reference every render, and a subscribed round-trip would loop. */
+export declare const treeOwnedItemsAtom: Family<Atom<TreeNode[]>>;
+/** Rail folded to icons — always `false` outside `sidebar`. */
+export declare const treeCollapsedAtom: Family<Atom<boolean>>;
+export declare const treeSectionedAtom: Family<Atom<boolean>>;
+export declare const treeSectionIdsAtom: Family<Atom<string[]>>;
+export declare const treeCanRenameAtom: Family<Atom<boolean>>;
+export declare const treeCanMoveAtom: Family<Atom<boolean>>;
+export declare const treeVariantAtom: Family<Atom<TreeVariant>>;
+export declare const treeSoundAtom: Family<Atom<boolean>>;
+/** Whether this one node's branch is open. */
+export declare const treeNodeExpandedAtom: (id: TreeInstanceId, nodeId: string) => Atom<boolean>;
+/** Whether this one node is the current entry. */
+export declare const treeNodeActiveAtom: (id: TreeInstanceId, nodeId: string) => Atom<boolean>;
+/** Whether this one node is in rename mode. */
+export declare const treeNodeRenamingAtom: (id: TreeInstanceId, nodeId: string) => Atom<boolean>;
+/** Whether this one node is the row in flight. */
+export declare const treeNodeDraggingAtom: (id: TreeInstanceId, nodeId: string) => Atom<boolean>;
+/** Where a drop on this one node would land, `null` when it is not hovered. */
+export declare const treeNodeDropAtom: (id: TreeInstanceId, nodeId: string) => Atom<TreeDropPosition | null>;
+/** The whole state of one tree. Components reading a single field should
+ * subscribe to that field's atom instead — this one changes on every edit. */
+export declare const treeStateAtom: Family<Atom<TreeState>>;
+export declare const expandTreeNodeAtom: Family<import('jotai').WritableAtom<null, [nodeId: string], void> & {
+    init: null;
+}>;
+export declare const collapseTreeNodeAtom: Family<import('jotai').WritableAtom<null, [nodeId: string], void> & {
+    init: null;
+}>;
+export declare const toggleTreeNodeAtom: Family<import('jotai').WritableAtom<null, [nodeId: string], void> & {
+    init: null;
+}>;
+export declare const expandAllTreeNodesAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+export declare const collapseAllTreeNodesAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Open every ancestor of `nodeId` without touching the rest of the tree. */
+export declare const revealTreeNodeAtom: Family<import('jotai').WritableAtom<null, [nodeId: string], void> & {
+    init: null;
+}>;
+/** @internal The same, silent. `useTree` runs it whenever the active id
+ * changes so a nested entry is never folded away — the hook has never
+ * reported that implicit reveal through `onExpandedChange`. */
+export declare const revealTreeAncestorsAtom: Family<import('jotai').WritableAtom<null, [nodeId: string], void> & {
+    init: null;
+}>;
+export declare const setTreeCollapsedAtom: Family<import('jotai').WritableAtom<null, [collapsed: boolean], void> & {
+    init: null;
+}>;
+export declare const toggleTreeCollapsedAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Runs the node's own `onSelect` first, then `onNavigate` — the order a row
+ * press follows. Disabled and unknown nodes are inert. */
+export declare const selectTreeNodeAtom: Family<import('jotai').WritableAtom<null, [nodeId: string], void> & {
+    init: null;
+}>;
+export declare const startTreeRenameAtom: Family<import('jotai').WritableAtom<null, [nodeId: string], void> & {
+    init: null;
+}>;
+export declare const cancelTreeRenameAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Commit a rename and leave rename mode. Blank or unchanged labels are
+ * dropped. */
+export declare const renameTreeNodeAtom: Family<import('jotai').WritableAtom<null, [nodeId: string, label: string], void> & {
+    init: null;
+}>;
+export declare const moveTreeNodeAtom: Family<import('jotai').WritableAtom<null, [nodeId: string, parentId: string | null, index: number], void> & {
+    init: null;
+}>;
+/** Replace the data. Reports through `onItemsChange`; writes the atom only
+ * when no controlled `items` prop owns it. */
+export declare const setTreeItemsAtom: Family<import('jotai').WritableAtom<null, [items: TreeNode[]], void> & {
+    init: null;
+}>;
+export declare const endTreeDragAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** @internal Publish the latest options; seed the instance once. */
+export declare const mountTreeAtom: Family<import('jotai').WritableAtom<null, [config: TreeConfig, seed: TreeSeed], void> & {
+    init: null;
+}>;
+/** @internal */
+export declare const setTreeHandlersAtom: Family<import('jotai').WritableAtom<null, [handlers: TreeHandlers], void> & {
+    init: null;
+}>;
+/** @internal One-way projections of controlled props — no callbacks fire. */
+export declare const projectTreeItemsAtom: Family<import('jotai').WritableAtom<null, [items: TreeNode[]], void> & {
+    init: null;
+}>;
+/** @internal */
+export declare const projectTreeActiveIdAtom: Family<import('jotai').WritableAtom<null, [activeId: string | undefined], void> & {
+    init: null;
+}>;
+/** @internal */
+export declare const projectTreeCollapsedAtom: Family<import('jotai').WritableAtom<null, [collapsed: boolean], void> & {
+    init: null;
+}>;
+/** Back to the values the instance mounted with. */
+export declare const resetTreeAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Drop every atom for `id`. `useTree` calls this on unmount for trees it
+ * keyed itself; an explicit `treeId` outlives its component, so a rail's fold
+ * survives a route change. */
+export declare function removeTreeInstance(id: TreeInstanceId): void;
+export {};

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,12 @@
+import { TreeNode } from './type';
+import * as React from "react";
+export interface TreeRowProps {
+    node: TreeNode;
+    depth: number;
+}
+declare function TreeRowImpl({ node, depth }: TreeRowProps): React.ReactElement;
+/** Rows are memoized so a re-render of the root — a rail measurement, a new
+ * `renderTrailing` — does not walk the whole tree. Each row's own state
+ * reaches it through its atoms instead. */
+export declare const TreeRow: React.MemoExoticComponent<typeof TreeRowImpl>;
+export {};

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,290 @@
+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;
+    /** Route metadata for the consumer's `onNavigate` — every row renders as
+     * a button, so this is never turned into an anchor element. Read it (with
+     * `target`) off the node your handler receives. One native behaviour is
+     * kept: `toc` rows below the route level jump to `#{id}` after select
+     * (a `#hash` href overrides the id; a non-hash href disables the jump). */
+    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";
+/** Key for one tree’s state in the store. Any stable string; `useTree`
+ * generates one when you don't pass it. */
+export type TreeInstanceId = string;
+/** Row a drag hovers, and where the drop would land. */
+export interface TreeDropTarget {
+    id: string;
+    position: TreeDropPosition;
+}
+interface TreeBaseProps {
+    items: TreeNode[];
+    /** Key this tree's state under a name your app can address —
+     * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+     * anywhere under `ExegiaProvider`. Without one the tree generates a key
+     * and its state is dropped when it unmounts. */
+    treeId?: TreeInstanceId;
+    /** 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 node's
+     * own `onSelect`. Rows are buttons, so this is the routing path — wire
+     * your router's navigate here. `toc` rows below the route level still jump
+     * to `#{id}` natively, after this fires. */
+    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
+     * rows); with 2 it renders plain selectable rows. */
+    variant: "navigation";
+} & TreeReadonlyProps) | ({
+    /** Table of contents: top-level nodes are routes (handled in
+     * `onNavigate`); rows below jump to `#{id}` after select, like an
+     * anchor would. Parents select on the row and expand from a
+     * separate overlay chevron. */
+    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 {
+    /** Key this tree's state under a name your app can address —
+     * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+     * anywhere under `ExegiaProvider`. Without one the hook generates a key
+     * and the state is dropped when the component unmounts. */
+    treeId?: TreeInstanceId;
+    /** 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 {
+    /** The key this tree's state is stored under. */
+    treeId: TreeInstanceId;
+    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;
+    /** Back to the values the tree mounted with. */
+    reset: () => void;
+    dnd: TreeDndContextValue;
+}
+/** @internal What a row needs from the root, threaded through context so
+ * the recursive rows stay prop-light.
+ *
+ * Deliberately free of tree state. Rows read state from per-node atoms, so
+ * this value keeps its identity for the life of the tree and expanding one
+ * branch no longer re-renders every row through context. */
+export interface TreeContextValue {
+    treeId: TreeInstanceId;
+    renderTrailing?: (node: TreeNode) => React.ReactNode;
+    dnd: TreeDndHandlers;
+}
+/** @internal The drag event handlers, stable for the life of the tree —
+ * they read drag state out of the store instead of closing over it, so
+ * handing them to every row costs no re-renders. */
+export interface TreeDndHandlers {
+    enabled: boolean;
+    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;
+}
+/** @internal Handlers plus live drag state — what `TreeController.dnd`
+ * exposes (all `null`/no-op outside `files`). */
+export interface TreeDndContextValue extends TreeDndHandlers {
+    draggedId: string | null;
+    /** Row the pointer is over and where the drop would land. */
+    dropTarget: TreeDropTarget | null;
+}
+/** Everything observable about one tree, for consumers reading it by id. */
+export interface TreeState {
+    variant: TreeVariant;
+    items: TreeNode[];
+    activeId?: string;
+    expandedIds: ReadonlySet<string>;
+    collapsed: boolean;
+    renamingId: string | null;
+    sectioned: boolean;
+    sectionIds: string[];
+    canRename: boolean;
+    canMove: boolean;
+    draggedId: string | null;
+    dropTarget: TreeDropTarget | null;
+}
+/** Everything doable to one tree from outside its component. */
+export interface TreeActions {
+    expand: (id: string) => void;
+    collapse: (id: string) => void;
+    toggleExpanded: (id: string) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    reveal: (id: string) => void;
+    setCollapsed: (collapsed: boolean) => void;
+    toggleCollapsed: () => void;
+    select: (id: string) => void;
+    startRename: (id: string) => void;
+    cancelRename: () => void;
+    rename: (id: string, label: string) => void;
+    move: (id: string, parentId: string | null, index: number) => void;
+    setItems: (items: TreeNode[]) => void;
+    reset: () => void;
+}
+/** @internal Projection of `useTree`'s options — primitives only, so the
+ * store write runs once per real change instead of once per render. */
+export interface TreeConfig {
+    variant: TreeVariant;
+    sound: boolean;
+    controlsItems: boolean;
+    controlsActiveId: boolean;
+    controlsCollapsed: boolean;
+    managesItems: boolean;
+    hasRenameHandler: boolean;
+    hasMoveHandler: boolean;
+}
+/** @internal Latest option callbacks. Only write atoms read this, so it
+ * can be refreshed every commit without re-rendering anything. */
+export interface TreeHandlers {
+    onNavigate?: (node: TreeNode) => void;
+    onItemsChange?: (items: TreeNode[]) => void;
+    onExpandedChange?: (ids: string[]) => void;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    onRename?: (id: string, label: string) => void;
+    onMove?: (id: string, parentId: string | null, index: number) => void;
+}
+/** @internal What an instance starts from, replayed by `resetTreeAtom`. */
+export interface TreeSeed {
+    items: TreeNode[];
+    activeId?: string;
+    collapsed: boolean;
+    expandedIds?: string[];
+}
+export {};

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

@@ -0,0 +1,18 @@
+import { TreeDndContextValue, TreeDndHandlers, TreeInstanceId } from './type';
+/**
+ * The drag handlers for the `files` variant, stable for the life of the tree.
+ *
+ * Nothing here subscribes to drag state: items, the dragged id and the drop
+ * target are read out of the store when a handler runs. That is what lets
+ * every row share one handler object without re-rendering when a drag moves —
+ * and it keeps `useTree` from subscribing to data it also projects from
+ * props, which would loop on an inline `items` array.
+ *
+ * Inert unless the tree `canMove`. `dataTransfer` is set for interop but
+ * never read, so the flow also works where the store is unavailable (tests,
+ * some webviews).
+ */
+export declare function useTreeDndHandlers(treeId: TreeInstanceId): TreeDndHandlers;
+/** The handlers plus live drag state, for `TreeController.dnd`. Rows take the
+ * handlers alone and read the state per node instead. */
+export declare function useTreeDnd(treeId: TreeInstanceId): TreeDndContextValue;

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

@@ -0,0 +1,25 @@
+import { TreeActions, TreeInstanceId, TreeState } from './type';
+/**
+ * Read the tree registered under `treeId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { collapsed, activeId } = useTreeState("app-nav")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on any
+ * change. A component that reads one field should subscribe to that field's
+ * atom instead: `useAtomValue(treeCollapsedAtom("app-nav"))`.
+ */
+export declare function useTreeState(treeId: TreeInstanceId): TreeState;
+/**
+ * Drive the tree registered under `treeId` from anywhere. Writes only — the
+ * caller never re-renders when the tree changes, so this is what a command
+ * palette, a keyboard shortcut or a route guard should reach for.
+ *
+ * ```tsx
+ * const nav = useTreeActions("app-nav")
+ * <Button onClick={nav.collapseAll}>Collapse all</Button>
+ * ```
+ */
+export declare function useTreeActions(treeId: TreeInstanceId): TreeActions;

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

@@ -0,0 +1,24 @@
+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>
+ * ```
+ *
+ * State lives in Jotai atoms keyed by `treeId`, so anything under
+ * `ExegiaProvider` can drive this tree without the controller — name it and
+ * reach for `useTreeState(treeId)` / `useTreeActions(treeId)` elsewhere.
+ */
+export declare function useTree(options: UseTreeOptions): TreeController;

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

@@ -0,0 +1,28 @@
+import { TreeNode } from './type';
+/** Depth-0 nodes read as sections only when the data actually nests three
+ * levels — a two-level tree keeps its top level as plain link rows. */
+export declare function hasThreeLevels(items: readonly TreeNode[]): boolean;
+/** Ids of every ancestor of `id` (nearest last); empty when absent. */
+export declare function ancestorIdsOf(items: readonly TreeNode[], id: string): string[];
+/** Ids that start expanded: `defaultOpen` nodes plus every ancestor of the
+ * active entry, so the current location is never folded away. */
+export declare function initialExpandedIds(items: readonly TreeNode[], activeId?: string): Set<string>;
+/** Ids of every node that can hold children — the set `expandAll` opens.
+ * In `files` an empty `children: []` still counts (it is a folder). */
+export declare function expandableIdsOf(items: readonly TreeNode[], filesVariant?: boolean): string[];
+/** Immutably relabel `id`. Returns the same array reference when absent. */
+export declare function renameNode(items: readonly TreeNode[], id: string, label: string): TreeNode[];
+/** Whether `candidateId` is `id` itself or nests anywhere under it — the
+ * guard that keeps a folder from being dropped into its own subtree. */
+export declare function containsNode(items: readonly TreeNode[], id: string, candidateId: string): boolean;
+export declare function findNode(items: readonly TreeNode[], id: string): TreeNode | null;
+/** Parent id (`null` at root) and index of `id` among its siblings. */
+export declare function locateNode(items: readonly TreeNode[], id: string): {
+    parentId: string | null;
+    index: number;
+} | null;
+/** Immutably lift `id` out of the tree and reinsert it under `parentId`
+ * (`null` = root) at `index` — the standard `onMove` reducer, exported so
+ * consumers don't each rebuild it. `index` addresses the sibling list
+ * *after* the node has been lifted out. */
+export declare function moveNode(items: readonly TreeNode[], id: string, parentId: string | null, index: number): TreeNode[];

package/dist-lib/components/composed/user-avatar.d.ts

@@ -1,30 +1,7 @@
-import { AvatarPrimitive } from '../ui/avatar';
-import * as React from "react";
-export interface UserAvatarProps extends Omit<AvatarPrimitive.Root.Props, "children"> {
-    /** Image URL. Without one the initials show immediately — no skeleton. */
-    src?: string;
-    /** Drives the initials, and the alt text unless `alt` overrides it. */
-    name?: string;
-    /** Overrides the initials derived from `name`. */
-    initials?: string;
-    /**
-     * Alt text for the image. Pass "" when adjacent text already names the
-     * person — the image is then decorative.
-     */
-    alt?: string;
-    /**
-     * Force the skeleton, for when the identity itself is still being fetched.
-     * Omitted, it follows the image: a passed `src` skeletons until it resolves.
-     */
-    loading?: boolean;
-}
-/** "Jenny Hamilton" → "JH", "luna" → "L". */
-export declare function initialsFrom(name: string): string;
 /**
- * Identity avatar: an image when one is given, initials otherwise.
- *
- * A passed `src` is assumed to be remote, so the slot holds a skeleton until
- * the image resolves rather than flashing initials that are about to be
- * replaced. A failed load settles on the initials.
+ * Back-compat path. The avatar moved to `components/user-avatar/` (split
+ * into component / atoms / hooks); this module re-exports it so existing
+ * imports keep resolving to the one implementation. Prefer the new path.
  */
-export declare function UserAvatar({ src, name, initials, alt, loading: loadingProp, className, ...props }: UserAvatarProps): React.ReactElement;
+export { UserAvatar, initialsFrom, useUserAvatar, useUserAvatarActions, useUserAvatarState, } from '../user-avatar';
+export type { UserAvatarProps, UserPresence } from '../user-avatar';

package/dist-lib/components/user-avatar/__tests__/user-avatar.test.d.ts

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

package/dist-lib/components/user-avatar/audio-wave.d.ts

@@ -0,0 +1,2 @@
+import { IAudioWaveProps } from './type';
+export declare function AudioWave({ className, volume: _volume, children }: IAudioWaveProps): import("react").JSX.Element;

package/dist-lib/components/user-avatar/component.d.ts

@@ -0,0 +1,3 @@
+import { UserAvatarProps } from './type';
+import * as React from "react";
+export declare function UserAvatar({ src, name, initials, alt, loading: loadingProp, presence: presenceProp, bezel, avatarId, className, style, ...props }: UserAvatarProps): React.ReactElement;

package/dist-lib/components/user-avatar/fallback.d.ts

@@ -0,0 +1,5 @@
+export declare function Fallback({ name, initials, loading, }: {
+    name?: string;
+    initials?: string;
+    loading?: boolean;
+}): import("react").JSX.Element;