@exegia/corpora-ui 0.6.0 → 0.8.0

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

@@ -0,0 +1,240 @@
+"use client";
+
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+import type { AuthAccent } from "@/lib/auth-accent";
+import {
+  AuthCard,
+  AuthError,
+  AuthSuccess,
+  MorphStep,
+  type AuthStatus,
+} from "./auth-shell";
+import { ProfileStep } from "./onboarding/profile-step";
+
+/** Value a single onboarding field can hold. */
+export type OnboardingValue = string | boolean;
+
+export interface OnboardingSelectOption {
+  value: string;
+  label: string;
+}
+
+interface OnboardingFieldBase {
+  /** Key the value is collected under; unique within the flow. */
+  name: string;
+  label: string;
+  /** Required fields gate the step's advance. */
+  required?: boolean;
+  placeholder?: string;
+  /** Extra validation; return a message to reject, `null` to accept. */
+  validate?: (value: string) => string | null;
+}
+
+export interface OnboardingTextField extends OnboardingFieldBase {
+  kind: "text" | "textarea" | "url";
+}
+
+export interface OnboardingCheckboxField extends OnboardingFieldBase {
+  kind: "checkbox";
+}
+
+export interface OnboardingSelectField extends OnboardingFieldBase {
+  kind: "select";
+  options: OnboardingSelectOption[];
+}
+
+/** Discriminated on `kind`. */
+export type OnboardingFieldConfig =
+  | OnboardingTextField
+  | OnboardingCheckboxField
+  | OnboardingSelectField;
+
+export interface OnboardingStepConfig {
+  /** Unique within the flow and stable across releases. */
+  id: string;
+  title: string;
+  description?: string;
+  fields: OnboardingFieldConfig[];
+}
+
+/** Default configuration: a single required display-name step. */
+export const DEFAULT_ONBOARDING_STEPS: OnboardingStepConfig[] = [
+  {
+    id: "profile",
+    title: "Your profile",
+    fields: [
+      { kind: "text", name: "display_name", label: "Display name", required: true },
+    ],
+  },
+];
+
+export interface OnboardingBlockProps {
+  /** Declared profile steps. */
+  steps?: OnboardingStepConfig[];
+  /** Brand mark rendered above the title. Omit for no logo row at all. */
+  logo?: React.ReactNode;
+  /** Brand accent for the primary action. Omit to keep the default primary. */
+  accent?: AuthAccent;
+  /**
+   * Fires per step as it is submitted. Reject (or throw) to keep the user on
+   * the step and show the error.
+   */
+  onStepSubmit?: (
+    stepId: string,
+    values: Record<string, OnboardingValue>,
+  ) => Promise<void> | void;
+  /** Fires once, after the final step is accepted, with the merged profile. */
+  onComplete?: (profile: Record<string, OnboardingValue>) => Promise<void> | void;
+  /** Shows a brief success screen once onboarding completes. */
+  showCompleteScreen?: boolean;
+  className?: string;
+}
+
+/**
+ * Multi-step profile onboarding: a declared `steps` config renders as
+ * progress-tracked forms with back/forward navigation, per-step submission and
+ * a single completion signal. Drafts survive back-navigation, and the step
+ * heading takes focus on advance so a screen reader announces where the flow
+ * moved.
+ *
+ * Account creation and email confirmation are separate blocks (`SignupBlock`,
+ * `CodeAuthBlock`) — this one picks up once the account exists.
+ */
+export function OnboardingBlock({
+  steps = DEFAULT_ONBOARDING_STEPS,
+  logo,
+  accent,
+  onStepSubmit,
+  onComplete,
+  showCompleteScreen = true,
+  className,
+}: OnboardingBlockProps) {
+  const headingRef = React.useRef<HTMLHeadingElement>(null);
+  // Unsubmitted per-step drafts. Accumulated in a ref so a keystroke does not
+  // re-render the whole flow, then published to state at each navigation —
+  // the only moment the seed values are actually read.
+  const draftsRef = React.useRef<
+    Record<string, Record<string, OnboardingValue>>
+  >({});
+  const [drafts, setDrafts] = React.useState<
+    Record<string, Record<string, OnboardingValue>>
+  >({});
+
+  const [index, setIndex] = React.useState(0);
+  const [values, setValues] = React.useState<Record<string, OnboardingValue>>(
+    {},
+  );
+  const [status, setStatus] = React.useState<AuthStatus>("idle");
+  const [error, setError] = React.useState<string | null>(null);
+
+  const done = status === "success";
+  const step = steps[index];
+  const last = index >= steps.length - 1;
+
+  // Focus the step heading on advance; on error the alert carries the message
+  // and stealing focus would talk over it.
+  React.useEffect(() => {
+    if (error) return;
+    headingRef.current?.focus();
+  }, [index, done, error]);
+
+  async function handleStepSubmit(stepValues: Record<string, OnboardingValue>) {
+    if (!step) return;
+    const merged = { ...values, ...stepValues };
+    setError(null);
+    setStatus("loading");
+    try {
+      await onStepSubmit?.(step.id, stepValues);
+      if (last) await onComplete?.(merged);
+      setValues(merged);
+      delete draftsRef.current[step.id];
+      setDrafts({ ...draftsRef.current });
+      setStatus(last ? "success" : "idle");
+      if (!last) setIndex((current) => current + 1);
+    } catch (cause) {
+      setStatus("idle");
+      setError(
+        cause instanceof Error ? cause.message : "Unable to save your profile.",
+      );
+    }
+  }
+
+  if (done && !showCompleteScreen) return null;
+
+  const heading = done ? "You're all set" : (step?.title ?? "Your profile");
+
+  return (
+    <AuthCard
+      title={heading}
+      description={done ? undefined : step?.description}
+      logo={logo}
+      accent={accent}
+      className={className}
+    >
+      <MorphStep step={done ? "done" : `step-${index}`}>
+        {done ? (
+          <AuthSuccess
+            title="Profile saved"
+            description="Your account is ready and your profile has been saved."
+          />
+        ) : step ? (
+          <div className="flex flex-col gap-4">
+            <nav aria-label="Onboarding progress">
+              <ol className="flex flex-wrap gap-x-3 gap-y-1 text-xs">
+                {steps.map((item, itemIndex) => (
+                  <li
+                    key={item.id}
+                    aria-current={itemIndex === index ? "step" : undefined}
+                    className={cn(
+                      "text-muted-foreground",
+                      itemIndex === index && "font-medium text-foreground",
+                    )}
+                  >
+                    {item.title}
+                    {itemIndex < index && (
+                      <span className="sr-only"> (completed)</span>
+                    )}
+                  </li>
+                ))}
+              </ol>
+            </nav>
+
+            {/* The AuthCard title is the visible heading; this one exists to
+                take focus on advance without duplicating it on screen. */}
+            <h3 ref={headingRef} tabIndex={-1} className="sr-only">
+              {step.title}
+            </h3>
+
+            <AuthError message={error} />
+
+            <ProfileStep
+              key={step.id}
+              step={step}
+              values={{ ...values, ...drafts[step.id] }}
+              submitting={status === "loading"}
+              submitLabel={last ? "Finish" : "Continue"}
+              onBack={
+                index > 0
+                  ? () => {
+                      setError(null);
+                      setDrafts({ ...draftsRef.current });
+                      setIndex((current) => current - 1);
+                    }
+                  : undefined
+              }
+              onDraftChange={(name, value) => {
+                draftsRef.current[step.id] = {
+                  ...draftsRef.current[step.id],
+                  [name]: value,
+                };
+              }}
+              onSubmit={handleStepSubmit}
+            />
+          </div>
+        ) : null}
+      </MorphStep>
+    </AuthCard>
+  );
+}

package/src/components/blocks/auth/passkey-manager-block.tsx

@@ -0,0 +1,334 @@
+"use client";
+
+import { AnimatePresence, MotionConfig, motion } from "motion/react";
+import * as React from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardDescription,
+  CardHeader,
+  CardPanel,
+  CardTitle,
+} from "@/components/ui/card";
+import { Field, FieldError, FieldLabel } from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import { Spinner } from "@/components/ui/spinner";
+import { cn } from "@/lib/utils";
+import { AuthError, EASE, Reveal } from "./auth-shell";
+
+/** One registered passkey, as rendered by {@link PasskeyManagerBlock}. */
+export interface PasskeyRecord {
+  id: string;
+  /** Server-derived name; falls back to "Passkey" when absent. */
+  name?: string | null;
+  /** ISO timestamps. Unparseable values are simply not shown. */
+  createdAt?: string | null;
+  lastUsedAt?: string | null;
+}
+
+export interface PasskeyManagerBlockProps {
+  title?: string;
+  description?: string;
+  /** The account's passkeys, newest first. */
+  passkeys?: PasskeyRecord[];
+  /** Whether this device can register passkeys at all. */
+  available?: boolean;
+  /** Shows the loading row instead of the list. */
+  loading?: boolean;
+  /**
+   * Reject (or throw) to show the error. Resolving with `{ cancelled: true }`
+   * returns silently to idle — a dismissed OS prompt is not a failure.
+   */
+  onRegister?: () => Promise<{ cancelled?: boolean } | void> | void;
+  onRename?: (id: string, name: string) => Promise<void> | void;
+  onDelete?: (id: string) => Promise<void> | void;
+  className?: string;
+}
+
+const NAME_MAX = 120;
+
+const LAST_PASSKEY_WARNING =
+  "This is your last passkey. After deleting it you won't be able to sign in with a passkey until you register a new one.";
+
+function formatDate(iso: string | null | undefined): string | null {
+  if (!iso) return null;
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? null : date.toLocaleDateString();
+}
+
+/**
+ * Settings panel for the passkeys on an account: register, inline rename with
+ * field-level validation, and delete behind an explicit confirmation. Deleting
+ * the last passkey is allowed — it is the account's passkey method that goes
+ * away, not its only way in — so the confirmation carries a warning instead of
+ * a block.
+ */
+export function PasskeyManagerBlock({
+  title = "Passkeys",
+  description = "Sign in without a password using your device's biometrics or security key.",
+  passkeys = [],
+  available = true,
+  loading = false,
+  onRegister,
+  onRename,
+  onDelete,
+  className,
+}: PasskeyManagerBlockProps) {
+  const [error, setError] = React.useState<string | null>(null);
+  const [busy, setBusy] = React.useState(false);
+  const [registering, setRegistering] = React.useState(false);
+  const [renamingId, setRenamingId] = React.useState<string | null>(null);
+  const [renameValue, setRenameValue] = React.useState("");
+  const [renameError, setRenameError] = React.useState<string | null>(null);
+  const [confirmingId, setConfirmingId] = React.useState<string | null>(null);
+
+  const lastPasskey = passkeys.length === 1;
+
+  async function run(action: () => Promise<unknown> | unknown) {
+    if (busy) return { ok: false } as const;
+    setError(null);
+    setBusy(true);
+    try {
+      const result = await action();
+      return { ok: true, result } as const;
+    } catch (cause) {
+      setError(
+        cause instanceof Error ? cause.message : "Something went wrong.",
+      );
+      return { ok: false } as const;
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function handleRegister() {
+    setRegistering(true);
+    await run(() => onRegister?.());
+    setRegistering(false);
+  }
+
+  function startRename(passkey: PasskeyRecord) {
+    setConfirmingId(null);
+    setRenamingId(passkey.id);
+    setRenameValue(passkey.name ?? "");
+    setRenameError(null);
+  }
+
+  async function submitRename(id: string) {
+    const name = renameValue.trim();
+    if (name.length < 1 || name.length > NAME_MAX) {
+      setRenameError(`Name must be between 1 and ${NAME_MAX} characters.`);
+      return;
+    }
+    const outcome = await run(() => onRename?.(id, name));
+    if (!outcome.ok) return;
+    setRenamingId(null);
+    setRenameError(null);
+  }
+
+  async function confirmDelete(id: string) {
+    const outcome = await run(() => onDelete?.(id));
+    setConfirmingId(null);
+    if (!outcome.ok) return;
+    if (renamingId === id) setRenamingId(null);
+  }
+
+  return (
+    <MotionConfig reducedMotion="user">
+      <Card className={cn("w-full", className)} data-slot="auth-block">
+        <CardHeader>
+          <CardTitle>{title}</CardTitle>
+          <CardDescription>{description}</CardDescription>
+        </CardHeader>
+        <CardPanel>
+          {!available ? (
+            <p className="text-sm text-muted-foreground">
+              Passkeys aren&apos;t available on this device. You can manage them
+              from a device that supports passkeys.
+            </p>
+          ) : loading ? (
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Spinner className="size-4" />
+              Loading passkeys…
+            </div>
+          ) : (
+            <motion.div
+              layout
+              transition={{ duration: 0.3, ease: EASE }}
+              className="flex flex-col gap-3"
+            >
+              <AuthError message={error} />
+
+              {passkeys.length > 0 ? (
+                <ul aria-label="Passkeys" className="flex flex-col gap-2">
+                  <AnimatePresence initial={false}>
+                    {passkeys.map((passkey, index) => {
+                      const name = passkey.name ?? "Passkey";
+                      const created = formatDate(passkey.createdAt);
+                      const lastUsed = formatDate(passkey.lastUsedAt);
+                      return (
+                        <motion.li
+                          key={passkey.id}
+                          layout
+                          className="flex flex-col gap-2 rounded-lg border px-3 py-2"
+                          initial={{ opacity: 0, y: -4 }}
+                          animate={{ opacity: 1, y: 0 }}
+                          exit={{ opacity: 0, y: -4 }}
+                          // 40ms per row, capped so a long list never leaves
+                          // the last row arriving noticeably late.
+                          transition={{
+                            duration: 0.25,
+                            ease: EASE,
+                            delay: Math.min(index, 5) * 0.04,
+                          }}
+                        >
+                          <div className="flex items-center justify-between gap-3">
+                            <div className="flex min-w-0 flex-col">
+                              <span className="truncate font-medium text-sm">
+                                {name}
+                              </span>
+                              <span className="text-xs text-muted-foreground">
+                                {created ? `Added ${created}` : null}
+                                {created && lastUsed ? " · " : null}
+                                {lastUsed ? `Last used ${lastUsed}` : null}
+                              </span>
+                            </div>
+                            <div className="flex shrink-0 gap-2">
+                              <Button
+                                aria-label={`Rename ${name}`}
+                                size="sm"
+                                type="button"
+                                variant="outline"
+                                disabled={busy}
+                                onClick={() => startRename(passkey)}
+                              >
+                                Rename
+                              </Button>
+                              <Button
+                                aria-label={`Delete ${name}`}
+                                size="sm"
+                                type="button"
+                                variant="destructive-outline"
+                                disabled={busy}
+                                onClick={() => {
+                                  setRenamingId(null);
+                                  setConfirmingId(passkey.id);
+                                }}
+                              >
+                                Delete
+                              </Button>
+                            </div>
+                          </div>
+
+                          <Reveal show={renamingId === passkey.id}>
+                            <form
+                              className="flex items-start gap-2 pt-1"
+                              onSubmit={(event) => {
+                                event.preventDefault();
+                                void submitRename(passkey.id);
+                              }}
+                            >
+                              <Field
+                                className="min-w-0 grow"
+                                invalid={Boolean(renameError)}
+                              >
+                                <FieldLabel className="sr-only">
+                                  Passkey name
+                                </FieldLabel>
+                                <Input
+                                  aria-label="Passkey name"
+                                  aria-invalid={renameError ? true : undefined}
+                                  autoFocus
+                                  disabled={busy}
+                                  maxLength={NAME_MAX + 1}
+                                  value={renameValue}
+                                  onChange={(event) =>
+                                    setRenameValue(event.target.value)
+                                  }
+                                />
+                                {renameError && (
+                                  <FieldError match>{renameError}</FieldError>
+                                )}
+                              </Field>
+                              <Button size="sm" type="submit" loading={busy}>
+                                Save
+                              </Button>
+                              <Button
+                                size="sm"
+                                type="button"
+                                variant="ghost"
+                                disabled={busy}
+                                onClick={() => setRenamingId(null)}
+                              >
+                                Cancel
+                              </Button>
+                            </form>
+                          </Reveal>
+
+                          <Reveal show={confirmingId === passkey.id}>
+                            <div
+                              className="flex flex-col gap-2 rounded-lg bg-muted/50 p-2"
+                              role="alertdialog"
+                              aria-label={`Confirm deleting ${name}`}
+                            >
+                              <p className="text-sm">
+                                Delete this passkey? It can no longer be used to
+                                sign in.
+                              </p>
+                              {lastPasskey && (
+                                <p className="text-xs text-destructive-foreground">
+                                  {LAST_PASSKEY_WARNING}
+                                </p>
+                              )}
+                              <div className="flex gap-2">
+                                <Button
+                                  size="sm"
+                                  type="button"
+                                  variant="destructive"
+                                  loading={busy}
+                                  onClick={() => void confirmDelete(passkey.id)}
+                                >
+                                  Delete passkey
+                                </Button>
+                                <Button
+                                  size="sm"
+                                  type="button"
+                                  variant="ghost"
+                                  disabled={busy}
+                                  onClick={() => setConfirmingId(null)}
+                                >
+                                  Keep it
+                                </Button>
+                              </div>
+                            </div>
+                          </Reveal>
+                        </motion.li>
+                      );
+                    })}
+                  </AnimatePresence>
+                </ul>
+              ) : (
+                <p className="text-sm text-muted-foreground">
+                  No passkeys registered yet. Add one to sign in without a
+                  password.
+                </p>
+              )}
+
+              <Button
+                className="w-full"
+                type="button"
+                variant="outline"
+                disabled={busy}
+                loading={registering}
+                onClick={() => void handleRegister()}
+              >
+                Add a passkey
+              </Button>
+            </motion.div>
+          )}
+        </CardPanel>
+      </Card>
+    </MotionConfig>
+  );
+}

package/src/components/blocks/auth/passkey-sign-in-block.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { FingerprintIcon } from "lucide-react";
+import * as React from "react";
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { AuthError, Reveal } from "./auth-shell";
+
+export interface PasskeySignInBlockProps {
+  /**
+   * Whether this device can use passkeys. `false` renders nothing at all —
+   * a passkey button that is guaranteed to fail is worse than no button.
+   */
+  available?: boolean;
+  /** Button label. */
+  label?: string;
+  /**
+   * Reject (or throw) to show the inline error. Resolving with
+   * `{ cancelled: true }` returns silently to idle — a dismissed OS prompt is
+   * not a failure and must not surface an error.
+   */
+  onSignIn?: () => Promise<{ cancelled?: boolean } | void> | void;
+  /** Hint shown under an error, pointing at the remaining sign-in methods. */
+  fallbackHint?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * Passkey sign-in entry point — a single button plus its error state, sized
+ * to drop into a login card next to the password form rather than to stand on
+ * its own. Renders `null` while passkeys are unavailable.
+ */
+export function PasskeySignInBlock({
+  available = true,
+  label = "Sign in with a passkey",
+  onSignIn,
+  fallbackHint = "You can still sign in with your other methods below.",
+  className,
+}: PasskeySignInBlockProps) {
+  const [error, setError] = React.useState<string | null>(null);
+  const [loading, setLoading] = React.useState(false);
+
+  if (!available) return null;
+
+  async function handleClick() {
+    if (loading) return;
+    setError(null);
+    setLoading(true);
+    try {
+      await onSignIn?.();
+    } catch (cause) {
+      setError(
+        cause instanceof Error
+          ? cause.message
+          : "Unable to sign in with a passkey.",
+      );
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div className={cn("flex w-full flex-col gap-2", className)}>
+      <Button
+        variant="outline"
+        className="w-full"
+        type="button"
+        loading={loading}
+        onClick={() => void handleClick()}
+      >
+        <FingerprintIcon aria-hidden="true" />
+        <span className="flex-1">{label}</span>
+      </Button>
+      <AuthError message={error} />
+      <Reveal show={Boolean(error) && Boolean(fallbackHint)}>
+        <p className="text-xs text-muted-foreground">{fallbackHint}</p>
+      </Reveal>
+    </div>
+  );
+}