@exegia/corpora-ui 0.6.0 → 0.7.0

package/src/components/blocks/auth/linked-accounts-block.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+import { AnimatePresence, MotionConfig, motion } from "motion/react";
+import * as React from "react";
+
+import {
+  SOCIAL_PROVIDERS,
+  type SocialProvider,
+} from "@/components/composed/social-providers";
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardDescription,
+  CardHeader,
+  CardPanel,
+  CardTitle,
+} from "@/components/ui/card";
+import { Spinner } from "@/components/ui/spinner";
+import { cn } from "@/lib/utils";
+import { AuthError, EASE } from "./auth-shell";
+
+/** One sign-in identity attached to the account. */
+export interface LinkedIdentity {
+  id: string;
+  provider: SocialProvider;
+  /** Account address shown under the provider name, when known. */
+  email?: string | null;
+}
+
+export interface LinkedAccountsBlockProps {
+  title?: string;
+  description?: string;
+  /** Identities already attached to the account. */
+  identities?: LinkedIdentity[];
+  /** Providers offered as connect candidates; connected ones are filtered out. */
+  providers?: SocialProvider[];
+  /** Shows the loading row instead of the list. */
+  loading?: boolean;
+  /** Reject (or throw) to show the inline error. */
+  onLink?: (provider: SocialProvider) => Promise<void> | void;
+  onUnlink?: (id: string) => Promise<void> | void;
+  className?: string;
+}
+
+const LAST_METHOD_EXPLANATION =
+  "This is your only way to sign in, so it can't be disconnected.";
+
+/**
+ * Settings panel for the sign-in identities attached to an account: lists the
+ * connected ones, offers connect buttons for the rest, and guards the last
+ * remaining method from being disconnected — the guard is a disabled button
+ * plus an explanation rather than an error after the fact.
+ */
+export function LinkedAccountsBlock({
+  title = "Connected accounts",
+  description = "Manage the accounts you can use to sign in.",
+  identities = [],
+  providers = ["google", "apple", "github"],
+  loading = false,
+  onLink,
+  onUnlink,
+  className,
+}: LinkedAccountsBlockProps) {
+  const noteId = React.useId();
+  const [error, setError] = React.useState<string | null>(null);
+  const [linking, setLinking] = React.useState<SocialProvider | null>(null);
+  const [unlinking, setUnlinking] = React.useState<string | null>(null);
+
+  const connected = new Set(identities.map((identity) => identity.provider));
+  const connectable = providers.filter((provider) => !connected.has(provider));
+  const busy = linking !== null || unlinking !== null;
+  // The backend rule, enforced here so we never fire a request that would
+  // remove the account's only way in.
+  const lastMethod = identities.length <= 1;
+
+  async function connect(provider: SocialProvider) {
+    if (busy) return;
+    setError(null);
+    setLinking(provider);
+    try {
+      await onLink?.(provider);
+    } catch (cause) {
+      setError(
+        cause instanceof Error ? cause.message : "Unable to connect account.",
+      );
+    } finally {
+      setLinking(null);
+    }
+  }
+
+  async function disconnect(id: string) {
+    if (busy || lastMethod) return;
+    setError(null);
+    setUnlinking(id);
+    try {
+      await onUnlink?.(id);
+    } catch (cause) {
+      setError(
+        cause instanceof Error
+          ? cause.message
+          : "Unable to disconnect account.",
+      );
+    } finally {
+      setUnlinking(null);
+    }
+  }
+
+  return (
+    <MotionConfig reducedMotion="user">
+      <Card className={cn("w-full", className)} data-slot="auth-block">
+        <CardHeader>
+          <CardTitle>{title}</CardTitle>
+          <CardDescription>{description}</CardDescription>
+        </CardHeader>
+        <CardPanel>
+          {loading ? (
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Spinner className="size-4" />
+              Loading connected accounts…
+            </div>
+          ) : (
+            <motion.div
+              layout
+              transition={{ duration: 0.3, ease: EASE }}
+              className="flex flex-col gap-3"
+            >
+              <AuthError message={error} />
+
+              {identities.length > 0 ? (
+                <ul
+                  aria-label="Connected accounts"
+                  className="flex flex-col gap-2"
+                >
+                  <AnimatePresence initial={false}>
+                    {identities.map((identity, index) => {
+                      const { label, Icon } = SOCIAL_PROVIDERS[
+                        identity.provider
+                      ];
+                      return (
+                        <motion.li
+                          key={identity.id}
+                          layout
+                          className="flex items-center justify-between gap-3 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 identity 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 min-w-0 items-center gap-2.5">
+                            <Icon
+                              aria-hidden="true"
+                              className="size-4 text-muted-foreground"
+                            />
+                            <div className="flex min-w-0 flex-col">
+                              <span className="font-medium text-sm">
+                                {label}
+                              </span>
+                              {identity.email && (
+                                <span className="truncate text-xs text-muted-foreground">
+                                  {identity.email}
+                                </span>
+                              )}
+                            </div>
+                          </div>
+                          <Button
+                            aria-describedby={lastMethod ? noteId : undefined}
+                            aria-label={`Disconnect ${label}`}
+                            size="sm"
+                            type="button"
+                            variant="destructive-outline"
+                            disabled={busy || lastMethod}
+                            loading={unlinking === identity.id}
+                            onClick={() => void disconnect(identity.id)}
+                          >
+                            Disconnect
+                          </Button>
+                        </motion.li>
+                      );
+                    })}
+                  </AnimatePresence>
+                </ul>
+              ) : (
+                <p className="text-sm text-muted-foreground">
+                  No sign-in methods connected yet.
+                </p>
+              )}
+
+              {lastMethod && identities.length > 0 && (
+                <p className="text-xs text-muted-foreground" id={noteId}>
+                  {LAST_METHOD_EXPLANATION}
+                </p>
+              )}
+
+              {connectable.map((provider) => {
+                const { label, Icon } = SOCIAL_PROVIDERS[provider];
+                return (
+                  <Button
+                    key={provider}
+                    className="w-full"
+                    type="button"
+                    variant="outline"
+                    disabled={busy}
+                    loading={linking === provider}
+                    onClick={() => void connect(provider)}
+                  >
+                    <Icon aria-hidden="true" />
+                    <span className="flex-1">Connect {label}</span>
+                  </Button>
+                );
+              })}
+            </motion.div>
+          )}
+        </CardPanel>
+      </Card>
+    </MotionConfig>
+  );
+}

package/src/components/blocks/auth/onboarding/profile-step.tsx

@@ -0,0 +1,227 @@
+"use client";
+
+import * as React from "react";
+
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Field, FieldError, FieldLabel } from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+import type {
+  OnboardingFieldConfig,
+  OnboardingStepConfig,
+  OnboardingValue,
+} from "../onboarding-block";
+
+export interface ProfileStepProps {
+  step: OnboardingStepConfig;
+  /** Seed values, so drafts survive back/forward navigation. */
+  values: Record<string, OnboardingValue>;
+  submitting?: boolean;
+  submitLabel: string;
+  onSubmit: (values: Record<string, OnboardingValue>) => void | Promise<void>;
+  onBack?: () => void;
+  /** Reports every edit so the flow can restore drafts across navigation. */
+  onDraftChange?: (name: string, value: OnboardingValue) => void;
+}
+
+function initialValue(
+  field: OnboardingFieldConfig,
+  saved: OnboardingValue | undefined,
+): OnboardingValue {
+  if (field.kind === "checkbox") return typeof saved === "boolean" ? saved : false;
+  return typeof saved === "string" ? saved : "";
+}
+
+/** Built-in validation, mirroring the declared `FieldConfig` contract. */
+function validateField(
+  field: OnboardingFieldConfig,
+  value: OnboardingValue,
+): string | null {
+  const required = field.required === true;
+
+  if (field.kind === "checkbox") {
+    if (required && value !== true) return `${field.label} is required`;
+    return null;
+  }
+
+  const text = typeof value === "string" ? value.trim() : "";
+  if (required && text.length === 0) return `${field.label} is required`;
+
+  if (field.kind === "url" && text.length > 0) {
+    try {
+      new URL(text);
+    } catch {
+      return "Enter a valid URL";
+    }
+  }
+
+  if (field.kind === "select" && text.length > 0) {
+    const allowed = field.options.map((option) => option.value);
+    if (!allowed.includes(text)) {
+      return `Choose a valid option for ${field.label}`;
+    }
+  }
+
+  return field.validate?.(text) ?? null;
+}
+
+/**
+ * Renders one declared profile step: `OnboardingFieldConfig[]` → labeled
+ * controls, validated locally before anything is handed to `onSubmit`. Mounted
+ * keyed by `step.id` so drafts re-seed per step.
+ */
+export function ProfileStep({
+  step,
+  values,
+  submitting = false,
+  submitLabel,
+  onSubmit,
+  onBack,
+  onDraftChange,
+}: ProfileStepProps) {
+  const idPrefix = React.useId();
+  const [draft, setDraft] = React.useState<Record<string, OnboardingValue>>(
+    () =>
+      Object.fromEntries(
+        step.fields.map((field) => [
+          field.name,
+          initialValue(field, values[field.name]),
+        ]),
+      ),
+  );
+  const [errors, setErrors] = React.useState<Record<string, string>>({});
+
+  function setValue(name: string, value: OnboardingValue) {
+    setDraft((current) => ({ ...current, [name]: value }));
+    onDraftChange?.(name, value);
+    // Clear a field's error as soon as it is edited; re-validation happens on
+    // the next submit rather than on every keystroke.
+    setErrors((current) =>
+      current[name] ? { ...current, [name]: "" } : current,
+    );
+  }
+
+  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (submitting) return;
+
+    const next: Record<string, string> = {};
+    for (const field of step.fields) {
+      const message = validateField(field, draft[field.name]);
+      if (message) next[field.name] = message;
+    }
+    if (Object.keys(next).length > 0) {
+      setErrors(next);
+      return;
+    }
+    setErrors({});
+
+    const submitted: Record<string, OnboardingValue> = {};
+    for (const field of step.fields) {
+      const value = draft[field.name];
+      submitted[field.name] = typeof value === "string" ? value.trim() : value;
+    }
+    await onSubmit(submitted);
+  }
+
+  return (
+    <form className="flex flex-col gap-4" noValidate onSubmit={handleSubmit}>
+      {step.fields.map((field) => {
+        const error = errors[field.name] || undefined;
+        const controlId = `${idPrefix}-${field.name}`;
+        const value = draft[field.name];
+
+        if (field.kind === "checkbox") {
+          return (
+            <Field
+              key={field.name}
+              name={field.name}
+              invalid={Boolean(error)}
+              className="gap-1.5"
+            >
+              <div className="flex items-center gap-2">
+                <Checkbox
+                  id={controlId}
+                  checked={value === true}
+                  disabled={submitting}
+                  onCheckedChange={(checked) => setValue(field.name, checked)}
+                />
+                <Label htmlFor={controlId} className="font-normal">
+                  {field.label}
+                </Label>
+              </div>
+              {error && <FieldError match>{error}</FieldError>}
+            </Field>
+          );
+        }
+
+        return (
+          <Field key={field.name} name={field.name} invalid={Boolean(error)}>
+            <FieldLabel htmlFor={controlId}>{field.label}</FieldLabel>
+            {field.kind === "textarea" ? (
+              <Textarea
+                id={controlId}
+                aria-invalid={error ? true : undefined}
+                disabled={submitting}
+                placeholder={field.placeholder}
+                value={String(value ?? "")}
+                onChange={(event) => setValue(field.name, event.target.value)}
+              />
+            ) : field.kind === "select" ? (
+              // No select atom exists in the library yet; a native control
+              // styled to match Input keeps the flow self-contained without
+              // inventing one here.
+              <select
+                id={controlId}
+                aria-invalid={error ? true : undefined}
+                className={cn(
+                  "h-8.5 w-full rounded-lg border border-input bg-background px-[calc(--spacing(3)-1px)] text-base text-foreground shadow-xs/5 outline-none transition-[box-shadow,border-color] duration-150 ease-smooth-out focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/24 disabled:opacity-64 aria-invalid:border-destructive/36 sm:h-7.5 sm:text-sm dark:bg-input/32",
+                )}
+                disabled={submitting}
+                value={String(value ?? "")}
+                onChange={(event) => setValue(field.name, event.target.value)}
+              >
+                <option value="">{field.placeholder ?? "Choose an option"}</option>
+                {field.options.map((option) => (
+                  <option key={option.value} value={option.value}>
+                    {option.label}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              <Input
+                id={controlId}
+                aria-invalid={error ? true : undefined}
+                disabled={submitting}
+                placeholder={field.placeholder}
+                type={field.kind === "url" ? "url" : "text"}
+                value={String(value ?? "")}
+                onChange={(event) => setValue(field.name, event.target.value)}
+              />
+            )}
+            {error && <FieldError match>{error}</FieldError>}
+          </Field>
+        );
+      })}
+
+      <div className="flex gap-2">
+        {onBack && (
+          <Button
+            type="button"
+            variant="outline"
+            disabled={submitting}
+            onClick={onBack}
+          >
+            Back
+          </Button>
+        )}
+        <Button className="flex-1" type="submit" loading={submitting}>
+          {submitLabel}
+        </Button>
+      </div>
+    </form>
+  );
+}

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>
+  );
+}