@exegia/corpora-ui 3.0.0 → 4.0.0

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

@@ -1,238 +0,0 @@
-/**
- * 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 {
-  TAuthStatus,
-  TAuthFlowChannel,
-  TAuthFlowId,
-  IAuthFlowState,
-  TAuthFlowStep,
-  IAuthUser,
-  IBeginAuthVerificationOptions,
-} from "./type"
-
-export const DEFAULT_AUTH_FLOW_ID: TAuthFlowId = "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 TFamily<AtomType> = ((id: TAuthFlowId) => AtomType) & {
-  remove: (id: TAuthFlowId) => void
-}
-
-/** Every family, so `removeAuthFlowInstance` can drop an id from all. */
-const families: { remove: (id: TAuthFlowId) => void }[] = []
-
-function keyed<AtomType>(create: (id: TAuthFlowId) => AtomType) {
-  const cache = new Map<TAuthFlowId, AtomType>()
-  const family = ((id: TAuthFlowId) => {
-    let instance = cache.get(id)
-    if (instance === undefined) {
-      instance = create(id)
-      cache.set(id, instance)
-    }
-    return instance
-  }) as TFamily<AtomType>
-  family.remove = (id: TAuthFlowId) => {
-    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: TAuthFlowId) => 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: TAuthFlowId, ...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<TAuthFlowStep>("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<TAuthFlowChannel>(
-  "channel",
-  "email"
-)
-
-export const authFlowStatusAtom = stateFamily<TAuthStatus>("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<IAuthFlowState>(
-  "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: TAuthFlowStep]>(
-  "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: IBeginAuthVerificationOptions]
->(
-  "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?: IAuthUser]>(
-  "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: TAuthFlowId): void {
-  for (const family of families) family.remove(id)
-}

package/src/components/blocks/auth/auth-flow-block.tsx

@@ -1,211 +0,0 @@
-"use client"
-
-import * as React from "react"
-import { MotionConfig } from "motion/react"
-
-import { cn } from "@/lib/utils"
-import { AuthCard, AuthSuccess, MorphStep } from "./auth-shell"
-import { CodeAuthBlock } from "./code-auth-block"
-import {
-  ForgotPasswordBlock,
-} from "./forgot-password-block"
-import { LoginBlock } from "./login-block"
-import {
-  OnboardingBlock,
-} from "./onboarding-block"
-import { SignupBlock } from "./signup-block"
-import {
-  UpdatePasswordBlock,
-} from "./update-password-block"
-import { useAuthFlow, useAuthFlowActions } from "./use-auth-state"
-import type { IAuthFlowBlockProps, TAuthFlowDirective, TAuthFlowHandler } from "./type"
-
-/**
- * Where the flow goes after a step callback resolves. Returned from every
- * `AuthFlowBlock` handler:
- *
- * - `{ user }` — the attempt signed someone in: mark the flow complete AND
- *   sign the session in (one atomic write, `completeAuthFlowAtom`).
- * - `{ verify }` — a code went out: record the identifier and move to the
- *   verification step (`beginAuthVerificationAtom`).
- * - `{ step }` — plain navigation with a clean slate (`goToAuthStepAtom`).
- * - `void` — stay put; the block renders its own success state.
- *
- * Rejections are NOT handled here — they propagate back into the block,
- * which owns its transient error/shake state (see `react/CLAUDE.md`,
- * "Third implementation: auth").
- */
-
-/**
- * Renders the right auth block for the flow's current step with the store
- * wiring built in — the switchboard every host app was hand-rolling around
- * `useAuthFlow`. Navigation links between steps (login ↔ signup, forgot
- * password, back from verification) are pre-wired to `goToStep`; each
- * submit-shaped prop awaits your handler and applies the returned
- * {@link TAuthFlowDirective}.
- *
- * The blocks themselves stay untouched: passwords, codes and field drafts
- * live in their local state, and a rejected handler renders as the block's
- * own error — the orchestrator never mirrors transients into the store.
- * Needs `ExegiaProvider` above it, like every stateful block.
- *
- * ```tsx
- * <AuthFlowBlock
- *   onLogin={async ({ email, password }) => {
- *     const outcome = await api.signIn(email, password)
- *     return outcome.mfa ? { verify: { identifier: email } } : { user: outcome.user }
- *   }}
- *   onVerifyCode={async (code) => ({ user: await api.verify(code) })}
- * />
- * ```
- */
-export function AuthFlowBlock({
-  flowId,
-  logo,
-  accent,
-  providers,
-  onLogin,
-  onSignup,
-  onProviderSelect,
-  onRequestReset,
-  onVerifyCode,
-  onResendCode,
-  onUpdatePassword,
-  onOnboardingComplete,
-  onboardingSteps,
-  steps,
-  renderStep,
-  success,
-  successTitle = "Welcome",
-  successDescription,
-  className,
-}: IAuthFlowBlockProps): React.ReactElement {
-  const flow = useAuthFlow(flowId)
-  const { goToStep, beginVerification, complete } = useAuthFlowActions(flowId)
-
-  const apply = React.useCallback(
-    (directive: TAuthFlowDirective) => {
-      if (!directive) return
-      if ("user" in directive) complete(directive.user)
-      else if ("verify" in directive) beginVerification(directive.verify)
-      else goToStep(directive.step)
-    },
-    [complete, beginVerification, goToStep]
-  )
-
-  /** Wrap a handler so its directive lands in the store. Errors propagate —
-   * the block owns the error rendering. Absent handlers stay absent, so a
-   * block keeps its "no handler" affordances (hidden buttons etc.). */
-  function run<Data>(handler: TAuthFlowHandler<Data> | undefined) {
-    if (!handler) return undefined
-    return async (data: Data) => {
-      apply(await handler(data))
-    }
-  }
-
-  const content = ((): React.ReactNode => {
-    const custom = renderStep?.(flow.step, flow)
-    if (custom !== undefined) return custom
-
-    switch (flow.step) {
-      case "login":
-        return (
-          <LoginBlock
-            logo={logo}
-            accent={accent}
-            providers={providers}
-            onSubmit={run(onLogin)}
-            onProviderSelect={run(onProviderSelect)}
-            onForgotPassword={() => goToStep("forgot-password")}
-            onSignup={() => goToStep("signup")}
-            {...steps?.login}
-          />
-        )
-      case "signup":
-        return (
-          <SignupBlock
-            logo={logo}
-            accent={accent}
-            providers={providers}
-            onSubmit={run(onSignup)}
-            onProviderSelect={run(onProviderSelect)}
-            onLogin={() => goToStep("login")}
-            {...steps?.signup}
-          />
-        )
-      case "verify-code":
-        return (
-          <CodeAuthBlock
-            logo={logo}
-            accent={accent}
-            channel={flow.channel}
-            destination={flow.maskedIdentifier ?? undefined}
-            onVerify={run(onVerifyCode)}
-            onResend={run(onResendCode)}
-            onBack={() => goToStep("login")}
-            {...steps?.["verify-code"]}
-          />
-        )
-      case "forgot-password":
-        return (
-          <ForgotPasswordBlock
-            logo={logo}
-            accent={accent}
-            onSubmit={run(onRequestReset)}
-            onBackToLogin={() => goToStep("login")}
-            {...steps?.["forgot-password"]}
-          />
-        )
-      case "update-password":
-        return (
-          <UpdatePasswordBlock
-            logo={logo}
-            accent={accent}
-            onSubmit={run(onUpdatePassword)}
-            onDone={() => goToStep("login")}
-            {...steps?.["update-password"]}
-          />
-        )
-      case "onboarding":
-        return (
-          <OnboardingBlock
-            logo={logo}
-            accent={accent}
-            steps={onboardingSteps}
-            onComplete={run(onOnboardingComplete)}
-            // The flow's success step is the completion screen — showing the
-            // block's own too would stack two checkmarks.
-            showCompleteScreen={false}
-            {...steps?.onboarding}
-          />
-        )
-      case "success":
-        return (
-          success ?? (
-            // Header names the moment, the check screen names the outcome —
-            // the same split the onboarding block's completion screen uses.
-            <AuthCard title={successTitle} logo={logo} accent={accent}>
-              <AuthSuccess
-                title="You're signed in"
-                description={successDescription}
-              />
-            </AuthCard>
-          )
-        )
-    }
-  })()
-
-  return (
-    <MotionConfig reducedMotion="user">
-      <div
-        className={cn("flex w-full justify-center", className)}
-        data-slot="auth-flow"
-        data-step={flow.step}
-      >
-        <MorphStep step={flow.step} className="flex w-full justify-center">
-          {content}
-        </MorphStep>
-      </div>
-    </MotionConfig>
-  )
-}

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

@@ -1,82 +0,0 @@
-/**
- * Session state for the auth blocks — singleton atoms, deliberately NOT a
- * family.
- *
- * A session is one-per-store: one signed-in user per app (per
- * `ExegiaProvider` store; SSR isolation comes from passing a fresh store).
- * Instance keying is for multi-instance components; a family here would
- * imply several concurrent users and be a lie.
- *
- * Import direction: this module is the LEAF — it imports nothing from
- * `auth-flow-atom.ts`. The flow module imports `signInAtom` from here (for
- * `completeAuthFlowAtom`) and defines the composite `endAuthSessionAtom`
- * that pairs `signOutAtom` with a flow reset. `signOutAtom` below clears the
- * session only.
- */
-import { atom } from "jotai"
-
-import type {
-  IAuthSessionState,
-  TAuthSessionStatus,
-  IAuthUser,
-} from "./type"
-
-// ── primitives ───────────────────────────────────────────────────────────
-
-/** `"unknown"` until the app restores or rejects a session at boot. */
-export const authSessionStatusAtom = atom<TAuthSessionStatus>("unknown")
-authSessionStatusAtom.debugLabel = "auth-session/status"
-
-export const authUserAtom = atom<IAuthUser | null>(null)
-authUserAtom.debugLabel = "auth-session/user"
-
-// ── derived ──────────────────────────────────────────────────────────────
-
-export const isAuthenticatedAtom = atom(
-  (get) => get(authSessionStatusAtom) === "authenticated"
-)
-isAuthenticatedAtom.debugLabel = "auth-session/isAuthenticated"
-
-export const authSessionStateAtom = atom<IAuthSessionState>((get) => ({
-  status: get(authSessionStatusAtom),
-  user: get(authUserAtom),
-}))
-authSessionStateAtom.debugLabel = "auth-session/state"
-
-// ── actions ──────────────────────────────────────────────────────────────
-
-export const signInAtom = atom(null, (_get, set, user: IAuthUser) => {
-  set(authUserAtom, user)
-  set(authSessionStatusAtom, "authenticated")
-})
-signInAtom.debugLabel = "auth-session/signIn"
-
-export const updateAuthUserAtom = atom(
-  null,
-  (get, set, patch: Partial<IAuthUser>) => {
-    const user = get(authUserAtom)
-    // No-op when signed out: there is no user to merge into, and inventing
-    // one from a partial patch would fabricate an identity.
-    if (user === null) return
-    set(authUserAtom, { ...user, ...patch })
-  }
-)
-updateAuthUserAtom.debugLabel = "auth-session/updateUser"
-
-/** What an app calls at boot when session restore fails. */
-export const markUnauthenticatedAtom = atom(null, (_get, set) => {
-  set(authSessionStatusAtom, "unauthenticated")
-  set(authUserAtom, null)
-})
-markUnauthenticatedAtom.debugLabel = "auth-session/markUnauthenticated"
-
-/**
- * Clears the session only. Most consumers want `endAuthSessionAtom` from
- * `auth-flow-atom.ts` instead, which also returns the default flow to the
- * login step — the hooks expose that one as `signOut`.
- */
-export const signOutAtom = atom(null, (_get, set) => {
-  set(authUserAtom, null)
-  set(authSessionStatusAtom, "unauthenticated")
-})
-signOutAtom.debugLabel = "auth-session/signOut"