@eifi1/ui-kit 0.17.0 → 0.18.0

package/src/components/confirm-dialog.tsx

@@ -2,8 +2,10 @@ import { createContext, useCallback, useContext, useEffect, useRef, useState } f
 import type { ReactNode } from "react";
 
 import { useKitLabels } from "../i18n/kit-labels";
+import { typedMatches } from "./danger-confirm";
+import type { TypedMatch } from "./danger-confirm";
 import { DialogFrame } from "./dialog-frame";
-import { Button } from "./ui";
+import { Button, Input } from "./ui";
 
 /**
  * The `confirmDialog` namespace of `<UiKitProvider labels>`: the two buttons' fallback
@@ -13,12 +15,25 @@ import { Button } from "./ui";
 export interface ConfirmDialogLabels {
   confirm: string;
   cancel: string;
+  /**
+   * 0.18: label of the field a `requireTyped` confirm shows. A FUNCTION of the text to
+   * type by default — where the address sits in the sentence moves with the language —
+   * or a finished STRING. A call's own `typedLabel` wins over it.
+   *
+   * Required, like every key of a namespace: the shipped catalogues
+   * (`@eifi1/ui-kit/i18n/<code>`) translate it, and an app's own full catalogue should
+   * hear about the new string from the compiler rather than show it in English.
+   */
+  typed: string | ((text: string) => string);
 }
 
-export const DEFAULT_CONFIRM_DIALOG_LABELS: ConfirmDialogLabels = {
+/** `satisfies` rather than a type annotation, so `.typed` stays known-callable for a
+ *  caller composing its own label from it. */
+export const DEFAULT_CONFIRM_DIALOG_LABELS = {
   confirm: "Confirm",
   cancel: "Cancel",
-};
+  typed: (text: string) => `Type “${text}” to confirm`,
+} satisfies ConfirmDialogLabels;
 
 export type ConfirmTone = "danger" | "warning" | "neutral";
 
@@ -37,6 +52,30 @@ export interface ConfirmOptions {
    * the confirm. See {@link ConfirmProvider} for why the two differ.
    */
   tone?: ConfirmTone;
+  /**
+   * 0.18: make the user TYPE this before confirm is enabled — the target account's
+   * e-mail address, a budget's name. For the action whose risk is not "did you mean
+   * it" but "is this the right row": an admin who deactivates somebody has already
+   * proven who THEY are (they passed the admin gate); typing the address is what
+   * proves they read which account they are on. Both keksdose (`TYPE_EMAIL`) and
+   * Kurvenschmiede (`TypedConfirm`) built this beside `useConfirm` because it had no
+   * field.
+   *
+   * The dialog then shows one text field under the body and focuses it (whatever the
+   * tone: a reflexive Enter cannot confirm a field that does not match yet). Confirm
+   * stays disabled until the text matches; Enter in the field confirms once it does.
+   * The answer is still `true` / `false` — the text matched what you passed, so send
+   * that to the server if it asks for the address too, not the user's spelling.
+   */
+  requireTyped?: string;
+  /** Label of that field. Default: `confirmDialog.typed` — `Type “a@b.c” to confirm`. */
+  typedLabel?: string;
+  /**
+   * How the typed text is compared. Default `"caseless"`: surrounding spaces and case
+   * ignored, the rule both apps applied to an address. `"trim"` keeps case, `"exact"`
+   * keeps spaces too — for a phrase like "DELETE" whose contract is "exactly this".
+   */
+  typedMatch?: TypedMatch;
 }
 
 export type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
@@ -201,15 +240,26 @@ function ConfirmDialogView({
   // Set by the confirm button, read once the panel has finished lowering. Everything
   // else that ends in `onClose` — Escape, the backdrop, Back, Cancel — leaves it false.
   const accepted = useRef(false);
+  const typedRef = useRef<HTMLInputElement>(null);
+  const [typed, setTyped] = useState("");
+  const target = request.requireTyped;
+  const matches = target === undefined || typedMatches(typed, target, request.typedMatch ?? "caseless");
 
   // In THIS component's effect, which runs after `Modal`'s own (a parent's effects run
   // after its children's). `Modal` engages its focus trap on the panel first — and
   // records the page's focused element as the restore target — and only then does
   // focus move to the button. Focusing it from inside the panel would run first and
-  // make the button the restore target.
+  // make the button the restore target. A typed confirm starts in its field: typing is
+  // the one thing the dialog is waiting for.
   useEffect(() => {
-    (tone === "danger" ? cancelRef : confirmRef).current?.focus();
-  }, [tone]);
+    (target !== undefined ? typedRef : tone === "danger" ? cancelRef : confirmRef).current?.focus();
+  }, [tone, target]);
+
+  const typedLabel =
+    target === undefined
+      ? ""
+      : (request.typedLabel ??
+        (typeof labels.typed === "string" ? labels.typed : labels.typed(target)));
 
   return (
     <DialogFrame
@@ -228,6 +278,7 @@ function ConfirmDialogView({
             ref={confirmRef}
             type="button"
             variant={tone === "danger" ? "danger" : "primary"}
+            disabled={!matches}
             onClick={() => {
               accepted.current = true;
               close();
@@ -237,6 +288,30 @@ function ConfirmDialogView({
           </Button>
         </>
       )}
-    />
+    >
+      {/* The field, when there is one, is the body; a plain confirm keeps having none. */}
+      {target !== undefined && (
+        <form
+          noValidate
+          onSubmit={(e) => {
+            e.preventDefault();
+            // Through the button, so Enter and a click are one path — and a disabled
+            // (not yet matching) confirm ignores the click.
+            confirmRef.current?.click();
+          }}
+        >
+          <Input
+            ref={typedRef}
+            label={typedLabel}
+            value={typed}
+            autoComplete="off"
+            autoCapitalize="off"
+            autoCorrect="off"
+            spellCheck={false}
+            onChange={(e) => setTyped(e.target.value)}
+          />
+        </form>
+      )}
+    </DialogFrame>
   );
 }

package/src/components/danger-confirm.tsx

@@ -1,10 +1,113 @@
-import { useEffect, useId, useRef, useState } from "react";
-import type { ChangeEvent, ComponentPropsWithoutRef, FormEvent, ReactNode } from "react";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import type { ChangeEvent, ComponentPropsWithoutRef, FormEvent, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
 import { Button, Input, Label, Spinner } from "./ui";
 import { Tooltip } from "./tooltip";
 
+/**
+ * How typed text is compared with the text it has to repeat — shared by
+ * `DangerConfirm`'s `phraseMatch` and `useConfirm`'s `typedMatch`.
+ *
+ * - `"trim"` ignores spaces around the typed text — a phone keyboard's autocomplete
+ *   likes to add one. Case counts: "delete" is not "DELETE".
+ * - `"exact"` compares character for character, spaces included.
+ * - `"caseless"` trims AND ignores case: for an e-mail address, whose domain is
+ *   case-insensitive and whose local part every real mail server treats so. Both apps'
+ *   "type the account's address" rules (keksdose's `TYPE_EMAIL`, Kurvenschmiede's
+ *   `TypedConfirm`) compared `trim().toLowerCase()`, and a capital the user's keyboard
+ *   put at the start must not make the right row look like the wrong one.
+ */
+export type TypedMatch = "trim" | "exact" | "caseless";
+
+/** Whether `typed` repeats `target` under `mode` — see {@link TypedMatch}. Exported for
+ *  a caller that draws its own field (a dialog that also picks a recipient) and wants
+ *  the same rule as the kit's. */
+export function typedMatches(typed: string, target: string, mode: TypedMatch = "trim"): boolean {
+  if (mode === "exact") return typed === target;
+  if (mode === "trim") return typed.trim() === target;
+  // `toLowerCase`, not `toLocaleLowerCase`: the comparison must not change with the
+  // reader's locale (a Turkish dotless i would otherwise fail an ASCII address).
+  return typed.trim().toLowerCase() === target.trim().toLowerCase();
+}
+
+/**
+ * Busy-while-a-promise-runs, for an action that MAY return one: `run(result, onResolved)`
+ * marks the caller pending until `result` settles, calls `onResolved` if it fulfilled,
+ * and only clears the flag if it rejected — the caller shows why and the user retries.
+ * Nothing runs after unmount. Shared by `DangerConfirm` and `ReauthDialog`, whose
+ * contract is the same: resolve = done, reject = stay put.
+ *
+ * @internal
+ */
+export function usePromisePending() {
+  const [pending, setPending] = useState(false);
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const run = useCallback((result: unknown, onResolved: () => void): boolean => {
+    if (!result || typeof (result as Promise<unknown>).then !== "function") return false;
+    setPending(true);
+    (result as Promise<unknown>).then(
+      () => {
+        if (!mounted.current) return;
+        setPending(false);
+        onResolved();
+      },
+      () => {
+        if (mounted.current) setPending(false);
+      },
+    );
+    return true;
+  }, []);
+  return { pending, run };
+}
+
+/**
+ * The "prove it is you" field: a password input the browser's password manager fills
+ * with the CURRENT password (`autocomplete="current-password"`), never offers to
+ * generate a new one for. `readOnly` rather than `disabled` while busy: disabling the
+ * field that has focus (Enter was pressed in it) drops focus to <body>.
+ *
+ * @internal DangerConfirm's field. ReauthDialog spells it out with the field's own
+ * `error`, which keeps the `<input>` mounted while its message comes and goes.
+ */
+export function CurrentPasswordInput({
+  inputRef,
+  label,
+  value,
+  onValueChange,
+  busy,
+  invalid,
+  describedBy,
+}: {
+  inputRef?: Ref<HTMLInputElement>;
+  label: string;
+  value: string;
+  onValueChange: (value: string) => void;
+  busy: boolean;
+  invalid?: boolean;
+  describedBy?: string;
+}) {
+  return (
+    <Input
+      ref={inputRef}
+      type="password"
+      autoComplete="current-password"
+      label={label}
+      value={value}
+      readOnly={busy}
+      invalid={invalid}
+      aria-describedby={describedBy}
+      onChange={(e) => onValueChange(e.target.value)}
+    />
+  );
+}
+
 /**
  * Every string the tile renders — the `dangerConfirm` namespace of
  * `<UiKitProvider labels>`, overridable per instance through `labels`. The arm and
@@ -65,9 +168,11 @@ export interface DangerConfirmProps extends Omit<ComponentPropsWithoutRef<"div">
    * How the typed text is compared with `phrase`. `"trim"` (default) ignores spaces
    * around it — a phone keyboard's autocomplete likes to add one. `"exact"` compares
    * character for character, spaces included, for an app whose contract is "type
-   * exactly this".
+   * exactly this". `"caseless"` (0.18) also ignores case — for a phrase that is an
+   * e-mail address (keksdose's "type the user's address" admin rule). See
+   * {@link TypedMatch}.
    */
-  phraseMatch?: "trim" | "exact";
+  phraseMatch?: TypedMatch;
   /** The warning above the fields. Defaults to `labels.prompt`. */
   prompt?: ReactNode;
   /** `"danger"` (default) for what cannot be undone; `"warning"` for what can, at a
@@ -140,7 +245,7 @@ export function DangerConfirm({
   const armed = armedProp ?? armedState;
   const [password, setPassword] = useState("");
   const [typed, setTyped] = useState("");
-  const [pending, setPending] = useState(false);
+  const { pending, run } = usePromisePending();
   const busy = Boolean(busyProp) || pending;
   // `readOnly` rather than `disabled` on the fields while busy: disabling the field
   // that has focus (Enter was pressed in it) drops focus to <body>.
@@ -155,13 +260,6 @@ export function DangerConfirm({
   // Focus moves only after a transition — never on mount, so a tile that renders armed
   // (controlled) does not take the page's focus merely by existing.
   const moveFocus = useRef(false);
-  const mounted = useRef(true);
-  useEffect(() => {
-    mounted.current = true;
-    return () => {
-      mounted.current = false;
-    };
-  }, []);
 
   // A disarm from anywhere (cancel, a resolved confirm, the parent) wipes the fields.
   // During render, like NumberField's draft, so no frame shows a collapsed tile that
@@ -200,26 +298,15 @@ export function DangerConfirm({
 
   const locked = lockedReason !== undefined && lockedReason !== null && lockedReason !== false && lockedReason !== "";
   const passwordOk = !requirePassword || password !== "";
-  const phraseOk = phrase === undefined || (phraseMatch === "exact" ? typed : typed.trim()) === phrase;
+  const phraseOk = phrase === undefined || typedMatches(typed, phrase, phraseMatch);
   const canConfirm = passwordOk && phraseOk && !busy;
 
   const submit = (e: FormEvent) => {
     e.preventDefault();
     if (!canConfirm) return;
-    const result = onConfirm(requirePassword ? password : undefined);
-    if (!result || typeof (result as Promise<unknown>).then !== "function") return;
-    setPending(true);
-    (result as Promise<unknown>).then(
-      () => {
-        if (!mounted.current) return;
-        setPending(false);
-        setArmed(false);
-      },
-      () => {
-        // Stays armed, fields kept: the caller shows why, the user retries.
-        if (mounted.current) setPending(false);
-      },
-    );
+    // Disarms when it resolves; a rejection leaves it armed, fields kept: the caller
+    // shows why, the user retries.
+    run(onConfirm(requirePassword ? password : undefined), () => setArmed(false));
   };
 
   const phrasePlaceholder =
@@ -309,15 +396,13 @@ export function DangerConfirm({
             <Input label={phraseLabel} {...phraseFieldProps} />
           ))}
         {requirePassword && (
-          <Input
+          <CurrentPasswordInput
             // The phrase field takes the ref when both are there — it comes first.
-            ref={phrase === undefined ? firstFieldRef : undefined}
-            type="password"
-            autoComplete="current-password"
+            inputRef={phrase === undefined ? firstFieldRef : undefined}
             label={labels.password}
             value={password}
-            readOnly={busy}
-            onChange={(e) => setPassword(e.target.value)}
+            busy={busy}
+            onValueChange={setPassword}
           />
         )}
         <div className="flex flex-wrap gap-2">

package/src/components/data-table.tsx

@@ -355,6 +355,24 @@ export interface DataTableProps<T> {
    * of unfolding it inline (feedback #204). Desktop always uses inline expansion.
    */
   mobileExpandAsDialog?: boolean;
+  /**
+   * The phone row dialog's `backCloses` ({@link FullBleedDialog}): whether it pushes
+   * its own history entry so Back dismisses it. On by default — right for a row whose
+   * expansion is component state, where nothing else would answer Back.
+   *
+   * **Set it `false` when the open row is in the URL** and opening it PUSHES (a
+   * `?row=` written with `useSearchParamState(…, { history: "replace-on-clear" })` or
+   * `"push"`): Back already closes the row through the router, and a second entry on
+   * top of the page's is two owners of one Back press (keksdose dev #584). Keep it on
+   * when opening the row REPLACES the URL — then nothing was pushed, and the dialog's
+   * own entry is the only thing Back can pop.
+   *
+   * The table cannot decide this for you: `isExpanded` is a predicate, and neither it
+   * nor `rowHref` says whether opening pushed or replaced (keksdose's feedback page
+   * has `rowHref` with a REPLACING `?row=`, and needs the entry). Ignored unless
+   * `mobileExpandAsDialog`.
+   */
+  mobileDialogBackCloses?: boolean;
   /**
    * Group the mobile card list into sections, each with a sticky header — the
    * "assistance"-style list (like the transactions list grouped by date, but by
@@ -835,6 +853,7 @@ export function DataTable<T>({
   locale: localeProp,
   storageKeyPrefix = DEFAULT_PERSIST_PREFIX,
   mobileExpandAsDialog = false,
+  mobileDialogBackCloses = true,
   mobileGroupBy,
   mobileGroupLabel,
   mobileCard,
@@ -1856,6 +1875,7 @@ export function DataTable<T>({
           onClose={closeDialog}
           closeLabel={labels.close}
           header={mobileDialogRow ? mobilePrimaryCol?.cell(mobileDialogRow) : null}
+          backCloses={mobileDialogBackCloses}
         >
           {mobileDialogContent}
         </FullBleedDialog>

package/src/components/form-actions.tsx

@@ -37,7 +37,8 @@ export type FormActionsPlacement = "inline" | "sticky" | "dialog";
  * md 768, lg 1024, xl 1280px), as `BulkActionBar`'s `variant` breakpoints are, and
  * resolved the same way, in JS: the sticky row is positioned by inline style, which a
  * `md:` class cannot reach. keksdose switched `placement` on its own media query at
- * every long form for want of this.
+ * every long form for want of this. The breakpoints are the VIEWPORT's, not the
+ * container's: a form in a narrow pane on a wide screen resolves to `md`.
  */
 export interface ResponsiveFormActionsPlacement {
   base: FormActionsPlacement;
@@ -96,7 +97,7 @@ export type FormActionsStickyWithin = "viewport" | "container";
  */
 export type FormActionsSubmitProps = Omit<
   ButtonProps,
-  "type" | "onClick" | "disabled" | "disabledReason" | "variant" | "form" | "children" | "aria-busy"
+  "type" | "onClick" | "disabled" | "disabledReason" | "variant" | "form" | "children" | "aria-busy" | "commit"
 > & { [key: `data-${string}`]: string | number | boolean | undefined };
 
 /** The start-side action of {@link FormActionsProps.destructive}, as data. */
@@ -157,6 +158,18 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
   submitDisabled?: boolean;
   /** Why save is disabled — see Button's `disabledReason`. Keeps it focusable. */
   submitDisabledReason?: ReactNode;
+  /**
+   * Save is a commit: under a locked {@link WriteLockProvider} it is disabled with the
+   * lock's reason (over `submitDisabledReason`), focusable, the reason in its tooltip —
+   * Button's `commit`. The `{ label, onClick }` form of {@link destructive} is a
+   * commit too and is locked with it; Cancel and `children` are not (closing a form
+   * writes nothing). No provider, or an unlocked one: no effect. Default `false`.
+   *
+   * keksdose wrote `submitDisabled={lock.locked || …}` and
+   * `submitDisabledReason={lock.locked ? lock.reason : undefined}` at each form; this is
+   * that pair, read from the provider.
+   */
+  commit?: boolean;
   /** The save button's variant. Default `brand`; `danger` for a save that destroys
    *  (kastlan's `destructive` flag on its own FormActions). */
   submitVariant?: ButtonVariant;
@@ -187,7 +200,8 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
    * from both sides, with the content scrolling past it in the gutters (keksdose wrote
    * `@max-md:-mx-3 @max-md:px-3` by hand). Pass the container's padding (`"0.75rem"`,
    * `12`, `"var(--pane-px)"`). Applied only while the resolved placement is sticky, so
-   * `placement={{ base: "sticky", md: "inline" }}` bleeds on the phone alone.
+   * `placement={{ base: "sticky", md: "inline" }}` bleeds on the phone alone. The margin
+   * is `calc(-1 * X)`; jsdom folds that to `calc(-X)`, so match it loosely in tests.
    */
   bleed?: string | number;
   /**
@@ -249,6 +263,7 @@ export function FormActions({
   pending = false,
   submitDisabled = false,
   submitDisabledReason,
+  commit = false,
   submitVariant = "brand",
   destructive,
   start: startSlot,
@@ -276,6 +291,7 @@ export function FormActions({
       onClick={destructive.onClick}
       disabled={destructive.disabled}
       disabledReason={destructive.disabledReason}
+      commit={commit}
     >
       {destructive.label}
     </Button>
@@ -332,6 +348,9 @@ export function FormActions({
           variant={submitVariant}
           disabled={pending || submitDisabled}
           disabledReason={pending ? undefined : submitDisabledReason}
+          // Not while pending: the save already left, and the lock's look over the
+          // spinner would say it had not.
+          commit={commit && !pending}
           aria-busy={pending || undefined}
         >
           {pending ? (

package/src/components/number-field.tsx

@@ -154,26 +154,27 @@ const FIELD_ERROR_CLASS = "mt-1 text-[11px] leading-tight text-[var(--danger)]";
  * digit grouping — "1.000" would read as a thousand in German and as one in English,
  * and a field that parses its own display back must not have that ambiguity.
  */
-export function NumberField({
-  value,
-  onCommit,
-  onValueChange,
-  digits,
-  min,
-  max,
-  nullable = false,
-  unit,
-  unitPlacement = "suffix",
-  locale: localeProp,
-  label,
-  invalid,
-  error,
-  id,
-  "aria-describedby": ariaDescribedBy,
-  "aria-invalid": ariaInvalid,
-  "aria-required": ariaRequired,
-  ...rest
-}: NumberFieldProps) {
+export function NumberField(props: NumberFieldProps) {
+  const {
+    value,
+    onCommit,
+    onValueChange,
+    digits,
+    min,
+    max,
+    nullable = false,
+    unit,
+    unitPlacement = "suffix",
+    locale: localeProp,
+    label,
+    invalid,
+    error,
+    id,
+    "aria-describedby": ariaDescribedBy,
+    "aria-invalid": ariaInvalid,
+    "aria-required": ariaRequired,
+    ...rest
+  } = props;
   const locale = useKitLocale(localeProp);
   const mark = decimalMark(locale);
   const localize = (text: string) => (mark === "," ? text.replace(/\./g, ",") : text);
@@ -292,15 +293,20 @@ export function NumberField({
       invalid={invalid || hasError || ariaInvalid === true || ariaInvalid === "true"}
     />
   );
-  // Same shape as Input's FieldGroup: no wrapper at all without a message, so adding
-  // `error` support changed nothing about the DOM a flex row lays out.
-  if (!hasError) return field;
+  // Input's FieldGroup, restated: no wrapper for a field that never takes `error`, so
+  // the prop changed nothing about the DOM a flex row lays out — and a STEADY one for a
+  // field that does, message or not. Wrapping only while a message showed swapped the
+  // element above the <input>, which remounted it: focus, caret and the half-typed
+  // draft's keystrokes were lost the moment the message came or went.
+  if (!hasError && !("error" in props)) return field;
   return (
     <div>
       {field}
-      <p id={errorId} className={FIELD_ERROR_CLASS}>
-        {error}
-      </p>
+      {hasError && (
+        <p id={errorId} className={FIELD_ERROR_CLASS}>
+          {error}
+        </p>
+      )}
     </div>
   );
 }

package/src/components/passkeys-setting.tsx

@@ -42,6 +42,32 @@ export interface PasskeysSettingProps<Id extends PasskeyId = PasskeyId> extends
    * the user cancelling the OS prompt) keeps what was typed.
    */
   onAdd: (name: string) => void | Promise<unknown>;
+  /**
+   * A step the app runs BEFORE `onAdd` (0.18.0) — re-asking for the current password,
+   * a policy notice, anything that may stop the add. Called with the same trimmed name;
+   * resolve `true` to go on to `onAdd`, `false` to stop quietly (nothing is said, the
+   * typed name stays). A rejection, or a throw, stops the same way: the app reports
+   * its own errors. While it runs the add button is disabled and busy, so a second
+   * click cannot start a second check.
+   *
+   * Kurvenschmiede asked for the password in its own dialog by handing `onAdd` a
+   * promise it kept open across that dialog (passkeys-card.tsx) — which still works.
+   * This is the documented place for it: open the dialog here, resolve with whether it
+   * was confirmed, and keep what it produced (the server's registration options) for
+   * `onAdd` in a ref. The ceremony then starts from the dialog's click rather than the
+   * card's, which is the user activation `navigator.credentials.create` wants.
+   *
+   * Left out, `onAdd` is called synchronously in the click, exactly as before.
+   */
+  beforeAdd?: (name: string) => boolean | Promise<boolean>;
+  /**
+   * What a passkey does to the password, which picks the line under the title (0.18.0).
+   * `"instead"` (default): it replaces it — `labels.description`, kastlan's promise.
+   * `"alongside"`: the password stays and the passkey is a second way in —
+   * `labels.descriptionAlongside`. Kurvenschmiede overrode `description` for exactly
+   * this; an app that sets `mode` needs no override.
+   */
+  mode?: "instead" | "alongside";
   /** The ceremony is running. The add button says so and does not start a second one. */
   adding?: boolean;
   /** Offer "Rename" on each row. Return a promise to leave edit mode only on success. */
@@ -92,6 +118,8 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
   passkeys,
   loading,
   onAdd,
+  beforeAdd,
+  mode = "instead",
   adding = false,
   onRename,
   onDelete,
@@ -108,6 +136,10 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
   const labels = useAccountSettingsLabels("passkeys", labelsProp);
   const locale = useKitLocale(localeProp);
   const [name, setName] = useState("");
+  // `beforeAdd` is running. State for the button, and a ref for the guard: two clicks
+  // in one frame both read the state from before either set it.
+  const [checking, setChecking] = useState(false);
+  const checkingRef = useRef(false);
 
   const date = (value: PasskeyItem["createdAt"]): string | null => {
     if (value === null || value === undefined || value === "") return null;
@@ -117,13 +149,40 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
   };
 
   const add = () => {
-    if (adding) return;
+    if (adding || checkingRef.current) return;
     const typed = name;
-    Promise.resolve(onAdd(typed.trim()))
-      // Clear only what was sent: the field stays editable while the OS prompt is up.
-      .then(() => setName((current) => (current === typed ? "" : current)))
-      .catch(() => {});
+    const value = typed.trim();
+    const send = () =>
+      Promise.resolve(onAdd(value))
+        // Clear only what was sent: the field stays editable while the OS prompt is up.
+        .then(() => setName((current) => (current === typed ? "" : current)));
+    if (!beforeAdd) {
+      send().catch(() => {});
+      return;
+    }
+    const done = () => {
+      checkingRef.current = false;
+      setChecking(false);
+    };
+    checkingRef.current = true;
+    setChecking(true);
+    let gate: Promise<boolean>;
+    // Called in the click, not a microtask later, so a step that itself needs the
+    // user's activation (a popup, the clipboard) still has it; a throw is a "no".
+    try {
+      gate = Promise.resolve(beforeAdd(value));
+    } catch (error) {
+      gate = Promise.reject(error);
+    }
+    gate
+      .then((go) => {
+        done();
+        // Strictly `true`: an app whose step resolves `undefined` meant nothing.
+        if (go === true) return send();
+      })
+      .catch(done);
   };
+  const busy = adding || checking;
 
   const isLoading = loading || passkeys === undefined;
   const items = passkeys ?? [];
@@ -171,7 +230,7 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
               }}
             />
           )}
-          <Button onClick={add} disabled={adding} aria-busy={adding || undefined}>
+          <Button onClick={add} disabled={busy} aria-busy={busy || undefined}>
             <KeyRound className="size-4" aria-hidden />
             {adding ? labels.adding : labels.add}
           </Button>
@@ -186,7 +245,9 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
       <div>
         <div className="text-sm font-medium">{labels.title}</div>
         <div className="text-xs text-[var(--text-muted)]">
-          {labels.description}
+          {mode === "alongside"
+            ? labels.descriptionAlongside
+            : labels.description}
         </div>
       </div>
       {body}