@eifi1/ui-kit 0.28.1 → 0.29.0

package/src/auth/accept-invitation.tsx

@@ -0,0 +1,227 @@
+import { useState } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { CheckCircle2, LogIn, TimerOff, XCircle } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { useAnnounce } from "../hooks/use-announce";
+import { LoadingState } from "../components/loading-state";
+import { Button, EmptyState } from "../components/ui";
+import { authErrorCode } from "./auth-errors";
+import { OUTCOME_CLASS, STATUS_HEADING_CLASS, useOncePerKey } from "./status-parts";
+import type { AuthHeadingLevel } from "./status-parts";
+
+/* ── Labels ──────────────────────────────────────────────────────────────── */
+
+/** Every string the page renders — the `acceptInvitation` namespace. keksdose's words
+ *  where its `/join` page has them (`budget_share.join*`). */
+export interface AcceptInvitationLabels {
+  /** The heading. */
+  title: string;
+  /** While the invitation is accepted. */
+  accepting: string;
+  /** Accepted, when the app did not say into what. */
+  accepted: string;
+  /** Accepted, given what it attached the account to — a company, a team, a budget. */
+  joined: (name: string) => string;
+  /** Into the app, from every outcome but "sign in first". */
+  continue: string;
+  /** The token is unknown, spent, or for another address. */
+  invalid: string;
+  expired: string;
+  /** The page was opened without a `token`. */
+  noToken: string;
+  /** Under `invalid` and `expired`: an invitation is re-sent as a new one (§4.4). */
+  askAgain: string;
+  /** Nobody is signed in: an existing account accepts after sign-in (§4.4). */
+  signInFirst: string;
+  /** Under it. */
+  signInHint: string;
+  signIn: string;
+  /** Beside "Sign in", with `registerHref`. */
+  register: string;
+}
+
+export const DEFAULT_ACCEPT_INVITATION_LABELS: AcceptInvitationLabels = {
+  title: "Accept invitation",
+  accepting: "Joining…",
+  accepted: "Invitation accepted.",
+  joined: (name) => `You’ve joined ${name}.`,
+  continue: "Continue",
+  invalid: "Could not join with this link",
+  expired: "This invitation has expired",
+  noToken: "This link is missing its invite token.",
+  askAgain: "Ask the person who invited you to send a new invitation.",
+  signInFirst: "Sign in to accept this invitation",
+  signInHint: "Use the account the invitation was sent to.",
+  signIn: "Sign in",
+  register: "Create account",
+};
+
+/* ── Types ───────────────────────────────────────────────────────────────── */
+
+/** What `onAccept` may resolve with. */
+export interface AcceptInvitationResult {
+  /** What the invitation attached the account to, by name — "Example Property Ltd",
+   *  "Team North", a budget. Said in the confirmation. */
+  name?: string;
+}
+
+/** What became of an invitation that was not accepted. `signIn`: the server wants a
+ *  session first (a `401`), which `signedIn` did not know about. */
+export type AcceptInvitationFailure = "invalid" | "expired" | "signIn";
+
+type Outcome = "accepted" | AcceptInvitationFailure;
+
+export interface AcceptInvitationProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "title"> {
+  /** The invitation's token — the app's `?invite=` / `?token=`. Empty: the link was cut
+   *  short, and the page says so without asking anyone. */
+  token: string;
+  /** Someone is signed in on this device. Until then the page asks for a sign-in and
+   *  sends nothing: accepting attaches the invitation to the SIGNED-IN account. */
+  signedIn: boolean;
+  /**
+   * Accept it — `POST /auth/invitations/accept {token}`, once per token, as soon as
+   * someone is signed in. Resolve (with what it attached the account to, if the app
+   * knows); reject with the client's error.
+   */
+  onAccept: (token: string) => Promise<AcceptInvitationResult | void | undefined>;
+  /** Which dead end a rejection is. Default: `invitation_expired` is `expired`,
+   *  anything else `invalid` (§5.2's codes). Map a `401` to `signIn` here. */
+  classifyError?: (error: unknown) => AcceptInvitationFailure;
+  /** "Continue" — into the app. Default `/`. */
+  continueHref?: string;
+  /** "Sign in" — the app's `/login`, with a way back here (`?next=…`). Default
+   *  `/login`. */
+  signInHref?: string;
+  /** "Create account" beside "Sign in", for an invitation that may lead to a new
+   *  account — the app's `/register?invite=…`. Left out, none. */
+  registerHref?: string;
+  /** 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<AcceptInvitationLabels>;
+}
+
+/**
+ * Accept an invitation with an EXISTING account (docs/auth-harmonization.md §4.4): the
+ * link leads here, the person signs in if they are not, and the app attaches the
+ * invitation — a kastlan user joining a second company, a Kurvenschmiede member a team,
+ * a keksdose user a shared budget. A new address never needs this page: its link opens
+ * the sign-up form, which spends the invitation itself.
+ *
+ * keksdose's `JoinSharePage` (features/budgets/join-page.tsx) is the model: it accepts
+ * on load, once (the token is single-use, and StrictMode's double effect would send it
+ * twice), and shows the outcome where its spinner was. The outcomes: accepted, with the
+ * way into the app; not valid; expired (both say to ask for a new invitation, since
+ * "resend" mints a new token); or "sign in first", with nothing sent. "Continue" REPLACES
+ * this page in the history: the token is spent, so Back must not land here again.
+ */
+export function AcceptInvitation({
+  token,
+  signedIn,
+  onAccept,
+  classifyError,
+  continueHref = "/",
+  signInHref = "/login",
+  registerHref,
+  title,
+  headingAs: Heading = "h2",
+  labels: labelsProp,
+  className,
+  ...rest
+}: AcceptInvitationProps) {
+  const labels = useKitLabels("acceptInvitation", DEFAULT_ACCEPT_INVITATION_LABELS, labelsProp);
+  const [settled, setSettled] = useState<{ token: string; outcome: Outcome; name?: string } | null>(null);
+  const { announce, regionProps } = useAnnounce();
+
+  useOncePerKey(token !== "" && signedIn ? token : null, onAccept, (key, result) => {
+    if (result.ok) {
+      const name = result.value?.name?.trim() || undefined;
+      setSettled({ token: key, outcome: "accepted", name });
+      announce(name ? labels.joined(name) : labels.accepted);
+      return;
+    }
+    const failure: AcceptInvitationFailure =
+      classifyError?.(result.error) ?? (authErrorCode(result.error) === "invitation_expired" ? "expired" : "invalid");
+    setSettled({ token: key, outcome: failure });
+    announce(failure === "signIn" ? labels.signInFirst : labels[failure]);
+  });
+
+  const outcome: Outcome | "accepting" =
+    token === ""
+      ? "invalid"
+      : settled?.token === token
+        ? settled.outcome
+        : signedIn
+          ? "accepting"
+          : "signIn";
+
+  const continueButton = (variant: "brand" | "secondary") => (
+    <Button href={continueHref} replace variant={variant}>
+      {labels.continue}
+    </Button>
+  );
+
+  let body: ReactNode;
+  if (outcome === "accepting") {
+    body = <LoadingState size="sm" label={labels.accepting} />;
+  } else if (outcome === "accepted") {
+    body = (
+      <EmptyState
+        tone="success"
+        icon={<CheckCircle2 />}
+        title={settled?.name ? labels.joined(settled.name) : labels.accepted}
+        action={continueButton("brand")}
+        className={OUTCOME_CLASS}
+      />
+    );
+  } else if (outcome === "signIn") {
+    body = (
+      <EmptyState
+        icon={<LogIn />}
+        title={labels.signInFirst}
+        hint={labels.signInHint}
+        action={
+          <>
+            <Button href={signInHref} variant="brand">
+              {labels.signIn}
+            </Button>
+            {registerHref !== undefined && (
+              <Button href={registerHref} variant="secondary">
+                {labels.register}
+              </Button>
+            )}
+          </>
+        }
+        className={OUTCOME_CLASS}
+      />
+    );
+  } else {
+    body = (
+      <EmptyState
+        tone="danger"
+        icon={outcome === "expired" ? <TimerOff /> : <XCircle />}
+        title={token === "" ? labels.noToken : labels[outcome]}
+        hint={labels.askAgain}
+        action={signedIn ? continueButton("secondary") : undefined}
+        className={OUTCOME_CLASS}
+      />
+    );
+  }
+
+  return (
+    <div
+      {...rest}
+      data-state={outcome}
+      aria-busy={outcome === "accepting" || undefined}
+      className={cn("space-y-3", className)}
+    >
+      {title === null ? null : <Heading className={STATUS_HEADING_CLASS}>{title ?? labels.title}</Heading>}
+      {body}
+      {/* Rendered from the start, so the outcome is read when it arrives. */}
+      <div {...regionProps} />
+    </div>
+  );
+}

package/src/auth/auth-errors.ts

@@ -0,0 +1,105 @@
+/**
+ * The coded refusals of sign-in and sign-up (docs/auth-harmonization.md §5.2): every
+ * refusal the auth routes answer carries a machine-readable `code`, and the pages
+ * recognise the CODE, never the server's sentence.
+ *
+ * Today each app's pages print the server's `detail` string (keksdose's
+ * `extractApiErrorMessage`), which is English on every locale and, on a credential
+ * check, would be an account-enumeration oracle if it ever said more than one thing.
+ * keksdose already keys one refusal on a code (`features/budgets/plan-limit.ts`,
+ * `402 {detail, code: "plan_budget_limit"}`); §5.2 makes that the rule for auth. Each
+ * app switches its server and its pages together (§9).
+ *
+ * - `invalid_credentials` — unknown address, wrong password AND deactivated account:
+ *   one answer, in the same time (§2.10). `401`.
+ * - `registration_closed` — the sign-up gate refused the address. `403`.
+ * - `email_taken` — an account with this address exists. `409`.
+ * - `invitation_invalid`, `invitation_expired` — the `invite` token of a sign-up or an
+ *   accept (§4.4).
+ * - `token_invalid` — a one-time token (reset, verification, a sign-in challenge) is
+ *   unknown, spent or expired.
+ * - `account_inactive` — **no server answers it.** §2.10 decided that a deactivated
+ *   account gets `invalid_credentials`, because a separate answer after a correct
+ *   password would confirm a leaked one. It stays in the union only for a future server
+ *   step that is past the password (an admin view, a signed-in refresh) and may say so.
+ */
+export type AuthErrorCode =
+  | "invalid_credentials"
+  | "registration_closed"
+  | "email_taken"
+  | "invitation_invalid"
+  | "invitation_expired"
+  | "token_invalid"
+  | "account_inactive";
+
+const CODES: ReadonlySet<string> = new Set<AuthErrorCode>([
+  "invalid_credentials",
+  "registration_closed",
+  "email_taken",
+  "invitation_invalid",
+  "invitation_expired",
+  "token_invalid",
+  "account_inactive",
+]);
+
+type Bag = Record<string, unknown>;
+
+const isBag = (value: unknown): value is Bag => typeof value === "object" && value !== null;
+
+/** A known code, or undefined. */
+function known(value: unknown): AuthErrorCode | undefined {
+  return typeof value === "string" && CODES.has(value) ? (value as AuthErrorCode) : undefined;
+}
+
+/** `{code}` on a parsed body, or FastAPI's `{detail: {code}}` — what an
+ *  `HTTPException(detail={"code": …})` serialises to. */
+function codeOfBody(body: unknown): AuthErrorCode | undefined {
+  if (!isBag(body)) return undefined;
+  return known(body.code) ?? (isBag(body.detail) ? known(body.detail.code) : undefined);
+}
+
+/**
+ * The {@link AuthErrorCode} an error carries, or `undefined` when it carries none.
+ *
+ * Reads the parsed response body wherever the apps' HTTP clients put it, without
+ * depending on any of them:
+ *
+ *  1. `err.response.data` — axios (keksdose's, kastlan's and Kurvenschmiede's clients;
+ *     keksdose's `isPlanBudgetLimitRefusal` reads the same path);
+ *  2. `err.data` — ofetch's `FetchError`, and most `fetch` wrappers that parse the body;
+ *  3. `err.body` — the generated OpenAPI clients' `ApiError`;
+ *  4. `err` itself — a body thrown as it came (`throw await res.json()`).
+ *
+ * In each, `code` or FastAPI's nested `detail.code`. Last, `err.code` — but only when
+ * it is one of the codes above: axios writes its OWN codes there (`ERR_NETWORK`,
+ * `ECONNABORTED`, `ERR_BAD_REQUEST`), and so does Node, so an unknown value is never
+ * read as a refusal. The HTTP status is not checked: the code is the contract, and the
+ * status differs per refusal (401, 403, 409, 410).
+ */
+export function authErrorCode(err: unknown): AuthErrorCode | undefined {
+  if (!isBag(err)) return undefined;
+  const response = err.response;
+  return (
+    (isBag(response) ? codeOfBody(response.data) : undefined) ??
+    codeOfBody(err.data) ??
+    codeOfBody(err.body) ??
+    codeOfBody(err)
+  );
+}
+
+/**
+ * Whether `err` is a coded auth refusal — any of them, or the one named:
+ *
+ * ```ts
+ * try { await api.register(values) }
+ * catch (err) { if (isAuthError(err, "email_taken")) … }
+ * ```
+ *
+ * The kit's `SignInForm` and `RegisterForm` call it on what their callbacks reject
+ * with, so an app's `onSubmit` can simply let its client's error through. See
+ * {@link authErrorCode} for the shapes it reads.
+ */
+export function isAuthError(err: unknown, code?: AuthErrorCode): boolean {
+  const found = authErrorCode(err);
+  return found !== undefined && (code === undefined || found === code);
+}

package/src/auth/complete-name-dialog.tsx

@@ -0,0 +1,253 @@
+import { useContext, useEffect, useId, useRef, useState } from "react";
+import type { KeyboardEvent, ReactNode } from "react";
+
+import { useKitLabels } from "../i18n/kit-labels";
+import { usePromisePending } from "../components/danger-confirm";
+import { DialogFrame } from "../components/dialog-frame";
+import { ModalCloseContext } from "../components/modal";
+import { Button, Input } from "../components/ui";
+import { personNameOk, PERSON_NAME_MAX_LENGTH } from "./form-rules";
+
+/** What `CompleteNameDialog` hands `onSave`: both names, trimmed, 1–120 characters —
+ *  `PATCH /auth/me {first_name, last_name}` (§6.1). */
+export interface CompleteNameValues {
+  firstName: string;
+  lastName: string;
+}
+
+/**
+ * Every string the dialog renders — the `completeName` namespace of `<UiKitProvider
+ * labels>`, overridable per instance through `labels`.
+ */
+export interface CompleteNameLabels {
+  title: string;
+  description: string;
+  firstName: string;
+  lastName: string;
+  save: string;
+  /** Dismisses the dialog until the next sign-in. */
+  later: string;
+  /** Under the fields when `onSave` rejected and the app passed no `error`. */
+  failed: string;
+}
+
+export const DEFAULT_COMPLETE_NAME_LABELS: CompleteNameLabels = {
+  title: "Complete your name",
+  description: "First and last name are now asked for separately. Check what is filled in and add what is missing.",
+  firstName: "First name",
+  lastName: "Last name",
+  save: "Save",
+  later: "Later",
+  failed: "Your name could not be saved. Please try again.",
+};
+
+export interface CompleteNameDialogProps {
+  /** What the account holds now — after the migration, the old display name (§3.3). */
+  firstName?: string;
+  /** Usually empty: that is why the dialog is up. */
+  lastName?: string;
+  /**
+   * Save the names (`PATCH /auth/me`). Resolve and the dialog closes (`onClose(true)`);
+   * reject and it stays open with the names kept and `error` — or "Your name could not
+   * be saved" — under them.
+   */
+  onSave: (values: CompleteNameValues) => Promise<unknown>;
+  /**
+   * The dialog has closed: `true` after a resolved `onSave`, `false` for "Later", Escape,
+   * the backdrop and Back. `false` only DEFERS it: the app shows it again after the
+   * next sign-in while `/auth/me` still answers `name_incomplete: true`.
+   */
+  onClose: (saved: boolean) => void;
+  /** The app's words for the last failed save, instead of `labels.failed`. Hidden again
+   *  once a name is edited. */
+  error?: ReactNode;
+  /** Kept-mounted mode, as on `Modal`: left out, the dialog is open while mounted. */
+  open?: boolean;
+  labels?: Partial<CompleteNameLabels>;
+}
+
+/**
+ * "Complete your name" — asked once after sign-in of a user whose name was migrated
+ * (docs/auth-harmonization.md §3.3). keksdose's and Kurvenschmiede's accounts had one
+ * `display_name`; it moved whole into `first_name`, `last_name` stayed empty, and
+ * nothing was split by guesswork (§2.4). The app shows this while `/auth/me` answers
+ * `name_incomplete: true` — never for a demo user.
+ *
+ * Both names prefilled with what is there; "Save" waits until both have 1–120
+ * characters after trimming. **"Later" only defers it**: nothing else waits on a
+ * complete name, no page is blocked, and the app asks again at the next sign-in.
+ *
+ * The promise handling is `ReauthDialog`'s: busy while `onSave` runs (the fields
+ * read-only, "Later" disabled, Escape held — a request that has left cannot be called
+ * back by closing the dialog), closed on resolve, kept open on reject. Save is a
+ * `commit` control, so a `WriteLockProvider` above it locks it with its reason.
+ *
+ * Focus starts in the first EMPTY field — the last name, as a rule — because filling it
+ * in is the whole of what the dialog is for.
+ */
+export function CompleteNameDialog({
+  firstName: initialFirst = "",
+  lastName: initialLast = "",
+  onSave,
+  onClose,
+  error,
+  open,
+  labels: labelsProp,
+}: CompleteNameDialogProps) {
+  const labels = useKitLabels("completeName", DEFAULT_COMPLETE_NAME_LABELS, labelsProp);
+  const [first, setFirst] = useState(initialFirst);
+  const [last, setLast] = useState(initialLast);
+  // A failed save describes the names that were sent; an edit makes it stale.
+  const [failed, setFailed] = useState(false);
+  const { pending, run } = usePromisePending();
+  const [done, setDone] = useState(false);
+  const saved = useRef(false);
+  const formId = useId();
+  const firstRef = useRef<HTMLInputElement>(null);
+  const lastRef = useRef<HTMLInputElement>(null);
+  const isOpen = open ?? true;
+
+  // Reopened (kept-mounted): start again from what the account holds. During render,
+  // as ReauthDialog wipes its password, so no frame shows the old draft.
+  const [wasOpen, setWasOpen] = useState(isOpen);
+  if (wasOpen !== isOpen) {
+    setWasOpen(isOpen);
+    if (isOpen) {
+      setFirst(initialFirst);
+      setLast(initialLast);
+      setFailed(false);
+      setDone(false);
+    }
+  }
+
+  // After Modal's own effect, so its trap has recorded the trigger before focus moves.
+  useEffect(() => {
+    if (!isOpen) return;
+    saved.current = false;
+    const target = firstRef.current?.value.trim() ? lastRef.current : firstRef.current;
+    target?.focus();
+  }, [isOpen]);
+
+  const canSave = personNameOk(first) && personNameOk(last);
+
+  const submit = () => {
+    if (pending || !canSave) return;
+    setFailed(false);
+    const values = { firstName: first.trim(), lastName: last.trim() };
+    let result: Promise<unknown>;
+    try {
+      result = Promise.resolve(onSave(values));
+    } catch (err) {
+      result = Promise.reject(err);
+    }
+    // A rejection must not go unhandled; usePromisePending clears `pending` on it.
+    result.catch(() => setFailed(true));
+    run(result, () => {
+      saved.current = true;
+      setDone(true);
+    });
+  };
+
+  const edit = (set: (value: string) => void) => (value: string) => {
+    set(value);
+    setFailed(false);
+  };
+
+  const message = failed ? (error ?? labels.failed) : undefined;
+
+  return (
+    <DialogFrame
+      open={open}
+      title={labels.title}
+      description={labels.description}
+      onClose={() => onClose(saved.current)}
+      onKeyDown={(e: KeyboardEvent<HTMLDivElement>) => {
+        if (pending && e.key === "Escape") e.preventDefault();
+      }}
+      aria-busy={pending || undefined}
+      actions={
+        <CompleteNameActions
+          formId={formId}
+          done={done}
+          busy={pending}
+          canSave={canSave}
+          laterLabel={labels.later}
+          saveLabel={labels.save}
+        />
+      }
+    >
+      <form
+        id={formId}
+        noValidate
+        className="grid gap-3 @container"
+        onSubmit={(e) => {
+          e.preventDefault();
+          submit();
+        }}
+      >
+        <div className="grid gap-3 @xs:grid-cols-2">
+          <Input
+            ref={firstRef}
+            name="given-name"
+            autoComplete="given-name"
+            label={labels.firstName}
+            value={first}
+            onChange={(e) => edit(setFirst)(e.target.value)}
+            maxLength={PERSON_NAME_MAX_LENGTH}
+            readOnly={pending}
+            required
+          />
+          <Input
+            ref={lastRef}
+            name="family-name"
+            autoComplete="family-name"
+            label={labels.lastName}
+            value={last}
+            onChange={(e) => edit(setLast)(e.target.value)}
+            maxLength={PERSON_NAME_MAX_LENGTH}
+            readOnly={pending}
+            required
+          />
+        </div>
+        {message !== undefined && (
+          <p role="alert" className="text-xs text-[var(--danger)]">
+            {message}
+          </p>
+        )}
+      </form>
+    </DialogFrame>
+  );
+}
+
+/** The actions row, inside the `Modal`, where its animated close is in context: a
+ *  resolved save lowers the panel through it, as "Later" and Escape do. */
+function CompleteNameActions({
+  formId,
+  done,
+  busy,
+  canSave,
+  laterLabel,
+  saveLabel,
+}: {
+  formId: string;
+  done: boolean;
+  busy: boolean;
+  canSave: boolean;
+  laterLabel: string;
+  saveLabel: string;
+}) {
+  const close = useContext(ModalCloseContext);
+  useEffect(() => {
+    if (done) close?.();
+  }, [done, close]);
+  return (
+    <>
+      <Button type="button" variant="ghost" disabled={busy} onClick={() => close?.()}>
+        {laterLabel}
+      </Button>
+      <Button type="submit" form={formId} commit disabled={!busy && !canSave} pending={busy}>
+        {saveLabel}
+      </Button>
+    </>
+  );
+}

package/src/auth/email-tag.ts

@@ -0,0 +1,75 @@
+/**
+ * The address tag: `you@example.com` → `you+kastlan@example.com`, the app's own name as
+ * a sub-address of the address a person types for themselves (docs/auth-harmonization.md
+ * §4.5, Marcel 2026-10-05). Lifted from keksdose (`features/auth/email-tag.ts`, feedback
+ * dev#481), where the tag was the constant `keksdose`; here it is the app's.
+ *
+ * **Structurally valid is not the same as deliverable.** `+` is an ordinary character in
+ * the local part under RFC 5322, and sub-addressing — `user+tag@host` delivered to
+ * `user@host` — is specified (RFC 5233). But it is specified as a convention the
+ * RECEIVING server may implement: Gmail, Outlook, iCloud, Fastmail and Proton do; many
+ * Exchange installs, small hosters and corporate filters do not, and some web forms
+ * refuse the character outright.
+ *
+ * Which is why every caller OFFERS the result and never applies it. Silently registering
+ * somebody as `you+kastlan@example.com` would send the verification mail — the one
+ * message the account depends on — down a delivery path nobody checked, and make the
+ * address they sign in with one they never typed. The tag is a convenience for the
+ * person who wants it: one click, with the exact resulting address on the button
+ * (`RegisterForm` does this with its `emailTag`).
+ *
+ * The tagged address is then the identity. The server trims and lower-cases an address
+ * at every entry and never strips a tag, so `you@…` and `you+kastlan@…` are two
+ * different accounts; sign-in stays exact (§4.5), which is why `SignInForm`'s hint after
+ * a failed sign-in names the tagged address rather than trying it.
+ *
+ * Offer it only where a person types an address FOR THEMSELVES — sign-up, a later email
+ * change in the profile — never in a field for someone else's (an invite dialog, a
+ * share), where the tag would be a guess about another person's mail server.
+ */
+
+/** What a tag may be: the app's name, lower case — letters, digits, `.`, `_`, `-`. A
+ *  space, `@` or `+` would make the result something other than a sub-address. */
+const TAG_SHAPE = /^[a-z0-9][a-z0-9._-]*$/;
+
+/**
+ * `taggedEmail("you@example.com", "kastlan")` → `"you+kastlan@example.com"`, or `null`
+ * when there is nothing to offer:
+ *
+ *  - the address is not complete enough to split — no local part, no domain, or a
+ *    domain without an inner dot (the shape the field's own `type="email"` accepts), so
+ *    the offer cannot appear before the address is plausible or linger once it stops
+ *    being one;
+ *  - the address already carries a `+` — the person's own scheme wins, and stacking a
+ *    second tag on it would be wrong;
+ *  - the tag is empty or not a plain name (see `TAG_SHAPE`).
+ *
+ * The tag is the app's name in lower case (`keksdose`, `kastlan`, `kurvenschmiede`); it
+ * is trimmed and lower-cased here, so `"Kastlan"` gives the same answer. The address is
+ * trimmed and otherwise kept as typed — normalising it is the server's job (server-kit's
+ * `normalise_email`).
+ */
+export function taggedEmail(email: string, tag: string): string | null {
+  const name = tag.trim().toLowerCase();
+  if (!TAG_SHAPE.test(name)) return null;
+  const parts = emailParts(email);
+  if (!parts || parts.local.includes("+")) return null;
+  return `${parts.local}+${name}@${parts.domain}`;
+}
+
+/**
+ * The trimmed address split at its last `@`, or `null` while it is not complete enough
+ * to split: no local part, no domain, or a domain without an inner dot — the shape the
+ * field's own `type="email"` accepts.
+ *
+ * @internal `RegisterForm` gates its submit on it; not part of the barrel.
+ */
+export function emailParts(email: string): { local: string; domain: string } | null {
+  const trimmed = email.trim();
+  const at = trimmed.lastIndexOf("@");
+  if (at <= 0 || at === trimmed.length - 1) return null;
+  const local = trimmed.slice(0, at);
+  const domain = trimmed.slice(at + 1);
+  if (!domain.includes(".") || domain.startsWith(".") || domain.endsWith(".")) return null;
+  return { local, domain };
+}