@eifi1/ui-kit 0.33.0 → 0.34.0

package/dist/hooks/use-file-picker.js

@@ -0,0 +1,149 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { useAnnounce } from "./use-announce.js";
+import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels.js";
+import { DEFAULT_FILE_PICKER_LABELS } from "./use-file-picker-labels.js";
+function matchesAccept(file, accept) {
+  const tokens = (accept ?? "").split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
+  if (tokens.length === 0) return true;
+  const name = file.name.toLowerCase();
+  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;
+  });
+}
+const EXTENSION_TYPES = {
+  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) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? void 0 : EXTENSION_TYPES[name.slice(dot + 1)];
+}
+function formatAccept(accept) {
+  return accept.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean).join(", ");
+}
+function screenFiles(files, opts, labels, formatSize) {
+  const accepted = [];
+  const rejected = [];
+  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) => useOnly ? labels.rejectedTypeOnly(acceptText, name) : labels.rejectedType(name);
+  for (const file of files) {
+    let reason = null;
+    if (!matchesAccept(file, opts.accept)) reason = "type";
+    else if (opts.maxSize !== void 0 && file.size > opts.maxSize) reason = "size";
+    else if (opts.isValid && !opts.isValid(file)) reason = "invalid";
+    else if (opts.maxFiles !== void 0 && 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 };
+}
+function judgePick(onPick, accepted, rejected) {
+  if (!onPick) return true;
+  return onPick(accepted, rejected) !== false || accepted.length === 0;
+}
+function summariseRejections(rejected, labels) {
+  if (rejected.length === 0) return "";
+  if (rejected.length === 1) return rejected[0].message;
+  return labels.rejectedMany(rejected.length);
+}
+function useFilePicker({
+  accept,
+  multiple,
+  capture,
+  maxSize,
+  maxFiles,
+  isValid,
+  invalidMessage,
+  onFiles,
+  onPick,
+  onReject,
+  disabled,
+  labels: labelsProp
+}) {
+  const inputRef = useRef(null);
+  const labels = useKitLabels("filePicker", DEFAULT_FILE_PICKER_LABELS, labelsProp);
+  const fileText = useKitFileLabels();
+  const { announce, regionProps } = useAnnounce({ politeness: "assertive" });
+  const take = (list) => {
+    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 : void 0, 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 = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "input",
+      {
+        ref: inputRef,
+        type: "file",
+        accept,
+        multiple,
+        capture,
+        disabled,
+        className: "hidden",
+        tabIndex: -1,
+        "aria-hidden": true,
+        onChange: (e) => {
+          const picked = Array.from(e.currentTarget.files ?? []);
+          e.currentTarget.value = "";
+          take(picked);
+        }
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { ...regionProps })
+  ] });
+  return {
+    open: () => {
+      if (!disabled) inputRef.current?.click();
+    },
+    take,
+    element
+  };
+}
+export {
+  formatAccept,
+  judgePick,
+  matchesAccept,
+  screenFiles,
+  summariseRejections,
+  useFilePicker
+};
+//# sourceMappingURL=use-file-picker.js.map

package/dist/hooks/use-file-picker.js.map

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

package/dist/hooks/use-focus-trap.d.ts

@@ -1,4 +1,4 @@
-interface FocusTrapOptions {
+export interface FocusTrapOptions {
     /** Trap only while this is true. Mount-time `true` is the common case. */
     active?: boolean;
     /** Return focus to whatever had it before the trap engaged. Default `true`. */
@@ -8,9 +8,15 @@ 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);
 }
-declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, { active, restoreFocus, initialFocus }?: FocusTrapOptions): void;
-
-export { type FocusTrapOptions, useFocusTrap };
+export declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, { active, restoreFocus, initialFocus }?: FocusTrapOptions): void;

package/dist/hooks/use-focus-trap.js

@@ -1,18 +1,24 @@
 "use client";
-import { useEffect, useRef } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 const FOCUSABLE = 'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+const isTabStop = (el) => el.tabIndex >= 0 && !el.closest("[hidden],[inert]");
 const TRAP_ATTR = "data-focus-trap";
+function focusedElement() {
+  return typeof document === "undefined" ? null : document.activeElement;
+}
 function useFocusTrap(containerRef, { active = true, restoreFocus = true, initialFocus = "container" } = {}) {
-  const optsRef = useRef({ restoreFocus, initialFocus });
-  useEffect(() => {
-    optsRef.current = { restoreFocus, initialFocus };
+  const optsRef = useRef({ active, restoreFocus, initialFocus });
+  useLayoutEffect(() => {
+    optsRef.current = { active, restoreFocus, initialFocus };
   });
+  const [opener, setOpener] = useState(void 0);
+  if (active && opener === void 0) setOpener(focusedElement());
+  else if (!active && opener !== void 0) setOpener(void 0);
   useEffect(() => {
     if (!active) return;
     const container = containerRef.current;
     if (!container) return;
     container.setAttribute(TRAP_ATTR, "");
-    const previouslyFocused = document.activeElement;
     const inNestedTrap = (node) => {
       if (!node) return false;
       const owner = node.closest(`[${TRAP_ATTR}]`);
@@ -22,15 +28,15 @@ function useFocusTrap(containerRef, { active = true, restoreFocus = true, initia
       // 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;
+    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) => {
       if (e.key !== "Tab") return;
@@ -56,10 +62,11 @@ function useFocusTrap(containerRef, { active = true, restoreFocus = true, initia
     return () => {
       container.removeEventListener("keydown", onKeyDown);
       container.removeAttribute(TRAP_ATTR);
+      if (container.isConnected && optsRef.current.active) return;
       if (!optsRef.current.restoreFocus) return;
-      if (previouslyFocused?.isConnected) previouslyFocused.focus?.();
+      if (opener?.isConnected) opener.focus?.();
     };
-  }, [active, containerRef]);
+  }, [active, containerRef, opener]);
 }
 export {
   useFocusTrap

package/dist/hooks/use-focus-trap.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/hooks/use-focus-trap.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\n/**\n * Keep keyboard focus inside an open overlay, and give it back when it closes.\n *\n * Extracted from `Modal`, which was the ONLY component in this package that did any of\n * this. Every other overlay — the full-bleed dialog a phone's row editor opens, the\n * picker sheet, the numpad, the tour card — declared `role=\"dialog\" aria-modal=\"true\"`\n * and then left focus on the page behind it. That is the worst of the two possible\n * bugs: assistive technology hides the page because of `aria-modal`, while the user's\n * focus is still down there in the part that is now hidden, so Tab walks through\n * controls the screen reader refuses to describe.\n *\n * What this does beyond Modal's original copy:\n *\n *   - **Recomputes the tabbable list on every Tab**, not once when the overlay opens.\n *     These panels have conditionally-rendered contents — a search box that appears\n *     once options load, a \"clear\" button that exists only while a filter is set — and\n *     a list captured at open time traps focus against elements that have since gone.\n *   - **Guards the restore target.** The element focused before opening may have left\n *     the DOM by the time the overlay closes (the row that owned the button was\n *     filtered away). Calling `.focus()` on a detached node silently drops focus to\n *     `<body>`, which for a keyboard user means losing their place in the page\n *     entirely. When the target is gone, focus falls back to the nearest thing that\n *     still exists rather than to nothing.\n *   - **Nests.** An overlay can open another — a picker inside a dialog. Only the\n *     innermost trap handles a keystroke, and closing it hands control back to the one\n *     underneath. Innermost is decided by DOM containment rather than by mount order;\n *     see the note on `TRAP_ATTR` for why the obvious stack is wrong.\n *     `use-overlay-history.ts` reasons about the same nesting problem for the back\n *     button; this is the focus half of it.\n */\n\n/**\n * Tabbable descendants, in DOM order.\n *\n * Deliberately the same selector `Modal` used, rather than a more thorough one that\n * also walks `inert`, `visibility: hidden` and open `<details>`: this is the set that\n * has been in production across three apps, and widening it here would change which\n * element receives focus in overlays nobody asked me to change the behaviour of.\n */\nconst FOCUSABLE =\n  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\n\n/**\n * Marks a container whose trap is currently active.\n *\n * \"Which trap is innermost?\" is answered by DOM CONTAINMENT, not by mount order. The\n * obvious implementation — a module-level stack pushed in the effect — is wrong, and\n * wrong in a way that passes a casual reading: React runs CHILD effects before PARENT\n * effects, so a nested overlay pushes first and the outer one ends up on top of the\n * stack, claiming to be innermost. The outer trap then handles the keystroke and wraps\n * focus to its own first element, jumping the user out of the picker they had open.\n *\n * An attribute on the live DOM cannot disagree with the DOM.\n */\nconst TRAP_ATTR = \"data-focus-trap\";\n\nexport interface FocusTrapOptions {\n  /** Trap only while this is true. Mount-time `true` is the common case. */\n  active?: boolean;\n  /** Return focus to whatever had it before the trap engaged. Default `true`. */\n  restoreFocus?: boolean;\n  /**\n   * What to focus when the trap engages. Default is the container itself, which is\n   * what `Modal` does and why: focusing the first FIELD pops the software keyboard on\n   * a phone the moment a dialog opens, before the user has asked to type.\n   * The container needs `tabIndex={-1}` for this to work.\n   */\n  initialFocus?: \"container\" | \"first\" | (() => HTMLElement | null);\n}\n\nexport function useFocusTrap(\n  containerRef: React.RefObject<HTMLElement | null>,\n  { active = true, restoreFocus = true, initialFocus = \"container\" }: FocusTrapOptions = {},\n): void {\n  // Latest-ref so a caller passing an inline `initialFocus` thunk — which every caller\n  // will — does not tear the trap down and re-engage it on each render, stealing focus\n  // back to the top of the panel mid-interaction.\n  const optsRef = useRef({ restoreFocus, initialFocus });\n  useEffect(() => {\n    optsRef.current = { restoreFocus, initialFocus };\n  });\n\n  useEffect(() => {\n    if (!active) return;\n    const container = containerRef.current;\n    if (!container) return;\n\n    container.setAttribute(TRAP_ATTR, \"\");\n    const previouslyFocused = document.activeElement as HTMLElement | null;\n\n    /** Is `node` inside a trap nested within this one? */\n    const inNestedTrap = (node: Element | null) => {\n      if (!node) return false;\n      const owner = node.closest(`[${TRAP_ATTR}]`);\n      return owner !== null && owner !== container;\n    };\n\n    const tabbables = () =>\n      Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(\n        // A tabbable inside a NESTED open overlay belongs to that overlay's trap, not\n        // to this one — otherwise the outer list spans both panels and Tab from the\n        // inner panel's last control wraps to the OUTER panel's first.\n        (el) => !inNestedTrap(el),\n      );\n\n    const { initialFocus: how } = optsRef.current;\n    if (typeof how === \"function\") {\n      (how() ?? container).focus();\n    } else if (how === \"first\") {\n      (tabbables()[0] ?? container).focus();\n    } else {\n      container.focus();\n    }\n\n    const onKeyDown = (e: KeyboardEvent) => {\n      if (e.key !== \"Tab\") return;\n      // Only the innermost trap acts. The event bubbles through every ancestor\n      // container, so without this an outer dialog and an inner picker both handle one\n      // Tab and fight over where focus lands.\n      if (inNestedTrap(document.activeElement)) return;\n\n      // Recomputed per keystroke — see the note at the top of this file.\n      const items = tabbables();\n      if (items.length === 0) {\n        e.preventDefault();\n        container.focus();\n        return;\n      }\n      const first = items[0];\n      const last = items[items.length - 1];\n      const activeEl = document.activeElement;\n      if (e.shiftKey && (activeEl === first || activeEl === container)) {\n        e.preventDefault();\n        last.focus();\n      } else if (!e.shiftKey && activeEl === last) {\n        e.preventDefault();\n        first.focus();\n      }\n    };\n\n    // On the container, not the document: a portalled child panel (an open dropdown\n    // rendered to <body>) is outside this subtree and manages its own focus, which is\n    // the behaviour Modal's comment describes and consumers already depend on.\n    container.addEventListener(\"keydown\", onKeyDown);\n\n    return () => {\n      container.removeEventListener(\"keydown\", onKeyDown);\n      container.removeAttribute(TRAP_ATTR);\n\n      if (!optsRef.current.restoreFocus) return;\n      // `isConnected` is the whole point: restoring to a node that has been removed\n      // sends focus to <body> and the user loses their place entirely. When the\n      // original is gone, leave focus where the browser put it rather than moving it\n      // somewhere arbitrary — a wrong guess is worse than no move.\n      if (previouslyFocused?.isConnected) previouslyFocused.focus?.();\n    };\n  }, [active, containerRef]);\n}\n"],"mappings":";AAAA,SAAS,WAAW,cAAc;AAyClC,MAAM,YACJ;AAcF,MAAM,YAAY;AAgBX,SAAS,aACd,cACA,EAAE,SAAS,MAAM,eAAe,MAAM,eAAe,YAAY,IAAsB,CAAC,GAClF;AAIN,QAAM,UAAU,OAAO,EAAE,cAAc,aAAa,CAAC;AACrD,YAAU,MAAM;AACd,YAAQ,UAAU,EAAE,cAAc,aAAa;AAAA,EACjD,CAAC;AAED,YAAU,MAAM;AACd,QAAI,CAAC,OAAQ;AACb,UAAM,YAAY,aAAa;AAC/B,QAAI,CAAC,UAAW;AAEhB,cAAU,aAAa,WAAW,EAAE;AACpC,UAAM,oBAAoB,SAAS;AAGnC,UAAM,eAAe,CAAC,SAAyB;AAC7C,UAAI,CAAC,KAAM,QAAO;AAClB,YAAM,QAAQ,KAAK,QAAQ,IAAI,SAAS,GAAG;AAC3C,aAAO,UAAU,QAAQ,UAAU;AAAA,IACrC;AAEA,UAAM,YAAY,MAChB,MAAM,KAAK,UAAU,iBAA8B,SAAS,CAAC,EAAE;AAAA;AAAA;AAAA;AAAA,MAI7D,CAAC,OAAO,CAAC,aAAa,EAAE;AAAA,IAC1B;AAEF,UAAM,EAAE,cAAc,IAAI,IAAI,QAAQ;AACtC,QAAI,OAAO,QAAQ,YAAY;AAC7B,OAAC,IAAI,KAAK,WAAW,MAAM;AAAA,IAC7B,WAAW,QAAQ,SAAS;AAC1B,OAAC,UAAU,EAAE,CAAC,KAAK,WAAW,MAAM;AAAA,IACtC,OAAO;AACL,gBAAU,MAAM;AAAA,IAClB;AAEA,UAAM,YAAY,CAAC,MAAqB;AACtC,UAAI,EAAE,QAAQ,MAAO;AAIrB,UAAI,aAAa,SAAS,aAAa,EAAG;AAG1C,YAAM,QAAQ,UAAU;AACxB,UAAI,MAAM,WAAW,GAAG;AACtB,UAAE,eAAe;AACjB,kBAAU,MAAM;AAChB;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,CAAC;AACrB,YAAM,OAAO,MAAM,MAAM,SAAS,CAAC;AACnC,YAAM,WAAW,SAAS;AAC1B,UAAI,EAAE,aAAa,aAAa,SAAS,aAAa,YAAY;AAChE,UAAE,eAAe;AACjB,aAAK,MAAM;AAAA,MACb,WAAW,CAAC,EAAE,YAAY,aAAa,MAAM;AAC3C,UAAE,eAAe;AACjB,cAAM,MAAM;AAAA,MACd;AAAA,IACF;AAKA,cAAU,iBAAiB,WAAW,SAAS;AAE/C,WAAO,MAAM;AACX,gBAAU,oBAAoB,WAAW,SAAS;AAClD,gBAAU,gBAAgB,SAAS;AAEnC,UAAI,CAAC,QAAQ,QAAQ,aAAc;AAKnC,UAAI,mBAAmB,YAAa,mBAAkB,QAAQ;AAAA,IAChE;AAAA,EACF,GAAG,CAAC,QAAQ,YAAY,CAAC;AAC3B;","names":[]}
+{"version":3,"sources":["../../src/hooks/use-focus-trap.ts"],"sourcesContent":["import { useEffect, useLayoutEffect, useRef, useState } from \"react\";\n\n/**\n * Keep keyboard focus inside an open overlay, and give it back when it closes.\n *\n * Extracted from `Modal`, which was the ONLY component in this package that did any of\n * this. Every other overlay — the full-bleed dialog a phone's row editor opens, the\n * picker sheet, the numpad, the tour card — declared `role=\"dialog\" aria-modal=\"true\"`\n * and then left focus on the page behind it. That is the worst of the two possible\n * bugs: assistive technology hides the page because of `aria-modal`, while the user's\n * focus is still down there in the part that is now hidden, so Tab walks through\n * controls the screen reader refuses to describe.\n *\n * What this does beyond Modal's original copy:\n *\n *   - **Recomputes the tabbable list on every Tab**, not once when the overlay opens.\n *     These panels have conditionally-rendered contents — a search box that appears\n *     once options load, a \"clear\" button that exists only while a filter is set — and\n *     a list captured at open time traps focus against elements that have since gone.\n *   - **Guards the restore target.** The element focused before opening may have left\n *     the DOM by the time the overlay closes (the row that owned the button was\n *     filtered away). Calling `.focus()` on a detached node silently drops focus to\n *     `<body>`, which for a keyboard user means losing their place in the page\n *     entirely. When the target is gone, focus falls back to the nearest thing that\n *     still exists rather than to nothing.\n *   - **Leaves an app's own autofocus alone** (0.33.1). React honours a child's\n *     `autoFocus` while it commits, and this hook's effect runs AFTER that commit, so\n *     focusing the container there took focus straight back off the field the app had\n *     asked for. See `initialFocus`.\n *   - **Nests.** An overlay can open another — a picker inside a dialog. Only the\n *     innermost trap handles a keystroke, and closing it hands control back to the one\n *     underneath. Innermost is decided by DOM containment rather than by mount order;\n *     see the note on `TRAP_ATTR` for why the obvious stack is wrong.\n *     `use-overlay-history.ts` reasons about the same nesting problem for the back\n *     button; this is the focus half of it.\n */\n\n/**\n * Candidate tab stops, in DOM order — narrowed by {@link isTabStop} to the ones a Tab\n * really reaches.\n *\n * The selector is the one `Modal` used. On its own it was not enough (round 0.34\n * BUG-4): only the bare `[tabindex]` clause excluded `-1`, so a `button`, an `input` or\n * a link taken out of the tab order still counted. A panel that ends in a roving grid —\n * the calendar's days, the month grid, the picker sheet's rows, every one of them `-1`\n * but the active cell — then had a \"last\" stop no Tab ever reaches: Tab from the real\n * last stop was not wrapped and walked out of the open panel, and Shift+Tab from the\n * first landed on a cell that is not a stop at all.\n */\nconst FOCUSABLE =\n  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\n\n/**\n * A stop the browser's own Tab would land on: in the tab order (`tabIndex` ≥ 0) and not\n * inside something `hidden` or `inert`. Removes only elements a native Tab never\n * reaches, so no correct order changes. `visibility: hidden` and closed `<details>` are\n * still not walked — they need layout, which this list has never read.\n */\nconst isTabStop = (el: HTMLElement): boolean =>\n  el.tabIndex >= 0 && !el.closest(\"[hidden],[inert]\");\n\n/**\n * Marks a container whose trap is currently active.\n *\n * \"Which trap is innermost?\" is answered by DOM CONTAINMENT, not by mount order. The\n * obvious implementation — a module-level stack pushed in the effect — is wrong, and\n * wrong in a way that passes a casual reading: React runs CHILD effects before PARENT\n * effects, so a nested overlay pushes first and the outer one ends up on top of the\n * stack, claiming to be innermost. The outer trap then handles the keystroke and wraps\n * focus to its own first element, jumping the user out of the picker they had open.\n *\n * An attribute on the live DOM cannot disagree with the DOM.\n */\nconst TRAP_ATTR = \"data-focus-trap\";\n\nexport interface FocusTrapOptions {\n  /** Trap only while this is true. Mount-time `true` is the common case. */\n  active?: boolean;\n  /** Return focus to whatever had it before the trap engaged. Default `true`. */\n  restoreFocus?: boolean;\n  /**\n   * What to focus when the trap engages. Default is the container itself, which is\n   * what `Modal` does and why: focusing the first FIELD pops the software keyboard on\n   * a phone the moment a dialog opens, before the user has asked to type.\n   * The container needs `tabIndex={-1}` for this to work.\n   *\n   * `\"container\"` and `\"first\"` both step aside when focus is ALREADY inside the\n   * container, on something other than the container itself. That is a child the app\n   * focused on purpose — an `autoFocus`, which React honours before this hook's effect\n   * runs — and the keyboard it brings up is the one the user was promised. Moving focus\n   * off it lost keksdose's create card its amount field the instant it got it, and on a\n   * phone the numpad sheet with it, which shows only while the field is focused (live\n   * #402). A function is the caller's explicit choice and is always followed.\n   */\n  initialFocus?: \"container\" | \"first\" | (() => HTMLElement | null);\n}\n\n/** Whatever has focus right now; nothing on the server, where there is no document. */\nfunction focusedElement(): Element | null {\n  return typeof document === \"undefined\" ? null : document.activeElement;\n}\n\nexport function useFocusTrap(\n  containerRef: React.RefObject<HTMLElement | null>,\n  { active = true, restoreFocus = true, initialFocus = \"container\" }: FocusTrapOptions = {},\n): void {\n  // Latest-ref so a caller passing an inline `initialFocus` thunk — which every caller\n  // will — does not tear the trap down and re-engage it on each render, stealing focus\n  // back to the top of the panel mid-interaction. Written in a LAYOUT effect so that\n  // the trap's cleanup, which runs after the layout effects of the same commit, reads\n  // this render's `active` rather than the last one's — see the cleanup for why.\n  const optsRef = useRef({ active, restoreFocus, initialFocus });\n  useLayoutEffect(() => {\n    optsRef.current = { active, restoreFocus, initialFocus };\n  });\n\n  // Where focus was BEFORE the trap engaged: the element it is given back to on close.\n  //\n  // Read DURING the render that turns the trap on, and that timing is the point. React\n  // honours a child's `autoFocus` while it commits that render, before any effect runs,\n  // so the effect below asking `document.activeElement` would get the child, inside the\n  // overlay. Restoring to that on close aimed focus at the dialog that was closing —\n  // already out of the DOM, so focus fell to <body> rather than going back to the\n  // button that opened it.\n  //\n  // State adjusted during render (the pattern `Modal` uses for `open`) rather than a\n  // ref written there: set once per opening and cleared on release, so a re-render\n  // while open cannot replace it with something inside, and StrictMode's second render\n  // and second effect both see the same element. `undefined` means \"not captured\";\n  // `null` is a capture that found nothing.\n  const [opener, setOpener] = useState<Element | null | undefined>(undefined);\n  if (active && opener === undefined) setOpener(focusedElement());\n  else if (!active && opener !== undefined) setOpener(undefined);\n\n  useEffect(() => {\n    if (!active) return;\n    const container = containerRef.current;\n    if (!container) return;\n\n    container.setAttribute(TRAP_ATTR, \"\");\n\n    /** Is `node` inside a trap nested within this one? */\n    const inNestedTrap = (node: Element | null) => {\n      if (!node) return false;\n      const owner = node.closest(`[${TRAP_ATTR}]`);\n      return owner !== null && owner !== container;\n    };\n\n    const tabbables = () =>\n      Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(\n        // A tabbable inside a NESTED open overlay belongs to that overlay's trap, not\n        // to this one — otherwise the outer list spans both panels and Tab from the\n        // inner panel's last control wraps to the OUTER panel's first.\n        (el) => isTabStop(el) && !inNestedTrap(el),\n      );\n\n    const { initialFocus: how } = optsRef.current;\n    const focused = document.activeElement;\n    // A child that already has focus was given it on purpose — see `initialFocus`.\n    const childHasFocus = focused !== container && container.contains(focused);\n    if (typeof how === \"function\") {\n      (how() ?? container).focus();\n    } else if (!childHasFocus) {\n      (how === \"first\" ? (tabbables()[0] ?? container) : container).focus();\n    }\n\n    const onKeyDown = (e: KeyboardEvent) => {\n      if (e.key !== \"Tab\") return;\n      // Only the innermost trap acts. The event bubbles through every ancestor\n      // container, so without this an outer dialog and an inner picker both handle one\n      // Tab and fight over where focus lands.\n      if (inNestedTrap(document.activeElement)) return;\n\n      // Recomputed per keystroke — see the note at the top of this file.\n      const items = tabbables();\n      if (items.length === 0) {\n        e.preventDefault();\n        container.focus();\n        return;\n      }\n      const first = items[0];\n      const last = items[items.length - 1];\n      const activeEl = document.activeElement;\n      if (e.shiftKey && (activeEl === first || activeEl === container)) {\n        e.preventDefault();\n        last.focus();\n      } else if (!e.shiftKey && activeEl === last) {\n        e.preventDefault();\n        first.focus();\n      }\n    };\n\n    // On the container, not the document: a portalled child panel (an open dropdown\n    // rendered to <body>) is outside this subtree and manages its own focus, which is\n    // the behaviour Modal's comment describes and consumers already depend on.\n    container.addEventListener(\"keydown\", onKeyDown);\n\n    return () => {\n      container.removeEventListener(\"keydown\", onKeyDown);\n      container.removeAttribute(TRAP_ATTR);\n\n      // Only when the trap is really being released: the container has left the page,\n      // or `active` has turned false. StrictMode runs this cleanup once more right after\n      // mounting, with the overlay still up, and then the effect again — and React does\n      // not re-apply `autoFocus` for that second run. Restoring here would pull focus\n      // out of the autofocused field for good: live #402 again, in development.\n      if (container.isConnected && optsRef.current.active) return;\n      if (!optsRef.current.restoreFocus) return;\n      // `isConnected` is the whole point: restoring to a node that has been removed\n      // sends focus to <body> and the user loses their place entirely. When the\n      // original is gone, leave focus where the browser put it rather than moving it\n      // somewhere arbitrary — a wrong guess is worse than no move.\n      if (opener?.isConnected) (opener as HTMLElement).focus?.();\n    };\n  }, [active, containerRef, opener]);\n}\n"],"mappings":";AAAA,SAAS,WAAW,iBAAiB,QAAQ,gBAAgB;AAiD7D,MAAM,YACJ;AAQF,MAAM,YAAY,CAAC,OACjB,GAAG,YAAY,KAAK,CAAC,GAAG,QAAQ,kBAAkB;AAcpD,MAAM,YAAY;AAyBlB,SAAS,iBAAiC;AACxC,SAAO,OAAO,aAAa,cAAc,OAAO,SAAS;AAC3D;AAEO,SAAS,aACd,cACA,EAAE,SAAS,MAAM,eAAe,MAAM,eAAe,YAAY,IAAsB,CAAC,GAClF;AAMN,QAAM,UAAU,OAAO,EAAE,QAAQ,cAAc,aAAa,CAAC;AAC7D,kBAAgB,MAAM;AACpB,YAAQ,UAAU,EAAE,QAAQ,cAAc,aAAa;AAAA,EACzD,CAAC;AAgBD,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAqC,MAAS;AAC1E,MAAI,UAAU,WAAW,OAAW,WAAU,eAAe,CAAC;AAAA,WACrD,CAAC,UAAU,WAAW,OAAW,WAAU,MAAS;AAE7D,YAAU,MAAM;AACd,QAAI,CAAC,OAAQ;AACb,UAAM,YAAY,aAAa;AAC/B,QAAI,CAAC,UAAW;AAEhB,cAAU,aAAa,WAAW,EAAE;AAGpC,UAAM,eAAe,CAAC,SAAyB;AAC7C,UAAI,CAAC,KAAM,QAAO;AAClB,YAAM,QAAQ,KAAK,QAAQ,IAAI,SAAS,GAAG;AAC3C,aAAO,UAAU,QAAQ,UAAU;AAAA,IACrC;AAEA,UAAM,YAAY,MAChB,MAAM,KAAK,UAAU,iBAA8B,SAAS,CAAC,EAAE;AAAA;AAAA;AAAA;AAAA,MAI7D,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE;AAAA,IAC3C;AAEF,UAAM,EAAE,cAAc,IAAI,IAAI,QAAQ;AACtC,UAAM,UAAU,SAAS;AAEzB,UAAM,gBAAgB,YAAY,aAAa,UAAU,SAAS,OAAO;AACzE,QAAI,OAAO,QAAQ,YAAY;AAC7B,OAAC,IAAI,KAAK,WAAW,MAAM;AAAA,IAC7B,WAAW,CAAC,eAAe;AACzB,OAAC,QAAQ,UAAW,UAAU,EAAE,CAAC,KAAK,YAAa,WAAW,MAAM;AAAA,IACtE;AAEA,UAAM,YAAY,CAAC,MAAqB;AACtC,UAAI,EAAE,QAAQ,MAAO;AAIrB,UAAI,aAAa,SAAS,aAAa,EAAG;AAG1C,YAAM,QAAQ,UAAU;AACxB,UAAI,MAAM,WAAW,GAAG;AACtB,UAAE,eAAe;AACjB,kBAAU,MAAM;AAChB;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,CAAC;AACrB,YAAM,OAAO,MAAM,MAAM,SAAS,CAAC;AACnC,YAAM,WAAW,SAAS;AAC1B,UAAI,EAAE,aAAa,aAAa,SAAS,aAAa,YAAY;AAChE,UAAE,eAAe;AACjB,aAAK,MAAM;AAAA,MACb,WAAW,CAAC,EAAE,YAAY,aAAa,MAAM;AAC3C,UAAE,eAAe;AACjB,cAAM,MAAM;AAAA,MACd;AAAA,IACF;AAKA,cAAU,iBAAiB,WAAW,SAAS;AAE/C,WAAO,MAAM;AACX,gBAAU,oBAAoB,WAAW,SAAS;AAClD,gBAAU,gBAAgB,SAAS;AAOnC,UAAI,UAAU,eAAe,QAAQ,QAAQ,OAAQ;AACrD,UAAI,CAAC,QAAQ,QAAQ,aAAc;AAKnC,UAAI,QAAQ,YAAa,CAAC,OAAuB,QAAQ;AAAA,IAC3D;AAAA,EACF,GAAG,CAAC,QAAQ,cAAc,MAAM,CAAC;AACnC;","names":[]}

package/dist/hooks/use-hotkey.d.ts

@@ -8,8 +8,8 @@
  * `KeyboardEvent.code` ("KeyF", "Digit1") when the physical key is what matters.
  * Several combos: pass an array.
  */
-type Hotkey = string;
-interface UseHotkeyOptions {
+export type Hotkey = string;
+export interface UseHotkeyOptions {
     /** Off while `false` (default `true`). */
     enabled?: boolean;
     /** Call `preventDefault()` on a match (default `true`): Ctrl+Shift+F must not also
@@ -28,7 +28,7 @@ interface UseHotkeyOptions {
     /** `keydown` (default) or `keyup`. */
     event?: "keydown" | "keyup";
 }
-interface ParsedHotkey {
+export interface ParsedHotkey {
     ctrl: boolean;
     meta: boolean;
     shift: boolean;
@@ -36,11 +36,11 @@ interface ParsedHotkey {
     key: string;
 }
 /** Whether this is an Apple platform, where `Mod` means Cmd. */
-declare function isApplePlatform(): boolean;
+export declare function isApplePlatform(): boolean;
 /** Parse one combo. `apple` decides what `Mod` is. Throws on an empty key. */
-declare function parseHotkey(combo: Hotkey, apple?: boolean): ParsedHotkey;
+export declare function parseHotkey(combo: Hotkey, apple?: boolean): ParsedHotkey;
 /** Whether `e` is `combo` — every modifier as named (no more, no fewer), and the key. */
-declare function matchesHotkey(e: KeyboardEvent, combo: ParsedHotkey): boolean;
+export declare function matchesHotkey(e: KeyboardEvent, combo: ParsedHotkey): boolean;
 /**
  * Call `handler` when `combo` is pressed — kastlan's feedback button (Ctrl+Shift+F,
  * feedback-button:60) wired it by hand, and so will every next shortcut.
@@ -54,6 +54,4 @@ declare function matchesHotkey(e: KeyboardEvent, combo: ParsedHotkey): boolean;
  *
  * `useCommandKey` (the ⌘K palette hook) is unchanged; this is its general form.
  */
-declare function useHotkey(combo: Hotkey | ReadonlyArray<Hotkey>, handler: (event: KeyboardEvent) => void, options?: UseHotkeyOptions): void;
-
-export { type Hotkey, type ParsedHotkey, type UseHotkeyOptions, isApplePlatform, matchesHotkey, parseHotkey, useHotkey };
+export declare function useHotkey(combo: Hotkey | ReadonlyArray<Hotkey>, handler: (event: KeyboardEvent) => void, options?: UseHotkeyOptions): void;

package/dist/hooks/use-large-text.d.ts

@@ -9,13 +9,13 @@
  */
 /** Large or Extra large is in force (`<html data-text-size>`) — the JS twin of the
  *  `large:` variant. */
-declare function useLargeText(): boolean;
+export declare function useLargeText(): boolean;
 /**
  * The primary pointer is a finger (`pointer: coarse`): a hover never happens, so a
  * tooltip opens only on the taps that do nothing else. A pointer query, so it stays
  * `useMediaQuery` (§10.4). `false` without `matchMedia` (SSR, jsdom).
  */
-declare function useCoarsePointer(): boolean;
+export declare function useCoarsePointer(): boolean;
 /**
  * Whether a fact may NOT live only in a tooltip here (§4 "No fact only in a tooltip"):
  * at Large and Extra large, where the reader is the one who asked for bigger type, and
@@ -24,6 +24,4 @@ declare function useCoarsePointer(): boolean;
  * control, a FieldHint as the field's caption, a StatTile hint as text — and keeps the
  * bubble only where there is no room (a top bar, a dense row's inline actions).
  */
-declare function useInlineFacts(): boolean;
-
-export { useCoarsePointer, useInlineFacts, useLargeText };
+export declare function useInlineFacts(): boolean;

package/dist/hooks/use-media-query.d.ts

@@ -3,6 +3,4 @@
  * re-rendering when it changes. `fallback` is the value used during SSR / when
  * `window.matchMedia` is unavailable.
  */
-declare function useMediaQuery(query: string, fallback: boolean): boolean;
-
-export { useMediaQuery };
+export declare function useMediaQuery(query: string, fallback: boolean): boolean;

package/dist/hooks/use-noindex.d.ts

@@ -21,6 +21,4 @@
  * preview inside another page (the showcase), where the host page's indexing is not its
  * business. Hooks cannot be called conditionally, so the switch is an argument.
  */
-declare function useNoIndex(active?: boolean): void;
-
-export { useNoIndex };
+export declare function useNoIndex(active?: boolean): void;

package/dist/hooks/use-overlay-history.d.ts

@@ -5,6 +5,4 @@
  *                  only while open (the common case) pass `true`.
  * @param onClose   the overlay's own close handler — the same one Escape calls.
  */
-declare function useOverlayHistory(open: boolean, onClose: () => void): void;
-
-export { useOverlayHistory };
+export declare function useOverlayHistory(open: boolean, onClose: () => void): void;

package/dist/hooks/use-row-swipe.d.ts

@@ -1,17 +1,16 @@
-import { PointerEvent } from 'react';
-
-interface SwipeStage {
+import type { PointerEvent } from "react";
+export interface SwipeStage {
     /** Drag magnitude (px) at which this stage arms. Stages must be sorted ascending. */
     threshold: number;
     onCommit: () => void;
 }
-interface RowSwipeOptions {
+export interface RowSwipeOptions {
     enabled: boolean;
     leftStages?: SwipeStage[];
     rightStages?: SwipeStage[];
     maxDrag?: number;
 }
-interface RowSwipeReturn {
+export interface RowSwipeReturn {
     dx: number;
     dragging: boolean;
     /** Highest armed stage index for the current drag (-1 when none armed). */
@@ -25,6 +24,4 @@ interface RowSwipeReturn {
     };
     consumeClick: () => boolean;
 }
-declare function useRowSwipe({ enabled, leftStages, rightStages, maxDrag, }: RowSwipeOptions): RowSwipeReturn;
-
-export { type RowSwipeOptions, type RowSwipeReturn, type SwipeStage, useRowSwipe };
+export declare function useRowSwipe({ enabled, leftStages, rightStages, maxDrag, }: RowSwipeOptions): RowSwipeReturn;

package/dist/hooks/use-search-param-state.d.ts

@@ -1,5 +1,5 @@
 type Updater<T> = T | ((prev: T) => T);
-interface SearchParamStateOptions<T> {
+export interface SearchParamStateOptions<T> {
     /**
      * The value of a param that IS present. Return `undefined` (or throw) for a value
      * that does not parse — a hand-edited or stale link — and the default is used.
@@ -52,21 +52,21 @@ interface SearchParamStateOptions<T> {
  *
  * Requires a react-router Router.
  */
-declare function useSearchParamState<T = string>(key: string, defaultValue: T, options?: SearchParamStateOptions<T>): [T, (next: Updater<T>) => void];
+export declare function useSearchParamState<T = string>(key: string, defaultValue: T, options?: SearchParamStateOptions<T>): [T, (next: Updater<T>) => void];
 /** One field of {@link useSearchParamsState}: its default, and the single hook's options. */
-interface SearchParamField<T> extends SearchParamStateOptions<T> {
+export interface SearchParamField<T> extends SearchParamStateOptions<T> {
     /** The value when the param is absent or does not parse; writing it removes the param. */
     default: T;
     /** The param's name in the URL. Default: the field's name (`namespace: { param: "ns" }`). */
     param?: string;
 }
 /** The fields of {@link useSearchParamsState}, one per key of the value object. */
-type SearchParamFields<V> = {
+export type SearchParamFields<V> = {
     [K in keyof V]: SearchParamField<V[K]>;
 };
 /** A partial value (fields left out — or `undefined` — stay as they are), or a function
  *  of the current value returning one. */
-type SearchParamsUpdate<V> = Partial<V> | ((prev: V) => Partial<V>);
+export type SearchParamsUpdate<V> = Partial<V> | ((prev: V) => Partial<V>);
 /**
  * Several URL search params as ONE state object, with one setter that writes them in
  * one navigation:
@@ -95,7 +95,7 @@ type SearchParamsUpdate<V> = Partial<V> | ((prev: V) => Partial<V>);
  * The value object keeps its identity while its params do not change, so it can sit in
  * a dependency array. Requires a react-router Router.
  */
-declare function useSearchParamsState<V extends object>(fields: SearchParamFields<V>): [V, (next: SearchParamsUpdate<V>) => void];
+export declare function useSearchParamsState<V extends object>(fields: SearchParamFields<V>): [V, (next: SearchParamsUpdate<V>) => void];
 /**
  * The active tab in `?tab=` (or `key`), with the default tab as the clean URL, for the
  * kit's `Tabs`:
@@ -108,13 +108,13 @@ declare function useSearchParamsState<V extends object>(fields: SearchParamField
  * renamed tab, an old link) into the default rather than into a blank panel.
  * kastlan's use-tab-param.ts, with the validation it did not have.
  */
-declare function useTabParam<T extends string>(defaultTab: T, options?: {
+export declare function useTabParam<T extends string>(defaultTab: T, options?: {
     key?: string;
     tabs?: readonly T[];
 }): [T, (tab: T) => void];
 /** Where a dialog's open state lives: a param's presence (`"edit"` → `?edit=1`), or one
  *  value of a shared param (`{ key: "dialog", value: "create-lease" }`). */
-type DialogParam = string | {
+export type DialogParam = string | {
     key: string;
     value: string;
 };
@@ -133,6 +133,5 @@ type DialogParam = string | {
  * leaves the history as it was before the dialog, and only the opener knows whether it
  * may.
  */
-declare function useDialogParam(param: DialogParam): [boolean, (open: boolean) => void];
-
-export { type DialogParam, type SearchParamField, type SearchParamFields, type SearchParamStateOptions, type SearchParamsUpdate, useDialogParam, useSearchParamState, useSearchParamsState, useTabParam };
+export declare function useDialogParam(param: DialogParam): [boolean, (open: boolean) => void];
+export {};

package/dist/hooks/use-windowed-rows.d.ts

@@ -1,11 +1,10 @@
-import { RefObject } from 'react';
-
+import type { RefObject } from "react";
 /** The attribute a measured row carries so {@link WindowedRows.measureRef} knows which
  *  row it is looking at: `data-row-index={index}`. */
-declare const WINDOWED_ROW_INDEX = "data-row-index";
+export declare const WINDOWED_ROW_INDEX = "data-row-index";
 /** What {@link useWindowedRows} answers: render rows `first` up to (not including)
  *  `last`, inside a scroll body `totalHeight` pixels tall. */
-interface WindowedRows {
+export interface WindowedRows {
     first: number;
     last: number;
     totalHeight: number;
@@ -68,6 +67,4 @@ interface WindowedRows {
  * rows of different heights — two copies of this would be two places to fix the day
  * the overscan turns out to be wrong.
  */
-declare function useWindowedRows(count: number, rowHeight: number, scrollRef: RefObject<HTMLElement | null>): WindowedRows;
-
-export { WINDOWED_ROW_INDEX, type WindowedRows, useWindowedRows };
+export declare function useWindowedRows(count: number, rowHeight: number, scrollRef: RefObject<HTMLElement | null>): WindowedRows;