Files
pipelines/web/src/attention.js
T

210 lines
7.9 KiB
JavaScript

// Pure, DOM-free model for the browser client's attention / "Needs you" surface
// (R15). It mirrors android/.../ui/Attention.kt and the wording shown by
// ui/components/AttentionSurface.kt, so the browser's bell, its badge and the
// sheet read exactly what the app reads.
//
// The surface is derived here from the same `list_runs` summaries the runs list
// is folded from (and from any run state already in the page). R10's live
// `run_event` fold feeds these same pure functions the pushed summaries, so the
// ordering and the wording are identical whether a row arrived from a read or a
// push.
//
// Everything in this file is pure: no DOM, no clock, no storage. app.js keeps the
// wiring; a malformed stored value can never throw into the page because decode
// is total. Every server-provided string is only ever compared or rendered,
// never parsed as markup; the caller sets it with textContent.
// ---------------------------------------------------------------------------
// Kinds and qualification
// ---------------------------------------------------------------------------
/**
* The two things the attention surface ranks, most important first. The rank is
* what orders the list; the name is what a dismissal identity is keyed by.
*/
export const AttentionKind = Object.freeze({
Decision: Object.freeze({ name: "Decision", rank: 0 }),
Failed: Object.freeze({ name: "Failed", rank: 1 }),
});
/**
* The attention kind a run status maps to, or null when the run needs nobody. It
* reads the server's own words only (trimmed/lowercased `waiting` and `failed`),
* so queued, running, succeeded, canceled, interrupted and any unknown status
* can never invent an entry.
*/
export function attentionKindOf(status) {
switch (String(status ?? "").trim().toLowerCase()) {
case "waiting":
return AttentionKind.Decision;
case "failed":
return AttentionKind.Failed;
default:
return null;
}
}
// ---------------------------------------------------------------------------
// Identity and wording
// ---------------------------------------------------------------------------
/** The identity of one run+kind entry; the unit an explicit dismissal removes. */
export function attentionKey(runId, kind) {
return `${runId}:${kind.name}`;
}
/**
* What one entry asks of the operator, in the operator's words. A failed run
* shows the server's own diagnostic when it recorded one so the line is
* actionable rather than a bare "failed".
*/
export function attentionDetail(kind, run) {
if (kind === AttentionKind.Decision) return "Waiting for your decision";
const diagnostic = String(run?.diagnostic ?? "").trim();
return diagnostic !== "" ? diagnostic : "Run failed";
}
/**
* The one-line secondary text for a row: the pipeline the run belongs to, then
* what it needs. Exactly `{pipeline} · {detail}`, as AttentionSurface.kt draws.
*/
export function attentionRowDescription(entry) {
return `${entry.pipeline} · ${entry.detail}`;
}
/**
* The bell action's accessible name: the bare `Notifications` when nothing needs
* the operator, else the count. The visible badge is drawn only in the second
* case, from the same count.
*/
export function attentionBadgeLabel(count) {
const n = Number(count) || 0;
return n > 0 ? `Notifications, ${n} needing attention` : "Notifications";
}
// ---------------------------------------------------------------------------
// The ordered list
// ---------------------------------------------------------------------------
/**
* The ordered attention list. Every run that needs the operator becomes one
* entry, ranked by kind (decision, then failure), then newest-first within a
* kind (its finish time else its creation time, as the server wrote it), then by
* run id descending so the order is stable and never reshuffles between reads.
* An entry the operator explicitly dismissed never returns. A run status that
* asks nobody is dropped, so the surface can only ever hold actionable work.
*/
export function attentionEntries(runs, dismissed) {
const dismissedKeys =
dismissed instanceof Set ? dismissed : new Set(Array.isArray(dismissed) ? dismissed : []);
return (runs ?? [])
.map((run) => {
const kind = attentionKindOf(run?.status);
if (!kind) return null;
const key = attentionKey(run.id, kind);
if (dismissedKeys.has(key)) return null;
const title = String(run.title ?? "").trim();
const finished = String(run.finished_at ?? "");
return {
runId: run.id,
pipeline: String(run.name ?? ""),
label: title !== "" ? title : String(run.name ?? ""),
kind,
detail: attentionDetail(kind, run),
recency: finished.trim() !== "" ? finished : String(run.created_at ?? ""),
key,
};
})
.filter((entry) => entry != null)
.sort(
(a, b) =>
a.kind.rank - b.kind.rank ||
descendingText(a.recency, b.recency) ||
(b.runId > a.runId ? 1 : b.runId < a.runId ? -1 : 0),
);
}
/**
* Captures the entries shown when the sheet opens. Bulk dismissal uses this
* snapshot so entries that arrive while the sheet is open are not removed. A
* defensive copy, so the live list can never mutate what Clear all will apply.
*/
export function attentionDismissalSnapshot(entries) {
return [...(entries ?? [])];
}
// ---------------------------------------------------------------------------
// Dismissal bookkeeping
// ---------------------------------------------------------------------------
/** Adds one identity to the dismissed set, ignoring a blank or already-present key. */
export function attentionDismiss(dismissed, key) {
const next = new Set(dismissed instanceof Set ? dismissed : []);
if (String(key ?? "") !== "") next.add(key);
return next;
}
/**
* Unions a snapshot's identities into the dismissed set. Only the identities in
* the snapshot are added, so an entry that arrived after the sheet opened (and
* is therefore not in the snapshot) is left alone. This is what Clear all does.
*/
export function attentionDismissAll(dismissed, snapshot) {
const next = new Set(dismissed instanceof Set ? dismissed : []);
for (const entry of snapshot ?? []) {
if (entry?.key) next.add(entry.key);
}
return next;
}
// ---------------------------------------------------------------------------
// Persistence
// ---------------------------------------------------------------------------
/**
* The single localStorage key the dismissed identities live under: one JSON
* array of `{runId}:{kind}` strings, with no expiry or TTL of any kind.
*/
export const ATTENTION_STORAGE_KEY = "pipelines.web.attention.v1";
/**
* The one-line JSON a dismissed set is stored as: a JSON array of strings. The
* array is sorted so an unchanged set always encodes to the same bytes.
*/
export function encodeAttentionDismissals(dismissed) {
const keys = [...(dismissed instanceof Set ? dismissed : [])].filter(
(key) => typeof key === "string" && key !== "",
);
keys.sort();
return JSON.stringify(keys);
}
/**
* Decodes a stored value into a dismissed set. Total: blank, unreadable JSON, a
* non-array value and non-string members all decode to empty, so a malformed
* value can never throw into the page.
*/
export function decodeAttentionDismissals(stored) {
const text = stored == null ? "" : String(stored).trim();
if (text === "") return new Set();
let parsed;
try {
parsed = JSON.parse(text);
} catch {
return new Set();
}
if (!Array.isArray(parsed)) return new Set();
return new Set(parsed.filter((key) => typeof key === "string" && key !== ""));
}
// ---------------------------------------------------------------------------
// Internals
// ---------------------------------------------------------------------------
/** Descending compare of two strings, matching the app's `thenByDescending`. */
function descendingText(a, b) {
if (a < b) return 1;
if (a > b) return -1;
return 0;
}