@exegia/corpora-ui 0.19.0 → 0.21.0

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

@@ -0,0 +1,152 @@
+"use client"
+
+import * as React from "react"
+
+import { Avatar, AvatarImage } from "@/components/ui/avatar"
+import { cn } from "@/lib/utils"
+import { Fallback } from "./fallback"
+import { PresenceBadge } from "./presence-badge"
+import type { UserAvatarProps } from "./type"
+import { useUserAvatar } from "./use-user-avatar"
+
+/**
+ * Identity avatar: an image when one is given, initials otherwise, with an
+ * optional presence badge and a pointer-lit bezel.
+ *
+ * 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.
+ *
+ * State (presence, bezel angle, image status) lives in Jotai atoms keyed by
+ * `avatarId` — name the avatar and `useUserAvatarActions(id).setPresence()`
+ * flips its badge from anywhere under `ExegiaProvider`.
+ */
+/** The rim (and the badge sheen) trail the pointer's bearing slightly rather
+ * than pointing dead at it — a touch of lag reads as weight. */
+const BEZEL_DAMPING = 0.8
+
+export function UserAvatar({
+  src,
+  name = "",
+  initials,
+  alt,
+  loading: loadingProp,
+  presence: presenceProp,
+  bezel = true,
+  avatarId,
+  className,
+  style,
+  ...props
+}: UserAvatarProps): React.ReactElement {
+  const hasImage = src !== undefined
+  const avatar = useUserAvatar({
+    avatarId,
+    presence: presenceProp,
+    bezel,
+    hasImage,
+  })
+  const { presence, bezelAngle, imageStatus, setImageStatus, ref } = avatar
+
+  const loading =
+    loadingProp ??
+    (hasImage && (imageStatus === "idle" || imageStatus === "loading"))
+  // A photo is actually on screen — not merely requested. A broken or
+  // still-loading `src` shows initials/skeleton and should be treated as
+  // the flat disc it is.
+  const showsImage = hasImage && loadingProp !== true && imageStatus === "loaded"
+
+  return (
+    // The frame is what the badge and bezel hang off: the Avatar root clips
+    // to its circle, and the badge has to sit on the rim, half outside it.
+    // Sizing classes still target the Avatar — the frame shrink-wraps it.
+    <span
+      className="relative inline-flex shrink-0 rounded-full"
+      data-slot="user-avatar-frame"
+      ref={ref as React.RefObject<HTMLSpanElement>}
+    >
+      <Avatar
+        className={cn(
+          "size-8 border-1 border-white bg-neutral-800! text-xl dark:border-neutral-900",
+          // The emboss itself: an inset drop toward the light's opposite side
+          // is what the ring below is rotated against.
+          bezel &&
+            "shadow-[inset_0_3px_3px_--theme(--color-white/80%),inset_0_-1px_2px_--theme(--color-black/15%)] dark:shadow-[inset_0_1px_1px_--theme(--color-white/5%),inset_0_-8px_2px_--theme(--color-black/20%)]",
+          className
+        )}
+        data-avatar-id={avatar.avatarId}
+        data-bezel={bezel ? "" : undefined}
+        data-loading={loading || undefined}
+        data-presence={presence ?? undefined}
+        data-slot="user-avatar"
+        style={style}
+        {...props}
+      >
+        {/* Held back while forced-loading: a loaded image would hide the
+            fallback the skeleton lives in. */}
+        {!hasImage || loadingProp === true ? null : (
+          <AvatarImage
+            alt={alt ?? name}
+            onLoadingStatusChange={setImageStatus}
+            src={src}
+          />
+        )}
+        <Fallback name={name} initials={initials} loading={loading} />
+      </Avatar>
+      {presence === "online" ? (
+        // The badge's green "reflected" onto the disc: a static radial wash
+        // anchored at the badge corner that fades inward, so the dot reads
+        // as a light source sitting on the avatar rather than a sticker on
+        // it. Does not move with the bezel — it belongs to the badge, not
+        // the pointer. Sits above the image, below the bezel and the badge.
+        <span
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute inset-0 rounded-full",
+            // One gradient, four knobs: colour, peak alpha, mid alpha, reach.
+            // Light mode is quieter than dark (a green wash on a pale disc
+            // reads as a stain, on a dark one as a glow), and an initials
+            // disc — flat, no photo to sit on — takes a smaller, fainter
+            // pool than an image does.
+            "[--reflect:--theme(--color-emerald-500)] dark:[--reflect:--theme(--color-emerald-400)]",
+            showsImage
+              ? "[--reflect-peak:30%] [--reflect-mid:12%] [--reflect-reach:56%] dark:[--reflect-peak:40%] dark:[--reflect-mid:16%] dark:[--reflect-reach:60%]"
+              : "[--reflect-peak:16%] [--reflect-mid:6%] [--reflect-reach:40%] dark:[--reflect-peak:26%] dark:[--reflect-mid:9%] dark:[--reflect-reach:46%]",
+            "bg-[radial-gradient(circle_at_88%_88%,color-mix(in_oklab,var(--reflect)_var(--reflect-peak),transparent)_0%,color-mix(in_oklab,var(--reflect)_var(--reflect-mid),transparent)_22%,transparent_var(--reflect-reach))]",
+            "transition-opacity duration-150 ease-smooth-out"
+          )}
+          data-image={showsImage ? "" : undefined}
+          data-slot="user-avatar-reflection"
+        />
+      ) : null}
+      {bezel ? (
+        // A conic highlight → shadow sweep, masked to a thin rim and rotated
+        // so the highlight faces the pointer. Rotation (not the gradient
+        // angle) is what moves, because `transform` transitions and a
+        // gradient stop does not. Light and dark pick their own alphas via
+        // the two CSS vars; the gradient reads them.
+        <span
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute inset-0 rounded-full",
+            "[--bezel-hi:--theme(--color-white)] [--bezel-lo:--theme(--color-black/20%)]",
+            "dark:[--bezel-hi:--theme(--color-white/18%)] dark:[--bezel-lo:--theme(--color-black/40%)]",
+            // Starts at 6 o'clock: shadow there, highlight peaking at 12 (50%),
+            // symmetric either side — so rotate(angle) puts the highlight at
+            // exactly `bezelAngle` clockwise from 12.
+            "bg-[conic-gradient(from_180deg,var(--bezel-lo)_0%,transparent_24%,transparent_28%,var(--bezel-hi)_50%,transparent_72%,transparent_76%,var(--bezel-lo)_100%)]",
+            "[mask-image:radial-gradient(farthest-side,transparent_calc(95%-4px),#000_calc(100%-2px))]",
+            "mix-blend-normal transition-transform duration-150 ease-smooth-out motion-reduce:transition-none"
+          )}
+          data-slot="user-avatar-bezel"
+          style={{ transform: `rotate(${bezelAngle * BEZEL_DAMPING}deg)` }}
+        />
+      ) : null}
+      {presence ? (
+        <PresenceBadge
+          lightAngle={bezel ? bezelAngle * BEZEL_DAMPING : undefined}
+          presence={presence}
+        />
+      ) : null}
+    </span>
+  )
+}

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,34 @@
+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 { PresenceBadge } from "./presence-badge"
+export { initialsFrom } from "./utils"
+export { useUserAvatar } from "./use-user-avatar"
+export type { UseUserAvatarOptions, UserAvatarBinding } from "./use-user-avatar"
+export { useUserAvatarActions, useUserAvatarState } from "./use-user-avatar-state"
+// The public atom surface. `@internal` atoms (config, image status, the
+// props projection) stay unexported on purpose — `export *` would make every
+// internal a breaking-change surface for consumer apps.
+export {
+  DEFAULT_BEZEL_ANGLE,
+  removeUserAvatarInstance,
+  resetUserAvatarAtom,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarPresenceAtom,
+  toggleUserAvatarPresenceAtom,
+  userAvatarBezelAngleAtom,
+  userAvatarIsOnlineAtom,
+  userAvatarPresenceAtom,
+  userAvatarStateAtom,
+} from "./user-avatar-atom"
+export type * from "./type"
+
+export const Avatar = {
+  AudioWave,
+  Component: UserAvatar,
+  Fallback,
+}

package/src/components/user-avatar/presence-badge.tsx

@@ -0,0 +1,56 @@
+import { cn } from "@/lib/utils"
+import type { UserPresence } from "./type"
+
+/**
+ * Corner dot naming whether the person is reachable. Sits on the avatar
+ * frame, outside the clipped circle, with a background-coloured ring so it
+ * reads against any image. Colour is not the only signal: `offline` is a
+ * hollow ring, `online` a filled dot, and the label is spelled out for AT.
+ *
+ * `lightAngle` (degrees clockwise from 12) lays a faint sheen across the dot
+ * from that side — the same angle the avatar's bezel is lit from, so the two
+ * highlights agree and the badge reads as a bead sitting in the same light.
+ */
+export function PresenceBadge({
+  presence,
+  lightAngle,
+  className,
+}: {
+  presence: UserPresence
+  lightAngle?: number
+  className?: string
+}) {
+  const online = presence === "online"
+  return (
+    <span
+      aria-label={online ? "Online" : "Offline"}
+      className={cn(
+        "absolute right-0 bottom-0 box-content size-[22%] min-h-1.5 min-w-1.5 overflow-hidden rounded-full",
+        "ring-2 ring-background transition-colors duration-150 ease-smooth-out",
+        online
+          ? "bg-emerald-500 dark:bg-emerald-400"
+          : "border-2 border-muted-foreground/60 bg-background dark:border-muted-foreground/70",
+        className
+      )}
+      data-presence={presence}
+      data-slot="user-avatar-presence"
+      role="img"
+    >
+      {lightAngle !== undefined ? (
+        // Highlight at 12 o'clock, fading out by the middle, rotated so it
+        // faces the light. Rotation transitions; the gradient is static.
+        <span
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute inset-0 rounded-full",
+            "bg-[linear-gradient(to_bottom,--theme(--color-white/55%),--theme(--color-white/12%)_38%,transparent_58%)]",
+            "dark:bg-[linear-gradient(to_bottom,--theme(--color-white/40%),--theme(--color-white/8%)_38%,transparent_58%)]",
+            "transition-transform duration-150 ease-smooth-out motion-reduce:transition-none"
+          )}
+          data-slot="user-avatar-presence-sheen"
+          style={{ transform: `rotate(${lightAngle}deg)` }}
+        />
+      ) : null}
+    </span>
+  )
+}

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

@@ -0,0 +1,85 @@
+import type * as React from "react"
+
+import type { AvatarPrimitive } from "@/components/ui/avatar"
+
+export type ImageStatus = Parameters<
+  NonNullable<AvatarPrimitive.Image.Props["onLoadingStatusChange"]>
+>[0]
+
+/** Whether the person is reachable right now — drawn as the corner badge. */
+export type UserPresence = "online" | "offline"
+
+/** Key for one avatar's state in the store. Any stable string; `useUserAvatar`
+ * generates one when the component does not name itself. */
+export type UserAvatarInstanceId = string
+
+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
+  /**
+   * Corner badge: a green dot for `online`, a hollow grey ring for `offline`.
+   * Omitted, no badge — unless the avatar is driven by id and something set
+   * its presence in the store. Controlled when passed.
+   */
+  presence?: UserPresence
+  /**
+   * Embossed rim whose highlight follows the pointer, so the avatar reads as
+   * a lit bezel rather than a flat disc. Light and dark aware; static under
+   * reduced motion. On by default — pass `false` for a flat disc.
+   */
+  bezel?: boolean
+  /**
+   * Name this avatar's slice of the store so `useUserAvatarState(id)` /
+   * `useUserAvatarActions(id)` can read or drive it from anywhere under
+   * `ExegiaProvider`. Unnamed avatars key off `useId` and are dropped on
+   * unmount.
+   */
+  avatarId?: UserAvatarInstanceId
+}
+
+/** Everything the store knows about one avatar. */
+export interface UserAvatarState {
+  presence: UserPresence | null
+  /** Bezel light direction in degrees, clockwise from 12 o'clock. Continuous
+   * (may leave [0, 360)) so the rim's CSS rotation never spins the long way;
+   * `((a % 360) + 360) % 360` if you need it normalised. */
+  bezelAngle: number
+  imageStatus: ImageStatus
+}
+
+/** Write-only handles onto one avatar. Nothing here re-renders the caller. */
+export interface UserAvatarActions {
+  setPresence: (presence: UserPresence | null) => void
+  togglePresence: () => void
+  setBezelAngle: (angle: number) => void
+  reset: () => void
+}
+
+/** @internal Which fields the mounted component controls from props. The
+ * store must never overwrite a controlled value. */
+export interface UserAvatarConfig {
+  controlsPresence: boolean
+}
+
+export interface IAudioWaveProps {
+  className?: string
+  children?: React.ReactNode
+  volume?: number
+}

package/src/components/user-avatar/use-user-avatar-state.ts

@@ -0,0 +1,60 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import type {
+  UserAvatarActions,
+  UserAvatarInstanceId,
+  UserAvatarState,
+} from "./type"
+import {
+  resetUserAvatarAtom,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarPresenceAtom,
+  toggleUserAvatarPresenceAtom,
+  userAvatarStateAtom,
+} from "./user-avatar-atom"
+
+/**
+ * Read the avatar registered under `avatarId` from anywhere below
+ * `ExegiaProvider` — no props, no ref, no provider of its own.
+ *
+ * ```tsx
+ * const { presence } = useUserAvatarState("me")
+ * ```
+ *
+ * Returns the whole state object, so the caller re-renders on any change —
+ * including every bezel frame while a pointer moves. A component that only
+ * cares about presence should subscribe to that atom instead:
+ * `useAtomValue(userAvatarPresenceAtom("me"))`.
+ */
+export function useUserAvatarState(
+  avatarId: UserAvatarInstanceId
+): UserAvatarState {
+  return useAtomValue(userAvatarStateAtom(avatarId))
+}
+
+/**
+ * Write-only handles onto the avatar registered under `avatarId`. Nothing
+ * here subscribes, so a presence indicator elsewhere in the app can flip
+ * the badge without re-rendering when the avatar changes.
+ *
+ * ```tsx
+ * const { setPresence } = useUserAvatarActions("me")
+ * socket.on("presence", (p) => setPresence(p))
+ * ```
+ */
+export function useUserAvatarActions(
+  avatarId: UserAvatarInstanceId
+): UserAvatarActions {
+  const setPresence = useSetAtom(setUserAvatarPresenceAtom(avatarId))
+  const togglePresence = useSetAtom(toggleUserAvatarPresenceAtom(avatarId))
+  const setBezelAngle = useSetAtom(setUserAvatarBezelAngleAtom(avatarId))
+  const reset = useSetAtom(resetUserAvatarAtom(avatarId))
+
+  return React.useMemo(
+    () => ({ setPresence, togglePresence, setBezelAngle, reset }),
+    [setPresence, togglePresence, setBezelAngle, reset]
+  )
+}

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

@@ -0,0 +1,144 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+import { useReducedMotion } from "motion/react"
+
+import type {
+  ImageStatus,
+  UserAvatarConfig,
+  UserAvatarInstanceId,
+  UserPresence,
+} from "./type"
+import {
+  projectUserAvatarPropsAtom,
+  removeUserAvatarInstance,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarImageStatusAtom,
+  userAvatarBezelAngleAtom,
+  userAvatarImageStatusAtom,
+  userAvatarPresenceAtom,
+} from "./user-avatar-atom"
+
+export interface UseUserAvatarOptions {
+  avatarId?: UserAvatarInstanceId
+  /** Controlled presence. `undefined` leaves the store in charge. */
+  presence?: UserPresence
+  /** Track the pointer for the bezel highlight. */
+  bezel: boolean
+  /** Only meaningful with an image — no image, no status to track. */
+  hasImage: boolean
+}
+
+export interface UserAvatarBinding {
+  avatarId: UserAvatarInstanceId
+  presence: UserPresence | null
+  bezelAngle: number
+  imageStatus: ImageStatus
+  /** Hand to the image's `onLoadingStatusChange`. Stable. */
+  setImageStatus: (status: ImageStatus) => void
+  /** Attach to the avatar root — the bezel is lit relative to its centre. */
+  ref: React.RefObject<HTMLElement | null>
+}
+
+/** Below this the angle write is skipped: a rim highlight cannot show a
+ * sub-degree change, and skipping keeps the pointer loop store-quiet. */
+const ANGLE_EPSILON = 1.5
+
+/**
+ * Binds one avatar to its slice of the store: projects the controlled
+ * `presence` prop, tracks the image status, and — while `bezel` is on —
+ * follows the pointer with a rAF-coalesced `pointermove` listener that turns
+ * the pointer's bearing from the avatar's centre into `bezelAngle`.
+ *
+ * Unnamed avatars key off `useId` and are dropped from the store on unmount;
+ * a named `avatarId` outlives its component so a presence set elsewhere
+ * survives a remount.
+ */
+export function useUserAvatar(options: UseUserAvatarOptions): UserAvatarBinding {
+  const { presence: presenceProp, bezel, hasImage } = options
+  const generatedId = React.useId()
+  const avatarId = options.avatarId ?? generatedId
+  const controlsPresence = presenceProp !== undefined
+
+  const config = React.useMemo<UserAvatarConfig>(
+    () => ({ controlsPresence }),
+    [controlsPresence]
+  )
+
+  const project = useSetAtom(projectUserAvatarPropsAtom(avatarId))
+  const setBezelAngle = useSetAtom(setUserAvatarBezelAngleAtom(avatarId))
+  const setImageStatus = useSetAtom(setUserAvatarImageStatusAtom(avatarId))
+
+  // Layout effect: the projection must land before children read the store
+  // in the same commit. Primitive deps, so no loop guard is needed here.
+  React.useLayoutEffect(() => {
+    project(config, presenceProp)
+  }, [project, config, presenceProp])
+
+  // A generated key belongs to this mount only; a given `avatarId` is the
+  // app's handle and outlives it.
+  React.useEffect(() => {
+    if (options.avatarId !== undefined) return
+    return () => removeUserAvatarInstance(avatarId)
+  }, [options.avatarId, avatarId])
+
+  const presence = useAtomValue(userAvatarPresenceAtom(avatarId))
+  const bezelAngle = useAtomValue(userAvatarBezelAngleAtom(avatarId))
+  const imageStatus = useAtomValue(userAvatarImageStatusAtom(avatarId))
+
+  const ref = React.useRef<HTMLElement | null>(null)
+  const reduce = useReducedMotion()
+
+  // Pointer → bearing. Coalesced to one write per animation frame, and only
+  // when the angle moved enough to matter, so a room full of avatars is
+  // still one cheap listener each and near-zero store traffic while idle.
+  React.useEffect(() => {
+    if (!bezel || reduce || typeof window === "undefined") return
+    let frame = 0
+    let last = Number.NaN
+    let pointer: { x: number; y: number } | null = null
+
+    const flush = () => {
+      frame = 0
+      const host = ref.current
+      if (!host || !pointer) return
+      const rect = host.getBoundingClientRect()
+      if (rect.width === 0) return
+      const dx = pointer.x - (rect.left + rect.width / 2)
+      const dy = pointer.y - (rect.top + rect.height / 2)
+      // atan2 measures from 3 o'clock anticlockwise-positive in screen
+      // space; rotate so 0 is 12 o'clock and clockwise grows.
+      const bearing = ((Math.atan2(dy, dx) * 180) / Math.PI + 90 + 360) % 360
+      // Unwrap: step from the last value by the shortest arc, so the stored
+      // angle is continuous and the rim never spins the long way round.
+      let angle = bearing
+      if (!Number.isNaN(last)) {
+        let delta = bearing - (((last % 360) + 360) % 360)
+        if (delta > 180) delta -= 360
+        if (delta < -180) delta += 360
+        if (Math.abs(delta) < ANGLE_EPSILON) return
+        angle = last + delta
+      }
+      last = angle
+      setBezelAngle(angle)
+    }
+    const onMove = (event: PointerEvent) => {
+      pointer = { x: event.clientX, y: event.clientY }
+      if (frame === 0) frame = window.requestAnimationFrame(flush)
+    }
+
+    window.addEventListener("pointermove", onMove, { passive: true })
+    return () => {
+      window.removeEventListener("pointermove", onMove)
+      if (frame !== 0) window.cancelAnimationFrame(frame)
+    }
+  }, [bezel, reduce, setBezelAngle])
+
+  // No image, no status: keep the store honest when `src` goes away.
+  React.useEffect(() => {
+    if (!hasImage) setImageStatus("idle")
+  }, [hasImage, setImageStatus])
+
+  return { avatarId, presence, bezelAngle, imageStatus, setImageStatus, ref }
+}