@exegia/corpora-ui 0.20.0 → 0.22.0

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

@@ -17,10 +17,18 @@ export interface SidebarResourceMenuControls {
     close: () => void;
     rename: () => void;
 }
+/** Key for one sidebar's state in the store. Any stable string;
+ * `useAISidebar` generates one when you don't pass it. */
+export type AISidebarInstanceId = string;
 /** Options for `useAISidebar`. `items`, `activeId` and `expandedIds` are
  * each controlled when passed and hook-owned via their `default*` twin
  * otherwise. */
 export interface UseAISidebarOptions {
+    /** Key this sidebar's state under a name your app can address —
+     * `useAISidebarState("app-resources")` / `useAISidebarActions(...)` reach
+     * it from anywhere under `ExegiaProvider`. Without one the hook generates
+     * a key and the state is dropped when the component unmounts. */
+    sidebarId?: AISidebarInstanceId;
     items?: SidebarResource[];
     defaultItems?: SidebarResource[];
     onItemsChange?: (items: SidebarResource[]) => void;
@@ -39,6 +47,8 @@ export interface UseAISidebarOptions {
  * toolbar, a command palette, a route change. Returned by `useAISidebar`
  * and accepted by `<AISidebar controller={…} />`. */
 export interface AISidebarController {
+    /** The key this sidebar's state is stored under. */
+    sidebarId: AISidebarInstanceId;
     items: SidebarResource[];
     /** Visible rows in order, each with its depth and parent id. */
     flat: FlatResource[];
@@ -74,6 +84,8 @@ export interface AISidebarController {
     movePending: boolean;
     /** Live-region text for the last move or rename outcome. */
     announcement: string;
+    /** Back to the values the sidebar mounted with. */
+    reset: () => void;
     /** @internal Row wiring the view threads through — drag state, the
      * hover pill and roving keyboard nav all belong to the rendering. */
     dnd: AISidebarDndState;
@@ -82,10 +94,15 @@ export interface AISidebarController {
     setRowRef: (id: string, node: HTMLDivElement | null) => void;
 }
 /** @internal */
-export interface AISidebarDndState {
+export interface AISidebarDndState extends AISidebarRowDndHandlers {
     draggingId: string | null;
     dropTarget: DropTarget | null;
     onRootDragOver: (event: DragEvent<HTMLDivElement>) => void;
+}
+/** @internal The drag handlers a row needs, stable for the life of the
+ * sidebar — they read drag state out of the store when they run instead of
+ * closing over it, so handing them to every row costs no re-renders. */
+export interface AISidebarRowDndHandlers {
     onDrop: (event: DragEvent<HTMLDivElement>) => void;
     onRowDragStart: (event: DragEvent<HTMLDivElement>, id: string) => void;
     onRowDragEnd: () => void;
@@ -130,36 +147,99 @@ export interface DropTarget {
     id: string | null;
     position: SidebarResourceDropPosition;
 }
+/** A row takes its place in the tree and nothing else: selection,
+ * expansion, focus, rename, drag and hover state all arrive through its own
+ * atoms, and the rendering options through the sidebar context. */
 export interface ResourceRowProps {
     row: FlatResource;
-    active: boolean;
-    expanded: boolean;
-    focused: boolean;
-    draggingId: string | null;
-    dropTarget: DropTarget | null;
-    menuOpen: boolean;
-    renaming: boolean;
-    onDragEnd: () => void;
-    onDragOver: (event: DragEvent<HTMLDivElement>, row: FlatResource) => void;
-    onDragStart: (event: DragEvent<HTMLDivElement>, id: string) => void;
-    onDrop: (event: DragEvent<HTMLDivElement>) => void;
-    onFocus: () => void;
-    onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
-    onMenuOpenChange: (open: boolean) => void;
-    onRenameCancel: () => void;
-    onRenameCommit: (label: string) => void;
-    onRenameStart: () => void;
-    onSelect: () => void;
-    onToggle: () => void;
-    /** Some row in the tree is hovered — mounts the pill fade wrapper. */
-    hoverActive?: boolean;
-    /** This row owns the sliding hover pill. */
-    hoverPill?: boolean;
-    /** Shared motion layoutId that lets the pill travel between rows. */
-    hoverLayoutId?: string;
-    onHoverChange?: (hovered: boolean) => void;
-    renderIcon?: (item: SidebarResource) => ReactNode;
+}
+/** @internal What a row needs from the block, threaded through context so
+ * the rows stay prop-light.
+ *
+ * Deliberately free of sidebar state and of the controller. Rows read state
+ * from per-row atoms, so this value keeps its identity for the life of the
+ * sidebar and hovering or expanding one row no longer re-renders every row
+ * through context. */
+export interface AISidebarContextValue {
+    sidebarId: AISidebarInstanceId;
+    /** Shared motion layoutId that lets the hover pill travel between rows. */
+    hoverLayoutId: string;
+    renderIcon?: AISidebarProps["renderIcon"];
     renderMenu?: AISidebarProps["renderMenu"];
     renderActionsTrigger?: AISidebarProps["renderActionsTrigger"];
-    setRef: (node: HTMLDivElement | null) => void;
+    /** Registers the row's DOM node with the block, which owns the ref map —
+     * DOM nodes never go in the store. */
+    setRowRef: (id: string, node: HTMLDivElement | null) => void;
+    onRowKeyDown: (event: KeyboardEvent<HTMLDivElement>, row: FlatResource) => void;
+    onRowHover: (id: string, hovered: boolean) => void;
+    /** Closing returns DOM focus to the row that owned the menu, so it goes
+     * through the block rather than the store. */
+    closeMenu: () => void;
+    dnd: AISidebarRowDndHandlers;
+}
+/** Everything observable about one sidebar, for consumers reading it by id. */
+export interface AISidebarState {
+    items: SidebarResource[];
+    /** Visible rows in order, each with its depth and parent id. */
+    flat: FlatResource[];
+    selectedId: string | null;
+    expandedIds: ReadonlySet<string>;
+    focusedId: string | null;
+    renamingId: string | null;
+    menuOpenId: string | null;
+    draggingId: string | null;
+    dropTarget: DropTarget | null;
+    hoveredId: string | null;
+    /** 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;
+}
+/** Everything doable to one sidebar from outside its component. */
+export interface AISidebarActions {
+    select: (id: string) => void;
+    expand: (id: string) => void;
+    collapse: (id: string) => void;
+    toggleExpanded: (id: string) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    reveal: (id: string) => void;
+    /** Moves the roving-focus target. DOM focus follows only for callers that
+     * hold the controller — the ref map lives in the block, not the store. */
+    focus: (id: string) => void;
+    startRename: (id: string) => void;
+    cancelRename: () => void;
+    rename: (id: string, label: string) => void;
+    openMenu: (id: string) => void;
+    closeMenu: () => void;
+    move: (move: SidebarResourceMove) => Promise<void>;
+    setItems: (items: SidebarResource[]) => void;
+    reset: () => void;
+}
+/** @internal Projection of `useAISidebar`'s options — primitives only, so
+ * the store write runs once per real change instead of once per render. */
+export interface AISidebarConfig {
+    controlsItems: boolean;
+    controlsActiveId: boolean;
+    controlsExpandedIds: boolean;
+}
+/** @internal Latest option callbacks. Only write atoms read this, so it can
+ * be refreshed every commit without re-rendering anything. */
+export interface AISidebarHandlers {
+    onItemsChange?: (items: SidebarResource[]) => void;
+    onMove?: (move: SidebarResourceMove) => void | Promise<void>;
+    onMoveError?: (error: unknown, move: SidebarResourceMove) => void;
+    onRename?: (item: SidebarResource, label: string) => void | Promise<void>;
+    onActiveChange?: (id: string) => void;
+    onExpandedChange?: (ids: string[]) => void;
+}
+/** @internal What an instance starts from, replayed by
+ * `resetAISidebarAtom`. */
+export interface AISidebarSeed {
+    items: SidebarResource[];
+    /** Hook-owned selection — the `defaultActiveId`, never the controlled
+     * `activeId`. */
+    activeId: string | null;
+    focusedId: string | null;
+    expandedIds: string[];
 }

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

@@ -0,0 +1,29 @@
+import { AISidebarActions, AISidebarInstanceId, AISidebarState } from './type.ts';
+/**
+ * Read the sidebar registered under `sidebarId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { selectedId, movePending } = useAISidebarState("app-resources")
+ * ```
+ *
+ * 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(aiSidebarActiveIdAtom("app-resources"))`.
+ */
+export declare function useAISidebarState(sidebarId: AISidebarInstanceId): AISidebarState;
+/**
+ * Drive the sidebar registered under `sidebarId` from anywhere. Writes only —
+ * the caller never re-renders when the sidebar changes, so this is what a
+ * command palette, a keyboard shortcut or a route guard should reach for.
+ *
+ * `focus` and `closeMenu` move the store's roving target; DOM focus follows
+ * only for callers that hold the controller, because the row refs live in
+ * the block rather than the store.
+ *
+ * ```tsx
+ * const resources = useAISidebarActions("app-resources")
+ * <Button onClick={resources.collapseAll}>Collapse all</Button>
+ * ```
+ */
+export declare function useAISidebarActions(sidebarId: AISidebarInstanceId): AISidebarActions;

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

@@ -8,7 +8,7 @@ export type { UseAISidebarOptions };
  *
  * `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
+ * are applied to the data optimistically 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.
@@ -18,5 +18,10 @@ export type { UseAISidebarOptions };
  * <AISidebar controller={sidebar} />
  * <Button onClick={sidebar.collapseAll}>Collapse all</Button>
  * ```
+ *
+ * State lives in Jotai atoms keyed by `sidebarId`, so anything under
+ * `ExegiaProvider` can drive this sidebar without the controller — name it
+ * and reach for `useAISidebarState(sidebarId)` /
+ * `useAISidebarActions(sidebarId)` elsewhere.
  */
 export declare function useAISidebar(options: UseAISidebarOptions): AISidebarController;

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

@@ -4,7 +4,7 @@ export declare const ROW_REVEAL: {
     readonly ease: readonly [0.16, 1, 0.3, 1];
 };
 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 flattenResources(items: SidebarResource[], expanded: ReadonlySet<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[];

package/dist-lib/components/blocks/profile/index.d.ts

@@ -0,0 +1,7 @@
+export { ProfileCardBlock, defaultProfileCardItems, } from './profile-card-block';
+export type { ProfileCardBlockProps } from './profile-card-block';
+export { useProfileCard } from './use-profile-card';
+export type { ProfileCardBinding, UseProfileCardOptions } from './use-profile-card';
+export { useProfileCardActions, useProfileCardState, } from './use-profile-card-state';
+export { profileCardBusyAtom, profileCardCollapsedAtom, profileCardMenuOpenAtom, profileCardPendingActionIdAtom, profileCardStateAtom, profileCardVariantAtom, removeProfileCardInstance, resetProfileCardAtom, selectProfileCardActionAtom, setProfileCardMenuOpenAtom, setProfileCardVariantAtom, toggleProfileCardVariantAtom, } from './profile-card-atom';
+export type * from './type';

package/dist-lib/components/blocks/profile/profile-card-atom.d.ts

@@ -0,0 +1,68 @@
+import { ProfileCardAction, ProfileCardConfig, ProfileCardHandlers, ProfileCardInstanceId, ProfileCardState, ProfileCardVariant } from './type';
+type Family<AtomType> = ((id: ProfileCardInstanceId) => AtomType) & {
+    remove: (id: ProfileCardInstanceId) => void;
+};
+export declare const profileCardVariantAtom: Family<import('jotai').PrimitiveAtom<ProfileCardVariant> & {
+    init: ProfileCardVariant;
+}>;
+export declare const profileCardMenuOpenAtom: Family<import('jotai').PrimitiveAtom<boolean> & {
+    init: boolean;
+}>;
+export declare const profileCardPendingActionIdAtom: Family<import('jotai').PrimitiveAtom<string | null> & {
+    init: string | null;
+}>;
+/** @internal */
+export declare const profileCardConfigAtom: Family<import('jotai').PrimitiveAtom<ProfileCardConfig> & {
+    init: ProfileCardConfig;
+}>;
+/** @internal */
+export declare const profileCardHandlersAtom: Family<import('jotai').PrimitiveAtom<ProfileCardHandlers> & {
+    init: ProfileCardHandlers;
+}>;
+export declare const profileCardCollapsedAtom: Family<import('jotai').Atom<boolean>>;
+export declare const profileCardBusyAtom: Family<import('jotai').Atom<boolean>>;
+/** Whole-state read for callers that want the object; the field atoms are
+ * cheaper for components that watch one thing. */
+export declare const profileCardStateAtom: Family<import('jotai').Atom<ProfileCardState>>;
+/** Reports through `onVariantChange` always; writes the store only when no
+ * `variant` prop controls the card — the prop is truth then. */
+export declare const setProfileCardVariantAtom: Family<import('jotai').WritableAtom<null, [variant: ProfileCardVariant], void> & {
+    init: null;
+}>;
+export declare const toggleProfileCardVariantAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Inert while an `open` prop controls the menu. */
+export declare const setProfileCardMenuOpenAtom: Family<import('jotai').WritableAtom<null, [open: boolean], void> & {
+    init: null;
+}>;
+/**
+ * Run an action's `onSelect`. A returned promise marks the card busy until it
+ * settles; a rejection goes to `onError` and the card leaves its busy state
+ * either way. Because the pending id is a store value, it survives the card
+ * unmounting mid-flight (sign-out typically unmounts it) — the settle just
+ * writes to an instance nobody renders any more.
+ */
+export declare const selectProfileCardActionAtom: Family<import('jotai').WritableAtom<null, [action: ProfileCardAction], void> & {
+    init: null;
+}>;
+/** @internal Projection of the mounted component's controlled props. */
+export declare const projectProfileCardPropsAtom: Family<import('jotai').WritableAtom<null, [config: ProfileCardConfig, variant: ProfileCardVariant | undefined, menuOpen: boolean | undefined], void> & {
+    init: null;
+}>;
+/** @internal */
+export declare const setProfileCardHandlersAtom: Family<import('jotai').WritableAtom<null, [handlers: ProfileCardHandlers], void> & {
+    init: null;
+}>;
+/** @internal Seed the uncontrolled variant on mount without firing
+ * `onVariantChange`. */
+export declare const seedProfileCardVariantAtom: Family<import('jotai').WritableAtom<null, [variant: ProfileCardVariant], void> & {
+    init: null;
+}>;
+export declare const resetProfileCardAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Forget a card entirely — every family drops the key so the store can
+ * release its state. Call on teardown of a named instance. */
+export declare function removeProfileCardInstance(id: ProfileCardInstanceId): void;
+export {};

package/dist-lib/components/blocks/profile/profile-card-block.d.ts

@@ -1,42 +1,7 @@
 import { DropdownMenuContent, MenuPrimitive } from '../../ui/menu';
+import { ProfileCardItem, ProfileCardUser, ProfileCardVariant } from './type';
 import * as React from "react";
-/** The identity shown on the card. */
-export interface ProfileCardUser {
-    name: string;
-    /** Secondary line under the name — a handle, an email, a role. */
-    username?: string;
-    /** Avatar image URL. Falls back to the initials when absent or broken. */
-    avatar?: string;
-    /** Fallback initials. Derived from `name` when omitted. */
-    initials?: string;
-}
-/** An actionable row of the menu. */
-export interface ProfileCardAction {
-    type?: "item";
-    id: string;
-    label: string;
-    icon?: React.ReactNode;
-    /** Right-aligned hint, e.g. "⌘K". Purely decorative — bind the key yourself. */
-    shortcut?: string;
-    disabled?: boolean;
-    variant?: "default" | "destructive";
-    /** Returning a promise puts the card in its loading state until it settles. */
-    onSelect?: () => void | Promise<void>;
-}
-/** A heading over the rows that follow it, up to the next separator. */
-export interface ProfileCardLabel {
-    type: "label";
-    label: string;
-}
-/** A rule between two sections. */
-export interface ProfileCardSeparator {
-    type: "separator";
-}
-/**
- * One entry of `items`. Authored flat; the block renders each run between
- * separators as its own menu group so a label actually names its section.
- */
-export type ProfileCardItem = ProfileCardAction | ProfileCardLabel | ProfileCardSeparator;
+export type { ProfileCardAction, ProfileCardActions, ProfileCardInstanceId, ProfileCardItem, ProfileCardLabel, ProfileCardSeparator, ProfileCardState, ProfileCardUser, ProfileCardVariant, } from './type';
 /**
  * The menu the card ships with. Spread it to keep the shape and attach your
  * own handlers, or ignore it and pass `items` of your own.
@@ -62,6 +27,31 @@ export interface ProfileCardBlockProps {
      * width, so `align` stops mattering horizontally.
      */
     menuWidth?: "content" | "card";
+    /**
+     * `expanded` shows avatar, name and handle; `collapsed` folds the card to
+     * its avatar — for an icon-collapsed sidebar rail. The fold animates: the
+     * identity lines and chevron slide to zero width, the avatar stays put.
+     * Controlled when passed. Left unset, the card follows the `AnimatedPanel`
+     * it sits in (a panel footer folds with the rail on its own), and
+     * outside a panel starts from `defaultVariant`.
+     */
+    variant?: ProfileCardVariant;
+    defaultVariant?: ProfileCardVariant;
+    onVariantChange?: (variant: ProfileCardVariant) => void;
+    /**
+     * Name this card's slice of the store so `useProfileCardState(id)` /
+     * `useProfileCardActions(id)` can read or drive it (fold it, open its
+     * menu) from anywhere under `ExegiaProvider`. Unnamed cards key off
+     * `useId` and are dropped on unmount.
+     */
+    profileCardId?: string;
+    /**
+     * Presence badge on the avatar — overrides `user.presence`. Name the avatar
+     * with `avatarId` and `useUserAvatarActions(id).setPresence()` can flip it
+     * from a socket handler instead.
+     */
+    presence?: ProfileCardUser["presence"];
+    avatarId?: string;
     /**
      * Emit cuelume press/release on the card and play the open/close cues.
      * Inert unless the app opts into interaction sound via `bindSounds()`.
@@ -78,5 +68,4 @@ export interface ProfileCardBlockProps {
  * popup is a plain action menu. `items` is the whole menu — a flat list of
  * actions, separators and labels — defaulting to `defaultProfileCardItems`.
  */
-export declare function ProfileCardBlock({ user, items, align, side, sideOffset, menuWidth, open, defaultOpen, onOpenChange, sound, onError, className, }: ProfileCardBlockProps): React.ReactElement;
-export {};
+export declare function ProfileCardBlock({ user, items, align, side, sideOffset, menuWidth, variant: variantProp, defaultVariant, onVariantChange, profileCardId, presence, avatarId, open, defaultOpen, onOpenChange, sound, onError, className, }: ProfileCardBlockProps): React.ReactElement;

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

@@ -0,0 +1,80 @@
+import { UserPresence } from '../../user-avatar';
+import type * as React from "react";
+/** The identity shown on the card. */
+export interface ProfileCardUser {
+    name: string;
+    /** Secondary line under the name — a handle, an email, a role. */
+    username?: string;
+    /** Avatar image URL. Falls back to the initials when absent or broken. */
+    avatar?: string;
+    /** Fallback initials. Derived from `name` when omitted. */
+    initials?: string;
+    /** Presence badge on the avatar. Omitted, no badge. */
+    presence?: UserPresence;
+}
+/** An actionable row of the menu. */
+export interface ProfileCardAction {
+    type?: "item";
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    /** Right-aligned hint, e.g. "⌘K". Purely decorative — bind the key yourself. */
+    shortcut?: string;
+    disabled?: boolean;
+    variant?: "default" | "destructive";
+    /** Returning a promise puts the card in its loading state until it settles. */
+    onSelect?: () => void | Promise<void>;
+}
+/** A heading over the rows that follow it, up to the next separator. */
+export interface ProfileCardLabel {
+    type: "label";
+    label: string;
+}
+/** A rule between two sections. */
+export interface ProfileCardSeparator {
+    type: "separator";
+}
+/**
+ * One entry of `items`. Authored flat; the block renders each run between
+ * separators as its own menu group so a label actually names its section.
+ */
+export type ProfileCardItem = ProfileCardAction | ProfileCardLabel | ProfileCardSeparator;
+/** `expanded` shows avatar, name and handle; `collapsed` folds to the avatar
+ * alone — for an icon-collapsed sidebar rail. */
+export type ProfileCardVariant = "expanded" | "collapsed";
+/** Key for one card's state in the store. Any stable string; `useProfileCard`
+ * generates one when the component does not name itself. */
+export type ProfileCardInstanceId = string;
+/** Everything the store knows about one card. */
+export interface ProfileCardState {
+    variant: ProfileCardVariant;
+    menuOpen: boolean;
+    /** Id of the action whose promise is in flight, `null` while idle. */
+    pendingActionId: string | null;
+    /** `pendingActionId !== null` — the trigger is disabled and shows a spinner. */
+    busy: boolean;
+}
+/** Write-only handles onto one card. Nothing here re-renders the caller. */
+export interface ProfileCardActions {
+    setVariant: (variant: ProfileCardVariant) => void;
+    toggleVariant: () => void;
+    /** Convenience over `setVariant`. */
+    collapse: () => void;
+    expand: () => void;
+    setMenuOpen: (open: boolean) => void;
+    openMenu: () => void;
+    closeMenu: () => void;
+    reset: () => void;
+}
+/** @internal Which fields the mounted component controls from props. The
+ * store must never overwrite a controlled value. */
+export interface ProfileCardConfig {
+    controlsVariant: boolean;
+    controlsMenuOpen: boolean;
+}
+/** @internal Latest option callbacks. Only write atoms read this, so it can
+ * be refreshed every commit without re-rendering anything. */
+export interface ProfileCardHandlers {
+    onVariantChange?: (variant: ProfileCardVariant) => void;
+    onError?: (error: unknown) => void;
+}

package/dist-lib/components/blocks/profile/use-profile-card-state.d.ts

@@ -0,0 +1,24 @@
+import { ProfileCardActions, ProfileCardInstanceId, ProfileCardState } from './type';
+/**
+ * Read the card registered under `profileCardId` from anywhere below
+ * `ExegiaProvider` — no props, no ref, no provider of its own.
+ *
+ * ```tsx
+ * const { variant, busy } = useProfileCardState("account")
+ * ```
+ *
+ * Returns the whole state object, so the caller re-renders on any change. A
+ * component that watches one field should subscribe to that atom instead:
+ * `useAtomValue(profileCardVariantAtom("account"))`.
+ */
+export declare function useProfileCardState(profileCardId: ProfileCardInstanceId): ProfileCardState;
+/**
+ * Write-only handles onto the card registered under `profileCardId`. Nothing
+ * here subscribes, so a rail toggle can fold the card without re-rendering
+ * when the card changes.
+ *
+ * ```tsx
+ * const { collapse, expand } = useProfileCardActions("account")
+ * ```
+ */
+export declare function useProfileCardActions(profileCardId: ProfileCardInstanceId): ProfileCardActions;

package/dist-lib/components/blocks/profile/use-profile-card.d.ts

@@ -0,0 +1,34 @@
+import { ProfileCardAction, ProfileCardInstanceId, ProfileCardVariant } from './type';
+export interface UseProfileCardOptions {
+    profileCardId?: ProfileCardInstanceId;
+    /** Controlled fold. `undefined` leaves the store (and `defaultVariant`) in charge. */
+    variant?: ProfileCardVariant;
+    defaultVariant?: ProfileCardVariant;
+    onVariantChange?: (variant: ProfileCardVariant) => void;
+    /** Controlled menu. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onError?: (error: unknown) => void;
+}
+export interface ProfileCardBinding {
+    profileCardId: ProfileCardInstanceId;
+    variant: ProfileCardVariant;
+    collapsed: boolean;
+    menuOpen: boolean;
+    busy: boolean;
+    /** Hand to the menu's `onOpenChange` (first argument). Stable. */
+    setMenuOpen: (open: boolean) => void;
+    /** Run an action: `onSelect`, promise → busy, rejection → `onError`. Stable. */
+    select: (action: ProfileCardAction) => void;
+}
+/**
+ * Binds one profile card to its slice of the store: projects the controlled
+ * `variant` / `open` props (one-way, with write gates so the store never
+ * overwrites a prop), publishes the latest handlers, and returns the values
+ * the component renders from.
+ *
+ * Unnamed cards key off `useId` and are dropped on unmount; a named
+ * `profileCardId` outlives its component, so a fold set from elsewhere
+ * (`useProfileCardActions(id).collapse()`) survives a route change.
+ */
+export declare function useProfileCard(options: UseProfileCardOptions): ProfileCardBinding;

package/dist-lib/components/blocks/shell/__tests__/shell-fit-atom.test.d.ts

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

package/dist-lib/components/blocks/shell/__tests__/shell-metrics.test.d.ts

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

package/dist-lib/components/blocks/shell/animated-panel-provider.d.ts

@@ -1,2 +1,2 @@
 import { AnimatedSidebarProviderProps } from './type';
-export declare function AnimatedPanelProvider({ children, open, defaultOpen, onOpenChange, openMobile, defaultOpenMobile, onOpenMobileChange, className, style, ...props }: AnimatedSidebarProviderProps): import("react").JSX.Element;
+export declare function AnimatedPanelProvider({ children, shellId, defaultPanelWidth, open, defaultOpen, onOpenChange, openMobile, defaultOpenMobile, onOpenMobileChange, onNarrowChange, className, style, ...props }: AnimatedSidebarProviderProps): import("react").JSX.Element;

package/dist-lib/components/blocks/shell/animated-panel.d.ts

@@ -1,2 +1,2 @@
 import { AnimatedSidebarProps } from './type';
-export declare function AnimatedPanel({ side, variant, collapsible, ariaLabel, children, className, panelClassName, style, ref, ...props }: AnimatedSidebarProps): import("react").JSX.Element;
+export declare function AnimatedPanel({ side, variant, collapsible, ariaLabel, children, className, panelClassName, style, ref, ...props }: AnimatedSidebarProps): import("react").JSX.Element | null;

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

@@ -1,21 +1,13 @@
 import { ShellLayout } from './shell-layout';
 export type * from './type';
+export * from './shell-metrics';
 export * from './use-shell-panels';
+export { useShellFit } from './use-shell-fit';
+export { useShellFitActions, useShellFitState } from './use-shell-fit-state';
+export { removeShellFitInstance, resetShellPanelWidthAtom, resizeShellPanelAtom, shellFitFitsAtom, shellFitMeasuredAtom, shellFitMetricsAtom, shellFitPanelBoundsAtom, shellFitPanelWidthAtom, shellFitRequestedWidthAtom, shellFitStateAtom, } from './shell-fit-atom';
 export * from './utils';
 export * from './animated-panel';
 export * from './animated-panel-inset';
 export * from './animated-panel-provider';
 export * from './animated-panel-trigger';
-export * from './animated-sidebar-header';
-export * from './animated-sidebar-content';
-export * from './animated-sidebar-footer';
-export * from './animated-sidebar-group';
-export * from './animated-sidebar-group-label';
-export * from './animated-sidebar-group-content';
-export * from './animated-sidebar-menu';
-export * from './animated-sidebar-menu-item';
-export * from './animated-sidebar-menu-sub';
-export * from './animated-sidebar-menu-sub-item';
-export * from './animated-sidebar-menu-sub-button';
-export * from './animated-sidebar-menu-button';
 export { ShellLayout as default };

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

@@ -0,0 +1,68 @@
+import { ShellMetrics } from './shell-metrics';
+import { ShellFitInstanceId, ShellFitPanelBounds, ShellFitSeed, ShellFitState } from './type';
+/**
+ * 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: ShellFitInstanceId) => AtomType) & {
+    remove: (id: ShellFitInstanceId) => void;
+};
+/** The shell's own measurement of its columns. `useShellFit` is the only
+ * writer; read `shellFitMeasuredAtom` to get it with the "no layout yet" case
+ * already resolved. */
+export declare const shellFitMetricsAtom: Family<import('jotai').PrimitiveAtom<ShellMetrics> & {
+    init: ShellMetrics;
+}>;
+/** The width the user dragged to, before clamping — null while the panel sits
+ * at `--panel-width`. Read `shellFitPanelWidthAtom` for the width the panel
+ * actually renders at: clamping on read is what lets a narrowing viewport
+ * pull the panel down without forgetting the width they asked for. */
+export declare const shellFitRequestedWidthAtom: Family<import('jotai').PrimitiveAtom<number | null> & {
+    init: number | null;
+}>;
+/** The metrics, or null when the shell has no layout to report — a server
+ * render, a `display: none` host, a test with no layout engine. A zero is not
+ * a width, and treating it as one would pin the panel to nothing. */
+export declare const shellFitMeasuredAtom: Family<import('jotai').Atom<ShellMetrics | null>>;
+/** Whether the shell can hold a secondary panel at all. */
+export declare const shellFitFitsAtom: Family<import('jotai').Atom<boolean>>;
+/** The range a resize may land in. */
+export declare const shellFitPanelBoundsAtom: Family<import('jotai').Atom<ShellFitPanelBounds>>;
+/** The width the secondary panel renders at, or null before the first
+ * measurement, where the caller falls back to `--panel-width`. */
+export declare const shellFitPanelWidthAtom: Family<import('jotai').Atom<number | null>>;
+/** The whole fit of one shell. This changes on every measurement, so a
+ * component that reads one field should subscribe to that field's atom
+ * instead: `useAtomValue(shellFitFitsAtom("app-shell"))`. */
+export declare const shellFitStateAtom: Family<import('jotai').Atom<ShellFitState>>;
+/** @internal The measurement's way in. Silent, and inert when the numbers did
+ * not move — a resize event that changes nothing must not re-render a shell. */
+export declare const measureShellFitAtom: Family<import('jotai').WritableAtom<null, [metrics: ShellMetrics], void> & {
+    init: null;
+}>;
+/** 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 —
+ * and a caller with no idea how wide the shell is can still ask for 900. */
+export declare const resizeShellPanelAtom: Family<import('jotai').WritableAtom<null, [width: number], void> & {
+    init: null;
+}>;
+/** Back to the width the shell mounted with — `defaultPanelWidth`, or
+ * `--panel-width` when there was none. */
+export declare const resetShellPanelWidthAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** @internal Seed the instance once. A seed describes the mount, not every
+ * render, so a `defaultPanelWidth` that arrives later never overwrites a
+ * width the user dragged to. */
+export declare const mountShellFitAtom: Family<import('jotai').WritableAtom<null, [seed: ShellFitSeed], void> & {
+    init: null;
+}>;
+/** Drop every atom for `id`. `useShellFit` calls this on unmount for shells it
+ * keyed itself; an explicit `shellId` is the app's key and outlives its
+ * component, so a resized panel survives a route change. */
+export declare function removeShellFitInstance(id: ShellFitInstanceId): void;
+export {};