@eifi1/ui-kit 0.53.0 → 0.55.0

package/src/auth/status-parts.tsx

@@ -1,132 +0,0 @@
-import { useEffect, useRef } from "react";
-import type { ReactNode } from "react";
-import { cn } from "../lib/cn";
-
-/**
- * The pieces the signed-out status pages share — {@link ForgotPasswordForm},
- * {@link ResetPasswordForm}, {@link VerifyEmailStatus}, {@link AcceptInvitation} and
- * {@link NotFoundPage} (docs/auth-harmonization.md §7).
- *
- * @internal Not part of the barrel; the pages are.
- */
-
-/** A heading level a page part may take. Default `h2`, under the page's `h1`
- *  (`AuthLayout`'s `title`, the app's name), as on `SignInForm`'s steps; deeper for a
- *  page embedded in another (a preview, the docs). */
-export type AuthHeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
-
-/** The form pages' heading: start-aligned, the size of `SignInForm`'s step headings. */
-export const FORM_HEADING_CLASS = "text-base font-semibold text-primary";
-/** The status pages' heading: centred over the centred outcome below it. */
-export const STATUS_HEADING_CLASS = "text-center text-base font-semibold text-primary";
-export const INTRO_CLASS = "text-sm text-secondary";
-
-/**
- * kastlan's outcome block (verify-email-page, reset-password-page): the kit's
- * `EmptyState` without its dashed box, because it already sits in `AuthLayout`'s card —
- * a box in a box. The icon and the title carry the tone.
- */
-export const OUTCOME_CLASS = "border-0 bg-transparent px-0 py-3";
-
-/** `href` with `key=value` added to its query, before any `#fragment`: the reset page's
- *  "Sign in" carries the address (`/login?email=ada%40example.com`). */
-export function withQuery(href: string, key: string, value: string): string {
-  const hash = href.indexOf("#");
-  const base = hash === -1 ? href : href.slice(0, hash);
-  const fragment = hash === -1 ? "" : href.slice(hash);
-  const separator = base.includes("?") ? (base.endsWith("?") || base.endsWith("&") ? "" : "&") : "?";
-  return `${base}${separator}${encodeURIComponent(key)}=${encodeURIComponent(value)}${fragment}`;
-}
-
-/** What a callback's promise came to. */
-export type Settled<T> = { ok: true; value: T } | { ok: false; error: unknown };
-
-/**
- * Run `start(key)` ONCE per key, and hand what it settles to into `settle` — unless the
- * key moved on in the meantime, when the stale answer is dropped.
- *
- * keksdose's verify-email and join pages fire their request from an effect behind a
- * `useRef` guard, and say why: the token is single-use, and StrictMode's
- * mount → unmount → remount would send it twice and turn a success into "invalid" on
- * the second answer. The guard is the same here; there is deliberately no "unmounted"
- * flag set in the cleanup, because StrictMode's simulated unmount would set it and the
- * remount would never clear the guard — the page would hang on its spinner (the bug
- * keksdose hit on /join with a react-query observer). A state update after a real
- * unmount is a no-op in React 18 and later.
- *
- * `key === null` runs nothing (no token, not signed in yet) and forgets the last key, so
- * the same token runs again once it is back.
- */
-export function useOncePerKey<T>(
-  key: string | null,
-  start: (key: string) => T | Promise<T>,
-  settle: (key: string, result: Settled<T>) => void,
-): void {
-  const latest = useRef({ start, settle });
-  useEffect(() => {
-    latest.current = { start, settle };
-  });
-  const current = useRef<string | null>(null);
-  useEffect(() => {
-    if (key === null) {
-      current.current = null;
-      return;
-    }
-    if (current.current === key) return;
-    current.current = key;
-    const report = (result: Settled<T>) => {
-      if (current.current === key) latest.current.settle(key, result);
-    };
-    let started: T | Promise<T>;
-    try {
-      started = latest.current.start(key);
-    } catch (error) {
-      report({ ok: false, error });
-      return;
-    }
-    Promise.resolve(started).then(
-      (value) => report({ ok: true, value }),
-      (error: unknown) => report({ ok: false, error }),
-    );
-  }, [key]);
-}
-
-/**
- * Move focus to `ref` when `active` turns true — the outcome a person's own submit led
- * to ("If an account exists … the link is on its way", "Your password has been
- * changed"). The submit button they pressed is gone with the form, which drops focus to
- * `<body>`; a screen reader then hears nothing at all. Focusing the message (a
- * `tabIndex={-1}` box) reads it out and leaves the next Tab where the page continues.
- */
-export function useFocusWhen(active: boolean, ref: { current: HTMLElement | null }): void {
-  useEffect(() => {
-    if (active) ref.current?.focus();
-  }, [active, ref]);
-}
-
-/** The box {@link useFocusWhen} focuses: centred, no focus ring of its own (it is not a
- *  control; the ring would read as one). */
-export function OutcomeMessage({
-  icon,
-  children,
-  focusRef,
-  className,
-}: {
-  icon: ReactNode;
-  children: ReactNode;
-  focusRef?: { current: HTMLDivElement | null };
-  className?: string;
-}) {
-  return (
-    <div
-      ref={focusRef}
-      tabIndex={-1}
-      className={cn("flex flex-col items-center gap-2 py-2 text-center outline-none", className)}
-    >
-      <span aria-hidden className="[&_svg]:size-10">
-        {icon}
-      </span>
-      {children}
-    </div>
-  );
-}

package/src/auth/verify-email-labels.ts

@@ -1,26 +0,0 @@
-// The English words of ./verify-email, in a module with no component code: the English
-// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
-// chunk like the other languages (0.34, KS U8). ./verify-email re-exports them.
-
-import { englishRateLimited } from "./auth-errors-labels";
-import type { VerifyEmailLabels } from "./verify-email";
-
-export const DEFAULT_VERIFY_EMAIL_LABELS: VerifyEmailLabels = {
-  title: "Confirm your email address",
-  verifying: "Confirming…",
-  verified: "Your email address is confirmed.",
-  continue: "Continue",
-  invalid: "This confirmation link is not valid",
-  expired: "This confirmation link has expired",
-  noToken: "This link is missing its confirmation token.",
-  invalidHint: "The link may have expired or already been used.",
-  requestInApp: "You can request a new one from inside the app.",
-  requestHere: "You can request a new one here.",
-  resend: "Send again",
-  resendIn: (seconds) => `Send again in ${seconds} s`,
-  resent: "Confirmation email sent",
-  resendError: "Could not send the confirmation email",
-  rateLimited: englishRateLimited,
-  banner: "Please confirm your email address.",
-  dismiss: "Not now",
-};

package/src/auth/verify-email.tsx

@@ -1,445 +0,0 @@
-import { useEffect, useState } from "react";
-import type { ComponentPropsWithRef, ReactNode } from "react";
-import { CheckCircle2, MailWarning, TimerOff, XCircle } from "lucide-react";
-import { cn } from "../lib/cn";
-import { describeFailure } from "../lib/describe-failure";
-import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
-import { useAnnounce } from "../hooks/use-announce";
-import { AlertBanner } from "../components/alert-banner";
-import { LoadingState } from "../components/loading-state";
-import { Button } from "../components/button";
-import { EmptyState } from "../components/empty-state";
-import { isThenable } from "../lib/thenable";
-import { OUTCOME_CLASS, STATUS_HEADING_CLASS, useOncePerKey } from "./status-parts";
-import { authErrorCode, englishRateLimited, isRateLimited, retryAfterSeconds } from "./auth-errors";
-import type { AuthHeadingLevel } from "./status-parts";
-import { DEFAULT_VERIFY_EMAIL_LABELS } from "./verify-email-labels";
-
-/* ── Labels ──────────────────────────────────────────────────────────────── */
-
-/** Every string the verification page and banner render — the `verifyEmail` namespace.
- *  keksdose's words (`verify_email.*`, and its server's "has expired"). */
-export interface VerifyEmailLabels {
-  /** The page's heading. */
-  title: string;
-  /** While the link is redeemed. */
-  verifying: string;
-  verified: string;
-  /** The way on from the page — into the app, or to sign-in. */
-  continue: string;
-  invalid: string;
-  expired: string;
-  /** The page was opened without a `token`. */
-  noToken: string;
-  /** Under `invalid`: why a link stops working. */
-  invalidHint: string;
-  /** Under a dead link, signed out: where a new one comes from. */
-  requestInApp: string;
-  /** Under a dead link, signed in, beside "Send again". */
-  requestHere: string;
-  /** The resend button, on the page and in the banner. */
-  resend: string;
-  /** The resend button while a just-sent mail cools down, given the seconds left. */
-  resendIn: (seconds: number) => string;
-  /** Said (and shown) after a resend went out. */
-  resent: string;
-  /** Said (and shown) after a resend failed. */
-  resendError: string;
-  /** 0.31.1: a resend refused as throttled — HTTP 429 (`isRateLimited`) — given the
-   *  `Retry-After` seconds, when the app's `describeError` has no words of its own
-   *  (keksdose borrowed the sign-in namespace's). */
-  rateLimited?: (seconds?: number) => string;
-  /** The banner's message. */
-  banner: string;
-  /** The banner's ×: it defers, it does not close anything. */
-  dismiss: string;
-}
-
-// Defined in ./verify-email-labels, which holds no component code (0.34, KS U8).
-export { DEFAULT_VERIFY_EMAIL_LABELS };
-
-/** A minute: long enough that an impatient second click does not mail twice, short
- *  enough that a mail lost to a spam filter can be re-sent without leaving the page. The
- *  server's own limit is the real one (kastlan: 3 an hour per address). */
-const DEFAULT_COOLDOWN = 60;
-
-/* ── Resend ──────────────────────────────────────────────────────────────── */
-
-type ResendPhase = "idle" | "sending" | "sent" | "failed";
-
-/**
- * "Send again" with its own memory: busy while the request runs, then — after a mail
- * went out — held for `cooldown` seconds with the countdown on the button, so a second
- * click cannot mail twice and a throttled server is not asked to refuse. A failure frees
- * it at once. The outcome is a polite live region that is always rendered (a region that
- * mounts with its message is often not read), and visible.
- */
-function useResend(onResend: (() => Promise<unknown> | void) | undefined, cooldown: number) {
-  const [phase, setPhase] = useState<ResendPhase>("idle");
-  // The refusal itself, for `describeError` (0.30.0): the server's own sentence — keksdose's
-  // per-address throttle, "try again in N minutes" — beats a fixed "could not send".
-  const [error, setError] = useState<unknown>(undefined);
-  const [remaining, setRemaining] = useState(0);
-  const counting = remaining > 0;
-  useEffect(() => {
-    if (!counting) return;
-    const id = setInterval(() => setRemaining((r) => Math.max(0, r - 1)), 1000);
-    return () => clearInterval(id);
-  }, [counting]);
-
-  const sent = () => {
-    setPhase("sent");
-    setRemaining(Math.max(0, Math.round(cooldown)));
-  };
-  const send = () => {
-    if (!onResend || phase === "sending" || counting) return;
-    let result: unknown;
-    try {
-      result = onResend();
-    } catch (e) {
-      setError(e);
-      setPhase("failed");
-      return;
-    }
-    if (!isThenable(result)) {
-      sent();
-      return;
-    }
-    setPhase("sending");
-    result.then(sent, (e: unknown) => {
-      setError(e);
-      setPhase("failed");
-    });
-  };
-  return { phase, remaining, send, error };
-}
-
-function ResendButton({
-  state,
-  labels,
-  variant,
-}: {
-  state: ReturnType<typeof useResend>;
-  labels: VerifyEmailLabels;
-  variant: "secondary" | "accent";
-}) {
-  return (
-    <Button
-      type="button"
-      variant={variant}
-      size={variant === "secondary" ? "sm" : undefined}
-      onClick={state.send}
-      pending={state.phase === "sending"}
-      // `disabledReason`, not `disabled`: the button just pressed has the focus, and a
-      // native `disabled` would drop it to <body>. The reason is what just happened.
-      disabledReason={state.remaining > 0 ? labels.resent : undefined}
-    >
-      {state.remaining > 0 ? labels.resendIn(state.remaining) : labels.resend}
-    </Button>
-  );
-}
-
-function ResendStatus({
-  phase,
-  error,
-  describeError,
-  labels,
-  className,
-}: {
-  phase: ResendPhase;
-  error?: unknown;
-  describeError?: (error: unknown) => string | undefined;
-  labels: VerifyEmailLabels;
-  className?: string;
-}) {
-  // The app's words first, then the throttle's, then the kit's catch-all — an app's ""
-  // is no words (refactor audit 2026-10-30, DUP-14: `??` printed an empty status).
-  const failed =
-    phase === "failed"
-      ? describeFailure(
-          describeError?.(error),
-          isRateLimited(error)
-            ? (labels.rateLimited ?? englishRateLimited)(retryAfterSeconds(error))
-            : labels.resendError,
-        )
-      : "";
-  return (
-    <span role="status" className={cn(phase === "failed" ? "text-danger" : "text-success", className)}>
-      {phase === "sent" ? labels.resent : failed}
-    </span>
-  );
-}
-
-/* ── The page ────────────────────────────────────────────────────────────── */
-
-/** What became of a confirmation link that did not verify. */
-export type VerifyEmailFailure = "invalid" | "expired";
-
-/** The default when the app gives no `classifyError`: the coded refusal decides. */
-function defaultVerifyFailure(error: unknown): VerifyEmailFailure {
-  return authErrorCode(error) === "token_expired" ? "expired" : "invalid";
-}
-
-export interface VerifyEmailStatusProps extends Omit<ComponentPropsWithRef<"div">, "children" | "title"> {
-  /** The link's token — the app's `?token=`. Empty: the link was cut short, and the
-   *  page says so without asking anyone. */
-  token: string;
-  /**
-   * Redeem it — `POST /auth/verify-email {token}`, once per token, on mount. A POST and
-   * not the link's own GET (§10.10): a mail scanner that opens every link must not
-   * confirm an address nobody read. Resolve when it verified (an address that already
-   * was counts: keksdose's redeem is idempotent); reject with the client's error.
-   */
-  onVerify: (token: string) => Promise<unknown>;
-  /** Which dead end a rejection is. Default: `invalid` for everything — §5.2's servers
-   *  answer one `token_invalid`; an app whose server tells expiry apart maps it here. */
-  classifyError?: (error: unknown) => VerifyEmailFailure;
-  /** 0.30.0: the words for a refused resend — the server's own sentence (a throttle's
-   *  "try again in N minutes"), else the kit's `resendError`. */
-  describeError?: (error: unknown) => string | undefined;
-  /** Someone is signed in on this device: "Continue" goes into the app, and a dead link
-   *  offers "Send again" (with `onResend`). */
-  signedIn?: boolean;
-  /** Send a new confirmation mail (`POST /auth/verify-email/resend`) — offered on a dead
-   *  link while signed in. */
-  onResend?: () => Promise<unknown> | void;
-  /** Seconds "Send again" waits after a mail went out. Default 60; `0` never waits. */
-  cooldown?: number;
-  /** Where "Continue" goes. Default `/` signed in, `/login` signed out. */
-  continueHref?: string;
-  /** App content under "confirmed" — keksdose's "Others can now share a budget with you
-   *  directly." */
-  verifiedContent?: ReactNode;
-  /** The heading. Default `labels.title`; `null` draws none, for a page that puts it in
-   *  `AuthLayout`'s `title` instead. */
-  title?: ReactNode;
-  /** The heading's level. Default `h2`, under the page's `h1`. */
-  headingAs?: AuthHeadingLevel;
-  labels?: LabelOverride<VerifyEmailLabels>;
-}
-
-type VerifyOutcome = "verified" | VerifyEmailFailure;
-
-/**
- * Redeem an email-confirmation link (`/verify-email?token=…`, docs/auth-harmonization.md
- * §7) — keksdose's `VerifyEmailPage` (features/auth/verify-email-page.tsx), with
- * kastlan's outcome blocks and its separate "expired".
- *
- * Opened from an inbox, often in a browser with no session, so the token is the only
- * credential and the page renders signed-out. It redeems once per token on mount
- * (StrictMode's double effect included — the token is single-use) and shows one of:
- * confirmed; not valid; expired; or the link had no token at all. Verification gates
- * nothing (§2.8), so every outcome ends on "Continue". Signed in, a dead link also
- * offers "Send again", which waits `cooldown` seconds after a mail went out.
- *
- * The outcome replaces the spinner, which says nothing to a screen reader on its own,
- * so it is also announced.
- */
-export function VerifyEmailStatus({
-  token,
-  onVerify,
-  classifyError,
-  describeError,
-  signedIn = false,
-  onResend,
-  cooldown = DEFAULT_COOLDOWN,
-  continueHref,
-  verifiedContent,
-  title,
-  headingAs: Heading = "h2",
-  labels: labelsProp,
-  className,
-  ...rest
-}: VerifyEmailStatusProps) {
-  const labels = useKitLabels("verifyEmail", DEFAULT_VERIFY_EMAIL_LABELS, labelsProp);
-  const [settled, setSettled] = useState<{ token: string; outcome: VerifyOutcome } | null>(null);
-  const outcome: VerifyOutcome | "verifying" =
-    token === "" ? "invalid" : settled?.token === token ? settled.outcome : "verifying";
-  const { announce, regionProps } = useAnnounce();
-  const resend = useResend(onResend, cooldown);
-
-  useOncePerKey(token === "" ? null : token, onVerify, (key, result) => {
-    // Without a classifier, the coded refusal decides (0.30.0): `token_expired` is
-    // "expired", anything else "invalid".
-    const next: VerifyOutcome = result.ok ? "verified" : (classifyError ?? defaultVerifyFailure)(result.error);
-    setSettled({ token: key, outcome: next });
-    announce(labels[next]);
-  });
-
-  const href = continueHref ?? (signedIn ? "/" : "/login");
-  // `replace`: the token is spent, so Back must not land on this page again (keksdose F1).
-  const continueButton = (
-    <Button href={href} replace variant={outcome === "verified" ? "accent" : "secondary"}>
-      {labels.continue}
-    </Button>
-  );
-  const canResend = signedIn && onResend !== undefined;
-
-  let body: ReactNode;
-  if (outcome === "verifying") {
-    body = <LoadingState size="sm" label={labels.verifying} />;
-  } else if (outcome === "verified") {
-    body = (
-      <EmptyState
-        tone="success"
-        icon={<CheckCircle2 />}
-        title={labels.verified}
-        hint={verifiedContent}
-        action={continueButton}
-        className={OUTCOME_CLASS}
-      />
-    );
-  } else {
-    const hint = (
-      <>
-        {outcome === "invalid" && token !== "" ? `${labels.invalidHint} ` : ""}
-        {canResend ? labels.requestHere : labels.requestInApp}
-      </>
-    );
-    body = (
-      <EmptyState
-        tone="danger"
-        icon={outcome === "expired" ? <TimerOff /> : <XCircle />}
-        title={token === "" ? labels.noToken : labels[outcome]}
-        hint={hint}
-        action={
-          <>
-            {canResend && <ResendButton state={resend} labels={labels} variant="accent" />}
-            {continueButton}
-          </>
-        }
-        className={OUTCOME_CLASS}
-      />
-    );
-  }
-
-  return (
-    <div
-      {...rest}
-      data-state={outcome}
-      aria-busy={outcome === "verifying" || undefined}
-      className={cn("space-y-3", className)}
-    >
-      {title === null ? null : <Heading className={STATUS_HEADING_CLASS}>{title ?? labels.title}</Heading>}
-      {body}
-      {canResend && (
-        <ResendStatus
-          phase={resend.phase}
-          error={resend.error}
-          describeError={describeError}
-          labels={labels}
-          className="block text-center text-xs"
-        />
-      )}
-      {/* Rendered from the start, so the outcome is read when it arrives. */}
-      <div {...regionProps} />
-    </div>
-  );
-}
-
-/* ── The banner ──────────────────────────────────────────────────────────── */
-
-export interface EmailVerificationBannerProps {
-  /** Send a new confirmation mail (`POST /auth/verify-email/resend`). Resolve when it
-   *  went out; reject and the banner says it could not. */
-  onResend: () => Promise<unknown> | void;
-  /** 0.30.0: the words for a refused resend — the server's own sentence, else the kit's. */
-  describeError?: (error: unknown) => string | undefined;
-  /** Seconds "Send again" waits after a mail went out. Default 60; `0` never waits. */
-  cooldown?: number;
-  /** The ×, "Not now". The banner does not hide itself: the app stops rendering it —
-   *  keksdose for the rest of the session. Left out, no ×. */
-  onDismiss?: () => void;
-  /** `strip` (default): keksdose's band across the top of the shell. `box`: kastlan's
-   *  callout inside the page. */
-  variant?: "strip" | "box";
-  /** The app's sentence after the kit's — keksdose's "Until you do, nobody can share a
-   *  budget with you directly." */
-  children?: ReactNode;
-  className?: string;
-  labels?: LabelOverride<VerifyEmailLabels>;
-  /**
-   * 0.48: on a phone hold the message to one line with a More / Less toggle —
-   * {@link AlertBanner}'s `clampMobile`, passed through (kastlan S2: its banner took ~110px
-   * of a 390px phone). The resend's outcome ("Sent", the error) then moves out of the
-   * message to sit after "Send again", at every width, so the line that answers the press
-   * is never hidden behind "More". Default `false`: the outcome stays in the message.
-   *
-   * 0.51 (kastlan K1, KX-5): in the `strip` variant "Send again" then stays on the clamped
-   * message's line on a phone — one line, 43px, on a 390px phone in all seven catalogues —
-   * where it took a line of its own (71px). The box's equivalent is `actionPlacement`.
-   */
-  clampMobile?: boolean;
-  /**
-   * 0.50 (kastlan K1): where "Send again" goes on a phone in the `box` variant —
-   * {@link AlertBanner}'s `actionPlacement`, passed through. `"flow"` keeps it on the
-   * message's line while the message keeps 10rem, else at the end of the next line,
-   * instead of a line of its own (kastlan's ≤ 56px banner on a 390px phone, KX-5).
-   * Default `"own-line"`, as before. The `strip` variant flows like that already.
-   */
-  actionPlacement?: "own-line" | "flow";
-}
-
-/**
- * The nudge for a signed-in account whose address is not confirmed — keksdose's
- * `VerifyEmailBanner` (features/auth/verify-email-banner.tsx), kastlan's copy of it.
- *
- * A prompt, not a wall: verification gates nothing (§2.8). The app renders it while
- * `/auth/me` says `email_verified: false`, and stops when the user dismisses it or the
- * page above confirms the address. "Send again" waits `cooldown` seconds after a mail
- * went out (the button says how long), and its outcome is written into the banner and
- * read out — no toast needed.
- */
-export function EmailVerificationBanner({
-  onResend,
-  describeError,
-  cooldown = DEFAULT_COOLDOWN,
-  onDismiss,
-  variant = "strip",
-  children,
-  className,
-  labels: labelsProp,
-  clampMobile = false,
-  actionPlacement,
-}: EmailVerificationBannerProps) {
-  const labels = useKitLabels("verifyEmail", DEFAULT_VERIFY_EMAIL_LABELS, labelsProp);
-  const resend = useResend(onResend, cooldown);
-  // One live region either way, mounted from the start (a region added later is often not
-  // read out): in the message, or — clamped — after the button, outside the clamp.
-  const status = (
-    <ResendStatus
-      phase={resend.phase}
-      error={resend.error}
-      describeError={describeError}
-      labels={labels}
-      className="font-medium"
-    />
-  );
-  const button = <ResendButton state={resend} labels={labels} variant="secondary" />;
-  return (
-    <AlertBanner
-      tone="warning"
-      variant={variant}
-      icon={<MailWarning />}
-      action={
-        clampMobile ? (
-          <>
-            {button}
-            {status}
-          </>
-        ) : (
-          button
-        )
-      }
-      onDismiss={onDismiss}
-      dismissLabel={onDismiss ? labels.dismiss : undefined}
-      clampMobile={clampMobile}
-      actionPlacement={actionPlacement}
-      className={className}
-    >
-      {labels.banner}
-      {children != null && children !== false && <> {children}</>}
-      {!clampMobile && <> {status}</>}
-    </AlertBanner>
-  );
-}