components/moderation-queue/moderation-queue-model.ts

Functions

Imports

It imports components/message/message.ts. Imported by components/moderation-queue/moderation-queue.ts.

Source

1// The moderation queue's data, its pure helpers and the markup builders (moderation-queue.ts).
2
3import { GLYPHS, glyphSvg } from "../message/message.ts";
4
5// ---------------------------------------------------------------------------------------
6// The data and the pure helpers.
7
8// A mention's state on its site, in the contract's words (site-api MentionStatus). A mention
9// arrives unverified; the site reads its source and it becomes pending, or failed when the
10// source cannot be found. Only pending, approved and rejected can be decided.
11export type ModState = "unverified" | "pending" | "approved" | "rejected" | "failed";
12// What the filter shows: one state each, and All. Not yet checked is in All only, and counted
13// in the live line, because there is nothing to decide about it yet.
14export type ModView = "pending" | "failed" | "approved" | "rejected" | "all";
15// A decision. "reset" puts a decided mention back to waiting, where the site offers it
16// (site-api v0.6); without it a decision on a waiting mention cannot be undone.
17export type ModAction = "approve" | "reject" | "reset";
18
19export interface Mention {
20  id: string;
21  // Who sent it, as they gave it. Text, never a link.
22  author: string;
23  // The source's host, as text.
24  host: string;
25  // The full source address, as text; shown in the open row only. It is a link only when
26  // `external` is set, and then with rel="nofollow ugc noopener".
27  url?: string;
28  external?: boolean;
29  excerpt: string;
30  // The post it mentions, and its editor.
31  post: string;
32  postHref?: string;
33  // When it was received (the contract's receivedAt).
34  at: string;
35  state: ModState;
36  // When it was last decided.
37  decidedAt?: string;
38  // Why the source was not found, as the site said it ("The page answered 404").
39  failureReason?: string;
40  // The contract's version, posted with each decision so a stale one is refused.
41  version?: string;
42  // The site's retention removes it at the next sweep.
43  expiring?: boolean;
44}
45
46export const VIEWS: readonly ModView[] = ["pending", "failed", "approved", "rejected", "all"];
47
48export const VIEW_LABEL: Record<ModView, string> = { pending: "Waiting", failed: "Source not found", approved: "Approved", rejected: "Rejected", all: "All" };
49
50export const STATE_LABEL: Record<ModState, string> = { unverified: "Not yet checked", pending: "Waiting", approved: "Approved", rejected: "Rejected", failed: "Source not found" };
51
52export const ACTIONS: readonly ModAction[] = ["approve", "reject", "reset"];
53
54// The key that decides the row under focus. Back to waiting has none: it is the rare one.
55export const ACTION_KEY: Partial<Record<ModAction, string>> = { approve: "a", reject: "r" };
56
57// The key that deletes, after a confirm.
58export const DELETE_KEY = "d";
59
60// The transition table: every state to the states a decision can reach. The contract refuses a
61// decision on a mention not yet checked or whose source was not found (422), so they have none.
62const TABLE: Record<ModState, Partial<Record<ModAction, ModState>>> = {
63  unverified: {},
64  pending: { approve: "approved", reject: "rejected" },
65  approved: { reject: "rejected", reset: "pending" },
66  rejected: { approve: "approved", reset: "pending" },
67  failed: {},
68};
69
70// Where a decision takes a mention, or null where it does nothing (approving what is approved,
71// deciding what cannot be decided, or Back to waiting on a site that does not offer it).
72export function decide(state: ModState, action: ModAction, reset = false): ModState | null {
73  if (action === "reset" && !reset) return null;
74  return TABLE[state][action] ?? null;
75}
76
77// Which decisions a state offers, in the order the buttons show.
78export function actionsFor(state: ModState, reset = false): ModAction[] {
79  return ACTIONS.filter((a) => decide(state, a, reset) !== null);
80}
81
82// The decisions the bulk bar offers in a view. In All they are the two decisions; a row they do
83// not apply to is left alone and said.
84export function bulkActionsFor(view: ModView, reset = false): ModAction[] {
85  if (view === "all") return ["approve", "reject"];
86  if (view === "failed") return [];
87  return actionsFor(view, reset);
88}
89
90export function inView(state: ModState, view: ModView): boolean {
91  return view === "all" || state === view;
92}
93
94export type Counts = Record<ModState | "all", number>;
95
96export function countStates(items: ReadonlyArray<Pick<Mention, "state">>): Counts {
97  const c: Counts = { unverified: 0, pending: 0, approved: 0, rejected: 0, failed: 0, all: 0 };
98  for (const m of items) {
99    c[m.state] += 1;
100    c.all += 1;
101  }
102  return c;
103}
104
105// The live line: what is left to do. "3 waiting", "3 waiting, 1 not yet checked", "Nothing
106// waiting".
107export function summaryText(c: Pick<Counts, "pending" | "unverified">): string {
108  const parts: string[] = [];
109  if (c.pending > 0) parts.push(`${c.pending} waiting`);
110  if (c.unverified > 0) parts.push(`${c.unverified} not yet checked`);
111  return parts.length ? parts.join(", ") : "Nothing waiting";
112}
113
114export interface Status {
115  tone: "info" | "ok" | "crit" | "nodata" | "warn";
116  word: string;
117  glyph: string;
118}
119
120const NOTICE_GLYPH = '<rect x="1.5" y="1.5" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="1.6"/><path fill="currentColor" d="M7.2 7h1.6v5H7.2zM7.2 4h1.6v1.7H7.2z"/>';
121const NODATA_GLYPH = '<circle cx="8" cy="8" r="6.2" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M5 8h6" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>';
122
123// A status is a shape, a word and a colour.
124export function statusOf(state: ModState): Status {
125  const word = STATE_LABEL[state];
126  switch (state) {
127    case "pending":
128      return { tone: "info", word, glyph: NOTICE_GLYPH };
129    case "approved":
130      return { tone: "ok", word, glyph: GLYPHS.ok };
131    case "rejected":
132      return { tone: "crit", word, glyph: GLYPHS.failure };
133    case "unverified":
134      return { tone: "nodata", word, glyph: NODATA_GLYPH };
135    case "failed":
136      return { tone: "warn", word, glyph: GLYPHS.warning };
137  }
138}
139
140export const ACTION_LABEL: Record<ModAction, string> = { approve: "Approve", reject: "Reject", reset: "Back to waiting" };
141
142// What a decision says: "Rejected the mention from Rosa Park."
143export function decidedText(action: ModAction, who: string[]): string {
144  const noun = who.length === 1 ? `the mention from ${who[0]}` : `${who.length} mentions`;
145  switch (action) {
146    case "approve":
147      return `Approved ${noun}.`;
148    case "reject":
149      return `Rejected ${noun}.`;
150    case "reset":
151      return `Put ${noun} back to waiting.`;
152  }
153}
154
155export function undoneText(who: string[]): string {
156  return who.length === 1 ? `The mention from ${who[0]} is back where it was.` : `${who.length} mentions are back where they were.`;
157}
158
159// The decision that puts a mention back in `from`: the opposite decision between approved and
160// rejected, which every site has; Back to waiting for a waiting one, only where the site offers
161// it. Null where nothing can.
162export function undoAction(from: ModState, reset = false): ModAction | null {
163  if (from === "approved") return "approve";
164  if (from === "rejected") return "reject";
165  if (from === "pending" && reset) return "reset";
166  return null;
167}
168
169// Said after a decision on a waiting mention, on a site that cannot put one back to waiting.
170export const NO_UNDO_TEXT = "This site cannot put a mention back to waiting, so there is no Undo; the other decision is one key away.";
171
172// What one decision changed, so it can be reversed.
173export interface UndoEntry {
174  ids: string[];
175  who: string[];
176  action: ModAction;
177  from: Record<string, { state: ModState; decidedAt?: string }>;
178}
179
180export interface UndoStack<T> {
181  push(entry: T): void;
182  pop(): T | undefined;
183  peek(): T | undefined;
184  remove(match: (entry: T) => boolean): void;
185  clear(): void;
186  readonly size: number;
187}
188
189// The decisions that can still be undone, newest last. The message region offers Undo for the
190// newest; once it is done the one before is offered, so z walks back through the list.
191export function undoStack<T>(max = 20): UndoStack<T> {
192  let items: T[] = [];
193  return {
194    push(entry) {
195      items.push(entry);
196      if (items.length > max) items = items.slice(items.length - max);
197    },
198    pop: () => items.pop(),
199    peek: () => items[items.length - 1],
200    remove(match) {
201      items = items.filter((e) => !match(e));
202    },
203    clear() {
204      items = [];
205    },
206    get size() {
207      return items.length;
208    },
209  };
210}
211
212// What the retention sweep will remove, one line per kind, from the site's own counts (the
213// contract's `expiring`). Waiting and approved mentions are never swept.
214export function sweepLines(expiring: { failed: number; rejected: number }): string[] {
215  const out: string[] = [];
216  if (expiring.failed) out.push(`${expiring.failed} whose source was not found`);
217  if (expiring.rejected) out.push(`${expiring.rejected} rejected`);
218  return out;
219}
220
221export function mentionsWord(n: number): string {
222  return n === 1 ? "mention" : "mentions";
223}
224
225export const EMPTY_TEXT: Record<ModView, { title: string; text: string }> = {
226  pending: { title: "All clear", text: "No mentions are waiting. Approved and rejected are one filter away." },
227  failed: { title: "No missing sources", text: "Every mention's source page was found." },
228  approved: { title: "Nothing approved yet", text: "Approved mentions show on their post." },
229  rejected: { title: "Nothing rejected", text: "Rejected mentions wait here until the site's retention removes them." },
230  all: { title: "No mentions yet", text: "When another site links to a post, its mention arrives here." },
231};
232
233// ---------------------------------------------------------------------------------------
234// DOM helpers.
235
236type Attrs = Record<string, string | boolean | undefined>;
237
238export function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Attrs = {}, ...kids: Array<Node | string>): HTMLElementTagNameMap[K] {
239  const el = document.createElement(tag);
240  for (const [k, v] of Object.entries(attrs)) {
241    if (v === undefined || v === false) continue;
242    el.setAttribute(k, v === true ? "" : v);
243  }
244  el.append(...kids);
245  return el;
246}
247
248export function statusEl(state: ModState): HTMLElement {
249  const s = statusOf(state);
250  return h("span", { class: "cap-status", "data-tone": s.tone }, glyphSvg(s.glyph), s.word);
251}
252
253// A decision's button: a real button with its key shown and announced (aria-keyshortcuts).
254export function actionButton(action: ModAction | "delete", who: string, opts: { bar?: boolean } = {}): HTMLButtonElement {
255  const key = action === "delete" ? DELETE_KEY : ACTION_KEY[action];
256  const label = action === "delete" ? "Delete" : ACTION_LABEL[action];
257  const b = h("button", { type: "button", class: "cap-btn", "data-variant": action === "delete" ? "danger" : "quiet", "data-size": "sm", "data-cap-action": action, "aria-keyshortcuts": key });
258  b.append(label);
259  if (!opts.bar) b.append(h("span", { class: "cap-sr-only" }, ` the mention from ${who}`));
260  if (key) b.append(h("kbd", { class: "cap-kbd", "aria-hidden": "true" }, key));
261  return b;
262}