app/lib/media/view.mjs

Functions

Imports

It imports app/lib/media/folders.mjs, app/lib/media/usage.mjs. Imported by app/components/admin/media-confirm-dialogs.tsx, app/components/admin/media-display-bar.tsx, app/components/admin/media-empty-state.tsx, app/components/admin/media-facets.tsx, app/components/admin/media-grid.tsx, app/components/admin/media-inspector.tsx, app/components/admin/media-list-header.tsx, app/components/admin/media-search.tsx, app/components/admin/media-tile.tsx, app/components/admin/media-trash-controls.tsx, app/routes/admin.media._index.tsx.

Source

1// Every link on this page is built by `hrefWith` from the WHOLE state: no gate can see a dropped query
2// parameter, so dropping one has to be a visible act rather than an omission.
3
4import { folderFor, folderRank } from "./folders.mjs";
5import { suggestedAlt } from "./usage.mjs";
6
7export const VIEWS = ["list", "grid"];
8
9export const GROUPS = ["flat", "folder", "month"];
10
11export const SORTS = ["added", "name", "size", "usage"];
12
13export const DIRS = ["desc", "asc"];
14
15/**
16 * A sort key carries its direction: "Largest" ascending would list the smallest. The Display popover and
17 * the list header both read this, so they produce the same URL for the same column.
18 *
19 * @type {Record<string, string>}
20 */
21const SORT_DEFAULT_DIR = {
22  added: "desc",
23  name: "asc",
24  size: "desc",
25  usage: "asc",
26};
27
28export const SIZES = ["s", "m", "l"];
29
30// `all` is the absence of a lens, so it is not a member.
31const LENSES = ["unattached", "duplicates", "no-alt", "large"];
32
33const CONFIRMS = ["empty-trash"];
34
35// LIST by default: most rows are PDFs, which a grid renders as empty boxes.
36export const DEFAULTS = {
37  view: "list",
38  // Folder by default: the section note is what says why a file exists.
39  group: "folder",
40  sort: "added",
41  dir: "desc",
42  size: "m",
43  role: "content",
44  q: "",
45  tag: "",
46  lens: "",
47  page: 1,
48  trash: false,
49  // In the state, so an open inspector survives a sort change.
50  key: "",
51  // A URL, not `prompt()`, so the confirmation works with scripting off. With no script a `prompt()`
52  // handler never runs and the form deletes straight through.
53  confirm: "",
54};
55
56export const PARAM_NAMES = Object.keys(DEFAULTS);
57
58/** @param {unknown} value @param {string[]} allowed @param {string} fallback */
59function oneOf(value, allowed, fallback) {
60  return typeof value === "string" && allowed.includes(value) ? value : fallback;
61}
62
63
64/**
65 * Total: an unrecognised value falls back to its default, so a hand-edited URL still shows a library.
66 *
67 * @param {{ get(name: string): string | null }} params
68 * @returns {typeof DEFAULTS}
69 */
70export function readView(params) {
71  const page = Number(params.get("page") ?? "1");
72  return {
73    view: oneOf(params.get("view"), VIEWS, DEFAULTS.view),
74    group: oneOf(params.get("group"), GROUPS, DEFAULTS.group),
75    sort: oneOf(params.get("sort"), SORTS, DEFAULTS.sort),
76    dir: oneOf(params.get("dir"), DIRS, DEFAULTS.dir),
77    size: oneOf(params.get("size"), SIZES, DEFAULTS.size),
78    // `all` asks for every role; an ABSENT role means the default, `content`.
79    role: typeof params.get("role") === "string" && params.get("role") !== ""
80      ? /** @type {string} */ (params.get("role"))
81      : DEFAULTS.role,
82    q: (params.get("q") ?? "").trim(),
83    tag: (params.get("tag") ?? "").trim().toLowerCase(),
84    lens: oneOf(params.get("lens"), LENSES, DEFAULTS.lens),
85    page: Number.isFinite(page) && page >= 1 ? Math.floor(page) : 1,
86    trash: params.get("trash") === "1",
87    // Not trimmed or lowercased: a key is an exact string, and many are paths.
88    key: params.get("key") ?? "",
89    confirm: oneOf(params.get("confirm"), CONFIRMS, DEFAULTS.confirm),
90  };
91}
92
93/**
94 * The only way a link on this page should be built. Defaults are omitted, so the bare URL is the
95 * default view and `Reset to defaults` can link to it.
96 *
97 * @param {typeof DEFAULTS} state
98 * @param {Partial<typeof DEFAULTS>} [overrides]
99 * @param {string} [base]
100 * @returns {string}
101 */
102export function hrefWith(state, overrides = {}, base = "/admin/media") {
103  const next = { ...state, ...overrides };
104  const search = new URLSearchParams();
105  for (const name of PARAM_NAMES) {
106    const value = /** @type {any} */ (next)[name];
107    const fallback = /** @type {any} */ (DEFAULTS)[name];
108    if (value === fallback) continue;
109    if (name === "trash") {
110      if (value) search.set("trash", "1");
111      continue;
112    }
113    if (name === "page") {
114      if (Number(value) > 1) search.set("page", String(value));
115      continue;
116    }
117    if (value === "" || value === null || value === undefined) continue;
118    search.set(name, String(value));
119  }
120  const query = search.toString();
121  return query ? `${base}?${query}` : base;
122}
123
124/**
125 * `page` is excluded: it is navigation, not a setting.
126 *
127 * @param {typeof DEFAULTS} state
128 * @returns {boolean}
129 */
130export function isModified(state) {
131  return PARAM_NAMES.filter((n) => n !== "page").some(
132    (n) => /** @type {any} */ (state)[n] !== /** @type {any} */ (DEFAULTS)[n],
133  );
134}
135
136/**
137 * PAGE-LOCAL, always: a group never spans a page boundary. Do not "fix" this; fetching the whole
138 * library or repeating a heading across pages are both worse. The SQL order is preserved.
139 *
140 * @template {{ key: string, uploaded?: string | null }} T
141 * @param {T[]} rows already sorted
142 * @param {string} group one of GROUPS
143 * @returns {Array<{ label: string, note: string, rows: T[] }>} one entry when flat
144 */
145export function groupRows(rows, group) {
146  if (group !== "folder" && group !== "month") return [{ label: "", note: "", rows }];
147
148  /** @type {Map<string, T[]>} */
149  const buckets = new Map();
150  for (const row of rows) {
151    const label = group === "folder" ? folderFor(row.key).prefix : monthOf(row.uploaded);
152    const bucket = buckets.get(label);
153    if (bucket) bucket.push(row);
154    else buckets.set(label, [row]);
155  }
156
157  const out = [...buckets.entries()].map(([label, bucketRows]) => {
158    if (group !== "folder") return { label, note: "", rows: bucketRows };
159    // The note travels with the section, so the component cannot forget to render it.
160    const folder = folderFor(bucketRows[0]?.key ?? "");
161    return { label: folder.title, note: folder.note, rows: bucketRows };
162  });
163
164  // Folder sections follow the table's order; month grouping keeps first-row order, since there the
165  // sort is the meaning.
166  if (group !== "folder") return out;
167  return out.sort(
168    (a, b) =>
169      folderRank(folderFor(a.rows[0]?.key ?? "").prefix) -
170      folderRank(folderFor(b.rows[0]?.key ?? "").prefix),
171  );
172}
173
174/**
175 * @param {string} key
176 * @returns {string}
177 */
178export function folderOf(key) {
179  const at = key.lastIndexOf("/");
180  if (at <= 0) return "Uploads";
181  return key.slice(0, at);
182}
183
184/**
185 * UTC, so a heading does not move with the reader's timezone.
186 *
187 * @param {string | null | undefined} uploaded ISO 8601
188 * @returns {string}
189 */
190export function monthOf(uploaded) {
191  const d = utcDate(uploaded);
192  if (!d) return "No upload date";
193  return `${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
194}
195
196/**
197 * The one parse, so the month heading and the Added cell under it cannot disagree about a date.
198 *
199 * @param {string | null | undefined} uploaded ISO 8601
200 * @returns {Date | null} null when absent or unparseable
201 */
202function utcDate(uploaded) {
203  if (!uploaded) return null;
204  const at = Date.parse(uploaded);
205  return Number.isNaN(at) ? null : new Date(at);
206}
207
208// Abbreviations are derived: all twelve are the first three letters (test/media-view-dates.test.mjs).
209const MONTHS = [
210  "January", "February", "March", "April", "May", "June",
211  "July", "August", "September", "October", "November", "December",
212];
213
214const MONTH_ABBR = MONTHS.map((m) => m.slice(0, 3));
215
216/**
217 * UTC, matching the month heading above it. Reads no clock.
218 *
219 * @param {string | null | undefined} uploaded ISO 8601
220 * @returns {string}
221 */
222export function formatAdded(uploaded) {
223  const d = utcDate(uploaded);
224  if (!d) return "in repo";
225  return `${String(d.getUTCDate()).padStart(2, "0")} ${MONTH_ABBR[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
226}
227
228/**
229 * No em dash allowed here, so an unmeasured row says so in words; 0x0 would be a claim.
230 *
231 * @param {number | null | undefined} width
232 * @param {number | null | undefined} height
233 * @returns {string}
234 */
235export function formatDims(width, height) {
236  return width && height ? `${width}×${height}` : "not measured";
237}
238
239/**
240 * Empty for a content-addressed key: unlike `folderOf`, which names a heading, it invents no folder.
241 *
242 * @param {string} key
243 * @returns {string}
244 */
245export function folderPrefix(key) {
246  const at = key.lastIndexOf("/");
247  return at > 0 ? `${key.slice(0, at)}/` : "";
248}
249
250/**
251 * The last segment: the roster photos share their directory and differ only at the end.
252 *
253 * @param {{ originalName: string | null, key: string }} object
254 * @returns {string}
255 */
256export function displayName(object) {
257  if (object.originalName) return object.originalName;
258  const last = object.key.split("/").pop();
259  return last && last.length > 0 ? last : object.key;
260}
261
262/**
263 * From the middle: these names differ at the end (`...session-01`, `...session-02`). The cap is 13
264 * because the name gets 109px on a 153px tile (measured; 14 clipped by a pixel). Characters, not
265 * pixels, because the server cannot measure a font; the CSS ellipsis is the backstop.
266 *
267 * @param {string} name
268 * @param {number} [max]
269 * @param {number} [tail]
270 * @returns {string}
271 */
272export function middleTruncate(name, max = 13, tail = 9) {
273  if (name.length <= max) return name;
274  return `${name.slice(0, max - tail - 1)}…${name.slice(-tail)}`;
275}
276
277/**
278 * Shared by the Display popover and the column headers so both produce one URL. Only the active column
279 * toggles. Always back to page one: page 3 of one sort is not page 3 of another.
280 *
281 * @param {typeof DEFAULTS} state
282 * @param {string} key one of SORTS
283 * @param {{ toggle?: boolean }} [options] toggle when the key is already active
284 * @returns {string}
285 */
286export function sortHref(state, key, options = {}) {
287  const active = state.sort === key;
288  const dir =
289    options.toggle && active
290      ? state.dir === "asc"
291        ? "desc"
292        : "asc"
293      : SORT_DEFAULT_DIR[key] ?? DEFAULTS.dir;
294  return hrefWith(state, { sort: key, dir, page: 1 });
295}
296
297/**
298 * A document card's title: the filename read as words, the same reading the alt suggestion makes.
299 * Not capitalised: title-casing a filename means guessing which words are proper nouns.
300 */
301export const docTitle = suggestedAlt;
302
303/**
304 * @param {typeof DEFAULTS} state
305 * @returns {string}
306 */
307export function displaySummary(state) {
308  const group = { flat: "Flat", folder: "Folder", month: "Month" }[state.group];
309  const sort = { added: "Newest", name: "A to Z", size: "Largest", usage: "Usage" }[state.sort];
310  return [group, sort, state.size.toUpperCase()].join(" · ");
311}
312
313// These never reach SQL, so a change skips the server (test/media-display-axes.test.mjs). `sort` and
314// `dir` must NOT be added: the page paginates, so reordering changes which rows page one holds.
315const DISPLAY_AXES = ["view", "group", "size"];
316
317/**
318 * Overlaid on the loader's view so a display change renders from the client URL with no revalidation.
319 *
320 * @param {{ get(name: string): string | null }} params
321 * @returns {{ view: string, group: string, size: string }}
322 */
323export function readDisplayAxes(params) {
324  return {
325    view: oneOf(params.get("view"), VIEWS, DEFAULTS.view),
326    group: oneOf(params.get("group"), GROUPS, DEFAULTS.group),
327    size: oneOf(params.get("size"), SIZES, DEFAULTS.size),
328  };
329}
330
331/**
332 * Identical URLs return FALSE: a post-action revalidation has the same URL on both sides, and skipping
333 * it would hide the write.
334 *
335 * @param {URL} currentUrl
336 * @param {URL} nextUrl
337 * @returns {boolean}
338 */
339export function onlyDisplayChanged(currentUrl, nextUrl) {
340  if (currentUrl.pathname !== nextUrl.pathname) return false;
341
342  const a = currentUrl.searchParams;
343  const b = nextUrl.searchParams;
344
345  // Compared through `readView` so `?view=list` and the bare URL count as the same state.
346  const from = readView(a);
347  const to = readView(b);
348  const names = /** @type {(keyof typeof from)[]} */ (PARAM_NAMES);
349  for (const name of names) {
350    if (DISPLAY_AXES.includes(name)) continue;
351    if (from[name] !== to[name]) return false;
352  }
353
354  return /** @type {(keyof typeof from)[]} */ (DISPLAY_AXES).some(
355    (name) => from[name] !== to[name],
356  );
357}