components/attention-list/attention-list.ts

Functions

Imports

It imports components/row-list/row-list.ts. Imported by components/attention-list/attention-list.react.tsx.

Source

1// The attention list's behaviour: the order (worst first), the two tiers (problems, then
2// notices), the grouping of like rows under one row that opens in place, the cap on how
3// many warnings show at once, and the buttons that show or hide what they control. No
4// framework; the React wrapper uses `arrange` and the same markup.
5//
6// The rules are the Portal's Overview (dashboard/src/lib/derive.ts: tierOf, fold,
7// attentionGroups, GROUP_CHILDREN, PROBLEM_ROWS; views/Overview.tsx: NeedsAttention),
8// made generic: the Portal's own feed types and its group table are the caller's here.
9
10import { attachRowList } from "../row-list/row-list.ts";
11
12export type AttentionTone = "crit" | "warn" | "nodata" | "info";
13
14export interface AttentionItem {
15  id: string;
16  tone: AttentionTone;
17  title: string;
18  detail?: string;
19  // Relative time in words ("11 minutes ago"), or that and the exact instant for a <time>.
20  when?: string | { text: string; datetime: string };
21  href: string;
22  // Rows that share a group key (and are not critical) fold into one row that opens in
23  // place. The key names the group; what it is called is `groups[key].title`.
24  group?: string;
25}
26
27// A group's title, detail and the view that lists all of its rows. Without an entry the
28// group is called "<key>, <count>" and has no link to a view.
29export interface AttentionGroupInfo {
30  title?: (count: number) => string;
31  // The facets the rows differ by: "capsid, carrel, foxhound".
32  detail?: string;
33  when?: string | { text: string; datetime: string };
34  view?: { href: string; label: string };
35}
36
37// A group shows up to this many rows, then a link to the view that lists them all.
38export const GROUP_CHILDREN = 5;
39// Past this many problem rows the rest of the warnings wait behind "N more warnings".
40// Critical rows are always shown.
41export const PROBLEM_ROWS = 8;
42
43export interface ArrangeOptions {
44  rows?: number;
45  children?: number;
46  groups?: Record<string, AttentionGroupInfo>;
47}
48
49export const TONE_ORDER: readonly AttentionTone[] = ["crit", "warn", "nodata", "info"];
50
51export const TONE_WORD: Record<AttentionTone, string> = {
52  crit: "Critical",
53  warn: "Warning",
54  nodata: "No data",
55  info: "Notice",
56};
57
58export interface AttentionRowEntry {
59  kind: "row";
60  item: AttentionItem;
61}
62
63export interface AttentionGroupEntry {
64  kind: "group";
65  key: string;
66  // What the group's button says: "3 pull requests await the seat".
67  label: string;
68  detail?: string;
69  when?: AttentionItem["when"];
70  // The worst tone among its rows.
71  tone: AttentionTone;
72  // The first rows only (see GROUP_CHILDREN); `total` is how many the group stands for.
73  items: AttentionItem[];
74  total: number;
75  view?: { href: string; label: string };
76}
77
78export type AttentionEntry = AttentionRowEntry | AttentionGroupEntry;
79
80export interface Arranged {
81  // Critical, then warnings, worst first: shown at once. Critical rows are never hidden.
82  problems: AttentionEntry[];
83  // Warnings past the cap, behind "N more warnings".
84  more: AttentionEntry[];
85  // Missing data and notices: facts with nothing to do now, one closed row at the foot.
86  notices: AttentionItem[];
87  // How many notice items the notices stand for (a folded group counts each of its rows).
88  noticeCount: number;
89}
90
91function rank(tone: AttentionTone): number {
92  const r = TONE_ORDER.indexOf(tone);
93  return r < 0 ? TONE_ORDER.length : r;
94}
95
96// A problem (critical or warning) needs a person; a notice (no data, a notice) is a fact
97// with nothing to do now. The tier follows from the tone (audit ruling 3).
98export function isNotice(tone: AttentionTone): boolean {
99  return tone === "nodata" || tone === "info";
100}
101
102function groupTitle(key: string, n: number, info: AttentionGroupInfo | undefined): string {
103  return info?.title ? info.title(n) : `${key}, ${n}`;
104}
105
106// Worst first (critical, warning, no data, notice), keeping the given order within a tone.
107// Then the two tiers. In the problems, rows sharing a group key fold into one group row,
108// placed where its worst row would be; a critical row is never folded, and a group of one is
109// just a row. Warnings past `rows` move to `more`. In the notices a group folds into a
110// single row that opens its view, not into a second disclosure.
111export function arrange(items: readonly AttentionItem[], options: ArrangeOptions = {}): Arranged {
112  const { rows = PROBLEM_ROWS, children = GROUP_CHILDREN, groups = {} } = options;
113  const sorted = items
114    .map((item, i) => ({ item, i }))
115    .sort((a, b) => rank(a.item.tone) - rank(b.item.tone) || a.i - b.i)
116    .map((x) => x.item);
117  const problemItems = sorted.filter((it) => !isNotice(it.tone));
118  const noticeItems = sorted.filter((it) => isNotice(it.tone));
119
120  const size = new Map<string, number>();
121  for (const it of problemItems) if (it.group && it.tone !== "crit") size.set(it.group, (size.get(it.group) ?? 0) + 1);
122  const entries: AttentionEntry[] = [];
123  const open = new Map<string, AttentionGroupEntry>();
124  for (const item of problemItems) {
125    const n = item.group && item.tone !== "crit" ? (size.get(item.group) ?? 0) : 0;
126    if (!item.group || n < 2) {
127      entries.push({ kind: "row", item });
128      continue;
129    }
130    let g = open.get(item.group);
131    if (!g) {
132      const info = groups[item.group];
133      g = { kind: "group", key: item.group, label: groupTitle(item.group, n, info), detail: info?.detail, when: info?.when ?? item.when, tone: item.tone, items: [], total: n, view: info?.view };
134      open.set(item.group, g);
135      entries.push(g);
136    }
137    if (g.items.length < children) g.items.push(item);
138  }
139
140  const crit = entries.filter((e) => (e.kind === "row" ? e.item.tone : e.tone) === "crit");
141  const warn = entries.filter((e) => (e.kind === "row" ? e.item.tone : e.tone) !== "crit");
142  const room = Math.max(0, rows - crit.length);
143  const hidden = warn.length > room ? warn.slice(room) : [];
144  const problems = [...crit, ...(hidden.length ? warn.slice(0, room) : warn)];
145
146  const noticeSize = new Map<string, number>();
147  for (const it of noticeItems) if (it.group) noticeSize.set(it.group, (noticeSize.get(it.group) ?? 0) + 1);
148  const notices: AttentionItem[] = [];
149  const folded = new Set<string>();
150  for (const item of noticeItems) {
151    const n = item.group ? (noticeSize.get(item.group) ?? 0) : 0;
152    if (!item.group || n < 2) {
153      notices.push(item);
154      continue;
155    }
156    if (folded.has(item.group)) continue;
157    folded.add(item.group);
158    const info = groups[item.group];
159    notices.push({ id: `group:${item.group}`, tone: item.tone, title: groupTitle(item.group, n, info), detail: info?.detail ?? item.detail, when: info?.when ?? item.when, href: info?.view?.href ?? item.href });
160  }
161  return { problems, more: hidden, notices, noticeCount: noticeItems.length };
162}
163
164// The sentence in the header: "3 problems", "no problems".
165export function problemCount(a: Arranged): string {
166  const n = a.problems.length + a.more.length;
167  return n ? `${n} ${n === 1 ? "problem" : "problems"}` : "No problems";
168}
169
170// "All 7 in CI and merges" when the group holds more than it shows, else "Open CI and merges".
171export function viewLinkText(g: AttentionGroupEntry): string {
172  return g.view ? (g.total > g.items.length ? `All ${g.total} in ${g.view.label}` : `Open ${g.view.label}`) : "";
173}
174
175// Shows or hides what one button controls (a group's rows, the warnings past the cap, the
176// notices) and keeps the button's state true. A button with data-open-label says that while
177// open ("Fewer warnings") and its own text again when closed, as the Portal's does.
178export function setGroup(button: HTMLElement, open: boolean): void {
179  button.setAttribute("aria-expanded", String(open));
180  const openLabel = button.dataset.openLabel;
181  if (openLabel) {
182    if (button.dataset.closedLabel === undefined) button.dataset.closedLabel = button.textContent ?? "";
183    button.textContent = open ? openLabel : button.dataset.closedLabel;
184  }
185  const id = button.getAttribute("aria-controls");
186  const members = id ? button.ownerDocument.getElementById(id) : null;
187  if (members) members.hidden = !open;
188}
189
190export function toggleGroup(button: HTMLElement): void {
191  setGroup(button, button.getAttribute("aria-expanded") !== "true");
192}
193
194// Attaches to every [data-cap="attention-list"] under root that is not attached yet: the
195// buttons that open and close, and j and k on the list (row-list's, attached here so one
196// call is enough). Returns a function that detaches them all.
197export function enhance(root: ParentNode = document): () => void {
198  const undo: Array<() => void> = [];
199  for (const list of root.querySelectorAll<HTMLElement>("[data-cap='attention-list']:not([data-cap-ready])")) {
200    list.dataset.capReady = "";
201    const onClick = (e: MouseEvent) => {
202      const button = (e.target as Element).closest<HTMLElement>("button[aria-expanded][aria-controls]");
203      if (button && list.contains(button)) toggleGroup(button);
204    };
205    list.addEventListener("click", onClick);
206    undo.push(() => {
207      list.removeEventListener("click", onClick);
208      delete list.dataset.capReady;
209    });
210    for (const rows of list.querySelectorAll<HTMLElement>("[data-cap='row-list']")) undo.push(attachRowList(rows));
211  }
212  return () => undo.forEach((f) => f());
213}