@joewinke/jatui 0.36.3 → 0.38.0

package/dist/artifact-blocks/liveData.js

@@ -0,0 +1,137 @@
+/**
+ * Largest serialized artifacts.data accepted after a write. Generous for a
+ * real dashboard (thousands of table rows), small enough that a runaway
+ * generator cannot balloon a page's poll payload. The service enforces it
+ * inside the UPDATE itself — a write that would exceed the cap changes
+ * NOTHING (no partial merge, no data_updated_at bump).
+ */
+export const MAX_DATA_BYTES = 1024 * 1024;
+/**
+ * Data keys are lowercase-ish identifiers, 1-80 chars, NO dots: the contract
+ * is exact-key match (`data[dataKey]`), and a dot would read as path
+ * semantics that do not exist. dataKey params in the block schemas carry the
+ * same 80-char cap, so every key a block can name is a key a publish can
+ * store.
+ */
+const DATA_KEY_RE = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,79}$/;
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Own-property read only — a data key must never resolve off the prototype
+ * chain (a hostile `dataKey: "__proto__"` would otherwise read
+ * Object.prototype as params). JSON.parse creates own properties only, so
+ * every legit key passes this. */
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/**
+ * A value is storable iff it is PLAIN JSON: finite numbers, strings, booleans,
+ * nulls, arrays, and objects whose prototype is Object.prototype (a Date, a
+ * Map, or a class instance would serialize with loss or throw — refuse them
+ * rather than store something the reader did not publish). NaN/Infinity are
+ * numbers but serialize to "null" — the classic silent corruption, so they
+ * are refused. JSON.parse output always passes: the route's body is already
+ * pure JSON, and this guards the service's direct server callers.
+ */
+function isSerializableJson(v) {
+    if (v === null)
+        return true;
+    const t = typeof v;
+    if (t === "number")
+        return Number.isFinite(v);
+    if (t === "string" || t === "boolean")
+        return true;
+    if (t === "object") {
+        if (Array.isArray(v)) {
+            return v.every((el) => isSerializableJson(el));
+        }
+        const proto = Object.getPrototypeOf(v);
+        if (proto !== null && proto !== Object.prototype)
+            return false;
+        return Object.values(v).every((el) => isSerializableJson(el));
+    }
+    return false;
+}
+/** Serialized UTF-8 byte length of a JSON value. TextEncoder, not Buffer —
+ * this module is imported by BlockRenderer in the browser too. */
+const textEncoder = new TextEncoder();
+export function serializedBytes(v) {
+    return textEncoder.encode(JSON.stringify(v) ?? "").length;
+}
+/**
+ * Validate + normalize a data publish. Throws with a message an agent can
+ * act on; the route turns that into a 400. `undefined` incoming data is a
+ * programmer error (the body always parses to something) and is refused like
+ * any other invalid input.
+ */
+export function normalizeDataPublish(input) {
+    if (input.data === undefined)
+        throw new Error("data is required (the JSON value to publish)");
+    const hasKey = input.key !== undefined && input.key !== null && input.key !== false;
+    if (hasKey && input.replace === true)
+        throw new Error("pass either --key (upsert one key) or replace (replace every key), not both");
+    if (hasKey) {
+        if (typeof input.key !== "string" || !DATA_KEY_RE.test(input.key))
+            throw new Error(`key must match ${DATA_KEY_RE.source} (1-80 chars, no dots)`);
+        if (!isSerializableJson(input.data))
+            throw new Error("data must be JSON-serializable (no NaN, Infinity or functions)");
+        return { mode: "key", key: input.key, value: input.data };
+    }
+    if (!isPlainObject(input.data))
+        throw new Error("data must be a JSON object of { dataKey: value } — or name a single key with --key");
+    for (const k of Object.keys(input.data)) {
+        if (!DATA_KEY_RE.test(k))
+            throw new Error(`data key "${k}" must match ${DATA_KEY_RE.source} (1-80 chars, no dots)`);
+        if (!isSerializableJson(input.data[k]))
+            throw new Error(`data key "${k}" must be JSON-serializable`);
+    }
+    return {
+        mode: input.replace === true ? "replace" : "merge",
+        key: null,
+        value: input.data,
+    };
+}
+/**
+ * The dataParam binding. `def.dataParam` names the params field holding the
+ * data key; when that field names a key WITH a published value, the live
+ * value replaces the params wholesale. Everything else renders inline:
+ * no opt-in, no published value, or a key that exists only on the prototype
+ * chain (hasOwn guard).
+ */
+export function resolveBlockParams(def, rawParams, data) {
+    const dataKey = def?.dataParam && isPlainObject(rawParams)
+        ? rawParams[def.dataParam]
+        : undefined;
+    if (typeof dataKey !== "string" || !dataKey)
+        return { params: rawParams, dataKey: null, fromData: false };
+    if (!hasOwn(data, dataKey))
+        return { params: rawParams, dataKey, fromData: false };
+    return { params: data[dataKey], dataKey, fromData: true };
+}
+// ---------------------------------------------------------------------------
+// Reader-facing "updated Nm ago"
+// ---------------------------------------------------------------------------
+/**
+ * The subtle freshness line: "just now" → "42s ago" → "2m ago" → "3h ago" →
+ * "5d ago". Empty string when there is no data yet (the line does not render
+ * at all).
+ */
+export function formatDataAge(updatedAt, now) {
+    if (!updatedAt)
+        return "";
+    const t = new Date(updatedAt).getTime();
+    if (!Number.isFinite(t))
+        return "";
+    const s = Math.max(0, Math.floor((new Date(now).getTime() - t) / 1000));
+    if (s < 15)
+        return "just now";
+    if (s < 90)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 36)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}

package/dist/artifact-blocks/liveDataPoller.d.ts

@@ -0,0 +1,41 @@
+export interface LiveDataPoller {
+    /** The latest data blob (starts as the server-rendered copy). */
+    readonly data: Record<string, unknown>;
+    /** When the blob last CHANGED (server's data_updated_at, ISO string). */
+    readonly updatedAt: string | null;
+    /** A ticking clock for age strings — advances every interval, browser-only. */
+    readonly now: number;
+    /** Last poll outcome, for a subtle failure hint (never a blocking UI). */
+    readonly lastError: "fetch" | "rate_limited" | null;
+    /** True while a fetch is in flight. */
+    readonly polling: boolean;
+    /** The host gave a refresh leg: the page really is live. */
+    readonly live: boolean;
+    /** The poll cadence, ms. */
+    readonly intervalMs: number;
+    start: () => void;
+    stop: () => void;
+}
+interface PollerOptions {
+    /** The host's read of the current data. Undefined → never polls. */
+    fetch?: () => Promise<{
+        data: Record<string, unknown>;
+        dataUpdatedAt: string | null;
+    }>;
+    /** The server-rendered data (SSR renders it; the poller takes over). */
+    initialData: Record<string, unknown>;
+    initialUpdatedAt: string | null;
+    /** Poll cadence. Default 30s (the phase-3 contract). */
+    intervalMs?: number;
+}
+export declare function createLiveDataPoller(options: PollerOptions): LiveDataPoller;
+/**
+ * The header's freshness line: "live · updated 2m ago", or an empty string
+ * when this page has no data yet (the line does not render at all). The dot
+ * is text — a failed poll shows "refresh pending" instead of a lie, and a
+ * page with no refresh leg never claims to be live.
+ */
+export declare function dataAgeLine(poller: LiveDataPoller): string;
+/** The freshness line's hover text. */
+export declare function dataAgeTitle(poller: LiveDataPoller): string;
+export {};

package/dist/artifact-blocks/liveDataPoller.js

@@ -0,0 +1,140 @@
+/* liveDataPoller.svelte.js generated by Svelte v5.53.11 */
+import * as $ from 'svelte/internal/client';
+import { formatDataAge } from "./liveData.js";
+
+const DEFAULT_INTERVAL_MS = 30_000;
+
+export function createLiveDataPoller(options) {
+	let data = $.state($.proxy(options.initialData ?? {}));
+	let updatedAt = $.state($.proxy(options.initialUpdatedAt ?? null));
+	let now = $.state(0);
+	let lastError = $.state(null);
+	let polling = $.state(false);
+	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+	let timer = null;
+	let started = false;
+
+	async function poll() {
+		if ($.get(polling)) return; // a slow response never stacks requests
+
+		$.set(polling, true);
+		$.set(now, Date.now(), true);
+
+		try {
+			if (!options.fetch) return;
+
+			const body = await options.fetch();
+
+			$.set(lastError, null);
+
+			// REPLACE, never merge: the endpoint answers with the whole blob, so
+			// the page always renders exactly what is stored.
+			$.set(data, body.data ?? {}, true);
+
+			$.set(updatedAt, body.dataUpdatedAt ?? null, true);
+		} catch(err) {
+			// A host may signal a rate limit by throwing { status: 429 }.
+			$.set(lastError, err?.status === 429 ? "rate_limited" : "fetch", true);
+
+			// Keep the last good data on the page — a failed poll must never
+			// blank a dashboard.
+		} finally {
+			$.set(polling, false);
+		}
+	}
+
+	function tick() {
+		// document is undefined during SSR module init — guarded because start()
+		// is only ever called from a browser $effect, but the listener setup is
+		// cheap enough to keep defensive.
+		if (typeof document !== "undefined" && !document.hidden) void poll(); else $.set(now, Date.now(), true);
+	}
+
+	function onVisibility() {
+		// Regaining visibility refreshes immediately instead of waiting out the
+		// interval — the common gesture is "switch back to the dashboard tab".
+		if (typeof document !== "undefined" && !document.hidden) void poll();
+	}
+
+	function start() {
+		if (started || !options.fetch) return;
+
+		started = true;
+		$.set(now, Date.now(), true);
+		timer = setInterval(tick, intervalMs);
+
+		if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisibility);
+	}
+
+	function stop() {
+		if (!started) return;
+
+		started = false;
+
+		if (timer) clearInterval(timer);
+
+		timer = null;
+
+		if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibility);
+	}
+
+	return {
+		get data() {
+			return $.get(data);
+		},
+
+		get updatedAt() {
+			return $.get(updatedAt);
+		},
+
+		get now() {
+			return $.get(now);
+		},
+
+		get lastError() {
+			return $.get(lastError);
+		},
+
+		get polling() {
+			return $.get(polling);
+		},
+
+		get live() {
+			return Boolean(options.fetch);
+		},
+		intervalMs,
+		start,
+		stop
+	};
+}
+
+/**
+ * The header's freshness line: "live · updated 2m ago", or an empty string
+ * when this page has no data yet (the line does not render at all). The dot
+ * is text — a failed poll shows "refresh pending" instead of a lie, and a
+ * page with no refresh leg never claims to be live.
+ */
+export function dataAgeLine(poller) {
+	if (!poller.updatedAt) return "";
+
+	const age = formatDataAge(poller.updatedAt, poller.now || Date.now());
+
+	if (!age) return "";
+	if (!poller.live) return `updated ${age}`;
+	if (poller.lastError) return `updated ${age} · refresh pending`;
+
+	return `live · updated ${age}`;
+}
+
+/** The freshness line's hover text. */
+export function dataAgeTitle(poller) {
+	if (!poller.live) return "Data as of when this page loaded";
+
+	const s = Math.round(poller.intervalMs / 1000);
+
+	const every = s % 60 === 0
+		? `${s / 60} minute${s === 60 ? "" : "s"}`
+		: `${s} seconds`;
+
+	return `Live data refreshes this page every ${every} while it is open`;
+}

package/dist/artifact-blocks/openNav.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Jump navigation for a review page's still-open units (mos-cs31v).
+ *
+ * The Finish panel's thumbnail cards and the sticky header's "N open" chip
+ * both land the reviewer ON an undecided item: scroll it into view (instant
+ * under prefers-reduced-motion), move focus there — the screen reader
+ * announces the card, the sighted eye gets a ring flash — and a CURSOR over
+ * the open list so N / shift+N walk next/previous without ever losing the
+ * thread. The cursor survives decisions: when the unit it names gets decided
+ * it leaves the list, and the unit that took its POSITION inherits the
+ * cursor — so "decide, N, decide, N" walks down the page instead of
+ * restarting at the top.
+ *
+ * DOM knowledge is kept to two small functions; the cursor is pure and
+ * unit-tested. Blocks render `id="block-<id>"` (BlockRenderer) and their
+ * reviewable items carry `data-item-id` (checklist rows, media cards, diff
+ * sections) — the same handles the blocks' own keyboard nav use.
+ */
+import type { OpenReviewUnit } from "./review.js";
+/** The part of a unit the jump machinery needs. */
+export type JumpUnit = Pick<OpenReviewUnit, "key" | "blockId" | "itemId" | "label">;
+/**
+ * Scroll the unit into view, focus it, flash it. `reduceMotion` overrides
+ * the media query (tests); under it the jump is instant and no flash runs.
+ * Returns the element that took the focus, or null when the unit renders
+ * nowhere (the page is not mounted, or the block is gone from this version).
+ */
+export declare function revealUnit(unit: JumpUnit, opts?: {
+    reduceMotion?: boolean;
+}): HTMLElement | null;
+export interface OpenNav {
+    /** Walk to the next (1) / previous (-1) open unit and reveal it. Null
+     *  when the page has no open units — the callers hide the controls then. */
+    jump: (dir: 1 | -1) => JumpUnit | null;
+    /** Jump to ONE unit (a Finish card click), cursor and all. */
+    jumpTo: (unit: JumpUnit) => void;
+}
+/**
+ * The cursor over the still-open list. `getUnits` is read at every jump —
+ * the list shrinks live as items are decided — and `onJump` does the DOM
+ * work (revealUnit + the announcement) exactly once per jump.
+ */
+export declare function createOpenNav(options: {
+    getUnits: () => JumpUnit[];
+    onJump: (unit: JumpUnit) => void;
+}): OpenNav;

package/dist/artifact-blocks/openNav.js

@@ -0,0 +1,106 @@
+/** BlockRenderer's section anchor for a block id. */
+const sectionFor = (blockId) => typeof document === "undefined"
+    ? null
+    : document.getElementById(`block-${blockId}`);
+/** Escape an id for an attribute selector. CSS.escape everywhere real;
+ *  jsdom test environments ship no CSS global, and the ids that reach here
+ *  are schema-restricted (never a quote or a backslash), so the fallback
+ *  only has to be honest about those two. */
+const attrEscape = (v) => typeof CSS !== "undefined" && typeof CSS.escape === "function"
+    ? CSS.escape(v)
+    : v.replace(/["\\]/g, "\\$&");
+/** The element a unit renders at: its item card, else the block section.
+ *  A card hidden behind the block's own filter (diff-review's Undecided
+ *  view) falls back to the section — still the right neighborhood. */
+function reviewUnitElement(unit) {
+    const root = sectionFor(unit.blockId);
+    if (!root || !unit.itemId)
+        return root;
+    const card = root.querySelector(`[data-item-id="${attrEscape(unit.itemId)}"]`);
+    if (!card || card.checkVisibility?.() === false)
+        return root;
+    return card;
+}
+const FOCUSABLE = "a[href], button, input, textarea, select, [tabindex]";
+/** Put focus on the unit's element, adding a temporary tabindex when it has
+ *  none of its own (a section, a plain card). preventScroll: the scroll
+ *  below already centers the item; a focusing scroll would fight it. */
+function focusUnit(el) {
+    if (!el.matches(FOCUSABLE))
+        el.setAttribute("tabindex", "-1");
+    el.focus({ preventScroll: true });
+}
+/** A brief ring around the jumped item — WAAPI, so it needs no shared CSS
+ *  and releases the element the moment it ends. Skipped entirely under
+ *  prefers-reduced-motion (the jump itself is the feedback there). */
+function flashBorder(el) {
+    el.animate?.([
+        { boxShadow: "0 0 0 0px transparent" },
+        { boxShadow: "0 0 0 3px var(--color-primary)", offset: 0.15 },
+        { boxShadow: "0 0 0 3px transparent" },
+    ], { duration: 1400, easing: "ease-out" });
+}
+/**
+ * Scroll the unit into view, focus it, flash it. `reduceMotion` overrides
+ * the media query (tests); under it the jump is instant and no flash runs.
+ * Returns the element that took the focus, or null when the unit renders
+ * nowhere (the page is not mounted, or the block is gone from this version).
+ */
+export function revealUnit(unit, opts = {}) {
+    const el = reviewUnitElement(unit);
+    if (!el)
+        return null;
+    const reduce = opts.reduceMotion ??
+        window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches === true;
+    el.scrollIntoView?.({
+        behavior: reduce ? "auto" : "smooth",
+        block: "center",
+    });
+    focusUnit(el);
+    if (!reduce)
+        flashBorder(el);
+    return el;
+}
+/**
+ * The cursor over the still-open list. `getUnits` is read at every jump —
+ * the list shrinks live as items are decided — and `onJump` does the DOM
+ * work (revealUnit + the announcement) exactly once per jump.
+ */
+export function createOpenNav(options) {
+    /** The key of the unit the cursor names; null until the first jump. */
+    let cursorKey = null;
+    /** The POSITION the cursor held — the fallback once its unit is decided
+     *  away, because the successor inherits the position, not the identity. */
+    let cursorIndex = 0;
+    function jump(dir) {
+        const units = options.getUnits();
+        const len = units.length;
+        if (len === 0)
+            return null;
+        const at = cursorKey ? units.findIndex((u) => u.key === cursorKey) : -1;
+        const t = at === -1
+            ? // The cursor's unit was decided away, or this is the first press.
+                // Forwards lands ON the stored position — the first press starts
+                // at the top of the page, and a decided unit hands its place to
+                // its successor. Backwards lands BEFORE it (wrapping), so the
+                // first shift+N reaches the last open item.
+                dir === 1
+                    ? Math.min(cursorIndex, len - 1)
+                    : cursorIndex - 1
+            : at + dir;
+        const i = ((t % len) + len) % len;
+        const unit = units[i];
+        cursorKey = unit.key;
+        cursorIndex = i;
+        options.onJump(unit);
+        return unit;
+    }
+    function jumpTo(unit) {
+        const at = options.getUnits().findIndex((u) => u.key === unit.key);
+        cursorKey = unit.key;
+        if (at !== -1)
+            cursorIndex = at;
+        options.onJump(unit);
+    }
+    return { jump, jumpTo };
+}

package/dist/artifact-blocks/pageReviewKeys.d.ts

@@ -0,0 +1,17 @@
+export interface PageReviewBlock {
+    id: string;
+    type: string;
+}
+export interface PageReviewKeysOptions {
+    /** The review blocks on the page, in page order. */
+    getBlocks: () => PageReviewBlock[];
+    /** The section a block renders in (BlockRenderer: `#block-<id>`). */
+    sectionFor?: (id: string) => HTMLElement | null;
+}
+/** True when focus sits on the page or its chrome, not in a block or modal.
+ *  Exported for the page's OTHER chrome-level key handlers (mos-cs31v: the
+ *  still-open n / shift+N walk shares the same "not inside a block" rule). */
+export declare function isPageChromeTarget(t: EventTarget | null): boolean;
+export declare function createPageReviewKeys(options: PageReviewKeysOptions): {
+    handleKeydown: (e: KeyboardEvent) => boolean;
+};

package/dist/artifact-blocks/pageReviewKeys.js

@@ -0,0 +1,115 @@
+/**
+ * Page-level review keys (mos-lsmve.13).
+ *
+ * Each review block's jatui `reviewKeys` listens on the block only (a page
+ * can carry several), so on page load — focus on <body> — j, f and ? did
+ * nothing until the reviewer clicked or tabbed into a card, and nothing on
+ * the page said so. This router listens on the window and, ONLY when focus
+ * is on the page itself or its chrome (never inside a block, a text field or
+ * an open dialog), hands the navigation keys to the FIRST review block:
+ *
+ *   j, gg   focus that block's first visible card
+ *   f       ask the block for its next item that needs you (its own
+ *           needs-you rule); if nothing takes focus, its first card
+ *   ?       that block's own shortcuts
+ *
+ * Verdict keys (a / x / r / b, u, n, …) are deliberately NOT routed:
+ * deciding needs a visible, focused item. Once a card has focus, the block's
+ * own handler owns every key and this router steps aside.
+ */
+import { isTextTarget, visualItems } from "./review/visualOrder.js";
+/** Block types whose `f` is needs-you. The checklist still honours its old
+ *  `f` = Fail letter, which would act on a stale cursor — so a checklist
+ *  gets a plain focus instead of a routed `f`. */
+const F_ROUTES_TO_BLOCK = new Set(["media-picker", "diff-review"]);
+/** How long the first `g` of `gg` waits for the second (ms). */
+const GG_WINDOW_MS = 800;
+const defaultSection = (id) => typeof document === "undefined"
+    ? null
+    : document.getElementById(`block-${id}`);
+/** True when focus sits on the page or its chrome, not in a block or modal.
+ *  Exported for the page's OTHER chrome-level key handlers (mos-cs31v: the
+ *  still-open n / shift+N walk shares the same "not inside a block" rule). */
+export function isPageChromeTarget(t) {
+    if (typeof document === "undefined")
+        return false;
+    if (t === null || t === window || t === document)
+        return true;
+    if (!(t instanceof HTMLElement))
+        return false;
+    if (isTextTarget(t))
+        return false;
+    if (t.closest('[id^="block-"]'))
+        return false;
+    if (t.closest('dialog, [role="dialog"], [aria-modal="true"]'))
+        return false;
+    // A modal that holds no focus (focus fell back to <body>) still owns keys.
+    if (document.querySelector('dialog[open], [aria-modal="true"]'))
+        return false;
+    return true;
+}
+export function createPageReviewKeys(options) {
+    const sectionFor = options.sectionFor ?? defaultSection;
+    let lastG = 0;
+    /** The first review block that has a card to land on. */
+    function firstBlock() {
+        for (const b of options.getBlocks()) {
+            const section = sectionFor(b.id);
+            if (!section)
+                continue;
+            const cards = visualItems(section);
+            if (cards.length > 0)
+                return { block: b, section, cards };
+        }
+        return null;
+    }
+    function focusCard(el) {
+        el.focus({ preventScroll: true });
+        el.scrollIntoView?.({ block: "center" });
+    }
+    /** Re-dispatch a key from inside the block so its own listener answers. */
+    function forward(target, key) {
+        target.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }));
+    }
+    /** Returns true when the key was routed (the caller's event is consumed). */
+    function handleKeydown(e) {
+        if (e.defaultPrevented || e.isComposing)
+            return false;
+        if (e.ctrlKey || e.metaKey || e.altKey)
+            return false;
+        if (!isPageChromeTarget(e.target))
+            return false;
+        const key = e.key;
+        if (key !== "g")
+            lastG = 0;
+        if (key !== "j" && key !== "f" && key !== "?" && key !== "g")
+            return false;
+        if (key === "g") {
+            const now = Date.now();
+            if (!lastG || now - lastG > GG_WINDOW_MS) {
+                lastG = now;
+                return false;
+            }
+            lastG = 0;
+        }
+        const hit = firstBlock();
+        if (!hit)
+            return false;
+        e.preventDefault();
+        const first = hit.cards[0];
+        if (key === "?") {
+            forward(first, "?");
+            return true;
+        }
+        if (key === "f" && F_ROUTES_TO_BLOCK.has(hit.block.type)) {
+            forward(first, "f");
+            // The block focused its next needs-you card; if nothing needs you,
+            // land on the first card so the reviewer is somewhere.
+            if (hit.section.contains(document.activeElement))
+                return true;
+        }
+        focusCard(first);
+        return true;
+    }
+    return { handleKeydown };
+}