@exegia/corpora-ui 1.0.0 → 2.0.0

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

@@ -0,0 +1,301 @@
+import { ReactNode, RefObject, ButtonHTMLAttributes, CSSProperties, HTMLAttributes } from 'react';
+import { HTMLMotionProps } from 'motion/react';
+import { IShellMetrics, IShellSidebarFit } from './shell-metrics';
+/** The key a shell's fit state is filed under. Pass your own to reach it from
+ * anywhere (`useShellFitState("app-shell")`); leave it out and the provider
+ * generates one that dies with it. */
+export type TShellFitInstanceId = string;
+/** The range a secondary-panel resize may land in, in px. */
+export interface IShellFitPanelBounds {
+    min: number;
+    max: number;
+}
+/** What the shell measured of itself — readable by id through
+ * `useShellFitState`. */
+export interface IShellFitState {
+    /** Actual rail layout after applying container constraints. */
+    sidebar: IShellSidebarFit | null;
+    /** The px the shell last measured, or null before its first measurement
+     * (a server render, a host with no layout). */
+    metrics: IShellMetrics | null;
+    /** Whether the shell can hold a secondary panel. True while unmeasured, so
+     * a panel never flickers out over a reading that has not happened yet. */
+    fits: boolean;
+    /** The secondary panel's width in px, already clamped to `bounds` — null
+     * before the first measurement, where the panel falls back to
+     * `--panel-width`. */
+    panelWidth: number | null;
+    /** The range a resize may land in. */
+    bounds: IShellFitPanelBounds;
+}
+/** Writes only — drive a shell's secondary panel by id through
+ * `useShellFitActions` without re-rendering when it moves. */
+export interface IShellFitActions {
+    /** Resize the secondary panel. Clamped on the way in, so a drag past the
+     * gutter parks at the bound instead of banking travel it has to give back. */
+    resizePanel: (width: number) => void;
+    /** Back to the width the shell mounted with — `defaultPanelWidth`, or
+     * `--panel-width` when there was none. */
+    resetPanelWidth: () => void;
+}
+/** What `useShellFit` hands the provider: the state, the actions and the id
+ * they are filed under. */
+export interface IShellFitController extends IShellFitState, IShellFitActions {
+    defaultPanelWidth: number | null;
+    shellId: TShellFitInstanceId;
+}
+export interface IUseShellFitOptions {
+    /** File the fit under this id so it can be read elsewhere and outlive the
+     * shell. Generated (and dropped on unmount) when omitted. */
+    shellId?: TShellFitInstanceId;
+    /** The element the shell's CSS variables live on (the provider wrapper). */
+    hostRef: RefObject<HTMLElement | null>;
+    /** Whether the left rail is expanded right now — a render input, so a fold
+     * counts the moment React commits it rather than a frame later when the
+     * width animation has moved. */
+    railOpen: boolean;
+    /** The width the secondary panel opens at, in px, instead of
+     * `--panel-width`. Read once, on mount. */
+    defaultPanelWidth?: number;
+    /** Fired whenever a measurement lands on "no room": the shell uses it to
+     * retire the panel's open state instead of parking it. */
+    onUnfit?: () => void;
+}
+/** @internal What an instance starts from, restored by `resetShellPanelWidthAtom`. */
+export interface IShellFitSeed {
+    /** The requested panel width at mount — null for `--panel-width`. */
+    panelWidth: number | null;
+}
+export interface IShellAction {
+    id: string;
+    label: string;
+    icon: ReactNode;
+    badge?: ReactNode;
+    onSelect?: () => void;
+}
+export interface IShellWorkspace {
+    name: string;
+    logo?: ReactNode;
+    meta?: ReactNode;
+}
+export interface IPanel {
+    id: string;
+    name: string;
+    component: ReactNode;
+    /** Replaces the default icon inside the panel's header trigger. The shell
+     * keeps the trigger button itself (toggle wiring, aria-label) — this only
+     * swaps what renders inside it. */
+    trigger?: ReactNode;
+    open: boolean;
+    defaultOpen?: boolean;
+    side: "left" | "bottom" | "right" | "sidebar";
+}
+/** The side a panel docks to, as a value union (`IPanel["side"]`).
+ * `Pick<IPanel, "side">` would be the object type `{ side: ... }`, which can
+ * neither key a Record nor travel as a plain callback argument. */
+export type TPanelSide = IPanel["side"];
+/** Panel content keyed by the side it docks to. `Side` narrows the map to
+ * the sides a surface actually renders (the shell renders left and right).
+ * Entries are optional — a shell with no bottom dock simply has no `bottom`
+ * key. Where an entry's own `side` field disagrees with its key, the key
+ * wins. */
+export type TPanelMap<Side extends TPanelSide = TPanelSide> = Partial<Record<Side, IPanel>>;
+/** Dynamic panel content keyed by side — filled by
+ * `useShellPanels().openPanel(side, component)` and read by ShellLayout,
+ * where a side's entry wins over the static `panels` map's `component`. */
+export type TSidebarComponentMap = Partial<Record<TSidebarSide, ReactNode>>;
+/** The open/close surface of the shell's panels, lifted straight from
+ * AnimatedPanelProvider — every prop is keyed by side, there are no
+ * explicit per-side props. `useShellPanels` produces the controlled subset
+ * of these as `providerProps`. */
+export type TShellPanelControlProps = Pick<IAnimatedSidebarProviderProps, "open" | "defaultOpen" | "onOpenChange" | "openMobile" | "defaultOpenMobile" | "onOpenMobileChange" | "shellId" | "defaultPanelWidth" | "panelComponents">;
+export interface IUseShellPanelsOptions {
+    /** The id the shell's fit state is filed under. Name it to read the same
+     * shell from elsewhere (`useShellFitState("app-shell")`) and to keep a
+     * dragged panel width across a route change; otherwise the hook generates
+     * one that dies with it. */
+    shellId?: TShellFitInstanceId;
+    /** Initial desktop open state per side, merged over
+     * `{ left: true, right: false }`. */
+    defaultOpen?: IAnimatedSidebarProviderProps["defaultOpen"];
+    /** Initial mobile overlay state per side — every side starts closed. */
+    defaultOpenMobile?: IAnimatedSidebarProviderProps["defaultOpenMobile"];
+    /** The width the secondary panel opens at, in px, instead of
+     * `--panel-width`. */
+    defaultPanelWidth?: number;
+    /** Panel change event returning both the next open state and the side of
+     * the panel the change comes from. Mobile overlay changes report the same
+     * side as their desktop counterpart. */
+    onPanelChange?: (open: boolean, side: TPanelSide) => void;
+}
+export interface IShellPanelControls {
+    /** Rendered rail width and whether it can expand in the current container. */
+    sidebar: IShellSidebarFit | null;
+    sidebarWidth: number | null;
+    resizeSidebar: (width: number) => void;
+    /** The id the shell's fit state is filed under — hand it to
+     * `useShellFitState` / `useShellFitActions` anywhere below `ExegiaProvider`. */
+    shellId: TShellFitInstanceId;
+    /** The viewport cannot hold the secondary panel beside the rail and the
+     * body at their floors, so the shell has dropped the right panel and its
+     * trigger — UI outside the shell should stand down with them. Read straight
+     * out of the shell's fit atoms; it is only ever `true` once the shell is
+     * mounted and measured. */
+    isNarrow: boolean;
+    /** The secondary panel's current width in px, or null until the shell has
+     * measured itself (the panel then sits at `--panel-width`). */
+    panelWidth: number | null;
+    /** Resize the secondary panel from outside the shell — clamped to the room
+     * the shell has. */
+    resizePanel: (width: number) => void;
+    /** Requested open state. `sidebar` reports the responsive rail layout. */
+    open: Record<TSidebarSide, boolean>;
+    /** Live mobile overlay state, keyed by side. */
+    openMobile: Record<TSidebarSide, boolean>;
+    /** Refuses to OPEN the right panel while `isNarrow` — there is nothing on
+     * screen to open. Closing it always goes through. */
+    setOpen: (open: boolean, side: TSidebarSide) => void;
+    setOpenMobile: (open: boolean, side: TSidebarSide) => void;
+    /** Desktop-only convenience — the in-shell triggers already pick the
+     * mobile state themselves when the viewport is narrow. Carries the same
+     * `isNarrow` refusal as `setOpen`. */
+    toggle: (side: TSidebarSide) => void;
+    /** Open a side's panel and, when given, swap in the content it shows.
+     * The component travels through `providerProps.panelComponents` into
+     * ShellLayout, where it wins over the static `panels` entry for that
+     * side, and sticks until the next `openPanel(side, component)` replaces
+     * it — closing the panel leaves it in place for the exit animation and
+     * the next open. Carries the same `isNarrow` refusal as `setOpen`. */
+    openPanel: (side: TSidebarSide, component?: ReactNode) => void;
+    /** Spread onto ShellLayout (or AnimatedPanelProvider directly). */
+    providerProps: TShellPanelControlProps;
+}
+export interface IShellLayoutProps extends TShellPanelControlProps {
+    children?: ReactNode;
+    /** Content for the shell's panels, keyed by the side. The shell renders
+     * the `left` rail and the `right` drawer; other sides are reserved. */
+    panels?: TPanelMap;
+    header?: ReactNode;
+    /** Actions pinned to the header's right edge, rendered just before the
+     * right panel's trigger. The cluster hugs the trailing edge no matter
+     * which of `header` / the left rail / the right panel are present. */
+    trailing?: ReactNode;
+    className?: string;
+    variant?: "web" | "desktop";
+}
+export type TSidebarSide = "left" | "right";
+/** Open flags keyed by the side. Sides left out stay uncontrolled / at their
+ * default — there is no per-side prop, the record IS the API. */
+export type TSidebarOpenState = Partial<Record<TSidebarSide, boolean>>;
+export type TSidebarVariant = "sidebar" | "floating" | "inset";
+export type TSidebarCollapsible = "offcanvas" | "icon" | "none";
+export interface IAnimatedSidebarContextValue {
+    isMobile: boolean;
+    /** What the shell measured of itself: whether it can hold a secondary panel
+     * at all, how wide that panel is, and the range a resize may land in. The
+     * right panel and its trigger stand down when `fit.fits` is false. */
+    fit: IShellFitController;
+    layoutId: string;
+    /** Desktop open state, keyed by side. */
+    open: Record<TSidebarSide, boolean>;
+    /** Mobile overlay open state, keyed by side. */
+    openMobile: Record<TSidebarSide, boolean>;
+    reduce: boolean;
+    setOpen: (open: boolean, side: TSidebarSide) => void;
+    setOpenMobile: (open: boolean, side: TSidebarSide) => void;
+    /** Toggle the docked panel when the container can accommodate it. */
+    toggleSidebar: (side: TSidebarSide) => void;
+    triggerRefs: Record<TSidebarSide, React.RefObject<HTMLButtonElement | null>>;
+}
+export interface IAnimatedSidebarProviderProps extends HTMLAttributes<HTMLDivElement> {
+    /** The id this shell's fit state (whether a secondary panel fits, how wide
+     * it is) is filed under in the store. Name it to read or drive the shell
+     * from elsewhere and to keep a dragged width across a route change; omit it
+     * and the provider generates one that is dropped on unmount. */
+    shellId?: TShellFitInstanceId;
+    /** The width the secondary panel opens at, in px, instead of
+     * `--panel-width`. Read once, on mount. */
+    defaultPanelWidth?: number;
+    /** Controlled desktop open state, keyed by the side. A side left undefined
+     * stays uncontrolled. */
+    open?: TSidebarOpenState;
+    /** Initial desktop open state, merged over `{ left: true, right: false }`. */
+    defaultOpen?: TSidebarOpenState;
+    onOpenChange?: (open: boolean, side: TSidebarSide) => void;
+    /** Controlled mobile overlay state, keyed by side. */
+    openMobile?: TSidebarOpenState;
+    /** Initial mobile overlay state — every side starts closed. */
+    defaultOpenMobile?: TSidebarOpenState;
+    onOpenMobileChange?: (open: boolean, side: TSidebarSide) => void;
+    /** Content pushed into a side's panel by `useShellPanels().openPanel`. It
+     * rides along in `providerProps` so the record can be spread on either
+     * surface: ShellLayout renders it in that side's panel; the bare provider
+     * renders no panels, so it only swallows the prop to keep it off the DOM. */
+    panelComponents?: TSidebarComponentMap;
+    /** Fires when the shell crosses the width a secondary panel needs (rail +
+     * body + panel at their floors). An imperative escape hatch for a consumer
+     * that mounts the provider on its own; anything under `ExegiaProvider` can
+     * subscribe by id instead with `useShellFitState(shellId).fits`. */
+    onNarrowChange?: (isNarrow: boolean) => void;
+    style?: TSidebarProviderStyle;
+}
+export type TSidebarProviderStyle = CSSProperties & {
+    /** Left rail, expanded. */
+    "--sidebar-width"?: string;
+    /** Minimum expanded rail width before it folds to icons. Default 180px. */
+    "--sidebar-min-width"?: string;
+    /** Left rail, folded to icons. */
+    "--sidebar-width-icon"?: string;
+    "--sidebar-width-mobile"?: string;
+    /** The secondary panel's floor, and the width it opens at. */
+    "--panel-width"?: string;
+    /** The body's floor — the secondary panel may never squeeze it past this. */
+    "--inset-min-width"?: string;
+};
+export type TAnimatedSidebarInsetProps = HTMLMotionProps<"main">;
+export interface IAnimatedSidebarTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    side?: TSidebarSide;
+}
+export interface IAnimatedSidebarPanelContextValue {
+    collapsed: boolean;
+    collapsible: TSidebarCollapsible;
+    side: TSidebarSide;
+}
+export interface IAnimatedSidebarProps extends Omit<HTMLMotionProps<"aside">, "children"> {
+    children?: ReactNode;
+    side?: TSidebarSide;
+    variant?: TSidebarVariant;
+    collapsible?: TSidebarCollapsible;
+    ariaLabel?: string;
+    panelClassName?: string;
+}
+export interface IAnimatedSidebarMenuSubProps extends Omit<HTMLMotionProps<"ul">, "children"> {
+    open: boolean;
+    children?: ReactNode;
+}
+export interface IAnimatedSidebarMenuSubButtonProps {
+    children: ReactNode;
+    icon?: ReactNode;
+    href?: string;
+    isActive?: boolean;
+    disabled?: boolean;
+    closeOnSelect?: boolean;
+    target?: "_blank" | "_self" | "_parent" | "_top";
+    rel?: string;
+    onSelect?: () => void;
+    className?: string;
+}
+export interface IAnimatedSidebarMenuButtonProps {
+    children: ReactNode;
+    icon?: ReactNode;
+    badge?: ReactNode;
+    href?: string;
+    isActive?: boolean;
+    ariaExpanded?: boolean;
+    disabled?: boolean;
+    closeOnSelect?: boolean;
+    target?: "_blank" | "_self" | "_parent" | "_top";
+    rel?: string;
+    onSelect?: () => void;
+    className?: string;
+}

package/dist-lib/components/blocks/shell/use-shell-fit-state.d.ts

@@ -0,0 +1,25 @@
+import { IShellFitActions, TShellFitInstanceId, IShellFitState } from './type';
+/**
+ * Read the fit of the shell registered under `shellId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { fits, panelWidth } = useShellFitState("app-shell")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on every
+ * measurement. A component that reads one field should subscribe to that
+ * field's atom instead: `useAtomValue(shellFitFitsAtom("app-shell"))`.
+ */
+export declare function useShellFitState(shellId: TShellFitInstanceId): IShellFitState;
+/**
+ * Drive the secondary panel of the shell registered under `shellId` from
+ * anywhere. Writes only — the caller never re-renders when the shell moves,
+ * so this is what a command palette or a keyboard shortcut should reach for.
+ *
+ * ```tsx
+ * const shell = useShellFitActions("app-shell")
+ * <Button onClick={() => shell.resizePanel(480)}>Wide inspector</Button>
+ * ```
+ */
+export declare function useShellFitActions(shellId: TShellFitInstanceId): IShellFitActions;

package/dist-lib/components/blocks/shell/use-shell-fit.d.ts

@@ -0,0 +1,13 @@
+import { IShellFitController, IUseShellFitOptions } from './type';
+/**
+ * Measures the shell and decides what the secondary panel may do: whether it
+ * exists at all, and how wide it may be dragged.
+ *
+ * Container resizing, rail folding, and user resizing are observed here,
+ * so embedded shells obey the same bounds as full-page layouts. The measurement is
+ * the only thing this hook keeps to itself: the numbers land in the shell-fit
+ * atoms keyed by `shellId`, so anything under `ExegiaProvider` can read the
+ * verdict (`useShellFitState`) or move the panel (`useShellFitActions`)
+ * without holding this controller.
+ */
+export declare function useShellFit({ shellId: explicitId, hostRef, railOpen, defaultPanelWidth, onUnfit, }: IUseShellFitOptions): IShellFitController;

package/dist-lib/components/blocks/shell/use-shell-panels.d.ts

@@ -0,0 +1,20 @@
+import { IShellPanelControls, IUseShellPanelsOptions } from './type';
+/**
+ * Owns the open/close state of the shell's panels, keyed by side, and
+ * reports every change through a single `onPanelChange(open, side)`
+ * callback. Spread the returned `providerProps` onto ShellLayout; the
+ * setters and `toggle` are for UI that lives outside the shell (title-bar
+ * buttons, command palette, shortcuts).
+ *
+ * The way back down is the store: `providerProps` carries a `shellId`, the
+ * shell files its measurement under it, and this hook reads `isNarrow` and
+ * `panelWidth` straight out of those atoms — so outside UI stands down with
+ * the panel instead of measuring `--sidebar-width` a second time. Name the
+ * `shellId` and any component below `ExegiaProvider` can do the same with
+ * `useShellFitState(shellId)`.
+ *
+ * Call it under the same `ExegiaProvider` as the shell it drives (or under
+ * none at all, on both sides): mounted above the provider it would read
+ * Jotai's default store while the shell writes to the provider's.
+ */
+export declare function useShellPanels({ shellId: explicitId, defaultOpen, defaultOpenMobile, defaultPanelWidth, onPanelChange, }?: IUseShellPanelsOptions): IShellPanelControls;

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

@@ -0,0 +1,72 @@
+import { Variants } from 'motion/react';
+import { IAnimatedSidebarContextValue, IAnimatedSidebarPanelContextValue } from './type';
+export declare const SHELL_BEZEL_CLASSES = "bezel-lit-t-2 bezel-lit-blur-2 bezel-lit/57 bezel-dim-b-2 bezel-dim-blur-3 bezel-dim/11 dark:bezel-lit-blur-3 dark:bezel-lit/14 dark:bezel-dim/78";
+export declare const TITLE_BAR_HEIGHT = 48;
+export declare const SIDEBAR_MORPH_TRANSITION: {
+    readonly type: "spring";
+    readonly stiffness: 380;
+    readonly damping: 35;
+    readonly mass: 0.75;
+};
+export declare const LABEL_ENTER_TRANSITION: {
+    readonly duration: 0.2;
+    readonly delay: 0.08;
+    readonly ease: readonly [0.16, 1, 0.3, 1];
+};
+export declare const LABEL_EXIT_TRANSITION: {
+    readonly duration: 0.12;
+    readonly ease: readonly [0.16, 1, 0.3, 1];
+};
+export declare const PANEL_TRANSITION: {
+    readonly duration: 0.36;
+    readonly ease: readonly [0.32, 0.72, 0, 1];
+};
+export declare const REDUCED_TRANSITION: {
+    readonly duration: 0.16;
+    readonly ease: readonly [0.16, 1, 0.3, 1];
+};
+export declare const SUBMENU_VARIANTS: Variants;
+export declare const SUBMENU_ITEM_VARIANTS: Variants;
+export declare const FOCUSABLE_SELECTOR: string;
+export declare const MOBILE_QUERY = "(max-width: 767px)";
+export declare const SIDEBAR_KEYBOARD_SHORTCUT = "b";
+/**
+ * The shell's layout contract, in px. Every entry lands on the provider's
+ * wrapper as a CSS variable, so a consumer overrides a column by restyling it
+ * rather than by passing a prop:
+ *
+ * | variable               | column                                    |
+ * | ---------------------- | ----------------------------------------- |
+ * | `--sidebar-width`      | left rail, expanded                       |
+ * | `--sidebar-width-icon` | left rail, folded to icons                |
+ * | `--panel-width`        | secondary panel: its floor AND its default |
+ * | `--inset-min-width`    | the body's floor                          |
+ *
+ * These are only the defaults. Every measurement resolves the live variable,
+ * so an override wins over the value written here.
+ */
+export declare const SHELL_WIDTHS: {
+    readonly "--sidebar-min-width": "180px";
+    readonly "--sidebar-width": "256px";
+    readonly "--sidebar-width-icon": "56px";
+    readonly "--sidebar-width-mobile": "18rem";
+    readonly "--panel-width": "320px";
+    readonly "--inset-min-width": "360px";
+};
+/** The expanded width of a panel docked to `side`: the secondary panel opens
+ * at `--panel-width`, the primary rail at `--sidebar-width`. */
+export declare function expandedWidthVar(side: "left" | "right"): "var(--panel-width)" | "var(--sidebar-width)";
+/** Resolve a CSS length — `var()` included — to px inside `host`'s cascade.
+ * Custom properties inherit, so a throwaway probe mounted in `host` reads the
+ * very `--sidebar-width` the shell lays out with, including a value a
+ * consumer overrode on the provider. Returns 0 when `host` has no layout
+ * (server render, `display: none`), so callers must fail open on 0 rather
+ * than treat it as a real measurement. */
+export declare function resolveLength(host: HTMLElement, value: string): number;
+export declare const AnimatedSidebarContext: import('react').Context<IAnimatedSidebarContextValue | null>;
+export declare const AnimatedSidebarPanelContext: import('react').Context<IAnimatedSidebarPanelContextValue | null>;
+export declare function useAnimatedSidebar(): IAnimatedSidebarContextValue;
+export declare function getMobileSnapshot(): boolean;
+export declare function getServerMobileSnapshot(): boolean;
+export declare function useIsMobile(): boolean;
+export declare function useAnimatedSidebarPanel(): IAnimatedSidebarPanelContextValue;

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

@@ -0,0 +1,217 @@
+import { Atom } from 'jotai';
+import { IAISidebarConfig, IAISidebarHandlers, TAISidebarInstanceId, IAISidebarSeed, IAISidebarState, IDropTarget, IFlatResource, ISidebarResource, TSidebarResourceDropPosition, ISidebarResourceMove } from './type.ts';
+/** What a sidebar reads as before `useAISidebar` publishes its options. */
+export declare const DEFAULT_AI_SIDEBAR_CONFIG: IAISidebarConfig;
+/**
+ * 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 TFamily<AtomType> = ((id: TAISidebarInstanceId) => AtomType) & {
+    remove: (id: TAISidebarInstanceId) => void;
+};
+/** @internal */
+export declare const aiSidebarConfigAtom: TFamily<import('jotai').PrimitiveAtom<IAISidebarConfig> & {
+    init: IAISidebarConfig;
+}>;
+/** @internal Refreshed every commit; nothing subscribes, so it is free. */
+export declare const aiSidebarHandlersAtom: TFamily<import('jotai').PrimitiveAtom<IAISidebarHandlers> & {
+    init: IAISidebarHandlers;
+}>;
+/** The sidebar's current data — hook-owned, or the projection of a
+ * controlled `items` prop. */
+export declare const aiSidebarItemsAtom: TFamily<import('jotai').PrimitiveAtom<ISidebarResource[]> & {
+    init: ISidebarResource[];
+}>;
+/** @internal The hook-owned selection. `select` writes it only while no
+ * `activeId` prop owns the selection — read `aiSidebarActiveIdAtom` for the
+ * value the sidebar actually renders. */
+export declare const aiSidebarOwnActiveIdAtom: TFamily<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+/** @internal Projection of a controlled `activeId` prop; `undefined` while
+ * the selection is hook-owned. */
+export declare const aiSidebarControlledActiveIdAtom: TFamily<import('jotai').PrimitiveAtom<string | null | undefined> & {
+    init: string | null | undefined;
+}>;
+/** Open rows — hook-owned, or the projection of a controlled `expandedIds`
+ * prop. */
+export declare const aiSidebarExpandedIdsAtom: TFamily<import('jotai').PrimitiveAtom<ReadonlySet<string>> & {
+    init: ReadonlySet<string>;
+}>;
+/** Roving-focus target. DOM focus is moved by the block, which owns the row
+ * refs; this is only which row is tabbable. */
+export declare const aiSidebarFocusedIdAtom: TFamily<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+export declare const aiSidebarDraggingIdAtom: TFamily<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+export declare const aiSidebarDropTargetAtom: TFamily<import('jotai').PrimitiveAtom<IDropTarget | null> & {
+    init: IDropTarget | null;
+}>;
+export declare const aiSidebarMenuOpenIdAtom: TFamily<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+export declare const aiSidebarRenamingIdAtom: TFamily<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+export declare const aiSidebarHoveredIdAtom: TFamily<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+/** Live-region text for the last move or rename outcome. */
+export declare const aiSidebarAnnouncementAtom: TFamily<import('jotai').PrimitiveAtom<string> & {
+    init: string;
+}>;
+/** A move is in flight. Read synchronously by `moveAISidebarRowAtom` before
+ * it starts another — the store needs no ref to see its own latest write. */
+export declare const aiSidebarMovePendingAtom: TFamily<import('jotai').PrimitiveAtom<boolean> & {
+    init: boolean;
+}>;
+/** @internal The only items atom `useAISidebar` 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 aiSidebarOwnedItemsAtom: TFamily<Atom<ISidebarResource[]>>;
+/** @internal The same guard for `expandedIds`, which is controllable here
+ * and arrives as an array — just as unstable an identity as `items`. */
+export declare const aiSidebarOwnedExpandedIdsAtom: TFamily<Atom<ReadonlySet<string>>>;
+/** The selected row: the controlled `activeId` when there is one, the
+ * hook-owned selection otherwise. Kept as two atoms because a controlled
+ * `activeId` of `null` falls through to the hook-owned value — the block has
+ * always read `activeId ?? internalActiveId`. */
+export declare const aiSidebarActiveIdAtom: TFamily<Atom<string | null>>;
+/** Visible rows in order, each with its depth and parent id. */
+export declare const aiSidebarFlatAtom: TFamily<Atom<IFlatResource[]>>;
+/** Some row is hovered and no drag is running — mounts the pill wrapper. */
+export declare const aiSidebarHoverActiveAtom: TFamily<Atom<boolean>>;
+/** Whether this one row is the current selection. */
+export declare const aiSidebarRowSelectedAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<boolean>;
+/** Whether this one row is open. */
+export declare const aiSidebarRowExpandedAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<boolean>;
+/** Whether this one row is the roving-focus target. */
+export declare const aiSidebarRowFocusedAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<boolean>;
+/** Whether this one row is in rename mode. */
+export declare const aiSidebarRowRenamingAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<boolean>;
+/** Whether this one row's action menu is open. */
+export declare const aiSidebarRowMenuOpenAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<boolean>;
+/** Whether this one row is the row in flight. */
+export declare const aiSidebarRowDraggingAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<boolean>;
+/** Where a drop on this one row would land, `null` when it is not hovered
+ * by a drag. */
+export declare const aiSidebarRowDropAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<TSidebarResourceDropPosition | null>;
+/** Whether this one row owns the sliding hover pill. */
+export declare const aiSidebarRowHoveredAtom: (id: TAISidebarInstanceId, rowId: string) => Atom<boolean>;
+/** The whole state of one sidebar. Components reading a single field should
+ * subscribe to that field's atom instead — this one changes on every edit. */
+export declare const aiSidebarStateAtom: TFamily<Atom<IAISidebarState>>;
+export declare const expandAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+export declare const collapseAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+export declare const toggleAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+export declare const expandAllAISidebarRowsAtom: TFamily<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+export declare const collapseAllAISidebarRowsAtom: TFamily<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Open every ancestor of `rowId` without touching the rest of the tree. */
+export declare const revealAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+export declare const selectAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+/** The store half of `focus`: which row is tabbable. Moving DOM focus is the
+ * block's job — it owns the row refs. */
+export declare const focusAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+/** @internal Keeps the roving target on a row that still renders: a focused
+ * row that folds away hands focus to the first visible row instead of
+ * pointing at nothing. `useAISidebar` runs it after every projection. */
+export declare const normalizeAISidebarFocusAtom: TFamily<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+export declare const startAISidebarRenameAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+export declare const cancelAISidebarRenameAtom: TFamily<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Commit a rename and leave rename mode. Applied optimistically and rolled
+ * back if `onRename` rejects. Blank and unchanged labels are dropped. */
+export declare const renameAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string, label: string], void> & {
+    init: null;
+}>;
+export declare const openAISidebarMenuAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string], void> & {
+    init: null;
+}>;
+/** Closes the menu and hands the roving target back to the row that owned
+ * it, then returns that id so the block can move DOM focus there — otherwise
+ * focus falls back to the body and the keyboard user loses their place. */
+export declare const closeAISidebarMenuAtom: TFamily<import('jotai').WritableAtom<null, [], string | null> & {
+    init: null;
+}>;
+/**
+ * Reorder, applied optimistically and rolled back if `onMove` rejects.
+ *
+ * The pending flag is read straight back out of the store, which is why this
+ * needs no ref to guard overlapping moves the way React state did: the write
+ * is visible to the next call immediately, not after a commit.
+ */
+export declare const moveAISidebarRowAtom: TFamily<import('jotai').WritableAtom<null, [move: ISidebarResourceMove], Promise<void>> & {
+    init: null;
+}>;
+/** Replace the data. Reports through `onItemsChange`; writes the atom only
+ * when no controlled `items` prop owns it. */
+export declare const setAISidebarItemsAtom: TFamily<import('jotai').WritableAtom<null, [items: ISidebarResource[]], void> & {
+    init: null;
+}>;
+export declare const setAISidebarHoveredAtom: TFamily<import('jotai').WritableAtom<null, [rowId: string, hovered: boolean], void> & {
+    init: null;
+}>;
+export declare const clearAISidebarHoverAtom: TFamily<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+export declare const endAISidebarDragAtom: TFamily<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** @internal Publish the latest options; seed the instance once. */
+export declare const mountAISidebarAtom: TFamily<import('jotai').WritableAtom<null, [config: IAISidebarConfig, seed: IAISidebarSeed], void> & {
+    init: null;
+}>;
+/** @internal */
+export declare const setAISidebarHandlersAtom: TFamily<import('jotai').WritableAtom<null, [handlers: IAISidebarHandlers], void> & {
+    init: null;
+}>;
+/** @internal One-way projections of controlled props — no callbacks fire. */
+export declare const projectAISidebarItemsAtom: TFamily<import('jotai').WritableAtom<null, [items: ISidebarResource[]], void> & {
+    init: null;
+}>;
+/** @internal */
+export declare const projectAISidebarActiveIdAtom: TFamily<import('jotai').WritableAtom<null, [activeId: string | null], void> & {
+    init: null;
+}>;
+/** @internal */
+export declare const projectAISidebarExpandedIdsAtom: TFamily<import('jotai').WritableAtom<null, [expandedIds: string[]], void> & {
+    init: null;
+}>;
+/** Back to the values the instance mounted with. */
+export declare const resetAISidebarAtom: TFamily<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Drop every atom for `id`. `useAISidebar` calls this on unmount for
+ * sidebars it keyed itself; an explicit `sidebarId` outlives its component,
+ * so an app-named sidebar keeps its open rows across a route change. */
+export declare function removeAISidebarInstance(id: TAISidebarInstanceId): void;
+export {};

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

@@ -0,0 +1,11 @@
+import { TAISidebarComponentProps } 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: TAISidebarComponentProps): import("react").JSX.Element;