@exegia/corpora-ui 0.19.0 → 0.21.0

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

@@ -1,98 +1,13 @@
-"use client"
-
-import * as React from "react"
-
-import {
-  Avatar,
-  AvatarFallback,
-  AvatarImage,
-  type AvatarPrimitive,
-} from "@/components/ui/avatar"
-import { Skeleton } from "@/components/ui/skeleton"
-import { cn } from "@/lib/utils"
-
-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
-}
-
-/** "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()
-}
-
 /**
- * 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.
+ * Back-compat path. The avatar moved to `components/user-avatar/` (split
+ * into component / atoms / hooks); this module re-exports it so existing
+ * imports keep resolving to the one implementation. Prefer the new path.
  */
-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", 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}
-        />
-      )}
-      <AvatarFallback>
-        {loading ? (
-          <Skeleton
-            className="size-full rounded-full"
-            data-slot="avatar-skeleton"
-          />
-        ) : (
-          (initials ?? initialsFrom(name))
-        )}
-      </AvatarFallback>
-    </Avatar>
-  )
-}
+export {
+  UserAvatar,
+  initialsFrom,
+  useUserAvatar,
+  useUserAvatarActions,
+  useUserAvatarState,
+} from "@/components/user-avatar"
+export type { UserAvatarProps, UserPresence } from "@/components/user-avatar"

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/__tests__/user-avatar.test.tsx

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test"
+import { act, fireEvent, render, screen } from "@testing-library/react"
+import { createStore, Provider } from "jotai"
+
+import { UserAvatar } from "../component"
+import {
+  DEFAULT_BEZEL_ANGLE,
+  removeUserAvatarInstance,
+  resetUserAvatarAtom,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarPresenceAtom,
+  toggleUserAvatarPresenceAtom,
+  userAvatarBezelAngleAtom,
+  userAvatarIsOnlineAtom,
+  userAvatarPresenceAtom,
+  userAvatarStateAtom,
+} from "../user-avatar-atom"
+import { useUserAvatarActions, useUserAvatarState } from "../use-user-avatar-state"
+import type { UserAvatarActions, UserAvatarState } from "../type"
+
+const badge = () => document.querySelector('[data-slot="user-avatar-presence"]')
+const bezel = () => document.querySelector('[data-slot="user-avatar-bezel"]')
+const frame = () =>
+  document.querySelector<HTMLElement>('[data-slot="user-avatar-frame"]')
+/** The rim's rotation, parsed. The component damps the stored bearing
+ * (`bezelAngle * 0.8`) so the highlight trails the pointer slightly. */
+const BEZEL_DAMPING = 0.8
+const rimRotation = () => {
+  const match = /rotate\((-?[\d.]+)deg\)/.exec(bezel()?.getAttribute("style") ?? "")
+  return match ? Number(match[1]) : Number.NaN
+}
+
+describe("UserAvatar · presence badge", () => {
+  test("no presence, no badge", () => {
+    render(<UserAvatar name="Jenny Hamilton" />)
+    expect(badge()).toBeNull()
+  })
+
+  test("online is a filled dot named for AT; offline a hollow ring", () => {
+    const { rerender } = render(
+      <UserAvatar name="Jenny Hamilton" presence="online" />
+    )
+    expect(badge()?.getAttribute("data-presence")).toBe("online")
+    expect(screen.getByRole("img", { name: "Online" })).toBeDefined()
+    expect(badge()?.className).toContain("bg-emerald-500")
+
+    rerender(<UserAvatar name="Jenny Hamilton" presence="offline" />)
+    expect(screen.getByRole("img", { name: "Offline" })).toBeDefined()
+    expect(badge()?.className).toContain("border-2")
+
+    // Releasing the prop clears the badge — a real transition for a user.
+    rerender(<UserAvatar name="Jenny Hamilton" />)
+    expect(badge()).toBeNull()
+  })
+
+  test("online reflects the badge colour onto the disc; offline does not", async () => {
+    const reflection = () =>
+      document.querySelector('[data-slot="user-avatar-reflection"]')
+    const { rerender } = render(
+      <UserAvatar name="Jenny Hamilton" presence="online" />
+    )
+    expect(reflection()).not.toBeNull()
+    // Static — no transform, unlike the bezel rim.
+    expect(reflection()?.getAttribute("style")).toBeNull()
+    expect(reflection()?.className).toContain("radial-gradient")
+    // Initials disc: the smaller, fainter pool.
+    expect(reflection()?.hasAttribute("data-image")).toBe(false)
+    expect(reflection()?.className).toContain("[--reflect-peak:16%]")
+    // A requested-but-not-loaded src still shows initials — still the small
+    // pool; only a loaded photo gets the larger one.
+    // happy-dom's Image reports naturalWidth 0 (Base UI reads that as a
+    // failed preload) — a broken src keeps the initials and the small pool.
+    rerender(
+      <UserAvatar name="Jenny Hamilton" presence="online" src="/broken.jpg" />
+    )
+    expect(reflection()?.hasAttribute("data-image")).toBe(false)
+
+    // Stand in a preload that succeeds: now a photo is on screen.
+    const RealImage = window.Image
+    window.Image = class {
+      complete = true
+      naturalWidth = 72
+      onload: (() => void) | null = null
+      onerror: (() => void) | null = null
+      src = ""
+    } as unknown as typeof window.Image
+    try {
+      rerender(
+        <UserAvatar name="Jenny Hamilton" presence="online" src="/ok.jpg" />
+      )
+      await act(async () => {
+        await new Promise((r) => setTimeout(r, 0))
+      })
+      expect(reflection()?.hasAttribute("data-image")).toBe(true)
+      expect(reflection()?.className).toContain("[--reflect-peak:30%]")
+    } finally {
+      window.Image = RealImage
+    }
+    rerender(<UserAvatar name="Jenny Hamilton" presence="offline" />)
+    expect(reflection()).toBeNull()
+  })
+
+  test("the badge carries a sheen lit from the bezel angle; none without a bezel", async () => {
+    const sheen = () =>
+      document.querySelector('[data-slot="user-avatar-presence-sheen"]')
+    const { rerender } = render(
+      <UserAvatar avatarId="sheen" name="Jenny Hamilton" presence="online" />
+    )
+    expect(sheen()).not.toBeNull()
+    const rot = () =>
+      Number(/rotate\((-?[\d.]+)deg\)/.exec(sheen()?.getAttribute("style") ?? "")?.[1])
+    expect(rot()).toBeCloseTo(DEFAULT_BEZEL_ANGLE * BEZEL_DAMPING, 5)
+
+    // Same light as the rim: a pointer move rotates both together.
+    const host = frame() as HTMLElement
+    host.getBoundingClientRect = () =>
+      ({ left: 100, top: 100, width: 40, height: 40, right: 140, bottom: 140 }) as DOMRect
+    await act(async () => {
+      fireEvent.pointerMove(window, { clientX: 200, clientY: 120 })
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    })
+    expect(rot()).toBeCloseTo(90 * BEZEL_DAMPING, 5)
+    expect(rot()).toBeCloseTo(rimRotation(), 5)
+
+    rerender(<UserAvatar bezel={false} name="Jenny Hamilton" presence="online" />)
+    expect(sheen()).toBeNull()
+    removeUserAvatarInstance("sheen")
+  })
+
+  test("the root carries data-presence for styling hooks", () => {
+    render(<UserAvatar name="Jenny Hamilton" presence="online" />)
+    expect(
+      document
+        .querySelector('[data-slot="user-avatar"]')
+        ?.getAttribute("data-presence")
+    ).toBe("online")
+  })
+})
+
+describe("UserAvatar · bezel", () => {
+  test("on by default: an emboss shadow on the root and a rotated rim", () => {
+    render(<UserAvatar name="Jenny Hamilton" />)
+    const root = document.querySelector('[data-slot="user-avatar"]')
+    expect(root?.hasAttribute("data-bezel")).toBe(true)
+    expect(root?.className).toContain("shadow-[inset")
+    // Rests at the classic top-left light until a pointer moves.
+    expect(rimRotation()).toBeCloseTo(DEFAULT_BEZEL_ANGLE * BEZEL_DAMPING, 5)
+  })
+
+  test("bezel={false} renders a flat disc", () => {
+    render(<UserAvatar bezel={false} name="Jenny Hamilton" />)
+    expect(bezel()).toBeNull()
+    expect(
+      document.querySelector('[data-slot="user-avatar"]')?.hasAttribute("data-bezel")
+    ).toBe(false)
+  })
+
+  test("the rim follows the pointer's bearing from the avatar's centre", async () => {
+    render(<UserAvatar avatarId="lit" name="Jenny Hamilton" />)
+    const host = frame() as HTMLElement
+    // happy-dom rects are 0×0; give the frame a box the hook can measure.
+    host.getBoundingClientRect = () =>
+      ({ left: 100, top: 100, width: 40, height: 40, right: 140, bottom: 140 }) as DOMRect
+
+    // Pointer straight to the right of centre (120,120) → 3 o'clock → 90°.
+    await act(async () => {
+      fireEvent.pointerMove(window, { clientX: 200, clientY: 120 })
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    })
+    expect(rimRotation()).toBeCloseTo(90 * BEZEL_DAMPING, 5)
+
+    // Straight below → 6 o'clock → 180°.
+    await act(async () => {
+      fireEvent.pointerMove(window, { clientX: 120, clientY: 300 })
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    })
+    expect(rimRotation()).toBeCloseTo(180 * BEZEL_DAMPING, 5)
+    removeUserAvatarInstance("lit")
+  })
+})
+
+describe("UserAvatar · store", () => {
+  test("presence, toggle, isOnline and reset on an isolated store", () => {
+    const store = createStore()
+    expect(store.get(userAvatarPresenceAtom("a"))).toBeNull()
+    store.set(setUserAvatarPresenceAtom("a"), "online")
+    expect(store.get(userAvatarIsOnlineAtom("a"))).toBe(true)
+    store.set(toggleUserAvatarPresenceAtom("a"))
+    expect(store.get(userAvatarPresenceAtom("a"))).toBe("offline")
+    // A badge-less avatar comes online on toggle.
+    store.set(setUserAvatarPresenceAtom("a"), null)
+    store.set(toggleUserAvatarPresenceAtom("a"))
+    expect(store.get(userAvatarPresenceAtom("a"))).toBe("online")
+
+    store.set(setUserAvatarBezelAngleAtom("a"), 400)
+    // Continuous — not wrapped — so a CSS rotation takes the short way.
+    expect(store.get(userAvatarBezelAngleAtom("a"))).toBe(400)
+    store.set(setUserAvatarBezelAngleAtom("a"), Number.NaN)
+    expect(store.get(userAvatarBezelAngleAtom("a"))).toBe(400)
+
+    store.set(resetUserAvatarAtom("a"))
+    expect(store.get(userAvatarStateAtom("a"))).toEqual({
+      presence: null,
+      bezelAngle: DEFAULT_BEZEL_ANGLE,
+      imageStatus: "idle",
+    })
+    removeUserAvatarInstance("a")
+  })
+
+  test("a controlled presence prop wins over store writes; hooks by id read and drive", () => {
+    let actions!: UserAvatarActions
+    let state!: UserAvatarState
+    function Probe() {
+      actions = useUserAvatarActions("me")
+      state = useUserAvatarState("me")
+      return null
+    }
+    const store = createStore()
+    const { rerender } = render(
+      <Provider store={store}>
+        <UserAvatar avatarId="me" name="Jenny Hamilton" presence="offline" />
+        <Probe />
+      </Provider>
+    )
+    expect(state.presence).toBe("offline")
+    act(() => actions.setPresence("online"))
+    // Controlled: the store write is inert, the badge stays offline.
+    expect(badge()?.getAttribute("data-presence")).toBe("offline")
+
+    // Uncontrolled: the store drives the badge from anywhere.
+    rerender(
+      <Provider store={store}>
+        <UserAvatar avatarId="me" name="Jenny Hamilton" />
+        <Probe />
+      </Provider>
+    )
+    expect(badge()).toBeNull()
+    act(() => actions.setPresence("online"))
+    expect(badge()?.getAttribute("data-presence")).toBe("online")
+    expect(state.presence).toBe("online")
+    act(() => actions.togglePresence())
+    expect(badge()?.getAttribute("data-presence")).toBe("offline")
+    removeUserAvatarInstance("me")
+  })
+})

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>
+  )
+}