app/lib/media/usage.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/admin/media-inspector-sections.tsx, app/components/admin/media-inspector.tsx, app/components/admin/media-tile.tsx, app/db/media.ts, app/lib/media/view.mjs, app/routes/admin.media._index.tsx.

Source

1// Three states, not two: post evidence cannot see an asset placed by route code, so without "in template"
2// the roster photos read as orphans beside a delete button. "Unattached" is an ABSENCE of evidence, not
3// "unused". A file both cited and referenced reports USED, the claim that can name a post.
4
5export const USAGE_STATES = {
6  used: {
7    id: "used",
8    label: "used",
9    title: "Referenced by a post",
10    note: "The usage tracker found this address in published content.",
11  },
12  template: {
13    id: "template",
14    label: "in template",
15    title: "Placed by page code",
16    note:
17      "Found by scanning the repository, not the post index. A post-level " +
18      "tracker will always report this file as unreferenced.",
19  },
20  unattached: {
21    id: "unattached",
22    label: "unattached",
23    title: "No reference found",
24    note:
25      "Not found in posts or in repository code. Unattached is not the same as " +
26      "unused: a file can still be linked from outside the site, and a path the " +
27      "code builds at runtime is invisible to the scan. Verify before deleting.",
28  },
29};
30
31export const USAGE_ORDER = ["used", "template", "unattached"];
32
33/**
34 * @param {{ postRefs: number, citations: number, templateRefs: number }} evidence
35 * @returns {"used"|"template"|"unattached"}
36 */
37export function usageStateOf(evidence) {
38  if (evidence.postRefs > 0 || evidence.citations > 0) return "used";
39  if (evidence.templateRefs > 0) return "template";
40  return "unattached";
41}
42
43/**
44 * @param {string} state
45 * @returns {{ id: string, label: string, title: string, note: string }}
46 */
47export function usageDescriptor(state) {
48  return /** @type {Record<string, typeof USAGE_STATES.used>} */ (USAGE_STATES)[state]
49    ?? USAGE_STATES.unattached;
50}
51
52/**
53 * @param {string} state
54 * @returns {number}
55 */
56export function usageRank(state) {
57  const at = USAGE_ORDER.indexOf(state);
58  return at < 0 ? USAGE_ORDER.length : at;
59}
60
61export const LARGE_FILE_BYTES = 1024 * 1024;
62
63/**
64 * `noAlt` applies to images only: a document takes no alt text.
65 *
66 *
67 * @param {{ viewable: boolean, alt: string | null, size: number, twinCount: number }} row
68 * @returns {Array<{ id: string, label: string }>}
69 */
70export function flagsFor(row) {
71  /** @type {Array<{ id: string, label: string }>} */
72  const out = [];
73  if (row.twinCount > 0) out.push({ id: "duplicate", label: "duplicate" });
74  if (row.viewable && !(row.alt ?? "").trim()) out.push({ id: "no-alt", label: "no alt" });
75  if (row.size > LARGE_FILE_BYTES) out.push({ id: "large", label: "over 1 MB" });
76  return out;
77}
78
79/**
80 * One dot: on a 150px tile three is a rash. Ordered by what the reader can lose by not knowing.
81 *
82 *
83 * @param {{ flags: Array<{ id: string, label: string }>, usage: string, twin: string | null }} row
84 * @returns {{ id: string, title: string } | null}
85 */
86export function tileFlagFor(row) {
87  /** @param {string} id */
88  const has = (id) => row.flags.some((f) => f.id === id);
89  if (has("duplicate")) {
90    return { id: "duplicate", title: row.twin ? `Duplicate of ${row.twin}` : "Duplicate" };
91  }
92  if (row.usage === "unattached") return { id: "unattached", title: "No reference found" };
93  if (has("no-alt")) return { id: "no-alt", title: "No alt text" };
94  return null;
95}
96
97export const LENS_NOTES = {
98  unattached:
99    "No reference was found in posts or in repository code. That is not proof a " +
100    "file is unused: check before deleting.",
101  duplicates:
102    "These files share a content hash with another file. Both addresses serve " +
103    "the same bytes.",
104  "no-alt":
105    "Images published without alt text. Documents are not listed; they do not " +
106    "take alt text.",
107  large: "Large files slow the pages that embed them. Consider a smaller derivative.",
108};
109
110/**
111 * @param {string} lens
112 * @returns {string}
113 */
114export function lensNoteFor(lens) {
115  return /** @type {Record<string, string>} */ (LENS_NOTES)[lens] ?? "";
116}
117
118/**
119 * Offered, never applied: alt text nobody read is worse than a visibly empty field.
120 *
121 * @param {string} base a filename, no directory
122 * @returns {string}
123 */
124export function suggestedAlt(base) {
125  return base.replace(/\.[a-z0-9]+$/i, "").replace(/[-_]+/g, " ").trim();
126}
127
128/**
129 * @param {string} key
130 * @returns {string[]}
131 */
132export function suggestedTags(key) {
133  const parts = key.split("/").filter(Boolean);
134  /** @type {string[]} */
135  const out = [];
136  // A content-addressed key has no directory, and its first segment is a hash, not a label.
137  const leading = parts[0];
138  if (key.startsWith("/") && parts.length > 1 && leading) {
139    out.push(leading.replace(/[-_]+/g, " "));
140  }
141  const year = key.match(/\b(20\d{2})\b/)?.[1];
142  if (year) out.push(year);
143  const term = key.match(/\b(spring|fall|summer|winter)\b/i)?.[1];
144  if (term) out.push(term.toLowerCase());
145  return [...new Set(out.map((t) => t.trim().toLowerCase()).filter(Boolean))];
146}
147
148/**
149 * An image goes in as `![alt](src)` and a document as `[title](href)`; an `<img>` for a PDF breaks the page.
150 *
151 * @param {{ url: string, viewable: boolean, alt: string | null, base: string }} row
152 * @returns {Array<{ id: string, label: string, name: string, value: string }>}
153 */
154export function copySnippetsFor(row) {
155  const alt = (row.alt ?? "").trim();
156  const title = suggestedAlt(row.base);
157  // `label` is what the button shows, `name` what a screen reader hears: the visible "Copy" group
158  // heading supplies the verb only for sighted readers.
159  if (row.viewable) {
160    return [
161      { id: "address", label: "Copy address", name: "Copy the address", value: row.url },
162      { id: "markdown", label: "Markdown", name: "Copy the markdown image", value: `![${alt}](${row.url})` },
163      { id: "html", label: "HTML tag", name: "Copy the HTML image tag", value: `<img src="${row.url}" alt="${alt}">` },
164    ];
165  }
166  return [
167    { id: "address", label: "Copy address", name: "Copy the address", value: row.url },
168    { id: "markdown", label: "Markdown", name: "Copy the markdown link", value: `[${title}](${row.url})` },
169    { id: "html", label: "HTML link", name: "Copy the HTML link", value: `<a href="${row.url}">${title}</a>` },
170  ];
171}