@eifi1/ui-kit 0.5.1 → 0.6.1

package/dist/components/file-button.d.ts

@@ -0,0 +1,161 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode, ReactElement } from 'react';
+import { Button } from './ui.js';
+
+/**
+ * A button that opens the file picker — the shape all three apps kept writing by hand
+ * as a `<Button>` plus a hidden `<input type="file">` plus a ref between them (seven
+ * copies in keksdose, two each in kastlan and lenkbank).
+ *
+ * Every copy had to remember the same four things, and each one forgot at least one:
+ *
+ *  1. **Reset the input after every pick.** A file input fires `change` only when its
+ *     value CHANGES, so picking the same file twice in a row — the retry after a failed
+ *     upload, the second photo of the same receipt — did nothing at all, which reads as
+ *     a broken button. `value = ""` after each pick; always, not per call site.
+ *  2. **`type="button"`.** `<Button>` does not set it, and inside a form a bare button
+ *     submits the form before the picker opens.
+ *  3. **Check the file.** `accept` filters the DIALOG, not the result: the dialog's
+ *     "All files" switch, a drop, and a mobile share sheet all hand over whatever the
+ *     user chose. So `accept` is re-checked here, along with `maxSize`, `maxFiles` and
+ *     an optional `isValid`.
+ *  4. **Say no without a toast.** A rejection is reported through `onReject`, with a
+ *     translated message per file, and spoken through a live region — the kit does not
+ *     decide how an app surfaces errors (keksdose's proposal §1 asked for exactly that).
+ *
+ * The part that is not a button — the hidden input, the check, the announcement — is
+ * {@link useFilePicker}, for the case where the thing that opens the picker is someone
+ * else's control (a card's "Add" action, a menu item, a second button for the camera).
+ */
+/** 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. */
+interface FilePickerLabels {
+    /** The file's type is not in `accept`. */
+    rejectedType: (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 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;
+}
+declare const DEFAULT_FILE_PICKER_LABELS: FilePickerLabels;
+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. */
+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.
+ */
+declare function matchesAccept(file: File, accept: string | undefined): boolean;
+/** What the pickers screen a pick with. All optional; nothing set accepts everything. */
+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. */
+declare function screenFiles(files: readonly File[], opts: FileScreenOptions, labels: FilePickerLabels, formatSize: (bytes: number) => string): {
+    accepted: File[];
+    rejected: FileRejection[];
+};
+/** 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. */
+declare function summariseRejections(rejected: readonly FileRejection[], labels: FilePickerLabels): string;
+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. */
+    onFiles: (files: File[]) => void;
+    /** 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?: Partial<FilePickerLabels>;
+}
+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} … /></>;
+ * ```
+ */
+declare function useFilePicker({ accept, multiple, capture, maxSize, maxFiles, isValid, invalidMessage, onFiles, onReject, disabled, labels: labelsProp, }: UseFilePickerOptions): UseFilePickerReturn;
+type ButtonOwnProps = ComponentPropsWithoutRef<typeof Button>;
+interface FileButtonProps extends Omit<UseFilePickerOptions, "disabled">, Omit<ButtonOwnProps, "type" | "children" | "accept" | "capture" | "multiple"> {
+    /** The button's content — usually an icon and a word. It is the accessible name. */
+    children: ReactNode;
+    /** Busy: disabled, `aria-busy`, and a spinner before the content — for "uploading". */
+    pending?: boolean;
+    /** Also accept files dropped ON the button (lenkbank's "drop onto the button").
+     *  Off by default: a button that silently takes drops is a surprise on a page that
+     *  has a real drop target elsewhere. */
+    droppable?: boolean;
+}
+/**
+ * {@link useFilePicker} behind a {@link Button}: `variant` and every other button prop
+ * pass through, and the ref is the `<button>` (so `ref.current.click()` opens the
+ * picker from elsewhere too).
+ *
+ * ```tsx
+ * <FileButton accept="image/*,application/pdf" capture="environment" variant="secondary"
+ *   maxSize={10_000_000} onFiles={([f]) => upload(f)} onReject={([r]) => setError(r.message)}>
+ *   <Camera aria-hidden /> Photograph receipt
+ * </FileButton>
+ * ```
+ */
+declare const FileButton: react.ForwardRefExoticComponent<FileButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+export { DEFAULT_FILE_PICKER_LABELS, FileButton, type FileButtonProps, type FilePickerLabels, type FileRejection, type FileRejectionReason, type FileScreenOptions, type UseFilePickerOptions, type UseFilePickerReturn, matchesAccept, screenFiles, summariseRejections, useFilePicker };

package/dist/components/file-button.js

@@ -0,0 +1,243 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { forwardRef, useRef, useState } from "react";
+import { cn } from "../lib/cn.js";
+import { useAnnounce } from "../hooks/use-announce.js";
+import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels.js";
+import { Button, Spinner } from "./ui.js";
+const DEFAULT_FILE_PICKER_LABELS = {
+  rejectedType: (name) => `\u201C${name}\u201D is not a supported file type`,
+  rejectedSize: (name, maxSize) => `\u201C${name}\u201D is larger than ${maxSize}`,
+  rejectedCount: (name, maxFiles) => `\u201C${name}\u201D was not added: at most ${maxFiles} ${maxFiles === 1 ? "file" : "files"}`,
+  rejectedInvalid: (name) => `\u201C${name}\u201D cannot be used here`,
+  rejectedMany: (count) => `${count} files were not added`,
+  selected: (count, firstName) => count === 1 ? `\u201C${firstName}\u201D selected` : `${count} files selected`,
+  remove: (name) => `Remove \u201C${name}\u201D`,
+  clearAll: "Remove all files",
+  removed: (name) => `\u201C${name}\u201D removed`,
+  cleared: "All files removed"
+};
+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 screenFiles(files, opts, labels, formatSize) {
+  const accepted = [];
+  const rejected = [];
+  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" ? labels.rejectedType(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 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,
+  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 (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
+  };
+}
+const FileButton = forwardRef(function FileButton2({
+  accept,
+  multiple,
+  capture,
+  maxSize,
+  maxFiles,
+  isValid,
+  invalidMessage,
+  onFiles,
+  onReject,
+  labels,
+  pending,
+  droppable,
+  disabled,
+  children,
+  className,
+  onClick,
+  onDragEnter,
+  onDragOver,
+  onDragLeave,
+  onDrop,
+  ...rest
+}, ref) {
+  const inert = Boolean(disabled || pending);
+  const picker = useFilePicker({
+    accept,
+    multiple,
+    capture,
+    maxSize,
+    maxFiles,
+    isValid,
+    invalidMessage,
+    onFiles,
+    onReject,
+    labels,
+    disabled: inert
+  });
+  const [dragOver, setDragOver] = useState(false);
+  const hasFiles = (e) => Array.from(e.dataTransfer?.types ?? []).includes("Files");
+  const dropHandlers = droppable ? {
+    onDragEnter: (e) => {
+      onDragEnter?.(e);
+      if (!hasFiles(e)) return;
+      e.preventDefault();
+      if (!inert) setDragOver(true);
+    },
+    onDragOver: (e) => {
+      onDragOver?.(e);
+      if (!hasFiles(e)) return;
+      e.preventDefault();
+      e.dataTransfer.dropEffect = inert ? "none" : "copy";
+    },
+    onDragLeave: (e) => {
+      onDragLeave?.(e);
+      if (e.currentTarget.contains(e.relatedTarget)) return;
+      setDragOver(false);
+    },
+    onDrop: (e) => {
+      onDrop?.(e);
+      if (!hasFiles(e)) return;
+      e.preventDefault();
+      setDragOver(false);
+      picker.take(e.dataTransfer.files);
+    }
+  } : { onDragEnter, onDragOver, onDragLeave, onDrop };
+  const refProp = { ref };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      Button,
+      {
+        ...rest,
+        ...refProp,
+        ...dropHandlers,
+        type: "button",
+        disabled: inert,
+        "aria-busy": pending || void 0,
+        "data-drag-over": dragOver || void 0,
+        className: cn(
+          // A live drag gets the focus ring's colour as a ring: "let go here", in the
+          // same vocabulary the button already uses for "you are here".
+          dragOver && "ring-2 ring-[var(--brand)]",
+          className
+        ),
+        onClick: (e) => {
+          onClick?.(e);
+          if (!e.defaultPrevented) picker.open();
+        },
+        children: [
+          pending && /* @__PURE__ */ jsx(Spinner, { label: null, className: "size-4" }),
+          children
+        ]
+      }
+    ),
+    picker.element
+  ] });
+});
+FileButton.displayName = "FileButton";
+export {
+  DEFAULT_FILE_PICKER_LABELS,
+  FileButton,
+  matchesAccept,
+  screenFiles,
+  summariseRejections,
+  useFilePicker
+};
+//# sourceMappingURL=file-button.js.map

package/dist/components/file-button.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/file-button.tsx"],"sourcesContent":["import { forwardRef, useRef, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, DragEvent, ReactElement, ReactNode, Ref } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { useAnnounce } from \"../hooks/use-announce\";\nimport { useKitFileLabels, useKitLabels } from \"../i18n/kit-labels\";\nimport { Button, Spinner } from \"./ui\";\n\n/**\n * A button that opens the file picker — the shape all three apps kept writing by hand\n * as a `<Button>` plus a hidden `<input type=\"file\">` plus a ref between them (seven\n * copies in keksdose, two each in kastlan and lenkbank).\n *\n * Every copy had to remember the same four things, and each one forgot at least one:\n *\n *  1. **Reset the input after every pick.** A file input fires `change` only when its\n *     value CHANGES, so picking the same file twice in a row — the retry after a failed\n *     upload, the second photo of the same receipt — did nothing at all, which reads as\n *     a broken button. `value = \"\"` after each pick; always, not per call site.\n *  2. **`type=\"button\"`.** `<Button>` does not set it, and inside a form a bare button\n *     submits the form before the picker opens.\n *  3. **Check the file.** `accept` filters the DIALOG, not the result: the dialog's\n *     \"All files\" switch, a drop, and a mobile share sheet all hand over whatever the\n *     user chose. So `accept` is re-checked here, along with `maxSize`, `maxFiles` and\n *     an optional `isValid`.\n *  4. **Say no without a toast.** A rejection is reported through `onReject`, with a\n *     translated message per file, and spoken through a live region — the kit does not\n *     decide how an app surfaces errors (keksdose's proposal §1 asked for exactly that).\n *\n * The part that is not a button — the hidden input, the check, the announcement — is\n * {@link useFilePicker}, for the case where the thing that opens the picker is someone\n * else's control (a card's \"Add\" action, a menu item, a second button for the camera).\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`. */\n  rejectedType: (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 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}\n\nexport const DEFAULT_FILE_PICKER_LABELS: FilePickerLabels = {\n  rejectedType: (name) => `“${name}” is not a supported file type`,\n  rejectedSize: (name, maxSize) => `“${name}” is larger than ${maxSize}`,\n  rejectedCount: (name, maxFiles) =>\n    `“${name}” was not added: at most ${maxFiles} ${maxFiles === 1 ? \"file\" : \"files\"}`,\n  rejectedInvalid: (name) => `“${name}” cannot be used here`,\n  rejectedMany: (count) => `${count} files were not added`,\n  selected: (count, firstName) => (count === 1 ? `“${firstName}” selected` : `${count} files selected`),\n  remove: (name) => `Remove “${name}”`,\n  clearAll: \"Remove all files\",\n  removed: (name) => `“${name}” removed`,\n  cleared: \"All files removed\",\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/** 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  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        ? labels.rejectedType(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/** 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  onFiles: (files: File[]) => void;\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?: Partial<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  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 (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\n/* ── FileButton ──────────────────────────────────────────────────────────── */\n\ntype ButtonOwnProps = ComponentPropsWithoutRef<typeof Button>;\n\nexport interface FileButtonProps\n  extends Omit<UseFilePickerOptions, \"disabled\">,\n    // `onDrop` & co. stay the caller's own when `droppable` is off; `type` is fixed to\n    // \"button\" (see 2. above) — a file trigger never submits a form.\n    Omit<ButtonOwnProps, \"type\" | \"children\" | \"accept\" | \"capture\" | \"multiple\"> {\n  /** The button's content — usually an icon and a word. It is the accessible name. */\n  children: ReactNode;\n  /** Busy: disabled, `aria-busy`, and a spinner before the content — for \"uploading\". */\n  pending?: boolean;\n  /** Also accept files dropped ON the button (lenkbank's \"drop onto the button\").\n   *  Off by default: a button that silently takes drops is a surprise on a page that\n   *  has a real drop target elsewhere. */\n  droppable?: boolean;\n}\n\n/**\n * {@link useFilePicker} behind a {@link Button}: `variant` and every other button prop\n * pass through, and the ref is the `<button>` (so `ref.current.click()` opens the\n * picker from elsewhere too).\n *\n * ```tsx\n * <FileButton accept=\"image/*,application/pdf\" capture=\"environment\" variant=\"secondary\"\n *   maxSize={10_000_000} onFiles={([f]) => upload(f)} onReject={([r]) => setError(r.message)}>\n *   <Camera aria-hidden /> Photograph receipt\n * </FileButton>\n * ```\n */\nexport const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(function FileButton(\n  {\n    accept,\n    multiple,\n    capture,\n    maxSize,\n    maxFiles,\n    isValid,\n    invalidMessage,\n    onFiles,\n    onReject,\n    labels,\n    pending,\n    droppable,\n    disabled,\n    children,\n    className,\n    onClick,\n    onDragEnter,\n    onDragOver,\n    onDragLeave,\n    onDrop,\n    ...rest\n  },\n  ref,\n) {\n  const inert = Boolean(disabled || pending);\n  const picker = useFilePicker({\n    accept,\n    multiple,\n    capture,\n    maxSize,\n    maxFiles,\n    isValid,\n    invalidMessage,\n    onFiles,\n    onReject,\n    labels,\n    disabled: inert,\n  });\n  const [dragOver, setDragOver] = useState(false);\n\n  const hasFiles = (e: DragEvent) => Array.from(e.dataTransfer?.types ?? []).includes(\"Files\");\n  // Only when `droppable`: otherwise the caller's own handlers are passed untouched.\n  const dropHandlers = droppable\n    ? {\n        onDragEnter: (e: DragEvent<HTMLButtonElement>) => {\n          onDragEnter?.(e);\n          if (!hasFiles(e)) return;\n          e.preventDefault();\n          if (!inert) setDragOver(true);\n        },\n        onDragOver: (e: DragEvent<HTMLButtonElement>) => {\n          onDragOver?.(e);\n          if (!hasFiles(e)) return;\n          // Always cancel for a file drag, busy or not: an uncancelled drop makes the\n          // browser NAVIGATE to the file, which loses the page.\n          e.preventDefault();\n          e.dataTransfer.dropEffect = inert ? \"none\" : \"copy\";\n        },\n        onDragLeave: (e: DragEvent<HTMLButtonElement>) => {\n          onDragLeave?.(e);\n          if (e.currentTarget.contains(e.relatedTarget as Node | null)) return;\n          setDragOver(false);\n        },\n        onDrop: (e: DragEvent<HTMLButtonElement>) => {\n          onDrop?.(e);\n          if (!hasFiles(e)) return;\n          e.preventDefault();\n          setDragOver(false);\n          picker.take(e.dataTransfer.files);\n        },\n      }\n    : { onDragEnter, onDragOver, onDragLeave, onDrop };\n\n  // `Button` is a plain function component; under React 19 `ref` is an ordinary prop\n  // and reaches the `<button>` through its `...rest`. Its props type just does not\n  // declare it, hence the widening here rather than a second button implementation.\n  const refProp = { ref } as { ref?: Ref<HTMLButtonElement> };\n\n  return (\n    <>\n      <Button\n        {...rest}\n        {...refProp}\n        {...dropHandlers}\n        type=\"button\"\n        disabled={inert}\n        aria-busy={pending || undefined}\n        data-drag-over={dragOver || undefined}\n        className={cn(\n          // A live drag gets the focus ring's colour as a ring: \"let go here\", in the\n          // same vocabulary the button already uses for \"you are here\".\n          dragOver && \"ring-2 ring-[var(--brand)]\",\n          className,\n        )}\n        onClick={(e) => {\n          onClick?.(e);\n          if (!e.defaultPrevented) picker.open();\n        }}\n      >\n        {/* `label={null}`: the spinner is decoration here — `aria-busy` says the same\n            thing on the button, and a spoken \"Loading\" would run into its name. */}\n        {pending && <Spinner label={null} className=\"size-4\" />}\n        {children}\n      </Button>\n      {picker.element}\n    </>\n  );\n});\nFileButton.displayName = \"FileButton\";\n"],"mappings":"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","names":["FileButton"]}

package/dist/components/file-dropzone.d.ts

@@ -1,6 +1,20 @@
 import * as react from 'react';
 import { ComponentPropsWithoutRef } from 'react';
+import { FileRejection, FilePickerLabels } from './file-button.js';
+import './ui.js';
 
+/**
+ * Where a refused file's message goes.
+ *
+ *  - `"toast"` — a `sonner` toast (the 0.5 behaviour, kept as the default for a caller
+ *    that handles nothing itself so no existing dropzone goes quiet on upgrade).
+ *  - `"inline"` — under the drop target, in the danger colour, tied to it with
+ *    `aria-describedby` (plus `data-invalid` for styling), and spoken through a live
+ *    region. Cleared by the next accepted pick.
+ *  - `"none"` — nothing visible; the caller shows it from `onReject` / `onInvalid`.
+ *    Still spoken, so a host rendering it should not ALSO make it `role="alert"`.
+ */
+type FileDropzoneRejectionFeedback = "toast" | "inline" | "none";
 /**
  * `onInvalid` is omitted from the `<div>` attributes and kept as this component's own.
  * The DOM event of that name belongs to form validation and takes a `FormEvent`; this
@@ -8,30 +22,64 @@ import { ComponentPropsWithoutRef } from 'react';
  * writes. Everything else a `<div>` takes reaches the root — which carries
  * `role="button"`, so that is also where an `aria-label` or an `aria-describedby`
  * belongs.
+ *
+ * Two modes. SINGLE (the default, and all of 0.5): `file` + `onFileSelected`. MULTIPLE
+ * (`multiple`): `files` + `onFilesSelected`. They are optional rather than a union so
+ * `FileDropzoneProps` stays an interface a caller can extend; a single-mode pick also
+ * reaches `onFilesSelected` as a one-element array, so one handler can serve both.
  */
 interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">, "onInvalid"> {
-    file: File | null;
-    onFileSelected: (file: File) => void;
+    /** Single mode: the chosen file, echoed with its size. */
+    file?: File | null;
+    /** Single mode: called with the accepted file. */
+    onFileSelected?: (file: File) => void;
+    /** Take several files per pick or drop. Without it a drop of several keeps the first. */
+    multiple?: boolean;
+    /** Multiple mode: the chosen files, listed in the zone. */
+    files?: readonly File[];
+    /** Every accepted file of one pick, in order. Never called with an empty array. */
+    onFilesSelected?: (files: File[]) => void;
+    /**
+     * Show a remove button inside the zone once something is chosen (kastlan asked for
+     * it: the only way to un-choose a file was to reload). Single mode: removes the file.
+     * Multiple mode: a "remove all" button. The host clears its own state here — the
+     * zone is controlled. Focus returns to the zone, and the removal is announced.
+     */
+    onClear?: () => void;
+    /** Multiple mode: a remove button per listed file. */
+    onRemove?: (file: File, index: number) => void;
     accept: string;
-    isValid: (file: File) => boolean;
-    invalidMessage: string;
     /**
-     * How to surface {@link invalidMessage}. Defaults to a `sonner` toast — an
-     * optional peer, imported only when a file is actually rejected. Pass your own to
-     * route it somewhere else, or a no-op to silence it. The same escape hatch, for
-     * the same reason, as `useWizard`'s `onValidationFailed`.
+     * The caller's check. Optional since 0.6: without it the zone checks `accept` itself
+     * (a drop ignores the dialog's filter). With it, `accept` is NOT re-checked — every
+     * 0.5 caller's `isValid` is its own type check, and doubling it could refuse a file
+     * the caller accepts (a `.zip` the OS labelled `application/octet-stream`).
+     */
+    isValid?: (file: File) => boolean;
+    /** The message for an `isValid` refusal. Defaults to `labels.rejectedInvalid`. */
+    invalidMessage?: string;
+    /** Bytes; larger files are refused. */
+    maxSize?: number;
+    /** Multiple mode: files one pick may add. Pass what is LEFT for a running cap. */
+    maxFiles?: number;
+    /**
+     * Called once per refused file. The 0.5 hook, kept as it was; {@link onReject}
+     * carries the reason and the translated message as well.
      *
-     * It exists so this module does not import `sonner` STATICALLY. `package.json`
-     * declares that peer `optional`, and the barrel re-exports this file — so a
-     * top-level `import { toast } from "sonner"` made the claim false for everybody:
-     * in an app that installed `@hb/ui` without sonner, `import { Button } from
-     * "@hb/ui"` failed to resolve and `tsc --noEmit` failed on the missing types,
-     * without a FileDropzone anywhere in it. Both current consumers happen to depend
-     * on sonner, which is why nothing broke and why the contradiction survived:
-     * `use-wizard.ts` had already answered the identical question the other way, in
-     * writing, two modules over.
+     * Its existence used to be what switched the toast off, and it still does (see
+     * {@link rejectionFeedback}). The toast is a dynamic `import("sonner")` on the
+     * failure path only: `sonner` is an OPTIONAL peer, and a static import here once
+     * broke `import { Button }` for every app without it (see
+     * `optional-peer-imports.test.tsx`).
      */
     onInvalid?: (file: File) => void;
+    /** Every refused file of one pick, with its reason and message. */
+    onReject?: (rejections: FileRejection[]) => void;
+    /** See {@link FileDropzoneRejectionFeedback}. Defaults to `"toast"` when neither
+     *  `onInvalid` nor `onReject` is given, `"none"` when one is. */
+    rejectionFeedback?: FileDropzoneRejectionFeedback;
+    /** Per-instance overrides of the `filePicker` label namespace. */
+    labels?: Partial<FilePickerLabels>;
     /** The dropzone's accessible name, and the instruction shown on it. A caller's own
      *  `aria-label` wins over it — see the root element below. */
     dropLabel: string;
@@ -41,10 +89,11 @@ interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">, "onInv
     /** Extra classes for the dropzone's root. */
     className?: string;
 }
-/** Drag-and-drop file picker shared by the import wizards (YNAB zip, CAMT xml).
- * Validation failures surface `invalidMessage` (a `sonner` toast by default, see
- * `onInvalid`); the chosen file is echoed with its size, otherwise `emptyLabel` +
- * `hint` describe what to drop. */
-declare function FileDropzone({ file, onFileSelected, accept, isValid, invalidMessage, onInvalid, dropLabel, browseLabel, emptyLabel, hint, className, "aria-label": ariaLabel, ...rest }: FileDropzoneProps): react.JSX.Element;
+/** Drag-and-drop file picker shared by the import wizards (YNAB zip, CAMT xml) and
+ * kastlan's document forms. Refusals go to `onReject`/`onInvalid` and to
+ * `rejectionFeedback`; the chosen file(s) are echoed with their size, otherwise
+ * `emptyLabel` + `hint` describe what to drop. For a trigger with no drop area, see
+ * `FileButton`. */
+declare function FileDropzone({ file, onFileSelected, multiple, files, onFilesSelected, onClear, onRemove, accept, isValid, invalidMessage, maxSize, maxFiles, onInvalid, onReject, rejectionFeedback, labels: labelsProp, dropLabel, browseLabel, emptyLabel, hint, className, "aria-label": ariaLabel, "aria-describedby": describedByProp, ...rest }: FileDropzoneProps): react.JSX.Element;
 
-export { FileDropzone, type FileDropzoneProps };
+export { FileDropzone, type FileDropzoneProps, type FileDropzoneRejectionFeedback };