@eifi1/ui-kit 0.33.0 → 0.34.0

package/src/hooks/use-file-picker.tsx

@@ -0,0 +1,363 @@
+import { useRef } from "react";
+import type { ReactElement } from "react";
+import { useAnnounce } from "./use-announce";
+import { useKitFileLabels, useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_FILE_PICKER_LABELS } from "./use-file-picker-labels";
+
+/**
+ * The file pickers' headless half: the hidden input, the screening of a pick and the
+ * announcement of a refusal, which {@link FileButton}, `FileDropzone` and {@link useFileDrop}
+ * are built on.
+ *
+ * In hooks/ since 0.34 (MOD-8, refactor audit 2026-10). It lived in
+ * components/file-button.tsx, and `useFileDrop` — a hook — imported it from there, so
+ * hooks/ reached up into components/. components/file-button re-exports all of it, so an
+ * import from there keeps working.
+ */
+
+/* ── Labels ──────────────────────────────────────────────────────────────── */
+
+/** Every string the file pickers ({@link FileButton}, `FileDropzone`) render or speak.
+ *  Messages are functions of the file name so a translation can put it anywhere. */
+export interface FilePickerLabels {
+  /** The file's type is not in `accept`, when no `accept` is known to name (see
+   *  `rejectedTypeOnly`). */
+  rejectedType: (name: string) => string;
+  /** The file's type is not in `accept`, naming what IS accepted: `accept`'s tokens,
+   *  lower-cased and joined with ", " (`".csv"` => "Only .csv files"). Used whenever
+   *  `accept` is set — kastlan kept a custom `isValid` + `invalidMessage` per form only
+   *  to say this, and `accept` already knows it. */
+  rejectedTypeOnly: (accept: string, name: string) => string;
+  /** The file is larger than `maxSize`; `maxSize` arrives formatted ("5 MB"). */
+  rejectedSize: (name: string, maxSize: string) => string;
+  /** The file was one too many for `maxFiles`. */
+  rejectedCount: (name: string, maxFiles: number) => string;
+  /** `isValid` said no and the caller gave no `invalidMessage`. */
+  rejectedInvalid: (name: string) => string;
+  /** Spoken instead of the per-file message when more than one file was refused. */
+  rejectedMany: (count: number) => string;
+  /** Spoken (and shown, on a dropzone) when `onPick` refused the WHOLE pick.
+   *  Receives the number of files in it. */
+  rejectedPick: (count: number) => string;
+  /** Spoken after a pick the component itself echoes (the dropzone). */
+  selected: (count: number, firstName: string) => string;
+  /** The dropzone's remove button for one file. */
+  remove: (name: string) => string;
+  /** The dropzone's remove-everything button in `multiple` mode. */
+  clearAll: string;
+  /** Spoken after a remove / clear, since the button that was pressed is gone. */
+  removed: (name: string) => string;
+  cleared: string;
+  /** The dropzone's accessible name, when the host passes no `dropLabel`. */
+  dropzone: string;
+  /** The dropzone's Browse button, when the host passes no `browseLabel`. */
+  browse: string;
+  /** What an empty single-file dropzone says (no `emptyLabel` given). */
+  empty: string;
+  /** …and an empty `multiple` one. */
+  emptyMultiple: string;
+  /** The dropzone's second line (no `hint` given). Receives `accept` as a person
+   *  reads it (`".pdf, image/png"`), or `""` when anything goes. */
+  hint: (accept: string) => string;
+  /** What a `busy` dropzone says in place of its body ("Uploading…"). */
+  busy: string;
+}
+
+/* ── Screening ───────────────────────────────────────────────────────────── */
+
+export type FileRejectionReason = "type" | "size" | "count" | "invalid";
+
+/** One file the picker refused, and why. `message` is already translated (see
+ *  {@link FilePickerLabels}, or the caller's `invalidMessage`), so a host that just
+ *  wants to show it can render `rejections[0].message` as is. */
+export interface FileRejection {
+  file: File;
+  reason: FileRejectionReason;
+  message: string;
+}
+
+/**
+ * Does `file` satisfy an `accept` string, the way the browser's dialog reads it?
+ * Comma-separated tokens: `.ext` (case-insensitive suffix of the name), `type/*`
+ * (a MIME family) or an exact MIME type. An empty or absent `accept` takes anything.
+ *
+ * A file with no `type` — common for `.step`, `.dat`, anything the OS has no MIME
+ * mapping for — can only match by extension, which is why lenkbank lists `.stp` AND
+ * `model/step`: that is how `accept` has to be written for the dialog anyway.
+ */
+export function matchesAccept(file: File, accept: string | undefined): boolean {
+  const tokens = (accept ?? "")
+    .split(",")
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean);
+  if (tokens.length === 0) return true;
+  const name = file.name.toLowerCase();
+  // An EMPTY type is the browser saying "I don't know", not "it's something else": HEIC
+  // photos on Windows without the codec arrive with `type === ""`. Refusing them
+  // (0.6.0) refused iPhone photos the picker itself had just offered (keksdose). So a
+  // missing type is inferred from the extension where that is unambiguous, and a file
+  // whose type cannot be known at all is given the benefit of the doubt — nothing here
+  // proves it does not match, and the server validates what it receives anyway.
+  const type = (file.type || typeFromExtension(name) || "").toLowerCase();
+  if (!type && !tokens.every((t) => t.startsWith("."))) return true;
+  return tokens.some((token) => {
+    if (token.startsWith(".")) return name.endsWith(token);
+    if (!type) return false;
+    if (token.endsWith("/*")) return type.startsWith(token.slice(0, -1));
+    return type === token;
+  });
+}
+
+/** MIME types for the extensions a browser most often leaves untyped. */
+const EXTENSION_TYPES: Record<string, string> = {
+  heic: "image/heic",
+  heif: "image/heif",
+  avif: "image/avif",
+  webp: "image/webp",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  pdf: "application/pdf",
+  csv: "text/csv",
+  txt: "text/plain",
+};
+
+function typeFromExtension(name: string): string | undefined {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? undefined : EXTENSION_TYPES[name.slice(dot + 1)];
+}
+
+/** @internal `" .PDF, image/png ,"` => `".pdf, image/png"` — `accept` as a person reads
+ *  it. Also the dropzone's default hint. */
+export function formatAccept(accept: string): string {
+  return accept
+    .split(",")
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean)
+    .join(", ");
+}
+
+/** What the pickers screen a pick with. All optional; nothing set accepts everything. */
+export interface FileScreenOptions {
+  accept?: string;
+  /** Bytes. Larger files are refused with reason `"size"`. */
+  maxSize?: number;
+  /** How many files one pick may deliver. The rest are refused with reason `"count"`
+   *  — first come, first kept. For a running cap ("at most 5 attachments") pass what
+   *  is LEFT: `maxFiles={5 - attachments.length}`. */
+  maxFiles?: number;
+  /** The caller's own check, after `accept` and `maxSize`. */
+  isValid?: (file: File) => boolean;
+  /** The message for an `isValid` refusal; `labels.rejectedInvalid` otherwise. */
+  invalidMessage?: string;
+}
+
+/** @internal Split a pick into the files that pass and the ones that do not. */
+export function screenFiles(
+  files: readonly File[],
+  opts: FileScreenOptions,
+  labels: FilePickerLabels,
+  formatSize: (bytes: number) => string,
+): { accepted: File[]; rejected: FileRejection[] } {
+  const accepted: File[] = [];
+  const rejected: FileRejection[] = [];
+  // Name what `accept` takes ("Only .csv files") — unless the host translated
+  // `rejectedType` but not yet `rejectedTypeOnly`: its own sentence beats an English one.
+  const acceptText = opts.accept ? formatAccept(opts.accept) : "";
+  const useOnly =
+    acceptText !== "" &&
+    (labels.rejectedTypeOnly !== DEFAULT_FILE_PICKER_LABELS.rejectedTypeOnly ||
+      labels.rejectedType === DEFAULT_FILE_PICKER_LABELS.rejectedType);
+  const typeMessage = (name: string) =>
+    useOnly ? labels.rejectedTypeOnly(acceptText, name) : labels.rejectedType(name);
+  for (const file of files) {
+    let reason: FileRejectionReason | null = null;
+    if (!matchesAccept(file, opts.accept)) reason = "type";
+    else if (opts.maxSize !== undefined && file.size > opts.maxSize) reason = "size";
+    else if (opts.isValid && !opts.isValid(file)) reason = "invalid";
+    // Count last, and only against files that passed everything else: a refused
+    // file should not use up one of the slots a good one could have had.
+    else if (opts.maxFiles !== undefined && accepted.length >= opts.maxFiles) reason = "count";
+    if (reason === null) {
+      accepted.push(file);
+      continue;
+    }
+    const message =
+      reason === "type"
+        ? typeMessage(file.name)
+        : reason === "size"
+          ? labels.rejectedSize(file.name, formatSize(opts.maxSize ?? 0))
+          : reason === "count"
+            ? labels.rejectedCount(file.name, Math.max(0, opts.maxFiles ?? 0))
+            : (opts.invalidMessage ?? labels.rejectedInvalid(file.name));
+    rejected.push({ file, reason, message });
+  }
+  return { accepted, rejected };
+}
+
+/**
+ * Judges a pick as a whole — keksdose's "refuse the pick if any file is bad", which
+ * with `onFiles` + `onReject` alone had to be rebuilt from two calls in a microtask.
+ *
+ * Called ONCE per pick, after screening and before `onFiles` / `onReject`, with both
+ * halves (either may be empty). Return `false` to refuse the whole pick: the accepted
+ * files are not delivered, `onReject` still receives what screening refused, and one
+ * sentence (`labels.rejectedPick`) is spoken for the pick instead of a per-file one.
+ * Return nothing to let the pick through as usual.
+ *
+ * ```tsx
+ * onPick={(ok, bad) => bad.length === 0 || false}  // all or nothing
+ * ```
+ */
+export type FilePickHandler = (accepted: File[], rejected: FileRejection[]) => boolean | void;
+
+/** @internal The shared tail of both pickers: run `onPick`, and say whether the pick
+ *  stands. A pick with nothing accepted has nothing to refuse, so `false` there is
+ *  treated as no verdict and the usual per-file messages are kept. */
+export function judgePick(
+  onPick: FilePickHandler | undefined,
+  accepted: File[],
+  rejected: FileRejection[],
+): boolean {
+  if (!onPick) return true;
+  return onPick(accepted, rejected) !== false || accepted.length === 0;
+}
+
+/** One sentence for a whole batch of refusals: the file's own message for one, a
+ *  count for several — reading out five sentences in a row helps nobody. */
+export function summariseRejections(rejected: readonly FileRejection[], labels: FilePickerLabels): string {
+  if (rejected.length === 0) return "";
+  if (rejected.length === 1) return rejected[0].message;
+  return labels.rejectedMany(rejected.length);
+}
+
+/* ── useFilePicker ───────────────────────────────────────────────────────── */
+
+export interface UseFilePickerOptions extends FileScreenOptions {
+  /** Let one pick deliver several files. Without it a drop of several keeps the first. */
+  multiple?: boolean;
+  /**
+   * Ask a phone for its camera instead of the file chooser: `"environment"` is the
+   * back camera, `"user"` the front. A HINT — desktop browsers ignore it, and Chrome
+   * drops it when `multiple` is also set (a camera cannot deliver a list), which is why
+   * keksdose's camera input has no `multiple`. Pass one or the other.
+   */
+  capture?: boolean | "user" | "environment";
+  /** The files that passed, in pick order. Never called with an empty array.
+   *  Optional since 0.7 for a caller that takes the pick through `onPick` alone. */
+  onFiles?: (files: File[]) => void;
+  /** See {@link FilePickHandler}: the whole pick at once, with the power to refuse it. */
+  onPick?: FilePickHandler;
+  /** The files that did not, with a translated message each. The refusals are also
+   *  spoken through a live region, so this is for SHOWING them, not for a11y. */
+  onReject?: (rejections: FileRejection[]) => void;
+  /** `open()` and `take()` do nothing while set. */
+  disabled?: boolean;
+  /** Per-instance overrides of the `filePicker` label namespace. */
+  labels?: LabelOverride<FilePickerLabels>;
+}
+
+export interface UseFilePickerReturn {
+  /** Open the system picker. Call it from a click handler — browsers only open a file
+   *  dialog in response to a user gesture. */
+  open: () => void;
+  /** Screen and deliver files that arrived some other way — a drop, a paste. Honours
+   *  `multiple` (only the first file without it) and every check. */
+  take: (files: ArrayLike<File> | null | undefined) => void;
+  /** The hidden input and the live region. Render it once, anywhere — it takes no
+   *  space and needs no positioned ancestor. */
+  element: ReactElement;
+}
+
+/**
+ * The headless half of {@link FileButton}: a hidden file input you can open from any
+ * control, with the reset, the screening and the announcement built in.
+ *
+ * ```tsx
+ * const picker = useFilePicker({ accept: ".pdf", onFiles: ([f]) => upload(f) });
+ * return <>{picker.element}<DetailTableCard onAdd={picker.open} … /></>;
+ * ```
+ */
+export function useFilePicker({
+  accept,
+  multiple,
+  capture,
+  maxSize,
+  maxFiles,
+  isValid,
+  invalidMessage,
+  onFiles,
+  onPick,
+  onReject,
+  disabled,
+  labels: labelsProp,
+}: UseFilePickerOptions): UseFilePickerReturn {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const labels = useKitLabels("filePicker", DEFAULT_FILE_PICKER_LABELS, labelsProp);
+  const fileText = useKitFileLabels();
+  // Assertive: a refusal is a failure the user has to hear before they move on, and
+  // it is the only thing this region ever says.
+  const { announce, regionProps } = useAnnounce({ politeness: "assertive" });
+
+  const take = (list: ArrayLike<File> | null | undefined) => {
+    if (disabled || !list || list.length === 0) return;
+    const all = Array.from(list);
+    const files = multiple ? all : all.slice(0, 1);
+    const { accepted, rejected } = screenFiles(
+      files,
+      // A single-file picker holds one file by definition; `maxFiles` is a multi-mode
+      // cap and would only ever say "0" there if a caller passed it by mistake.
+      { accept, maxSize, maxFiles: multiple ? maxFiles : undefined, isValid, invalidMessage },
+      labels,
+      fileText.size,
+    );
+    if (!judgePick(onPick, accepted, rejected)) {
+      if (rejected.length > 0) onReject?.(rejected);
+      announce(labels.rejectedPick(files.length));
+      return;
+    }
+    if (accepted.length > 0) onFiles?.(accepted);
+    if (rejected.length > 0) {
+      onReject?.(rejected);
+      announce(summariseRejections(rejected, labels));
+    }
+  };
+
+  const element = (
+    <>
+      <input
+        ref={inputRef}
+        type="file"
+        accept={accept}
+        multiple={multiple}
+        capture={capture}
+        disabled={disabled}
+        // `hidden` (display: none), not `sr-only`: the control a user reaches is the
+        // button, and a second, nameless tab stop for the same action is noise. A
+        // display:none file input still opens on `.click()` in every current browser —
+        // and, unlike `sr-only`, it cannot escape to the initial containing block and
+        // stretch the page (see the note in `file-dropzone.tsx`).
+        className="hidden"
+        tabIndex={-1}
+        aria-hidden
+        onChange={(e) => {
+          // Copy BEFORE the reset: `files` is a live view of the input's value, and
+          // clearing the value empties it.
+          const picked = Array.from(e.currentTarget.files ?? []);
+          e.currentTarget.value = "";
+          take(picked);
+        }}
+      />
+      <span {...regionProps} />
+    </>
+  );
+
+  return {
+    open: () => {
+      if (!disabled) inputRef.current?.click();
+    },
+    take,
+    element,
+  };
+}

package/src/hooks/use-focus-trap.ts

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 
 /**
  * Keep keyboard focus inside an open overlay, and give it back when it closes.
@@ -23,6 +23,10 @@ import { useEffect, useRef } from "react";
  *     `<body>`, which for a keyboard user means losing their place in the page
  *     entirely. When the target is gone, focus falls back to the nearest thing that
  *     still exists rather than to nothing.
+ *   - **Leaves an app's own autofocus alone** (0.33.1). React honours a child's
+ *     `autoFocus` while it commits, and this hook's effect runs AFTER that commit, so
+ *     focusing the container there took focus straight back off the field the app had
+ *     asked for. See `initialFocus`.
  *   - **Nests.** An overlay can open another — a picker inside a dialog. Only the
  *     innermost trap handles a keystroke, and closing it hands control back to the one
  *     underneath. Innermost is decided by DOM containment rather than by mount order;
@@ -32,16 +36,29 @@ import { useEffect, useRef } from "react";
  */
 
 /**
- * Tabbable descendants, in DOM order.
+ * Candidate tab stops, in DOM order — narrowed by {@link isTabStop} to the ones a Tab
+ * really reaches.
  *
- * Deliberately the same selector `Modal` used, rather than a more thorough one that
- * also walks `inert`, `visibility: hidden` and open `<details>`: this is the set that
- * has been in production across three apps, and widening it here would change which
- * element receives focus in overlays nobody asked me to change the behaviour of.
+ * The selector is the one `Modal` used. On its own it was not enough (round 0.34
+ * BUG-4): only the bare `[tabindex]` clause excluded `-1`, so a `button`, an `input` or
+ * a link taken out of the tab order still counted. A panel that ends in a roving grid —
+ * the calendar's days, the month grid, the picker sheet's rows, every one of them `-1`
+ * but the active cell — then had a "last" stop no Tab ever reaches: Tab from the real
+ * last stop was not wrapped and walked out of the open panel, and Shift+Tab from the
+ * first landed on a cell that is not a stop at all.
  */
 const FOCUSABLE =
   'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
 
+/**
+ * A stop the browser's own Tab would land on: in the tab order (`tabIndex` ≥ 0) and not
+ * inside something `hidden` or `inert`. Removes only elements a native Tab never
+ * reaches, so no correct order changes. `visibility: hidden` and closed `<details>` are
+ * still not walked — they need layout, which this list has never read.
+ */
+const isTabStop = (el: HTMLElement): boolean =>
+  el.tabIndex >= 0 && !el.closest("[hidden],[inert]");
+
 /**
  * Marks a container whose trap is currently active.
  *
@@ -66,29 +83,61 @@ export interface FocusTrapOptions {
    * what `Modal` does and why: focusing the first FIELD pops the software keyboard on
    * a phone the moment a dialog opens, before the user has asked to type.
    * The container needs `tabIndex={-1}` for this to work.
+   *
+   * `"container"` and `"first"` both step aside when focus is ALREADY inside the
+   * container, on something other than the container itself. That is a child the app
+   * focused on purpose — an `autoFocus`, which React honours before this hook's effect
+   * runs — and the keyboard it brings up is the one the user was promised. Moving focus
+   * off it lost keksdose's create card its amount field the instant it got it, and on a
+   * phone the numpad sheet with it, which shows only while the field is focused (live
+   * #402). A function is the caller's explicit choice and is always followed.
    */
   initialFocus?: "container" | "first" | (() => HTMLElement | null);
 }
 
+/** Whatever has focus right now; nothing on the server, where there is no document. */
+function focusedElement(): Element | null {
+  return typeof document === "undefined" ? null : document.activeElement;
+}
+
 export function useFocusTrap(
   containerRef: React.RefObject<HTMLElement | null>,
   { active = true, restoreFocus = true, initialFocus = "container" }: FocusTrapOptions = {},
 ): void {
   // Latest-ref so a caller passing an inline `initialFocus` thunk — which every caller
   // will — does not tear the trap down and re-engage it on each render, stealing focus
-  // back to the top of the panel mid-interaction.
-  const optsRef = useRef({ restoreFocus, initialFocus });
-  useEffect(() => {
-    optsRef.current = { restoreFocus, initialFocus };
+  // back to the top of the panel mid-interaction. Written in a LAYOUT effect so that
+  // the trap's cleanup, which runs after the layout effects of the same commit, reads
+  // this render's `active` rather than the last one's — see the cleanup for why.
+  const optsRef = useRef({ active, restoreFocus, initialFocus });
+  useLayoutEffect(() => {
+    optsRef.current = { active, restoreFocus, initialFocus };
   });
 
+  // Where focus was BEFORE the trap engaged: the element it is given back to on close.
+  //
+  // Read DURING the render that turns the trap on, and that timing is the point. React
+  // honours a child's `autoFocus` while it commits that render, before any effect runs,
+  // so the effect below asking `document.activeElement` would get the child, inside the
+  // overlay. Restoring to that on close aimed focus at the dialog that was closing —
+  // already out of the DOM, so focus fell to <body> rather than going back to the
+  // button that opened it.
+  //
+  // State adjusted during render (the pattern `Modal` uses for `open`) rather than a
+  // ref written there: set once per opening and cleared on release, so a re-render
+  // while open cannot replace it with something inside, and StrictMode's second render
+  // and second effect both see the same element. `undefined` means "not captured";
+  // `null` is a capture that found nothing.
+  const [opener, setOpener] = useState<Element | null | undefined>(undefined);
+  if (active && opener === undefined) setOpener(focusedElement());
+  else if (!active && opener !== undefined) setOpener(undefined);
+
   useEffect(() => {
     if (!active) return;
     const container = containerRef.current;
     if (!container) return;
 
     container.setAttribute(TRAP_ATTR, "");
-    const previouslyFocused = document.activeElement as HTMLElement | null;
 
     /** Is `node` inside a trap nested within this one? */
     const inNestedTrap = (node: Element | null) => {
@@ -102,16 +151,17 @@ export function useFocusTrap(
         // A tabbable inside a NESTED open overlay belongs to that overlay's trap, not
         // to this one — otherwise the outer list spans both panels and Tab from the
         // inner panel's last control wraps to the OUTER panel's first.
-        (el) => !inNestedTrap(el),
+        (el) => isTabStop(el) && !inNestedTrap(el),
       );
 
     const { initialFocus: how } = optsRef.current;
+    const focused = document.activeElement;
+    // A child that already has focus was given it on purpose — see `initialFocus`.
+    const childHasFocus = focused !== container && container.contains(focused);
     if (typeof how === "function") {
       (how() ?? container).focus();
-    } else if (how === "first") {
-      (tabbables()[0] ?? container).focus();
-    } else {
-      container.focus();
+    } else if (!childHasFocus) {
+      (how === "first" ? (tabbables()[0] ?? container) : container).focus();
     }
 
     const onKeyDown = (e: KeyboardEvent) => {
@@ -149,12 +199,18 @@ export function useFocusTrap(
       container.removeEventListener("keydown", onKeyDown);
       container.removeAttribute(TRAP_ATTR);
 
+      // Only when the trap is really being released: the container has left the page,
+      // or `active` has turned false. StrictMode runs this cleanup once more right after
+      // mounting, with the overlay still up, and then the effect again — and React does
+      // not re-apply `autoFocus` for that second run. Restoring here would pull focus
+      // out of the autofocused field for good: live #402 again, in development.
+      if (container.isConnected && optsRef.current.active) return;
       if (!optsRef.current.restoreFocus) return;
       // `isConnected` is the whole point: restoring to a node that has been removed
       // sends focus to <body> and the user loses their place entirely. When the
       // original is gone, leave focus where the browser put it rather than moving it
       // somewhere arbitrary — a wrong guess is worse than no move.
-      if (previouslyFocused?.isConnected) previouslyFocused.focus?.();
+      if (opener?.isConnected) (opener as HTMLElement).focus?.();
     };
-  }, [active, containerRef]);
+  }, [active, containerRef, opener]);
 }