@eifi1/ui-kit 0.22.0 → 0.23.0

package/src/feedback/feedback-attachment.tsx

@@ -1,7 +1,17 @@
 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 { 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 +57,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 +75,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 +88,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 +156,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>;
@@ -111,11 +195,16 @@ export interface FeedbackAttachmentFieldSingleProps extends FeedbackAttachmentFi
   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 +220,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 +234,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 +274,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 +353,7 @@ function SingleField({
   onCaptureScreenshot,
   documentPaste = false,
   pasteFrom,
+  disabled = false,
   className,
 }: FeedbackAttachmentFieldSingleProps) {
   // The object URL is keyed to the file it was made for, so a stale one (from the
@@ -249,6 +364,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 +382,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 +398,7 @@ function SingleField({
     },
     documentPaste,
     pasteFrom,
+    disabled,
   );
 
   return (
@@ -315,23 +432,26 @@ 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()}>
+            <Button
+              type="button"
+              variant="secondary"
+              disabled={disabled}
+              onClick={() => fileInputRef.current?.click()}
+            >
               <Paperclip className="size-4" /> {text.attachmentAdd}
             </Button>
             {onCaptureScreenshot && (
-              <CaptureButton capture={onCaptureScreenshot} onFile={pick} label={text.attachmentCapture} />
+              <CaptureButton
+                capture={onCaptureScreenshot}
+                onFile={pick}
+                label={text.attachmentCapture}
+                disabled={disabled}
+              />
             )}
           </div>
           {/* Said out loud, because a gesture with no affordance is a gesture
@@ -346,6 +466,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 +489,7 @@ function MultipleField({
   onCaptureScreenshot,
   documentPaste = false,
   pasteFrom,
+  disabled = false,
   className,
 }: FeedbackAttachmentFieldMultipleProps) {
   const rootRef = useRef<HTMLDivElement>(null);
@@ -377,6 +499,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 +528,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 +557,7 @@ function MultipleField({
       return;
     }
     const problem = rejection(file, accept, maxBytes);
-    if (problem) onError?.(problem);
+    if (problem) onError?.(problem, errorInfo(problem, [file]));
     else onScreenshotChange(file);
   };
 
@@ -489,18 +613,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>
@@ -512,6 +632,7 @@ function MultipleField({
               type="button"
               variant="secondary"
               data-attachment-action=""
+              disabled={disabled}
               onClick={() => fileInputRef.current?.click()}
             >
               <Paperclip className="size-4" /> {text.attachmentAdd}
@@ -522,6 +643,7 @@ function MultipleField({
               capture={onCaptureScreenshot}
               onFile={capture}
               label={text.attachmentCapture}
+              disabled={disabled}
               data-attachment-action=""
             />
           )}
@@ -540,6 +662,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 +694,9 @@ function RefsField({
   onCaptureScreenshot,
   documentPaste = false,
   pasteFrom,
+  disabled = false,
+  commit: commits,
+  disabledReason: ownDisabledReason,
   className,
 }: FeedbackAttachmentFieldRefsProps) {
   const rootRef = useRef<HTMLDivElement>(null);
@@ -580,6 +706,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 +771,7 @@ function RefsField({
       },
       (error: unknown) => {
         settle();
-        if (mounted.current) onError?.("upload", error);
+        if (mounted.current) onError?.("upload", error, errorInfo("upload", [file], error));
       },
     );
   };
@@ -645,28 +779,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 +818,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);
@@ -707,15 +843,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) => (
@@ -742,6 +875,8 @@ function RefsField({
             type="button"
             variant="secondary"
             data-attachment-action=""
+            disabled={disabled}
+            disabledReason={reason}
             onClick={() => fileInputRef.current?.click()}
           >
             <Paperclip className="size-4" /> {text.attachmentAdd}
@@ -751,12 +886,22 @@ function RefsField({
               capture={onCaptureScreenshot}
               onFile={(file) => add([file])}
               label={text.attachmentCapture}
+              disabled={disabled}
+              disabledReason={reason}
               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 +910,7 @@ function RefsField({
         className="sr-only"
         tabIndex={-1}
         aria-hidden
+        disabled={inert}
         onChange={(e) => {
           add(Array.from(e.target.files ?? []));
           e.target.value = "";
@@ -797,11 +943,15 @@ function CaptureButton({
   capture,
   onFile,
   label,
+  disabled = false,
+  disabledReason,
   ...rest
 }: {
   capture: () => Promise<File | null>;
   onFile: (file: File) => void;
   label: string;
+  disabled?: boolean;
+  disabledReason?: ReactNode;
   "data-attachment-action"?: string;
 }) {
   const [capturing, setCapturing] = useState(false);
@@ -809,10 +959,11 @@ function CaptureButton({
     <Button
       type="button"
       variant="secondary"
-      disabled={capturing}
+      disabled={capturing || disabled}
+      disabledReason={disabledReason}
       {...rest}
       onClick={() => {
-        if (capturing) return;
+        if (capturing || disabled) return;
         setCapturing(true);
         void capture()
           .then((file) => {
@@ -826,6 +977,93 @@ function CaptureButton({
   );
 }
 
+/**
+ * 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 +1141,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 +1160,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 +1171,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) {