@eifi1/ui-kit 0.6.1 → 0.7.1

package/src/components/dialog-frame.tsx

@@ -42,6 +42,15 @@ export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "child
    * calling `onClose` directly unmounts it at once.
    */
   actions?: ReactNode | ((close: () => void) => ReactNode);
+  /**
+   * Controls that belong to the HEADER rather than to the actions row — an "Edit"
+   * toggle, a status badge with a menu, a "Copy link" (kastlan). Rendered beside the
+   * title, before the optional X; on a phone, where title and controls do not fit on
+   * one line, they wrap under the title and the X keeps its corner.
+   *
+   * A function receives the animated close, as `actions` does.
+   */
+  headerActions?: ReactNode | ((close: () => void) => ReactNode);
   /**
    * Show an X in the header. Off by default: a centred dialog has a backdrop and
    * Escape, and a form dialog has a Cancel. On for a dialog that commits as it goes
@@ -52,8 +61,24 @@ export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "child
   closeLabel?: string;
   /** Extra classes for the scrolling body (default spacing `space-y-3`). */
   bodyClassName?: string;
-  /** The body. */
-  children: ReactNode;
+  /**
+   * Extra classes for the header row (default padding `px-4 pt-4 pb-3`), merged last —
+   * `px-3` for a phone sheet whose body runs at `px-3`, so heading and fields share
+   * one gutter.
+   */
+  headerClassName?: string;
+  /**
+   * A rule under the header, the twin of the one over the actions row — for a tall or
+   * full-screen body that scrolls under a header which stays. The body then starts a
+   * step below the rule instead of flush against it.
+   */
+  headerDivider?: boolean;
+  /**
+   * The body. Optional: a dialog whose title, description and actions are the whole
+   * of it (a "you have unsynced changes" question) leaves it out, and the frame then
+   * renders no body at all rather than an empty padded one.
+   */
+  children?: ReactNode;
 }
 
 /**
@@ -92,9 +117,12 @@ export function DialogFrame({
   description,
   headingAs: Heading = "h2",
   actions,
+  headerActions,
   closeButton = false,
   closeLabel,
   bodyClassName,
+  headerClassName,
+  headerDivider = false,
   className,
   children,
   "aria-describedby": describedBy,
@@ -103,6 +131,8 @@ export function DialogFrame({
   const titleId = useId();
   const descriptionId = useId();
   const hasDescription = description !== undefined && description !== null;
+  // `false` too, so `{cond && <Body/>}` with a false `cond` means "no body".
+  const hasBody = children !== undefined && children !== null && children !== false;
 
   return (
     <Modal
@@ -116,30 +146,50 @@ export function DialogFrame({
       // to the body, which is the only part that should move.
       className={cn("flex flex-col overflow-hidden p-0", className)}
     >
-      <div className="flex shrink-0 items-start justify-between gap-2 px-4 pt-4 pb-3">
-        <div className="min-w-0">
-          <Heading id={titleId} className="text-lg font-semibold leading-snug text-[var(--text-primary)]">
-            {title}
-          </Heading>
-          {hasDescription && (
-            <p id={descriptionId} className="mt-0.5 text-sm text-[var(--text-muted)]">
-              {description}
-            </p>
-          )}
-        </div>
-        {closeButton && <FrameClose label={closeLabel} onClose={modal.onClose} />}
-      </div>
       <div
         className={cn(
-          // `min-h-0` is what lets a flex child shrink below its content and scroll;
-          // `last:pb-4` closes a frame that has no actions row under it.
-          "min-h-0 flex-1 space-y-3 overflow-y-auto overscroll-contain px-4 pb-3 last:pb-4",
-          bodyClassName,
+          // `last:pb-4`: a frame with neither body nor actions closes on its header.
+          "flex shrink-0 items-start justify-between gap-2 px-4 pt-4 pb-3 last:pb-4",
+          headerDivider && "border-b border-[var(--border)]",
+          headerClassName,
         )}
       >
-        {children}
+        {/* Title and header actions share a wrapping row of their own, so it is THEY
+            that wrap on a phone — the actions drop under a title that needs its 12rem —
+            while the X stays outside it, pinned to the top-end corner. */}
+        <div className="flex min-w-0 flex-1 flex-wrap items-start justify-between gap-x-3 gap-y-2">
+          <div className="min-w-0 grow basis-48">
+            <Heading id={titleId} className="text-lg font-semibold leading-snug text-[var(--text-primary)]">
+              {title}
+            </Heading>
+            {hasDescription && (
+              <p id={descriptionId} className="mt-0.5 text-sm text-[var(--text-muted)]">
+                {description}
+              </p>
+            )}
+          </div>
+          {headerActions !== undefined && headerActions !== null && headerActions !== false && (
+            <FrameHeaderActions actions={headerActions} onClose={modal.onClose} />
+          )}
+        </div>
+        {closeButton && <FrameClose label={closeLabel} onClose={modal.onClose} />}
       </div>
-      {actions !== undefined && actions !== null && <FrameActions actions={actions} onClose={modal.onClose} />}
+      {hasBody && (
+        <div
+          className={cn(
+            // `min-h-0` is what lets a flex child shrink below its content and scroll;
+            // `last:pb-4` closes a frame that has no actions row under it.
+            "min-h-0 flex-1 space-y-3 overflow-y-auto overscroll-contain px-4 pb-3 last:pb-4",
+            headerDivider && "pt-3",
+            bodyClassName,
+          )}
+        >
+          {children}
+        </div>
+      )}
+      {actions !== undefined && actions !== null && (
+        <FrameActions actions={actions} onClose={modal.onClose} divider={hasBody} />
+      )}
     </Modal>
   );
 }
@@ -161,18 +211,43 @@ function FrameClose({ label, onClose }: { label?: string; onClose: () => void })
   );
 }
 
+/** The header's own controls; a component for the same reason as {@link FrameClose}. */
+function FrameHeaderActions({
+  actions,
+  onClose,
+}: {
+  actions: NonNullable<DialogFrameProps["headerActions"]>;
+  onClose: () => void;
+}) {
+  const close = useContext(ModalCloseContext) ?? onClose;
+  return (
+    <div data-dialog-header-actions="" className="flex shrink-0 flex-wrap items-center gap-2">
+      {typeof actions === "function" ? actions(close) : actions}
+    </div>
+  );
+}
+
 function FrameActions({
   actions,
   onClose,
+  divider,
 }: {
   actions: NonNullable<DialogFrameProps["actions"]>;
   onClose: () => void;
+  /** Off when there is no body: nothing scrolls, so there is no edge to mark, and a
+   *  rule straight under the description would cut the question from its answers. */
+  divider: boolean;
 }) {
   const close = useContext(ModalCloseContext) ?? onClose;
   return (
     // The border marks where the scrolling stops; `flex-wrap` keeps three long
     // translated labels on a phone from pushing the row wider than the sheet.
-    <div className="flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-[var(--border)] px-4 py-3">
+    <div
+      className={cn(
+        "flex shrink-0 flex-wrap items-center justify-end gap-2 px-4 py-3",
+        divider && "border-t border-[var(--border)]",
+      )}
+    >
       {typeof actions === "function" ? actions(close) : actions}
     </div>
   );

package/src/components/disclosure.tsx

@@ -149,7 +149,27 @@ export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "
   headerClassName?: string;
   /** Extra classes for the body's wrapper — where its padding and spacing live. */
   bodyClassName?: string;
-  children: ReactNode;
+  /**
+   * Content at the far end of the header row, beside the title: a count, a date, a
+   * status chip, an action button. It is a SIBLING of the header button, never inside
+   * it — a button may not contain another interactive element, and a count inside it
+   * would also be read as part of the button's name. The header button still spans
+   * the row under it (a stretched hit area), so clicking the empty space or the
+   * card's chevron still toggles, while whatever sits in `trailing` gets its own
+   * clicks. With `trailing`, the card's chevron moves after it, to the row's end.
+   */
+  trailing?: ReactNode;
+  /**
+   * Trigger-only mode: the id of an element the CALLER renders elsewhere — the hidden
+   * rows of a table, a panel in another column — which this header shows and hides.
+   * The header's `aria-controls` points at it and the disclosure renders no body of
+   * its own (`children`, `bodyClassName` and `keepMounted` are ignored). Pair it with
+   * `open` / `onOpenChange`: the caller owns the state, since the caller renders what
+   * it governs.
+   */
+  controls?: string;
+  /** The body. Not rendered in trigger-only mode ({@link DisclosureProps.controls}). */
+  children?: ReactNode;
 }
 
 /**
@@ -178,6 +198,8 @@ export function Disclosure({
   disabled,
   headerClassName,
   bodyClassName,
+  trailing,
+  controls,
   className,
   children,
   ...rest
@@ -186,6 +208,10 @@ export function Disclosure({
   const open = controlled ?? own;
   const bodyId = useId();
   const card = variant === "card";
+  const triggerOnly = controls !== undefined;
+  // The card's header squares its lower corners only when a body opens under it.
+  const joined = open && !triggerOnly;
+  const hasTrailing = trailing !== undefined && trailing !== null && trailing !== false;
 
   const toggle = () => {
     const next = !open;
@@ -197,43 +223,79 @@ export function Disclosure({
     <button
       type="button"
       aria-expanded={open}
-      aria-controls={bodyId}
+      aria-controls={triggerOnly ? controls : bodyId}
       disabled={disabled}
       onClick={toggle}
+      data-disclosure-trigger=""
       className={cn(
         "flex w-full gap-2 text-start outline-none disabled:cursor-not-allowed disabled:opacity-50",
-        "focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+        hasTrailing
+          ? // Stretched over the whole header row (the row is `relative`), so the space
+            // round `trailing` and the card's chevron still toggle; the ring and the
+            // card's hover paint on the stretched area / the row, not the text box.
+            cn(
+              "min-w-0 flex-1 after:absolute after:inset-0 after:content-['']",
+              "focus-visible:after:ring-2 focus-visible:after:ring-inset focus-visible:after:ring-[var(--brand)]",
+              card ? cn("after:rounded-lg", joined && "after:rounded-b-none") : "after:rounded-sm",
+            )
+          : "focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
         card
           ? cn(
-              "items-center justify-between rounded-lg p-4 hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
-              open && "rounded-b-none",
+              "items-center justify-between rounded-lg p-4",
+              hasTrailing ? "pe-0" : "hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
+              joined && "rounded-b-none",
             )
           : "items-center rounded-sm text-sm font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]",
         headerClassName,
       )}
     >
       {!card && <Chevron open={open} leading />}
-      <span className="min-w-0">
+      {/* `flex-1`: the title takes the row, so whatever a caller puts at its end sits
+          at the header's far edge. */}
+      <span className="min-w-0 flex-1">
         <span className={cn("block", card && "text-sm font-semibold text-[var(--text-primary)]")}>{title}</span>
         {hint !== undefined && (
           <span className="mt-0.5 block text-xs font-normal text-[var(--text-muted)]">{hint}</span>
         )}
       </span>
-      {card && <Chevron open={open} />}
+      {card && !hasTrailing && <Chevron open={open} />}
     </button>
   );
 
+  // Preflight already makes h1–h6 inherit size and weight, so the heading adds
+  // structure and nothing visible.
+  const header = Heading ? <Heading className={hasTrailing ? "min-w-0 flex-1" : undefined}>{button}</Heading> : button;
+
   return (
     <div
       {...rest}
       className={cn(card && "rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] shadow-sm", className)}
     >
-      {/* Preflight already makes h1–h6 inherit size and weight, so the heading adds
-          structure and nothing visible. */}
-      {Heading ? <Heading>{button}</Heading> : button}
-      <Collapse id={bodyId} open={open} keepMounted={keepMounted}>
-        <div className={cn(card ? "space-y-3 px-4 pb-4" : "space-y-2 pt-2", bodyClassName)}>{children}</div>
-      </Collapse>
+      {hasTrailing ? (
+        <div
+          className={cn(
+            "relative flex items-center gap-2",
+            card &&
+              cn(
+                "rounded-lg pe-4 has-[[data-disclosure-trigger]:enabled:hover]:bg-[var(--bg-hover)]",
+                joined && "rounded-b-none",
+              ),
+          )}
+        >
+          {header}
+          {/* Positioned, so it paints over the stretched button and takes its own
+              clicks; the chevron is not, so a click on it lands on the button. */}
+          <div className="relative flex shrink-0 items-center gap-2">{trailing}</div>
+          {card && <Chevron open={open} />}
+        </div>
+      ) : (
+        header
+      )}
+      {!triggerOnly && (
+        <Collapse id={bodyId} open={open} keepMounted={keepMounted}>
+          <div className={cn(card ? "space-y-3 px-4 pb-4" : "space-y-2 pt-2", bodyClassName)}>{children}</div>
+        </Collapse>
+      )}
     </div>
   );
 }

package/src/components/dropdown.tsx

@@ -11,6 +11,7 @@ import { useAnchoredPanel } from "../hooks/use-anchored-panel";
 import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { cn } from "../lib/cn";
+import { useAnchorDir } from "./use-anchor-dir";
 
 /**
  * Open state + close-on-outside-click for the custom dropdowns (MultiSelect,
@@ -225,8 +226,12 @@ export interface DropdownPanelProps extends ComponentPropsWithoutRef<"div"> {
   panelRef?: RefObject<HTMLDivElement | null>;
   /** Panel width in px, for the anchored form (the CSS `w-*` cannot be measured). */
   width?: number;
-  /** Which of the panel's edges lines up with the trigger's, room permitting. */
-  align?: "left" | "right";
+  /** Which of the panel's edges lines up with the trigger's, room permitting.
+   *  `start`/`end` follow the trigger's reading direction — `end` is the right edge
+   *  in a left-to-right form and the left one in a right-to-left form — and are what
+   *  the kit's own pickers pass; `left`/`right` stay physical. Default `end`, which
+   *  is the old `right` in a left-to-right page. */
+  align?: "left" | "right" | "start" | "end";
   children: ReactNode;
 }
 
@@ -239,7 +244,7 @@ export interface DropdownPanelProps extends ComponentPropsWithoutRef<"div"> {
  *
  * Without `anchorRef` the panel is `position: absolute` inside whatever relative box
  * the caller put it in, and the caller places it with `className` (`w-64`,
- * `right-0 top-full`). That is fine in a page that does not scroll around it, and
+ * `end-0 top-full`). That is fine in a page that does not scroll around it, and
  * wrong the moment an ancestor has `overflow` — the panel is then CLIPPED by that
  * ancestor's box, with no error and no scrollbar, just a list with its side sliced
  * off. Keksdose dev#548 is what that looks like in practice: the app's own content
@@ -266,12 +271,13 @@ export function DropdownPanel({
   anchorRef,
   panelRef,
   width = 256,
-  align = "right",
+  align = "end",
   children,
   style,
   ...rest
 }: DropdownPanelProps) {
   const anchored = useAnchoredPanel(anchorRef ?? EMPTY_REF, Boolean(anchorRef));
+  const dir = useAnchorDir(anchorRef ?? EMPTY_REF, Boolean(anchorRef));
   const body = (
     <>
       {header}
@@ -313,12 +319,18 @@ export function DropdownPanel({
   if (!rect) return null;
   // Clamped exactly as `Popover` clamps: the panel may leave the trigger's edge to
   // stay on screen, because a list half off the viewport is the bug this exists for.
-  const wanted = align === "right" ? rect.right - width : rect.left;
+  // The portal leaves the subtree the trigger's `dir` came from, so it is read off
+  // the trigger — for the alignment here, and for the panel's own `dir` below,
+  // without which a right-to-left form got a left-to-right list.
+  const physical =
+    align === "start" ? (dir === "rtl" ? "right" : "left") : align === "end" ? (dir === "rtl" ? "left" : "right") : align;
+  const wanted = physical === "right" ? rect.right - width : rect.left;
   const left = Math.min(Math.max(8, wanted), window.innerWidth - width - 8);
   return createPortal(
     <div
       {...rest}
       ref={panelRef}
+      dir={dir}
       // The caller's `style` is kept underneath, but the placement is measured rather
       // than chosen (dev#548: an `overflow` ancestor clipped a third of this panel
       // away), so those five values are the panel's own.

package/src/components/entity-combobox.tsx

@@ -7,20 +7,30 @@ import {
   ComboboxPanel,
   useComboboxCore,
   useComboboxFieldError,
+  type ComboClearValue,
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 
-export type { ComboOption } from "./combobox-core";
+export type { ComboClearValue, ComboOption } from "./combobox-core";
 
 /** `onChange` is the kit's — "a selection was made", carrying values — rather
  *  than the div's form event, so the DOM's spelling of it is omitted. */
-export interface EntityComboboxProps<V extends string | number>
+export interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>
   extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
-  /** Selected id, or null/undefined when nothing is selected. */
-  value: V | null | undefined;
-  /** Selecting an option emits its value; the clear button emits `null`. */
-  onChange: (value: V | null) => void;
+  /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */
+  value: V | C | null | undefined;
+  /** Selecting an option emits its value; the clear button emits `clearValue`. */
+  onChange: (value: V | C) => void;
+  /**
+   * What the clear button emits. Default `null`. Pass `""` for a form whose schema
+   * wants an empty string for "no choice" (a zod `z.string()` field), rather than
+   * mapping `null` in every `onChange` — the type of `onChange` follows it, so the
+   * mapping cannot be forgotten on one field and not another. The picker also reads
+   * the value back as empty, so `value=""` shows the placeholder and no "×".
+   * See {@link ComboClearValue} for why the choice is closed.
+   */
+  clearValue?: C;
   /** Already-loaded options (client-side filtered). Also used to resolve the
    *  trigger label for the current `value`. */
   options?: ComboOption<V>[];
@@ -70,9 +80,10 @@ export interface EntityComboboxProps<V extends string | number>
  * the shared field/anchor/dismiss/search primitives (no cmdk/Radix). For picking
  * several entities use {@link MultiEntityCombobox}.
  */
-export function EntityCombobox<V extends string | number>({
+export function EntityCombobox<V extends string | number, C extends ComboClearValue = null>({
   value,
   onChange,
+  clearValue = null as C,
   options,
   loadOptions,
   loading,
@@ -95,7 +106,7 @@ export function EntityCombobox<V extends string | number>({
   loadErrorLabel,
   "aria-label": ariaLabel,
   ...rest
-}: EntityComboboxProps<V>) {
+}: EntityComboboxProps<V, C>) {
   const core = useComboboxCore<V>({
     options,
     loadOptions,
@@ -120,11 +131,13 @@ export function EntityCombobox<V extends string | number>({
   // belongs to whoever renders both ends of it.
   const listboxId = useId();
 
-  const selectedOption = value == null ? null : resolve(value);
+  // The clear value is "nothing selected" too, whichever one the caller picked.
+  const chosen: V | null = value == null || value === clearValue ? null : (value as V);
+  const selectedOption = chosen == null ? null : resolve(chosen);
   const q = core.query.trim();
   const showCreate =
     Boolean(onCreate) && q.length > 0 && !results.some((o) => o.label.toLowerCase() === q.toLowerCase());
-  const showClear = Boolean(clearable && value != null && !disabled);
+  const showClear = Boolean(clearable && chosen != null && !disabled);
   /** What the closed control is showing — the second half of its accessible name. */
   const triggerText = selectedOption?.label ?? placeholder ?? "";
 
@@ -184,7 +197,7 @@ export function EntityCombobox<V extends string | number>({
         }}
         className={cn(
           FIELD_TRIGGER,
-          "pr-9",
+          "pe-9",
           label !== undefined && FIELD_FLOATING_PAD,
           disabled && "cursor-not-allowed opacity-50",
           field.isInvalid && FIELD_INVALID,
@@ -215,9 +228,9 @@ export function EntityCombobox<V extends string | number>({
             aria-label={labels.clear}
             onClick={(e) => {
               e.stopPropagation();
-              onChange(null);
+              onChange(clearValue);
             }}
-            className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+            className="absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
           >
             <X className="size-4" />
           </span>

package/src/components/file-button.tsx

@@ -36,8 +36,14 @@ import { Button, Spinner } from "./ui";
 /** Every string the file pickers ({@link FileButton}, `FileDropzone`) render or speak.
  *  Messages are functions of the file name so a translation can put it anywhere. */
 export interface FilePickerLabels {
-  /** The file's type is not in `accept`. */
+  /** The file's type is not in `accept`, when no `accept` is known to name (see
+   *  `rejectedTypeOnly`). */
   rejectedType: (name: string) => string;
+  /** The file's type is not in `accept`, naming what IS accepted: `accept`'s tokens,
+   *  lower-cased and joined with ", " (`".csv"` => "Only .csv files"). Used whenever
+   *  `accept` is set — kastlan kept a custom `isValid` + `invalidMessage` per form only
+   *  to say this, and `accept` already knows it. */
+  rejectedTypeOnly: (accept: string, name: string) => string;
   /** The file is larger than `maxSize`; `maxSize` arrives formatted ("5 MB"). */
   rejectedSize: (name: string, maxSize: string) => string;
   /** The file was one too many for `maxFiles`. */
@@ -46,6 +52,9 @@ export interface FilePickerLabels {
   rejectedInvalid: (name: string) => string;
   /** Spoken instead of the per-file message when more than one file was refused. */
   rejectedMany: (count: number) => string;
+  /** Spoken (and shown, on a dropzone) when `onPick` refused the WHOLE pick.
+   *  Receives the number of files in it. */
+  rejectedPick: (count: number) => string;
   /** Spoken after a pick the component itself echoes (the dropzone). */
   selected: (count: number, firstName: string) => string;
   /** The dropzone's remove button for one file. */
@@ -59,11 +68,14 @@ export interface FilePickerLabels {
 
 export const DEFAULT_FILE_PICKER_LABELS: FilePickerLabels = {
   rejectedType: (name) => `“${name}” is not a supported file type`,
+  rejectedTypeOnly: (accept) => `Only ${accept} files`,
   rejectedSize: (name, maxSize) => `“${name}” is larger than ${maxSize}`,
   rejectedCount: (name, maxFiles) =>
     `“${name}” was not added: at most ${maxFiles} ${maxFiles === 1 ? "file" : "files"}`,
   rejectedInvalid: (name) => `“${name}” cannot be used here`,
   rejectedMany: (count) => `${count} files were not added`,
+  rejectedPick: (count) =>
+    count === 1 ? "The file was not added" : `None of the ${count} files were added`,
   selected: (count, firstName) => (count === 1 ? `“${firstName}” selected` : `${count} files selected`),
   remove: (name) => `Remove “${name}”`,
   clearAll: "Remove all files",
@@ -136,6 +148,15 @@ function typeFromExtension(name: string): string | undefined {
   return dot === -1 ? undefined : EXTENSION_TYPES[name.slice(dot + 1)];
 }
 
+/** `" .PDF, image/png ,"` => `".pdf, image/png"` — `accept` as a person reads it. */
+function formatAccept(accept: string): string {
+  return accept
+    .split(",")
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean)
+    .join(", ");
+}
+
 /** What the pickers screen a pick with. All optional; nothing set accepts everything. */
 export interface FileScreenOptions {
   accept?: string;
@@ -160,6 +181,15 @@ export function screenFiles(
 ): { accepted: File[]; rejected: FileRejection[] } {
   const accepted: File[] = [];
   const rejected: FileRejection[] = [];
+  // Name what `accept` takes ("Only .csv files") — unless the host translated
+  // `rejectedType` but not yet `rejectedTypeOnly`: its own sentence beats an English one.
+  const acceptText = opts.accept ? formatAccept(opts.accept) : "";
+  const useOnly =
+    acceptText !== "" &&
+    (labels.rejectedTypeOnly !== DEFAULT_FILE_PICKER_LABELS.rejectedTypeOnly ||
+      labels.rejectedType === DEFAULT_FILE_PICKER_LABELS.rejectedType);
+  const typeMessage = (name: string) =>
+    useOnly ? labels.rejectedTypeOnly(acceptText, name) : labels.rejectedType(name);
   for (const file of files) {
     let reason: FileRejectionReason | null = null;
     if (!matchesAccept(file, opts.accept)) reason = "type";
@@ -174,7 +204,7 @@ export function screenFiles(
     }
     const message =
       reason === "type"
-        ? labels.rejectedType(file.name)
+        ? typeMessage(file.name)
         : reason === "size"
           ? labels.rejectedSize(file.name, formatSize(opts.maxSize ?? 0))
           : reason === "count"
@@ -185,6 +215,34 @@ export function screenFiles(
   return { accepted, rejected };
 }
 
+/**
+ * Judges a pick as a whole — keksdose's "refuse the pick if any file is bad", which
+ * with `onFiles` + `onReject` alone had to be rebuilt from two calls in a microtask.
+ *
+ * Called ONCE per pick, after screening and before `onFiles` / `onReject`, with both
+ * halves (either may be empty). Return `false` to refuse the whole pick: the accepted
+ * files are not delivered, `onReject` still receives what screening refused, and one
+ * sentence (`labels.rejectedPick`) is spoken for the pick instead of a per-file one.
+ * Return nothing to let the pick through as usual.
+ *
+ * ```tsx
+ * onPick={(ok, bad) => bad.length === 0 || false}  // all or nothing
+ * ```
+ */
+export type FilePickHandler = (accepted: File[], rejected: FileRejection[]) => boolean | void;
+
+/** @internal The shared tail of both pickers: run `onPick`, and say whether the pick
+ *  stands. A pick with nothing accepted has nothing to refuse, so `false` there is
+ *  treated as no verdict and the usual per-file messages are kept. */
+export function judgePick(
+  onPick: FilePickHandler | undefined,
+  accepted: File[],
+  rejected: FileRejection[],
+): boolean {
+  if (!onPick) return true;
+  return onPick(accepted, rejected) !== false || accepted.length === 0;
+}
+
 /** One sentence for a whole batch of refusals: the file's own message for one, a
  *  count for several — reading out five sentences in a row helps nobody. */
 export function summariseRejections(rejected: readonly FileRejection[], labels: FilePickerLabels): string {
@@ -205,8 +263,11 @@ export interface UseFilePickerOptions extends FileScreenOptions {
    * 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 passed, in pick order. Never called with an empty array.
+   *  Optional since 0.7 for a caller that takes the pick through `onPick` alone. */
+  onFiles?: (files: File[]) => void;
+  /** See {@link FilePickHandler}: the whole pick at once, with the power to refuse it. */
+  onPick?: FilePickHandler;
   /** The files that did not, with a translated message each. The refusals are also
    *  spoken through a live region, so this is for SHOWING them, not for a11y. */
   onReject?: (rejections: FileRejection[]) => void;
@@ -246,6 +307,7 @@ export function useFilePicker({
   isValid,
   invalidMessage,
   onFiles,
+  onPick,
   onReject,
   disabled,
   labels: labelsProp,
@@ -269,7 +331,12 @@ export function useFilePicker({
       labels,
       fileText.size,
     );
-    if (accepted.length > 0) onFiles(accepted);
+    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));
@@ -355,6 +422,7 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
     isValid,
     invalidMessage,
     onFiles,
+    onPick,
     onReject,
     labels,
     pending,
@@ -381,6 +449,7 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
     isValid,
     invalidMessage,
     onFiles,
+    onPick,
     onReject,
     labels,
     disabled: inert,