@eifi1/ui-kit 0.16.1 → 0.18.0

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

@@ -1,4 +1,4 @@
-import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import type { CSSProperties, ReactNode, TdHTMLAttributes, ThHTMLAttributes } from "react";
 import { createPortal } from "react-dom";
 import {
@@ -101,6 +101,26 @@ export interface DataTableColumn<T> {
    *  width a resize pins stay the table's, and the class list goes before
    *  `headClassName` for the same reason as in {@link cellProps}. */
   headProps?: DataTableHeadProps;
+  /**
+   * This column's cell in the table's totals row — a `<tfoot>` on a wide screen, a
+   * labelled summary card under the list on a phone. kastlan's trial balance is why
+   * it exists: it hand-built a debit/credit/balance strip in a `div` UNDER the table,
+   * which lined up with no column, dropped out of the table's semantics, and stayed
+   * put when the user hid or resized the columns it was summing.
+   *
+   * `rows` is every row that passes the current filters (in the current sort order),
+   * NOT just the page on screen: a total that changes when the user pages is not a
+   * total, and the trial balance has to balance on page 1 as much as on page 7. The
+   * page is the second argument for the rare "subtotal of this page" footer.
+   *
+   * Under `serverPagination` the table only ever holds one page, so both arguments are
+   * that page — a server-side table computes its totals on the server and returns
+   * them here (`footer: () => fmt(response.totalDebit)`), ignoring the arguments.
+   *
+   * The cell takes the column's `className` (so a `text-end` amount column totals
+   * end-aligned), its resized width, and drops out with the column when it is hidden.
+   */
+  footer?: (rows: T[], page: T[]) => ReactNode;
 }
 
 /** A `data-*` attribute, typed so `{ "data-private": "" }` needs no cast. */
@@ -335,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
@@ -466,6 +504,26 @@ export interface DataTableProps<T> {
    * pages set a search box in a `div` above the card, outside the frame it filters).
    */
   toolbar?: ReactNode;
+  /**
+   * The totals row's name — "Total", "Summe", "Totals as of 30 June". It is the row's
+   * header: rendered as a `<th scope="row">` in the first visible column that has no
+   * `footer` of its own (falling back to the first visible column if every one has a
+   * value), so a screen reader reads "Total, Debit, 12 400.00" for the cell beside it.
+   * On a phone it heads the summary card, which is also named by it.
+   *
+   * There is no built-in default word: a new kit label key is a silent English string
+   * in every translated app (see `missingDataTableLabels`), and the caller has the
+   * word in its own catalogue already. Without it the row is unlabelled on screen —
+   * pass one.
+   */
+  footerLabel?: ReactNode;
+  /**
+   * Show the totals row. Default: shown when any column declares a `footer`. Set
+   * false to drop it without touching the column definitions (a "show totals"
+   * switch). The row is also left out while there are no rows to total — a row of
+   * zeroes under "No results" says nothing the empty state has not.
+   */
+  footer?: boolean;
 }
 
 /** One entry of {@link DataTableProps.rowActions}. */
@@ -590,6 +648,15 @@ function logicalAlign(className: string | undefined): string | undefined {
   );
 }
 
+/**
+ * A totals-row cell: pinned to the scroller's bottom edge, on the header's surface.
+ * The rule above it is an inset shadow rather than a `border-t`: the table collapses
+ * its borders, and a collapsed border belongs to the TABLE, not the cell, so it stays
+ * behind at the bottom of the rows while the sticky cell rides over them.
+ */
+const FOOTER_CELL =
+  "sticky bottom-0 z-10 bg-[var(--bg-surface-2)] shadow-[inset_0_2px_0_var(--border-strong)]";
+
 /** Whether a column is end-aligned — the header then puts its filter button first. */
 const END_ALIGN = /(^|\s)text-end(?=\s|$)/;
 
@@ -786,6 +853,7 @@ export function DataTable<T>({
   locale: localeProp,
   storageKeyPrefix = DEFAULT_PERSIST_PREFIX,
   mobileExpandAsDialog = false,
+  mobileDialogBackCloses = true,
   mobileGroupBy,
   mobileGroupLabel,
   mobileCard,
@@ -801,6 +869,8 @@ export function DataTable<T>({
   className,
   rowActions,
   toolbar,
+  footerLabel,
+  footer: footerProp,
 }: DataTableProps<T>) {
   const compact = density === "compact";
   const minimal = chrome === "minimal";
@@ -1192,7 +1262,7 @@ export function DataTable<T>({
   // `setWidths` is called once, when the drag ends.
   const resizing = useRef<Resize | null>(null);
 
-  /** Every cell in one column, header first. `data-col` rather than a cell index:
+  /** Every cell in one column, header first, totals row included. `data-col` rather than a cell index:
    *  an expanded row holds a single `colSpan` cell, so the nth `<td>` of a row is
    *  not reliably the nth column. */
   const columnCells = (key: string): HTMLElement[] => {
@@ -1202,7 +1272,7 @@ export function DataTable<T>({
     if (!table) return [th];
     return [
       th,
-      ...Array.from(table.querySelectorAll<HTMLElement>("tbody [data-col]")).filter(
+      ...Array.from(table.querySelectorAll<HTMLElement>("tbody [data-col], tfoot [data-col]")).filter(
         (el) => el.dataset.col === key,
       ),
     ];
@@ -1309,6 +1379,21 @@ export function DataTable<T>({
   const totalCount = columns.length;
   // Spans the full row width including the optional leading selection column.
   const totalColSpan = visibleCount + (selection ? 1 : 0);
+
+  // ---- Totals row ----
+  // `sorted`, not `slice`: the totals are of everything the filters let through, so
+  // paging does not move them — see `DataTableColumn.footer`. In server mode `sorted`
+  // IS the page (the table holds nothing else), which the prop's note spells out.
+  const hasFooterColumns = columns.some((c) => c.footer);
+  const showFooter = footerProp !== false && hasFooterColumns && sorted.length > 0;
+  // The row header sits in the first visible column that has nothing of its own to
+  // show — so hiding the "Account" column moves "Total" into "Name" rather than
+  // dropping it — and on the first visible column when every one carries a value.
+  const footerLabelCol = showFooter
+    ? (visibleColumns.find((c) => !c.footer && c.key !== ROW_ACTIONS_KEY) ?? visibleColumns[0])
+    : undefined;
+  const footerValue = (col: DataTableColumn<T>) => col.footer?.(sorted, slice);
+  const footerHeadingId = useId();
   // The actions column is the table's own, not one the user can hide: out of the count.
   const columnsCountLabel = rowActions
     ? labels.columnsCount(visibleCount - 1, totalCount - 1)
@@ -1725,6 +1810,49 @@ export function DataTable<T>({
             </li>
           )}
         </ul>
+        {/* The phone's totals: a summary card after the list rather than one more
+            `<li>` in it. The list reveals rows in chunks as it is scrolled, so a last
+            item would sit mid-list until the end was reached; outside it, and under
+            `fillHeight` outside the scroller too, the totals stay in view the way the
+            sticky `<tfoot>` keeps them in view on a wide screen. Named by
+            `footerLabel` so it is announced as what it is, not as a stray list of
+            numbers; `mobileHidden` columns stay hidden here as on the cards. */}
+        {showFooter && mobileColumns.some((c) => c.footer) && (
+          <section
+            data-table-footer=""
+            aria-labelledby={footerLabel != null ? footerHeadingId : undefined}
+            className={cn(
+              "border-t-2 border-[var(--border-strong)] bg-[var(--bg-surface-2)]",
+              compact ? "px-3 py-2" : "px-4 py-3",
+              isLoading && "opacity-60 transition-opacity",
+            )}
+          >
+            {footerLabel != null && (
+              <div id={footerHeadingId} className={cn("font-semibold", compact ? "mb-1 text-sm" : "mb-2")}>
+                {footerLabel}
+              </div>
+            )}
+            <dl
+              className={cn(
+                "grid grid-cols-[auto_1fr] gap-x-3",
+                compact ? "gap-y-0.5 text-xs" : "gap-y-1 text-sm",
+              )}
+            >
+              {mobileColumns
+                .filter((c) => c.footer)
+                .map((col) => (
+                  <Fragment key={col.key}>
+                    <dt className="self-center text-xs uppercase tracking-wide text-[var(--text-muted)]">
+                      {col.header}
+                    </dt>
+                    <dd className="min-w-0 self-center font-semibold text-[var(--text-primary)]">
+                      {footerValue(col)}
+                    </dd>
+                  </Fragment>
+                ))}
+            </dl>
+          </section>
+        )}
         {/* Client-side mobile lists scroll endlessly (sentinel above); only
             server-paginated tables keep the pager here. */}
         {isServer && (
@@ -1747,6 +1875,7 @@ export function DataTable<T>({
           onClose={closeDialog}
           closeLabel={labels.close}
           header={mobileDialogRow ? mobilePrimaryCol?.cell(mobileDialogRow) : null}
+          backCloses={mobileDialogBackCloses}
         >
           {mobileDialogContent}
         </FullBleedDialog>
@@ -2166,6 +2295,59 @@ export function DataTable<T>({
               </tr>
             )}
           </tbody>
+          {showFooter && (
+            // Sticky to the scroller's bottom edge for the same reason the header is
+            // sticky to its top: the body scrolls inside a bounded wrapper, and a
+            // total that scrolls away with the last row is a total nobody sees on a
+            // 25-row page. Each cell carries its own background and its own `sticky`,
+            // as the header's do — `position: sticky` on a `<tfoot>` is not reliable.
+            <tfoot
+              data-table-footer=""
+              className={cn(
+                "font-semibold text-[var(--text-primary)]",
+                isLoading && "opacity-60 transition-opacity",
+              )}
+            >
+              <tr>
+                {/* The selection column has nothing to total: an empty cell keeps the
+                    values under their own headers. */}
+                {selection && (
+                  <td
+                    className={cn(
+                      FOOTER_CELL,
+                      compact ? "w-8 px-2 py-1" : "w-10 px-3 py-2",
+                    )}
+                  />
+                )}
+                {visibleColumns.map((col) => {
+                  const width = widths[col.key];
+                  const pinned = width ? { width, minWidth: width, maxWidth: width } : undefined;
+                  const isLabel = col === footerLabelCol;
+                  const Cell = isLabel ? "th" : "td";
+                  return (
+                    <Cell
+                      key={col.key}
+                      data-col={col.key}
+                      scope={isLabel ? "row" : undefined}
+                      style={pinned}
+                      className={cn(
+                        FOOTER_CELL,
+                        "align-top",
+                        compact ? "px-2 py-1" : "px-3 py-2",
+                        width && "overflow-hidden text-ellipsis",
+                        // A `<th>` centres by default; the label reads from the start
+                        // like the cells above it, unless the column says otherwise.
+                        isLabel && "text-start",
+                        logicalAlign(col.className),
+                      )}
+                    >
+                      {col.footer ? footerValue(col) : isLabel ? footerLabel : null}
+                    </Cell>
+                  );
+                })}
+              </tr>
+            </tfoot>
+          )}
         </table>
       </div>
           {!unpaged && (

package/src/components/form-actions.tsx

@@ -3,6 +3,7 @@ import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
+import { useMediaQuery } from "../hooks/use-media-query";
 import { Button, Spinner, type ButtonProps, type ButtonVariant } from "./ui";
 
 /** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
@@ -29,6 +30,57 @@ export type FormActionsAlign = "start" | "center" | "end" | "between";
  */
 export type FormActionsPlacement = "inline" | "sticky" | "dialog";
 
+/**
+ * A placement per breakpoint, mobile first — `{ base: "sticky", md: "inline" }` is a
+ * Save row stuck to the bottom of a phone's long form and in the flow under the last
+ * field from 768px up, where the form fits. The breakpoints are Tailwind's (sm 640,
+ * 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. 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;
+  sm?: FormActionsPlacement;
+  md?: FormActionsPlacement;
+  lg?: FormActionsPlacement;
+  xl?: FormActionsPlacement;
+}
+
+const BREAKPOINTS = [
+  ["xl", "(min-width: 1280px)"],
+  ["lg", "(min-width: 1024px)"],
+  ["md", "(min-width: 768px)"],
+  ["sm", "(min-width: 640px)"],
+] as const;
+
+/** The placement in force: the widest breakpoint that matches AND names one, else
+ *  `base`. The queries are subscribed unconditionally (hooks cannot be skipped); a
+ *  plain string ignores them. Without `matchMedia` (SSR, tests) none match, so the row
+ *  renders its `base`, the phone's. The same resolution as BulkActionBar's variant. */
+function useResolvedPlacement(
+  placement: FormActionsPlacement | ResponsiveFormActionsPlacement,
+): FormActionsPlacement {
+  const matches = {
+    xl: useMediaQuery(BREAKPOINTS[0][1], false),
+    lg: useMediaQuery(BREAKPOINTS[1][1], false),
+    md: useMediaQuery(BREAKPOINTS[2][1], false),
+    sm: useMediaQuery(BREAKPOINTS[3][1], false),
+  };
+  if (typeof placement === "string") return placement;
+  for (const [key] of BREAKPOINTS) {
+    const p = placement[key];
+    if (matches[key] && p !== undefined) return p;
+  }
+  return placement.base;
+}
+
+/** A CSS length: a number is pixels. */
+function cssLength(value: string | number): string {
+  return typeof value === "number" ? `${value}px` : value;
+}
+
 /**
  * What a `sticky` row sticks to — see {@link FormActionsProps.stickyWithin}.
  *  - `viewport` (default): the page's (or AppShell pane's) bottom edge, lifted onto
@@ -45,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. */
@@ -106,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;
@@ -125,8 +189,21 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
   start?: ReactNode;
   /** Horizontal alignment. Default `end` (`between` with a `destructive` action). */
   align?: FormActionsAlign;
-  /** See {@link FormActionsPlacement}. Default `inline`. */
-  placement?: FormActionsPlacement;
+  /** See {@link FormActionsPlacement}, or one per breakpoint — see
+   *  {@link ResponsiveFormActionsPlacement}. Default `inline`. */
+  placement?: FormActionsPlacement | ResponsiveFormActionsPlacement;
+  /**
+   * While the row is `sticky`: pull it out over its container's inline padding by this
+   * much (a CSS length, a number in px) and give the same back as padding — so the
+   * rule above it and its surface run edge to edge, while the buttons stay on the
+   * content's line. Without it a sticky row in a padded card or pane is a strip inset
+   * 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. The margin
+   * is `calc(-1 * X)`; jsdom folds that to `calc(-X)`, so match it loosely in tests.
+   */
+  bleed?: string | number;
   /**
    * With `placement="sticky"`: what the row sticks to. Default `viewport`.
    *
@@ -186,12 +263,14 @@ export function FormActions({
   pending = false,
   submitDisabled = false,
   submitDisabledReason,
+  commit = false,
   submitVariant = "brand",
   destructive,
   start: startSlot,
   align,
-  placement = "inline",
+  placement: placementProp = "inline",
   stickyWithin = "viewport",
+  bleed,
   form,
   children,
   className,
@@ -199,6 +278,8 @@ export function FormActions({
   ...rest
 }: FormActionsProps) {
   const labels = useKitLabels("form", DEFAULT_FORM_ACTIONS_LABELS);
+  const placement = useResolvedPlacement(placementProp);
+  const bleedLength = bleed === undefined || bleed === "" ? undefined : cssLength(bleed);
   const hasDestructive = destructive !== undefined && destructive !== null && destructive !== false;
   const hasStart = startSlot !== undefined && startSlot !== null && startSlot !== false;
   const justify = align ?? (hasDestructive || hasStart ? "between" : "end");
@@ -210,6 +291,7 @@ export function FormActions({
       onClick={destructive.onClick}
       disabled={destructive.disabled}
       disabledReason={destructive.disabledReason}
+      commit={commit}
     >
       {destructive.label}
     </Button>
@@ -235,6 +317,10 @@ export function FormActions({
               // container the nav is not underneath: `--app-nav-h` is the document's,
               // and would hold the row that far above the container's own edge.
               bottom: stickyWithin === "container" ? 0 : "max(0px, calc(var(--app-nav-h, 0px) - 1px))",
+              ...(bleedLength !== undefined && {
+                marginInline: `calc(-1 * ${bleedLength})`,
+                paddingInline: bleedLength,
+              }),
               ...style,
             }
           : style
@@ -262,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 ? (