@eifi1/ui-kit 0.22.0 → 0.24.0

package/src/feedback/feedback-attachment.tsx

@@ -1,7 +1,18 @@
 import { cn } from "../lib/cn";
-import { useEffect, useLayoutEffect, useRef, useState, type ClipboardEvent as ReactClipboardEvent, type RefObject } from "react";
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ClipboardEvent as ReactClipboardEvent,
+  type ReactNode,
+  type RefObject,
+} from "react";
 import { Camera, FileText, Image as ImageIcon, Paperclip, X } from "lucide-react";
-import { Button, Spinner } from "../components/ui";
+import { Button, IconButton, Spinner } from "../components/ui";
+import type { ButtonSize, ButtonVariant } from "../components/ui";
+import { DEFAULT_FILE_PICKER_LABELS, formatAccept } from "../components/file-button";
+import { useCommitReason } from "../components/write-lock";
 import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels";
 import type { FeedbackAttachmentLabels } from "./feedback-dialog";
 
@@ -47,6 +58,11 @@ export interface FeedbackAttachmentFieldLabels {
    *  running, where an uploaded one shows its size — "Uploading…". Optional, like the
    *  keys above, so a `UiKitLabels` typed before it still compiles. */
   attachmentUploading?: string;
+  /** `refs` mode (0.23.0, keksdose G5a): {@link FeedbackAttachmentErrorInfo.message} for
+   *  an `"upload"` refusal — "“huge.png” could not be uploaded". The other refusals'
+   *  sentences are the `filePicker` namespace's, shared with FileButton. Optional, like
+   *  the keys above. */
+  attachmentUploadFailed?: (name: string) => string;
 }
 
 export const DEFAULT_FEEDBACK_ATTACHMENT_LABELS: FeedbackAttachmentFieldLabels = {
@@ -60,6 +76,7 @@ export const DEFAULT_FEEDBACK_ATTACHMENT_LABELS: FeedbackAttachmentFieldLabels =
   attachmentLimit: (max) =>
     `Up to ${max} ${max === 1 ? "attachment" : "attachments"} — remove one to add another.`,
   attachmentUploading: "Uploading…",
+  attachmentUploadFailed: (name) => `“${name}” could not be uploaded`,
 };
 
 /** Why a file was turned away. `"count"` only ever comes from `multiple` (and `refs`)
@@ -72,6 +89,58 @@ export type FeedbackAttachmentError = "type" | "size" | "count";
  *  own so a host's exhaustive switch over the File modes' reasons stays exhaustive. */
 export type FeedbackAttachmentRefsError = FeedbackAttachmentError | "upload";
 
+/**
+ * What `onError` knows about a refusal beyond its kind (0.23.0, keksdose G5a): the file
+ * it was about, the limit that refused it, and a sentence that says both.
+ *
+ * keksdose's support chat toasted "File too large" with no name — the field's `onError`
+ * carried a kind and nothing else, so a refusal could not say WHICH of three pasted
+ * screenshots went, nor what the ceiling was, and its own `AttachmentPicker` (a
+ * FileButton, whose `onReject` hands over `{ file, message }`) said more than the kit's
+ * field would have. This is that, for every mode.
+ *
+ * It arrives as an EXTRA argument, after the ones `onError` already had, so a handler
+ * written for 0.22 — `(kind) => …`, or `refs` mode's `(kind, error) => …` — compiles
+ * and behaves as before:
+ *
+ * - single and `multiple`: `onError(kind, info)`;
+ * - `refs`: `onError(kind, error, info)` — the second place is `onUpload`'s rejection
+ *   since 0.22 (`undefined` for the other kinds, as it always was), so the info comes
+ *   third rather than changing what a 0.22 handler reads there. It also carries that
+ *   `error`, so one helper `(kind, info) => …` serves all three modes.
+ *
+ * An object rather than more positional arguments because what a host reaches for
+ * differs by kind — the bytes for `"size"`, `max` for `"count"`, the server's answer for
+ * `"upload"` — and a field added later must not shift anyone's arguments.
+ */
+export interface FeedbackAttachmentErrorInfo {
+  /** The file refused — under the name the field would have given it (a pasted image
+   *  is already "pasted.png"). For `"count"`, the first of the surplus; for
+   *  `"upload"`, the file whose upload failed. */
+  file: File;
+  /** `"count"`: every file of the surplus (several can arrive in one pick). Otherwise
+   *  `[file]`. */
+  files: File[];
+  /**
+   * One translated sentence naming the file and the limit — the ones FileButton's
+   * `onReject` hands over, from the same `filePicker` namespace: "“huge.png” is larger
+   * than 10 MB", "Only image/png, image/jpeg files", "“c.png” was not added: at most 5
+   * files" (several at once: "3 files were not added"). `"upload"`: the field's own
+   * `attachmentUploadFailed`, "“huge.png” could not be uploaded" — a host with a better
+   * sentence from the server's answer uses `error`. Ready for a toast as it is.
+   */
+  message: string;
+  /** The field's `maxBytes` — the ceiling a `"size"` refusal went over, in bytes. */
+  maxBytes: number;
+  /** The field's `accept` — the types a `"type"` refusal was not among. */
+  accept: string[];
+  /** The field's `max` — the ceiling a `"count"` refusal hit. Absent in single mode,
+   *  which holds one file by definition. */
+  max?: number;
+  /** `"upload"` only: what `onUpload` rejected with — `onError`'s second argument. */
+  error?: unknown;
+}
+
 /**
  * One uploaded attachment in `refs` mode: what the host's upload answered with. `key`
  * identifies it (a storage key, an upload id) and is what a remove goes by; `name` is
@@ -88,9 +157,25 @@ export interface FeedbackAttachmentRef {
 interface FeedbackAttachmentFieldBaseProps {
   /** Prop > `<UiKitProvider labels={{ feedbackAttachment }}>` > English. Optional
    *  since 0.7.0; `attachment` (the heading) is only ever read from here. */
-  labels?: Partial<FeedbackAttachmentLabels> & Pick<Partial<FeedbackAttachmentFieldLabels>, "attachmentUploading">;
+  labels?: Partial<FeedbackAttachmentLabels> &
+    Pick<Partial<FeedbackAttachmentFieldLabels>, "attachmentUploading" | "attachmentUploadFailed">;
   accept?: string[];
   maxBytes?: number;
+  /**
+   * Take no files for now (0.23.0, keksdose G5b): the add and capture buttons, the
+   * hidden file input and every chip's remove button are natively disabled, and a paste
+   * is let through untouched. The chips stay as they are — what is about to be sent
+   * stays readable.
+   *
+   * For the moment a send is in flight. keksdose's support picker is `disabled` while
+   * the message goes out, because the message carries the attachments AS THEY WERE at
+   * the press: a chip removed mid-send has gone with it all the same, and one added
+   * mid-send looks as if it had. The field has no drop target; the paste is its drop.
+   *
+   * This is a pause, not a lock that explains itself — for that, `refs` mode (the mode
+   * that commits) takes `commit` and `disabledReason`.
+   */
+  disabled?: boolean;
   /** Snapshot the app view behind this and return it as a File. A "Capture
    *  screenshot" button appears only when it is given. */
   onCaptureScreenshot?: () => Promise<File | null>;
@@ -102,20 +187,56 @@ interface FeedbackAttachmentFieldBaseProps {
    *  in, whose common parent is where the event bubbles to. Ignored when
    *  `documentPaste` is set. */
   pasteFrom?: RefObject<HTMLElement | null>;
+  /**
+   * The add and capture buttons' look (0.24.0, keksdose) — Button's own `variant`.
+   * Default `"secondary"`, the look they always had.
+   *
+   * keksdose's support chat puts this field in ChatComposer's `attachmentSlot`, in the
+   * row with Send, where its own picker had been a `ghost` / `sm` FileButton: two
+   * bordered full-size buttons under a chat box read as a second form, and the field
+   * gave no way to say otherwise. Every mode, wherever the buttons appear; the chips'
+   * remove buttons keep their size.
+   */
+  buttonVariant?: ButtonVariant;
+  /** The add and capture buttons' size — Button's own `size`, with `buttonVariant`.
+   *  Default `"md"`. `"sm"` draws their icons at 14px, as a small button's are. */
+  buttonSize?: ButtonSize;
   className?: string;
 }
 
+/**
+ * The field's root, in every mode. `relative` for the `sr-only` file input (see the
+ * single field). `min-w-0 max-w-full` (0.24.0, keksdose) because the field is often a
+ * FLEX ITEM — ChatComposer's `attachmentSlot` row, FormActions' `start` — and a flex item
+ * is never narrower than its content's min-content width unless told it may be. A chip
+ * truncates its name only inside a box of bounded width, and a screenshot's name
+ * ("Screenshot 2026-10-03 at 07.45.12.png") was the min-content: the field grew to it
+ * and ran off a 390px phone composer (measured in Chromium: the field's right edge at
+ * 592px, the page 614px wide). keksdose passed `className="min-w-0 max-w-full"` at both
+ * its callers to stop it; here once, for every host. In normal flow — a dialog, a note
+ * editor — both are no-ops.
+ */
+const FIELD_ROOT = "relative min-w-0 max-w-full";
+
+/** Paperclip and camera at the size the button's text is: 16px at `md`, 14px at `sm`. */
+const buttonIcon = (size: ButtonSize) => (size === "sm" ? "size-3.5" : "size-4");
+
 /** One file: choosing a second means removing the first. The field's only mode until 0.15.5. */
 export interface FeedbackAttachmentFieldSingleProps extends FeedbackAttachmentFieldBaseProps {
   multiple?: false;
   refs?: false;
   value: File | null;
   onChange: (file: File | null) => void;
-  onError?: (kind: "type" | "size") => void;
+  /** A file was refused. `info` (0.23.0) names it and the limit — see
+   *  {@link FeedbackAttachmentErrorInfo}. */
+  onError?: (kind: "type" | "size", info: FeedbackAttachmentErrorInfo) => void;
   // Multiple-mode props, refused here: without `multiple` they would be silently ignored.
   max?: never;
   screenshot?: never;
   onScreenshotChange?: never;
+  // `refs` mode's lock: a staged File is not a commit (see the refs props).
+  commit?: never;
+  disabledReason?: never;
 }
 
 /**
@@ -131,8 +252,10 @@ export interface FeedbackAttachmentFieldMultipleProps extends FeedbackAttachment
   /** How many files `value` may hold. Default {@link DEFAULT_MAX_ATTACHMENTS} (5). The
    *  add buttons and the paste hint are offered only while there is room. */
   max?: number;
-  /** Per file: a rejected one is reported and the others are still added. */
-  onError?: (kind: FeedbackAttachmentError) => void;
+  /** Per file: a rejected one is reported and the others are still added. `"count"` is
+   *  once per pick, with the whole surplus in `info.files`. `info` (0.23.0): see
+   *  {@link FeedbackAttachmentErrorInfo}. */
+  onError?: (kind: FeedbackAttachmentError, info: FeedbackAttachmentErrorInfo) => void;
   /**
    * A separate slot for THE screenshot, outside `value` and `max`. Given
    * `onScreenshotChange`, what `onCaptureScreenshot` returns lands here instead of in
@@ -143,6 +266,9 @@ export interface FeedbackAttachmentFieldMultipleProps extends FeedbackAttachment
    */
   screenshot?: File | null;
   onScreenshotChange?: (file: File | null) => void;
+  // `refs` mode's lock: a staged File is not a commit (see the refs props).
+  commit?: never;
+  disabledReason?: never;
 }
 
 /**
@@ -180,8 +306,28 @@ export interface FeedbackAttachmentFieldRefsProps extends FeedbackAttachmentFiel
   /** How many refs `value` may hold, uploads in flight included. Default
    *  {@link DEFAULT_MAX_ATTACHMENTS} (5). */
   max?: number;
-  /** Per file. `"upload"` carries what `onUpload` rejected with. */
-  onError?: (kind: FeedbackAttachmentRefsError, error?: unknown) => void;
+  /** Per file. `"upload"` carries what `onUpload` rejected with as `error` (`undefined`
+   *  for the other kinds). `info` (0.23.0) comes third so a 0.22 handler's `error` is
+   *  still the second argument — see {@link FeedbackAttachmentErrorInfo}. */
+  onError?: (kind: FeedbackAttachmentRefsError, error: unknown, info: FeedbackAttachmentErrorInfo) => void;
+  /**
+   * This field COMMITS (0.23.0): each file is uploaded the moment it is chosen, and a
+   * remove may delete the upload (`onRemove`) — a save, unlike the File modes, which
+   * only stage a file for a form sent later (and so stay open under a lock, like every
+   * field). Under a locked {@link WriteLockProvider} it takes the `disabledReason` path
+   * with the lock's reason, which wins over one of its own. No provider, or an unlocked
+   * one: no effect.
+   */
+  commit?: boolean;
+  /**
+   * Why no file can be added or removed — the write lock's sentence, a quota, a thread
+   * closed to replies. Unlike `disabled`, it SAYS so, the kit's commit-control way: the
+   * buttons (add, capture, every chip's remove) stay focusable, `aria-disabled`, with
+   * the reason in the kit Tooltip and their description; no pick, paste or remove gets
+   * through; and the reason stands where the paste hint was, for a phone that never
+   * hovers. The chips stay readable.
+   */
+  disabledReason?: ReactNode;
   screenshot?: never;
   onScreenshotChange?: never;
 }
@@ -239,6 +385,9 @@ function SingleField({
   onCaptureScreenshot,
   documentPaste = false,
   pasteFrom,
+  disabled = false,
+  buttonVariant = "secondary",
+  buttonSize = "md",
   className,
 }: FeedbackAttachmentFieldSingleProps) {
   // The object URL is keyed to the file it was made for, so a stale one (from the
@@ -249,6 +398,7 @@ function SingleField({
   // `file.size` from `<UiKitProvider labels>`, formatted in its locale — see FileDropzone.
   const fileText = useKitFileLabels();
   const text = useKitLabels("feedbackAttachment", DEFAULT_FEEDBACK_ATTACHMENT_LABELS, labelsProp);
+  const errorInfo = useErrorInfo(accept, maxBytes, undefined, text);
 
   // Object-URL preview lifecycle (create on change, revoke on cleanup).
   useEffect(() => {
@@ -266,7 +416,7 @@ function SingleField({
     if (!file) return;
     const problem = rejection(file, accept, maxBytes);
     if (problem) {
-      onError?.(problem);
+      onError?.(problem, errorInfo(problem, [file]));
       return;
     }
     onChange(file);
@@ -282,6 +432,7 @@ function SingleField({
     },
     documentPaste,
     pasteFrom,
+    disabled,
   );
 
   return (
@@ -289,8 +440,9 @@ function SingleField({
       // `relative` for the same reason as FileDropzone: the `sr-only` file input below
       // is `position: absolute`, and without a positioned ancestor it is laid out
       // against the initial containing block — extending the DOCUMENT height to its own
-      // offset and producing a phantom second scrollbar on any long page.
-      className={cn("relative", className)}
+      // offset and producing a phantom second scrollbar on any long page. And
+      // `min-w-0 max-w-full`, so a long name truncates in a flex row: see FIELD_ROOT.
+      className={cn(FIELD_ROOT, className)}
       onPaste={onPaste}
     >
       <Heading text={labelsProp?.attachment} />
@@ -315,23 +467,29 @@ function SingleField({
               {fileText.size(value.size)}
             </div>
           </div>
-          <button
-            type="button"
-            onClick={() => onChange(null)}
-            aria-label={text.attachmentRemove}
-            className="rounded p-1.5 text-[var(--text-placeholder)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]"
-          >
-            <X className="size-4" />
-          </button>
+          <RemoveButton label={text.attachmentRemove} onClick={() => onChange(null)} disabled={disabled} />
         </div>
       ) : (
         <div className="space-y-1.5">
           <div className="flex flex-wrap gap-2">
-            <Button type="button" variant="secondary" onClick={() => fileInputRef.current?.click()}>
-              <Paperclip className="size-4" /> {text.attachmentAdd}
+            <Button
+              type="button"
+              variant={buttonVariant}
+              size={buttonSize}
+              disabled={disabled}
+              onClick={() => fileInputRef.current?.click()}
+            >
+              <Paperclip className={buttonIcon(buttonSize)} /> {text.attachmentAdd}
             </Button>
             {onCaptureScreenshot && (
-              <CaptureButton capture={onCaptureScreenshot} onFile={pick} label={text.attachmentCapture} />
+              <CaptureButton
+                capture={onCaptureScreenshot}
+                onFile={pick}
+                label={text.attachmentCapture}
+                disabled={disabled}
+                variant={buttonVariant}
+                size={buttonSize}
+              />
             )}
           </div>
           {/* Said out loud, because a gesture with no affordance is a gesture
@@ -346,6 +504,7 @@ function SingleField({
         type="file"
         accept={accept.join(",")}
         className="sr-only"
+        disabled={disabled}
         onChange={(e) => {
           pick(e.target.files?.[0]);
           e.target.value = "";
@@ -368,6 +527,9 @@ function MultipleField({
   onCaptureScreenshot,
   documentPaste = false,
   pasteFrom,
+  disabled = false,
+  buttonVariant = "secondary",
+  buttonSize = "md",
   className,
 }: FeedbackAttachmentFieldMultipleProps) {
   const rootRef = useRef<HTMLDivElement>(null);
@@ -377,6 +539,7 @@ function MultipleField({
   const removeLabel = text.attachmentRemoveFile ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentRemoveFile!;
   const limitLabel = text.attachmentLimit ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentLimit!;
   const screenshotLabel = text.attachmentScreenshot ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentScreenshot!;
+  const errorInfo = useErrorInfo(accept, maxBytes, max, text);
 
   // What an add or a remove builds on: the `value` prop, plus whatever this field has
   // already handed to `onChange` since the parent last rendered. The field is
@@ -405,27 +568,28 @@ function MultipleField({
     const accepted: File[] = [];
     const taken = new Set([...current, ...(screenshot ? [screenshot] : [])].map((f) => f.name));
     for (const raw of incoming) {
-      const problem = rejection(raw, accept, maxBytes);
-      if (problem) {
-        onError?.(problem);
-        continue;
-      }
       // Two pastes are two files called "pasted.png", and a backend that stores by
       // name keeps one of them — the very loss this mode exists to end. A picked
-      // file keeps its own name: it is the user's, and they may look for it.
+      // file keeps its own name: it is the user's, and they may look for it. Named
+      // before the check, so a refusal names it as the single field's does.
       const file = pasted ? renamed(raw, uniqueName(pastedName(raw.type), taken)) : raw;
+      const problem = rejection(file, accept, maxBytes);
+      if (problem) {
+        onError?.(problem, errorInfo(problem, [file]));
+        continue;
+      }
       taken.add(file.name);
       // The same File object twice is one file chosen twice, not two.
       if (!current.includes(file)) accepted.push(file);
     }
     if (accepted.length === 0) return;
     const space = Math.max(0, max - current.length);
-    if (accepted.length > space) onError?.("count");
+    if (accepted.length > space) onError?.("count", errorInfo("count", accepted.slice(space)));
     const kept = accepted.slice(0, space);
     if (kept.length > 0) commit([...current, ...kept]);
   };
 
-  const onPaste = usePaste((images) => add(images, true), documentPaste, pasteFrom);
+  const onPaste = usePaste((images) => add(images, true), documentPaste, pasteFrom, disabled);
 
   const capture = (file: File) => {
     if (!hasSlot) {
@@ -433,7 +597,7 @@ function MultipleField({
       return;
     }
     const problem = rejection(file, accept, maxBytes);
-    if (problem) onError?.(problem);
+    if (problem) onError?.(problem, errorInfo(problem, [file]));
     else onScreenshotChange(file);
   };
 
@@ -468,7 +632,7 @@ function MultipleField({
   ];
 
   return (
-    <div ref={rootRef} className={cn("relative space-y-2", className)} onPaste={onPaste}>
+    <div ref={rootRef} className={cn(FIELD_ROOT, "space-y-2", className)} onPaste={onPaste}>
       <Heading text={labelsProp?.attachment} className="mb-0" />
       {chips.length > 0 && (
         // One chip per row, full width: wrapped chips of name-dependent widths made a
@@ -489,18 +653,14 @@ function MultipleField({
                   {chip.screenshot ? `${chip.file.name} · ${fileText.size(chip.file.size)}` : fileText.size(chip.file.size)}
                 </div>
               </div>
-              <button
-                type="button"
-                data-attachment-remove=""
+              <RemoveButton
+                label={removeLabel(chip.name)}
+                disabled={disabled}
                 onClick={() => {
                   pendingFocus.current = index;
                   chip.remove();
                 }}
-                aria-label={removeLabel(chip.name)}
-                className="shrink-0 rounded p-1.5 text-[var(--text-placeholder)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]"
-              >
-                <X className="size-4" />
-              </button>
+              />
             </li>
           ))}
         </ul>
@@ -510,11 +670,13 @@ function MultipleField({
           {room > 0 && (
             <Button
               type="button"
-              variant="secondary"
+              variant={buttonVariant}
+              size={buttonSize}
               data-attachment-action=""
+              disabled={disabled}
               onClick={() => fileInputRef.current?.click()}
             >
-              <Paperclip className="size-4" /> {text.attachmentAdd}
+              <Paperclip className={buttonIcon(buttonSize)} /> {text.attachmentAdd}
             </Button>
           )}
           {canCapture && onCaptureScreenshot && (
@@ -522,6 +684,9 @@ function MultipleField({
               capture={onCaptureScreenshot}
               onFile={capture}
               label={text.attachmentCapture}
+              disabled={disabled}
+              variant={buttonVariant}
+              size={buttonSize}
               data-attachment-action=""
             />
           )}
@@ -540,6 +705,7 @@ function MultipleField({
         // the way in, and a second, unlabelled "Choose files" stop is noise.
         tabIndex={-1}
         aria-hidden
+        disabled={disabled}
         onChange={(e) => {
           add(Array.from(e.target.files ?? []));
           e.target.value = "";
@@ -571,6 +737,11 @@ function RefsField({
   onCaptureScreenshot,
   documentPaste = false,
   pasteFrom,
+  disabled = false,
+  commit: commits,
+  disabledReason: ownDisabledReason,
+  buttonVariant = "secondary",
+  buttonSize = "md",
   className,
 }: FeedbackAttachmentFieldRefsProps) {
   const rootRef = useRef<HTMLDivElement>(null);
@@ -580,6 +751,14 @@ function RefsField({
   const removeLabel = text.attachmentRemoveFile ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentRemoveFile!;
   const limitLabel = text.attachmentLimit ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentLimit!;
   const uploadingLabel = text.attachmentUploading ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentUploading!;
+  const errorInfo = useErrorInfo(accept, maxBytes, max, text);
+  // The lock's reason (under `commit`) over the field's own; with either, the controls
+  // take the focusable `aria-disabled` path and say why — Button's and IconButton's
+  // `disabledReason`, handed down as is.
+  const disabledReason = useCommitReason(commits, ownDisabledReason);
+  const locked = hasReason(disabledReason);
+  const reason = locked ? disabledReason : undefined;
+  const inert = disabled || locked;
 
   // As in `multiple` mode: `value` plus whatever has been handed to `onChange` since
   // the parent last rendered — two uploads landing in one tick must both survive.
@@ -637,7 +816,7 @@ function RefsField({
       },
       (error: unknown) => {
         settle();
-        if (mounted.current) onError?.("upload", error);
+        if (mounted.current) onError?.("upload", error, errorInfo("upload", [file], error));
       },
     );
   };
@@ -645,28 +824,29 @@ function RefsField({
   const add = (incoming: File[], pasted = false) => {
     let space = Math.max(0, max - latest.current.length - inFlight.current.length);
     const taken = new Set([...latest.current.map((r) => r.name), ...inFlight.current.map((u) => u.file.name)]);
-    let dropped = false;
+    const dropped: File[] = [];
     for (const raw of incoming) {
-      const problem = rejection(raw, accept, maxBytes);
+      // Pasted images are all "image.png" to the clipboard; as in `multiple` mode,
+      // each gets a name of its own before it is checked and uploaded under it.
+      const file = pasted ? renamed(raw, uniqueName(pastedName(raw.type), taken)) : raw;
+      const problem = rejection(file, accept, maxBytes);
       if (problem) {
-        onError?.(problem);
+        // `undefined` in `error`'s place, as in 0.22: only an upload has one.
+        onError?.(problem, undefined, errorInfo(problem, [file]));
         continue;
       }
+      taken.add(file.name);
       if (space === 0) {
-        dropped = true;
+        dropped.push(file);
         continue;
       }
-      // Pasted images are all "image.png" to the clipboard; as in `multiple` mode,
-      // each gets a name of its own before it is uploaded under it.
-      const file = pasted ? renamed(raw, uniqueName(pastedName(raw.type), taken)) : raw;
-      taken.add(file.name);
       space -= 1;
       start(file);
     }
-    if (dropped) onError?.("count");
+    if (dropped.length > 0) onError?.("count", undefined, errorInfo("count", dropped));
   };
 
-  const onPaste = usePaste((images) => add(images, true), documentPaste, pasteFrom);
+  const onPaste = usePaste((images) => add(images, true), documentPaste, pasteFrom, inert);
 
   // Focus after a remove, as in `multiple` mode: the next chip, else the first action.
   const pendingFocus = useRef<number | null>(null);
@@ -683,6 +863,7 @@ function RefsField({
   }, [value]);
 
   const remove = (key: string, index: number) => {
+    if (inert) return;
     pendingFocus.current = index;
     commit(latest.current.filter((r) => r.key !== key));
     onRemove?.(key);
@@ -691,7 +872,7 @@ function RefsField({
   const hasChips = value.length > 0 || uploads.length > 0;
 
   return (
-    <div ref={rootRef} className={cn("relative space-y-2", className)} onPaste={onPaste}>
+    <div ref={rootRef} className={cn(FIELD_ROOT, "space-y-2", className)} onPaste={onPaste}>
       <Heading text={labelsProp?.attachment} className="mb-0" />
       {hasChips && (
         <ul aria-label={text.attachmentList} className="flex flex-col gap-2">
@@ -707,15 +888,12 @@ function RefsField({
                   <div className="truncate text-xs text-[var(--text-muted)]">{fileText.size(ref.size)}</div>
                 )}
               </div>
-              <button
-                type="button"
-                data-attachment-remove=""
+              <RemoveButton
+                label={removeLabel(ref.name)}
                 onClick={() => remove(ref.key, index)}
-                aria-label={removeLabel(ref.name)}
-                className="shrink-0 rounded p-1.5 text-[var(--text-placeholder)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]"
-              >
-                <X className="size-4" />
-              </button>
+                disabled={disabled}
+                reason={reason}
+              />
             </li>
           ))}
           {uploads.map((upload) => (
@@ -740,23 +918,38 @@ function RefsField({
         <div className="flex flex-wrap gap-2">
           <Button
             type="button"
-            variant="secondary"
+            variant={buttonVariant}
+            size={buttonSize}
             data-attachment-action=""
+            disabled={disabled}
+            disabledReason={reason}
             onClick={() => fileInputRef.current?.click()}
           >
-            <Paperclip className="size-4" /> {text.attachmentAdd}
+            <Paperclip className={buttonIcon(buttonSize)} /> {text.attachmentAdd}
           </Button>
           {onCaptureScreenshot && (
             <CaptureButton
               capture={onCaptureScreenshot}
               onFile={(file) => add([file])}
               label={text.attachmentCapture}
+              disabled={disabled}
+              disabledReason={reason}
+              variant={buttonVariant}
+              size={buttonSize}
               data-attachment-action=""
             />
           )}
         </div>
       )}
-      <p className="text-xs text-[var(--text-muted)]">{room > 0 ? text.attachmentPaste : limitLabel(max)}</p>
+      {locked ? (
+        // Where the paste hint was: a phone never hovers, so the Tooltip alone would
+        // leave a touch user with buttons that do nothing and no word why.
+        <div data-attachment-reason="" className="text-xs text-[var(--text-muted)]">
+          {disabledReason}
+        </div>
+      ) : (
+        <p className="text-xs text-[var(--text-muted)]">{room > 0 ? text.attachmentPaste : limitLabel(max)}</p>
+      )}
       <input
         ref={fileInputRef}
         type="file"
@@ -765,6 +958,7 @@ function RefsField({
         className="sr-only"
         tabIndex={-1}
         aria-hidden
+        disabled={inert}
         onChange={(e) => {
           add(Array.from(e.target.files ?? []));
           e.target.value = "";
@@ -797,22 +991,32 @@ function CaptureButton({
   capture,
   onFile,
   label,
+  disabled = false,
+  disabledReason,
+  variant,
+  size,
   ...rest
 }: {
   capture: () => Promise<File | null>;
   onFile: (file: File) => void;
   label: string;
+  disabled?: boolean;
+  disabledReason?: ReactNode;
+  variant: ButtonVariant;
+  size: ButtonSize;
   "data-attachment-action"?: string;
 }) {
   const [capturing, setCapturing] = useState(false);
   return (
     <Button
       type="button"
-      variant="secondary"
-      disabled={capturing}
+      variant={variant}
+      size={size}
+      disabled={capturing || disabled}
+      disabledReason={disabledReason}
       {...rest}
       onClick={() => {
-        if (capturing) return;
+        if (capturing || disabled) return;
         setCapturing(true);
         void capture()
           .then((file) => {
@@ -821,11 +1025,98 @@ function CaptureButton({
           .finally(() => setCapturing(false));
       }}
     >
-      <Camera className="size-4" /> {capturing ? "…" : label}
+      <Camera className={buttonIcon(size)} /> {capturing ? "…" : label}
     </Button>
   );
 }
 
+/**
+ * A chip's (or the single file's) remove button: the kit's IconButton at the 28px the
+ * hand-built one had, so `disabled` (0.23.0) dims and disables it the kit way and a
+ * `reason` takes IconButton's `disabledReason` path — focusable, `aria-disabled`, the
+ * reason in the Tooltip — rather than a third copy of either here.
+ */
+function RemoveButton({
+  label,
+  onClick,
+  disabled,
+  reason,
+}: {
+  label: string;
+  onClick: () => void;
+  disabled: boolean;
+  reason?: ReactNode;
+}) {
+  return (
+    <IconButton
+      type="button"
+      size="xs"
+      tone="muted"
+      data-attachment-remove=""
+      aria-label={label}
+      disabled={disabled}
+      disabledReason={reason}
+      onClick={onClick}
+      className="shrink-0"
+    >
+      <X aria-hidden />
+    </IconButton>
+  );
+}
+
+/** A reason worth showing: `null`, `false` and `""` are a caller's "no reason". */
+function hasReason(reason: ReactNode): boolean {
+  return reason !== undefined && reason !== null && reason !== false && reason !== "";
+}
+
+/**
+ * The {@link FeedbackAttachmentErrorInfo} builder of one field: its limits, and the
+ * sentence for each refusal. The sentences are the `filePicker` namespace's — the ones
+ * FileButton and FileDropzone say — so an app that translated those has these too, and
+ * a refusal reads the same whichever of the kit's pickers made it. Only the upload
+ * failure, which no other picker has, is this field's own (`attachmentUploadFailed`).
+ */
+function useErrorInfo(
+  accept: string[],
+  maxBytes: number,
+  max: number | undefined,
+  text: FeedbackAttachmentFieldLabels,
+) {
+  const picker = useKitLabels("filePicker", DEFAULT_FILE_PICKER_LABELS);
+  const fileText = useKitFileLabels();
+  const uploadFailed = text.attachmentUploadFailed ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentUploadFailed!;
+  return (kind: FeedbackAttachmentRefsError, files: File[], error?: unknown): FeedbackAttachmentErrorInfo => {
+    const file = files[0];
+    let message: string;
+    if (kind === "type") {
+      // FileButton's rule: name what IS accepted ("Only image/png, image/jpeg files"),
+      // unless the app translated `rejectedType` but not yet `rejectedTypeOnly` — its
+      // own sentence beats an English one.
+      const acceptText = formatAccept(accept.join(","));
+      const useOnly =
+        acceptText !== "" &&
+        (picker.rejectedTypeOnly !== DEFAULT_FILE_PICKER_LABELS.rejectedTypeOnly ||
+          picker.rejectedType === DEFAULT_FILE_PICKER_LABELS.rejectedType);
+      message = useOnly ? picker.rejectedTypeOnly(acceptText, file.name) : picker.rejectedType(file.name);
+    } else if (kind === "size") {
+      message = picker.rejectedSize(file.name, fileText.size(maxBytes));
+    } else if (kind === "count") {
+      message = files.length === 1 ? picker.rejectedCount(file.name, max ?? 1) : picker.rejectedMany(files.length);
+    } else {
+      message = uploadFailed(file.name);
+    }
+    return {
+      file,
+      files,
+      message,
+      maxBytes,
+      accept,
+      ...(max !== undefined ? { max } : null),
+      ...(kind === "upload" ? { error } : null),
+    };
+  };
+}
+
 /** A chip's picture: the image itself, or a file glyph for anything that is not one.
  *  Decorative (`alt=""`) — the name stands beside it. Its own component so the object
  *  URL lives exactly as long as the chip: removing the chip unmounts it and revokes. */
@@ -903,10 +1194,15 @@ function usePaste(
   onImages: (images: File[]) => void,
   documentPaste: boolean,
   pasteFrom: RefObject<HTMLElement | null> | undefined,
+  /** `disabled` / locked (0.23.0): the paste goes where it was going, untouched — not
+   *  swallowed, so a text half still lands in the box it was made in. */
+  off: boolean,
 ) {
-  const latest = useRef(onImages);
+  // `null` while off, so the listeners below leave the event alone entirely.
+  const handler = off ? null : onImages;
+  const latest = useRef(handler);
   useEffect(() => {
-    latest.current = onImages;
+    latest.current = handler;
   });
 
   // The element listened on, where it is not this field's own subtree: the
@@ -917,6 +1213,7 @@ function usePaste(
     const target: EventTarget | null = documentPaste ? document : (pasteFrom?.current ?? null);
     if (!target) return;
     const onPaste = (event: Event) => {
+      if (!latest.current) return;
       const clipboard = (event as ClipboardEvent).clipboardData;
       takeImages(clipboard, () => event.preventDefault(), latest.current);
     };
@@ -927,7 +1224,10 @@ function usePaste(
   const listensElsewhere = documentPaste || pasteFrom !== undefined;
   return listensElsewhere
     ? undefined
-    : (event: ReactClipboardEvent) => takeImages(event.clipboardData, () => event.preventDefault(), latest.current);
+    : (event: ReactClipboardEvent) => {
+        if (!latest.current) return;
+        takeImages(event.clipboardData, () => event.preventDefault(), latest.current);
+      };
 }
 
 function takeImages(clipboard: DataTransfer | null, stop: () => void, onImages: (images: File[]) => void) {