@exegia/corpora-ui 0.20.0 → 0.21.0

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

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

@@ -0,0 +1,198 @@
+/**
+ * User avatar state — Jotai atom families keyed by an avatar id.
+ *
+ * Follows the tree's layout (`components/composed/tree/tree-atom.ts`): one
+ * in-house `keyed()` family per field, write-only action atoms for every
+ * mutation, a composed read-only state atom, and `removeUserAvatarInstance`
+ * to drop an id from every family. Nothing here touches the DOM — the
+ * pointer maths that feeds `bezelAngle` lives in `use-user-avatar.ts`.
+ */
+
+import { atom } from "jotai"
+import type { Getter, Setter } from "jotai"
+
+import type {
+  ImageStatus,
+  UserAvatarConfig,
+  UserAvatarInstanceId,
+  UserAvatarState,
+  UserPresence,
+} from "./type"
+
+/** Light from the top-left, the classic emboss, until a pointer moves. */
+export const DEFAULT_BEZEL_ANGLE = 315
+
+const DEFAULT_CONFIG: UserAvatarConfig = { controlsPresence: false }
+
+// ── families ───────────────────────────────────────────────────────────────
+
+type Family<AtomType> = ((id: UserAvatarInstanceId) => AtomType) & {
+  remove: (id: UserAvatarInstanceId) => void
+}
+
+const families: { remove: (id: UserAvatarInstanceId) => void }[] = []
+
+function keyed<AtomType>(create: (id: UserAvatarInstanceId) => AtomType) {
+  const cache = new Map<UserAvatarInstanceId, AtomType>()
+  const family = ((id: UserAvatarInstanceId) => {
+    let instance = cache.get(id)
+    if (instance === undefined) {
+      instance = create(id)
+      cache.set(id, instance)
+    }
+    return instance
+  }) as Family<AtomType>
+  family.remove = (id: UserAvatarInstanceId) => {
+    cache.delete(id)
+  }
+  families.push(family)
+  return family
+}
+
+function stateFamily<Value>(name: string, initialValue: Value) {
+  return keyed((id) => {
+    const instance = atom(initialValue)
+    instance.debugLabel = `userAvatar/${id}/${name}`
+    return instance
+  })
+}
+
+function readFamily<Value>(
+  name: string,
+  read: (get: Getter, id: UserAvatarInstanceId) => Value
+) {
+  return keyed((id) => {
+    const instance = atom((get) => read(get, id))
+    instance.debugLabel = `userAvatar/${id}/${name}`
+    return instance
+  })
+}
+
+function actionFamily<Args extends unknown[]>(
+  name: string,
+  write: (
+    get: Getter,
+    set: Setter,
+    id: UserAvatarInstanceId,
+    ...args: Args
+  ) => void
+) {
+  return keyed((id) => {
+    const instance = atom(null, (get, set, ...args: Args) =>
+      write(get, set, id, ...args)
+    )
+    instance.debugLabel = `userAvatar/${id}/${name}`
+    return instance
+  })
+}
+
+// ── primitives ─────────────────────────────────────────────────────────────
+
+/** `null` = no badge. */
+export const userAvatarPresenceAtom = stateFamily<UserPresence | null>(
+  "presence",
+  null
+)
+
+/** Degrees clockwise from 12 o'clock — where the bezel highlight sits. */
+export const userAvatarBezelAngleAtom = stateFamily<number>(
+  "bezelAngle",
+  DEFAULT_BEZEL_ANGLE
+)
+
+export const userAvatarImageStatusAtom = stateFamily<ImageStatus>(
+  "imageStatus",
+  "idle"
+)
+
+/** @internal Which fields the mounted component controls from props. */
+export const userAvatarConfigAtom = stateFamily<UserAvatarConfig>(
+  "config",
+  DEFAULT_CONFIG
+)
+
+// ── derived ────────────────────────────────────────────────────────────────
+
+export const userAvatarIsOnlineAtom = readFamily(
+  "isOnline",
+  (get, id) => get(userAvatarPresenceAtom(id)) === "online"
+)
+
+/** Whole-state read for callers that want the object; field atoms above are
+ * cheaper for components that watch one thing. */
+export const userAvatarStateAtom = readFamily<UserAvatarState>(
+  "state",
+  (get, id) => ({
+    presence: get(userAvatarPresenceAtom(id)),
+    bezelAngle: get(userAvatarBezelAngleAtom(id)),
+    imageStatus: get(userAvatarImageStatusAtom(id)),
+  })
+)
+
+// ── actions ────────────────────────────────────────────────────────────────
+
+/** Inert while a `presence` prop controls the avatar — the prop is truth. */
+export const setUserAvatarPresenceAtom = actionFamily<
+  [presence: UserPresence | null]
+>("setPresence", (get, set, id, presence) => {
+  if (get(userAvatarConfigAtom(id)).controlsPresence) return
+  set(userAvatarPresenceAtom(id), presence)
+})
+
+/** online ⇄ offline; a badge-less avatar comes online. */
+export const toggleUserAvatarPresenceAtom = actionFamily<[]>(
+  "togglePresence",
+  (get, set, id) => {
+    const next = get(userAvatarPresenceAtom(id)) === "online" ? "offline" : "online"
+    set(setUserAvatarPresenceAtom(id), next)
+  }
+)
+
+/** Stored as given — continuous, not wrapped into [0, 360): the rim is
+ * rotated with a CSS transition, and an unwrapped angle is what lets a
+ * 359° → 1° move take the short way round. Written on every pointer frame,
+ * so it stays a bare set — no config gate, no side effects. */
+export const setUserAvatarBezelAngleAtom = actionFamily<[angle: number]>(
+  "setBezelAngle",
+  (_get, set, id, angle) => {
+    if (!Number.isFinite(angle)) return
+    set(userAvatarBezelAngleAtom(id), angle)
+  }
+)
+
+/** @internal Reported by the image element; drives the skeleton. */
+export const setUserAvatarImageStatusAtom = actionFamily<[status: ImageStatus]>(
+  "setImageStatus",
+  (_get, set, id, status) => {
+    set(userAvatarImageStatusAtom(id), status)
+  }
+)
+
+/** @internal Projection of the mounted component's controlled props. */
+export const projectUserAvatarPropsAtom = actionFamily<
+  [config: UserAvatarConfig, presence: UserPresence | null | undefined]
+>("projectProps", (get, set, id, config, presence) => {
+  const wasControlled = get(userAvatarConfigAtom(id)).controlsPresence
+  set(userAvatarConfigAtom(id), config)
+  if (config.controlsPresence) set(userAvatarPresenceAtom(id), presence ?? null)
+  // Releasing control (`presence` prop → undefined) clears the badge rather
+  // than leaving the last projected value stranded in the store — going
+  // from "online" to no presence is a real transition for a user object.
+  else if (wasControlled) set(userAvatarPresenceAtom(id), null)
+})
+
+export const resetUserAvatarAtom = actionFamily<[]>(
+  "reset",
+  (_get, set, id) => {
+    set(userAvatarPresenceAtom(id), null)
+    set(userAvatarBezelAngleAtom(id), DEFAULT_BEZEL_ANGLE)
+    set(userAvatarImageStatusAtom(id), "idle")
+    set(userAvatarConfigAtom(id), DEFAULT_CONFIG)
+  }
+)
+
+/** Forget an avatar entirely — every family drops the key so the store can
+ * release its state. Call on teardown of a named instance. */
+export function removeUserAvatarInstance(id: UserAvatarInstanceId): void {
+  for (const family of families) family.remove(id)
+}

package/src/index.ts

@@ -27,10 +27,39 @@ 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"
+// user-avatar: named, not `export *` — its barrel also exports an `Avatar`
+// namespace object that would collide with ui/avatar's component above.
+export {
+  DEFAULT_BEZEL_ANGLE,
+  PresenceBadge,
+  UserAvatar,
+  initialsFrom,
+  removeUserAvatarInstance,
+  resetUserAvatarAtom,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarPresenceAtom,
+  toggleUserAvatarPresenceAtom,
+  useUserAvatar,
+  useUserAvatarActions,
+  useUserAvatarState,
+  userAvatarBezelAngleAtom,
+  userAvatarIsOnlineAtom,
+  userAvatarPresenceAtom,
+  userAvatarStateAtom,
+} from "./components/user-avatar"
+export type {
+  UseUserAvatarOptions,
+  UserAvatarActions,
+  UserAvatarBinding,
+  UserAvatarInstanceId,
+  UserAvatarProps,
+  UserAvatarState,
+  UserPresence,
+} from "./components/user-avatar"
 
 // blocks
 export * from "./components/blocks/auth/auth-shell"
+export * from "./components/blocks/auth/auth-state"
 export * from "./components/blocks/auth/code-auth-block"
 export * from "./components/blocks/auth/forgot-password-block"
 export * from "./components/blocks/auth/linked-accounts-block"
@@ -46,11 +75,14 @@ export * from "./components/blocks/shell"
 export { default as ShellLayout } from "./components/blocks/shell"
 export * from "./components/blocks/scaffold"
 export { default as Layout } from "./components/blocks/layout"
-export * from "./components/blocks/profile/profile-card-block"
+export * from "./components/blocks/profile"
 
 // motion primitives
 export * from "./components/motion/shared-layout-bg"
 
+// state
+export * from "./state"
+
 // The v0.17 sidebar monolith became the shell block's AnimatedPanel parts.
 // `blocks/shell` above already exports every part under its new name; these
 // aliases keep the published AnimatedSidebar* names working for consumers.

package/src/state/exegia-provider.tsx

@@ -0,0 +1,79 @@
+"use client"
+
+/* eslint-disable react-refresh/only-export-components */
+/**
+ * The library's one and only state provider.
+ *
+ * Mount it once at the app root. Every library state hook then works
+ * anywhere below it — there are no per-component providers to nest.
+ *
+ * One provider suffices because library state lives in module-level Jotai
+ * atom families keyed by an instance id, not in a context created per
+ * component. A new stateful component adds atoms to that module scope; it
+ * never adds a provider. Consumer code therefore stays exactly as it is as
+ * the library grows.
+ *
+ * Without this provider the hooks still run, which is the trap: Jotai falls
+ * back to its implicit default store, and that store is NOT `exegiaStore`,
+ * so imperative access would read a different store than the one the
+ * components render from. Mount the provider.
+ *
+ * ```tsx
+ * export function App() {
+ *   return (
+ *     <ExegiaProvider sound>
+ *       <Routes />
+ *     </ExegiaProvider>
+ *   )
+ * }
+ * ```
+ */
+import * as React from "react"
+import { Provider, useStore } from "jotai"
+
+import { ThemeProvider } from "@/components/theme-provider"
+import { bindSounds } from "@/lib/sound"
+import { exegiaStore } from "./store"
+import type { ExegiaStore } from "./store"
+
+/** Options forwarded to the library's `ThemeProvider`. */
+export interface ExegiaThemeOptions {
+  defaultTheme?: "dark" | "light" | "system"
+  storageKey?: string
+  disableTransitionOnChange?: boolean
+}
+
+export interface ExegiaProviderProps {
+  children: React.ReactNode
+  /** Store to mount. Defaults to the library's `exegiaStore`. */
+  store?: ExegiaStore
+  /** Opt into interaction sound. Off unless the app asks for it. */
+  sound?: boolean
+  /** Mount `ThemeProvider` with these options. Omit it and none is mounted —
+   * it reads `localStorage` in its state initializer, so an unconditional
+   * mount would break SSR consumers, and `useTheme` already throws without
+   * one. */
+  theme?: ExegiaThemeOptions
+}
+
+export function ExegiaProvider({
+  children,
+  store,
+  sound = false,
+  theme,
+}: ExegiaProviderProps): React.ReactElement {
+  React.useEffect(() => {
+    // Idempotent, and deliberately not at module scope: opting into sound is
+    // the consuming app's decision, not an import side effect.
+    if (sound) bindSounds()
+  }, [sound])
+
+  return (
+    <Provider store={store ?? exegiaStore}>
+      {theme ? <ThemeProvider {...theme}>{children}</ThemeProvider> : children}
+    </Provider>
+  )
+}
+
+/** The store mounted by the nearest `ExegiaProvider` above the caller. */
+export const useExegiaStore = useStore

package/src/state/index.ts

@@ -0,0 +1,4 @@
+export { ExegiaProvider, useExegiaStore } from "./exegia-provider"
+export type { ExegiaProviderProps, ExegiaThemeOptions } from "./exegia-provider"
+export { exegiaStore } from "./store"
+export type { ExegiaStore } from "./store"

package/src/state/store.ts

@@ -0,0 +1,19 @@
+import { createStore } from "jotai"
+
+/** A Jotai store as created by `createStore()`. */
+export type ExegiaStore = ReturnType<typeof createStore>
+
+/**
+ * The library's default store — the one `ExegiaProvider` mounts unless it is
+ * handed another. Exported so non-React code (a router guard, a command
+ * palette, a test) can read and write library state imperatively:
+ *
+ * ```ts
+ * exegiaStore.get(treeExpandedIdsAtom("app-nav"))
+ * ```
+ *
+ * A single module-level store is wrong for SSR — state would leak between
+ * requests — so render-per-request apps pass a fresh `createStore()` to
+ * `ExegiaProvider` instead.
+ */
+export const exegiaStore: ExegiaStore = createStore()