components/media-library/media-library.ts

Functions

Imports

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

Source

1// The media library's pure helpers: the addresses of its views and filters, which actions a person
2// is offered here and why the others are withheld, the count, the empty state, the upload rules in
3// words, and which files the picker offers. No DOM; the React component and a server render use the
4// same functions.
5import type { ContentLabels, MediaData, MediaOffers, MediaQuery } from "../content/content.ts";
6import { acceptLabel, formatBytes } from "../drop-zone/drop-zone.ts";
7import type { MediaRecord } from "../media/media.ts";
8
9export function nounsOf(labels: ContentLabels = {}): { noun: string; plural: string } {
10  const noun = labels.noun ?? "file";
11  return { noun, plural: labels.plural ?? `${noun}s` };
12}
13
14// ---------------------------------------------------------------------------------------
15// Addresses.
16
17const QUERY_ORDER: ReadonlyArray<keyof MediaQuery> = ["q", "tag", "view", "layout", "lens", "cursor", "inspect", "pick"];
18
19// The library's address with a query, its keys in one fixed order and the empty or default ones
20// left out, so the same view is always the same address. `base` is the route.
21export function mediaHref(base: string, q: MediaQuery): string {
22  const params = new URLSearchParams();
23  for (const k of QUERY_ORDER) {
24    const v = q[k];
25    if (!v || (k === "view" && v === "library") || (k === "layout" && v === "grid")) continue;
26    params.set(k, v);
27  }
28  const path = base.split("?")[0] || "";
29  const s = params.toString();
30  return s ? `${path}?${s}` : path || "?";
31}
32
33// A filter or view change starts again at the first page, with the inspector and the pick closed;
34// opening a file (`inspect`, `pick`) keeps the page it is on.
35export function withMedia(q: MediaQuery, change: Partial<MediaQuery>): MediaQuery {
36  const next: MediaQuery = { ...q, ...change };
37  const opening = "inspect" in change || "pick" in change;
38  if (!opening) {
39    delete next.cursor;
40    delete next.inspect;
41    delete next.pick;
42  }
43  for (const k of Object.keys(change) as Array<keyof MediaQuery>) if (change[k] === undefined) delete next[k];
44  return next;
45}
46
47// ---------------------------------------------------------------------------------------
48// What is offered.
49
50export type MediaIntent = "add-tags" | "remove-tags" | "trash" | "restore" | "delete";
51
52export interface OfferedAction {
53  intent: MediaIntent;
54  label: string;
55  destructive?: boolean;
56}
57
58// The bulk actions this person may run on this view of this site, in the bar's order, and a
59// sentence for each one held back. Delete is for good: from Trash where the site has one, from
60// the library only where it has none.
61export function mediaActions(data: Pick<MediaData, "offers" | "can" | "query">, labels?: ContentLabels): { bulk: OfferedAction[]; withheld: string[] } {
62  const { plural } = nounsOf(labels);
63  const { offers, can } = data;
64  const trash = data.query.view === "trash";
65  const bulk: OfferedAction[] = [];
66  const withheld: string[] = [];
67  if (trash) {
68    if (can.deleteMedia && offers.trash) bulk.push({ intent: "restore", label: "Restore" });
69    if (can.deleteMedia && offers.delete) bulk.push({ intent: "delete", label: "Delete for good", destructive: true });
70  } else {
71    if (can.edit && offers.tags) bulk.push({ intent: "add-tags", label: "Add tag" }, { intent: "remove-tags", label: "Remove tag" });
72    if (can.deleteMedia && offers.trash) bulk.push({ intent: "trash", label: "Move to Trash" });
73    else if (can.deleteMedia && offers.delete) bulk.push({ intent: "delete", label: "Delete for good", destructive: true });
74  }
75  if (!can.edit) withheld.push(`You can look at these ${plural}. Changing them needs an editor's role.`);
76  else {
77    if (!offers.upload && !trash) withheld.push("Uploads are not offered by this site.");
78    if (!offers.alt) withheld.push("Alt text is set at upload here: this site cannot change it afterwards.");
79    if (!offers.tags && !trash) withheld.push(`Tags are not offered: this site keeps no tags on its ${plural}.`);
80  }
81  if (can.deleteMedia && !offers.delete && (trash || !offers.trash)) withheld.push(`Delete is not offered: this site cannot delete ${plural}.`);
82  return { bulk, withheld };
83}
84
85// What a file's inspector may do here.
86export function inspectorOffers(data: Pick<MediaData, "offers" | "can">): { alt: boolean; tags: boolean; trash: boolean; delete: boolean } {
87  const { offers, can } = data;
88  return { alt: can.edit && offers.alt, tags: can.edit && offers.tags, trash: can.deleteMedia && offers.trash, delete: can.deleteMedia && offers.delete };
89}
90
91// ---------------------------------------------------------------------------------------
92// Words.
93
94// "24 files", "Showing 48 of 210 files", "3 files in Trash".
95export function countLine(data: Pick<MediaData, "rows" | "page" | "query">, labels?: ContentLabels): string {
96  const { noun, plural } = nounsOf(labels);
97  const n = data.rows.length;
98  const total = data.page.total;
99  const word = (k: number) => (k === 1 ? noun : plural);
100  const base = total != null && total > n ? `Showing ${n} of ${total} ${word(total)}` : `${n} ${word(n)}`;
101  return data.query.view === "trash" ? `${base} in Trash` : base;
102}
103
104export function filtered(q: MediaQuery): boolean {
105  return !!(q.q || q.tag || q.lens);
106}
107
108// The empty state's title and line, naming what is not there.
109export function emptyWords(q: MediaQuery, labels?: ContentLabels): { kind: "nothing-yet" | "no-match" | "all-clear"; title: string; text: string } {
110  const { noun, plural } = nounsOf(labels);
111  if (filtered(q)) {
112    const what = [q.q ? `“${q.q}”` : null, q.tag ? `tag ${q.tag}` : null, q.lens ? `the ${q.lens} lens` : null].filter(Boolean).join(", ");
113    return { kind: "no-match", title: `No ${plural} match ${what}`, text: "Clear the filters to see every one." };
114  }
115  if (q.view === "trash") return { kind: "all-clear", title: "Trash is empty", text: `A ${noun} moved to Trash waits here until it is restored or deleted for good.` };
116  return { kind: "nothing-yet", title: `No ${plural} yet`, text: `Upload the first ${noun} and it shows here.` };
117}
118
119// The site's upload rules in words, for the drop zone's hint: "PNG, JPEG and WebP, up to 5 MB".
120// The picker takes images only; null when the site takes none.
121export function uploadRules(limits: NonNullable<MediaOffers["upload"]>, imagesOnly = false): { accept: string; hint: string } | null {
122  const types = imagesOnly ? limits.types.filter((t) => t.startsWith("image/")) : limits.types;
123  if (types.length === 0) return null;
124  const accept = types.join(",");
125  return { accept, hint: `${acceptLabel(accept)}, up to ${formatBytes(limits.maxBytes)}.` };
126}
127
128// The picker's files: images that are in the library and uploaded, nothing in Trash or on its
129// way.
130export function pickable(rows: readonly MediaRecord[]): MediaRecord[] {
131  return rows.filter((r) => r.kind === "image" && r.state === "ready");
132}