components/media/media-record.ts

Functions

Imports

It imports no other module of this repo. Imported by components/media/media-inspector.ts, components/media/media-tile.ts, components/media/media.ts.

Source

1// The media library's records: the facts of one file and the plain functions that read them.
2
3// ---------------------------------------------------------------------------------------
4// The records, pure.
5
6export type AltState = "missing" | "decorative" | "set";
7export type TileState = "ready" | "uploading" | "failed" | "binned";
8
9export interface UsedIn {
10  title: string;
11  href: string;
12  // How the post uses it: "image in the body", "cover".
13  how?: string;
14}
15
16export interface MediaRecord {
17  key: string;
18  name: string;
19  url: string;
20  thumb?: string;
21  kind: "image" | "document";
22  type: string;
23  bytes: number;
24  width?: number;
25  height?: number;
26  uploaded?: string;
27  alt: string;
28  altState: AltState;
29  title: string;
30  caption: string;
31  tags: string[];
32  used: UsedIn[];
33  state: TileState;
34  suggestedTags?: string[];
35  progress?: number;
36  error?: string;
37  // The site's version of the file's metadata (site-api v0.4): a form posts it back as the
38  // version it last saw.
39  version?: string;
40  // Where it is used was not read (a list of files has no usedBy; the inspected one does): no
41  // Unattached flag, and the inspector says it was not checked.
42  usedUnknown?: boolean;
43}
44
45// What the inspector edits.
46export interface MediaFields {
47  alt: string;
48  decorative: boolean;
49  title: string;
50  caption: string;
51  tags: string[];
52}
53
54// Decimal unit names, binary division: the site's own rule, so a size reads the same on both.
55export function byteSize(size: number): string {
56  if (size < 1024) return `${size} B`;
57  if (size < 1024 * 1024) return `${Math.round(size / 1024)} kB`;
58  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
59}
60
61export const LARGE_BYTES = 1024 * 1024;
62
63// "foxhound-hero.jpg" gives "foxhound hero": offered as alt text, never applied (alt text nobody
64// read is worse than a visibly empty field).
65export function suggestedAlt(name: string): string {
66  return name
67    .replace(/\.[a-z0-9]+$/i, "")
68    .replace(/[-_]+/g, " ")
69    .trim();
70}
71
72// The state of a file's alt text. Missing and decorative are different: missing is a to-do,
73// decorative is a decision the author made.
74export function altStateOf(alt: string, decorative: boolean): AltState {
75  if (decorative) return "decorative";
76  return alt.trim() ? "set" : "missing";
77}
78
79export function parseTags(text: string): string[] {
80  const out: string[] = [];
81  for (const raw of text.split(",")) {
82    const t = raw.trim().toLowerCase();
83    if (t && !out.includes(t)) out.push(t);
84  }
85  return out;
86}
87
88// What a tile says about the file besides its name: the things a person should not miss.
89export interface Flag {
90  tone: "warn" | "info" | "nodata";
91  word: string;
92}
93export function flagsFor(r: Pick<MediaRecord, "kind" | "altState" | "used" | "state" | "usedUnknown">): Flag[] {
94  const out: Flag[] = [];
95  if (r.state === "binned") out.push({ tone: "nodata", word: "In Trash" });
96  if (r.state === "uploading" || r.state === "failed") return out;
97  if (r.kind === "image" && r.altState === "missing") out.push({ tone: "warn", word: "No alt text" });
98  if (r.kind === "image" && r.altState === "decorative") out.push({ tone: "info", word: "Decorative" });
99  if (r.state !== "binned" && !r.usedUnknown && r.used.length === 0) out.push({ tone: "nodata", word: "Unattached" });
100  return out;
101}
102
103// What a tile's controls are called, in one line a screen reader reads after the file's name.
104export function describeRecord(r: Pick<MediaRecord, "kind" | "type" | "bytes" | "state" | "progress" | "error">): string {
105  const kind = r.type.split("/").pop()?.toUpperCase() || (r.kind === "image" ? "Image" : "File");
106  if (r.state === "uploading") return `${kind}, uploading${r.progress != null ? ` ${Math.round(r.progress)} percent` : ""}`;
107  if (r.state === "failed") return `${kind}, upload failed${r.error ? `: ${r.error}` : ""}`;
108  return `${kind}, ${byteSize(r.bytes)}`;
109}
110
111// The three things a person copies: the address, the Markdown, the HTML. An image goes in as an
112// image and a document as a link: an <img> for a PDF breaks the page.
113export function copySnippets(r: Pick<MediaRecord, "url" | "kind" | "alt" | "name">): Array<{ id: string; label: string; name: string; value: string }> {
114  const alt = r.alt.trim();
115  const title = suggestedAlt(r.name);
116  if (r.kind === "image") {
117    return [
118      { id: "address", label: "Copy address", name: "Copy address", value: r.url },
119      { id: "markdown", label: "Markdown", name: "Copy the Markdown image", value: `![${alt}](${r.url})` },
120      { id: "html", label: "HTML tag", name: "Copy the HTML tag", value: `<img src="${r.url}" alt="${alt}">` },
121    ];
122  }
123  return [
124    { id: "address", label: "Copy address", name: "Copy address", value: r.url },
125    { id: "markdown", label: "Markdown", name: "Copy the Markdown link", value: `[${title}](${r.url})` },
126    { id: "html", label: "HTML link", name: "Copy the HTML link", value: `<a href="${r.url}">${title}</a>` },
127  ];
128}
129