components/media/media.react.tsx

Functions

Imports

It imports components/dialog/dialog.ts, components/media/media-actions.ts, components/media/media-grid.react.tsx, components/media/media.ts, components/status/status.react.tsx. Imported by components/media-library/media-library.react.tsx, components/media/examples.tsx.

Source

1import { type ComponentType, type FormHTMLAttributes, type KeyboardEvent, type ReactNode, type Ref, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
2import { openDialog, wireDialog } from "../dialog/dialog.ts";
3import { Glyph } from "../status/status.react.tsx";
4import { type Autosave, type MediaFields, type MediaRecord, type SaveState, byteSize, copySnippets, copyText, createAutosave, parseTags, suggestedAlt } from "./media.ts";
5import { COPIED_MS, COPY_FAILED_MS } from "./media-actions.ts";
6
7export { MediaTile, MediaGrid } from "./media-grid.react.tsx";
8export type { MediaTileProps, MediaGroup, MediaGridProps } from "./media-grid.react.tsx";
9
10export type { MediaFields, MediaRecord } from "./media.ts";
11
12// ---------------------------------------------------------------------------------------
13// MediaInspector: the details of one file, in a pane beside the grid or a side sheet over it, saving
14// by itself. A failed save keeps what was typed, in the form and in `drafts`, so switching files
15// and coming back does not lose it.
16
17const drafts = new Map<string, MediaFields>();
18
19export type MediaMode = "pane" | "sheet";
20
21// Reads how the inspector sits ("pane" or "sheet") from the layout's container query, and follows
22// it as the container resizes. Put the ref on the element with class cap-media-layout.
23export function useMediaMode(layout: { current: HTMLElement | null }): MediaMode {
24  const [mode, setMode] = useState<MediaMode>("pane");
25  useLayoutEffect(() => {
26    const el = layout.current;
27    if (!el) return;
28    const read = () => setMode(getComputedStyle(el).getPropertyValue("--cap-media-mode").trim() === "pane" ? "pane" : "sheet");
29    read();
30    const ro = new ResizeObserver(read);
31    ro.observe(el);
32    return () => ro.disconnect();
33  }, [layout]);
34  return mode;
35}
36
37export interface MediaInspectorProps {
38  // The file, or null for none.
39  item: MediaRecord | null;
40  open: boolean;
41  mode: MediaMode;
42  // Sends the fields. Reject with an Error that says why; the pane shows it and Retry.
43  onSave: (key: string, fields: MediaFields) => Promise<void>;
44  onClose: () => void;
45  onBin?: (key: string) => void;
46  onRestore?: (key: string) => void;
47  // The grid's Unattached filter, from the "Show unattached files" button.
48  onShowUnattached?: () => void;
49  // The tile that opened a sheet: focus returns here.
50  opener?: HTMLElement | null;
51  // Alt and an arrow in a field: the previous or next file. The app moves its active key.
52  onStep?: (dir: "prev" | "next") => void;
53  id?: string;
54  // focus() puts focus in the first field: call it when the person asked to open the inspector (Enter on a tile).
55  ref?: Ref<{ focus: () => void }>;
56  // Which fields it shows. All by default; a site that keeps no title or caption leaves them out.
57  show?: { alt?: boolean; title?: boolean; caption?: boolean; tags?: boolean };
58  // "auto" (the default) saves by itself through onSave. "form" is one form per field with its
59  // own Save button, posting to `action`, so it works with no script.
60  saving?: "auto" | "form";
61  // Where its forms post: the fields in form mode, and Move to Trash, Restore and Delete in
62  // either mode (each a form with `intent`, `ids` and `version`). Without it those are buttons.
63  action?: string;
64  // The host router's form component, for those forms.
65  Form?: ComponentType<FormHTMLAttributes<HTMLFormElement> & { method?: "get" | "post" }>;
66  // Close as a link to this address (the list without ?inspect=), so it works with no script.
67  closeHref?: string;
68  // What the footer offers. Trash and Restore by default; Delete only when given.
69  can?: { trash?: boolean; delete?: boolean };
70}
71
72const PlainForm: NonNullable<MediaInspectorProps["Form"]> = (props) => <form {...props} />;
73
74// The hidden fields every inspector form carries: what it is about and the version last seen.
75function Ident({ item, intent }: { item: MediaRecord; intent: string }) {
76  return (
77    <>
78      <input type="hidden" name="intent" value={intent} />
79      <input type="hidden" name="ids" value={item.key} />
80      {item.version ? <input type="hidden" name="version" value={item.version} /> : null}
81    </>
82  );
83}
84
85const SAVE_TEXT: Record<SaveState, string> = { idle: "Changes save by themselves.", dirty: "Unsaved changes", saving: "Saving…", saved: "Saved", failed: "Could not save" };
86
87export function MediaInspector(props: MediaInspectorProps) {
88  const { item, open, mode, onClose, opener, id, ref: handle } = props;
89  const own = useId();
90  const base = id ?? own;
91  const ref = useRef<HTMLDialogElement>(null);
92  const unwire = useRef<(() => void) | null>(null);
93  const first = useRef<HTMLElement | null>(null);
94  useImperativeHandle(handle, () => ({ focus: () => first.current?.focus() }), []);
95
96  useEffect(() => {
97    const d = ref.current;
98    if (!d) return;
99    const modal = d.matches(":modal");
100    if (open && item && mode === "pane") {
101      if (modal) d.close();
102      if (!d.open) d.show();
103    } else if (open && item && mode === "sheet") {
104      if (!modal) {
105        if (d.open) d.close();
106        unwire.current?.();
107        unwire.current = wireDialog(d, { returnTo: opener ?? null });
108        openDialog(d, opener ?? document.activeElement, { focus: first.current });
109      }
110    } else if (d.open) d.close();
111  }, [open, item, mode, opener]);
112
113  useEffect(() => {
114    const d = ref.current;
115    if (!d) return;
116    const onCloseEvent = () => {
117      unwire.current?.();
118      unwire.current = null;
119      if (open) onClose();
120    };
121    d.addEventListener("close", onCloseEvent);
122    return () => d.removeEventListener("close", onCloseEvent);
123  }, [open, onClose]);
124
125  const titleId = `${base}-title`;
126  return (
127    <dialog ref={ref} className="cap-dialog cap-media-inspector" data-cap="media-inspector" data-placement="right" data-size="md" id={base} aria-labelledby={titleId} open={open && mode === "pane" && !!item}>
128      {item ? <InspectorBody key={item.key} {...props} item={item} base={base} titleId={titleId} firstRef={first} /> : <p className="cap-dialog-body">Select a file to see its details.</p>}
129    </dialog>
130  );
131}
132
133function InspectorBody({ item, onSave, onClose, onBin, onRestore, onShowUnattached, onStep, base, titleId, firstRef, show = {}, saving = "auto", action, Form: F = PlainForm, closeHref, can = {} }: MediaInspectorProps & { item: MediaRecord; base: string; titleId: string; firstRef: { current: HTMLElement | null } }) {
134  const formMode = saving === "form" && !!action;
135  const shows = { alt: show.alt ?? true, title: show.title ?? true, caption: show.caption ?? true, tags: show.tags ?? true };
136  const draft = drafts.get(item.key);
137  const initial: MediaFields = draft ?? { alt: item.alt, decorative: item.altState === "decorative", title: item.title, caption: item.caption, tags: item.tags };
138  const [fields, setFields] = useState<MediaFields>(initial);
139  const [tagText, setTagText] = useState("");
140  const [state, setState] = useState<SaveState>(draft ? "failed" : "idle");
141  const [error, setError] = useState<string | undefined>(draft ? "the last save did not go through" : undefined);
142  const [copied, setCopied] = useState<ReactNode>(null);
143  const latest = useRef(fields);
144  latest.current = fields;
145  const onSaveRef = useRef(onSave);
146  onSaveRef.current = onSave;
147  const saver = useRef<Autosave | null>(null);
148  if (!saver.current) {
149    saver.current = createAutosave({
150      save: () => {
151        const f = latest.current;
152        const clean: MediaFields = { alt: f.decorative ? "" : f.alt.trim(), decorative: f.decorative, title: f.title.trim(), caption: f.caption.trim(), tags: f.tags };
153        return onSaveRef.current(item.key, clean).then(
154          () => void drafts.delete(item.key),
155          (err: unknown) => {
156            drafts.set(item.key, f);
157            throw err;
158          },
159        );
160      },
161      onState: (s, e) => {
162        setState(s);
163        setError(e);
164      },
165    });
166  }
167  // Leaving this file saves what is unsaved first.
168  useEffect(
169    () => () => {
170      void saver.current?.flush();
171    },
172    [],
173  );
174  const edit = (patch: Partial<MediaFields>, now = false) => {
175    const next = { ...latest.current, ...patch };
176    latest.current = next;
177    setFields(next);
178    // In form mode each form's own Save button sends it.
179    if (formMode) return;
180    saver.current?.schedule();
181    if (now) void saver.current?.flush();
182  };
183
184  const img = item.kind === "image";
185  const url = item.url;
186  const snippets = copySnippets({ url, kind: item.kind, alt: fields.alt, name: item.name });
187  const copy = async (value: string, what: string) => {
188    setCopied(null);
189    const ok = await copyText(value);
190    setCopied(
191      ok ? (
192        <>
193          <Glyph name="ok" />
194          Copied the {what}.
195        </>
196      ) : (
197        <>
198          <Glyph name="crit" />
199          Could not copy. The address is selected: press Ctrl+C or Cmd+C.
200        </>
201      ),
202    );
203    window.setTimeout(() => setCopied(null), ok ? COPIED_MS : COPY_FAILED_MS);
204  };
205  const sub = [item.type.split("/").pop()?.toUpperCase(), byteSize(item.bytes), item.width && item.height ? `${item.width} by ${item.height}` : ""].filter(Boolean).join(" · ");
206  const addTag = (text: string) => {
207    const add = parseTags(text);
208    if (add.length) edit({ tags: [...fields.tags, ...add.filter((t) => !fields.tags.includes(t))] }, true);
209    setTagText("");
210  };
211  const onKeyDown = (e: KeyboardEvent<HTMLElement>) => {
212    if (e.altKey && !e.ctrlKey && !e.metaKey && (e.key === "ArrowLeft" || e.key === "ArrowUp" || e.key === "ArrowRight" || e.key === "ArrowDown")) {
213      e.preventDefault();
214      void saver.current?.flush();
215      onStep?.(e.key === "ArrowLeft" || e.key === "ArrowUp" ? "prev" : "next");
216    }
217  };
218  const binned = item.state === "binned";
219  // One autosaving form, or (form mode) a plain block holding one form per group of fields.
220  const BodyTag = formMode ? "div" : "form";
221
222  return (
223    <>
224      <div className="cap-dialog-header" data-divider>
225        <h2 className="cap-dialog-title cap-media-title" id={titleId} data-cap-part="title">
226          {item.name}
227        </h2>
228        <p className="cap-dialog-description" data-cap-part="subtitle">{sub}</p>
229      </div>
230      <BodyTag
231        className="cap-dialog-body cap-media-form"
232        data-cap-part="form"
233        {...(formMode
234          ? { onKeyDown }
235          : {
236              method: "post",
237              "aria-busy": state === "saving" ? true : undefined,
238              onKeyDown,
239              onSubmit: (e: { preventDefault: () => void }) => {
240                e.preventDefault();
241                void saver.current?.flush();
242              },
243              onBlur: (e: { target: EventTarget }) => {
244                const t = e.target as HTMLElement;
245                if (/^(INPUT|TEXTAREA)$/.test(t.tagName) && t.dataset.capPart !== "tag-input") void saver.current?.flush();
246              },
247            })}
248      >
249        <input type="hidden" name="key" value={item.key} data-cap-part="key" />
250        <div className="cap-media-preview">
251          {img && item.thumb ? <img data-cap-part="preview" src={item.thumb} alt="" width={640} height={427} /> : <span className="cap-media-doc" aria-hidden="true">{(item.name.split(".").pop() ?? "file").slice(0, 5).toUpperCase()}</span>}
252        </div>
253        {img && shows.alt ? (
254          <Wrap on={formMode} F={F} action={action} label="Alt text" intent="save-alt" item={item} save="Save alt text">
255            <div className="cap-field" data-cap-part="alt-field">
256              <label className="cap-field-label" htmlFor={`${base}-alt`}>
257                Alt text
258              </label>
259              <textarea
260                ref={(el) => {
261                  if (el && !el.disabled) firstRef.current = el;
262                }}
263                className="cap-input"
264                id={`${base}-alt`}
265                name="alt"
266                data-cap-part="alt"
267                rows={2}
268                placeholder="Describe what the picture shows"
269                aria-describedby={`${base}-alt-help`}
270                disabled={fields.decorative && !formMode}
271                value={fields.decorative ? "" : fields.alt}
272                onChange={(e) => edit({ alt: e.target.value })}
273              />
274              <p className="cap-field-help" id={`${base}-alt-help`}>
275                What a person who cannot see the picture needs to know. Leave out “image of”. {fields.alt.trim() ? "" : `Suggested: ${suggestedAlt(item.name)}.`}
276              </p>
277            </div>
278            <div className="cap-field" data-cap-part="decorative-field">
279              <label className="cap-check">
280                <input type="checkbox" name="decorative" data-cap-part="decorative" aria-describedby={`${base}-deco-help`} checked={fields.decorative} onChange={(e) => edit({ decorative: e.target.checked, alt: e.target.checked ? "" : fields.alt }, true)} /> Decorative image
281              </label>
282              <p className="cap-field-help" id={`${base}-deco-help`}>
283                It adds nothing a reader needs, so a screen reader skips it. This is a choice, not a missing description.
284              </p>
285            </div>
286          </Wrap>
287        ) : !img ? (
288          <p className="cap-field-help" data-cap-part="alt-document">A document takes no alt text. What a reader hears is the link text, and that lives in the post.</p>
289        ) : null}
290        {shows.title || shows.caption ? (
291          <Wrap on={formMode} F={F} action={action} label="Title and caption" intent="save-details" item={item} save="Save title and caption">
292            {shows.title ? (
293              <div className="cap-field">
294                <label className="cap-field-label" htmlFor={`${base}-title-field`}>
295                  Title
296                </label>
297                <input className="cap-input" id={`${base}-title-field`} data-cap-part="title-field" name="title" type="text" autoComplete="off" value={fields.title} onChange={(e) => edit({ title: e.target.value })} />
298              </div>
299            ) : null}
300            {shows.caption ? (
301              <div className="cap-field">
302                <label className="cap-field-label" htmlFor={`${base}-caption`}>
303                  Caption
304                </label>
305                <textarea className="cap-input" id={`${base}-caption`} data-cap-part="caption" name="caption" rows={2} value={fields.caption} onChange={(e) => edit({ caption: e.target.value })} />
306              </div>
307            ) : null}
308          </Wrap>
309        ) : null}
310        {shows.tags && formMode ? (
311          <Wrap on F={F} action={action} label="Tags" intent="save-tags" item={item} save="Save tags">
312            <div className="cap-field">
313              <label className="cap-field-label" htmlFor={`${base}-tags-text`}>
314                Tags
315              </label>
316              <input className="cap-input" id={`${base}-tags-text`} name="tags" type="text" autoComplete="off" aria-describedby={`${base}-tags-help`} value={fields.tags.join(", ")} onChange={(e) => edit({ tags: parseTags(e.target.value) })} />
317              <p className="cap-field-help" id={`${base}-tags-help`}>
318                Separate tags with commas.
319              </p>
320            </div>
321          </Wrap>
322        ) : null}
323        {shows.tags && !formMode ? (
324        <div className="cap-media-section" role="group" aria-labelledby={`${base}-tags-l`}>
325          <span className="cap-field-label" id={`${base}-tags-l`}>
326            Tags
327          </span>
328          <ul className="cap-media-tags" data-cap-part="tags">
329            {fields.tags.map((t) => (
330              <li key={t}>
331                <button type="button" className="cap-chip" aria-label={`Remove tag ${t}`} onClick={() => edit({ tags: fields.tags.filter((x) => x !== t) }, true)}>
332                  {t} <span aria-hidden="true">×</span>
333                </button>
334              </li>
335            ))}
336          </ul>
337          <input type="hidden" name="tags" value={fields.tags.join(", ")} data-cap-part="tags-value" />
338          <label className="cap-sr-only" htmlFor={`${base}-tag-input`}>
339            Add a tag
340          </label>
341          <input
342            className="cap-input"
343            id={`${base}-tag-input`}
344            type="text"
345            autoComplete="off"
346            placeholder="Add a tag, then press Enter"
347            data-cap-part="tag-input"
348            value={tagText}
349            onChange={(e) => setTagText(e.target.value)}
350            onKeyDown={(e) => {
351              if (e.key === "Enter" || e.key === ",") {
352                e.preventDefault();
353                addTag(tagText);
354              }
355            }}
356            onBlur={() => tagText.trim() && addTag(tagText)}
357          />
358          <ul className="cap-media-tags" data-cap-part="suggestions">
359            {(item.suggestedTags ?? [])
360              .filter((t) => !fields.tags.includes(t))
361              .map((t) => (
362                <li key={t}>
363                  <button type="button" className="cap-chip" aria-label={`Add suggested tag ${t}`} onClick={() => edit({ tags: [...fields.tags, t] }, true)}>
364                    + {t}
365                  </button>
366                </li>
367              ))}
368          </ul>
369        </div>
370        ) : null}
371        <div className="cap-media-section" role="group" aria-labelledby={`${base}-addr-l`}>
372          <label className="cap-field-label" id={`${base}-addr-l`} htmlFor={`${base}-addr`}>
373            Address
374          </label>
375          <input className="cap-input" id={`${base}-addr`} data-cap-part="address" readOnly value={url} />
376          <div className="cap-media-copy">
377            {snippets.map((s) => (
378              <button key={s.id} type="button" className="cap-btn" data-size="sm" data-cap-copy-kind={s.id} aria-label={s.name} onClick={() => void copy(s.value, s.name.replace(/^Copy (the )?/, ""))}>
379                {s.label}
380              </button>
381            ))}
382          </div>
383          <p className="cap-media-copied" role="status" data-cap-part="copied">
384            {copied}
385          </p>
386        </div>
387        <dl className="cap-media-facts" data-cap-part="facts">
388          <dt>Key</dt>
389          <dd>{item.key}</dd>
390          <dt>Type</dt>
391          <dd>{item.type || "unknown"}</dd>
392          <dt>Size</dt>
393          <dd>{byteSize(item.bytes)}</dd>
394          <dt>Dimensions</dt>
395          <dd>{item.width && item.height ? `${item.width} by ${item.height}` : "not measured"}</dd>
396          <dt>Uploaded</dt>
397          <dd>{item.uploaded ?? "ships with the site"}</dd>
398        </dl>
399        <section className="cap-media-section" aria-labelledby={`${base}-used-l`}>
400          <h3 id={`${base}-used-l`}>Used in</h3>
401          <div data-cap-part="used">
402            {item.usedUnknown ? (
403              <p className="cap-media-note">Where it is used was not checked for this list. Open the file to see.</p>
404            ) : item.used.length > 0 ? (
405              <ul className="cap-media-used">
406                {item.used.map((u) => (
407                  <li key={u.href}>
408                    <a href={u.href}>{u.title}</a>
409                    {u.how ? <span className="cap-media-used-how">{u.how}</span> : null}
410                  </li>
411                ))}
412              </ul>
413            ) : (
414              <>
415                <p className="cap-media-used-empty">Not used anywhere.</p>
416                <p className="cap-media-note">
417                  No post cites this file. That is not proof it is unused: a page built in code can still use it, so check before you delete it. The Unattached filter lists every file like this.{" "}
418                  {onShowUnattached ? (
419                    <button type="button" className="cap-btn" data-variant="link" onClick={onShowUnattached}>
420                      Show unattached files
421                    </button>
422                  ) : null}
423                </p>
424              </>
425            )}
426          </div>
427        </section>
428      </BodyTag>
429      <div className="cap-dialog-footer">
430        {formMode ? null : (
431        <div className="cap-media-save" data-cap-part="save" data-state={state}>
432          <p role="status" data-cap-part="save-status">
433            {state !== "failed" ? (
434              <>
435                {state === "saving" ? <Glyph name="running" /> : state === "saved" ? <Glyph name="ok" /> : state === "dirty" ? <Glyph name="info" /> : null}
436                {SAVE_TEXT[state]}
437              </>
438            ) : null}
439          </p>
440          <p role="alert" data-cap-part="save-error">
441            {state === "failed" ? (
442              <>
443                <Glyph name="crit" />
444                Could not save{error ? `: ${error.replace(/\.$/, "")}` : ""}. What you typed is still here.
445              </>
446            ) : null}
447          </p>
448          <button type="button" className="cap-btn" data-size="sm" data-cap-part="retry-save" hidden={state !== "failed"} onClick={() => void saver.current?.retry()}>
449            Retry
450          </button>
451        </div>
452        )}
453        {action ? (
454          <>
455            {binned ? (
456              <F method="post" action={action} className="cap-media-act">
457                <Ident item={item} intent="restore" />
458                <button type="submit" className="cap-btn" data-cap-part="restore">
459                  Restore
460                </button>
461              </F>
462            ) : can.trash !== false ? (
463              <F method="post" action={action} className="cap-media-act">
464                <Ident item={item} intent="trash" />
465                <button type="submit" className="cap-btn" data-cap-part="bin">
466                  Move to Trash
467                </button>
468              </F>
469            ) : null}
470            {can.delete ? (
471              <F method="post" action={action} className="cap-media-act">
472                <Ident item={item} intent="delete" />
473                <button type="submit" className="cap-btn" data-variant="danger" data-cap-part="delete">
474                  Delete for good
475                </button>
476              </F>
477            ) : null}
478          </>
479        ) : binned ? (
480          <button type="button" className="cap-btn" data-cap-part="restore" onClick={() => onRestore?.(item.key)}>
481            Restore
482          </button>
483        ) : (
484          <button type="button" className="cap-btn" data-cap-part="bin" onClick={() => onBin?.(item.key)}>
485            Move to Trash
486          </button>
487        )}
488      </div>
489      {closeHref ? (
490        <a className="cap-btn cap-dialog-close" data-variant="quiet" data-icon-only data-cap-part="close" aria-label="Close" href={closeHref} onClick={(e) => {
491            e.preventDefault();
492            onClose();
493          }}>
494          <CloseGlyph />
495        </a>
496      ) : (
497        <button type="button" className="cap-btn cap-dialog-close" data-variant="quiet" data-icon-only data-cap-part="close" aria-label="Close" onClick={onClose}>
498          <CloseGlyph />
499        </button>
500      )}
501    </>
502  );
503}
504
505function CloseGlyph() {
506  return (
507    <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">
508      <path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
509    </svg>
510  );
511}
512
513// In form mode, a group of fields is its own form with its own Save button, posting `intent`, the
514// file's id and its version; otherwise the fields sit in the inspector's one autosaving form.
515function Wrap({ on, F, action, label, intent, item, save, children }: { on: boolean; F: NonNullable<MediaInspectorProps["Form"]>; action?: string; label: string; intent: string; item: MediaRecord; save: string; children: ReactNode }) {
516  if (!on || !action) return <>{children}</>;
517  return (
518    <F method="post" action={action} className="cap-media-field-form" aria-label={label}>
519      <Ident item={item} intent={intent} />
520      {children}
521      <button type="submit" className="cap-btn" data-size="sm">
522        {save}
523      </button>
524    </F>
525  );
526}