@exegia/corpora-ui 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {

package/src/components/beste/piece/browser-frame.tsx

@@ -19,7 +19,7 @@ export function BrowserFrame({
         className
       )}
     >
-      <div className="relative flex max-h-[500px] min-h-32 w-full flex-col overflow-hidden rounded-lg border border-border bg-neutral-50 shadow-lg dark:bg-neutral-900">
+      <div className="relative flex min-h-32 w-full flex-col overflow-hidden rounded-lg border border-border bg-neutral-50 shadow-lg dark:bg-neutral-900">
         <div
           id="title-bar"
           className={cn(

package/src/components/beste/piece/utils.ts

@@ -6,15 +6,15 @@ export const titleBarStyle = (
   component: "title" | "frame"
 ): ClassNameValue => {
   const titleBarClassName: Record<TitleStyleType, ClassNameValue> = {
-    titlebar: "",
+    titlebar: "relative",
     hidden: "top-0 left-0 absolute",
-    expanded: "",
+    expanded: "relative",
   }
 
   const bodyClassName: Record<TitleStyleType, ClassNameValue> = {
-    titlebar: "",
+    titlebar: "relative",
     hidden: "",
-    expanded: "",
+    expanded: "relative",
   }
 
   return component == "title" ? titleBarClassName[style] : bodyClassName[style]

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

@@ -0,0 +1,183 @@
+import { describe, expect, mock, test } from "bun:test"
+import { render, screen, waitFor } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { createStore } from "jotai"
+
+import { ExegiaProvider } from "@/state"
+import { AuthFlowBlock } from "../auth-flow-block"
+import {
+  DEFAULT_AUTH_FLOW_ID,
+  authFlowStepAtom,
+  authUserAtom,
+  goToAuthStepAtom,
+  isAuthenticatedAtom,
+} from "../auth-state"
+import type { AuthUser } from "../auth-state"
+
+const USER: AuthUser = {
+  id: "u-1",
+  name: "Yona Appletree",
+  email: "yo@example.com",
+}
+
+type Store = ReturnType<typeof createStore>
+
+function mount(store: Store, ui: React.ReactElement) {
+  return render(<ExegiaProvider store={store}>{ui}</ExegiaProvider>)
+}
+
+/** MorphStep exits run under AnimatePresence; happy-dom serves stale
+ * selector-cache results to `waitFor` queries that start while an exit is
+ * still running — let the exit settle on real timers, then query once. */
+const settleExit = () => new Promise((resolve) => setTimeout(resolve, 400))
+
+async function submitLogin(email = "yo@example.com", password = "hunter22!") {
+  const user = userEvent.setup()
+  await user.type(screen.getByLabelText("Email"), email)
+  await user.type(screen.getByLabelText("Password"), password)
+  await user.click(screen.getByRole("button", { name: "Login" }))
+  return user
+}
+
+describe("AuthFlowBlock · step switching", () => {
+  test("renders the login step by default with pre-wired navigation", async () => {
+    const user = userEvent.setup()
+    const store = createStore()
+    mount(store, <AuthFlowBlock />)
+
+    expect(screen.getByText("Login to your account")).toBeDefined()
+
+    await user.click(screen.getByRole("button", { name: "Sign up" }))
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe("signup")
+    await settleExit()
+    expect(screen.getByText("Create your account")).toBeDefined()
+
+    // Signup's footer goes back to login.
+    await user.click(screen.getByRole("button", { name: "Login" }))
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe("login")
+    await settleExit()
+
+    // The forgot-password link sits in the password row, which the login
+    // block reveals once the email is valid.
+    await user.type(screen.getByLabelText("Email"), "yo@example.com")
+    await user.click(
+      await screen.findByRole("button", { name: "Forgot password?" })
+    )
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe(
+      "forgot-password"
+    )
+  })
+
+  test("follows the store when something else drives the flow", async () => {
+    const store = createStore()
+    mount(store, <AuthFlowBlock />)
+
+    store.set(goToAuthStepAtom(DEFAULT_AUTH_FLOW_ID), "update-password")
+    expect(await screen.findByText("Update your password")).toBeDefined()
+  })
+})
+
+describe("AuthFlowBlock · directives", () => {
+  test("{ verify } moves to the code step with the masked destination", async () => {
+    const store = createStore()
+    const onLogin = mock(() => ({
+      verify: { identifier: "yo@example.com" } as const,
+    }))
+    mount(store, <AuthFlowBlock onLogin={onLogin} />)
+
+    await submitLogin()
+    expect(onLogin).toHaveBeenCalledTimes(1)
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe(
+      "verify-code"
+    )
+    // The masked identifier feeds CodeAuthBlock's destination copy.
+    expect(await screen.findByText(/y•••@example\.com/)).toBeDefined()
+  })
+
+  test("{ user } completes the flow and signs the session in", async () => {
+    const store = createStore()
+    mount(store, <AuthFlowBlock onLogin={() => ({ user: USER })} />)
+
+    await submitLogin()
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe("success")
+    expect(store.get(isAuthenticatedAtom)).toBe(true)
+    expect(store.get(authUserAtom)?.id).toBe("u-1")
+    await settleExit()
+    expect(screen.getByText("Welcome")).toBeDefined()
+    expect(screen.getByText("You're signed in")).toBeDefined()
+  })
+
+  test("a resolved handler without a directive stays on the step", async () => {
+    const store = createStore()
+    mount(store, <AuthFlowBlock onLogin={() => undefined} />)
+
+    await submitLogin()
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe("login")
+  })
+
+  test("a rejected handler stays on the step and shows the block's error", async () => {
+    const store = createStore()
+    mount(
+      store,
+      <AuthFlowBlock
+        onLogin={() => {
+          throw new Error("Wrong password")
+        }}
+      />
+    )
+
+    await submitLogin()
+    expect(store.get(authFlowStepAtom(DEFAULT_AUTH_FLOW_ID))).toBe("login")
+    expect(await screen.findByText("Wrong password")).toBeDefined()
+    expect(store.get(isAuthenticatedAtom)).toBe(false)
+  })
+})
+
+describe("AuthFlowBlock · customization", () => {
+  test("steps overrides merge over the wiring", async () => {
+    const store = createStore()
+    mount(
+      store,
+      <AuthFlowBlock
+        steps={{ login: { title: "Sign in to Corpora", providers: [] } }}
+      />
+    )
+
+    expect(screen.getByText("Sign in to Corpora")).toBeDefined()
+  })
+
+  test("renderStep replaces a step; undefined keeps the default", async () => {
+    const store = createStore()
+    mount(
+      store,
+      <AuthFlowBlock
+        renderStep={(step) =>
+          step === "success" ? <p>Custom landing</p> : undefined
+        }
+      />
+    )
+
+    expect(screen.getByText("Login to your account")).toBeDefined()
+    store.set(goToAuthStepAtom(DEFAULT_AUTH_FLOW_ID), "success")
+    expect(await screen.findByText("Custom landing")).toBeDefined()
+  })
+
+  test("two flow ids orchestrate independently", async () => {
+    const store = createStore()
+    mount(
+      store,
+      <>
+        <AuthFlowBlock flowId="page" />
+        <AuthFlowBlock flowId="modal" />
+      </>
+    )
+
+    store.set(goToAuthStepAtom("modal"), "forgot-password")
+    expect(await screen.findByText("Reset your password")).toBeDefined()
+    // The page flow is still on login.
+    await waitFor(() =>
+      expect(screen.getByText("Login to your account")).toBeDefined()
+    )
+    expect(store.get(authFlowStepAtom("page"))).toBe("login")
+  })
+})

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

@@ -0,0 +1,296 @@
+"use client"
+
+import * as React from "react"
+import { MotionConfig } from "motion/react"
+
+import type { SocialProvider } from "@/components/composed/social-providers"
+import type { AuthAccent } from "@/lib/auth-accent"
+import { cn } from "@/lib/utils"
+import { AuthCard, AuthSuccess, MorphStep } from "./auth-shell"
+import { CodeAuthBlock, type CodeAuthBlockProps } from "./code-auth-block"
+import {
+  ForgotPasswordBlock,
+  type ForgotPasswordBlockProps,
+} from "./forgot-password-block"
+import { LoginBlock, type LoginBlockProps } from "./login-block"
+import {
+  OnboardingBlock,
+  type OnboardingBlockProps,
+  type OnboardingStepConfig,
+  type OnboardingValue,
+} from "./onboarding-block"
+import { SignupBlock, type SignupBlockProps } from "./signup-block"
+import {
+  UpdatePasswordBlock,
+  type UpdatePasswordBlockProps,
+} from "./update-password-block"
+import type {
+  AuthFlowId,
+  AuthFlowState,
+  AuthFlowStep,
+  AuthUser,
+  BeginAuthVerificationOptions,
+} from "./auth-state-type"
+import { useAuthFlow, useAuthFlowActions } from "./use-auth-state"
+
+/**
+ * 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").
+ */
+export type AuthFlowDirective =
+  | { user: AuthUser }
+  | { verify: BeginAuthVerificationOptions }
+  | { step: AuthFlowStep }
+  | void
+
+export type AuthFlowHandler<Data = void> = (
+  data: Data
+) => Promise<AuthFlowDirective> | AuthFlowDirective
+
+/** Per-step prop overrides, merged over the orchestrator's wiring — spread
+ * last, so an app can restyle a block or unhook a default navigation link
+ * (`{ login: { onSignup: undefined } }` removes the sign-up hand-off). */
+export interface AuthFlowStepOverrides {
+  login?: Partial<LoginBlockProps>
+  signup?: Partial<SignupBlockProps>
+  "verify-code"?: Partial<CodeAuthBlockProps>
+  "forgot-password"?: Partial<ForgotPasswordBlockProps>
+  "update-password"?: Partial<UpdatePasswordBlockProps>
+  onboarding?: Partial<OnboardingBlockProps>
+}
+
+export interface AuthFlowBlockProps {
+  /** Which flow instance to orchestrate. The default flow unless a re-auth
+   * modal or a second surface needs its own. */
+  flowId?: AuthFlowId
+  /** Brand mark handed to every step's card. */
+  logo?: React.ReactNode
+  /** Brand accent handed to every step's card. */
+  accent?: AuthAccent
+  /** Social providers offered on the login and signup steps. */
+  providers?: SocialProvider[]
+  /** The login attempt. Resolve with a directive; reject to show the error
+   * in the block. */
+  onLogin?: AuthFlowHandler<{
+    email: string
+    password: string
+    remember: boolean
+  }>
+  /** The signup attempt. */
+  onSignup?: AuthFlowHandler<{ name: string; email: string; password: string }>
+  /** A social provider chosen on the login or signup step. */
+  onProviderSelect?: AuthFlowHandler<SocialProvider>
+  /** The forgot-password request. Resolving without a directive stays on the
+   * step (the block shows its own "link sent" state). */
+  onRequestReset?: AuthFlowHandler<{ email: string }>
+  /** The code entered on the verification step. */
+  onVerifyCode?: AuthFlowHandler<string>
+  /** "Resend code" on the verification step. */
+  onResendCode?: AuthFlowHandler
+  /** The update-password submit. */
+  onUpdatePassword?: AuthFlowHandler<{ password: string }>
+  /** Onboarding finished, with the merged profile. */
+  onOnboardingComplete?: AuthFlowHandler<Record<string, OnboardingValue>>
+  /** Declared onboarding steps, handed to `OnboardingBlock`. */
+  onboardingSteps?: OnboardingStepConfig[]
+  /** Per-step prop overrides, merged over the orchestrator's wiring. */
+  steps?: AuthFlowStepOverrides
+  /** Replace any step's UI entirely; return `undefined` to keep the default
+   * for that step. Receives the flow state for destination copy etc. */
+  renderStep?: (
+    step: AuthFlowStep,
+    flow: AuthFlowState
+  ) => React.ReactNode | undefined
+  /** Replaces the whole default success card. */
+  success?: React.ReactNode
+  /** Card title of the default success step. */
+  successTitle?: string
+  /** Body under the default success step's "You're signed in" check. */
+  successDescription?: string
+  className?: string
+}
+
+/**
+ * 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 AuthFlowDirective}.
+ *
+ * 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,
+}: AuthFlowBlockProps): React.ReactElement {
+  const flow = useAuthFlow(flowId)
+  const { goToStep, beginVerification, complete } = useAuthFlowActions(flowId)
+
+  const apply = React.useCallback(
+    (directive: AuthFlowDirective) => {
+      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: AuthFlowHandler<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>
+  )
+}