components/media/media-grid.react.tsx

Functions

Imports

It imports components/media/media.ts, components/status/status.react.tsx. Imported by components/media/media.react.tsx.

Source

1// The media library's React grid: MediaTile and MediaGrid (media.react.tsx).
2
3import { type KeyboardEvent, type ReactNode, useCallback, useId, useLayoutEffect, useRef } from "react";
4import { Glyph } from "../status/status.react.tsx";
5import { type Direction, type MediaRecord, bands, byteSize, describeRecord, flagsFor, nextTile } from "./media.ts";
6
7// ---------------------------------------------------------------------------------------
8// MediaTile: one file. Renders exactly the contract in the doc page: the open link (the tile's
9// one tab stop), the flags, the checkbox, and the progress or failure block.
10
11export interface MediaTileProps {
12  item: MediaRecord;
13  active?: boolean;
14  selected?: boolean;
15  // The inspector is open on the active tile: the link says aria-current.
16  inspecting?: boolean;
17  // Whether this tile's controls take Tab (roving: the active tile only).
18  tabStop?: boolean;
19  href?: string;
20  onOpen?: (key: string) => void;
21  onSelect?: (key: string, how: "toggle" | "range") => void;
22  onRetry?: (key: string) => void;
23  // A binned tile's Restore. Without it the tile has no Restore button (restore it from the
24  // bulk bar or the inspector).
25  onRestore?: (key: string) => void;
26  // The checkbox as a form field: named `ids`, in this form (by id), so a form post carries
27  // the ticked files with no script.
28  selectForm?: string;
29  // False for a list that only opens files (the picker): no checkbox.
30  selectable?: boolean;
31}
32
33function slug(key: string): string {
34  return key.replace(/[^a-z0-9]+/gi, "-").toLowerCase();
35}
36
37export function MediaTile({ item, active, selected, inspecting, tabStop = true, href, onOpen, onSelect, onRetry, onRestore, selectForm, selectable: canSelect = true }: MediaTileProps) {
38  const id = `tile-${slug(item.key)}`;
39  const flags = flagsFor(item);
40  const selectable = item.state === "ready" || item.state === "binned";
41  const checkable = selectable && canSelect;
42  const tab = tabStop ? 0 : -1;
43  const kind = item.type.split("/").pop()?.toUpperCase() ?? "";
44  const meta = item.state === "uploading" ? "Uploading" : item.state === "failed" ? "Not uploaded" : [kind, byteSize(item.bytes)].filter(Boolean).join(" · ");
45  const body = (
46    <>
47      <span className="cap-media-thumb">
48        {item.kind === "image" && item.thumb ? <img src={item.thumb} alt="" loading="lazy" decoding="async" width={320} height={320} /> : <span className="cap-media-doc" aria-hidden="true">{(item.name.split(".").pop() ?? "file").slice(0, 5).toUpperCase()}</span>}
49      </span>
50      <span className="cap-media-name" title={item.key}>
51        {item.name}
52      </span>
53      <span className="cap-media-meta">{meta}</span>
54    </>
55  );
56  const pct = Math.max(0, Math.min(100, Math.round(item.progress ?? 0)));
57  return (
58    <li
59      className="cap-media-tile"
60      id={id}
61      data-key={item.key}
62      data-label={item.name}
63      data-state={item.state}
64      data-kind={item.kind}
65      data-type={item.type}
66      data-bytes={item.bytes}
67      data-width={item.width}
68      data-height={item.height}
69      data-uploaded={item.uploaded}
70      data-url={item.url}
71      data-alt={item.altState}
72      data-alt-text={item.alt}
73      data-title={item.title}
74      data-caption={item.caption}
75      data-tags={item.tags.join(", ")}
76      data-used={item.used.length}
77      data-used-in={JSON.stringify(item.used)}
78      data-suggested-tags={JSON.stringify(item.suggestedTags ?? [])}
79      data-progress={item.state === "uploading" ? pct : undefined}
80      data-error={item.state === "failed" ? item.error : undefined}
81      data-active={active ? "" : undefined}
82      data-selected={selected ? "" : undefined}
83    >
84      {selectable ? (
85        <a
86          className="cap-media-open"
87          href={href ?? `?key=${encodeURIComponent(item.key)}`}
88          aria-describedby={`${id}-flags`}
89          aria-current={inspecting && active ? "true" : undefined}
90          tabIndex={tab}
91          onClick={(e) => {
92            e.preventDefault();
93            if (e.shiftKey) onSelect?.(item.key, "range");
94            else if (e.ctrlKey || e.metaKey) onSelect?.(item.key, "toggle");
95            else onOpen?.(item.key);
96          }}
97        >
98          {body}
99        </a>
100      ) : (
101        <button type="button" className="cap-media-open" aria-disabled="true" aria-describedby={`${id}-flags`} aria-description={describeRecord(item)} tabIndex={tab}>
102          {body}
103        </button>
104      )}
105      <span className="cap-media-flags" id={`${id}-flags`}>
106        {flags.map((f) => (
107          <span key={f.word} className="cap-status" data-tone={f.tone}>
108            <Glyph name={f.tone} />
109            {f.word}
110          </span>
111        ))}
112        {item.state === "binned" && onRestore ? (
113          <button type="button" className="cap-btn" data-size="xs" data-cap-part="restore" tabIndex={tab} onClick={() => onRestore?.(item.key)}>
114            Restore<span className="cap-sr-only"> {item.name}</span>
115          </button>
116        ) : null}
117      </span>
118      {checkable ? (
119        <label className="cap-media-check">
120          <input type="checkbox" name={selectForm ? "ids" : undefined} form={selectForm} value={item.key} data-cap-select="" aria-label={`Select ${item.name}`} checked={!!selected} tabIndex={tab} onChange={() => onSelect?.(item.key, "toggle")} />
121          <span className="cap-media-check-box" aria-hidden="true">
122            <svg viewBox="0 0 16 16">
123              <path fill="none" stroke="currentColor" strokeWidth="2.4" strokeLinecap="round" strokeLinejoin="round" d="M3.5 8.5l3 3 6-7" />
124            </svg>
125          </span>
126          <span className="cap-media-check-word" aria-hidden="true">
127            Selected
128          </span>
129        </label>
130      ) : null}
131      {item.state === "uploading" ? (
132        <div className="cap-media-state">
133          <div className="cap-meter" data-cap="meter">
134            <span className="cap-meter-label" id={`${id}-p`}>
135              Uploading
136            </span>
137            <span className="cap-meter-value">{pct}%</span>
138            <ProgressBar labelId={`${id}-p`} pct={pct} name={item.name} />
139          </div>
140        </div>
141      ) : null}
142      {item.state === "failed" ? (
143        <div className="cap-media-state" data-tone="crit">
144          <p className="cap-media-state-lead">
145            <Glyph name="crit" />
146            Upload failed
147          </p>
148          <p className="cap-media-reason">{item.error ?? "The server did not say why."}</p>
149          <button type="button" className="cap-btn" data-size="sm" data-cap-part="retry" tabIndex={tab} onClick={() => onRetry?.(item.key)}>
150            Retry<span className="cap-sr-only"> uploading {item.name}</span>
151          </button>
152        </div>
153      ) : null}
154    </li>
155  );
156}
157
158// The shared meter's bar, drawn as a progress bar: the fill's position is set through the CSSOM.
159function ProgressBar({ labelId, pct, name }: { labelId: string; pct: number; name: string }) {
160  const bar = useRef<HTMLSpanElement>(null);
161  useLayoutEffect(() => {
162    bar.current?.style.setProperty("--cap-meter-ratio", String(pct / 100));
163  }, [pct]);
164  return (
165    <span ref={bar} className="cap-meter-bar" role="progressbar" aria-labelledby={labelId} aria-valuemin={0} aria-valuemax={100} aria-valuenow={pct} aria-valuetext={`${pct} percent of ${name} uploaded`}>
166      <span className="cap-meter-fill" />
167    </span>
168  );
169}
170
171// ---------------------------------------------------------------------------------------
172// MediaGrid: the tiles, with roving focus and the arrow keys. Selection and the active file are the
173// app's state.
174
175export interface MediaGroup {
176  label: string;
177  items: readonly MediaRecord[];
178}
179
180export interface MediaGridProps {
181  // Either a flat list or groups under headings (a folder, a month).
182  items?: readonly MediaRecord[];
183  groups?: readonly MediaGroup[];
184  activeKey: string;
185  onActiveChange: (key: string) => void;
186  selected: readonly string[];
187  onSelectedChange: (keys: string[]) => void;
188  // Enter, or a click: open the inspector on this file.
189  onOpen: (key: string) => void;
190  inspecting?: boolean;
191  onRetry?: (key: string) => void;
192  onRestore?: (key: string) => void;
193  size?: "s" | "m" | "l";
194  label?: string;
195  // Where a tile's link goes with no script (its address); `?key=` by default.
196  hrefFor?: (key: string) => string;
197  // The tiles' checkboxes post as `ids` in this form (by id).
198  selectForm?: string;
199  // False: no checkboxes, Space and x do nothing (the picker opens a file and nothing else).
200  selectable?: boolean;
201}
202
203export function MediaGrid({ items, groups, activeKey, onActiveChange, selected, onSelectedChange, onOpen, inspecting, onRetry, onRestore, label = "Files", hrefFor, selectForm, selectable = true }: MediaGridProps) {
204  const root = useRef<HTMLDivElement>(null);
205  const all = groups ? groups.flatMap((g) => g.items) : (items ?? []);
206  const anchor = useRef<string>(activeKey);
207
208  const toggle = (key: string) => onSelectedChange(selected.includes(key) ? selected.filter((k) => k !== key) : [...selected, key]);
209  const select = (key: string, how: "toggle" | "range") => {
210    if (how === "range") {
211      const keys = all.filter((i) => i.state === "ready" || i.state === "binned").map((i) => i.key);
212      const a = keys.indexOf(anchor.current);
213      const b = keys.indexOf(key);
214      if (a >= 0 && b >= 0) {
215        const span = keys.slice(Math.min(a, b), Math.max(a, b) + 1);
216        onSelectedChange([...new Set([...selected, ...span])]);
217        return;
218      }
219    }
220    anchor.current = key;
221    toggle(key);
222  };
223
224  const focusKey = useCallback(
225    (key: string) => {
226      onActiveChange(key);
227      const link = root.current?.querySelector<HTMLElement>(`[data-key="${CSS.escape(key)}"] .cap-media-open`);
228      link?.focus();
229      link?.scrollIntoView({ block: "nearest" });
230    },
231    [onActiveChange],
232  );
233
234  const onKeyDown = (e: KeyboardEvent<HTMLElement>) => {
235    if (e.ctrlKey || e.metaKey || e.altKey) return;
236    const t = e.target as HTMLElement;
237    const tile = t.closest<HTMLElement>(".cap-media-tile");
238    if (!tile || !t.matches(".cap-media-open, .cap-media-check > input, .cap-btn")) return;
239    const here = tile.dataset.key ?? "";
240    const dirs: Record<string, Direction> = { ArrowLeft: "left", ArrowRight: "right", ArrowUp: "up", ArrowDown: "down", Home: "first", End: "last" };
241    const dir = dirs[e.key];
242    if (dir) {
243      e.preventDefault();
244      const boxes = Array.from(root.current?.querySelectorAll<HTMLElement>(".cap-media-tile") ?? []).map((el) => {
245        const r = el.getBoundingClientRect();
246        return { id: el.dataset.key ?? "", top: r.top, left: r.left, width: r.width };
247      });
248      const next = nextTile(bands(boxes), here, dir);
249      if (next) focusKey(next);
250    } else if (!selectable) {
251      return;
252    } else if (e.key === " " && !(t instanceof HTMLInputElement)) {
253      e.preventDefault();
254      select(here, "toggle");
255    } else if ((e.key === "x" || e.key === "X") && !e.shiftKey && document.documentElement.dataset.capSingleKeys !== "off") {
256      e.preventDefault();
257      select(here, "toggle");
258    }
259  };
260
261  const tiles = (list: readonly MediaRecord[]) =>
262    list.map((item) => (
263      <MediaTile
264        key={item.key}
265        item={item}
266        active={item.key === activeKey}
267        selected={selected.includes(item.key)}
268        inspecting={inspecting}
269        tabStop={item.key === activeKey}
270        onOpen={(k) => {
271          onActiveChange(k);
272          onOpen(k);
273        }}
274        onSelect={select}
275        onRetry={onRetry}
276        onRestore={onRestore}
277        href={hrefFor?.(item.key)}
278        selectForm={selectForm}
279        selectable={selectable}
280      />
281    ));
282
283  return (
284    <div ref={root} onKeyDown={onKeyDown} onFocus={(e) => {
285        const k = (e.target as HTMLElement).closest<HTMLElement>(".cap-media-tile")?.dataset.key;
286        if (k && k !== activeKey) onActiveChange(k);
287      }}>
288      {groups ? (
289        groups.map((g) => (
290          <GroupSection key={g.label} label={g.label} count={g.items.length} listLabel={`${label}, ${g.label}`}>
291            {tiles(g.items)}
292          </GroupSection>
293        ))
294      ) : (
295        <ul className="cap-media-grid" role="list" aria-label={label}>
296          {tiles(items ?? [])}
297        </ul>
298      )}
299    </div>
300  );
301}
302
303function GroupSection({ label, count, listLabel, children }: { label: string; count: number; listLabel: string; children: ReactNode }) {
304  const id = useId();
305  return (
306    <section className="cap-media-group" aria-labelledby={id}>
307      <h2 className="cap-media-group-title" id={id}>
308        {label} <span className="cap-media-group-count">{count} on this page</span>
309      </h2>
310      <ul className="cap-media-grid" role="list" aria-label={listLabel}>
311        {children}
312      </ul>
313    </section>
314  );
315}