@exegia/corpora-ui 0.19.0 → 0.20.0

package/src/components/composed/tree/use-tree.ts

@@ -0,0 +1,306 @@
+"use client"
+
+import * as React from "react"
+
+import { playCue } from "@/lib/sound"
+import type { TreeController, TreeNode, UseTreeOptions } from "./type"
+import { useTreeDnd } from "./use-tree-dnd"
+import {
+  ancestorIdsOf,
+  expandableIdsOf,
+  findNode,
+  hasThreeLevels,
+  initialExpandedIds,
+  moveNode,
+  renameNode,
+} from "./utils"
+
+/**
+ * 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 function useTree(options: UseTreeOptions): TreeController {
+  const {
+    variant,
+    onNavigate,
+    onRename,
+    onMove,
+    onItemsChange,
+    onExpandedChange,
+    onCollapsedChange,
+    sound = true,
+  } = options
+
+  // Data: controlled through `items`, otherwise owned here.
+  const [ownItems, setOwnItems] = React.useState<TreeNode[]>(
+    () => options.defaultItems ?? []
+  )
+  const items = options.items ?? ownItems
+  // The hook may only rewrite the data when it owns it, or when the
+  // consumer asked for the next tree through `onItemsChange`.
+  const managesItems =
+    options.items === undefined || onItemsChange !== undefined
+
+  const setItems = React.useCallback(
+    (next: TreeNode[]) => {
+      if (options.items === undefined) setOwnItems(next)
+      onItemsChange?.(next)
+    },
+    [options.items, onItemsChange]
+  )
+
+  const sectioned = variant === "navigation" && hasThreeLevels(items)
+
+  // Selection: controlled through `activeId`, otherwise owned here.
+  const [ownActiveId, setOwnActiveId] = React.useState(options.defaultActiveId)
+  const activeId = options.activeId ?? ownActiveId
+
+  const [expandedIds, setExpandedIds] = React.useState<Set<string>>(() => {
+    const expanded = options.defaultExpandedIds
+      ? new Set(options.defaultExpandedIds)
+      : initialExpandedIds(items, activeId)
+    // Section names default open — they are headings over their run of
+    // items, not drawers; `defaultOpen: false` still starts one closed.
+    if (sectioned && !options.defaultExpandedIds)
+      for (const node of items)
+        if (node.defaultOpen !== false) expanded.add(node.id)
+    return expanded
+  })
+
+  const commitExpanded = React.useCallback(
+    (next: Set<string>) => {
+      setExpandedIds(next)
+      onExpandedChange?.([...next])
+    },
+    [onExpandedChange]
+  )
+
+  // Navigating into a nested entry from elsewhere reveals its ancestors,
+  // even ones the reader had collapsed. Adjusted during render so the
+  // branch never paints closed for a frame first.
+  const [prevActiveId, setPrevActiveId] = React.useState(activeId)
+  if (activeId !== prevActiveId) {
+    setPrevActiveId(activeId)
+    if (activeId !== undefined) {
+      const ancestors = ancestorIdsOf(items, activeId)
+      if (ancestors.some((id) => !expandedIds.has(id)))
+        setExpandedIds(new Set([...expandedIds, ...ancestors]))
+    }
+  }
+
+  // Rail fold: controlled through `collapsed`, otherwise owned here. Only
+  // `sidebar` has a rail — every other variant reads as expanded.
+  const [ownCollapsed, setOwnCollapsed] = React.useState(
+    options.defaultCollapsed ?? false
+  )
+  const collapsed =
+    variant === "sidebar" ? (options.collapsed ?? ownCollapsed) : false
+
+  const [renamingId, setRenamingId] = React.useState<string | null>(null)
+
+  const canRename =
+    variant === "files" && (onRename !== undefined || managesItems)
+  const canMove = variant === "files" && (onMove !== undefined || managesItems)
+
+  const isExpanded = React.useCallback(
+    (id: string) => expandedIds.has(id),
+    [expandedIds]
+  )
+
+  const expand = React.useCallback(
+    (id: string) => {
+      if (expandedIds.has(id)) return
+      commitExpanded(new Set([...expandedIds, id]))
+      if (sound) playCue("toggle")
+    },
+    [commitExpanded, expandedIds, sound]
+  )
+
+  const collapse = React.useCallback(
+    (id: string) => {
+      if (!expandedIds.has(id)) return
+      const next = new Set(expandedIds)
+      next.delete(id)
+      commitExpanded(next)
+      if (sound) playCue("toggle")
+    },
+    [commitExpanded, expandedIds, sound]
+  )
+
+  const toggleExpanded = React.useCallback(
+    (id: string) => {
+      const next = new Set(expandedIds)
+      if (next.has(id)) next.delete(id)
+      else next.add(id)
+      commitExpanded(next)
+      if (sound) playCue("toggle")
+    },
+    [commitExpanded, expandedIds, sound]
+  )
+
+  const expandAll = React.useCallback(() => {
+    commitExpanded(new Set(expandableIdsOf(items, variant === "files")))
+  }, [commitExpanded, items, variant])
+
+  const collapseAll = React.useCallback(() => {
+    commitExpanded(new Set())
+  }, [commitExpanded])
+
+  /** Open every ancestor of `id` without touching the rest of the tree. */
+  const reveal = React.useCallback(
+    (id: string) => {
+      const ancestors = ancestorIdsOf(items, id)
+      if (!ancestors.some((ancestor) => !expandedIds.has(ancestor))) return
+      commitExpanded(new Set([...expandedIds, ...ancestors]))
+    },
+    [commitExpanded, expandedIds, items]
+  )
+
+  const setCollapsed = React.useCallback(
+    (next: boolean) => {
+      if (options.collapsed === undefined) setOwnCollapsed(next)
+      onCollapsedChange?.(next)
+      if (sound) playCue("toggle")
+    },
+    [options.collapsed, onCollapsedChange, sound]
+  )
+
+  const toggleCollapsed = React.useCallback(
+    () => setCollapsed(!collapsed),
+    [collapsed, setCollapsed]
+  )
+
+  const getNode = React.useCallback(
+    (id: string) => findNode(items, id),
+    [items]
+  )
+
+  /** Selecting runs the node's own `onSelect` first, then `onNavigate` —
+   * the same order a row press follows. Disabled nodes are inert. */
+  const select = React.useCallback(
+    (id: string) => {
+      const node = findNode(items, id)
+      if (!node || node.disabled) return
+      if (options.activeId === undefined) setOwnActiveId(id)
+      node.onSelect?.()
+      onNavigate?.(node)
+    },
+    [items, options.activeId, onNavigate]
+  )
+
+  const startRename = React.useCallback(
+    (id: string) => {
+      // An id from elsewhere (a stale selection, another tree) would arm
+      // rename mode against a row that never renders.
+      if (!canRename || !findNode(items, id)) return
+      setRenamingId(id)
+    },
+    [canRename, items]
+  )
+
+  const cancelRename = React.useCallback(() => setRenamingId(null), [])
+
+  const rename = React.useCallback(
+    (id: string, label: string) => {
+      setRenamingId(null)
+      const next = label.trim()
+      if (!canRename || !next) return
+      const node = findNode(items, id)
+      if (!node || node.label === next) return
+      onRename?.(id, next)
+      if (managesItems) setItems(renameNode(items, id, next))
+    },
+    [canRename, items, managesItems, onRename, setItems]
+  )
+
+  const move = React.useCallback(
+    (id: string, parentId: string | null, index: number) => {
+      if (!canMove) return
+      onMove?.(id, parentId, index)
+      if (managesItems) setItems(moveNode(items, id, parentId, index))
+    },
+    [canMove, items, managesItems, onMove, setItems]
+  )
+
+  const dnd = useTreeDnd(items, canMove ? move : undefined)
+
+  const sectionIds = React.useMemo(
+    () => (sectioned ? items.map((node) => node.id) : []),
+    [items, sectioned]
+  )
+
+  return React.useMemo<TreeController>(
+    () => ({
+      variant,
+      items,
+      sectioned,
+      sectionIds,
+      sound,
+      getNode,
+      expandedIds,
+      isExpanded,
+      expand,
+      collapse,
+      toggleExpanded,
+      expandAll,
+      collapseAll,
+      reveal,
+      collapsed,
+      setCollapsed,
+      toggleCollapsed,
+      activeId,
+      select,
+      canRename,
+      renamingId,
+      startRename,
+      cancelRename,
+      rename,
+      canMove,
+      move,
+      dnd,
+    }),
+    [
+      variant,
+      items,
+      sectioned,
+      sectionIds,
+      sound,
+      getNode,
+      expandedIds,
+      isExpanded,
+      expand,
+      collapse,
+      toggleExpanded,
+      expandAll,
+      collapseAll,
+      reveal,
+      collapsed,
+      setCollapsed,
+      toggleCollapsed,
+      activeId,
+      select,
+      canRename,
+      renamingId,
+      startRename,
+      cancelRename,
+      rename,
+      canMove,
+      move,
+      dnd,
+    ]
+  )
+}

package/src/components/composed/tree/utils.ts

@@ -0,0 +1,172 @@
+import type { 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 function hasThreeLevels(items: readonly TreeNode[]): boolean {
+  return items.some((node) =>
+    node.children?.some((child) => (child.children?.length ?? 0) > 0)
+  )
+}
+
+/** Ids of every ancestor of `id` (nearest last); empty when absent. */
+export function ancestorIdsOf(
+  items: readonly TreeNode[],
+  id: string
+): string[] {
+  const walk = (nodes: readonly TreeNode[], trail: string[]): string[] | null => {
+    for (const node of nodes) {
+      if (node.id === id) return trail
+      if (node.children) {
+        const found = walk(node.children, [...trail, node.id])
+        if (found) return found
+      }
+    }
+    return null
+  }
+  return walk(items, []) ?? []
+}
+
+/** Ids that start expanded: `defaultOpen` nodes plus every ancestor of the
+ * active entry, so the current location is never folded away. */
+export function initialExpandedIds(
+  items: readonly TreeNode[],
+  activeId?: string
+): Set<string> {
+  const expanded = new Set<string>()
+  const walk = (nodes: readonly TreeNode[]) => {
+    for (const node of nodes) {
+      if (node.defaultOpen) expanded.add(node.id)
+      if (node.children) walk(node.children)
+    }
+  }
+  walk(items)
+  if (activeId !== undefined)
+    for (const id of ancestorIdsOf(items, activeId)) expanded.add(id)
+  return expanded
+}
+
+/** Ids of every node that can hold children — the set `expandAll` opens.
+ * In `files` an empty `children: []` still counts (it is a folder). */
+export function expandableIdsOf(
+  items: readonly TreeNode[],
+  filesVariant = false
+): string[] {
+  const ids: string[] = []
+  const walk = (nodes: readonly TreeNode[]) => {
+    for (const node of nodes) {
+      const branch = filesVariant
+        ? node.children !== undefined
+        : (node.children?.length ?? 0) > 0
+      if (branch) ids.push(node.id)
+      if (node.children) walk(node.children)
+    }
+  }
+  walk(items)
+  return ids
+}
+
+/** Immutably relabel `id`. Returns the same array reference when absent. */
+export function renameNode(
+  items: readonly TreeNode[],
+  id: string,
+  label: string
+): TreeNode[] {
+  return items.map((node) => {
+    if (node.id === id) return { ...node, label }
+    return node.children
+      ? { ...node, children: renameNode(node.children, id, label) }
+      : node
+  })
+}
+
+/** Whether `candidateId` is `id` itself or nests anywhere under it — the
+ * guard that keeps a folder from being dropped into its own subtree. */
+export function containsNode(
+  items: readonly TreeNode[],
+  id: string,
+  candidateId: string
+): boolean {
+  if (id === candidateId) return true
+  const root = findNode(items, id)
+  if (!root?.children) return false
+  return findNode(root.children, candidateId) !== null
+}
+
+export function findNode(
+  items: readonly TreeNode[],
+  id: string
+): TreeNode | null {
+  for (const node of items) {
+    if (node.id === id) return node
+    if (node.children) {
+      const found = findNode(node.children, id)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+/** Parent id (`null` at root) and index of `id` among its siblings. */
+export function locateNode(
+  items: readonly TreeNode[],
+  id: string
+): { parentId: string | null; index: number } | null {
+  const walk = (
+    nodes: readonly TreeNode[],
+    parentId: string | null
+  ): { parentId: string | null; index: number } | null => {
+    for (const [index, node] of nodes.entries()) {
+      if (node.id === id) return { parentId, index }
+      if (node.children) {
+        const found = walk(node.children, node.id)
+        if (found) return found
+      }
+    }
+    return null
+  }
+  return walk(items, 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 function moveNode(
+  items: readonly TreeNode[],
+  id: string,
+  parentId: string | null,
+  index: number
+): TreeNode[] {
+  // Dropping into the node's own subtree would orphan it — refuse.
+  if (parentId !== null && containsNode(items, id, parentId)) return [...items]
+  let moved: TreeNode | null = null
+  const strip = (nodes: readonly TreeNode[]): TreeNode[] =>
+    nodes.flatMap((node) => {
+      if (node.id === id) {
+        moved = node
+        return []
+      }
+      return node.children
+        ? [{ ...node, children: strip(node.children) }]
+        : [node]
+    })
+  const stripped = strip(items)
+  if (!moved) return [...items]
+  const captured = moved as TreeNode
+
+  if (parentId === null) {
+    const next = [...stripped]
+    next.splice(Math.min(index, next.length), 0, captured)
+    return next
+  }
+  const insert = (nodes: readonly TreeNode[]): TreeNode[] =>
+    nodes.map((node) => {
+      if (node.id === parentId) {
+        const children = [...(node.children ?? [])]
+        children.splice(Math.min(index, children.length), 0, captured)
+        return { ...node, children }
+      }
+      return node.children ? { ...node, children: insert(node.children) } : node
+    })
+  return insert(stripped)
+}

package/src/components/composed/user-avatar.tsx

@@ -69,7 +69,10 @@ export function UserAvatar({
 
   return (
     <Avatar
-      className={cn("size-8", className)}
+      className={cn(
+        "size-8 border-2 border-white bg-neutral-800 text-xl",
+        className
+      )}
       data-loading={loading || undefined}
       data-slot="user-avatar"
       {...props}

package/src/components/docs/component-preview.tsx

@@ -12,18 +12,18 @@ export function ComponentPreview({ entry }: { entry: RegistryEntry }) {
   const Demo = entry.preview
 
   return (
-    <BrowserFrame title={entry.name} titleStyle="hidden">
+    <BrowserFrame title={entry.name} titleStyle="hidden" className="min-h-60">
       {Demo ? (
-          <React.Suspense
-            fallback={<p className="text-sm text-muted-foreground">Loading…</p>}
-          >
-            <Demo />
-          </React.Suspense>
-        ) : (
-          <p className="text-sm text-muted-foreground">
-            Preview coming soon ({entry.status}).
-          </p>
-        )}
+        <React.Suspense
+          fallback={<p className="text-sm text-muted-foreground">Loading…</p>}
+        >
+          <Demo />
+        </React.Suspense>
+      ) : (
+        <p className="text-sm text-muted-foreground">
+          Preview coming soon ({entry.status}).
+        </p>
+      )}
     </BrowserFrame>
   )
 }

package/src/components/user-avatar/audio-wave.tsx

@@ -0,0 +1,22 @@
+import { cn } from "@/lib/utils"
+import type { IAudioWaveProps } from "./type"
+
+// `volume` is accepted but not yet wired to the ring animation.
+export function AudioWave({ className, volume: _volume, children }: IAudioWaveProps) {
+  return (
+    <div
+      className={cn(
+        "group/avatar relative flex items-center justify-center",
+        className
+      )}
+    >
+      {/* Animated Story Ring */}
+      <div className="absolute -inset-1 animate-[spin_3s_linear_infinite] rounded-full bg-linear-to-tr from-yellow-400 via-fuchsia-500 to-violet-600 opacity-75 blur-xs transition-all duration-500 group-hover/avatar:opacity-100 group-hover/avatar:blur-sm" />
+
+      {/* Main Avatar */}
+      <div className="size-10 ring-2 ring-background transition-transform duration-500 group-hover/avatar:scale-95">
+        {children}
+      </div>
+    </div>
+  )
+}

package/src/components/user-avatar/component.tsx

@@ -0,0 +1,53 @@
+"use client"
+
+import * as React from "react"
+
+import { Avatar, AvatarImage } from "@/components/ui/avatar"
+import { cn } from "@/lib/utils"
+import { Fallback } from "./fallback"
+import type { ImageStatus, UserAvatarProps } from "./type"
+
+/**
+ * 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 function UserAvatar({
+  src,
+  name = "",
+  initials,
+  alt,
+  loading: loadingProp,
+  className,
+  ...props
+}: UserAvatarProps): React.ReactElement {
+  const [status, setStatus] = React.useState<ImageStatus>("idle")
+  const loading =
+    loadingProp ??
+    (src !== undefined && (status === "idle" || status === "loading"))
+
+  return (
+    <Avatar
+      className={cn(
+        "size-8 border-2 border-white bg-neutral-800 text-xl",
+        className
+      )}
+      data-loading={loading || undefined}
+      data-slot="user-avatar"
+      {...props}
+    >
+      {/* Held back while forced-loading: a loaded image would hide the
+          fallback the skeleton lives in. */}
+      {src === undefined || loadingProp === true ? null : (
+        <AvatarImage
+          alt={alt ?? name}
+          onLoadingStatusChange={setStatus}
+          src={src}
+        />
+      )}
+      <Fallback name={name} initials={initials} loading={loading} />
+    </Avatar>
+  )
+}

package/src/components/user-avatar/fallback.tsx

@@ -0,0 +1,26 @@
+import { AvatarFallback } from "@/components/ui/avatar"
+import { Skeleton } from "@/components/ui/skeleton"
+import { initialsFrom } from "./utils"
+
+export function Fallback({
+  name,
+  initials,
+  loading,
+}: {
+  name?: string
+  initials?: string
+  loading?: boolean
+}) {
+  return (
+    <AvatarFallback>
+      {loading ? (
+        <Skeleton
+          className="size-full rounded-full"
+          data-slot="avatar-skeleton"
+        />
+      ) : (
+        (initials ?? initialsFrom(name ?? ""))
+      )}
+    </AvatarFallback>
+  )
+}

package/src/components/user-avatar/index.ts

@@ -0,0 +1,15 @@
+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 const Avatar = {
+  AudioWave,
+  Component: UserAvatar,
+  Fallback,
+}

package/src/components/user-avatar/type.ts

@@ -0,0 +1,35 @@
+import type * as React from "react"
+
+import type { AvatarPrimitive } from "@/components/ui/avatar"
+
+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/src/components/user-avatar/utils.ts

@@ -0,0 +1,8 @@
+/** "Jenny Hamilton" → "JH", "luna" → "L". */
+export function initialsFrom(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return ""
+  const first = parts[0]?.[0] ?? ""
+  const last = parts.length > 1 ? (parts.at(-1)?.[0] ?? "") : ""
+  return (first + last).toUpperCase()
+}