@exegia/corpora-ui 0.20.0 → 0.22.0

package/dist-lib/state/exegia-provider.d.ts

@@ -0,0 +1,51 @@
+import { useStore } from 'jotai';
+import { ExegiaStore } from './store';
+/**
+ * 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";
+/** 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 declare function ExegiaProvider({ children, store, sound, theme, }: ExegiaProviderProps): React.ReactElement;
+/** The store mounted by the nearest `ExegiaProvider` above the caller. */
+export declare const useExegiaStore: typeof useStore;

package/dist-lib/state/index.d.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/dist-lib/state/store.d.ts

@@ -0,0 +1,17 @@
+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 declare const exegiaStore: ExegiaStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
     "dist-lib",
     "src/components",
     "src/lib",
+    "src/state",
     "src/index.css",
     "src/index.ts"
   ],
@@ -37,18 +38,19 @@
     "preview": "vite preview"
   },
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "jotai": "^2.20.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
   },
   "dependencies": {
-    "@base-ui/react": "^1.6.0",
+    "@base-ui/react": "^1.7.0",
     "@remixicon/react": "^4.9.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "cuelume": "^0.2.1",
+    "cuelume": "^0.2.2",
     "iconsax-reactjs": "^0.0.8",
     "lucide-react": "^1.31.0",
-    "motion": "^12.43.0",
+    "motion": "^13.1.0",
     "motion-icons-react": "^1.1.0",
     "tailwind-animations": "^1.0.2",
     "tailwind-merge": "^3.6.0"
@@ -57,11 +59,11 @@
     "@eslint/js": "^10",
     "@fontsource-variable/figtree": "^5.3.0",
     "@fontsource-variable/inter": "^5.3.0",
-    "@happy-dom/global-registrator": "^20.11.1",
+    "@happy-dom/global-registrator": "^20.11.2",
     "@tailwindcss/vite": "^4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.1",
+    "@testing-library/user-event": "^14.6.5",
     "@types/bun": "^1.3.14",
     "@types/node": "^24",
     "@types/react": "^19",
@@ -69,14 +71,15 @@
     "@vitejs/plugin-react": "^6",
     "eslint": "^10",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "eslint-plugin-react-refresh": "^0.5.2",
+    "eslint-plugin-react-refresh": "^0.5.4",
     "globals": "^17",
-    "prettier": "^3.8.3",
-    "prettier-plugin-tailwindcss": "^0.8.0",
+    "jotai": "^2.20.2",
+    "prettier": "^3.9.6",
+    "prettier-plugin-tailwindcss": "^0.8.1",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-router": "^8.3.0",
-    "shadcn": "^4.16.0",
+    "shadcn": "^4.18.0",
     "tailwindcss": "^4",
     "tw-animate-css": "^1.4.0",
     "typescript": "~6",

package/src/components/blocks/auth/__tests__/auth-state-atom.test.tsx

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { createStore } from "jotai"
+
+import { ExegiaProvider } from "@/state"
+import {
+  DEFAULT_AUTH_FLOW_ID,
+  authFlowErrorAtom,
+  authFlowIdentifierAtom,
+  authFlowMaskedIdentifierAtom,
+  authFlowStateAtom,
+  authFlowStatusAtom,
+  authFlowStepAtom,
+  authSessionStatusAtom,
+  authUserAtom,
+  beginAuthVerificationAtom,
+  completeAuthFlowAtom,
+  endAuthSessionAtom,
+  failAuthFlowAtom,
+  goToAuthStepAtom,
+  isAuthenticatedAtom,
+  maskAuthIdentifier,
+  removeAuthFlowInstance,
+  resetAuthFlowAtom,
+  signInAtom,
+  updateAuthUserAtom,
+  useAuthFlow,
+  useAuthFlowActions,
+} from "../auth-state"
+import type { AuthUser } from "../auth-state"
+
+const USER: AuthUser = {
+  id: "u-1",
+  name: "Yona Appletree",
+  email: "yo@example.com",
+}
+
+describe("auth flow atoms · instance isolation", () => {
+  test("two flow ids never share state", () => {
+    const store = createStore()
+    store.set(beginAuthVerificationAtom("modal"), {
+      identifier: "yo@example.com",
+    })
+
+    expect(store.get(authFlowStepAtom("modal"))).toBe("verify-code")
+    expect(store.get(authFlowStepAtom("page"))).toBe("login")
+    expect(store.get(authFlowIdentifierAtom("page"))).toBeNull()
+  })
+
+  test("two stores never share state under one id", () => {
+    const one = createStore()
+    const two = createStore()
+    one.set(beginAuthVerificationAtom("shared"), {
+      identifier: "yo@example.com",
+    })
+
+    expect(one.get(authFlowStepAtom("shared"))).toBe("verify-code")
+    expect(two.get(authFlowStepAtom("shared"))).toBe("login")
+  })
+})
+
+describe("auth flow atoms · flow drives the session", () => {
+  test("beginVerification → complete(user) drives flow and session together", () => {
+    const store = createStore()
+    const other = createStore()
+    store.set(beginAuthVerificationAtom(DEFAULT_AUTH_FLOW_ID), {
+      identifier: "+15551234567",
+      channel: "sms",
+    })
+    store.set(completeAuthFlowAtom(DEFAULT_AUTH_FLOW_ID), USER)
+
+    const flow = store.get(authFlowStateAtom(DEFAULT_AUTH_FLOW_ID))
+    expect(flow.step).toBe("success")
+    expect(flow.status).toBe("success")
+    expect(flow.error).toBeNull()
+    expect(flow.channel).toBe("sms")
+    expect(store.get(authUserAtom)).toEqual(USER)
+    expect(store.get(isAuthenticatedAtom)).toBe(true)
+
+    // The other store's session never moved.
+    expect(other.get(authSessionStatusAtom)).toBe("unknown")
+    expect(other.get(authUserAtom)).toBeNull()
+  })
+
+  test("complete() without a user leaves the session alone", () => {
+    const store = createStore()
+    store.set(completeAuthFlowAtom(DEFAULT_AUTH_FLOW_ID))
+
+    expect(store.get(authFlowStatusAtom(DEFAULT_AUTH_FLOW_ID))).toBe("success")
+    expect(store.get(authSessionStatusAtom)).toBe("unknown")
+  })
+})
+
+describe("auth flow atoms · status transitions", () => {
+  test("fail sets status and error; goToStep clears them", () => {
+    const store = createStore()
+    store.set(failAuthFlowAtom(DEFAULT_AUTH_FLOW_ID), "Wrong code")
+
+    expect(store.get(authFlowStatusAtom(DEFAULT_AUTH_FLOW_ID))).toBe("error")
+    expect(store.get(authFlowErrorAtom(DEFAULT_AUTH_FLOW_ID))).toBe(
+      "Wrong code"
+    )
+
+    store.set(goToAuthStepAtom(DEFAULT_AUTH_FLOW_ID), "forgot-password")
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe(
+      "forgot-password"
+    )
+    expect(store.get(authFlowStatusAtom(DEFAULT_AUTH_FLOW_ID))).toBe("idle")
+    expect(store.get(authFlowErrorAtom(DEFAULT_AUTH_FLOW_ID))).toBeNull()
+  })
+})
+
+describe("maskAuthIdentifier", () => {
+  test("masks emails, keeping the first character and the domain", () => {
+    expect(maskAuthIdentifier("yo@example.com")).toBe("y•••@example.com")
+    expect(maskAuthIdentifier("y@ex.co")).toBe("y•••@ex.co")
+  })
+
+  test("masks phone numbers down to the last 4 characters", () => {
+    expect(maskAuthIdentifier("+15551234567")).toBe("•••4567")
+    expect(maskAuthIdentifier("123")).toBe("•••")
+    // Exactly 4 chars: last-4 would reveal everything — mask it all.
+    expect(maskAuthIdentifier("1234")).toBe("•••")
+  })
+
+  test("the derived atom masks the identifier in flight", () => {
+    const store = createStore()
+    expect(store.get(authFlowMaskedIdentifierAtom("m"))).toBeNull()
+
+    store.set(beginAuthVerificationAtom("m"), {
+      identifier: "yo@example.com",
+    })
+    expect(store.get(authFlowMaskedIdentifierAtom("m"))).toBe(
+      "y•••@example.com"
+    )
+  })
+})
+
+describe("auth session atoms · sign out", () => {
+  test("endAuthSession clears the session and resets the default flow", () => {
+    const store = createStore()
+    store.set(beginAuthVerificationAtom(DEFAULT_AUTH_FLOW_ID), {
+      identifier: "yo@example.com",
+    })
+    store.set(completeAuthFlowAtom(DEFAULT_AUTH_FLOW_ID), USER)
+
+    store.set(endAuthSessionAtom)
+    expect(store.get(authSessionStatusAtom)).toBe("unauthenticated")
+    expect(store.get(authUserAtom)).toBeNull()
+    expect(store.get(isAuthenticatedAtom)).toBe(false)
+
+    const flow = store.get(authFlowStateAtom(DEFAULT_AUTH_FLOW_ID))
+    expect(flow.step).toBe("login")
+    expect(flow.identifier).toBeNull()
+    expect(flow.maskedIdentifier).toBeNull()
+    expect(flow.status).toBe("idle")
+  })
+})
+
+describe("auth session atoms · updateAuthUser", () => {
+  test("shallow-merges a patch into the signed-in user", () => {
+    const store = createStore()
+    store.set(signInAtom, USER)
+    store.set(updateAuthUserAtom, { name: "Yona A.", avatar: "/a.png" })
+
+    expect(store.get(authUserAtom)).toEqual({
+      ...USER,
+      name: "Yona A.",
+      avatar: "/a.png",
+    })
+  })
+
+  test("is a no-op when signed out", () => {
+    const store = createStore()
+    store.set(updateAuthUserAtom, { name: "Nobody" })
+    expect(store.get(authUserAtom)).toBeNull()
+  })
+})
+
+describe("auth flow atoms · reset and teardown", () => {
+  test("resetAuthFlow restores the initial values", () => {
+    const store = createStore()
+    store.set(beginAuthVerificationAtom("r"), {
+      identifier: "+15551234567",
+      channel: "sms",
+      step: "signup",
+    })
+    store.set(failAuthFlowAtom("r"), "nope")
+
+    store.set(resetAuthFlowAtom("r"))
+    expect(store.get(authFlowStateAtom("r"))).toEqual({
+      step: "login",
+      identifier: null,
+      maskedIdentifier: null,
+      channel: "email",
+      status: "idle",
+      error: null,
+    })
+  })
+
+  test("removeAuthFlowInstance drops the slice back to its defaults", () => {
+    const store = createStore()
+    store.set(beginAuthVerificationAtom("gone"), {
+      identifier: "yo@example.com",
+    })
+
+    removeAuthFlowInstance("gone")
+    expect(store.get(authFlowStepAtom("gone"))).toBe("login")
+    expect(store.get(authFlowIdentifierAtom("gone"))).toBeNull()
+  })
+})
+
+describe("ExegiaProvider · siblings share one flow", () => {
+  /** Drives the flow; holds no state of its own. */
+  function Begin() {
+    const { beginVerification } = useAuthFlowActions()
+    return (
+      <button
+        onClick={() => beginVerification({ identifier: "yo@example.com" })}
+        type="button"
+      >
+        begin
+      </button>
+    )
+  }
+
+  /** Reads the flow; no relationship to `Begin` beyond the default id. */
+  function Destination() {
+    const flow = useAuthFlow()
+    return <p>{flow.maskedIdentifier ?? "no destination"}</p>
+  }
+
+  test("one sibling's beginVerification shows in the other's read", async () => {
+    const user = userEvent.setup()
+    render(
+      <ExegiaProvider store={createStore()}>
+        <Begin />
+        <Destination />
+      </ExegiaProvider>
+    )
+
+    expect(screen.getByText("no destination")).toBeDefined()
+    await user.click(screen.getByRole("button", { name: "begin" }))
+    expect(await screen.findByText("y•••@example.com")).toBeDefined()
+  })
+})

package/src/components/blocks/auth/auth-flow-atom.ts

@@ -0,0 +1,238 @@
+/**
+ * Per-instance Jotai state for the auth flow — which auth block the app is
+ * showing, the identifier in flight, and the attempt status.
+ *
+ * Every atom is a module-level family keyed by a flow id, so one
+ * `ExegiaProvider` at the app root is enough: a modal login and a full-page
+ * login can coexist in one store, and any component can drive a flow by id
+ * without holding a controller. Most apps have one flow and use
+ * `DEFAULT_AUTH_FLOW_ID`.
+ *
+ * This is a coordination layer only. The auth blocks keep passwords, codes
+ * and field values in local `useState` on purpose — never store those here.
+ *
+ * Import direction: `auth-session-atom.ts` is the LEAF. This module imports
+ * `signInAtom` from it (`completeAuthFlowAtom` signs the session in) and
+ * defines the composite `endAuthSessionAtom`; the session module never
+ * imports from here.
+ */
+import { atom } from "jotai"
+import type { Getter, Setter } from "jotai"
+
+import { signInAtom, signOutAtom } from "./auth-session-atom"
+import type { AuthStatus } from "./auth-shell"
+import type {
+  AuthFlowChannel,
+  AuthFlowId,
+  AuthFlowState,
+  AuthFlowStep,
+  AuthUser,
+  BeginAuthVerificationOptions,
+} from "./auth-state-type"
+
+export const DEFAULT_AUTH_FLOW_ID: AuthFlowId = "default"
+
+/**
+ * A string-keyed atom family (same in-house shape as `tree-atom.ts`:
+ * `jotai/utils`' `atomFamily` is deprecated for Jotai v3, and we need only
+ * the string-keyed case with a `remove`). Dropping a key lets the store's
+ * WeakMap release that instance's state.
+ */
+type Family<AtomType> = ((id: AuthFlowId) => AtomType) & {
+  remove: (id: AuthFlowId) => void
+}
+
+/** Every family, so `removeAuthFlowInstance` can drop an id from all. */
+const families: { remove: (id: AuthFlowId) => void }[] = []
+
+function keyed<AtomType>(create: (id: AuthFlowId) => AtomType) {
+  const cache = new Map<AuthFlowId, AtomType>()
+  const family = ((id: AuthFlowId) => {
+    let instance = cache.get(id)
+    if (instance === undefined) {
+      instance = create(id)
+      cache.set(id, instance)
+    }
+    return instance
+  }) as Family<AtomType>
+  family.remove = (id: AuthFlowId) => {
+    cache.delete(id)
+  }
+  families.push(family)
+  return family
+}
+
+function stateFamily<Value>(name: string, initialValue: Value) {
+  return keyed((id) => {
+    const instance = atom(initialValue)
+    instance.debugLabel = `auth-flow/${id}/${name}`
+    return instance
+  })
+}
+
+function readFamily<Value>(
+  name: string,
+  read: (get: Getter, id: AuthFlowId) => Value
+) {
+  return keyed((id) => {
+    const instance = atom((get) => read(get, id))
+    instance.debugLabel = `auth-flow/${id}/${name}`
+    return instance
+  })
+}
+
+function actionFamily<Args extends unknown[]>(
+  name: string,
+  write: (get: Getter, set: Setter, id: AuthFlowId, ...args: Args) => void
+) {
+  return keyed((id) => {
+    const instance = atom(null, (get, set, ...args: Args) =>
+      write(get, set, id, ...args)
+    )
+    instance.debugLabel = `auth-flow/${id}/${name}`
+    return instance
+  })
+}
+
+// ── masking ──────────────────────────────────────────────────────────────
+
+/**
+ * Mask an identifier for display. Email → first character of the local part
+ * plus `"•••"`, domain intact (`"y•••@example.com"`; a 1-char local part
+ * still gets `"y•••@…"`). Non-email (sms) → `"•••"` + last 4 characters;
+ * fewer than 4 characters masks everything as `"•••"`.
+ */
+export function maskAuthIdentifier(identifier: string): string {
+  const at = identifier.indexOf("@")
+  if (at > 0) return `${identifier[0]}•••${identifier.slice(at)}`
+  // At 4 characters or fewer, "keep the last 4" would reveal the whole
+  // identifier while implying redaction — mask everything instead.
+  if (identifier.length <= 4) return "•••"
+  return `•••${identifier.slice(-4)}`
+}
+
+// ── primitives ───────────────────────────────────────────────────────────
+
+export const authFlowStepAtom = stateFamily<AuthFlowStep>("step", "login")
+
+/** An email or phone number in flight — never a password or a code. */
+export const authFlowIdentifierAtom = stateFamily<string | null>(
+  "identifier",
+  null
+)
+
+export const authFlowChannelAtom = stateFamily<AuthFlowChannel>(
+  "channel",
+  "email"
+)
+
+export const authFlowStatusAtom = stateFamily<AuthStatus>("status", "idle")
+
+export const authFlowErrorAtom = stateFamily<string | null>("error", null)
+
+// ── derived ──────────────────────────────────────────────────────────────
+
+/** `identifier` masked for display, `null` while nothing is in flight. */
+export const authFlowMaskedIdentifierAtom = readFamily<string | null>(
+  "maskedIdentifier",
+  (get, id) => {
+    const identifier = get(authFlowIdentifierAtom(id))
+    return identifier === null ? null : maskAuthIdentifier(identifier)
+  }
+)
+
+export const authFlowStateAtom = readFamily<AuthFlowState>(
+  "state",
+  (get, id) => ({
+    step: get(authFlowStepAtom(id)),
+    identifier: get(authFlowIdentifierAtom(id)),
+    maskedIdentifier: get(authFlowMaskedIdentifierAtom(id)),
+    channel: get(authFlowChannelAtom(id)),
+    status: get(authFlowStatusAtom(id)),
+    error: get(authFlowErrorAtom(id)),
+  })
+)
+
+// ── actions ──────────────────────────────────────────────────────────────
+
+/** Show a step with a clean slate (`"idle"`, no error). Keeps the
+ * identifier so "back to verify" flows don't lose the destination. */
+export const goToAuthStepAtom = actionFamily<[step: AuthFlowStep]>(
+  "goToStep",
+  (_get, set, id, step) => {
+    set(authFlowStepAtom(id), step)
+    set(authFlowStatusAtom(id), "idle")
+    set(authFlowErrorAtom(id), null)
+  }
+)
+
+/** Record the identifier in flight and move to the verification step. */
+export const beginAuthVerificationAtom = actionFamily<
+  [options: BeginAuthVerificationOptions]
+>(
+  "beginVerification",
+  (_get, set, id, { identifier, channel = "email", step = "verify-code" }) => {
+    set(authFlowIdentifierAtom(id), identifier)
+    set(authFlowChannelAtom(id), channel)
+    set(authFlowStepAtom(id), step)
+    set(authFlowStatusAtom(id), "idle")
+    set(authFlowErrorAtom(id), null)
+  }
+)
+
+/** Mark the flow `"loading"` while an async attempt is in flight. */
+export const beginAuthAttemptAtom = actionFamily<[]>(
+  "beginAttempt",
+  (_get, set, id) => {
+    set(authFlowStatusAtom(id), "loading")
+    set(authFlowErrorAtom(id), null)
+  }
+)
+
+export const failAuthFlowAtom = actionFamily<[message: string]>(
+  "fail",
+  (_get, set, id, message) => {
+    set(authFlowStatusAtom(id), "error")
+    set(authFlowErrorAtom(id), message)
+  }
+)
+
+/** Mark the flow `"success"` and land on the success step. When `user` is
+ * given, also sign the session in — one atomic write for the whole
+ * "verification passed" transition. */
+export const completeAuthFlowAtom = actionFamily<[user?: AuthUser]>(
+  "complete",
+  (_get, set, id, user) => {
+    set(authFlowStatusAtom(id), "success")
+    set(authFlowErrorAtom(id), null)
+    set(authFlowStepAtom(id), "success")
+    if (user) set(signInAtom, user)
+  }
+)
+
+/** Back to the initial values (login step, no identifier, `"email"`,
+ * `"idle"`, no error). */
+export const resetAuthFlowAtom = actionFamily<[]>("reset", (_get, set, id) => {
+  set(authFlowStepAtom(id), "login")
+  set(authFlowIdentifierAtom(id), null)
+  set(authFlowChannelAtom(id), "email")
+  set(authFlowStatusAtom(id), "idle")
+  set(authFlowErrorAtom(id), null)
+})
+
+/**
+ * Sign out and return the default flow to the login step — the one to wire
+ * to a logout button. `useAuthSessionActions().signOut` is this atom;
+ * `signOutAtom` in `auth-session-atom.ts` clears the session only.
+ */
+export const endAuthSessionAtom = atom(null, (_get, set) => {
+  set(signOutAtom)
+  set(resetAuthFlowAtom(DEFAULT_AUTH_FLOW_ID))
+})
+endAuthSessionAtom.debugLabel = "auth-flow/endAuthSession"
+
+/** Drop every atom for `id`. Call on teardown of an explicit flow id; the
+ * default flow usually just gets `resetAuthFlowAtom`. */
+export function removeAuthFlowInstance(id: AuthFlowId): void {
+  for (const family of families) family.remove(id)
+}