@exegia/corpora-ui 0.20.0 → 0.22.0

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

@@ -0,0 +1,82 @@
+/**
+ * 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 {
+  AuthSessionState,
+  AuthSessionStatus,
+  AuthUser,
+} from "./auth-state-type"
+
+// ── primitives ───────────────────────────────────────────────────────────
+
+/** `"unknown"` until the app restores or rejects a session at boot. */
+export const authSessionStatusAtom = atom<AuthSessionStatus>("unknown")
+authSessionStatusAtom.debugLabel = "auth-session/status"
+
+export const authUserAtom = atom<AuthUser | 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<AuthSessionState>((get) => ({
+  status: get(authSessionStatusAtom),
+  user: get(authUserAtom),
+}))
+authSessionStateAtom.debugLabel = "auth-session/state"
+
+// ── actions ──────────────────────────────────────────────────────────────
+
+export const signInAtom = atom(null, (_get, set, user: AuthUser) => {
+  set(authUserAtom, user)
+  set(authSessionStatusAtom, "authenticated")
+})
+signInAtom.debugLabel = "auth-session/signIn"
+
+export const updateAuthUserAtom = atom(
+  null,
+  (get, set, patch: Partial<AuthUser>) => {
+    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"

package/src/components/blocks/auth/auth-state-type.ts

@@ -0,0 +1,97 @@
+/**
+ * Types for the auth coordination state (`auth-flow-atom.ts` /
+ * `auth-session-atom.ts`).
+ *
+ * This file stays dependency-free of the atom modules: types only, no atom
+ * imports. The auth blocks themselves are unaware of this layer — they keep
+ * field values in local `useState` — these types describe the coordination
+ * state an app wires *around* the blocks.
+ */
+import type { AuthStatus } from "./auth-shell"
+
+export type AuthFlowId = string
+
+/** Which auth block the app is showing. */
+export type AuthFlowStep =
+  | "login"
+  | "signup"
+  | "verify-code"
+  | "forgot-password"
+  | "update-password"
+  | "onboarding"
+  | "success"
+
+export type AuthFlowChannel = "email" | "sms"
+
+export interface AuthFlowState {
+  step: AuthFlowStep
+  /** The identifier in flight — an email or phone number. Cleared by reset
+   * and by signOut. Never store passwords or codes here. */
+  identifier: string | null
+  /** `identifier` masked for display — "y•••@example.com", "•••1234". */
+  maskedIdentifier: string | null
+  channel: AuthFlowChannel
+  status: AuthStatus
+  error: string | null
+}
+
+/** Options for `beginAuthVerificationAtom` / `beginVerification`. */
+export interface BeginAuthVerificationOptions {
+  identifier: string
+  /** @default "email" */
+  channel?: AuthFlowChannel
+  /** @default "verify-code" */
+  step?: AuthFlowStep
+}
+
+/** What `useAuthFlowActions(flowId)` returns. */
+export interface AuthFlowActions {
+  /** Show a step; resets status to `"idle"` and clears the error. Keeps the
+   * identifier. */
+  goToStep: (step: AuthFlowStep) => void
+  /** Record the identifier in flight and move to the verification step. */
+  beginVerification: (options: BeginAuthVerificationOptions) => void
+  /** Mark the flow `"loading"` while an async attempt is in flight. */
+  beginAttempt: () => void
+  /** Mark the flow `"error"` with a message. */
+  fail: (message: string) => void
+  /** Mark the flow `"success"`; when a user is given, also sign the session
+   * in. */
+  complete: (user?: AuthUser) => void
+  /** Back to the initial values (login step, no identifier). */
+  reset: () => void
+}
+
+/** The signed-in identity, kept for the whole session. Structurally
+ * assignable to `ProfileCardUser`, so it drops into `ProfileCardBlock`. */
+export interface AuthUser {
+  id: string
+  name: string
+  /** Secondary line — a handle, an email, a role. */
+  username?: string
+  email?: string
+  /** Avatar image URL. */
+  avatar?: string
+  initials?: string
+  /** App-specific extras the library never interprets. */
+  metadata?: Record<string, unknown>
+}
+
+/** `unknown` until the app restores or rejects a session at boot. */
+export type AuthSessionStatus = "unknown" | "unauthenticated" | "authenticated"
+
+export interface AuthSessionState {
+  status: AuthSessionStatus
+  user: AuthUser | null
+}
+
+/** What `useAuthSessionActions()` returns. */
+export interface AuthSessionActions {
+  signIn: (user: AuthUser) => void
+  /** Shallow-merge a patch into the signed-in user; no-op when signed out. */
+  updateUser: (patch: Partial<AuthUser>) => void
+  /** What an app calls at boot when session restore fails. */
+  markUnauthenticated: () => void
+  /** Sign out AND return the default auth flow to the login step. */
+  signOut: () => void
+}

package/src/components/blocks/auth/auth-state.ts

@@ -0,0 +1,52 @@
+/**
+ * Public barrel for the auth coordination state. Explicit named exports
+ * only — never `export *` from the atom modules, so internals can move
+ * without becoming a breaking-change surface.
+ */
+export {
+  DEFAULT_AUTH_FLOW_ID,
+  authFlowChannelAtom,
+  authFlowErrorAtom,
+  authFlowIdentifierAtom,
+  authFlowMaskedIdentifierAtom,
+  authFlowStateAtom,
+  authFlowStatusAtom,
+  authFlowStepAtom,
+  beginAuthAttemptAtom,
+  beginAuthVerificationAtom,
+  completeAuthFlowAtom,
+  endAuthSessionAtom,
+  failAuthFlowAtom,
+  goToAuthStepAtom,
+  maskAuthIdentifier,
+  removeAuthFlowInstance,
+  resetAuthFlowAtom,
+} from "./auth-flow-atom"
+export {
+  authSessionStateAtom,
+  authSessionStatusAtom,
+  authUserAtom,
+  isAuthenticatedAtom,
+  markUnauthenticatedAtom,
+  signInAtom,
+  signOutAtom,
+  updateAuthUserAtom,
+} from "./auth-session-atom"
+export {
+  useAuthFlow,
+  useAuthFlowActions,
+  useAuthSession,
+  useAuthSessionActions,
+} from "./use-auth-state"
+export type {
+  AuthFlowActions,
+  AuthFlowChannel,
+  AuthFlowId,
+  AuthFlowState,
+  AuthFlowStep,
+  AuthSessionActions,
+  AuthSessionState,
+  AuthSessionStatus,
+  AuthUser,
+  BeginAuthVerificationOptions,
+} from "./auth-state-type"

package/src/components/blocks/auth/use-auth-state.ts

@@ -0,0 +1,127 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  DEFAULT_AUTH_FLOW_ID,
+  authFlowStateAtom,
+  beginAuthAttemptAtom,
+  beginAuthVerificationAtom,
+  completeAuthFlowAtom,
+  endAuthSessionAtom,
+  failAuthFlowAtom,
+  goToAuthStepAtom,
+  resetAuthFlowAtom,
+} from "./auth-flow-atom"
+import {
+  authSessionStateAtom,
+  isAuthenticatedAtom,
+  markUnauthenticatedAtom,
+  signInAtom,
+  updateAuthUserAtom,
+} from "./auth-session-atom"
+import type {
+  AuthFlowActions,
+  AuthFlowId,
+  AuthFlowState,
+  AuthSessionActions,
+  AuthSessionState,
+} from "./auth-state-type"
+
+/**
+ * Read the auth flow registered under `flowId` from anywhere below
+ * `ExegiaProvider`. Pairs with `useAuthFlowActions` to wire the auth blocks
+ * into one flow — the blocks keep passwords and codes in local state, the
+ * flow tracks which block shows and what identifier is in flight:
+ *
+ * ```tsx
+ * const flow = useAuthFlow()
+ * const { beginVerification, complete, fail } = useAuthFlowActions()
+ *
+ * {flow.step === "login" && (
+ *   <LoginBlock
+ *     onSubmit={async ({ email }) => {
+ *       await api.requestCode(email)
+ *       beginVerification({ identifier: email })
+ *     }}
+ *   />
+ * )}
+ * {flow.step === "verify-code" && (
+ *   <CodeAuthBlock
+ *     destination={flow.maskedIdentifier ?? undefined}
+ *     onVerify={async (code) => complete(await api.verify(code))}
+ *   />
+ * )}
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on any
+ * change. A component that reads one field should subscribe to that field's
+ * atom instead: `useAtomValue(authFlowStepAtom(flowId))`.
+ */
+export function useAuthFlow(
+  flowId: AuthFlowId = DEFAULT_AUTH_FLOW_ID
+): AuthFlowState {
+  return useAtomValue(authFlowStateAtom(flowId))
+}
+
+/**
+ * Drive the auth flow registered under `flowId` from anywhere. Writes only —
+ * the caller never re-renders when the flow changes. See `useAuthFlow` for
+ * the intended wiring; a block's submit handler typically runs
+ * `beginAttempt()` → the API call → `complete(user)` or `fail(message)`.
+ */
+export function useAuthFlowActions(
+  flowId: AuthFlowId = DEFAULT_AUTH_FLOW_ID
+): AuthFlowActions {
+  const goToStep = useSetAtom(goToAuthStepAtom(flowId))
+  const beginVerification = useSetAtom(beginAuthVerificationAtom(flowId))
+  const beginAttempt = useSetAtom(beginAuthAttemptAtom(flowId))
+  const fail = useSetAtom(failAuthFlowAtom(flowId))
+  const complete = useSetAtom(completeAuthFlowAtom(flowId))
+  const reset = useSetAtom(resetAuthFlowAtom(flowId))
+
+  return React.useMemo(
+    () => ({
+      goToStep,
+      beginVerification,
+      beginAttempt,
+      fail,
+      complete,
+      reset,
+    }),
+    [goToStep, beginVerification, beginAttempt, fail, complete, reset]
+  )
+}
+
+/**
+ * Read the session: `status` (`"unknown"` until the app restores or rejects
+ * a session at boot), the signed-in `user`, and derived `isAuthenticated`.
+ */
+export function useAuthSession(): AuthSessionState & {
+  isAuthenticated: boolean
+} {
+  const state = useAtomValue(authSessionStateAtom)
+  const isAuthenticated = useAtomValue(isAuthenticatedAtom)
+  return React.useMemo(
+    () => ({ ...state, isAuthenticated }),
+    [state, isAuthenticated]
+  )
+}
+
+/**
+ * Drive the session. Writes only. `signOut` is the composite
+ * `endAuthSessionAtom`: it clears the session AND returns the default flow
+ * to the login step — the one to wire to a logout button.
+ */
+export function useAuthSessionActions(): AuthSessionActions {
+  const signIn = useSetAtom(signInAtom)
+  const updateUser = useSetAtom(updateAuthUserAtom)
+  const markUnauthenticated = useSetAtom(markUnauthenticatedAtom)
+  const signOut = useSetAtom(endAuthSessionAtom)
+
+  return React.useMemo(
+    () => ({ signIn, updateUser, markUnauthenticated, signOut }),
+    [signIn, updateUser, markUnauthenticated, signOut]
+  )
+}

package/src/components/blocks/layout.ts

@@ -1,7 +1,35 @@
-import ShellLayout from "@/components/blocks/shell"
+import ShellLayout, {
+  AnimatedPanel,
+  AnimatedPanelTrigger,
+  useShellPanels,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitMeasuredAtom,
+  shellFitMetricsAtom,
+  shellFitPanelBoundsAtom,
+  shellFitPanelWidthAtom,
+  shellFitRequestedWidthAtom,
+  shellFitStateAtom,
+} from "@/components/blocks/shell"
 
 const Layout = {
-  Main: ShellLayout
+  Main: ShellLayout,
+  Panel: AnimatedPanel,
+  Trigger: AnimatedPanelTrigger,
+}
+
+export {
+  useShellPanels,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitMeasuredAtom,
+  shellFitMetricsAtom,
+  shellFitPanelBoundsAtom,
+  shellFitPanelWidthAtom,
+  shellFitRequestedWidthAtom,
+  shellFitStateAtom,
 }
 
 export default Layout