components/media-library/media-library.react.tsx

Functions

Imports

It imports components/content/content.react.tsx, components/content/content.ts, components/drop-zone/drop-zone.react.tsx, components/empty/empty.react.tsx, components/media-library/media-library.ts, components/media/media.react.tsx, components/media/media.ts, components/tabs/tabs.react.tsx. Imported by components/media-library/examples.tsx.

Source

1import { useEffect, useId, useMemo, useRef, useState, type FormEvent } from "react";
2import type { ContentLabels, IntentResult, MediaData, MediaQuery, PickedMedia, SubmitIntent } from "../content/content.ts";
3import { ContentBulkBar, PlainForm, useIntents, type FormComponent } from "../content/content.react.tsx";
4import { DropZone } from "../drop-zone/drop-zone.react.tsx";
5import { Empty } from "../empty/empty.react.tsx";
6import { MediaGrid, MediaInspector, useMediaMode, type MediaFields } from "../media/media.react.tsx";
7import { suggestedAlt } from "../media/media.ts";
8import { TabLink, TabsNav } from "../tabs/tabs.react.tsx";
9import { countLine, emptyWords, inspectorOffers, mediaActions, mediaHref, nounsOf, pickable, uploadRules, withMedia } from "./media-library.ts";
10
11export type { FormComponent, IntentResult, MediaData, PickedMedia, SubmitIntent };
12
13export interface MediaLibraryProps {
14  // The loader's view data: one page of one site's files.
15  data: MediaData;
16  // Where the forms post, and the library's own address: usually the route itself.
17  action: string;
18  Form?: FormComponent;
19  // The script path: posts a form and resolves with the action's result. With it, outcomes, Undo,
20  // the confirm dialog and the inspector's autosave happen in place.
21  submit?: SubmitIntent;
22  // The last result from the action, for the page that comes back after a post with no script.
23  result?: IntentResult | null;
24  labels?: ContentLabels;
25  // "library" (the default) manages files; "picker" offers images to insert, with an alt step.
26  mode?: "library" | "picker";
27  // How the inspector saves: "form" (the default), one form per field with its own Save button,
28  // which works with no script; or "autosave" (needs `submit`), saving by itself as you type.
29  inspector?: "form" | "autosave";
30  // Picker mode, with script: called with the file and the alt text written for this use, in
31  // place of posting `intent=pick`.
32  onPick?: (picked: PickedMedia) => void;
33}
34
35// One page of one site's files, the same component in Carrel and in every site admin: search, tag
36// chips, the library and Trash, the grid or list of tiles, upload checked against the site's limits,
37// the bulk bar with each file's outcome, the inspector (from ?inspect=) in form or autosave mode,
38// Undo, and the confirmation for what cannot be undone. In picker mode, the same grid offers images
39// and asks for the alt text this use needs. Every action is a form post, so it works with no
40// script; `submit` adds the in-place path.
41export function MediaLibrary({ data, action, Form = PlainForm, submit, result = null, labels, mode = "library", inspector = "form", onPick }: MediaLibraryProps) {
42  const uid = useId().replace(/[^a-zA-Z0-9]/g, "");
43  const formId = `${uid}-bulk`;
44  const { plural } = nounsOf(labels);
45  const title = mode === "picker" ? "Choose an image" : plural.charAt(0).toUpperCase() + plural.slice(1);
46  const [mounted, setMounted] = useState(false);
47  useEffect(() => setMounted(true), []);
48  const { rows, query, page, offers, can } = data;
49  const path = action.split("?")[0] ?? action;
50  const href = (q: MediaQuery) => mediaHref(path, q);
51  const picker = mode === "picker";
52  const trash = query.view === "trash";
53  const { bulk, withheld } = mediaActions(data, labels);
54  const selectable = !picker && bulk.length > 0;
55  const shown = picker ? pickable(rows) : rows;
56  const names = useMemo(() => new Map(rows.map((r) => [r.key, r.name])), [rows]);
57
58  const [selected, setSelected] = useState<string[]>([]);
59  useEffect(() => setSelected((s) => s.filter((k) => names.has(k))), [names]);
60  const [active, setActive] = useState(query.inspect ?? query.pick ?? shown[0]?.key ?? "");
61  const [chosen, setChosen] = useState<string | undefined>(query.pick);
62  useEffect(() => setChosen(query.pick), [query.pick]);
63  const intents = useIntents({ action, Form, submit, result, names, cancelHref: href(withMedia(query, {})), onDone: () => setSelected([]) });
64
65  // Moving to another view of the library (open a file, close it) with script is a GET of the
66  // library's own form, so the host's router (React Router's <Form>) makes it a navigation in the
67  // app and the loader reads the file with where it is used.
68  const goRef = useRef<HTMLDivElement>(null);
69  const [goTo, setGoTo] = useState<MediaQuery | null>(null);
70  useEffect(() => {
71    if (!goTo) return;
72    goRef.current?.querySelector("form")?.requestSubmit();
73  }, [goTo]);
74  const go = (q: MediaQuery) => setGoTo(q);
75
76  const layoutRef = useRef<HTMLDivElement>(null);
77  const inspectorMode = useMediaMode(layoutRef);
78  const insRef = useRef<{ focus: () => void }>(null);
79  const inspected = picker ? null : (data.inspected ?? null);
80  // A file the person opened (Enter or a click) gets focus in its first field once it is here; one
81  // that came with the page leaves focus where the page put it.
82  const opening = useRef(false);
83  useEffect(() => {
84    if (!opening.current) return;
85    opening.current = false;
86    if (picker) document.getElementById(`${uid}-pick-alt`)?.focus();
87    else insRef.current?.focus();
88  }, [inspected?.key, chosen, picker, uid]);
89  const iOffers = inspectorOffers(data);
90
91  // The inspector's autosave posts one `save` with every field the site keeps.
92  const save = async (key: string, fields: MediaFields) => {
93    if (!submit) return;
94    const form = new FormData();
95    form.set("intent", "save");
96    form.set("ids", key);
97    const version = rows.find((r) => r.key === key)?.version ?? inspected?.version;
98    if (version) form.set("version", version);
99    if (iOffers.alt) {
100      form.set("alt", fields.alt);
101      if (fields.decorative) form.set("decorative", "on");
102    }
103    if (iOffers.tags) form.set("tags", fields.tags.join(", "));
104    const r = await submit(form);
105    if (!r.ok) throw new Error(r.message);
106  };
107
108  // Picker mode with `onPick`: the alt step hands the file to the host instead of posting.
109  const onSubmit = (e: FormEvent<HTMLElement>) => {
110    const form = e.target;
111    if (onPick && form instanceof HTMLFormElement && form.dataset.capPart === "pick") {
112      e.preventDefault();
113      const fd = new FormData(form, (e.nativeEvent as SubmitEvent).submitter as HTMLButtonElement | null);
114      const item = rows.find((r) => r.key === fd.get("ids"));
115      if (item) onPick({ id: item.key, url: item.url, alt: fd.get("decorative") ? "" : String(fd.get("alt") ?? "").trim() });
116      return;
117    }
118    intents.onSubmit(e);
119  };
120
121  if (intents.confirmPage) {
122    return (
123      <section className="cap-media-lib" data-cap="media-library" aria-label={title}>
124        {intents.confirmPage}
125      </section>
126    );
127  }
128
129  const pick = picker && chosen ? rows.find((r) => r.key === chosen) : undefined;
130  const words = emptyWords(query, labels);
131  const rules = offers.upload ? uploadRules(offers.upload, picker) : null;
132  const canUpload = !!rules && can.edit && !trash;
133  const layout = query.layout ?? "grid";
134
135  return (
136    <section className="cap-media-lib" data-cap="media-library" data-mode={picker ? "picker" : undefined} aria-label={title} ref={(el) => void (intents.rootRef.current = el)} onSubmit={onSubmit}>
137      <div ref={goRef} hidden>
138        <Form method="get" action={path}>
139          {Object.entries(goTo ?? {}).map(([k, v]) => (v ? <input key={k} type="hidden" name={k} value={v} /> : null))}
140        </Form>
141      </div>
142
143      {!picker && offers.trash ? (
144        <TabsNav aria-label={`${title}: library or Trash`} className="cap-media-lib-tabs">
145          <TabLink href={href(withMedia(query, { view: undefined }))} current={!trash} count={data.counts?.library}>
146            Library
147          </TabLink>
148          <TabLink href={href(withMedia(query, { view: "trash" }))} current={trash} count={data.counts?.trash}>
149            Trash
150          </TabLink>
151        </TabsNav>
152      ) : null}
153
154      <Form method="get" action={path} className="cap-media-lib-filters" role="search" aria-label={`Find ${plural}`}>
155        {(["view", "layout", "tag", "lens"] as const).map((k) => (query[k] ? <input key={k} type="hidden" name={k} value={query[k]} /> : null))}
156        <div className="cap-field cap-media-lib-search">
157          <label className="cap-field-label" htmlFor={`${uid}-q`}>
158            Search
159          </label>
160          <input className="cap-input" type="search" id={`${uid}-q`} name="q" defaultValue={query.q ?? ""} />
161        </div>
162        <button type="submit" className="cap-btn">
163          Show
164        </button>
165      </Form>
166
167      {data.tags.length || data.extra?.lenses?.length ? (
168        <nav className="cap-media-lib-chips" aria-label={`Narrow the ${plural}`}>
169          {data.tags.length ? (
170            <ul className="cap-chips" aria-label="Tags">
171              <li>
172                <a className="cap-chip" href={href(withMedia(query, { tag: undefined }))} aria-current={!query.tag ? "true" : undefined}>
173                  Any tag
174                </a>
175              </li>
176              {data.tags.map((t) => (
177                <li key={t.tag}>
178                  <a className="cap-chip" href={href(withMedia(query, { tag: t.tag }))} aria-current={query.tag === t.tag ? "true" : undefined}>
179                    {t.tag}
180                    {t.count != null ? <span className="cap-chip-count">{t.count}</span> : null}
181                  </a>
182                </li>
183              ))}
184            </ul>
185          ) : null}
186          {data.extra?.lenses?.length && !picker ? (
187            <ul className="cap-chips" aria-label="Lenses">
188              {data.extra.lenses.map((l) => (
189                <li key={l.id}>
190                  <a className="cap-chip" href={href(withMedia(query, { lens: query.lens === l.id ? undefined : l.id }))} aria-current={query.lens === l.id ? "true" : undefined}>
191                    {l.label}
192                    {l.count != null ? <span className="cap-chip-count">{l.count}</span> : null}
193                  </a>
194                </li>
195              ))}
196            </ul>
197          ) : null}
198        </nav>
199      ) : null}
200
201      <div className="cap-media-lib-bar">
202        <p className="cap-media-lib-count">{shown.length === 0 ? "" : countLine({ ...data, rows: shown }, labels)}</p>
203        <div className="cap-media-lib-tools">
204          {!picker ? (
205            <nav className="cap-media-lib-layout" aria-label="Show as">
206              <a className="cap-chip" href={href(withMedia(query, { layout: undefined }))} aria-current={layout === "grid" ? "true" : undefined}>
207                Grid
208              </a>
209              <a className="cap-chip" href={href(withMedia(query, { layout: "list" }))} aria-current={layout === "list" ? "true" : undefined}>
210                List
211              </a>
212            </nav>
213          ) : null}
214          {!picker && data.extra?.toolbar?.length ? (
215            <Form method="post" action={action} className="cap-media-lib-extra">
216              {data.extra.toolbar.map((a) => (
217                <button key={a.intent} type="submit" className="cap-btn" name="intent" value={a.intent}>
218                  {a.label}
219                </button>
220              ))}
221            </Form>
222          ) : null}
223        </div>
224      </div>
225
226      {!picker && withheld.length ? (
227        <ul className="cap-media-lib-withheld">
228          {withheld.map((w) => (
229            <li key={w}>{w}</li>
230          ))}
231        </ul>
232      ) : null}
233
234      {canUpload && rules ? (
235        <Form method="post" action={action} encType="multipart/form-data" className="cap-media-lib-upload" aria-label={`Upload a ${nounsOf(labels).noun}`}>
236          <input type="hidden" name="intent" value="upload" />
237          <DropZone name="file" accept={rules.accept} maxBytes={offers.upload?.maxBytes} hint={rules.hint} />
238          <div className="cap-field">
239            <label className="cap-field-label" htmlFor={`${uid}-upalt`}>
240              Alt text
241            </label>
242            <input className="cap-input" id={`${uid}-upalt`} name="alt" type="text" autoComplete="off" aria-describedby={`${uid}-upalt-help`} />
243            <p className="cap-field-help" id={`${uid}-upalt-help`}>
244              What the picture shows, for a person who cannot see it. You can add it later.
245            </p>
246          </div>
247          <button type="submit" className="cap-btn" data-variant="primary">
248            Upload
249          </button>
250        </Form>
251      ) : null}
252
253      {intents.resultBox}
254
255      {selectable ? (
256        <ContentBulkBar
257            formId={formId}
258            action={action}
259            Form={Form}
260            formClass="cap-media-lib-bulk-form"
261            items={rows.filter((r) => selected.includes(r.key)).map((r) => ({ id: r.key, label: r.name }))}
262            total={shown.length}
263            onSelectAll={mounted ? () => setSelected(shown.filter((r) => r.state === "ready" || r.state === "binned").map((r) => r.key)) : undefined}
264            onClear={() => setSelected([])}
265            plural={plural}
266            actions={bulk}
267            tag={bulk.some((a) => a.intent === "add-tags")}
268            intents={intents}
269          />
270      ) : null}
271
272      <div className="cap-media" data-size="m" data-view={layout === "list" ? "list" : undefined}>
273        <div className="cap-media-layout" ref={layoutRef}>
274          <div className="cap-media-main">
275            {shown.length === 0 ? (
276              <Empty
277                kind={words.kind}
278                title={words.title}
279                action={
280                  words.kind === "no-match" ? (
281                    <a className="cap-btn" href={href(withMedia(query, { q: undefined, tag: undefined, lens: undefined }))}>
282                      Clear filters
283                    </a>
284                  ) : undefined
285                }
286              >
287                {words.text}
288              </Empty>
289            ) : (
290              <MediaGrid
291                items={shown}
292                activeKey={active}
293                onActiveChange={setActive}
294                selected={selected}
295                onSelectedChange={setSelected}
296                selectable={selectable}
297                selectForm={selectable ? formId : undefined}
298                hrefFor={(key) => href(withMedia(query, picker ? { pick: key } : { inspect: key }))}
299                onOpen={(key) => {
300                  if (key === (picker ? chosen : inspected?.key)) {
301                    if (picker) document.getElementById(`${uid}-pick-alt`)?.focus();
302                    else insRef.current?.focus();
303                    return;
304                  }
305                  opening.current = true;
306                  if (picker) return setChosen(key);
307                  go(withMedia(query, { inspect: key }));
308                }}
309                inspecting={!!inspected}
310                label={picker ? "Images" : trash ? "Files in Trash" : "Files"}
311              />
312            )}
313          </div>
314          {inspected ? (
315            <MediaInspector
316              ref={insRef}
317              id={`${uid}-ins`}
318              item={inspected}
319              open
320              mode={inspectorMode}
321              onSave={save}
322              onClose={() => go(withMedia(query, { inspect: undefined }))}
323              onStep={(dir) => {
324                const keys = shown.filter((r) => r.state === "ready" || r.state === "binned").map((r) => r.key);
325                const next = keys[keys.indexOf(inspected.key) + (dir === "next" ? 1 : -1)];
326                if (next) go(withMedia(query, { inspect: next }));
327              }}
328              show={{ alt: iOffers.alt, title: false, caption: false, tags: iOffers.tags }}
329              saving={inspector === "autosave" && submit ? "auto" : "form"}
330              action={action}
331              Form={Form}
332              closeHref={href(withMedia(query, { inspect: undefined }))}
333              can={{ trash: iOffers.trash, delete: iOffers.delete && (trash || !offers.trash) }}
334            />
335          ) : null}
336        </div>
337      </div>
338
339      {pick ? (
340        <Form method="post" action={action} className="cap-media-pick" data-cap-part="pick" aria-labelledby={`${uid}-pick-h`}>
341          <input type="hidden" name="intent" value="pick" />
342          <input type="hidden" name="ids" value={pick.key} />
343          <h3 className="cap-media-pick-title" id={`${uid}-pick-h`}>
344            Alt text for {pick.name}
345          </h3>
346          {pick.thumb ? <img className="cap-media-pick-preview" src={pick.thumb} alt="" width={160} height={160} /> : null}
347          <div className="cap-field">
348            <label className="cap-field-label" htmlFor={`${uid}-pick-alt`}>
349              Alt text (required)
350            </label>
351            <textarea className="cap-input" id={`${uid}-pick-alt`} name="alt" rows={2} required defaultValue={pick.alt} aria-describedby={`${uid}-pick-help`} />
352            <p className="cap-field-help" id={`${uid}-pick-help`}>
353              What a person who cannot see the picture needs to know here. {pick.alt ? "It starts with the file's own alt text." : `Suggested: ${suggestedAlt(pick.name)}.`}
354            </p>
355          </div>
356          <div className="cap-media-pick-actions">
357            <button type="submit" className="cap-btn" data-variant="primary">
358              Insert
359            </button>
360            <button type="submit" className="cap-btn" name="decorative" value="on" formNoValidate>
361              Insert as decorative
362            </button>
363            <a className="cap-btn" data-variant="quiet" href={href(withMedia(query, { pick: undefined }))} onClick={(e) => {
364                if (!mounted) return;
365                e.preventDefault();
366                setChosen(undefined);
367              }}>
368              Choose another
369            </a>
370          </div>
371        </Form>
372      ) : null}
373
374      {query.cursor || page.nextCursor ? (
375        <nav className="cap-media-lib-pages" aria-label={`${title} pages`}>
376          {query.cursor ? (
377            <a className="cap-btn" href={href(withMedia(query, {}))}>
378              First page
379            </a>
380          ) : null}
381          {page.nextCursor ? (
382            <a className="cap-btn" href={href({ ...withMedia(query, {}), cursor: page.nextCursor })}>
383              Next page
384            </a>
385          ) : null}
386        </nav>
387      ) : null}
388
389      {intents.confirmDialog}
390    </section>
391  );
392}