@eifi1/ui-kit 0.15.3 → 0.15.5

package/src/feedback/feedback-attachment.tsx

@@ -1,5 +1,5 @@
 import { cn } from "../lib/cn";
-import { useEffect, useRef, useState, type RefObject } from "react";
+import { useEffect, useRef, useState, type ClipboardEvent as ReactClipboardEvent, type RefObject } from "react";
 import { Camera, FileText, Paperclip, X } from "lucide-react";
 import { Button } from "../components/ui";
 import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels";
@@ -7,6 +7,10 @@ import type { FeedbackAttachmentLabels } from "./feedback-dialog";
 
 export const DEFAULT_ATTACHMENT_ACCEPT = ["image/png", "image/jpeg", "image/webp", "image/gif"];
 export const DEFAULT_MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+/** How many files `<FeedbackAttachmentField multiple>` takes when `max` is not given
+ *  (0.15.5). Five photos of one problem is already a lot to look through; a report
+ *  that needs more is a conversation, which the thread is for. */
+export const DEFAULT_MAX_ATTACHMENTS = 5;
 
 /**
  * The field's own strings — the `feedbackAttachment` namespace of `<UiKitProvider
@@ -17,12 +21,22 @@ export const DEFAULT_MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
  *
  * Before 0.7.0 the two optional keys fell back to hard-coded English, so a German app
  * that relied on its provider got "Capture screenshot" under a German form.
+ *
+ * The three keys added in 0.15.5 for `multiple` mode are optional, so a complete
+ * `UiKitLabels` typed before it still compiles; they fall back to English.
  */
 export interface FeedbackAttachmentFieldLabels {
   attachmentAdd: string;
   attachmentCapture: string;
   attachmentPaste: string;
   attachmentRemove: string;
+  /** `multiple` mode: the accessible name of the list of chosen files. */
+  attachmentList?: string;
+  /** `multiple` mode: one chip's remove button — "Remove photo.jpg". Named per file,
+   *  because five buttons all called "Remove attachment" say nothing about which. */
+  attachmentRemoveFile?: (name: string) => string;
+  /** `multiple` mode: the line shown in place of the add buttons once `max` is reached. */
+  attachmentLimit?: (max: number) => string;
 }
 
 export const DEFAULT_FEEDBACK_ATTACHMENT_LABELS: FeedbackAttachmentFieldLabels = {
@@ -30,10 +44,81 @@ export const DEFAULT_FEEDBACK_ATTACHMENT_LABELS: FeedbackAttachmentFieldLabels =
   attachmentCapture: "Capture screenshot",
   attachmentPaste: "…or paste a screenshot from the clipboard.",
   attachmentRemove: "Remove attachment",
+  attachmentList: "Attachments",
+  attachmentRemoveFile: (name) => `Remove ${name}`,
+  attachmentLimit: (max) =>
+    `Up to ${max} ${max === 1 ? "attachment" : "attachments"} — remove one to add another.`,
 };
 
+/** Why a file was turned away. `"count"` only ever comes from `multiple` mode: more
+ *  files arrived at once than `max` left room for, and the surplus was dropped. */
+export type FeedbackAttachmentError = "type" | "size" | "count";
+
+interface FeedbackAttachmentFieldBaseProps {
+  /** Prop > `<UiKitProvider labels={{ feedbackAttachment }}>` > English. Optional
+   *  since 0.7.0; `attachment` (the heading) is only ever read from here. */
+  labels?: Partial<FeedbackAttachmentLabels>;
+  accept?: string[];
+  maxBytes?: number;
+  /** 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>;
+  /** Listen for the paste on `document` rather than on this field's own
+   *  subtree. For a modal, which owns the whole page while it is up. */
+  documentPaste?: boolean;
+  /** Listen for the paste within this element's subtree rather than this
+   *  field's own — for a field standing *beside* the text box a paste is made
+   *  in, whose common parent is where the event bubbles to. Ignored when
+   *  `documentPaste` is set. */
+  pasteFrom?: RefObject<HTMLElement | null>;
+  className?: string;
+}
+
+/** 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;
+  value: File | null;
+  onChange: (file: File | null) => void;
+  onError?: (kind: "type" | "size") => void;
+  // Multiple-mode props, refused here: without `multiple` they would be silently ignored.
+  max?: never;
+  screenshot?: never;
+  onScreenshotChange?: never;
+}
+
+/**
+ * Several files (0.15.5, keksdose dev#578: "pasted two photos, the second overwrote
+ * the first"). Every way in ADDS — a pick of several files, a paste, a capture — up to
+ * `max`, and each file is a removable chip.
+ */
+export interface FeedbackAttachmentFieldMultipleProps extends FeedbackAttachmentFieldBaseProps {
+  multiple: true;
+  value: File[];
+  onChange: (files: File[]) => void;
+  /** 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;
+  /**
+   * A separate slot for THE screenshot, outside `value` and `max`. Given
+   * `onScreenshotChange`, what `onCaptureScreenshot` returns lands here instead of in
+   * `value`, shown as the first chip, and the capture button is offered only while the
+   * slot is empty — a second snapshot of the same view is not more evidence. This is
+   * how `<FeedbackDialog attachments="multiple">` keeps the screenshot apart from the
+   * photos; a form built from the parts can do the same.
+   */
+  screenshot?: File | null;
+  onScreenshotChange?: (file: File | null) => void;
+}
+
+export type FeedbackAttachmentFieldProps =
+  | FeedbackAttachmentFieldSingleProps
+  | FeedbackAttachmentFieldMultipleProps;
+
 /**
  * Picking one picture: the file dialog, a capture of the app view, or a paste.
+ * With `multiple`, picking several (see {@link FeedbackAttachmentFieldMultipleProps}).
  *
  * Lifted out of {@link FeedbackDialog} so the *reply* half of the feature can
  * have it too (Steering Design feedback #128). A report is a conversation — it
@@ -61,7 +146,14 @@ export const DEFAULT_FEEDBACK_ATTACHMENT_LABELS: FeedbackAttachmentFieldLabels =
  * (Steering Design feedback #140): the element whose subtree is listened to,
  * handed in by whoever renders both the box and this field side by side.
  */
-export function FeedbackAttachmentField({
+export function FeedbackAttachmentField(props: FeedbackAttachmentFieldProps) {
+  // Two components rather than one with branches: the modes hold different state
+  // (one preview vs. one per chip), and a hook order that depends on a prop is a
+  // crash the day a caller flips it.
+  return props.multiple ? <MultipleField {...props} /> : <SingleField {...props} />;
+}
+
+function SingleField({
   value,
   onChange,
   labels: labelsProp,
@@ -72,33 +164,11 @@ export function FeedbackAttachmentField({
   documentPaste = false,
   pasteFrom,
   className,
-}: {
-  value: File | null;
-  onChange: (file: File | null) => void;
-  /** Prop > `<UiKitProvider labels={{ feedbackAttachment }}>` > English. Optional
-   *  since 0.7.0; `attachment` (the heading) is only ever read from here. */
-  labels?: Partial<FeedbackAttachmentLabels>;
-  accept?: string[];
-  maxBytes?: number;
-  onError?: (kind: "type" | "size") => void;
-  /** 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>;
-  /** Listen for the paste on `document` rather than on this field's own
-   *  subtree. For a modal, which owns the whole page while it is up. */
-  documentPaste?: boolean;
-  /** Listen for the paste within this element's subtree rather than this
-   *  field's own — for a field standing *beside* the text box a paste is made
-   *  in, whose common parent is where the event bubbles to. Ignored when
-   *  `documentPaste` is set. */
-  pasteFrom?: RefObject<HTMLElement | null>;
-  className?: string;
-}) {
+}: FeedbackAttachmentFieldSingleProps) {
   // The object URL is keyed to the file it was made for, so a stale one (from the
   // previous file, or after `value` is cleared) is never shown — no reset needed.
   const [previewFor, setPreviewFor] = useState<{ file: File; url: string } | null>(null);
   const preview = value && previewFor?.file === value ? previewFor.url : null;
-  const [capturing, setCapturing] = useState(false);
   const fileInputRef = useRef<HTMLInputElement>(null);
   // `file.size` from `<UiKitProvider labels>`, formatted in its locale — see FileDropzone.
   const fileText = useKitFileLabels();
@@ -118,55 +188,25 @@ export function FeedbackAttachmentField({
 
   const pick = (file: File | undefined | null) => {
     if (!file) return;
-    if (!accept.includes(file.type)) {
-      onError?.("type");
-      return;
-    }
-    if (file.size > maxBytes) {
-      onError?.("size");
+    const problem = rejection(file, accept, maxBytes);
+    if (problem) {
+      onError?.(problem);
       return;
     }
     onChange(file);
   };
 
-  // The paste handler is registered once rather than per render, so it reads
-  // `pick` — which closes over props that change identity on every render — out
-  // of a ref rather than out of its own dependency list.
-  const latest = useRef(pick);
-  useEffect(() => {
-    latest.current = pick;
-  });
-
-  const takeImage = (clipboard: DataTransfer | null, stop: () => void) => {
-    const items = Array.from(clipboard?.items ?? []);
-    const image = items.find((item) => item.kind === "file" && item.type.startsWith("image/"));
-    const file = image?.getAsFile();
-    if (!file) return;
-    // Only once there IS an image: a paste of text into a field must stay a
-    // paste of text, and a clipboard holding both is a copy whose text half is
-    // what the field was focused for.
-    stop();
-    // Clipboard images arrive named "image.png" at best and unnamed at worst,
-    // and the name is what the inbox shows beside the thumbnail. A name that
-    // says where it came from is more use than the browser's.
-    latest.current(new File([file], pastedName(file.type), { type: file.type }));
-  };
-
-  // The element listened on, where it is not this field's own subtree: the
-  // document for a modal, the given parent for an inline editor. Read inside
-  // the effect rather than in render, because a ref's `current` is only set
-  // once the parent has mounted — which it has by the time effects run.
-  useEffect(() => {
-    const target: EventTarget | null = documentPaste ? document : (pasteFrom?.current ?? null);
-    if (!target) return;
-    const onPaste = (event: Event) => {
-      const clipboard = (event as ClipboardEvent).clipboardData;
-      takeImage(clipboard, () => event.preventDefault());
-    };
-    target.addEventListener("paste", onPaste);
-    return () => target.removeEventListener("paste", onPaste);
-  }, [documentPaste, pasteFrom]);
-  const listensElsewhere = documentPaste || pasteFrom !== undefined;
+  const onPaste = usePaste(
+    (images) => {
+      // Clipboard images arrive named "image.png" at best and unnamed at worst,
+      // and the name is what the inbox shows beside the thumbnail. A name that
+      // says where it came from is more use than the browser's.
+      const file = images[0];
+      pick(new File([file], pastedName(file.type), { type: file.type }));
+    },
+    documentPaste,
+    pasteFrom,
+  );
 
   return (
     <div
@@ -175,17 +215,9 @@ export function FeedbackAttachmentField({
       // 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)}
-      onPaste={
-        listensElsewhere
-          ? undefined
-          : (event) => takeImage(event.clipboardData, () => event.preventDefault())
-      }
+      onPaste={onPaste}
     >
-      {labelsProp?.attachment && (
-        <div className="mb-1 text-xs font-medium uppercase tracking-wide text-[var(--text-muted)]">
-          {labelsProp.attachment}
-        </div>
-      )}
+      <Heading text={labelsProp?.attachment} />
       {value ? (
         <div className="flex items-start gap-2">
           {value.type.startsWith("image/") && preview ? (
@@ -223,23 +255,7 @@ export function FeedbackAttachmentField({
               <Paperclip className="size-4" /> {text.attachmentAdd}
             </Button>
             {onCaptureScreenshot && (
-              <Button
-                type="button"
-                variant="secondary"
-                disabled={capturing}
-                onClick={() => {
-                  if (capturing) return;
-                  setCapturing(true);
-                  void onCaptureScreenshot()
-                    .then((file) => {
-                      if (file) pick(file);
-                    })
-                    .finally(() => setCapturing(false));
-                }}
-              >
-                <Camera className="size-4" />{" "}
-                {capturing ? "…" : text.attachmentCapture}
-              </Button>
+              <CaptureButton capture={onCaptureScreenshot} onFile={pick} label={text.attachmentCapture} />
             )}
           </div>
           {/* Said out loud, because a gesture with no affordance is a gesture
@@ -263,6 +279,335 @@ export function FeedbackAttachmentField({
   );
 }
 
+function MultipleField({
+  value,
+  onChange,
+  max = DEFAULT_MAX_ATTACHMENTS,
+  screenshot = null,
+  onScreenshotChange,
+  labels: labelsProp,
+  accept = DEFAULT_ATTACHMENT_ACCEPT,
+  maxBytes = DEFAULT_MAX_ATTACHMENT_BYTES,
+  onError,
+  onCaptureScreenshot,
+  documentPaste = false,
+  pasteFrom,
+  className,
+}: FeedbackAttachmentFieldMultipleProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const fileText = useKitFileLabels();
+  const text = useKitLabels("feedbackAttachment", DEFAULT_FEEDBACK_ATTACHMENT_LABELS, labelsProp);
+  const removeLabel = text.attachmentRemoveFile ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentRemoveFile!;
+  const limitLabel = text.attachmentLimit ?? DEFAULT_FEEDBACK_ATTACHMENT_LABELS.attachmentLimit!;
+
+  const hasSlot = onScreenshotChange !== undefined;
+  const room = Math.max(0, max - value.length);
+  // The screenshot slot is its own thing: it neither counts against `max` nor is
+  // closed by it, so a full set of photos still leaves the capture on offer.
+  const canCapture = !!onCaptureScreenshot && (hasSlot ? !screenshot : room > 0);
+
+  const add = (incoming: File[], pasted = false) => {
+    const accepted: File[] = [];
+    const taken = new Set([...value, ...(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.
+      const file = pasted ? renamed(raw, uniqueName(pastedName(raw.type), taken)) : raw;
+      taken.add(file.name);
+      // The same File object twice is one file chosen twice, not two.
+      if (!value.includes(file)) accepted.push(file);
+    }
+    if (accepted.length === 0) return;
+    if (accepted.length > room) onError?.("count");
+    const kept = accepted.slice(0, room);
+    if (kept.length > 0) onChange([...value, ...kept]);
+  };
+
+  const onPaste = usePaste((images) => add(images, true), documentPaste, pasteFrom);
+
+  const capture = (file: File) => {
+    if (!hasSlot) {
+      add([file]);
+      return;
+    }
+    const problem = rejection(file, accept, maxBytes);
+    if (problem) onError?.(problem);
+    else onScreenshotChange(file);
+  };
+
+  // Removing a chip removes the button that had focus. Focus goes to the chip that
+  // took its place — the next one — and, when it was the last, to the first action
+  // button (there is room again, so "Attach" is back), else to the chip before it.
+  // Applied once the parent has re-rendered with the shorter list: the field is
+  // controlled, and focusing before that would land on the chip being removed.
+  const pendingFocus = useRef<number | null>(null);
+  useEffect(() => {
+    const index = pendingFocus.current;
+    if (index === null) return;
+    pendingFocus.current = null;
+    const root = rootRef.current;
+    if (!root) return;
+    const removes = root.querySelectorAll<HTMLElement>("[data-attachment-remove]");
+    const target =
+      removes[index] ?? root.querySelector<HTMLElement>("[data-attachment-action]") ?? removes[index - 1];
+    target?.focus();
+  }, [value, screenshot]);
+
+  const chips: Array<{ file: File; screenshot: boolean; remove: () => void }> = [
+    ...(hasSlot && screenshot
+      ? [{ file: screenshot, screenshot: true, remove: () => onScreenshotChange(null) }]
+      : []),
+    ...value.map((file) => ({
+      file,
+      screenshot: false,
+      remove: () => onChange(value.filter((f) => f !== file)),
+    })),
+  ];
+
+  return (
+    <div ref={rootRef} className={cn("relative 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
+        // ragged block in a 430px dialog, and a column keeps every name and remove
+        // button in the same place — the next chip's button is right under the last.
+        <ul aria-label={text.attachmentList} className="flex flex-col gap-2">
+          {chips.map((chip, index) => (
+            <li
+              key={fileKey(chip.file)}
+              className="flex min-w-0 items-center gap-2 rounded-md border border-[var(--border)] bg-[var(--bg-surface)] p-1"
+            >
+              <ChipPreview file={chip.file} screenshot={chip.screenshot} />
+              <div className="min-w-0 flex-1">
+                <div className="truncate text-sm text-[var(--text-secondary)]">{chip.file.name}</div>
+                <div className="text-xs text-[var(--text-muted)]">{fileText.size(chip.file.size)}</div>
+              </div>
+              <button
+                type="button"
+                data-attachment-remove=""
+                onClick={() => {
+                  pendingFocus.current = index;
+                  chip.remove();
+                }}
+                aria-label={removeLabel(chip.file.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>
+      )}
+      {(room > 0 || canCapture) && (
+        <div className="flex flex-wrap gap-2">
+          {room > 0 && (
+            <Button
+              type="button"
+              variant="secondary"
+              data-attachment-action=""
+              onClick={() => fileInputRef.current?.click()}
+            >
+              <Paperclip className="size-4" /> {text.attachmentAdd}
+            </Button>
+          )}
+          {canCapture && onCaptureScreenshot && (
+            <CaptureButton
+              capture={onCaptureScreenshot}
+              onFile={capture}
+              label={text.attachmentCapture}
+              data-attachment-action=""
+            />
+          )}
+        </div>
+      )}
+      <p className="text-xs text-[var(--text-muted)]">
+        {room > 0 ? text.attachmentPaste : limitLabel(max)}
+      </p>
+      <input
+        ref={fileInputRef}
+        type="file"
+        multiple={room > 1}
+        accept={accept.join(",")}
+        className="sr-only"
+        // Out of the tab order and the accessibility tree: the button above is
+        // the way in, and a second, unlabelled "Choose files" stop is noise.
+        tabIndex={-1}
+        aria-hidden
+        onChange={(e) => {
+          add(Array.from(e.target.files ?? []));
+          e.target.value = "";
+        }}
+      />
+    </div>
+  );
+}
+
+function Heading({ text, className }: { text?: string; className?: string }) {
+  if (!text) return null;
+  return (
+    <div className={cn("mb-1 text-xs font-medium uppercase tracking-wide text-[var(--text-muted)]", className)}>
+      {text}
+    </div>
+  );
+}
+
+function CaptureButton({
+  capture,
+  onFile,
+  label,
+  ...rest
+}: {
+  capture: () => Promise<File | null>;
+  onFile: (file: File) => void;
+  label: string;
+  "data-attachment-action"?: string;
+}) {
+  const [capturing, setCapturing] = useState(false);
+  return (
+    <Button
+      type="button"
+      variant="secondary"
+      disabled={capturing}
+      {...rest}
+      onClick={() => {
+        if (capturing) return;
+        setCapturing(true);
+        void capture()
+          .then((file) => {
+            if (file) onFile(file);
+          })
+          .finally(() => setCapturing(false));
+      }}
+    >
+      <Camera className="size-4" /> {capturing ? "…" : label}
+    </Button>
+  );
+}
+
+/** 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. */
+function ChipPreview({ file, screenshot }: { file: File; screenshot: boolean }) {
+  const isImage = file.type.startsWith("image/");
+  const [previewFor, setPreviewFor] = useState<{ file: File; url: string } | null>(null);
+  const url = previewFor?.file === file ? previewFor.url : null;
+  useEffect(() => {
+    if (!isImage) return;
+    const next = URL.createObjectURL(file);
+    // As in the single field: an external resource created and revoked with the effect.
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- publishing an external resource's handle
+    setPreviewFor({ file, url: next });
+    return () => URL.revokeObjectURL(next);
+  }, [file, isImage]);
+
+  return (
+    <span className="relative flex size-12 shrink-0 items-center justify-center overflow-hidden rounded border border-[var(--border)] bg-[var(--bg-surface-2)] text-[var(--text-placeholder)]">
+      {isImage && url ? (
+        <img src={url} alt="" className="size-full object-cover" />
+      ) : (
+        <FileText aria-hidden className="size-6" />
+      )}
+      {screenshot && (
+        // Marks the slot apart from the photos: it is why the capture button is gone.
+        <span className="absolute bottom-0.5 end-0.5 rounded-sm bg-[var(--bg-surface)] p-0.5 text-[var(--text-secondary)]">
+          <Camera aria-hidden className="size-3" />
+        </span>
+      )}
+    </span>
+  );
+}
+
+/** A stable React key per File object — the name is not one (two pastes, two
+ *  "pasted.png" before renaming; the same photo picked from two folders). */
+const fileKeys = new WeakMap<File, number>();
+let nextFileKey = 0;
+function fileKey(file: File): number {
+  let key = fileKeys.get(file);
+  if (key === undefined) {
+    key = nextFileKey++;
+    fileKeys.set(file, key);
+  }
+  return key;
+}
+
+function rejection(file: File, accept: string[], maxBytes: number): "type" | "size" | null {
+  if (!accept.includes(file.type)) return "type";
+  if (file.size > maxBytes) return "size";
+  return null;
+}
+
+function renamed(file: File, name: string): File {
+  return new File([file], name, { type: file.type });
+}
+
+/** `pasted.png`, then `pasted-2.png`, `pasted-3.png`… — the first name not in `taken`. */
+function uniqueName(name: string, taken: Set<string>): string {
+  if (!taken.has(name)) return name;
+  const dot = name.lastIndexOf(".");
+  const [stem, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
+  let n = 2;
+  while (taken.has(`${stem}-${n}${ext}`)) n++;
+  return `${stem}-${n}${ext}`;
+}
+
+/**
+ * The paste listener both modes share. `onImages` gets every image file on the
+ * clipboard (the single field takes the first). It is registered once rather than per
+ * render, so it reads the handler — which closes over props that change identity on
+ * every render — out of a ref rather than out of its own dependency list. Returns the
+ * `onPaste` for the field's root, or `undefined` when listening elsewhere.
+ */
+function usePaste(
+  onImages: (images: File[]) => void,
+  documentPaste: boolean,
+  pasteFrom: RefObject<HTMLElement | null> | undefined,
+) {
+  const latest = useRef(onImages);
+  useEffect(() => {
+    latest.current = onImages;
+  });
+
+  // The element listened on, where it is not this field's own subtree: the
+  // document for a modal, the given parent for an inline editor. Read inside
+  // the effect rather than in render, because a ref's `current` is only set
+  // once the parent has mounted — which it has by the time effects run.
+  useEffect(() => {
+    const target: EventTarget | null = documentPaste ? document : (pasteFrom?.current ?? null);
+    if (!target) return;
+    const onPaste = (event: Event) => {
+      const clipboard = (event as ClipboardEvent).clipboardData;
+      takeImages(clipboard, () => event.preventDefault(), latest.current);
+    };
+    target.addEventListener("paste", onPaste);
+    return () => target.removeEventListener("paste", onPaste);
+  }, [documentPaste, pasteFrom]);
+
+  const listensElsewhere = documentPaste || pasteFrom !== undefined;
+  return listensElsewhere
+    ? undefined
+    : (event: ReactClipboardEvent) => takeImages(event.clipboardData, () => event.preventDefault(), latest.current);
+}
+
+function takeImages(clipboard: DataTransfer | null, stop: () => void, onImages: (images: File[]) => void) {
+  const images = Array.from(clipboard?.items ?? [])
+    .filter((item) => item.kind === "file" && item.type.startsWith("image/"))
+    .map((item) => item.getAsFile())
+    .filter((file): file is File => file !== null);
+  if (images.length === 0) return;
+  // Only once there IS an image: a paste of text into a field must stay a
+  // paste of text, and a clipboard holding both is a copy whose text half is
+  // what the field was focused for.
+  stop();
+  onImages(images);
+}
+
 /** What a pasted image is called once it is an attachment.
  *
  *  The extension is read off the mime type rather than assumed to be `.png`: