@exegia/corpora-ui 0.18.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

@@ -2,6 +2,14 @@
 export declare const SCAFFOLD_SIDEBAR_WIDTH = 64;
 /** Inspector drawer width in px. */
 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/index.d.ts

@@ -7,12 +7,13 @@ import { ScaffoldMain } from './scaffold-main';
 import { ScaffoldPanel } from './scaffold-panel';
 import { ScaffoldRoot } from './scaffold-root';
 import { ScaffoldSidebar } from './scaffold-sidebar';
+import { ScaffoldTab } from './scaffold-tab';
 import { ScaffoldSubPanel } from './scaffold-sub-panel.tsx';
 export { useScaffoldContext } from './scaffold-context';
 export { useScaffold } from './use-scaffold';
 export type * from './type';
 export * from './constants';
-export { PanelCloseButton, PanelMenuButton, ScaffoldActions, ScaffoldCanvas, ScaffoldInspector, ScaffoldMain, ScaffoldPanel, ScaffoldRoot, ScaffoldSidebar, };
+export { PanelCloseButton, PanelMenuButton, ScaffoldActions, ScaffoldCanvas, ScaffoldInspector, ScaffoldMain, ScaffoldPanel, ScaffoldRoot, ScaffoldSidebar, ScaffoldTab, };
 export declare const Scaffold: {
     Root: typeof ScaffoldRoot;
     Sidebar: typeof ScaffoldSidebar;
@@ -20,6 +21,7 @@ export declare const Scaffold: {
     Actions: typeof ScaffoldActions;
     Canvas: typeof ScaffoldCanvas;
     Panel: typeof ScaffoldPanel;
+    Tab: typeof ScaffoldTab;
     Inspector: typeof ScaffoldInspector;
     SubPanel: typeof ScaffoldSubPanel;
 };

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

@@ -1,7 +1,8 @@
 import { PanelMenuButtonProps } from './type';
 import * as React from "react";
 /**
- * Floating swap affordance centered on the seam between a panel's primary
- * surface and its secondary strip.
+ * Floating menu affordance centered on the seam between a panel's primary
+ * surface and its secondary strip: a compact ⋯ toggle that morphs into the
+ * Expand | Swap (| Close) actions.
  */
-export declare function PanelMenuButton({ onClick, onExpand, secondaryExpanded, label, sound, className, }: PanelMenuButtonProps): React.ReactElement;
+export declare function PanelMenuButton({ onClick, onExpand, onCloseSecondary, secondaryExpanded, swapped, label, sound, className, }: PanelMenuButtonProps): React.ReactElement;

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

@@ -2,8 +2,9 @@ import { ScaffoldActionsProps } from './type';
 import * as React from "react";
 /**
  * The floating pill cluster in the main region's top-right corner — the
- * design's "Panel Context Menu": an Add segment plus an overflow segment
- * whose badge counts the non-visible panels. Slides left in step with the
- * inspector opening.
+ * design's "Panel Context Menu": one tab per open panel (`Scaffold.Tab`
+ * children) plus an Add segment. Add renders only while `onAdd` is
+ * present — omit it once the canvas holds `SCAFFOLD_PANEL_CAPACITY`
+ * panels. Slides left in step with the inspector opening.
  */
-export declare function ScaffoldActions({ onAdd, addLabel, addIcon, overflowCount, onBrowse, browseLabel, sound, className, children, ...rest }: ScaffoldActionsProps): React.ReactElement;
+export declare function ScaffoldActions({ onAdd, addLabel, addIcon, sound, className, children, ...rest }: ScaffoldActionsProps): React.ReactElement;

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, onClose, onSwap, name, closeLabel, 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

@@ -0,0 +1,14 @@
+import { ScaffoldTabProps } from './type';
+import * as React from "react";
+/**
+ * A panel's tab inside the action cluster: its label plus a close
+ * 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, 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
@@ -25,58 +44,63 @@ export type ScaffoldCanvasProps = ComponentProps<"div">;
  * on `motion.*` elements — strip them from pass-through HTML props. */
 type MotionSafe<T> = Omit<T, "onDrag" | "onDragStart" | "onDragEnd" | "onAnimationStart" | "onAnimationEnd" | "onAnimationIteration">;
 export interface ScaffoldActionsProps extends MotionSafe<Omit<ComponentProps<"div">, "children">> {
-    /** Called when the Add segment is pressed. */
+    /** Called when the Add segment is pressed. The segment renders only
+     * while this is present — omit it to hide Add, e.g. once the canvas
+     * holds `SCAFFOLD_PANEL_CAPACITY` panels. */
     onAdd?: () => void;
     /** Label of the Add segment. */
     addLabel?: ReactNode;
     /** Replaces the default add icon. */
     addIcon?: ReactNode;
-    /** Number of non-visible panels tucked into the overflow dropdown —
-     * the badge on the browse segment. The segment renders when this or
-     * `onBrowse` is present; the badge only when > 0. Per the design
-     * comments the dropdown menu itself is a later iteration; for now the
-     * segment just keeps the count. */
-    overflowCount?: number;
-    /** Called when the overflow (stacked-panels) segment is pressed. */
-    onBrowse?: () => void;
-    /** Accessible name of the overflow segment. */
-    browseLabel?: string;
-    /** Extra segments appended after the built-in ones. */
+    /** The panel tabs (`Scaffold.Tab`, one per open panel) and any extra
+     * segments, rendered before Add. Key each tab — closes animate out. */
     children?: ReactNode;
     /** Emit interaction-sound attributes (inert until an app binds cuelume). */
     sound?: boolean;
 }
 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. */
     SecondaryPanel?: TScaffoldPanelChild;
-    /** Renders the floating close button in the panel's top-right corner. */
-    onClose?: () => void;
-    /** Renders the floating swap button over the primary/secondary gap.
-     * Only shown when `secondary` is present. Clicking it trades the two
-     * cards with a layout morph — flip the slot content here so each card
-     * carries its subject to its new home. */
+    /** Reveals the Swap action in the seam menu (needs `SecondaryPanel`).
+     * Swapping trades the two cards with a layout morph — flip the slot
+     * content here so each card carries its subject to its new home. */
     onSwap?: () => void;
-    /** Controlled swap state — while true the strip's card sits in the
-     * primary slot. Omit letting the panel toggle it on swap clicks. */
-    swapped?: boolean;
-    /** Initial swap state when uncontrolled. */
-    defaultSwapped?: boolean;
-    /** Fixed width in px; omitted, the panel flexes to share the canvas. */
-    width?: number;
+    /** Reveals the Close action in the seam menu — remove `SecondaryPanel`
+     * here; the strip and the menu leave together. */
+    onCloseSecondary?: () => void;
     /** Accessible name of the panel region. */
     name?: string;
     /** Emit interaction-sound attributes on the floating buttons. */
     sound?: boolean;
-    /** Accessible name of the close button. */
-    closeLabel?: string;
-    /** Accessible name of the swap button. */
+    /** Accessible name of the seam-menu toggle. */
     swapLabel?: string;
     /** Extra class names for the panel's root element. */
     className?: string;
 }
+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). */
+    onClose?: () => void;
+    /** Accessible name of the close button. */
+    closeLabel?: string;
+    /** Emit interaction-sound attributes on the close button. */
+    sound?: boolean;
+}
 export type TSubPanelPosition = "bottom" | "top";
 export type TSubPanelVariant = "card" | "subtle" | "inset";
 export interface ScaffoldSubPanelProps extends MotionSafe<Omit<ComponentProps<"div">, "children">> {
@@ -113,9 +137,15 @@ export interface PanelMenuButtonProps extends PanelFloatingButtonProps {
     /** Called when the Expand action is pressed — the panel trades which
      * sub-panel holds the flexible slot. */
     onExpand?: () => void;
+    /** Renders the Close action; called when it is pressed — the consumer
+     * removes the secondary strip. */
+    onCloseSecondary?: () => void;
     /** Whether the secondary strip currently holds the flexible slot —
      * flips the Expand chevron between down and up. */
     secondaryExpanded?: boolean;
+    /** Whether the panel is swapped (column-reverse). Mirrors the Expand
+     * chevron so it keeps pointing at the sub-panel that grows next. */
+    swapped?: boolean;
 }
 export interface UseScaffoldOptions {
     /** Initial inspector state. Closed by default. */

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,5 +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. */
@@ -11,5 +18,10 @@ export declare const floatingButtonClass: ClassNameValue;
 export declare const revealOnPanelHoverClass: ClassNameValue;
 /** Pill segment inside the actions cluster (Add, browse). */
 export declare const actionSegmentClass: ClassNameValue;
+/** Pill segments (seam-menu actions, tabs, Add) blur/fade in place while
+ * the track morphs around them. The exit is a fast tween, not the layout
+ * spring — the track stays overflow-visible, so popped-out segments must be
+ * gone before the shrinking pill leaves them behind as a ghost. */
+export declare const segmentVariants: Variants;
 /** Map of sub-panel variants to their corresponding side. */
 export declare const subPanelVariant: Record<TSubPanelVariant, ClassNameValue>;

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;