@exegia/corpora-ui 0.19.0 → 0.21.0

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

@@ -17,7 +17,18 @@ export interface SidebarResourceMenuControls {
     close: () => void;
     rename: () => void;
 }
-export interface AISidebarProps {
+/** 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;
@@ -28,7 +39,86 @@ 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 {
+    /** 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[];
+    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;
+    /** 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;
+    hover: AISidebarHoverState;
+    onRowKeyDown: (event: KeyboardEvent<HTMLDivElement>, row: FlatResource) => void;
+    setRowRef: (id: string, node: HTMLDivElement | null) => void;
+}
+/** @internal */
+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;
+    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 +129,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;
@@ -48,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

@@ -1,31 +1,27 @@
-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 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>
+ * ```
+ *
+ * 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,8 +4,13 @@ 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[];
+/** 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/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 `SidebarBlock` 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;