@exegia/corpora-ui 0.18.0 → 0.20.0

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

@@ -0,0 +1,192 @@
+import type * as React from "react";
+/** One node in the tree. Nesting depth carries meaning per variant — see
+ * `TreeProps["variant"]`. */
+export interface TreeNode {
+    id: string;
+    label: string;
+    /** Leading icon. Required in practice for `sidebar` — it is all that
+     * remains of a row while the rail is collapsed. */
+    icon?: React.ReactNode;
+    /** Renders an anchor. Without one the row is a button; `toc` leaves
+     * default to `#{id}` so they scroll to the matching heading. */
+    href?: string;
+    target?: "_blank" | "_self" | "_parent" | "_top";
+    disabled?: boolean;
+    /** Start expanded. Ancestors of `activeId` expand regardless. */
+    defaultOpen?: boolean;
+    /** Trailing hint — a count, a "New" pill. */
+    badge?: React.ReactNode;
+    /** Fires on selection, before the tree-level `onNavigate`. */
+    onSelect?: () => void;
+    children?: TreeNode[];
+}
+export type TreeVariant = "navigation" | "toc" | "sidebar" | "files";
+/** Where a dragged row lands relative to its drop target. */
+export type TreeDropPosition = "before" | "after" | "inside";
+interface TreeBaseProps {
+    items: TreeNode[];
+    /** Never set on the data form — `tree` selects the controller form. */
+    tree?: never;
+    /** `id` of the current entry — matches any depth. Its ancestors expand. */
+    activeId?: string;
+    /** Fires for every selection (rows and leaves alike), after the row's
+     * anchor default — wire your router's navigate here. */
+    onNavigate?: (node: TreeNode) => void;
+    /** Expand/collapse cues. Silent until `bindSounds()`. */
+    sound?: boolean;
+    ariaLabel?: string;
+    className?: string;
+}
+interface TreeReadonlyProps {
+    collapsed?: never;
+    onMove?: never;
+    onRename?: never;
+    renderTrailing?: never;
+}
+/** Drive the tree from a `useTree` controller instead of raw props. The
+ * controller carries the variant, the data and every handler; only the
+ * presentational props stay here. */
+export interface TreeControllerProps {
+    tree: TreeController;
+    items?: never;
+    ariaLabel?: string;
+    className?: string;
+    /** Row actions revealed on hover/focus (`files` only — ignored by the
+     * other variants, which the controller form cannot type-gate). */
+    renderTrailing?: (node: TreeNode) => React.ReactNode;
+}
+/** Either form: raw props, or a `useTree` controller via `tree`. */
+export type TreeProps = TreeDataProps | TreeControllerProps;
+/** The four shapes a Tree takes. Editing props only exist on `files`;
+ * `collapsed` only on `sidebar` — the union is the contract. */
+export type TreeDataProps = TreeBaseProps & (({
+    /** Nested app navigation. With 3 levels of nodes the top level
+     * becomes collapsible section names (styled as headings, not
+     * links); with 2 it renders plain link rows. */
+    variant: "navigation";
+} & TreeReadonlyProps) | ({
+    /** Table of contents: top-level nodes are routes, leaf nodes are
+     * in-page anchors (`#{id}` unless the node carries an `href`). */
+    variant: "toc";
+} & TreeReadonlyProps) | ({
+    /** Single-level icon rail. `collapsed` shrinks rows to their
+     * leading icon; nested children are ignored. */
+    variant: "sidebar";
+    collapsed?: boolean;
+} & Omit<TreeReadonlyProps, "collapsed">) | {
+    /** File explorer: only leaves navigate, folders toggle. Compact
+     * spacing; rename, drag-and-drop and trailing actions enabled. */
+    variant: "files";
+    /** Enables drag-and-drop. Reorder `items` yourself: `parentId`
+     * `null` means the root list, `index` is the slot among the new
+     * siblings (computed on the list without the dragged node). */
+    onMove?: (id: string, parentId: string | null, index: number) => void;
+    /** Enables inline rename (double-click or F2). */
+    onRename?: (id: string, label: string) => void;
+    /** Row actions revealed on hover/focus — a menu, a delete icon. */
+    renderTrailing?: (node: TreeNode) => React.ReactNode;
+    collapsed?: never;
+});
+/** Options for `useTree`. Each of `items`, `activeId` and `collapsed` is
+ * controlled when passed and hook-owned when its `default*` twin is used
+ * instead. */
+export interface UseTreeOptions {
+    /** Which shape the tree takes — gates rename/reorder (`files`) and the
+     * collapsible rail (`sidebar`). */
+    variant: TreeVariant;
+    /** Controlled data. With it, `rename`/`move` only report the edit unless
+     * you also pass `onItemsChange`. */
+    items?: TreeNode[];
+    /** Hook-owned data — `rename` and `move` apply the edit themselves. */
+    defaultItems?: TreeNode[];
+    /** Next tree after a `rename`/`move`. Also enables self-applying edits
+     * on top of controlled `items`. */
+    onItemsChange?: (items: TreeNode[]) => void;
+    /** Controlled selection. Ancestors of the active node expand. */
+    activeId?: string;
+    defaultActiveId?: string;
+    /** Fires for every selection (rows and leaves alike), after the node's
+     * own `onSelect` — wire your router's navigate here. */
+    onNavigate?: (node: TreeNode) => void;
+    /** Start with these ids expanded instead of the `defaultOpen` set. */
+    defaultExpandedIds?: Iterable<string>;
+    onExpandedChange?: (ids: string[]) => void;
+    /** Controlled rail fold (`sidebar` only). */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Enables rename (`files`). Not needed when the hook owns the data. */
+    onRename?: (id: string, label: string) => void;
+    /** Enables drag-and-drop (`files`). `parentId` `null` means the root
+     * list, `index` is the slot among the new siblings (computed on the list
+     * without the moved node). Not needed when the hook owns the data. */
+    onMove?: (id: string, parentId: string | null, index: number) => void;
+    /** Expand/collapse cues. Silent until `bindSounds()`. */
+    sound?: boolean;
+}
+/** Everything the tree can do, callable from outside the component.
+ * Returned by `useTree` and accepted by `<Tree tree={…} />`. */
+export interface TreeController {
+    variant: TreeVariant;
+    items: TreeNode[];
+    /** `navigation` with 3 levels of nodes — depth 0 renders as sections. */
+    sectioned: boolean;
+    /** Ids of the section headings, empty unless `sectioned`. Pass one to
+     * `expand`/`collapse`/`toggleExpanded` to work a whole section. */
+    sectionIds: string[];
+    sound: boolean;
+    getNode: (id: string) => TreeNode | null;
+    expandedIds: ReadonlySet<string>;
+    isExpanded: (id: string) => boolean;
+    expand: (id: string) => void;
+    collapse: (id: string) => void;
+    toggleExpanded: (id: string) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    /** Open every ancestor of `id`, leaving the rest of the tree alone. */
+    reveal: (id: string) => void;
+    /** Rail folded to icons — always `false` outside `sidebar`. */
+    collapsed: boolean;
+    setCollapsed: (collapsed: boolean) => void;
+    toggleCollapsed: () => void;
+    activeId?: string;
+    /** Select a node: runs its `onSelect`, then `onNavigate`. Inert on
+     * disabled and unknown nodes. */
+    select: (id: string) => void;
+    /** Whether rename is wired up at all (`files` + a handler or owned data). */
+    canRename: boolean;
+    /** Rename target id, `null` while idle. */
+    renamingId: string | null;
+    startRename: (id: string) => void;
+    cancelRename: () => void;
+    /** Commit a rename and leave rename mode. Blank or unchanged labels are
+     * dropped. */
+    rename: (id: string, label: string) => void;
+    /** Whether reorder is wired up at all. */
+    canMove: boolean;
+    move: (id: string, parentId: string | null, index: number) => void;
+    dnd: TreeDndContextValue;
+}
+/** @internal What a row needs from the root, threaded through context so
+ * the recursive rows stay prop-light. */
+export interface TreeContextValue {
+    tree: TreeController;
+    renderTrailing?: (node: TreeNode) => React.ReactNode;
+}
+/** @internal Drag state shared by every row (all `null`/no-op outside
+ * `files`). */
+export interface TreeDndContextValue {
+    enabled: boolean;
+    draggedId: string | null;
+    /** Row the pointer is over and where the drop would land. */
+    dropTarget: {
+        id: string;
+        position: TreeDropPosition;
+    } | null;
+    onRowDragStart: (event: React.DragEvent, id: string) => void;
+    onRowDragOver: (event: React.DragEvent, node: TreeNode) => void;
+    onRowDragLeave: (event: React.DragEvent) => void;
+    onRowDrop: (event: React.DragEvent, node: TreeNode) => void;
+    onRowDragEnd: () => void;
+}
+export {};

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

@@ -0,0 +1,7 @@
+import { TreeDndContextValue, TreeNode, UseTreeOptions } from './type';
+/** Owns drag state for the `files` variant: which row is in flight, which
+ * row the pointer rests on and where the drop would land. Everything is
+ * component state — `dataTransfer` is set for interop but never read, so
+ * the flow also works where the store is unavailable (tests, some
+ * webviews). Without `onMove` every handler is inert. */
+export declare function useTreeDnd(items: readonly TreeNode[], onMove: UseTreeOptions["onMove"]): TreeDndContextValue;

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

@@ -0,0 +1,20 @@
+import { TreeController, UseTreeOptions } from './type';
+/**
+ * The tree's headless controller — every behaviour the component exposes,
+ * callable from outside it: expand/collapse (a node, a section, the whole
+ * tree), fold the `sidebar` rail, select a node, rename, reorder.
+ *
+ * Each piece of state is controlled-or-uncontrolled in the usual React
+ * shape: pass `items`/`activeId`/`collapsed` to own it yourself, or
+ * `defaultItems`/`defaultActiveId`/`defaultCollapsed` to let the hook. When
+ * the hook owns `items` (or you pass `onItemsChange`), `rename` and `move`
+ * apply the edit to the data themselves — otherwise they only report it
+ * through `onRename`/`onMove` and you reduce the tree yourself.
+ *
+ * ```tsx
+ * const tree = useTree({ variant: "files", defaultItems: files })
+ * <Tree tree={tree} />
+ * <Button onClick={tree.collapseAll}>Collapse all</Button>
+ * ```
+ */
+export declare function useTree(options: UseTreeOptions): TreeController;

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

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

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

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

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

@@ -0,0 +1,10 @@
+import { UserAvatarProps } from './type';
+import * as React from "react";
+/**
+ * Identity avatar: an image when one is given, initials otherwise.
+ *
+ * A passed `src` is assumed to be remote, so the slot holds a skeleton until
+ * the image resolves rather than flashing initials that are about to be
+ * replaced. A failed load settles on the initials.
+ */
+export declare function UserAvatar({ src, name, initials, alt, loading: loadingProp, className, ...props }: UserAvatarProps): React.ReactElement;

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

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

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

@@ -0,0 +1,13 @@
+import { AudioWave } from './audio-wave';
+import { UserAvatar } from './component';
+import { Fallback } from './fallback';
+export { AudioWave } from './audio-wave';
+export { UserAvatar } from './component';
+export { Fallback } from './fallback';
+export { initialsFrom } from './utils';
+export type * from './type';
+export declare const Avatar: {
+    AudioWave: typeof AudioWave;
+    Component: typeof UserAvatar;
+    Fallback: typeof Fallback;
+};

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

@@ -0,0 +1,26 @@
+import { AvatarPrimitive } from '../ui/avatar';
+import type * as React from "react";
+export type ImageStatus = Parameters<NonNullable<AvatarPrimitive.Image.Props["onLoadingStatusChange"]>>[0];
+export interface UserAvatarProps extends Omit<AvatarPrimitive.Root.Props, "children"> {
+    /** Image URL. Without one the initials show immediately — no skeleton. */
+    src?: string;
+    /** Drives the initials, and the alt text unless `alt` overrides it. */
+    name?: string;
+    /** Overrides the initials derived from `name`. */
+    initials?: string;
+    /**
+     * Alt text for the image. Pass "" when adjacent text already names the
+     * person — the image is then decorative.
+     */
+    alt?: string;
+    /**
+     * Force the skeleton, for when the identity itself is still being fetched.
+     * Omitted, it follows the image: a passed `src` skeletons until it resolves.
+     */
+    loading?: boolean;
+}
+export interface IAudioWaveProps {
+    className?: string;
+    children?: React.ReactNode;
+    volume?: number;
+}

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

@@ -0,0 +1,2 @@
+/** "Jenny Hamilton" → "JH", "luna" → "L". */
+export declare function initialsFrom(name: string): string;

package/dist-lib/index.d.ts

@@ -22,6 +22,7 @@ export * from './components/ui/spinner';
 export * from './components/ui/textarea';
 export * from './components/composed/password-input';
 export * from './components/composed/social-providers';
+export * from './components/composed/tree';
 export * from './components/composed/user-avatar';
 export * from './components/blocks/auth/auth-shell';
 export * from './components/blocks/auth/code-auth-block';