@eifi1/ui-kit 0.28.0 → 0.29.0

package/src/auth/status-parts.tsx

@@ -0,0 +1,138 @@
+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-[var(--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-[var(--text-primary)]";
+export const INTRO_CLASS = "text-sm text-[var(--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]);
+}
+
+/** Whether a callback's return is a promise to wait for. A callback that returns
+ *  nothing is done when it returns. */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return typeof (value as PromiseLike<unknown> | null)?.then === "function";
+}
+
+/**
+ * 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.tsx

@@ -0,0 +1,358 @@
+import { useEffect, useState } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { CheckCircle2, MailWarning, TimerOff, XCircle } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { useAnnounce } from "../hooks/use-announce";
+import { AlertBanner } from "../components/alert-banner";
+import { LoadingState } from "../components/loading-state";
+import { Button, EmptyState } from "../components/ui";
+import { OUTCOME_CLASS, STATUS_HEADING_CLASS, isThenable, useOncePerKey } from "./status-parts";
+import type { AuthHeadingLevel } from "./status-parts";
+
+/* ── 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;
+  /** The banner's message. */
+  banner: string;
+  /** The banner's ×: it defers, it does not close anything. */
+  dismiss: string;
+}
+
+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",
+  banner: "Please confirm your email address.",
+  dismiss: "Not now",
+};
+
+/** 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");
+  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 {
+      setPhase("failed");
+      return;
+    }
+    if (!isThenable(result)) {
+      sent();
+      return;
+    }
+    setPhase("sending");
+    result.then(sent, () => setPhase("failed"));
+  };
+  return { phase, remaining, send };
+}
+
+function ResendButton({
+  state,
+  labels,
+  variant,
+}: {
+  state: ReturnType<typeof useResend>;
+  labels: VerifyEmailLabels;
+  variant: "secondary" | "brand";
+}) {
+  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, labels, className }: { phase: ResendPhase; labels: VerifyEmailLabels; className?: string }) {
+  return (
+    <span
+      role="status"
+      className={cn(phase === "failed" ? "text-[var(--danger)]" : "text-[var(--success)]", className)}
+    >
+      {phase === "sent" ? labels.resent : phase === "failed" ? labels.resendError : ""}
+    </span>
+  );
+}
+
+/* ── The page ────────────────────────────────────────────────────────────── */
+
+/** What became of a confirmation link that did not verify. */
+export type VerifyEmailFailure = "invalid" | "expired";
+
+export interface VerifyEmailStatusProps extends Omit<ComponentPropsWithoutRef<"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;
+  /** 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?: Partial<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,
+  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) => {
+    const next: VerifyOutcome = result.ok ? "verified" : (classifyError?.(result.error) ?? "invalid");
+    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" ? "brand" : "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="brand" />}
+            {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} 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;
+  /** 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?: Partial<VerifyEmailLabels>;
+}
+
+/**
+ * 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,
+  cooldown = DEFAULT_COOLDOWN,
+  onDismiss,
+  variant = "strip",
+  children,
+  className,
+  labels: labelsProp,
+}: EmailVerificationBannerProps) {
+  const labels = useKitLabels("verifyEmail", DEFAULT_VERIFY_EMAIL_LABELS, labelsProp);
+  const resend = useResend(onResend, cooldown);
+  return (
+    <AlertBanner
+      tone="warning"
+      variant={variant}
+      icon={<MailWarning />}
+      action={<ResendButton state={resend} labels={labels} variant="secondary" />}
+      onDismiss={onDismiss}
+      dismissLabel={onDismiss ? labels.dismiss : undefined}
+      className={className}
+    >
+      {labels.banner}
+      {children != null && children !== false && <> {children}</>}{" "}
+      <ResendStatus phase={resend.phase} labels={labels} className="font-medium" />
+    </AlertBanner>
+  );
+}

package/src/components/legal-page.tsx

@@ -10,6 +10,7 @@ import { Checkbox } from "./checkbox";
 import type { CheckboxProps } from "./checkbox";
 import {
   LEGAL_HREFS,
+  baseLanguage,
   LegalFooter,
   LegalLayout,
   LegalPageContext,
@@ -33,6 +34,7 @@ import type {
   LegalTextSectionLabels,
 } from "./legal";
 import { TextLink } from "./text-link";
+import { Button } from "./ui";
 
 /**
  * The legal pages' frame and the kit's own sections — docs/legal-harmonization.md §3
@@ -107,6 +109,8 @@ export const LEGAL_SKELETON: Readonly<Record<LegalPageKey, LegalSkeletonPage>> =
       { key: "warranty", owner: "kit" },
       { key: "liability", owner: "kit" },
       { key: "changes", owner: "kit" },
+      // 0.28.1: which language's version prevails (the operator's `bindingLanguage`).
+      { key: "language", owner: "kit" },
       { key: "law", owner: "kit" },
     ] as const),
   }),
@@ -125,6 +129,7 @@ export type LegalKitSectionKey =
   | "warranty"
   | "liability"
   | "changes"
+  | "language"
   | "law";
 
 /** The kit's sections of one page, in the skeleton's order. */
@@ -228,6 +233,11 @@ export function LegalKitSection(props: LegalKitSectionProps) {
         `LegalKitSection "${section}" names the operator: render it inside <LegalPage operator={…}>, or pass operator.`,
       );
     }
+    if (section === "language" && !operator.bindingLanguage) {
+      throw new Error(
+        `LegalKitSection "language" names the binding language: give the operator a bindingLanguage ("de-CH").`,
+      );
+    }
     return body(operator);
   };
 
@@ -303,6 +313,12 @@ export interface LegalPageProps {
   /** Default: the kit's beta notice on the imprint and the terms, its privacy notice on
    *  the privacy policy (§3.2). `null` for none. */
   notice?: ReactNode;
+  /**
+   * 0.28.1: switches the app to the operator's `bindingLanguage` — the button after the
+   * translation note on a page read in another language. Without it the note stands
+   * alone; the app's own language switcher is in its header anyway.
+   */
+  onShowBindingLanguage?: () => void;
   /** The language the operator's country is named in. Default: the `<UiKitProvider
    *  locale>`, else English. */
   locale?: string;
@@ -434,6 +450,7 @@ export function LegalPage({
   footer,
   homeHref = "/",
   notice,
+  onShowBindingLanguage,
   locale: localeProp,
   headingAs = "h1",
   landmark = true,
@@ -462,6 +479,23 @@ export function LegalPage({
   const Main = landmark ? "main" : "div";
   const shownNotice =
     notice !== undefined ? notice : page === "privacy" ? labels.notice.privacy : labels.notice.beta;
+  // 0.28.1 (Marcel): one language is binding and the lawyer reviews that one; a page read
+  // in any other says so, with a way to the binding version.
+  const translated =
+    operator.bindingLanguage !== undefined && baseLanguage(operator.bindingLanguage) !== baseLanguage(locale);
+  const translationNote = translated ? (
+    <p className="text-sm text-[var(--text-secondary)]">
+      {labels.translation.note(operatorText)}
+      {onShowBindingLanguage && (
+        <>
+          {" "}
+          <Button type="button" variant="link" size="sm" className="h-auto p-0 align-baseline" onClick={onShowBindingLanguage}>
+            {labels.translation.show(operatorText)}
+          </Button>
+        </>
+      )}
+    </p>
+  ) : undefined;
 
   return (
     <UiKitProvider labels={overrides}>
@@ -477,6 +511,7 @@ export function LegalPage({
               }
               title={labels.titles[page]}
               notice={shownNotice}
+              translationNote={translationNote}
               headingAs={headingAs}
             >
               {nodes}