@eifi1/ui-kit 0.51.6 → 0.52.0

package/src/components/date-range-picker.tsx

@@ -1,12 +1,13 @@
-// The two-date range picker: presets beside the calendar, `commit="apply"` drafts, a
-// custom trigger. Moved out of date-picker.tsx as it was (MOD-9, refactor audit
+// The two-date range picker: presets beside the calendar, `apply` drafts, a custom
+// trigger. Moved out of date-picker.tsx as it was (MOD-9, refactor audit
 // 2026-10); date-picker still exports every public name here.
 import { useState } from "react";
 import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { useKitLocale, type DatePickerLabels } from "../i18n/kit-labels";
 import { Button } from "./button";
-import { FieldBox, useFieldMessages } from "./field-parts";
+import { FieldBox, LockedReason, useFieldMessages, useLockReason } from "./field-parts";
+import type { CommitScope } from "./write-lock";
 import { usePhoneLayout } from "../hooks/use-breakpoint";
 import {
   DateField,
@@ -40,19 +41,13 @@ export interface DateRangePickerPreset {
 }
 
 /**
- * When the picker hands its range to `onChange`.
+ * The 0.x values of DateRangePicker's `commit`, when it was the panel's mode:
+ * `"immediate"` is `apply` left out, `"apply"` is `apply`. See
+ * {@link DateRangePickerProps.apply}.
  *
- *  - `"immediate"` (the default, and all of 0.7): a preset click commits and closes,
- *    and each calendar click is reported as it happens — the half-made `(from, "")`
- *    included. The right shape for quick ranges on a filter, where one click is one
- *    answer.
- *  - `"apply"`: the panel works on a DRAFT. A preset ARMS the calendar instead of
- *    committing, days can then be nudged ("last 3 months, but end it last Friday"),
- *    and nothing reaches `onChange` until Apply — which stays disabled until both ends
- *    exist. Cancel, Escape and an outside click discard the draft, and every open
- *    starts again from the committed value. keksdose's report range asked for exactly
- *    this: each commit there re-runs a whole page of charts, so an intermediate state
- *    must never escape the panel.
+ * @deprecated 0.52 — DateRangePicker's `apply` (`commit="apply"` → `apply`, `"immediate"`
+ * → nothing); removed in 0.53. `commit` is the write lock's opt-in on every other kit
+ * control, and since 0.52 on this one too (refactor audit 2026-10-30, API-3).
  */
 export type DateRangeCommit = "immediate" | "apply";
 
@@ -65,8 +60,9 @@ export interface DateRangePickerProps extends DatePickerBaseProps {
   onChange: (from: string, to: string, presetId?: string) => void;
   /** Separator between the two formatted dates in the trigger (default " – "). */
   separator?: string;
-  /** Optional named ranges rendered as a start-side column (last month / YTD / …). */
-  presets?: DateRangePickerPreset[];
+  /** Optional named ranges rendered as a start-side column (last month / YTD / …).
+   *  `readonly` since 0.52 (API-7): the picker never changes the list. */
+  presets?: readonly DateRangePickerPreset[];
   /**
    * The active preset's `id`, controlled — e.g. straight from keksdose's `?preset=`.
    * `null` (or an id no preset has, such as `"custom"`) says "no preset": nothing in
@@ -77,8 +73,39 @@ export interface DateRangePickerProps extends DatePickerBaseProps {
    * itself; with no memory at all it falls back to the first preset whose dates match.
    */
   preset?: string | null;
-  /** See {@link DateRangeCommit}. Default `"immediate"`. */
-  commit?: DateRangeCommit;
+  /**
+   * When the picker hands its range to `onChange`.
+   *
+   *  - Left out (the default, and all of 0.7): a preset click commits and closes, and
+   *    each calendar click is reported as it happens — the half-made `(from, "")`
+   *    included. The right shape for quick ranges on a filter, where one click is one
+   *    answer.
+   *  - `apply`: the panel works on a DRAFT. A preset ARMS the calendar instead of
+   *    committing, days can then be nudged ("last 3 months, but end it last Friday"),
+   *    and nothing reaches `onChange` until Apply — which stays disabled until both ends
+   *    exist. Cancel, Escape and an outside click discard the draft, and every open
+   *    starts again from the committed value. keksdose's report range asked for exactly
+   *    this: each commit there re-runs a whole page of charts, so an intermediate state
+   *    must never escape the panel.
+   *
+   * `commit="apply"` until 0.52 (refactor audit 2026-10-30, API-3): `commit` is the write
+   * lock's prop on every other kit control. The old spelling still works for 0.52 and
+   * goes in 0.53 ({@link DateRangeCommit}); `apply` wins where both are given.
+   */
+  apply?: boolean;
+  /**
+   * This picker COMMITS — picking a range saves it (a report's period kept per user, a
+   * filter persisted as it moves). Under a locked {@link WriteLockProvider} it is locked
+   * the `disabledReason` way, with the lock's reason; a {@link CommitScope}, as on every
+   * kit control since 0.33, and on this one since 0.52 (API-3). A range inside a form with
+   * its own Save stays editable under the lock — leave this off there.
+   *
+   * The strings `"immediate"` and `"apply"` are the panel's mode, the 0.x meaning of this
+   * prop: deprecated, read as `apply` for one minor, removed in 0.53 — see
+   * {@link DateRangeCommit}. They cannot be taken for a scope, which is a boolean or an
+   * object.
+   */
+  commit?: CommitScope | DateRangeCommit;
   /**
    * Draw the trigger yourself. keksdose's report range field
    * (reports/report-range-field.tsx, "Why this is app-level") is why: its trigger
@@ -103,7 +130,7 @@ export interface DateRangePickerProps extends DatePickerBaseProps {
    */
   sheetBackCloses?: boolean;
   /**
-   * With `commit="apply"`: a line above the calendar saying what Apply would commit —
+   * With `apply`: a line above the calendar saying what Apply would commit —
    * keksdose's report range writes "Custom · 1 Mar 2026 – …" there
    * (report-range-field.tsx), the one place a preset armed and then nudged by a day is
    * seen to have become "Custom", and a half-made range to still lack its end. Called
@@ -112,7 +139,7 @@ export interface DateRangePickerProps extends DatePickerBaseProps {
    * `""` until the second click. The line is a polite live region, so a screen reader
    * hears the draft change as the calendar is used.
    *
-   * Ignored in `"immediate"` mode, where there is no draft: every click is the value.
+   * Ignored without `apply`, where there is no draft: every click is the value.
    */
   renderDraftSummary?: (draft: DateRangeDraftSummary) => ReactNode;
 }
@@ -218,8 +245,8 @@ function PresetColumn({
 }
 
 /**
- * The panel's body. A component of its own so `commit="apply"` can keep its draft in
- * state that is born when the panel opens: `Popover` unmounts its children on close,
+ * The panel's body. A component of its own so `apply` can keep its draft in state that
+ * is born when the panel opens: `Popover` unmounts its children on close,
  * so the draft is re-seeded from the committed value on every open, and an abandoned
  * half-selection cannot survive into the next one.
  */
@@ -229,7 +256,7 @@ function RangePanel({
   presets,
   activeId,
   controlled,
-  commit,
+  drafting,
   close,
   frame,
   sheet,
@@ -243,7 +270,8 @@ function RangePanel({
   presets: readonly DateRangePickerPreset[] | undefined;
   activeId: string | null | undefined;
   controlled: boolean;
-  commit: DateRangeCommit;
+  /** `apply`: the panel works on a draft. */
+  drafting: boolean;
   close: () => void;
   /** Where the body and the Apply row go — see `PanelFrame`. */
   frame: PanelFrame;
@@ -253,7 +281,6 @@ function RangePanel({
   labels: DatePickerLabels;
   renderDraftSummary?: DateRangePickerProps["renderDraftSummary"];
 }) {
-  const drafting = commit === "apply";
   const [draft, setDraft] = useState<RangeDraft>({
     from,
     to,
@@ -360,8 +387,8 @@ function RangePanel({
 }
 
 /** Two-date range picker: click a start then an end; closes once both are set.
- *  With `presets`, a column of named ranges is shown beside the calendar; with
- *  `commit="apply"` the panel drafts and commits on Apply (see {@link DateRangeCommit}). */
+ *  With `presets`, a column of named ranges is shown beside the calendar; with `apply`
+ *  the panel drafts and commits on Apply (see {@link DateRangePickerProps.apply}). */
 export function DateRangePicker(props: DateRangePickerProps) {
   const {
     from,
@@ -376,7 +403,8 @@ export function DateRangePicker(props: DateRangePickerProps) {
     separator = " – ",
     presets,
     preset,
-    commit = "immediate",
+    apply,
+    commit,
     renderTrigger,
     sheetBackCloses,
     renderDraftSummary,
@@ -386,10 +414,13 @@ export function DateRangePicker(props: DateRangePickerProps) {
     clearable,
     clearLabel,
     disabled,
+    disabledReason,
+    disabledReasonDisplay,
     invalid,
     hint,
     help,
     error,
+    className,
     // The trigger's (API-3).
     ref,
     ...rest
@@ -397,6 +428,11 @@ export function DateRangePicker(props: DateRangePickerProps) {
   const locale = useKitLocale(localeProp);
   const text = useDatePickerLabels(clearLabel, undefined, undefined);
   const render = useTriggerFormat("dateRangePicker", locale, formatOptions, formatValue);
+  // `commit` is two props until 0.53: a string is the deprecated mode, anything else
+  // the write lock's scope (API-3).
+  const drafting = apply ?? commit === "apply";
+  const lock = useLockReason(typeof commit === "string" ? undefined : commit, disabledReason);
+  const locked = lock.locked;
   const messages = useFieldMessages({
     hint,
     help,
@@ -405,6 +441,8 @@ export function DateRangePicker(props: DateRangePickerProps) {
     invalid,
     describedBy: rest["aria-describedby"],
     ariaInvalid: rest["aria-invalid"],
+    // A lock's reason between the caption and the error, as on Select.
+    reasonId: locked && lock.reasonId,
   });
   // The preset this picker committed itself, for a caller that does not control
   // `preset`. Cleared by a hand-picked range or a clear.
@@ -417,6 +455,7 @@ export function DateRangePicker(props: DateRangePickerProps) {
   const hasPresets = Boolean(presets && presets.length > 0);
   const sheet = usePhoneLayout();
   const commitRange = (f: string, t: string, presetId: string | undefined) => {
+    if (locked) return;
     setOwnPreset(presetId);
     // Two arguments when no preset is involved — exactly the 0.7 call, so a caller's
     // `toHaveBeenCalledWith(from, to)` and a variadic handler see no difference.
@@ -434,6 +473,9 @@ export function DateRangePicker(props: DateRangePickerProps) {
       clearLabel={text.clear}
       panelLabel={text.rangePanel}
       disabled={disabled}
+      locked={locked}
+      // Locked, the caller's classes are the reason's frame's (below).
+      className={locked ? undefined : className}
       invalid={messages.isInvalid}
       // Widen so the preset column sits beside the calendar (default otherwise).
       width={hasPresets ? "27.5rem" : undefined}
@@ -463,7 +505,7 @@ export function DateRangePicker(props: DateRangePickerProps) {
           presets={presets}
           activeId={activeId}
           controlled={controlled}
-          commit={commit}
+          drafting={drafting}
           close={close}
           frame={frame}
           sheet={sheet}
@@ -475,9 +517,18 @@ export function DateRangePicker(props: DateRangePickerProps) {
       )}
     </DateField>
   );
+  const box = withEndHint(field, label === undefined ? messages.labelHint : undefined);
   return (
     <FieldBox below={messages.below} reserve={"error" in props || "hint" in props}>
-      {withEndHint(field, label === undefined ? messages.labelHint : undefined)}
+      {locked ? (
+        // DatePicker's frame: the line under the field, or the Tooltip with a hidden copy
+        // for `aria-describedby`; the outermost box, so it takes the caller's classes.
+        <LockedReason lock={lock} display={disabledReasonDisplay} className={cn("block", className)}>
+          {box}
+        </LockedReason>
+      ) : (
+        box
+      )}
     </FieldBox>
   );
 }

package/src/components/dialog-frame.tsx

@@ -25,7 +25,8 @@ export { DEFAULT_DIALOG_FRAME_LABELS };
  * `PickerSheet` met first. Everything else, `size`, `draggable`, `fullBleed`,
  * `onKeyDown`, a `data-tour` anchor, still reaches the `Modal` — and since 0.35 `ref`
  * (round 0.35 R4): the panel, the `role="dialog"` element the frame's header, body and
- * actions sit in.
+ * actions sit in. `busy` too (DUP-3): it holds the frame's X and the `close` that
+ * `actions` and `headerActions` receive, since both are the `Modal`'s own close.
  */
 export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "children" | "title"> {
   /** The heading, and therefore the dialog's accessible name (`aria-labelledby`). */

package/src/components/entity-combobox.tsx

@@ -12,7 +12,7 @@ import {
   type ComboClearValue,
   type ComboOption,
 } from "./combobox-core";
-import { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
 import {
   assignRef,
   EndHintRow,
@@ -248,11 +248,14 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
   const chosen: V | null = value == null || value === clearValue ? null : (value as V);
   const selectedOption = chosen == null ? null : resolve(chosen);
   const q = query.trim();
+  // The create row's "is this name already listed" folds as the list's match does (DUP-5).
+  const locale = useKitLocale();
   const showCreate = offersCreate(
     onCreate,
     q,
     results.map((o) => o.label),
     createEmptyLabel,
+    locale,
   );
   const showClear = Boolean(clearable && chosen != null && !inert);
   /** What the closed control is showing — the second half of its accessible name. */

package/src/components/error-boundary.tsx

@@ -1,4 +1,4 @@
-import { Component } from "react";
+import { Component, useEffect } from "react";
 import type { ErrorInfo, ReactNode } from "react";
 import { AlertTriangle, RefreshCw, WifiOff } from "lucide-react";
 import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
@@ -7,6 +7,7 @@ import { EmptyState } from "./empty-state";
 import { CopyButton } from "./copy-button";
 import { Disclosure } from "./disclosure";
 import { documentNavigation } from "../lib/document-navigation";
+import { useAnnounce } from "../hooks/use-announce";
 import { DEFAULT_ERROR_BOUNDARY_LABELS } from "./error-boundary-labels";
 
 /** The words of the default fallback. */
@@ -605,6 +606,17 @@ function ErrorFallback({
   const reportText = report ? formatCrashReport(report) : null;
   const errorLine = details.message ? `${details.name}: ${details.message}` : details.name;
 
+  // The title and the hint, said once through an assertive region of their own (0.52,
+  // refactor audit 2026-10-30, DSP-17). `role="alert"` on the whole box put the actions
+  // in it, so each later insertion was read out as news: "Copy error report" and
+  // "Details" on `componentDidCatch`'s second render, "Reported as …", and on opening
+  // Details both stacks of the crash report. EmptyState has no wrapper for title and
+  // hint alone, and a region mounted with its message is often missed anyway.
+  const alert = useAnnounce({ politeness: "assertive" });
+  const { announce } = alert;
+  const spoken = `${title}. ${hint}`;
+  useEffect(() => announce(spoken), [announce, spoken]);
+
   const reloadButton = (
     <Button key="reload" variant={mode === "error" ? "secondary" : "default"} onClick={reloadPage}>
       {text.reload}
@@ -619,43 +631,45 @@ function ErrorFallback({
   );
 
   return (
-    <EmptyState
-      role="alert"
-      tone={mode === "error" ? "danger" : undefined}
-      headingAs={headingAs}
-      className={className}
-      icon={<Icon />}
-      title={title}
-      hint={hint}
-      action={
-        <>
-          {showMessage && mode === "error" && (
-            // A quotation, not prose: left-aligned and monospaced, so it reads as the
-            // program's words and can be read out or screenshotted verbatim.
-            <p
-              data-error-message=""
-              className="-mt-1 mb-1 basis-full whitespace-pre-wrap break-words rounded-md border border-danger-strong bg-danger-soft px-3 py-2 text-start font-mono text-xs text-primary"
-            >
-              {errorLine}
-            </p>
-          )}
-          {filing === "filed" && (
-            <p className="-mt-1 mb-1 basis-full text-xs">{reference ? text.reportedAs(reference) : text.reported}</p>
-          )}
-          {mode === "error" ? [retryButton, reloadButton] : [reloadButton, retryButton]}
-          {copyReport && reportText !== null && filing !== "filed" && (
-            <CopyButton variant="label" buttonVariant="ghost" label={text.copyReport} text={reportText} />
-          )}
-          {actions}
-          {showDetails && reportText !== null && (
-            <Disclosure variant="bare" title={text.details} className="basis-full text-start">
-              <pre className="max-h-60 overflow-auto whitespace-pre-wrap break-words text-xs text-secondary">
-                {reportText}
-              </pre>
-            </Disclosure>
-          )}
-        </>
-      }
-    />
+    <>
+      <span {...alert.regionProps} />
+      <EmptyState
+        tone={mode === "error" ? "danger" : undefined}
+        headingAs={headingAs}
+        className={className}
+        icon={<Icon />}
+        title={title}
+        hint={hint}
+        action={
+          <>
+            {showMessage && mode === "error" && (
+              // A quotation, not prose: left-aligned and monospaced, so it reads as the
+              // program's words and can be read out or screenshotted verbatim.
+              <p
+                data-error-message=""
+                className="-mt-1 mb-1 basis-full whitespace-pre-wrap break-words rounded-md border border-danger-strong bg-danger-soft px-3 py-2 text-start font-mono text-xs text-primary"
+              >
+                {errorLine}
+              </p>
+            )}
+            {filing === "filed" && (
+              <p className="-mt-1 mb-1 basis-full text-xs">{reference ? text.reportedAs(reference) : text.reported}</p>
+            )}
+            {mode === "error" ? [retryButton, reloadButton] : [reloadButton, retryButton]}
+            {copyReport && reportText !== null && filing !== "filed" && (
+              <CopyButton variant="label" buttonVariant="ghost" label={text.copyReport} text={reportText} />
+            )}
+            {actions}
+            {showDetails && reportText !== null && (
+              <Disclosure variant="bare" title={text.details} className="basis-full text-start">
+                <pre className="max-h-60 overflow-auto whitespace-pre-wrap break-words text-xs text-secondary">
+                  {reportText}
+                </pre>
+              </Disclosure>
+            )}
+          </>
+        }
+      />
+    </>
   );
 }

package/src/components/field-base-labels.ts

@@ -0,0 +1,20 @@
+// The English words of ./field-base, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./field-base re-exports them.
+//
+// Until 0.52 they shared ui-labels.ts with the tabs' words, named after the ui.tsx that
+// 0.34 split up (MOD-7, refactor audit 2026-10-30): one labels module per component now,
+// as every other `*-labels.ts` is.
+
+import type { CharacterCountLabels, PasswordRevealLabels } from "./field-base";
+
+export const DEFAULT_PASSWORD_REVEAL_LABELS: PasswordRevealLabels = {
+  show: "Show password",
+  hide: "Hide password",
+};
+
+export const DEFAULT_CHARACTER_COUNT_LABELS: CharacterCountLabels = {
+  count: (used, max) => `${used} of ${max} characters`,
+  remaining: (left) => (left === 1 ? "1 character left" : `${left} characters left`),
+  limitReached: "Character limit reached",
+};

package/src/components/field-base.tsx

@@ -11,7 +11,7 @@ import {
   STATIC_LABEL_TYPE,
   type FieldHintParts,
 } from "./field-parts";
-import { DEFAULT_CHARACTER_COUNT_LABELS, DEFAULT_PASSWORD_REVEAL_LABELS } from "./ui-labels";
+import { DEFAULT_CHARACTER_COUNT_LABELS, DEFAULT_PASSWORD_REVEAL_LABELS } from "./field-base-labels";
 
 /**
  * The field base: what Input, Select and Textarea — and every kit field built on the same
@@ -20,7 +20,8 @@ import { DEFAULT_CHARACTER_COUNT_LABELS, DEFAULT_PASSWORD_REVEAL_LABELS } from "
  * reveal and the character counter. The message under a wrong field is field-parts'
  * `useFieldError`, every field's.
  *
- * Public through ./ui by name. `FieldGroup`, the counter and the placeholder helpers are
+ * Public through the barrel (src/index.ts) by name. `FieldGroup`, the counter and the
+ * placeholder helpers are
  * the three fields' shared parts (`@internal`), as are the Select's own classes and its
  * `SelectWidthFloor` (0.51).
  */
@@ -47,7 +48,12 @@ export const FIELD_BASE =
   // doubles the line inward — FIELD_INVALID's border-plus-ring (live #295), and the
   // DatePicker stepper's fix (0.34) — so every side keeps one fully covered device
   // pixel. Inset: nothing outside the field moves or is covered.
-  "focus:ring-1 focus:ring-inset focus:ring-brand " +
+  //
+  // Under More contrast the ring is 2px, so the line is 3px — what `--focus-ring-width`
+  // gives every `FOCUS_RING` there, and what `appearance.contrastHelp` promises ("thickens
+  // focus frames"); before 0.52 a text field kept its 2px (refactor audit 2026-10-30,
+  // DOC-2). Still inset, so nothing moves.
+  "focus:ring-1 contrast:focus:ring-2 focus:ring-inset focus:ring-brand " +
   // §10.1: at least 16 px on a touch screen, or iOS zooms the page on focus.
   FIELD_TOUCH_TEXT +
   " " +
@@ -106,9 +112,9 @@ export const FIELD_FLOATING_PAD = "pt-4 pb-1 large:py-2";
 //
 // A ring rather than `border-2`: a box-shadow adds no layout, so an invalid field
 // stays exactly the size of a valid one and nothing beside it moves when the value
-// arrives.
+// arrives. Under More contrast the ring is 2px, as FIELD_BASE's focus line (0.52, DOC-2).
 export const FIELD_INVALID =
-  "border-danger-strong ring-1 ring-danger-strong focus:border-[var(--danger)] focus:ring-[var(--danger)]";
+  "border-danger-strong ring-1 contrast:ring-2 ring-danger-strong focus:border-[var(--danger)] focus:ring-[var(--danger)]";
 
 export const FLOATING_INPUT_CLASS = cn(FIELD_BASE, FIELD_FLOATING_PAD, "peer placeholder:text-transparent");
 
@@ -504,7 +510,7 @@ export interface PasswordRevealLabels {
   hide: string;
 }
 
-// Defined in ./ui-labels, which holds no component code (0.34, KS U8).
+// Defined in ./field-base-labels, which holds no component code (0.34, KS U8).
 export { DEFAULT_PASSWORD_REVEAL_LABELS };
 
 /**
@@ -523,7 +529,7 @@ export interface CharacterCountLabels {
   limitReached: string;
 }
 
-// Defined in ./ui-labels, which holds no component code (0.34, KS U8).
+// Defined in ./field-base-labels, which holds no component code (0.34, KS U8).
 export { DEFAULT_CHARACTER_COUNT_LABELS };
 
 /** The length the browser's own `maxLength` counts — UTF-16 code units — so the counter

package/src/components/field-sync-labels.ts

@@ -4,6 +4,7 @@
 
 import type { FieldSyncLabels } from "./field-sync";
 
+/** @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53. */
 export const DEFAULT_FIELD_SYNC_LABELS: FieldSyncLabels = {
   synced: "Saved",
   edited: "Unsaved changes",

package/src/components/field-sync.tsx

@@ -23,9 +23,17 @@ import { DEFAULT_FIELD_SYNC_LABELS } from "./field-sync-labels";
  * because the state is useful without the dot — a form can disable its submit
  * button while any field is `pending`, and a router can block navigation while
  * any field is `edited`.
+ *
+ * Deprecated in 0.52 as a whole, removed in 0.53 (decision 4 of the refactor audit
+ * 2026-10-30, MOD-5): no app renders it or calls the hook — 483 lines and a namespace in
+ * seven catalogues that only this package's tests and showcase read. An app that wants
+ * it keeps a copy of this file.
+ *
+ * @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53.
  */
 export type FieldSyncState = "synced" | "edited" | "pending" | "error";
 
+/** @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53. */
 export interface FieldSyncLabels {
   synced: string;
   edited: string;
@@ -38,6 +46,7 @@ export interface FieldSyncLabels {
 // Defined in ./field-sync-labels, which holds no component code (0.34, KS U8).
 export { DEFAULT_FIELD_SYNC_LABELS };
 
+/** @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53. */
 export interface UseFieldSyncOptions<T> {
   /** What the database currently holds. Changing it re-seeds a CLEAN field. */
   value: T;
@@ -57,6 +66,7 @@ export interface UseFieldSyncOptions<T> {
   onError?: (error: Error) => void;
 }
 
+/** @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53. */
 export interface UseFieldSyncReturn<T> {
   /** The draft — bind this to the input, not the `value` option. */
   value: T;
@@ -101,6 +111,8 @@ function toError(cause: unknown): Error {
  *      may be gone — a row scrolled out of a virtualised table, a closed dialog.
  *   4. **`onSave` is read through a ref**, so an inline arrow — which every call
  *      site will pass — does not restart the debounce on every render.
+ *
+ * @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53.
  */
 export function useFieldSync<T>({
   value,
@@ -240,6 +252,7 @@ const STATE_STYLE: Record<FieldSyncState, { color: string; Icon: typeof Check }>
   error: { color: "var(--status-error)", Icon: AlertCircle },
 };
 
+/** @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53. */
 export interface FieldSyncIndicatorProps {
   state: FieldSyncState;
   /** The failure. Its message becomes the tooltip when `state === "error"`. */
@@ -269,6 +282,8 @@ export interface FieldSyncIndicatorProps {
  * The state is also announced: the wrapper is a polite live region, so a screen
  * reader hears "Saving…" then "Saved" without the user going looking. `error` is
  * assertive instead — a failed write is worth interrupting for.
+ *
+ * @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53.
  */
 export function FieldSyncIndicator({
   state,
@@ -340,6 +355,8 @@ export function FieldSyncIndicator({
  * colour does not.
  *
  * Every class is a literal so Tailwind's scanner can see it.
+ *
+ * @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53.
  */
 export const FIELD_SYNC_FRAME: Record<FieldSyncState, string> = {
   synced:
@@ -352,9 +369,12 @@ export const FIELD_SYNC_FRAME: Record<FieldSyncState, string> = {
     "[&_:is(input,select,textarea)]:border-[var(--status-error)] [&_:is(input,select,textarea)]:ring-1 [&_:is(input,select,textarea)]:ring-[var(--status-error)] [&_:is(input,select,textarea):focus]:border-[var(--status-error)] [&_:is(input,select,textarea):focus]:ring-[var(--status-error)]",
 };
 
-/** How long the green "saved" frame and check stay after a save lands, in ms. */
+/** How long the green "saved" frame and check stay after a save lands, in ms.
+ *
+ * @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53. */
 export const FIELD_SYNC_SAVED_MS = 1500;
 
+/** @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53. */
 export interface FieldSyncRowProps<T> extends Omit<FieldSyncIndicatorProps, "state" | "error" | "showLabel"> {
   sync: UseFieldSyncReturn<T>;
   children: ReactNode;
@@ -386,6 +406,8 @@ export interface FieldSyncRowProps<T> extends Omit<FieldSyncIndicatorProps, "sta
  * always in the DOM as a live region — polite for the ordinary states, assertive for
  * a failure. The input gets end padding for the icon whether or not one is showing,
  * so the text never reflows when the state changes.
+ *
+ * @deprecated 0.52 — none: no app uses the FieldSync family (MOD-5); removed in 0.53.
  */
 export function FieldSyncRow<T>({
   sync,

package/src/components/form-actions.tsx

@@ -5,7 +5,9 @@ import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
 import { useBreakpoint, usePhoneLayout } from "../hooks/use-breakpoint";
 import { useLargeText } from "../hooks/use-large-text";
-import { isApplePlatform } from "../hooks/use-hotkey";
+import { isApplePlatform, matchesHotkey, type ParsedHotkey } from "../hooks/use-hotkey";
+import { isComposing } from "../lib/ime";
+import { hasContent } from "../lib/presence";
 import { Button, type ButtonProps } from "./button";
 import { Spinner } from "./spinner";
 import type { ButtonSize, ButtonVariant } from "./button-look";
@@ -337,6 +339,17 @@ function shortcutScope(row: HTMLElement | null, formId: string | undefined): Ele
   return row.closest("form") ?? row.closest('[role="dialog"]') ?? row.parentElement;
 }
 
+/**
+ * What {@link FormActionsProps.submitShortcut} answers, on every platform: Ctrl+Enter and
+ * Cmd+Enter with nothing else held, read by `matchesHotkey` as every kit shortcut is
+ * (refactor audit 2026-10-30, DUP-12). Literals, not `parseHotkey` calls: no module-scope
+ * call for a bundler to keep.
+ */
+const SUBMIT_CHORDS: readonly ParsedHotkey[] = [
+  { ctrl: true, meta: false, shift: false, alt: false, key: "Enter" },
+  { ctrl: false, meta: true, shift: false, alt: false, key: "Enter" },
+];
+
 function isDestructiveData(value: unknown): value is FormActionsDestructive {
   return typeof value === "object" && value !== null && !isValidElement(value) && "onClick" in value;
 }
@@ -429,8 +442,9 @@ export function FormActions({
   useEffect(() => {
     if (submitShortcut !== "mod-enter") return;
     const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key !== "Enter" || !(e.ctrlKey || e.metaKey) || e.shiftKey || e.altKey) return;
-      if (e.repeat || e.isComposing || e.defaultPrevented || !canSaveRef.current) return;
+      if (!SUBMIT_CHORDS.some((chord) => matchesHotkey(e, chord))) return;
+      // `isComposing` is lib/ime's: Safari's composition-ending Enter (keyCode 229) too.
+      if (e.repeat || isComposing(e) || e.defaultPrevented || !canSaveRef.current) return;
       const scope = shortcutScope(rootRef.current, form);
       if (!scope || !(e.target instanceof Node) || !scope.contains(e.target)) return;
       e.preventDefault();
@@ -442,8 +456,9 @@ export function FormActions({
   const apple = submitShortcut ? isApplePlatform() : false;
   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;
+  // `hasContent` (DUP-14): an empty string is no slot either, not an empty `me-auto` box.
+  const hasDestructive = isDestructiveData(destructive) || hasContent(destructive);
+  const hasStart = hasContent(startSlot);
   const justify = align ?? (hasDestructive || hasStart ? "between" : "end");
   const destructiveNode = !hasDestructive ? null : isDestructiveData(destructive) ? (
     <Button