@mythicalos/ui-core 0.2.1 → 0.3.0

package/dist/logic/popover.js

@@ -0,0 +1,303 @@
+// @mythicalos/ui-core — PURE, DOM-free dropdown-popover logic (ds/components-popover, the
+// component registry's `popover` v1 row). The design card is a chip trigger ("review lane:
+// **codex cross-model** ▾") over an anchored panel — `--my-shadow-modal`, high z-index, ✓ marking
+// the current item, and "ancestors must never clip it".
+//
+// EVERY decision the popover makes lives here so the Preact and React bindings can only ever
+// render, never decide: class derivation, the viewport-aware flip/align geometry, the keyboard
+// grammar (which key does what), roving-focus index arithmetic that skips disabled rows, the
+// trigger's text composition, and the ARIA attribute maps. The bindings own exactly two things
+// this module cannot: touching the DOM (measuring, focusing, listening) and rendering.
+//
+// Geometry provenance: `resolvePopoverPlacement` reproduces the established approach in
+// `src/select/mythical-select.js`'s `data-flip` handling — flip up only when the panel would clip
+// below AND genuinely fits above, measured as `panelHeight + gap + breathing` against the
+// viewport. Keeping one rule means <mythical-select> and <Popover> never disagree about which way
+// a list opens on the same screen.
+/** Trigger caret (design card: `<span class="car">▾</span>`). */
+export const POPOVER_CARET = "▾";
+/** Selected-item marker (design card: "✓ marks current"). */
+export const POPOVER_CHECK = "✓";
+/** Anchor gap in px — the design card's `top: calc(100% + 6px)`. Mirrored in styles.css. */
+export const POPOVER_GAP_PX = 6;
+/** Extra breathing room the flip test demands beyond the gap (mythical-select uses `height + 8`
+ * for a 6px gap — i.e. gap + 2). */
+export const POPOVER_BREATHING_PX = 2;
+/** Trigger value shown when nothing is selected (the em-dash placeholder, as in the product's
+ * hand-rolled selector) — never a fabricated item label. */
+export const POPOVER_EMPTY_VALUE = "—";
+/** The pre-measurement position: the design card's own (anchored below, left-aligned). A binding
+ * renders this on the first open frame, then corrects it once the panel can be measured. */
+export const POPOVER_DEFAULT_POSITION = { placement: "below", align: "start" };
+/**
+ * Viewport-aware vertical placement. Flips UP only when the panel would clip off the bottom AND it
+ * genuinely fits above — a panel taller than both gaps stays `below` (scrolling down to it beats
+ * clipping it against the top edge, and it matches <mythical-select>'s behaviour exactly).
+ */
+export function resolvePopoverPlacement(anchor, panelHeight, viewport, gap = POPOVER_GAP_PX) {
+    const need = panelHeight + gap + POPOVER_BREATHING_PX;
+    return anchor.bottom + need > viewport.height && anchor.top - need > 0 ? "above" : "below";
+}
+/**
+ * Viewport-aware horizontal alignment. The panel is start-aligned (design card: `left: 0`) and
+ * switches to end-aligned only when start does NOT fit and end does.
+ *
+ * "Fits" means BOTH resulting edges are inside the viewport, on both branches — an alignment pins
+ * one panel edge to the matching anchor edge, so an anchor that is itself partly off-screen drags
+ * the panel off with it. Testing only the far edge is wrong in each direction symmetrically:
+ * start-aligning an anchor hanging off the LEFT clips the panel's left edge even though its right
+ * edge is comfortable, and end-aligning an anchor hanging off the RIGHT clips its right edge even
+ * though `right - panelWidth >= 0`. A panel that fits neither way stays `start` — flipping would
+ * only trade one overflow for the other.
+ */
+export function resolvePopoverAlign(anchor, panelWidth, viewport) {
+    const startFits = anchor.left >= 0 && anchor.left + panelWidth <= viewport.width;
+    const endFits = anchor.right <= viewport.width && anchor.right - panelWidth >= 0;
+    return !startFits && endFits ? "end" : "start";
+}
+/** Both axes at once — what a binding calls from its post-open measurement effect. */
+export function resolvePopoverPosition(anchor, panel, viewport, gap = POPOVER_GAP_PX) {
+    return {
+        placement: resolvePopoverPlacement(anchor, panel.height, viewport, gap),
+        align: resolvePopoverAlign(anchor, panel.width, viewport),
+    };
+}
+/** True when two positions describe the same placement — lets a binding skip a redundant
+ * re-render after re-measuring (and, more importantly, not loop measure→setState→measure). */
+export function samePopoverPosition(a, b) {
+    return a.placement === b.placement && a.align === b.align;
+}
+/* ── class derivation ─────────────────────────────────────────────────── */
+/**
+ * EVERY class name this component family renders — the derived ones the functions below compose
+ * AND the purely structural ones a binding puts on a wrapper/span. One source, so a binding cannot
+ * invent, misspell, or quietly re-style a class, and the Preact and React siblings cannot drift on
+ * markup either. (The rest of this package's atoms inline their structural classes in both
+ * bindings; the popover has more of them than any other atom, so it earns the map.)
+ */
+export const POPOVER_CLASS = {
+    anchor: "my-pop-anchor",
+    trigger: "my-pop-trigger",
+    triggerLabel: "my-pop-trigger__label",
+    triggerValue: "my-pop-trigger__value",
+    triggerCaret: "my-pop-trigger__caret",
+    panel: "my-pop",
+    panelAbove: "my-pop--above",
+    panelEnd: "my-pop--end",
+    head: "my-pop__head",
+    title: "my-pop__title",
+    caption: "my-pop__caption",
+    menu: "my-pop__menu",
+    item: "my-pop__item",
+    itemLabel: "my-pop__label",
+    itemCheck: "my-pop__check",
+    divider: "my-pop__div",
+    foot: "my-pop__foot",
+    isOpen: "is-open",
+    isSelected: "is-selected",
+    isDisabled: "is-disabled",
+};
+/** Trigger class list. Shape rule 10: the trigger is clickable, so styles.css gives it
+ * `--my-r-control` — never the pill radius. */
+export function popoverTriggerClass(s = {}) {
+    const cls = [POPOVER_CLASS.trigger];
+    if (s.open)
+        cls.push(POPOVER_CLASS.isOpen);
+    if (s.disabled)
+        cls.push(POPOVER_CLASS.isDisabled);
+    return cls.join(" ");
+}
+/** Panel class list; the flip/align modifiers are the only thing position changes. */
+export function popoverPanelClass(pos = POPOVER_DEFAULT_POSITION) {
+    const cls = [POPOVER_CLASS.panel];
+    if (pos.placement === "above")
+        cls.push(POPOVER_CLASS.panelAbove);
+    if (pos.align === "end")
+        cls.push(POPOVER_CLASS.panelEnd);
+    return cls.join(" ");
+}
+/** Menu-row class list. */
+export function popoverItemClass(item = {}) {
+    const cls = [POPOVER_CLASS.item];
+    if (item.selected)
+        cls.push(POPOVER_CLASS.isSelected);
+    if (item.disabled)
+        cls.push(POPOVER_CLASS.isDisabled);
+    return cls.join(" ");
+}
+/** Stable, collision-free id set derived from one caller-supplied base id. */
+export function popoverIds(baseId) {
+    return {
+        trigger: `${baseId}-trigger`,
+        panel: `${baseId}-panel`,
+        menu: `${baseId}-menu`,
+        title: `${baseId}-title`,
+    };
+}
+export function popoverTriggerAria(open, ids) {
+    return {
+        id: ids.trigger,
+        "aria-haspopup": "menu",
+        "aria-expanded": open ? "true" : "false",
+        "aria-controls": open ? ids.menu : undefined,
+    };
+}
+/** The visual panel: the surface, deliberately WITHOUT a role. It holds the optional heading and
+ * the caller's footer, which a `menu` may not own. */
+export function popoverPanelAria(ids) {
+    return { id: ids.panel };
+}
+/** The nested menu, which owns ONLY the `menuitemradio` rows. Named by the heading when there is
+ * one (the more specific label), otherwise by the trigger. */
+export function popoverMenuAria(ids, titled) {
+    return { id: ids.menu, role: "menu", "aria-labelledby": titled ? ids.title : ids.trigger };
+}
+/**
+ * The caret and the ✓ are pure decoration: the trigger's `aria-expanded` and the row's
+ * `aria-checked` already convey both states, so reading the glyphs would duplicate them. Lives here
+ * rather than inline in each binding so neither can quietly un-hide one.
+ */
+export const POPOVER_DECORATIVE_ARIA = { "aria-hidden": "true" };
+/** The rule between the menu and the caller's footer — a real separator, not a styled `<div>`. */
+export const POPOVER_SEPARATOR_ARIA = { role: "separator" };
+export function popoverItemAria(item) {
+    return {
+        role: "menuitemradio",
+        "aria-checked": item.selected ? "true" : "false",
+        "aria-disabled": item.disabled ? "true" : undefined,
+    };
+}
+export function popoverTriggerKeyAction(key) {
+    if (key === "ArrowDown")
+        return "open-first";
+    if (key === "ArrowUp")
+        return "open-last";
+    return null;
+}
+export function popoverPanelKeyAction(key) {
+    switch (key) {
+        case "Escape":
+            return "close";
+        case "Tab":
+            return "dismiss";
+        case "ArrowDown":
+            return "next";
+        case "ArrowUp":
+            return "prev";
+        case "Home":
+            return "first";
+        case "End":
+            return "last";
+        default:
+            return null;
+    }
+}
+/** Should the binding call `preventDefault()`? Everything we act on, except `dismiss` — Tab MUST
+ * keep its native behaviour or the popover becomes a focus trap. */
+export function popoverKeyHandled(action) {
+    return action !== null && action !== "dismiss";
+}
+/**
+ * Does this action apply to the element that currently has focus?
+ *
+ * Dismissal (Escape / Tab) applies from ANYWHERE inside the popover — including the caller's
+ * footer content, where Escape must still close. Roving (arrows / Home / End) applies ONLY when
+ * focus is on a menu row or on the panel fallback. That distinction is load-bearing, not tidiness:
+ * a footer control is arbitrary caller markup, so swallowing Home/End there would steal a text
+ * input's caret keys, and swallowing an arrow would yank focus out of the footer and into the menu.
+ * The binding supplies the one thing this module cannot compute — whether the focused element is a
+ * roving surface.
+ */
+export function popoverAppliesToFocus(action, focusOnRovingSurface) {
+    if (action === null)
+        return false;
+    if (action === "close" || action === "dismiss")
+        return true;
+    return focusOnRovingSurface;
+}
+/* ── roving-focus index arithmetic (disabled rows are skipped, ends wrap) ── */
+/** Index of the first enabled item scanning forward (`dir` 1) or backward (`dir` -1); -1 if every
+ * item is disabled (or the list is empty). */
+export function edgePopoverIndex(items, dir = 1) {
+    const n = items.length;
+    for (let step = 0; step < n; step++) {
+        const i = dir === 1 ? step : n - 1 - step;
+        if (!items[i]?.disabled)
+            return i;
+    }
+    return -1;
+}
+/** The next enabled index from `from` in `dir`, wrapping. Returns -1 when nothing is enabled and
+ * `from` itself when it is the ONLY enabled row (a wrap that lands back where it started). */
+export function stepPopoverIndex(items, from, dir) {
+    const n = items.length;
+    if (n === 0)
+        return -1;
+    for (let step = 1; step <= n; step++) {
+        const i = (((from + dir * step) % n) + n) % n;
+        if (!items[i]?.disabled)
+            return i;
+    }
+    return -1;
+}
+/**
+ * Where focus lands when the panel opens: the selected row if it is focusable, else the first
+ * enabled one. A selected-but-disabled row does not swallow focus.
+ */
+export function initialPopoverIndex(items) {
+    const sel = items.findIndex((it) => it.selected && !it.disabled);
+    return sel >= 0 ? sel : edgePopoverIndex(items, 1);
+}
+/**
+ * The single entry point a binding's keydown handler calls: maps a panel key action + the current
+ * focused index to the next focused index. Non-navigation actions (and a null action) leave the
+ * index untouched, so the caller never has to branch on the action twice.
+ *
+ * `current < 0` means "focus is in the panel but not on a row" (an all-disabled or empty list, or
+ * a click that landed on the panel's padding). From there Down means the FIRST enabled row and Up
+ * means the LAST — not a wrap arithmetic accident off index -1.
+ */
+export function resolvePopoverIndex(action, items, current) {
+    switch (action) {
+        case "next":
+            return current < 0 ? edgePopoverIndex(items, 1) : stepPopoverIndex(items, current, 1);
+        case "prev":
+            return current < 0 ? edgePopoverIndex(items, -1) : stepPopoverIndex(items, current, -1);
+        case "first":
+            return edgePopoverIndex(items, 1);
+        case "last":
+            return edgePopoverIndex(items, -1);
+        default:
+            return current;
+    }
+}
+/* ── optional slots ───────────────────────────────────────────────────── */
+/**
+ * Is an optional slot (heading, caption, footer) worth rendering its chrome?
+ *
+ * `undefined`, `null`, `false` and `""` are all values BOTH frameworks render as nothing, and the
+ * idiomatic conditional slot is `footer={enabled && <Action />}` — which passes `false`, not
+ * `undefined`, when disabled. Testing `!== undefined` would leave an orphan separator and an empty
+ * box behind it, and an empty heading would leave the menu's `aria-labelledby` pointing at an
+ * element with no text. Shared here so both bindings apply the same rule.
+ */
+export function popoverHasSlotContent(slot) {
+    return slot !== undefined && slot !== null && slot !== false && slot !== "";
+}
+/**
+ * The trigger face: prefix + the CURRENTLY selected item's label. Honest by construction — with no
+ * selection (or a selection that is not in the list) it shows the placeholder rather than naming an
+ * item that is not actually chosen.
+ */
+export function popoverTriggerText(items, opts = {}) {
+    const sel = items.find((it) => it.selected);
+    return {
+        label: opts.label ?? null,
+        value: sel ? sel.label : (opts.placeholder ?? POPOVER_EMPTY_VALUE),
+    };
+}
+// Deliberately NOT exported: an `aria-label` for the trigger. The trigger renders its label and
+// value as real text (only the caret is aria-hidden), so its accessible name is already computed
+// from exactly what the eye reads. Adding an aria-label would override that visible text — the
+// classic "label in name" failure — so the panel points at the trigger with `aria-labelledby`
+// instead of anyone re-deriving a string.

package/dist/logic/queue.d.ts

@@ -0,0 +1,142 @@
+import type { DeliveryClass } from "./sendbar.js";
+/** Queue record lifecycle. `queued` is the ONLY cancellable state (see `canCancelRow`). */
+export type QueueItemStatus = "queued" | "leased" | "delivered" | "canceled";
+/** One queue record, generic over the product: an opaque id, its class, its body, its status. */
+export interface QueueItem {
+    id: string;
+    cls: DeliveryClass;
+    body: string;
+    status: QueueItemStatus;
+}
+/**
+ * Why the queue cannot be shown. These stay DISTINCT on purpose (see `QUEUE_UNAVAILABLE_COPY`):
+ * collapsing them into one message would make the UI claim something it does not know.
+ *  - `unsupported`  — this deployment does not do queued delivery at all.
+ *  - `error`        — the read failed. Says only that; never that the queue is empty.
+ *  - `unaddressable` — there is no queue address to read for this target.
+ */
+export type QueueUnavailableReason = "unsupported" | "error" | "unaddressable";
+/**
+ * HONESTY INVARIANT (binding, do not reword): CAPABILITY-NEUTRAL empty copy. It reports what the
+ * READ returned and nothing else. It must never claim operational emptiness ("queue empty", "no
+ * pending deliveries"), never imply a store exists, and never restate the design card's
+ * "deliveries land here by class (ASAP interrupts · ON-DONE waits)" — that line is doubly false
+ * (it asserts a store AND the interrupt semantics `DELIVERY_HINT` corrects).
+ */
+export declare const QUEUE_EMPTY_COPY = "The queue read returned no records.";
+/** Stale = last-known data. NO retry/reconnect claim — nothing here is recovering on its own. */
+export declare const QUEUE_STALE_COPY = "Queue disconnected \u2014 showing the last received list.";
+export declare const QUEUE_LOADING_COPY = "Loading queue\u2026";
+/** The three unavailable reasons, each with its own copy. Asserted pairwise-distinct by test. */
+export declare const QUEUE_UNAVAILABLE_COPY: Record<QueueUnavailableReason, string>;
+export declare const QUEUE_CANCEL_ASK = "Cancel this delivery?";
+export declare const QUEUE_CANCEL_YES = "Cancel it";
+export declare const QUEUE_CANCEL_NO = "Keep";
+export declare const QUEUE_CANCEL_LABEL = "\u2715 cancel";
+/**
+ * Every structural class the queue renders. Named here — not typed literally in a binding — so the
+ * Preact and React bindings cannot drift.
+ */
+export declare const QUEUE_CLASSES: {
+    readonly panel: "my-queue";
+    readonly list: "my-queue__list";
+    readonly state: "my-queue__state";
+    readonly stale: "my-queue__stale";
+    readonly empty: "my-queue__empty";
+    readonly rowBody: "my-qrow__body";
+    readonly rowStatus: "my-qrow__status";
+    readonly cancel: "my-qrow__cancel";
+    readonly ask: "my-qrow__ask";
+    readonly actions: "my-qrow__acts";
+    readonly confirmYes: "my-qmini my-qmini--yes";
+    readonly confirmNo: "my-qmini my-qmini--no";
+};
+/**
+ * The queue's input. `stale` is its OWN state, never folded into `ok` — a failing poll that still
+ * holds the last received list is a materially different claim from a fresh successful read.
+ */
+export type QueueSource = {
+    kind: "loading";
+} | {
+    kind: "unavailable";
+    reason: QueueUnavailableReason;
+} | {
+    kind: "ok";
+    items: readonly QueueItem[];
+} | {
+    kind: "stale";
+    items: readonly QueueItem[];
+};
+/** What the panel body renders. `empty` is reachable from exactly one source arm — see below. */
+export type QueueView = {
+    kind: "state";
+    copy: string;
+} | {
+    kind: "empty";
+    copy: string;
+} | {
+    kind: "list";
+    items: readonly QueueItem[];
+    staleCopy: string | null;
+    /** See `isFreshSource` — false suppresses every cancel affordance in the list. */
+    fresh: boolean;
+};
+/**
+ * HONESTY INVARIANT (binding): only a completed SUCCESSFUL read is fresh. A `stale` list is
+ * last-known data — the poll is failing, so each row's status is what it WAS, not what it is. That
+ * makes a cancel control on a stale row a claim the component cannot support: it would assert the
+ * record is still `queued` right beside a banner saying the list is no longer current. Stale rows
+ * therefore render with no cancel affordance, and an armed confirm force-disarms when its source
+ * goes stale (`shouldDisarmCancel`).
+ */
+export declare function isFreshSource(source: QueueSource): boolean;
+/**
+ * HONESTY INVARIANT (binding): the empty presentation renders ONLY on `ok` + zero items — i.e. only
+ * after a fresh successful read actually returned nothing.
+ *  - `loading` renders the loading state, NEVER "empty" (an unfinished read knows nothing yet).
+ *  - `unavailable` renders its own distinct reason copy, NEVER "empty".
+ *  - `stale` with zero items renders a flagged (but empty) LIST, never the empty copy — the last
+ *    received list happening to be empty is not a fresh "there is nothing queued" claim.
+ *
+ * `unavailableDetail` lets a product ADD what it knows about a reason (e.g. which mode the daemon
+ * is in). It is APPENDED to this package's own sentence, never substituted for it — a caller
+ * therefore cannot collapse two reasons into one message, deliberately or by accident: the distinct
+ * base sentences always survive, so two reasons can never render identical copy.
+ */
+export declare function unavailableText(reason: QueueUnavailableReason, detail?: string): string;
+export declare function queueView(source: QueueSource, unavailableDetail?: Partial<Record<QueueUnavailableReason, string>>): QueueView;
+/** ASAP / ON-DONE badge label (verbatim). */
+export declare function queueBadgeLabel(cls: DeliveryClass): "ASAP" | "ON-DONE";
+/** Badge class: ASAP → accent-soft, ON-DONE → disabled-muted (design card). */
+export declare function queueBadgeClass(cls: DeliveryClass): string;
+/** The row class. An armed row swaps to the confirm presentation instead of a status modifier. */
+export declare function queueRowClass(status: QueueItemStatus, armed: boolean): string;
+/** Human status label — the status verbatim, never a friendlier synonym that loses precision. */
+export declare function queueStatusLabel(status: QueueItemStatus): string;
+/**
+ * HONESTY INVARIANT (binding): the cancel affordance exists ONLY on `queued` records AND only when
+ * the caller says the record is cancellable at all (`canCancel` — e.g. the viewer owns the queue).
+ * Every other status renders WITHOUT an active cancel control: no greyed-out button that implies a
+ * cancel could have happened, and never a control whose click would be rejected downstream.
+ */
+export declare function canCancelRow(status: QueueItemStatus, canCancel: boolean): boolean;
+export type CancelState = {
+    armedId: string | null;
+};
+export type CancelEvent = {
+    type: "arm";
+    id: string;
+} | {
+    type: "confirm";
+} | {
+    type: "disarm";
+};
+export declare function cancelReducer(state: CancelState, event: CancelEvent): CancelState;
+/**
+ * An armed two-step cancel must NEVER outlive its cancelability. Force-disarm when cancelability is
+ * lost (`canCancel` flips false), when the source stops being FRESH (it went stale, unavailable, or
+ * back to loading — the armed row is then last-known data, not a live record), or when the armed row
+ * is no longer a live `queued` record in the current source (it left the queue as
+ * leased/delivered/canceled, or vanished).
+ */
+export declare function shouldDisarmCancel(armedId: string | null, canCancel: boolean, source: QueueSource): boolean;

package/dist/logic/queue.js

@@ -0,0 +1,143 @@
+// @mythicalos/ui-core — the queue-row half of the terminal set (ds/components-terminal, spec v2):
+// the delivery queue's source→view resolution, row classes, and the two-step inline-cancel state
+// machine. Pure — no framework, no DOM. The honesty rules below live HERE, not in the product, so
+// every consumer inherits them.
+import { deliveryClassLabel } from "./sendbar.js";
+/**
+ * HONESTY INVARIANT (binding, do not reword): CAPABILITY-NEUTRAL empty copy. It reports what the
+ * READ returned and nothing else. It must never claim operational emptiness ("queue empty", "no
+ * pending deliveries"), never imply a store exists, and never restate the design card's
+ * "deliveries land here by class (ASAP interrupts · ON-DONE waits)" — that line is doubly false
+ * (it asserts a store AND the interrupt semantics `DELIVERY_HINT` corrects).
+ */
+export const QUEUE_EMPTY_COPY = "The queue read returned no records.";
+/** Stale = last-known data. NO retry/reconnect claim — nothing here is recovering on its own. */
+export const QUEUE_STALE_COPY = "Queue disconnected — showing the last received list.";
+export const QUEUE_LOADING_COPY = "Loading queue…";
+/** The three unavailable reasons, each with its own copy. Asserted pairwise-distinct by test. */
+export const QUEUE_UNAVAILABLE_COPY = {
+    unsupported: "Queued delivery is unavailable in this mode.",
+    error: "The queue could not be read.",
+    unaddressable: "This session has no queue address.",
+};
+export const QUEUE_CANCEL_ASK = "Cancel this delivery?";
+export const QUEUE_CANCEL_YES = "Cancel it";
+export const QUEUE_CANCEL_NO = "Keep";
+export const QUEUE_CANCEL_LABEL = "✕ cancel";
+/**
+ * Every structural class the queue renders. Named here — not typed literally in a binding — so the
+ * Preact and React bindings cannot drift.
+ */
+export const QUEUE_CLASSES = {
+    panel: "my-queue",
+    list: "my-queue__list",
+    state: "my-queue__state",
+    stale: "my-queue__stale",
+    empty: "my-queue__empty",
+    rowBody: "my-qrow__body",
+    rowStatus: "my-qrow__status",
+    cancel: "my-qrow__cancel",
+    ask: "my-qrow__ask",
+    actions: "my-qrow__acts",
+    confirmYes: "my-qmini my-qmini--yes",
+    confirmNo: "my-qmini my-qmini--no",
+};
+/**
+ * HONESTY INVARIANT (binding): only a completed SUCCESSFUL read is fresh. A `stale` list is
+ * last-known data — the poll is failing, so each row's status is what it WAS, not what it is. That
+ * makes a cancel control on a stale row a claim the component cannot support: it would assert the
+ * record is still `queued` right beside a banner saying the list is no longer current. Stale rows
+ * therefore render with no cancel affordance, and an armed confirm force-disarms when its source
+ * goes stale (`shouldDisarmCancel`).
+ */
+export function isFreshSource(source) {
+    return source.kind === "ok";
+}
+/**
+ * HONESTY INVARIANT (binding): the empty presentation renders ONLY on `ok` + zero items — i.e. only
+ * after a fresh successful read actually returned nothing.
+ *  - `loading` renders the loading state, NEVER "empty" (an unfinished read knows nothing yet).
+ *  - `unavailable` renders its own distinct reason copy, NEVER "empty".
+ *  - `stale` with zero items renders a flagged (but empty) LIST, never the empty copy — the last
+ *    received list happening to be empty is not a fresh "there is nothing queued" claim.
+ *
+ * `unavailableDetail` lets a product ADD what it knows about a reason (e.g. which mode the daemon
+ * is in). It is APPENDED to this package's own sentence, never substituted for it — a caller
+ * therefore cannot collapse two reasons into one message, deliberately or by accident: the distinct
+ * base sentences always survive, so two reasons can never render identical copy.
+ */
+export function unavailableText(reason, detail) {
+    const base = QUEUE_UNAVAILABLE_COPY[reason];
+    const extra = detail?.trim();
+    return extra ? `${base} ${extra}` : base;
+}
+export function queueView(source, unavailableDetail) {
+    switch (source.kind) {
+        case "loading":
+            return { kind: "state", copy: QUEUE_LOADING_COPY };
+        case "unavailable":
+            return { kind: "state", copy: unavailableText(source.reason, unavailableDetail?.[source.reason]) };
+        case "ok":
+            return source.items.length === 0
+                ? { kind: "empty", copy: QUEUE_EMPTY_COPY }
+                : { kind: "list", items: source.items, staleCopy: null, fresh: true };
+        case "stale":
+            return { kind: "list", items: source.items, staleCopy: QUEUE_STALE_COPY, fresh: false };
+    }
+}
+// ── class + label derivation ──
+/** ASAP / ON-DONE badge label (verbatim). */
+export function queueBadgeLabel(cls) {
+    return deliveryClassLabel(cls);
+}
+/** Badge class: ASAP → accent-soft, ON-DONE → disabled-muted (design card). */
+export function queueBadgeClass(cls) {
+    return cls === "asap" ? "my-qbadge my-qbadge--asap" : "my-qbadge my-qbadge--done";
+}
+/** The row class. An armed row swaps to the confirm presentation instead of a status modifier. */
+export function queueRowClass(status, armed) {
+    return armed ? "my-qrow is-confirm" : `my-qrow my-qrow--${status}`;
+}
+/** Human status label — the status verbatim, never a friendlier synonym that loses precision. */
+export function queueStatusLabel(status) {
+    return status;
+}
+/**
+ * HONESTY INVARIANT (binding): the cancel affordance exists ONLY on `queued` records AND only when
+ * the caller says the record is cancellable at all (`canCancel` — e.g. the viewer owns the queue).
+ * Every other status renders WITHOUT an active cancel control: no greyed-out button that implies a
+ * cancel could have happened, and never a control whose click would be rejected downstream.
+ */
+export function canCancelRow(status, canCancel) {
+    return canCancel && status === "queued";
+}
+export function cancelReducer(state, event) {
+    switch (event.type) {
+        case "arm":
+            return { armedId: event.id };
+        case "confirm":
+            return { armedId: null }; // the onCancel(id) side-effect belongs to the component, not here
+        case "disarm":
+            return { armedId: null };
+    }
+}
+/**
+ * An armed two-step cancel must NEVER outlive its cancelability. Force-disarm when cancelability is
+ * lost (`canCancel` flips false), when the source stops being FRESH (it went stale, unavailable, or
+ * back to loading — the armed row is then last-known data, not a live record), or when the armed row
+ * is no longer a live `queued` record in the current source (it left the queue as
+ * leased/delivered/canceled, or vanished).
+ */
+export function shouldDisarmCancel(armedId, canCancel, source) {
+    if (armedId === null)
+        return false;
+    if (!canCancel)
+        return true;
+    // deliberately `ok` only: a `stale` list still carries items, but they are the LAST RECEIVED
+    // statuses, so an arm held against them would be a cancel aimed at data we know is out of date
+    if (!isFreshSource(source))
+        return true;
+    const items = source.kind === "ok" ? source.items : [];
+    const row = items.find((it) => it.id === armedId);
+    return row === undefined || !canCancelRow(row.status, canCancel);
+}

package/dist/logic/save-bar.d.ts

@@ -0,0 +1,39 @@
+/** The separator between the bold "N unsaved change(s)" count and the changed-field list. */
+export declare const SAVE_BAR_SEP = " \u00B7 ";
+/** Design-card copy for the two actions (ds/layouts-settings.html). Both are overridable per
+ *  surface — the reference product's settings page says "Save locally" because its save writes to
+ *  the local container, not the card's "Save & apply". */
+export declare const SAVE_BAR_DISCARD_LABEL = "Discard";
+export declare const SAVE_BAR_SAVE_LABEL = "Save & apply";
+export interface SaveBarNote {
+    /** How many fields are dirty. `0` ⇒ the bar must not be shown at all (see `saveBarDirty`). */
+    count: number;
+    /** The bold lead-in: `1 unsaved change` / `3 unsaved changes`. */
+    countLabel: string;
+    /** The changed-field list that follows the separator: `Base URL, Harness`. */
+    detail: string;
+    /** The full visible sentence, `countLabel + SAVE_BAR_SEP + detail`. Empty `detail` ⇒ just the
+     *  count (never a dangling separator). */
+    text: string;
+}
+/** Compose the save bar's note from the list of changed-field labels. Pluralization is decided
+ *  here, once, for both bindings. Non-string / blank entries are dropped rather than rendered as
+ *  `undefined` in the list — but they are dropped BEFORE the count, so the count always equals the
+ *  number of fields actually named. */
+export declare function saveBarNote(changed: readonly string[]): SaveBarNote;
+/** The card's "the save bar slides up only when dirty" rule, as a predicate. The bindings return
+ *  `null` for a not-dirty bar so no surface can ever render "0 unsaved changes" next to a live
+ *  Save button. */
+export declare function saveBarDirty(changed: readonly string[]): boolean;
+/** Every class the bar renders, root and elements. The bindings import these rather than spelling
+ *  the strings themselves, so a rename cannot land in one framework and not the other, and the
+ *  stylesheet test can enumerate the parts instead of restating a hand-written list. */
+export declare const SAVE_BAR_PARTS: {
+    readonly root: "my-savebar";
+    readonly note: "my-savebar__note";
+    readonly count: "my-savebar__count";
+    readonly actions: "my-savebar__actions";
+};
+/** Root class for the bar. No tone axis — the modifier space is reserved for the caller's own
+ *  passthrough class, which the bindings append. */
+export declare function saveBarClass(): string;