@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/components/file-dropzone.tsx

@@ -15,6 +15,7 @@ import {
 import type { FilePickHandler, FilePickerLabels, FileRejection } from "./file-button";
 import { useDragTarget } from "../hooks/use-file-drop";
 import { toast } from "./toast";
+import { useCommitReason } from "./write-lock";
 
 /**
  * Where a refused file's message goes.
@@ -35,6 +36,11 @@ export interface FileDropzoneState {
   dragOver: boolean;
   disabled: boolean;
   busy: boolean;
+  /** 0.22: locked with a reason (`disabledReason`, or `commit` under a locked
+   *  {@link WriteLockProvider}) — takes no files, like `disabled`. */
+  locked: boolean;
+  /** The reason while `locked`, for a custom body to show; `undefined` otherwise. */
+  disabledReason: ReactNode | undefined;
   /** What is chosen: `files` in multiple mode, `[file]` or `[]` in single mode. */
   files: readonly File[];
   /** The inline refusal, when `rejectionFeedback="inline"` has one to show. */
@@ -139,6 +145,22 @@ export interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">,
    * text. The other half of why keksdose's invoice zone was hand-rolled.
    */
   busy?: boolean;
+  /**
+   * Why the zone is not taking files — the write lock's sentence, a quota, a closed
+   * period (keksdose K3). Takes no drop, no picker and no removal, like `disabled`, and
+   * SAYS so: the Browse button (and every remove button) stays focusable,
+   * `aria-disabled`, with the reason in the kit Tooltip and its description, the zone's
+   * group is described by it, and the default body shows it where the hint was. Not
+   * dimmed: what is chosen stays readable. Wins over `disabled`'s silent look.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * This zone COMMITS — an upload that starts on drop. Under a locked
+   * {@link WriteLockProvider} it takes the `disabledReason` path with the lock's
+   * reason (which wins over one of its own). No provider, or an unlocked one: no
+   * effect. A zone that only stages a file for a form saved later is not a commit.
+   */
+  commit?: boolean;
   /**
    * Replace the zone's body — the icon, the text and the chosen-file list — with your
    * own, given the zone's state: keksdose's spinner-plus-"uploading", its multi-shot
@@ -182,6 +204,8 @@ export function FileDropzone({
   hint: hintProp,
   disabled,
   busy,
+  disabledReason: ownDisabledReason,
+  commit,
   renderBody,
   className,
   "aria-label": ariaLabel,
@@ -189,7 +213,12 @@ export function FileDropzone({
   ...rest
 }: FileDropzoneProps) {
   const [error, setError] = useState<string | null>(null);
-  const inert = Boolean(disabled || busy);
+  const disabledReason = useCommitReason(commit, ownDisabledReason);
+  const locked = hasReason(disabledReason);
+  // Locked counts as inert for every file path (drop, click, Browse, remove); only the
+  // LOOK and the native `disabled` keep it apart, so its controls stay focusable.
+  const inert = Boolean(disabled || busy) || locked;
+  const reasonId = useId();
   // State rather than a ref: `open` is handed to `renderBody` during render, and a
   // function that reads a ref there is exactly what the refs rule cannot prove safe.
   const [fileInput, setFileInput] = useState<HTMLInputElement | null>(null);
@@ -278,7 +307,16 @@ export function FileDropzone({
 
   const chosen: readonly File[] = multiple ? (files ?? []) : file ? [file] : [];
   const showError = feedback === "inline" && error !== null;
-  const describedBy = cn(describedByProp, showError && errorId) || undefined;
+  const describedBy = cn(describedByProp, showError && errorId, locked && reasonId) || undefined;
+  // The controls inside: natively disabled while disabled or busy; locked, they take
+  // the reason instead and stay reachable (Button's `disabledReason` path).
+  const controlDisabled = Boolean(disabled || busy);
+  const controlReason = locked ? disabledReason : undefined;
+  const reasonLine = locked && (
+    <div data-slot="file-dropzone-reason" className="text-xs text-[var(--text-muted)]">
+      {disabledReason}
+    </div>
+  );
 
   return (
     <>
@@ -311,7 +349,7 @@ export function FileDropzone({
         // reached through the description instead, and spoken when it appears.
         aria-describedby={describedBy}
         data-invalid={showError || undefined}
-        aria-disabled={disabled || undefined}
+        aria-disabled={disabled || locked || undefined}
         aria-busy={busy || undefined}
         data-drag-over={dragOver || undefined}
         className={cn(
@@ -336,7 +374,9 @@ export function FileDropzone({
             ? "cursor-not-allowed border-[var(--border)] opacity-60"
             : busy
               ? "cursor-progress border-[var(--border)]"
-              : dragOver
+              : locked
+                ? "cursor-not-allowed border-[var(--border)]"
+                : dragOver
                 ? "cursor-pointer border-[var(--border-strong)] bg-[var(--bg-active)]"
                 : showError
                   ? "cursor-pointer border-[var(--danger-border-strong)]"
@@ -349,6 +389,8 @@ export function FileDropzone({
             dragOver,
             disabled: Boolean(disabled),
             busy: Boolean(busy),
+            locked,
+            disabledReason: locked ? disabledReason : undefined,
             files: chosen,
             error: showError ? error : null,
             open,
@@ -365,34 +407,38 @@ export function FileDropzone({
           <>
             <Upload aria-hidden className="size-5 text-[var(--text-muted)]" />
             {multiple && chosen.length > 0 ? (
-              <ul className="flex w-full max-w-sm flex-col gap-1 text-start">
-                {chosen.map((f, i) => (
-                  <li
-                    // Name + size + position: two files may share a name, and the index
-                    // alone would re-key every row below a removal.
-                    key={`${f.name}-${f.size}-${i}`}
-                    className="flex items-center gap-2 text-sm text-[var(--text-secondary)]"
-                  >
-                    <span className="min-w-0 flex-1 truncate font-medium">{f.name}</span>
-                    <span className="shrink-0 text-xs text-[var(--text-muted)]">{fileText.size(f.size)}</span>
-                    {onRemove && (
-                      <IconButton
-                        type="button"
-                        size="sm"
-                        disabled={inert}
-                        aria-label={labels.remove(f.name)}
-                        onClick={(e) => {
-                          e.stopPropagation();
-                          onRemove(f, i);
-                          afterRemoval(labels.removed(f.name));
-                        }}
-                      >
-                        <X aria-hidden />
-                      </IconButton>
-                    )}
-                  </li>
-                ))}
-              </ul>
+              <>
+                <ul className="flex w-full max-w-sm flex-col gap-1 text-start">
+                  {chosen.map((f, i) => (
+                    <li
+                      // Name + size + position: two files may share a name, and the index
+                      // alone would re-key every row below a removal.
+                      key={`${f.name}-${f.size}-${i}`}
+                      className="flex items-center gap-2 text-sm text-[var(--text-secondary)]"
+                    >
+                      <span className="min-w-0 flex-1 truncate font-medium">{f.name}</span>
+                      <span className="shrink-0 text-xs text-[var(--text-muted)]">{fileText.size(f.size)}</span>
+                      {onRemove && (
+                        <IconButton
+                          type="button"
+                          size="sm"
+                          disabled={controlDisabled}
+                          disabledReason={controlReason}
+                          aria-label={labels.remove(f.name)}
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            onRemove(f, i);
+                            afterRemoval(labels.removed(f.name));
+                          }}
+                        >
+                          <X aria-hidden />
+                        </IconButton>
+                      )}
+                    </li>
+                  ))}
+                </ul>
+                {reasonLine}
+              </>
             ) : (
               <>
                 <div className="flex items-center gap-1 text-sm text-[var(--text-secondary)]">
@@ -403,7 +449,8 @@ export function FileDropzone({
                     <IconButton
                       type="button"
                       size="sm"
-                      disabled={inert}
+                      disabled={controlDisabled}
+                      disabledReason={controlReason}
                       aria-label={labels.remove(file.name)}
                       onClick={(e) => {
                         e.stopPropagation();
@@ -415,9 +462,16 @@ export function FileDropzone({
                     </IconButton>
                   )}
                 </div>
-                <div className="text-xs text-[var(--text-muted)]">
-                  {file && !multiple ? fileText.size(file.size) : hint}
-                </div>
+                {/* Locked, the reason takes the hint's place: what may be dropped is moot
+                    while nothing may. A chosen file keeps its size, the reason below. */}
+                {locked && !(file && !multiple) ? (
+                  reasonLine
+                ) : (
+                  <div className="text-xs text-[var(--text-muted)]">
+                    {file && !multiple ? fileText.size(file.size) : hint}
+                  </div>
+                )}
+                {locked && file && !multiple && reasonLine}
               </>
             )}
           </>
@@ -427,7 +481,8 @@ export function FileDropzone({
             ref={browseRef}
             type="button"
             variant="secondary"
-            disabled={inert}
+            disabled={controlDisabled}
+            disabledReason={controlReason}
             onClick={(e) => {
               e.stopPropagation();
               open();
@@ -439,7 +494,8 @@ export function FileDropzone({
             <Button
               type="button"
               variant="ghost"
-              disabled={inert}
+              disabled={controlDisabled}
+              disabledReason={controlReason}
               onClick={(e) => {
                 e.stopPropagation();
                 onClear();
@@ -455,6 +511,13 @@ export function FileDropzone({
             {error}
           </p>
         )}
+        {/* The group's description while locked: a copy of its own, so a custom body
+            that does not show the reason still has the zone say it. */}
+        {locked && (
+          <span id={reasonId} hidden>
+            {disabledReason}
+          </span>
+        )}
         <input
           ref={setFileInput}
           type="file"
@@ -484,6 +547,11 @@ export function FileDropzone({
   );
 }
 
+/** A reason that is really there — `null`, `false` and `""` are no reason. */
+function hasReason(reason: ReactNode): boolean {
+  return reason !== undefined && reason !== null && reason !== false && reason !== "";
+}
+
 /** A click that landed on a control inside the zone (a custom body's own button, a
  *  link in the hint) is that control's, not a request to open the picker. */
 function fromControl(e: MouseEvent<HTMLElement>): boolean {

package/src/components/form-actions.tsx

@@ -1,22 +1,35 @@
-import { isValidElement } from "react";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { isValidElement, useCallback, useEffect, useRef } from "react";
+import type { ComponentPropsWithoutRef, ReactNode, Ref } 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";
+import { isApplePlatform } from "../hooks/use-hotkey";
+import { Button, Spinner, type ButtonProps, type ButtonSize, type ButtonVariant } from "./ui";
+import { useWriteLock } from "./write-lock";
 
 /** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
 export interface FormActionsLabels {
   save: string;
   cancel: string;
+  /**
+   * The {@link FormActionsProps.submitShortcut} hint beside Save's text, when
+   * {@link FormActionsProps.submitShortcutHint} shows it. `apple` is true on a Mac,
+   * iPhone or iPad, where the key is Cmd: "⌘ Enter" there, "Ctrl+Enter" elsewhere
+   * (a German keyboard says "Strg").
+   */
+  submitShortcut: (apple: boolean) => string;
 }
 
 export const DEFAULT_FORM_ACTIONS_LABELS: FormActionsLabels = {
   save: "Save",
   cancel: "Cancel",
+  submitShortcut: (apple) => (apple ? "⌘ Enter" : "Ctrl+Enter"),
 };
 
+/** See {@link FormActionsProps.submitShortcut}. */
+export type FormActionsSubmitShortcut = "mod-enter";
+
 export type FormActionsAlign = "start" | "center" | "end" | "between";
 
 /**
@@ -173,6 +186,27 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
   /** The save button's variant. Default `brand`; `danger` for a save that destroys
    *  (kastlan's `destructive` flag on its own FormActions). */
   submitVariant?: ButtonVariant;
+  /**
+   * The Cancel button's variant. Default `secondary` (the outlined button, as before).
+   * `ghost` for a row where Cancel should step back further than an outline — keksdose
+   * G3: a quiet inline row (a confirm under a table row, a card's own small editor)
+   * whose Cancel was a ghost button before it moved onto FormActions, which drew every
+   * Cancel outlined.
+   */
+  cancelVariant?: ButtonVariant;
+  /**
+   * The size of every button the row draws itself — Save, Cancel and the
+   * `{ label, onClick }` form of {@link destructive}: Button's `size`. Default `md`.
+   * `sm` (12px text, `px-2 py-1`) for a dense row: a confirm inside a table's expansion
+   * row, a toolbar card. keksdose G3: two such rows had small hand-built buttons and lost
+   * them on adopting FormActions, which had no size. At `sm` the spinner and
+   * {@link submitIcon} shrink with the text.
+   *
+   * Your own elements (`children`, an element passed as `destructive`, `start`) are
+   * yours to size — pass them `size="sm"` too. A `size` in {@link submitProps} still
+   * wins for Save, as it always has.
+   */
+  size?: ButtonSize;
   /**
    * A destructive action at the START of the row, apart from Save and Cancel — the
    * "Delete" of an edit dialog. Pass `{ label, onClick }` for the kit's quiet danger
@@ -229,10 +263,60 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
   /** The `id` of the `<form>` the save button submits, when the row is rendered
    *  outside it (a dialog's footer slot). */
   form?: string;
+  /**
+   * A keyboard shortcut that presses Save from anywhere in the form. `"mod-enter"`:
+   * Ctrl+Enter, or Cmd+Enter on a Mac — both are accepted everywhere, as keksdose's
+   * editors always have. keksdose K14 (inputs audit 2026-10-02, S5): its transaction
+   * editor, category editor and create card each wrote this as an `onKeyDown` on a
+   * container, re-stating `!pending && !saveDisabled && !lock.locked` every time, and
+   * the one that forgot the lock let the demo's refused save through from the keyboard.
+   *
+   * What it does is what pressing Save does — the same button is clicked, so a form
+   * submits with its validation and its submitter, and `onSubmit` is called in the
+   * `type="button"` mode — and it does NOTHING while Save could not be pressed:
+   * `pending`, `submitDisabled`, or a `commit` under a locked {@link WriteLockProvider}.
+   *
+   * Scoped to the form Save submits (the `form` prop's, else the enclosing `<form>`):
+   * the chord counts only when the focus is inside it, so two editors on one page each
+   * answer for their own fields. Without a form (an `onSubmit` row in a plain container)
+   * the scope is the nearest `role="dialog"`, else the row's parent element — the
+   * container the row ends.
+   *
+   * Listened for on the document, so it runs AFTER every React handler: a field that
+   * takes Ctrl+Enter for itself calls `preventDefault()` or `stopPropagation()` and
+   * the row stays out of it (keksdose live #202 — the create card's Ctrl+Shift+Enter
+   * must create ONE row; the chord here is exactly Ctrl/Cmd+Enter, never with Shift or
+   * Alt). Not during IME composition, and not on a held key's repeats.
+   *
+   * The save button announces it with `aria-keyshortcuts`; {@link submitShortcutHint}
+   * also shows it.
+   */
+  submitShortcut?: FormActionsSubmitShortcut;
+  /** Show the {@link submitShortcut} beside Save's text ("Ctrl+Enter", "⌘ Enter"; the
+   *  `form.submitShortcut` label), dimmed. Hidden on a touch-only device, which has no
+   *  keyboard to press it on. Default `false`. */
+  submitShortcutHint?: boolean;
   /** Extra actions, placed before Cancel. */
   children?: ReactNode;
 }
 
+/** Hand `el` to a caller's ref, whichever kind it is. */
+function assignRef<E>(ref: Ref<E> | undefined, el: E | null): void {
+  if (typeof ref === "function") ref(el);
+  else if (ref) (ref as { current: E | null }).current = el;
+}
+
+/**
+ * Where {@link FormActionsProps.submitShortcut} listens: the form Save submits (named
+ * by `formId`, else the enclosing one), else the nearest dialog, else the row's parent.
+ */
+function shortcutScope(row: HTMLElement | null, formId: string | undefined): Element | null {
+  if (!row) return null;
+  const named = formId ? row.ownerDocument.getElementById(formId) : null;
+  if (named instanceof HTMLFormElement) return named;
+  return row.closest("form") ?? row.closest('[role="dialog"]') ?? row.parentElement;
+}
+
 function isDestructiveData(value: unknown): value is FormActionsDestructive {
   return typeof value === "object" && value !== null && !isValidElement(value) && "onClick" in value;
 }
@@ -265,6 +349,8 @@ export function FormActions({
   submitDisabledReason,
   commit = false,
   submitVariant = "brand",
+  cancelVariant = "secondary",
+  size = "md",
   destructive,
   start: startSlot,
   align,
@@ -272,12 +358,47 @@ export function FormActions({
   stickyWithin = "viewport",
   bleed,
   form,
+  submitShortcut,
+  submitShortcutHint = false,
   children,
   className,
   style,
   ...rest
 }: FormActionsProps) {
   const labels = useKitLabels("form", DEFAULT_FORM_ACTIONS_LABELS);
+  const lock = useWriteLock();
+  const rootRef = useRef<HTMLDivElement>(null);
+  const saveRef = useRef<HTMLButtonElement | null>(null);
+  // The caller's own `submitProps.ref` still gets the element.
+  const callerSaveRef = submitProps?.ref;
+  const setSaveRef = useCallback(
+    (el: HTMLButtonElement | null) => {
+      saveRef.current = el;
+      assignRef(callerSaveRef, el);
+    },
+    [callerSaveRef],
+  );
+  // Read by the shortcut's listener at the moment of the key press, so the listener
+  // itself is attached once and never sees a stale `pending`.
+  const canSave = !pending && !submitDisabled && !(commit && lock.locked);
+  const canSaveRef = useRef(canSave);
+  useEffect(() => {
+    canSaveRef.current = canSave;
+  });
+  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;
+      const scope = shortcutScope(rootRef.current, form);
+      if (!scope || !(e.target instanceof Node) || !scope.contains(e.target)) return;
+      e.preventDefault();
+      saveRef.current?.click();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [submitShortcut, form]);
+  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;
@@ -288,6 +409,7 @@ export function FormActions({
       type="button"
       variant="ghost"
       tone="danger"
+      size={size}
       onClick={destructive.onClick}
       disabled={destructive.disabled}
       disabledReason={destructive.disabledReason}
@@ -299,9 +421,13 @@ export function FormActions({
     destructive
   );
   const saveLabel = submitLabel ?? labels.save;
+  // The glyphs follow the text: 16px beside `md`'s 14px text, 14px beside `sm`'s 12px.
+  const saveSize = submitProps?.size ?? size;
+  const glyphClass = saveSize === "sm" ? "size-3.5" : "size-4";
 
   return (
     <div
+      ref={rootRef}
       data-slot="form-actions"
       data-placement={placement}
       data-sticky-within={placement === "sticky" ? stickyWithin : undefined}
@@ -336,16 +462,21 @@ export function FormActions({
       <div className="flex flex-wrap items-center gap-2">
         {children}
         {onCancel && (
-          <Button type="button" variant="secondary" onClick={onCancel}>
+          <Button type="button" variant={cancelVariant} size={size} onClick={onCancel}>
             {cancelLabel ?? labels.cancel}
           </Button>
         )}
         <Button
           {...submitProps}
+          ref={setSaveRef}
+          aria-keyshortcuts={
+            submitShortcut === "mod-enter" ? "Control+Enter Meta+Enter" : submitProps?.["aria-keyshortcuts"]
+          }
           type={onSubmit ? "button" : "submit"}
           form={form}
           onClick={onSubmit}
           variant={submitVariant}
+          size={saveSize}
           disabled={pending || submitDisabled}
           disabledReason={pending ? undefined : submitDisabledReason}
           // Not while pending: the save already left, and the lock's look over the
@@ -354,11 +485,21 @@ export function FormActions({
           aria-busy={pending || undefined}
         >
           {pending ? (
-            <Spinner label={null} className="size-4" />
+            <Spinner label={null} className={glyphClass} />
           ) : (
-            SubmitIcon && <SubmitIcon aria-hidden className="size-4 shrink-0" />
+            SubmitIcon && <SubmitIcon aria-hidden className={cn(glyphClass, "shrink-0")} />
           )}
           {pending && pendingLabel !== undefined ? pendingLabel : saveLabel}
+          {submitShortcut && submitShortcutHint && (
+            // Hidden from the accessibility tree: `aria-keyshortcuts` already says it,
+            // and in the name it would make the button "Save Ctrl+Enter".
+            <kbd
+              aria-hidden
+              className="ms-1 font-sans text-[0.85em] font-normal whitespace-nowrap opacity-70 pointer-coarse:hidden"
+            >
+              {labels.submitShortcut(apple)}
+            </kbd>
+          )}
         </Button>
       </div>
     </div>