components/media/media.ts

Functions

Imports

It imports components/bulk-bar/bulk-bar.ts, components/dialog/dialog.ts, components/media/media-actions.ts, components/media/media-autosave.ts, components/media/media-grid.ts, components/media/media-inspector.ts, components/media/media-record.ts, components/media/media-tile.ts, components/message/message.ts, components/meter/meter.ts. Imported by components/content/content.ts, components/media-library/examples.tsx, components/media-library/media-library.react.tsx, components/media-library/media-library.ts, components/media/media-grid.react.tsx, components/media/media.react.tsx.

Source

1// The media library's behaviour: a grid of tiles with roving focus and two-dimensional arrow keys,
2// selection by real checkboxes, an inspector that sits beside the grid (a pane) or over it (a
3// side sheet) and SAVES BY ITSELF, the copy button, the filters, search, Trash and Restore.
4// The arrow keys read the rendered boxes, not a column count; alt text has three states; an
5// unattached file is not an unused one. The inspector saves after typing stops, with a live
6// status that never loses typed text. No framework; the React wrapper uses the same pure
7// functions.
8
9import { enhance as enhanceMeters } from "../meter/meter.ts";
10import { openDialog, wireDialog } from "../dialog/dialog.ts";
11import { fail } from "../message/message.ts";
12import { performBulk, type BulkHandler, type BulkItem } from "../bulk-bar/bulk-bar.ts";
13import { altStateOf, describeRecord, LARGE_BYTES, parseTags, type MediaFields, type MediaRecord } from "./media-record.ts";
14import { bands, nextTile, type Direction } from "./media-grid.ts";
15import { createAutosave, type Autosave, type SaveState } from "./media-autosave.ts";
16import { applyBulkTag, COPIED_MS, COPY_FAILED_MS, copyText } from "./media-actions.ts";
17import { buildTile, glyph, part, recordOf, syncTile, writeRecord } from "./media-tile.ts";
18import { fillInspector, readFields, renderSave as renderSaveState, renderTags } from "./media-inspector.ts";
19
20export * from "./media-record.ts";
21export * from "./media-grid.ts";
22export * from "./media-autosave.ts";
23export * from "./media-actions.ts";
24export { buildTile, glyph, recordOf, syncTile, writeRecord } from "./media-tile.ts";
25
26const READY = "data-cap-ready";
27
28// ---------------------------------------------------------------------------------------
29// The controller.
30
31export interface MediaOptions {
32  // Sends the inspector's fields. Reject with an Error that says why. Default: a POST of the
33  // inspector's form to its action.
34  save?: (key: string, fields: MediaFields) => Promise<void>;
35  // Persist a move to Trash, a restore, a retry. Each rejects with an Error that says why.
36  bin?: (keys: string[]) => Promise<void>;
37  restore?: (keys: string[]) => Promise<void>;
38  retry?: (key: string) => Promise<void>;
39  // Deletes files for good (the bulk bar's destructive action, after its preview).
40  delete?: (keys: string[]) => Promise<void>;
41}
42
43export interface MediaController {
44  open(key: string): void;
45  close(): void;
46  setActive(key: string): void;
47  selectedKeys(): string[];
48  // Adds a tile (an upload) at the start of the first grid.
49  add(record: MediaRecord): HTMLElement;
50  // Changes a tile's facts and redraws it (progress, a finished upload, a failure).
51  update(key: string, patch: Partial<MediaRecord>): void;
52  bin(keys: string[]): Promise<boolean>;
53  restore(keys: string[]): Promise<boolean>;
54  // The actions a bulk bar over this library runs: bin, restore, copy, add-tag, remove-tag.
55  bulkHandlers(): Record<string, BulkHandler>;
56  refresh(): void;
57  detach(): void;
58}
59
60const controllers = new WeakMap<HTMLElement, MediaController>();
61
62export function controllerFor(root: HTMLElement | null): MediaController | undefined {
63  return root ? controllers.get(root) : undefined;
64}
65
66function singleKeysOff(): boolean {
67  return document.documentElement.dataset.capSingleKeys === "off";
68}
69
70export function attachMedia(root: HTMLElement, options: MediaOptions = {}): MediaController {
71  const existing = controllers.get(root);
72  if (existing) return existing;
73  root.setAttribute(READY, "");
74  const layout = root.querySelector<HTMLElement>(".cap-media-layout") ?? root;
75  const inspector = root.querySelector<HTMLDialogElement>("dialog.cap-media-inspector");
76  const tiles = () => Array.from(root.querySelectorAll<HTMLElement>(".cap-media-tile"));
77  const shown = () => tiles().filter((t) => !t.hidden && !t.closest("[hidden]"));
78  const cleanups: Array<() => void> = [];
79  const listen = <K extends keyof HTMLElementEventMap>(el: HTMLElement | Document | Window, type: K | string, fn: (e: never) => void, opts?: AddEventListenerOptions) => {
80    el.addEventListener(type, fn as EventListener, opts);
81    cleanups.push(() => el.removeEventListener(type, fn as EventListener, opts));
82  };
83
84  let active: HTMLElement | null = root.querySelector<HTMLElement>(".cap-media-tile[data-active]") ?? shown()[0] ?? null;
85  let anchor: HTMLElement | null = null;
86  let unwire: (() => void) | null = null;
87  const tileOf = (el: Element | null) => el?.closest<HTMLElement>(".cap-media-tile") ?? null;
88  const byKey = (key: string) => tiles().find((t) => t.dataset.key === key) ?? null;
89  const modeOf = () => (getComputedStyle(layout).getPropertyValue("--cap-media-mode").trim() === "pane" ? "pane" : "sheet");
90  const openLink = (t: HTMLElement | null) => t?.querySelector<HTMLElement>(".cap-media-open") ?? null;
91
92  // ---- roving focus: one tile's controls take Tab, the arrows move between tiles.
93  const controlsOf = (t: HTMLElement) => Array.from(t.querySelectorAll<HTMLElement>(".cap-media-open, .cap-media-check > input, [data-cap-part='retry'], [data-cap-part='restore']"));
94  const syncRoving = () => {
95    for (const t of tiles()) {
96      const on = t === active;
97      for (const c of controlsOf(t)) c.tabIndex = on ? 0 : -1;
98      if (on) t.setAttribute("data-active", "");
99      else t.removeAttribute("data-active");
100      const link = openLink(t);
101      if (link) {
102        if (on && inspector?.open) link.setAttribute("aria-current", "true");
103        else link.removeAttribute("aria-current");
104      }
105    }
106  };
107  const setActive = (t: HTMLElement | null) => {
108    if (t === active) return;
109    active = t;
110    syncRoving();
111  };
112  const focusTile = (t: HTMLElement | null) => {
113    const link = openLink(t);
114    if (!t || !link) return;
115    setActive(t);
116    link.focus();
117    t.scrollIntoView({ block: "nearest" });
118  };
119  const move = (from: HTMLElement, dir: Direction): HTMLElement | null => {
120    const boxes = shown().map((t) => {
121      const r = t.getBoundingClientRect();
122      return { id: t.dataset.key ?? "", top: r.top, left: r.left, width: r.width };
123    });
124    const id = nextTile(bands(boxes), from.dataset.key ?? "", dir);
125    return id === null ? null : byKey(id);
126  };
127
128  // ---- selection: the real checkboxes; the tile mirrors them.
129  const boxOf = (t: HTMLElement) => t.querySelector<HTMLInputElement>(".cap-media-check > input");
130  const syncSelected = (t: HTMLElement) => {
131    const box = boxOf(t);
132    if (box?.checked) t.setAttribute("data-selected", "");
133    else t.removeAttribute("data-selected");
134  };
135  const selectedKeys = () => tiles().filter((t) => boxOf(t)?.checked).map((t) => t.dataset.key ?? "");
136  const toggle = (t: HTMLElement) => {
137    const box = boxOf(t);
138    if (box && !box.disabled) box.click();
139  };
140  const range = (to: HTMLElement) => {
141    const list = shown();
142    const a = list.indexOf(anchor ?? active ?? to);
143    const b = list.indexOf(to);
144    if (a < 0 || b < 0) return;
145    for (const t of list.slice(Math.min(a, b), Math.max(a, b) + 1)) {
146      const box = boxOf(t);
147      if (box && !box.checked) box.click();
148    }
149  };
150
151  // ---- the inspector.
152  let current: HTMLElement | null = null;
153  let session = 0;
154  const drafts = new Map<string, MediaFields>();
155  let autosave: Autosave | null = null;
156  const ins = <T extends HTMLElement = HTMLElement>(name: string) => (inspector ? part<T>(inspector, name) : null);
157
158  const renderSave = (state: SaveState, error?: string) => renderSaveState(inspector, state, error);
159
160  // Writes a record into the inspector's fields and lists. Idempotent: the server's own markup
161  // for the first file is what this would write.
162  const fill = (tile: HTMLElement) => {
163    if (!inspector) return;
164    const r = recordOf(tile);
165    const draft = drafts.get(r.key);
166    startSession(tile);
167    fillInspector(inspector, r, draft);
168    syncRoving();
169  };
170
171  const defaultSave = async (key: string, fields: MediaFields): Promise<void> => {
172    const form = ins<HTMLFormElement>("form");
173    if (!form) return;
174    const body = new FormData(form);
175    body.set("key", key);
176    const res = await fetch(form.getAttribute("action") || location.href, { method: (form.getAttribute("method") || "post").toUpperCase(), body, headers: { accept: "application/json" } });
177    if (!res.ok) throw new Error(`The server answered ${res.status}.`);
178    void fields;
179  };
180
181  // Applies saved fields to the tile, so the grid, the filters and the next open read them.
182  const applySaved = (tile: HTMLElement, f: MediaFields) => {
183    writeRecord(tile, { altState: altStateOf(f.alt, f.decorative), alt: f.alt, title: f.title, caption: f.caption, tags: f.tags });
184    syncTile(tile);
185    applyFilters(false);
186    updateCounts();
187  };
188
189  const startSession = (tile: HTMLElement | null) => {
190    session += 1;
191    const mine = session;
192    autosave?.cancel();
193    current = tile;
194    autosave = tile
195      ? createAutosave({
196          save: () => {
197            // Read now: this runs the moment a save starts, before anything else can change the fields.
198            const fields = readFields(inspector);
199            const key = tile.dataset.key ?? "";
200            const send = options.save ?? defaultSave;
201            return send(key, fields).then(
202              () => {
203                drafts.delete(key);
204                applySaved(tile, fields);
205              },
206              (err: unknown) => {
207                drafts.set(key, fields);
208                throw err;
209              },
210            );
211          },
212          onState: (s, err) => {
213            if (mine === session) renderSave(s, err);
214            else if (s === "failed") fail(`Could not save the changes to ${tile.dataset.label ?? "a file"}: ${err ?? "nothing says why"}. Open it again to retry.`);
215          },
216        })
217      : null;
218  };
219
220  const setTags = (tags: string[]) => {
221    const r = current ? recordOf(current) : null;
222    renderTags(inspector, tags, r?.suggestedTags ?? []);
223    autosave?.schedule();
224    void autosave?.flush();
225  };
226
227  const closePending = () => void autosave?.flush();
228
229  const showPane = () => {
230    if (!inspector || inspector.open) return;
231    inspector.show();
232  };
233
234  const openInspector = (tile: HTMLElement, o: { focus: boolean }) => {
235    if (!inspector) return;
236    setActive(tile);
237    const switching = current !== tile;
238    if (switching) {
239      closePending();
240      fill(tile);
241    }
242    if (modeOf() === "pane") {
243      if (inspector.matches(":modal")) inspector.close();
244      showPane();
245      syncRoving();
246      if (o.focus) firstField()?.focus();
247    } else if (!inspector.open || !inspector.matches(":modal")) {
248      if (inspector.open) inspector.close();
249      unwire?.();
250      unwire = wireDialog(inspector, { returnTo: openLink(tile) });
251      openDialog(inspector, openLink(tile), { focus: firstField() });
252      syncRoving();
253    }
254  };
255  const firstField = () => {
256    const alt = ins<HTMLTextAreaElement>("alt");
257    if (alt && !alt.disabled && !alt.closest("[hidden]")) return alt;
258    return ins<HTMLInputElement>("decorative") ?? ins<HTMLInputElement>("title-field");
259  };
260  const closeInspector = (o: { focus: boolean } = { focus: true }) => {
261    if (!inspector) return;
262    closePending();
263    const was = inspector.open;
264    if (was) inspector.close();
265    syncRoving();
266    if (was && o.focus) focusTile(active);
267  };
268
269  // ---- filters, search, view, size, counts.
270  const view = () => root.querySelector<HTMLInputElement>("[data-cap-part='view'] input:checked")?.value ?? "library";
271  const query = () => (root.querySelector<HTMLInputElement>("[data-cap-part='search']")?.value ?? "").trim().toLowerCase();
272  const chipsGroup = () => root.querySelector<HTMLElement>("[data-cap-part='filters']");
273  const pressed = () => {
274    const g = chipsGroup();
275    return g ? Array.from(g.querySelectorAll<HTMLElement>(".cap-chip[aria-pressed='true']")).map((c) => c.dataset.value ?? "") : [];
276  };
277  const matchesFilter = (t: HTMLElement, name: string): boolean => {
278    const r = recordOf(t);
279    if (name === "unattached") return r.used.length === 0;
280    if (name === "no-alt") return r.kind === "image" && r.altState === "missing";
281    if (name === "large") return r.bytes > LARGE_BYTES;
282    return true;
283  };
284  const haystack = (t: HTMLElement) => [t.dataset.label, t.dataset.altText, t.dataset.title, t.dataset.caption, t.dataset.tags, t.dataset.key].join(" ").toLowerCase();
285
286  // Where the active tile goes when it leaves the view (binned, filtered out): the next file that can be
287  // opened, else the one before it. An upload in progress is not a file to look at yet.
288  const settled = (t: HTMLElement) => t.dataset.state === "ready" || t.dataset.state === "binned";
289  const successor = (from: HTMLElement): HTMLElement | null => {
290    const list = shown();
291    const after = list.find((t) => settled(t) && from.compareDocumentPosition(t) & Node.DOCUMENT_POSITION_FOLLOWING);
292    if (after) return after;
293    const before = [...list].reverse().find((t) => settled(t) && from.compareDocumentPosition(t) & Node.DOCUMENT_POSITION_PRECEDING);
294    return before ?? list.find(settled) ?? list[0] ?? null;
295  };
296
297  const countEl = () => root.querySelector<HTMLElement>(".cap-media-count");
298  const applyFilters = (announce = true) => {
299    const v = view();
300    const q = query();
301    const names = pressed();
302    let visible = 0;
303    let matchable = 0;
304    let library = 0;
305    for (const t of tiles()) {
306      const state = t.dataset.state ?? "ready";
307      const inView = v === "bin" ? state === "binned" : state !== "binned";
308      if (state !== "binned") library += 1;
309      let show = inView;
310      const settled = state === "ready" || state === "binned";
311      // An upload in progress or a failed one stays in view: it is not a search result, it is news.
312      if (show && settled) {
313        if (q && !q.split(/\s+/).every((w) => haystack(t).includes(w))) show = false;
314        if (show && names.some((n) => !matchesFilter(t, n))) show = false;
315      }
316      t.hidden = !show;
317      // A file that is out of sight is not selected: an action must never reach what the person cannot see.
318      if (!show) {
319        const box = boxOf(t);
320        if (box?.checked) {
321          box.checked = false;
322          box.dispatchEvent(new Event("change", { bubbles: true }));
323        }
324      }
325      if (show) visible += 1;
326      if (show && settled) matchable += 1;
327    }
328    for (const g of root.querySelectorAll<HTMLElement>(".cap-media-group")) g.hidden = !g.querySelector(".cap-media-tile:not([hidden])");
329    const empty = root.querySelector<HTMLElement>(".cap-media-empty");
330    if (empty) {
331      const narrowed = !!q || names.length > 0;
332      const none = visible === 0 || (matchable === 0 && narrowed && v === "library");
333      const cause = !none ? "" : v === "bin" ? "bin" : q ? "search" : names.length ? "filter" : library === 0 ? "library" : "library";
334      empty.hidden = !none;
335      for (const child of empty.querySelectorAll<HTMLElement>("[data-cap-empty]")) child.hidden = child.dataset.capEmpty !== cause;
336    }
337    const count = countEl();
338    if (count && announce) {
339      const total = tiles().filter((t) => (v === "bin" ? t.dataset.state === "binned" : t.dataset.state === "ready")).length;
340      count.textContent = v === "bin" ? `${matchable} in Trash` : matchable === total ? `${matchable} ${matchable === 1 ? "file" : "files"}` : `${matchable} of ${total} files`;
341    }
342    if (active && (active.hidden || active.closest("[hidden]"))) {
343      const first = successor(active);
344      setActive(first);
345      if (inspector?.open) {
346        if (first) {
347          closePending();
348          fill(first);
349        } else closeInspector({ focus: false });
350      }
351    } else if (!active) setActive(shown()[0] ?? null);
352    syncRoving();
353  };
354  const updateCounts = () => {
355    const g = chipsGroup();
356    const lib = tiles().filter((t) => t.dataset.state === "ready");
357    if (g) {
358      for (const chip of g.querySelectorAll<HTMLElement>(".cap-chip")) {
359        const n = lib.filter((t) => matchesFilter(t, chip.dataset.value ?? "")).length;
360        const el = chip.querySelector<HTMLElement>(".cap-chip-count");
361        if (el) el.textContent = String(n);
362      }
363    }
364    const nLib = tiles().filter((t) => t.dataset.state === "ready").length;
365    const nBin = tiles().filter((t) => t.dataset.state === "binned").length;
366    for (const el of root.querySelectorAll<HTMLElement>("[data-cap-count='library']")) el.textContent = String(nLib);
367    for (const el of root.querySelectorAll<HTMLElement>("[data-cap-count='bin']")) el.textContent = String(nBin);
368  };
369
370  // ---- order: within each group, as the sort says. An upload in progress or a failed one stays first.
371  const sortBy = () => root.querySelector<HTMLInputElement>("[data-cap-part='sort'] input:checked")?.value ?? "";
372  const applySort = () => {
373    const by = sortBy();
374    if (!by) return;
375    const focused = document.activeElement;
376    const settledFirst = (t: HTMLElement) => (t.dataset.state === "uploading" || t.dataset.state === "failed" ? 0 : 1);
377    const cmp = (a: HTMLElement, b: HTMLElement): number => {
378      const pending = settledFirst(a) - settledFirst(b);
379      if (pending !== 0) return pending;
380      if (by === "name") return (a.dataset.label ?? "").localeCompare(b.dataset.label ?? "", undefined, { numeric: true, sensitivity: "base" });
381      if (by === "size") return Number(b.dataset.bytes ?? 0) - Number(a.dataset.bytes ?? 0);
382      return (b.dataset.uploaded ?? "").localeCompare(a.dataset.uploaded ?? "");
383    };
384    for (const grid of root.querySelectorAll<HTMLElement>(".cap-media-grid")) {
385      const list = Array.from(grid.children).filter((c): c is HTMLElement => c instanceof HTMLElement && c.classList.contains("cap-media-tile"));
386      const sorted = list.slice().sort(cmp);
387      if (sorted.every((t, i) => t === list[i])) continue;
388      grid.append(...sorted);
389    }
390    // Moving a node can drop focus; put it back.
391    if (focused instanceof HTMLElement && focused.isConnected && document.activeElement !== focused) focused.focus({ preventScroll: true });
392  };
393
394  // ---- Trash.
395  const rawBin = async (keys: string[], to: "binned" | "ready") => {
396    const before = keys.map((k) => ({ k, state: byKey(k)?.dataset.state ?? "ready" }));
397    for (const k of keys) {
398      const t = byKey(k);
399      if (!t) continue;
400      writeRecord(t, { state: to });
401      syncTile(t);
402    }
403    applyFilters();
404    updateCounts();
405    try {
406      await (to === "binned" ? options.bin : options.restore)?.(keys);
407    } catch (err) {
408      for (const b of before) {
409        const t = byKey(b.k);
410        if (t) {
411          t.dataset.state = b.state;
412          syncTile(t);
413        }
414      }
415      applyFilters();
416      updateCounts();
417      throw err;
418    }
419  };
420  const itemsOf = (keys: string[]): BulkItem[] => keys.map((k) => ({ id: k, label: byKey(k)?.dataset.label ?? k }));
421  const bin = (keys: string[]) =>
422    performBulk({
423      action: "bin",
424      items: itemsOf(keys),
425      run: () => rawBin(keys, "binned"),
426      undo: () => rawBin(keys, "ready"),
427      said: keys.length === 1 ? `Moved ${byKey(keys[0] ?? "")?.dataset.label ?? "the file"} to Trash.` : "Moved {n} files to Trash.",
428      undone: keys.length === 1 ? "Put it back in the library." : "Put {n} files back in the library.",
429      returnTo: openLink(active),
430    });
431  const restore = (keys: string[]) =>
432    performBulk({
433      action: "restore",
434      items: itemsOf(keys),
435      run: () => rawBin(keys, "ready"),
436      undo: () => rawBin(keys, "binned"),
437      said: keys.length === 1 ? `Restored ${byKey(keys[0] ?? "")?.dataset.label ?? "the file"} to the library.` : "Restored {n} files to the library.",
438      undone: keys.length === 1 ? "Put it back in Trash." : "Put {n} files back in Trash.",
439      returnTo: openLink(active),
440    });
441
442  // ---- events.
443  listen(root, "change", (e: Event) => {
444    const t = e.target;
445    if (!(t instanceof HTMLInputElement)) return;
446    const tile = tileOf(t);
447    if (tile && t.closest(".cap-media-check")) {
448      syncSelected(tile);
449      anchor = tile;
450      return;
451    }
452    if (inspector?.contains(t)) {
453      if (t.dataset.capPart === "decorative") {
454        const alt = ins<HTMLTextAreaElement>("alt");
455        if (alt) {
456          if (t.checked) {
457            alt.dataset.prev = alt.value;
458            alt.value = "";
459            alt.disabled = true;
460          } else {
461            alt.disabled = false;
462            alt.value = alt.dataset.prev ?? "";
463          }
464        }
465        autosave?.schedule();
466        void autosave?.flush();
467      }
468      return;
469    }
470    if (t.closest("[data-cap-part='view']")) {
471      applyFilters();
472      return;
473    }
474    if (t.closest("[data-cap-part='size']")) root.dataset.size = t.value;
475    else if (t.closest("[data-cap-part='layout']")) root.dataset.view = t.value;
476    else if (t.closest("[data-cap-part='sort']")) {
477      applySort();
478      syncRoving();
479    }
480  });
481
482  listen(root, "input", (e: Event) => {
483    const t = e.target;
484    if (!(t instanceof HTMLElement)) return;
485    if (inspector?.contains(t) && (t.dataset.capPart === "alt" || t.dataset.capPart === "title-field" || t.dataset.capPart === "caption")) autosave?.schedule();
486    else if (t.dataset.capPart === "search") applyFilters();
487  });
488
489  listen(root, "cap:filter-change", () => applyFilters());
490
491  listen(root, "focusout", (e: FocusEvent) => {
492    const t = e.target;
493    // A field that loses focus saves what was typed in it.
494    if (t instanceof HTMLElement && inspector?.contains(t) && /^(INPUT|TEXTAREA)$/.test(t.tagName) && t.dataset.capPart !== "tag-input") void autosave?.flush();
495    if (t instanceof HTMLElement && t.dataset.capPart === "tag-input") {
496      const input = t as HTMLInputElement;
497      if (input.value.trim()) addTagFrom(input);
498    }
499  });
500
501  const addTagFrom = (input: HTMLInputElement) => {
502    const add = parseTags(input.value);
503    input.value = "";
504    if (add.length === 0) return;
505    const have = parseTags(ins<HTMLInputElement>("tags-value")?.value ?? "");
506    setTags([...have, ...add.filter((t) => !have.includes(t))]);
507  };
508
509  listen(root, "focusin", (e: FocusEvent) => {
510    const t = e.target;
511    if (!(t instanceof Element)) return;
512    const tile = tileOf(t);
513    if (!tile || inspector?.contains(t)) return;
514    if (tile !== active) setActive(tile);
515    // The inspector follows the tile that has focus; focus stays where it is.
516    if (inspector?.open && !inspector.matches(":modal") && current !== tile && tile.dataset.state !== "uploading" && tile.dataset.state !== "failed") {
517      closePending();
518      fill(tile);
519    }
520  });
521
522  listen(root, "click", (e: MouseEvent) => {
523    const target = e.target instanceof Element ? e.target : null;
524    if (!target) return;
525    const tile = tileOf(target);
526    const open = target.closest<HTMLElement>(".cap-media-open");
527    if (tile && open && root.contains(open)) {
528      e.preventDefault();
529      if (e.shiftKey) return range(tile);
530      if (e.ctrlKey || e.metaKey) return toggle(tile);
531      if (open.getAttribute("aria-disabled") === "true") return;
532      return openInspector(tile, { focus: true });
533    }
534    const retry = target.closest<HTMLElement>("[data-cap-part='retry']");
535    if (retry && tile) {
536      const key = tile.dataset.key ?? "";
537      tile.dispatchEvent(new CustomEvent("cap-media-retry", { bubbles: true, detail: { key } }));
538      void options.retry?.(key);
539      return;
540    }
541    const restoreBtn = target.closest<HTMLElement>("[data-cap-part='restore']");
542    if (restoreBtn && tile) {
543      void restore([tile.dataset.key ?? ""]);
544      return;
545    }
546    if (target.closest("[data-cap-part='clear-search']")) {
547      const search = root.querySelector<HTMLInputElement>("[data-cap-part='search']");
548      if (search) {
549        search.value = "";
550        applyFilters();
551        search.focus();
552      }
553      return;
554    }
555    if (target.closest("[data-cap-part='clear-filters']")) {
556      const clear = chipsGroup()?.querySelector<HTMLElement>("[data-cap-part='clear']");
557      if (clear) clear.click();
558      return;
559    }
560    if (!inspector?.contains(target)) return;
561    const btn = target.closest<HTMLElement>("button");
562    if (!btn) return;
563    const p = btn.dataset.capPart;
564    if (p === "close") closeInspector();
565    else if (p === "bin" && current) void bin([current.dataset.key ?? ""]);
566    else if (p === "restore" && current) void restore([current.dataset.key ?? ""]);
567    else if (p === "retry-save") void autosave?.retry();
568    else if (p === "show-unattached") {
569      const chip = chipsGroup()?.querySelector<HTMLElement>(".cap-chip[data-value='unattached']");
570      if (chip && chip.getAttribute("aria-pressed") !== "true") chip.click();
571      if (chip) chip.focus();
572    } else if (btn.dataset.capTag !== undefined) {
573      const have = parseTags(ins<HTMLInputElement>("tags-value")?.value ?? "");
574      setTags(have.filter((x) => x !== btn.dataset.capTag));
575      ins("tag-input")?.focus();
576    } else if (btn.dataset.capSuggest !== undefined) {
577      const have = parseTags(ins<HTMLInputElement>("tags-value")?.value ?? "");
578      setTags([...have, btn.dataset.capSuggest]);
579      ins("tag-input")?.focus();
580    } else if (btn.dataset.capCopy !== undefined) {
581      void copyFrom(btn);
582    }
583  });
584
585  let copiedTimer: ReturnType<typeof setTimeout> | null = null;
586  const copyFrom = async (btn: HTMLElement) => {
587    const value = btn.dataset.capCopy || ins<HTMLInputElement>("address")?.value || "";
588    const what = btn.getAttribute("aria-label")?.replace(/^Copy (the )?/, "") || "address";
589    const status = ins("copied");
590    if (copiedTimer) clearTimeout(copiedTimer);
591    // Emptied first, so a second copy of the same thing is announced again.
592    status?.replaceChildren();
593    await Promise.resolve();
594    const ok = await copyText(value);
595    if (status) {
596      if (ok) status.replaceChildren(glyph("ok"), document.createTextNode(`Copied the ${what}.`));
597      else {
598        status.replaceChildren(glyph("crit"), document.createTextNode("Could not copy. The address is selected: press Ctrl+C or Cmd+C."));
599        ins<HTMLInputElement>("address")?.select();
600      }
601      copiedTimer = setTimeout(() => status.replaceChildren(), ok ? COPIED_MS : COPY_FAILED_MS);
602    }
603  };
604
605  // The inspector's keys: Enter in the tag field adds a tag; Esc goes back to the grid (a sheet
606  // closes by itself); Alt and an arrow move to the next file without leaving the field.
607  listen(root, "keydown", (e: KeyboardEvent) => {
608    const t = e.target instanceof HTMLElement ? e.target : null;
609    if (!t || e.defaultPrevented || e.isComposing) return;
610    if (inspector?.contains(t)) {
611      if (t.dataset.capPart === "tag-input" && (e.key === "Enter" || e.key === ",")) {
612        e.preventDefault();
613        addTagFrom(t as HTMLInputElement);
614        return;
615      }
616      if (e.altKey && !e.ctrlKey && !e.metaKey && current) {
617        const dir: Direction | null = e.key === "ArrowLeft" || e.key === "ArrowUp" ? "prev" : e.key === "ArrowRight" || e.key === "ArrowDown" ? "next" : null;
618        if (dir) {
619          e.preventDefault();
620          const next = move(current, dir);
621          if (next && next.dataset.state !== "uploading" && next.dataset.state !== "failed") {
622            closePending();
623            setActive(next);
624            fill(next);
625            next.scrollIntoView({ block: "nearest" });
626          }
627          return;
628        }
629      }
630      if (e.key === "Escape" && inspector.open && !inspector.matches(":modal")) {
631        e.preventDefault();
632        closePending();
633        focusTile(active);
634      }
635      return;
636    }
637    // Keys on a tile's own controls.
638    const tile = tileOf(t);
639    if (!tile || e.ctrlKey || e.metaKey || e.altKey) return;
640    const isControl = t.matches(".cap-media-open, .cap-media-check > input, [data-cap-part='retry'], [data-cap-part='restore']");
641    if (!isControl) return;
642    const dirs: Record<string, Direction> = { ArrowLeft: "left", ArrowRight: "right", ArrowUp: "up", ArrowDown: "down", Home: "first", End: "last" };
643    const dir = dirs[e.key];
644    if (dir) {
645      e.preventDefault();
646      const next = move(tile, dir);
647      if (next) focusTile(next);
648      return;
649    }
650    if (e.key === " " && !(t instanceof HTMLInputElement)) {
651      e.preventDefault();
652      toggle(tile);
653    } else if ((e.key === "x" || e.key === "X") && !e.shiftKey && !singleKeysOff()) {
654      e.preventDefault();
655      toggle(tile);
656    }
657  });
658
659  if (inspector) {
660    listen(inspector, "close", () => {
661      unwire?.();
662      unwire = null;
663      syncRoving();
664    });
665    listen(inspector, "submit", (e: Event) => {
666      // The form's own Save button is for a page with no script; with script the pane saves itself.
667      e.preventDefault();
668      void autosave?.flush();
669    });
670  }
671  // ---- mode: a pane beside the grid, or a sheet over it.
672  let lastMode = modeOf();
673  if (typeof ResizeObserver !== "undefined") {
674    const ro = new ResizeObserver(() => {
675      const m = modeOf();
676      if (m === lastMode) return;
677      lastMode = m;
678      if (!inspector) return;
679      const wasOpen = inspector.open;
680      if (!wasOpen) return;
681      if (m === "pane") {
682        if (inspector.matches(":modal")) {
683          inspector.close();
684          showPane();
685        }
686      } else if (!inspector.matches(":modal")) {
687        closePending();
688        inspector.close();
689      }
690      syncRoving();
691    });
692    ro.observe(root);
693    cleanups.push(() => ro.disconnect());
694  }
695
696  // ---- start.
697  for (const t of tiles()) syncSelected(t);
698  applySort();
699  if (inspector) {
700    if (inspector.open) {
701      if (modeOf() === "sheet") inspector.close();
702      else if (active) {
703        current = active;
704        // The server rendered the inspector for the active tile: start its session without rewriting it.
705        startSession(active);
706        renderSave("idle");
707      }
708    }
709  }
710  syncRoving();
711  enhanceMeters(root);
712  applyFilters(false);
713  updateCounts();
714
715  const controller: MediaController = {
716    open: (key) => {
717      const t = byKey(key);
718      if (t) openInspector(t, { focus: false });
719    },
720    close: () => closeInspector(),
721    setActive: (key) => setActive(byKey(key)),
722    selectedKeys,
723    add: (r) => {
724      const t = buildTile(r);
725      let grid = root.querySelector<HTMLElement>(".cap-media-grid");
726      if (!grid) {
727        grid = document.createElement("ul");
728        grid.className = "cap-media-grid";
729        grid.setAttribute("role", "list");
730        grid.setAttribute("aria-label", "Files");
731        (root.querySelector(".cap-media-empty") ?? root.querySelector(".cap-media-main"))?.before(grid);
732      }
733      grid.prepend(t);
734      applySort();
735      applyFilters();
736      updateCounts();
737      return t;
738    },
739    update: (key, patch) => {
740      const t = byKey(key);
741      if (!t) return;
742      const wasKey = t.dataset.key;
743      writeRecord(t, patch);
744      if (patch.state === "ready" && !t.querySelector(".cap-media-check")) {
745        // An upload that finished becomes a tile that can be opened and selected.
746        const fresh = buildTile(recordOf(t));
747        t.replaceWith(fresh);
748        if (active === t) active = fresh;
749        applySort();
750        applyFilters();
751        updateCounts();
752        return;
753      }
754      if (wasKey !== t.dataset.key) t.dataset.key = patch.key ?? wasKey ?? "";
755      if (patch.progress !== undefined && t.dataset.state === "uploading") {
756        const bar = t.querySelector<HTMLElement>(".cap-meter-bar");
757        const pct = Math.max(0, Math.min(100, Math.round(patch.progress)));
758        if (bar) {
759          bar.setAttribute("aria-valuenow", String(pct));
760          bar.setAttribute("aria-valuetext", `${pct} percent of ${t.dataset.label ?? "the file"} uploaded`);
761          const value = t.querySelector<HTMLElement>(".cap-meter-value");
762          if (value) value.textContent = `${pct}%`;
763          const open = openLink(t);
764          open?.setAttribute("aria-description", describeRecord({ ...recordOf(t), progress: pct }));
765          return;
766        }
767      }
768      syncTile(t);
769      applyFilters();
770      updateCounts();
771    },
772    bin,
773    restore,
774    bulkHandlers: () => ({
775      bin: { run: (items) => rawBin(items.map((i) => i.id), "binned"), undo: (items) => rawBin(items.map((i) => i.id), "ready"), said: "Moved {n} file{s} to Trash.", undone: "Put {n} file{s} back in the library." },
776      restore: { run: (items) => rawBin(items.map((i) => i.id), "ready"), undo: (items) => rawBin(items.map((i) => i.id), "binned"), said: "Restored {n} file{s} to the library.", undone: "Put {n} file{s} back in Trash." },
777      copy: {
778        run: async (items) => {
779          const urls = items.map((i) => byKey(i.id)?.dataset.url ?? "").filter(Boolean);
780          if (!(await copyText(urls.join("\n")))) throw new Error("the browser refused the clipboard");
781        },
782        said: "Copied the address of {n} file{s}.",
783      },
784      delete: {
785        run: async (items) => {
786          await options.delete?.(items.map((i) => i.id));
787          for (const i of items) byKey(i.id)?.remove();
788          applyFilters();
789          updateCounts();
790        },
791        said: "Deleted {n} file{s} for good.",
792      },
793      "add-tag": tagHandler(true),
794      "remove-tag": tagHandler(false),
795    }),
796    refresh: () => {
797      applyFilters();
798      updateCounts();
799      syncRoving();
800    },
801    detach: () => {
802      cleanups.forEach((f) => f());
803      unwire?.();
804      controllers.delete(root);
805      root.removeAttribute(READY);
806    },
807  };
808
809  // Bulk tags: add or remove one tag across the selection; undo reverses exactly what changed.
810  function tagHandler(adding: boolean): BulkHandler {
811    const changed = new WeakMap<object, string[]>();
812    const apply = async (items: readonly BulkItem[], value: string | undefined, add: boolean) => {
813      const tag = (value ?? "").trim().toLowerCase();
814      if (!tag) throw new Error("name a tag first");
815      const result = await applyBulkTag<HTMLElement>({
816        ids: items.map((i) => i.id),
817        wanted: tag,
818        adding: add,
819        missing: "no longer in the library",
820        read: async (id) => {
821          const t = byKey(id);
822          return t ? { item: t, tags: parseTags(t.dataset.tags ?? "") } : null;
823        },
824        write: async (id, t, tags) => {
825          t.dataset.tags = tags.join(", ");
826          await options.save?.(id, { ...recordFields(t), tags });
827        },
828      });
829      changed.set(items, result.done);
830      if (result.failed.length > 0) throw new Error(result.failed.join("; "));
831      updateCounts();
832    };
833    return {
834      run: (items, value) => apply(items, value, adding),
835      undo: async (items, value) => {
836        const did = changed.get(items) ?? [];
837        await apply(items.filter((i) => did.includes(i.id)), value, !adding);
838      },
839      said: adding ? "Added the tag to {n} file{s}." : "Removed the tag from {n} file{s}.",
840      undone: adding ? "Took the tag off {n} file{s}." : "Put the tag back on {n} file{s}.",
841    };
842  }
843  const recordFields = (t: HTMLElement): MediaFields => {
844    const r = recordOf(t);
845    return { alt: r.alt, decorative: r.altState === "decorative", title: r.title, caption: r.caption, tags: r.tags };
846  };
847
848  controllers.set(root, controller);
849  return controller;
850}
851
852// Attaches to every [data-cap="media"] under root not yet attached (with the default save, a POST
853// of the inspector's form). Returns a function that detaches them all.
854export function enhance(root: ParentNode = document): () => void {
855  const undo = Array.from(root.querySelectorAll<HTMLElement>("[data-cap='media']:not([data-cap-ready])")).map((el) => attachMedia(el).detach);
856  return () => undo.forEach((f) => f());
857}