npm - @mythicalos/preact-ui - Versions diffs - 0.2.2 → 0.4.0 - Mend

@mythicalos/preact-ui 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/dist/Popover.js ADDED Viewed

@@ -0,0 +1,167 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+// @mythicalos/preact-ui — the dropdown popover (ds/components-popover, registry row `popover` v1).
+// A chip trigger over an anchored single-select menu: "review lane: **codex cross-model** ▾", ✓ on
+// the current row, `--my-shadow-modal`, high z-index.
+//
+// This file is WIRING ONLY. Every decision — class strings, the viewport-aware flip/align
+// geometry, which key does what, roving-focus index arithmetic that skips disabled rows, the
+// trigger's text composition, and the ARIA maps — is imported from `@mythicalos/ui-core`, so this
+// binding and its React sibling cannot drift. The three things that genuinely cannot live in the
+// core are all this component adds: measuring the DOM, moving focus, and rendering.
+//
+// Behavioural requirements were taken from the design card plus the hand-rolled selector the
+// product ships today (rail/ProjectSelector.tsx): outside-pointerdown and Escape close; Escape and
+// selecting BOTH return focus to the trigger (never stranding it on <body>); focus moves INTO the
+// menu on open, landing on the selected row; Arrow/Home/End rove within it; and an optional
+// head (title + caption) and footer action sit around the rows.
+//
+// Documented residual: the flip/align decision is re-measured on open, on window resize, and on
+// any scroll — but not on a mutation that changes the panel's own size while it is open (no
+// ResizeObserver). `<mythical-select>` measures on open only; this is a superset of the
+// established approach, not a regression against it.
+//
+// Consumer contract (design card, verbatim): "Ancestors must never clip it." The panel is
+// absolutely positioned inside `.my-pop-anchor`, so an ancestor with `overflow: hidden`/`auto`
+// will crop it.
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "preact/hooks";
+import { POPOVER_CARET, POPOVER_CHECK, POPOVER_CLASS, POPOVER_DECORATIVE_ARIA, POPOVER_DEFAULT_POSITION, POPOVER_SEPARATOR_ARIA, edgePopoverIndex, initialPopoverIndex, popoverHasSlotContent, popoverIds, popoverItemAria, popoverItemClass, popoverAppliesToFocus, popoverKeyHandled, popoverMenuAria, popoverPanelAria, popoverPanelClass, popoverPanelKeyAction, popoverTriggerAria, popoverTriggerClass, popoverTriggerKeyAction, popoverTriggerText, resolvePopoverIndex, resolvePopoverPosition, samePopoverPosition, } from "@mythicalos/ui-core/logic";
+export { POPOVER_CARET, POPOVER_CHECK, POPOVER_CLASS, POPOVER_EMPTY_VALUE, popoverItemClass, popoverPanelClass, popoverTriggerClass, popoverTriggerText, resolvePopoverPosition, } from "@mythicalos/ui-core/logic";
+/**
+ * The OPEN panel, deliberately hook-free (same testability split as the shell's `SwitcherPanel`):
+ * `preact-render-to-string` never runs effects or dispatches events, so the panel markup — and a
+ * row's REAL onClick closure, reachable off the returned vnode tree — would otherwise be
+ * unreachable from a DOM-free test. Exported from this module for tests; NOT part of the package
+ * barrel. `panelRef` rather than `ref` because plain Preact does not forward `ref` to a function
+ * component, and the React sibling keeps the same prop name so the two stay symmetric.
+ */
+export function PopoverPanel(props) {
+    return (_jsxs("div", { ref: props.panelRef, class: popoverPanelClass(props.pos), tabIndex: -1, ...popoverPanelAria(props.ids), children: [popoverHasSlotContent(props.title) || popoverHasSlotContent(props.caption) ? (_jsxs("div", { class: POPOVER_CLASS.head, children: [popoverHasSlotContent(props.title) ? (_jsx("span", { id: props.ids.title, class: POPOVER_CLASS.title, children: props.title })) : null, popoverHasSlotContent(props.caption) ? _jsx("span", { class: POPOVER_CLASS.caption, children: props.caption }) : null] })) : null, _jsx("div", { class: POPOVER_CLASS.menu, ...popoverMenuAria(props.ids, popoverHasSlotContent(props.title)), children: props.items.map((item) => (_jsxs("button", { type: "button", "data-pop-item": "", class: popoverItemClass(item), disabled: item.disabled, ...popoverItemAria(item), onClick: () => {
+                        if (item.disabled)
+                            return; // belt-and-braces: a native disabled button fires no click
+                        props.onPick(item);
+                    }, children: [_jsx("span", { class: POPOVER_CLASS.itemLabel, children: item.label }), _jsx("span", { class: POPOVER_CLASS.itemCheck, ...POPOVER_DECORATIVE_ARIA, children: item.selected ? POPOVER_CHECK : "" })] }, item.key))) }), popoverHasSlotContent(props.footer) ? (_jsxs(_Fragment, { children: [_jsx("div", { class: POPOVER_CLASS.divider, ...POPOVER_SEPARATOR_ARIA }), _jsx("div", { class: POPOVER_CLASS.foot, children: props.footer })] })) : null] }));
+}
+/** A single-select dropdown popover anchored to its own chip trigger. */
+export function Popover(props) {
+    const { items, disabled = false } = props;
+    const generatedId = useId();
+    const ids = popoverIds(props.id ?? generatedId);
+    const [open, setOpen] = useState(false);
+    const [pos, setPos] = useState(POPOVER_DEFAULT_POSITION);
+    const anchorRef = useRef(null);
+    const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    /** Row to focus on the next open (-1 ⇒ let `initialPopoverIndex` decide). */
+    const pendingFocus = useRef(-1);
+    const itemNodes = () => Array.from(panelRef.current?.querySelectorAll("[data-pop-item]") ?? []);
+    const focusRow = (i) => {
+        // preventScroll: a bare focus() asks the browser to reveal the row by scrolling every
+        // scrollable ancestor — which yanks the page out from under an open popover.
+        itemNodes()[i]?.focus({ preventScroll: true });
+    };
+    const setOpenState = (next) => {
+        setOpen(next);
+        props.onOpenChange?.(next);
+    };
+    const openAt = (index) => {
+        if (disabled)
+            return;
+        pendingFocus.current = index;
+        setPos(POPOVER_DEFAULT_POSITION); // re-measured below; never reuse a stale flip
+        setOpenState(true);
+    };
+    const closeToTrigger = () => {
+        setOpenState(false);
+        triggerRef.current?.focus({ preventScroll: true });
+    };
+    // Placement: measure once the panel is in the DOM but before paint, so it never flashes at the
+    // wrong end of the trigger. Guarded by samePopoverPosition so measure → setState can't loop.
+    useLayoutEffect(() => {
+        if (!open)
+            return;
+        const measure = () => {
+            const trigger = triggerRef.current;
+            const panel = panelRef.current;
+            if (!trigger || !panel)
+                return;
+            const next = resolvePopoverPosition(trigger.getBoundingClientRect(), { width: panel.offsetWidth, height: panel.offsetHeight }, { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight });
+            setPos((prev) => (samePopoverPosition(prev, next) ? prev : next));
+        };
+        measure();
+        window.addEventListener("resize", measure);
+        // capture: scroll does not bubble, so this is the only way to see a scrollable ANCESTOR move
+        // the anchor and invalidate the flip decision.
+        document.addEventListener("scroll", measure, { capture: true, passive: true });
+        return () => {
+            window.removeEventListener("resize", measure);
+            document.removeEventListener("scroll", measure, { capture: true });
+        };
+    }, [open, items.length]);
+    // a11y: on open, focus moves INTO the menu the role promises — the selected row, else the first
+    // enabled one, else the panel itself (an empty or all-disabled list), never left on the trigger.
+    useEffect(() => {
+        if (!open)
+            return;
+        const requested = pendingFocus.current;
+        pendingFocus.current = -1;
+        const index = requested >= 0 ? requested : initialPopoverIndex(items);
+        if (index >= 0)
+            focusRow(index);
+        else
+            panelRef.current?.focus({ preventScroll: true });
+    }, [open]);
+    // Outside pointerdown closes. Focus is NOT pulled back to the trigger here: the pointer is
+    // already establishing focus somewhere else, and stealing it back would fight the user.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onDown = (e) => {
+            if (anchorRef.current && !anchorRef.current.contains(e.target))
+                setOpenState(false);
+        };
+        document.addEventListener("pointerdown", onDown, true);
+        return () => document.removeEventListener("pointerdown", onDown, true);
+    }, [open]);
+    // One handler on the anchor catches keys from the trigger AND the panel (both are inside it).
+    // The anchor is a plain <div>, but it is never itself focusable or a tab stop — every key this
+    // sees has bubbled up from a real <button>, so this is delegation, not a keyboard handler bolted
+    // onto a non-interactive element. Enter/Space are absent by design: the trigger is a real
+    // <button>, so the browser already synthesises a click from them.
+    const onKeyDown = (e) => {
+        if (disabled)
+            return;
+        if (!open) {
+            const action = popoverTriggerKeyAction(e.key);
+            if (action === null)
+                return;
+            e.preventDefault();
+            openAt(edgePopoverIndex(items, action === "open-first" ? 1 : -1));
+            return;
+        }
+        const action = popoverPanelKeyAction(e.key);
+        // Roving keys apply only on a row (or the panel fallback); the caller's footer content keeps
+        // its own arrows/Home/End. Escape and Tab still work from anywhere inside the popover.
+        const focused = itemNodes().indexOf(document.activeElement);
+        const onRovingSurface = focused >= 0 || document.activeElement === panelRef.current;
+        if (!popoverAppliesToFocus(action, onRovingSurface))
+            return;
+        // Tab ("dismiss") must keep its native behaviour or the popover is a focus trap; moving focus
+        // to the trigger first makes the browser continue the tab sequence from AFTER the trigger,
+        // which is where tabbing out of a menu belongs.
+        if (popoverKeyHandled(action))
+            e.preventDefault();
+        if (action === "close" || action === "dismiss") {
+            closeToTrigger();
+            return;
+        }
+        const next = resolvePopoverIndex(action, items, focused);
+        if (next >= 0)
+            focusRow(next);
+    };
+    const text = popoverTriggerText(items, { label: props.label, placeholder: props.placeholder });
+    return (_jsxs("div", { class: POPOVER_CLASS.anchor, ref: anchorRef, onKeyDown: onKeyDown, children: [_jsxs("button", { ref: triggerRef, type: "button", class: popoverTriggerClass({ open, disabled }), disabled: disabled, title: props.triggerTitle, ...popoverTriggerAria(open, ids), onClick: () => (open ? closeToTrigger() : openAt(-1)), children: [text.label !== null ? _jsx("span", { class: POPOVER_CLASS.triggerLabel, children: text.label }) : null, _jsx("span", { class: POPOVER_CLASS.triggerValue, children: text.value }), _jsx("span", { class: POPOVER_CLASS.triggerCaret, ...POPOVER_DECORATIVE_ARIA, children: POPOVER_CARET })] }), open ? (_jsx(PopoverPanel, { panelRef: panelRef, ids: ids, pos: pos, items: items, title: props.title, caption: props.caption, footer: props.footer, onPick: (item) => {
+                    closeToTrigger(); // a11y — selecting returns focus to the trigger, never to <body>
+                    props.onSelect(item.key, item);
+                } })) : null] }));
+}

package/dist/QueuePanel.d.ts ADDED Viewed

@@ -0,0 +1,38 @@
+/** @jsxImportSource preact */
+import { type QueueItem, type QueueSource, type QueueUnavailableReason } from "@mythicalos/ui-core/logic";
+export { QUEUE_EMPTY_COPY, QUEUE_LOADING_COPY, QUEUE_STALE_COPY, QUEUE_UNAVAILABLE_COPY, canCancelRow, cancelReducer, queueBadgeClass, queueBadgeLabel, queueRowClass, queueView, shouldDisarmCancel, unavailableText, type CancelEvent, type CancelState, type QueueItem, type QueueItemStatus, type QueueSource, type QueueUnavailableReason, type QueueView, } from "@mythicalos/ui-core/logic";
+export interface QueueRowProps {
+    item: QueueItem;
+    /** The row is showing its two-step confirm instead of its normal presentation. */
+    armed?: boolean;
+    /** Whether the cancel affordance may exist at all — combined with the status by ui-core. */
+    canCancel?: boolean;
+    onArm?(): void;
+    onConfirm?(): void;
+    onDisarm?(): void;
+}
+/**
+ * One queue record. The registry atom — usable standalone, or through `QueuePanel`.
+ *
+ * INVARIANT 4 is enforced HERE, not only by the panel: `armed` is honored only when the record is
+ * genuinely cancellable (`canCancelRow`). A caller that arms a `leased`/`delivered`/`canceled` row,
+ * or arms a row whose cancellability was revoked, gets the ordinary row back — never a live
+ * "Cancel it" button for something that cannot be cancelled. That also covers the render between a
+ * revocation and the panel's disarming effect.
+ */
+export declare function QueueRow(props: QueueRowProps): import("preact").JSX.Element;
+export interface QueuePanelProps {
+    source: QueueSource;
+    /** Whether cancelling is possible at all right now (e.g. the viewer owns the queue). */
+    canCancel?: boolean;
+    onCancel?(id: string): void;
+    /** Changing this clears any pending confirm (e.g. the selected target changed). */
+    resetKey?: string;
+    /**
+     * Extra detail per unavailable reason, APPENDED to this package's own sentence — never
+     * substituted for it. Two reasons therefore always render different copy, whatever the caller
+     * supplies (see ui-core's `unavailableText`).
+     */
+    unavailableDetail?: Partial<Record<QueueUnavailableReason, string>>;
+}
+export declare function QueuePanel(props: QueuePanelProps): import("preact").JSX.Element;

package/dist/QueuePanel.js ADDED Viewed

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+// @mythicalos/preact-ui — the delivery queue (ds/components-terminal, spec v2): `QueueRow` is the
+// registry atom; `QueuePanel` is the list that carries the source→view honesty around it.
+//
+// Thin binding: render + wiring only. The source resolution, every copy string, the row/badge class
+// derivation, and the two-step cancel state machine all come from `@mythicalos/ui-core`.
+//
+// Honesty (binding, inherited from ui-core): the empty copy is CAPABILITY-NEUTRAL and renders ONLY
+// on `ok` + zero items — never an operational-emptiness or store-existence claim, and never the
+// design card's "queue empty — deliveries land here by class (ASAP interrupts · ON-DONE waits)";
+// `loading` never renders empty; the three unavailable reasons render DISTINCTLY; `stale` is its own
+// state, flagged as last-known data with no retry claim. The cancel affordance exists ONLY on
+// `queued` records, only when the caller says the record is cancellable, and only while the
+// source is FRESH — a stale (last-known) list carries no cancel controls at all.
+import { useEffect, useReducer } from "preact/hooks";
+import { QUEUE_CANCEL_ASK, QUEUE_CANCEL_LABEL, QUEUE_CANCEL_NO, QUEUE_CANCEL_YES, QUEUE_CLASSES, canCancelRow, cancelReducer, queueBadgeClass, queueBadgeLabel, queueRowClass, queueStatusLabel, queueView, shouldDisarmCancel, } from "@mythicalos/ui-core/logic";
+export { QUEUE_EMPTY_COPY, QUEUE_LOADING_COPY, QUEUE_STALE_COPY, QUEUE_UNAVAILABLE_COPY, canCancelRow, cancelReducer, queueBadgeClass, queueBadgeLabel, queueRowClass, queueView, shouldDisarmCancel, unavailableText, } from "@mythicalos/ui-core/logic";
+/**
+ * One queue record. The registry atom — usable standalone, or through `QueuePanel`.
+ *
+ * INVARIANT 4 is enforced HERE, not only by the panel: `armed` is honored only when the record is
+ * genuinely cancellable (`canCancelRow`). A caller that arms a `leased`/`delivered`/`canceled` row,
+ * or arms a row whose cancellability was revoked, gets the ordinary row back — never a live
+ * "Cancel it" button for something that cannot be cancelled. That also covers the render between a
+ * revocation and the panel's disarming effect.
+ */
+export function QueueRow(props) {
+    const { item } = props;
+    const cancellable = canCancelRow(item.status, !!props.canCancel);
+    const badge = _jsx("span", { class: queueBadgeClass(item.cls), children: queueBadgeLabel(item.cls) });
+    if (props.armed && cancellable) {
+        return (_jsxs("div", { class: queueRowClass(item.status, true), children: [badge, _jsx("span", { class: QUEUE_CLASSES.ask, children: QUEUE_CANCEL_ASK }), _jsxs("span", { class: QUEUE_CLASSES.actions, children: [_jsx("button", { type: "button", class: QUEUE_CLASSES.confirmYes, onClick: props.onConfirm, children: QUEUE_CANCEL_YES }), _jsx("button", { type: "button", class: QUEUE_CLASSES.confirmNo, onClick: props.onDisarm, children: QUEUE_CANCEL_NO })] })] }));
+    }
+    return (_jsxs("div", { class: queueRowClass(item.status, false), children: [badge, _jsx("span", { class: QUEUE_CLASSES.rowBody, children: item.body }), _jsx("span", { class: QUEUE_CLASSES.rowStatus, children: queueStatusLabel(item.status) }), cancellable ? (_jsx("button", { type: "button", class: QUEUE_CLASSES.cancel, onClick: props.onArm, children: QUEUE_CANCEL_LABEL })) : null] }));
+}
+export function QueuePanel(props) {
+    const { source } = props;
+    const canCancel = !!props.canCancel;
+    const [cancel, dispatch] = useReducer(cancelReducer, { armedId: null });
+    // A changed target clears any pending ask.
+    useEffect(() => {
+        dispatch({ type: "disarm" });
+    }, [props.resetKey]);
+    // An armed confirm must never outlive its cancelability: ownership loss, or the armed row leaving
+    // `queued` in the CURRENT source (leased/delivered/canceled/vanished/unavailable), force-disarms.
+    const mustDisarm = shouldDisarmCancel(cancel.armedId, canCancel, source);
+    useEffect(() => {
+        if (mustDisarm)
+            dispatch({ type: "disarm" });
+    }, [mustDisarm]);
+    useEffect(() => {
+        if (cancel.armedId === null)
+            return;
+        const onKey = (e) => {
+            if (e.key === "Escape")
+                dispatch({ type: "disarm" });
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [cancel.armedId]);
+    const view = queueView(source, props.unavailableDetail);
+    return (_jsxs("div", { class: QUEUE_CLASSES.panel, children: [view.kind === "state" ? _jsx("div", { class: QUEUE_CLASSES.state, children: view.copy }) : null, view.kind === "empty" ? _jsx("div", { class: QUEUE_CLASSES.empty, children: view.copy }) : null, view.kind === "list" ? (_jsxs("div", { class: QUEUE_CLASSES.list, children: [view.staleCopy !== null ? _jsx("div", { class: QUEUE_CLASSES.stale, children: view.staleCopy }) : null, view.items.map((item) => {
+                        // A STALE list is last-known data, so no row in it may carry a cancel affordance: the
+                        // row's real status is unknown, and offering a cancel would contradict the banner right
+                        // above it. `view.fresh` is ui-core's freshness verdict, not a local guess.
+                        const rowCanCancel = canCancel && view.fresh;
+                        return (_jsx(QueueRow, { item: item, canCancel: rowCanCancel, armed: cancel.armedId === item.id, onArm: () => dispatch({ type: "arm", id: item.id }), onConfirm: () => {
+                                // Re-checked at the moment of confirm: the intent only fires if the row is STILL
+                                // fresh AND cancellable — never a stale-arm cancel.
+                                if (canCancelRow(item.status, rowCanCancel))
+                                    props.onCancel?.(item.id);
+                                dispatch({ type: "confirm" });
+                            }, onDisarm: () => dispatch({ type: "disarm" }) }, item.id));
+                    })] })) : null] }));
+}

package/dist/SaveBar.d.ts ADDED Viewed

@@ -0,0 +1,20 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from "preact";
+import { SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, SAVE_BAR_PARTS, SAVE_BAR_SEP, saveBarClass, saveBarDirty, saveBarNote, type SaveBarNote } from "@mythicalos/ui-core/logic";
+export { saveBarNote, saveBarDirty, saveBarClass, SAVE_BAR_PARTS, SAVE_BAR_SEP, SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, type SaveBarNote, };
+export interface SaveBarProps {
+    /** Human labels of the dirty fields. Empty ⇒ the bar does not render. */
+    changed: readonly string[];
+    /** A save is in flight: the primary goes loading + inert. */
+    saving?: boolean;
+    /** Card copy is "Save & apply"; override per surface (the reference product says "Save locally"
+     *  because its save writes to the local container). */
+    saveLabel?: string;
+    discardLabel?: string;
+    onDiscard: () => void;
+    onSave: () => void;
+    /** Extra content rendered between the note and the actions (e.g. a validation hint). */
+    children?: ComponentChildren;
+    class?: string;
+}
+export declare function SaveBar(props: SaveBarProps): import("preact").JSX.Element | null;

package/dist/SaveBar.js ADDED Viewed

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, SAVE_BAR_PARTS, SAVE_BAR_SEP, saveBarClass, saveBarDirty, saveBarNote, } from "@mythicalos/ui-core/logic";
+import { Button } from "./Button.js";
+export { saveBarNote, saveBarDirty, saveBarClass, SAVE_BAR_PARTS, SAVE_BAR_SEP, SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, };
+export function SaveBar(props) {
+    const { changed, saving = false, class: cls = "" } = props;
+    const note = saveBarNote(changed);
+    if (note.count === 0)
+        return null;
+    return (_jsxs("div", { class: `${saveBarClass()} ${cls}`, children: [_jsxs("span", { class: SAVE_BAR_PARTS.note, children: [_jsx("b", { class: SAVE_BAR_PARTS.count, children: note.countLabel }), SAVE_BAR_SEP, note.detail] }), props.children, _jsxs("span", { class: SAVE_BAR_PARTS.actions, children: [_jsx(Button, { variant: "sec", onClick: props.onDiscard, children: props.discardLabel ?? SAVE_BAR_DISCARD_LABEL }), _jsx(Button, { variant: "pri", loading: saving, onClick: props.onSave, children: props.saveLabel ?? SAVE_BAR_SAVE_LABEL })] })] }));
+}

package/dist/SendBar.d.ts ADDED Viewed

@@ -0,0 +1,26 @@
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import { type DeliveryClass } from "@mythicalos/ui-core/logic";
+export { DEFAULT_DELIVERY_CLASS, DELIVERY_CLASSES, DELIVERY_HINT, SEND_DISABLED_FALLBACK, SEND_PLACEHOLDER, canSend, clearDraftOnSend, deliveryClassLabel, keyAction, resolveSend, sendPlaceholder, showDeliveryHint, type DeliveryClass, type KeyAction, } from "@mythicalos/ui-core/logic";
+export interface SendBarProps {
+    /** Initial selection. A manual pick then wins — a later prop change never clobbers it. */
+    defaultClass?: DeliveryClass;
+    /** A send is in flight: the send button is inert but the field stays editable. */
+    busy?: boolean;
+    disabled?: boolean;
+    /** The honest reason the bar is unusable — surfaced as the placeholder. */
+    disabledReason?: string;
+    /** A persistent notice rendered below the bar (e.g. a pending stop). */
+    notice?: string;
+    /** Carried into the enabled placeholder: `Message {name}… (⏎ send · ⇧⏎ newline)`. */
+    targetName?: string;
+    /** Resolve `true` on success; the draft clears only then (text survives failures). */
+    onSend(cls: DeliveryClass, body: string): boolean | Promise<boolean>;
+    /**
+     * Called when `onSend` REJECTS. The rejection is treated as a failed send (nothing delivered, the
+     * draft kept) rather than escaping as an unhandled rejection; this is how a caller still observes
+     * it. Omitting it does not hide a success — only a resolved `true` ever counts as sent.
+     */
+    onSendError?(error: unknown): void;
+}
+export declare function SendBar(props: SendBarProps): JSX.Element;

package/dist/SendBar.js ADDED Viewed

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+// @mythicalos/preact-ui — the delivery send bar (ds/components-terminal, spec v2). Holds the LOCAL
+// draft + class selection and fires `onSend(cls, body)`; the caller owns the delivery call.
+//
+// Thin binding: render + wiring only. The placeholder composition, the send predicate, the
+// draft-clear rule, the keyboard semantics and the hint all come from `@mythicalos/ui-core`.
+//
+// Honesty (binding, inherited from ui-core): the per-class hint is
+// `ASAP takes the first turn gap · ON-DONE waits for full idle.` — the design card's older
+// "ASAP interrupts" wording is FALSE (delivery always waits for a turn boundary) and must never be
+// reintroduced. The hint renders ONLY where the controls are usable; a disabled bar surfaces just
+// the caller's truthful reason.
+//
+// Keyboard: Enter=send, Shift/Alt-Enter=newline, IME composition suppressed (`keyAction`).
+import { useRef, useState } from "preact/hooks";
+import { DEFAULT_DELIVERY_CLASS, DELIVERY_CLASSES, DELIVERY_HINT, SENDBAR_CLASSES, SEND_BUTTON_LABEL, canSend, clearDraftOnSend, deliveryClassButtonClass, deliveryClassLabel, keyAction, makeSendGate, resolveSend, sendBarClass, sendPlaceholder, showDeliveryHint, } from "@mythicalos/ui-core/logic";
+export { DEFAULT_DELIVERY_CLASS, DELIVERY_CLASSES, DELIVERY_HINT, SEND_DISABLED_FALLBACK, SEND_PLACEHOLDER, canSend, clearDraftOnSend, deliveryClassLabel, keyAction, resolveSend, sendPlaceholder, showDeliveryHint, } from "@mythicalos/ui-core/logic";
+export function SendBar(props) {
+    const disabled = !!props.disabled;
+    const busy = !!props.busy;
+    const [cls, setCls] = useState(props.defaultClass ?? DEFAULT_DELIVERY_CLASS);
+    const [text, setText] = useState("");
+    // Single-flight: `busy` covers a caller that tracks the request itself, but `onSend` may be async
+    // and a caller that flips `busy` a tick later (or never) would let two clicks — or a click racing
+    // an Enter — deliver the same message twice. The gate is synchronous, so the second attempt is
+    // refused before any state update lands; `sending` only exists to re-render the disabled button.
+    const gate = useRef(makeSendGate());
+    const [sending, setSending] = useState(false);
+    const locked = busy || sending;
+    const doSend = async () => {
+        if (!canSend(text, disabled, locked))
+            return;
+        if (!gate.current.tryAcquire())
+            return;
+        setSending(true);
+        const submitted = text;
+        try {
+            // a REJECTED onSend resolves to `false` here (a failed send) instead of escaping the handler
+            // as an unhandled rejection; the caller still sees it through `onSendError`
+            const sent = await resolveSend(() => props.onSend(cls, submitted), props.onSendError);
+            // Functional update: compared against the LIVE draft at resolve time, not this closure's
+            // snapshot, so text typed while the request was in flight is never erased.
+            if (sent)
+                setText((current) => (clearDraftOnSend(sent, submitted, current) ? "" : current));
+        }
+        finally {
+            // released on every path, so a failing send can never wedge the bar shut. The draft survives
+            // either way (it clears only on `sent === true`).
+            gate.current.release();
+            setSending(false);
+        }
+    };
+    const onKeyDown = (e) => {
+        if (keyAction(e) === "send") {
+            e.preventDefault();
+            void doSend();
+        }
+        // "newline" / "none": the textarea handles the keystroke natively.
+    };
+    return (_jsxs("div", { class: SENDBAR_CLASSES.wrap, children: [_jsxs("div", { class: sendBarClass(disabled), children: [_jsx("div", { class: SENDBAR_CLASSES.segment, role: "group", children: DELIVERY_CLASSES.map((c) => (_jsx("button", { type: "button", class: deliveryClassButtonClass(cls === c), disabled: disabled, "aria-pressed": cls === c, onClick: () => setCls(c), children: deliveryClassLabel(c) }, c))) }), _jsx("textarea", { class: SENDBAR_CLASSES.input, rows: 1, placeholder: sendPlaceholder(disabled, props.disabledReason, props.targetName), value: text, disabled: disabled, onInput: (e) => setText(e.target.value), onKeyDown: onKeyDown }), _jsx("button", { type: "button", class: SENDBAR_CLASSES.send, disabled: !canSend(text, disabled, locked), onClick: doSend, children: SEND_BUTTON_LABEL })] }), showDeliveryHint(disabled) ? _jsx("div", { class: SENDBAR_CLASSES.hint, children: DELIVERY_HINT }) : null, props.notice ? _jsx("div", { class: SENDBAR_CLASSES.notice, children: props.notice }) : null] }));
+}

package/dist/SessionCard.d.ts ADDED Viewed

@@ -0,0 +1,42 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from "preact";
+import { ctxBand, ctxReading, ctxBarGeom, normalizeCtxThresholds, ctxMeterClass, ctxNoteText, ctxValueText, sessionAvatarInitial, sessionCardClass, sessionCardIsStale, sessionCardStale, sessionSpineSummary, sessionStatus, sessionStatusClass, sessionStatusText, sessionSubline, spineNodeClass, type CtxThresholds, type SessionSpine, type SessionStatusInput } from "@mythicalos/ui-core/logic";
+export { ctxBand, ctxReading, ctxBarGeom, normalizeCtxThresholds, ctxMeterClass, ctxNoteText, ctxValueText, sessionAvatarInitial, sessionCardClass, sessionCardIsStale, sessionCardStale, sessionSpineSummary, sessionStatus, sessionStatusClass, sessionStatusText, sessionSubline, spineNodeClass, };
+export interface SessionCardProps {
+    /** Display name — the card's headline and the source of the avatar initial. */
+    name: string;
+    /**
+     * The meta subline, as a free list joined with ` · `. The design card's own states use it for
+     * `role · model · duration`, `role · model · queued: 1 ON-DONE` and `role · last seen 00:12 ago`
+     * alike. Absent/blank entries collapse; an all-absent list omits the line entirely.
+     */
+    meta?: readonly (string | null | undefined)[];
+    /**
+     * What the product actually knows about the session. Every field is optional and every absent
+     * field means "not reported" — an omitted `activity` never becomes `idle`.
+     */
+    status?: SessionStatusInput;
+    /** The product's own wording for the derived status (e.g. a wake-specific phrase). The tone,
+     *  pulse and stale treatment still come from the derivation — only the words change. A blank
+     *  override, and ANY override on the `unknown` status, is ignored: nothing was claimed, so there
+     *  is nothing to reword (see ui-core's `sessionStatusText`). */
+    statusLabel?: string;
+    /** Context reading, 0–100. `undefined`/`null` ⇒ NOT MEASURED: no fill is drawn and the value
+     *  reads `—`. It is never rendered as 0. */
+    contextPct?: number | null;
+    /** Product-tunable warn/critical thresholds (default 75/90 — tokens.css rule #4). */
+    thresholds?: CtxThresholds;
+    /** Spine strip. An unreported `distills` omits the strip entirely. */
+    spine?: SessionSpine;
+    /** The design's selected state (petrol border + ring). Independent of `stale`. */
+    selected?: boolean;
+    /** ADD the design's stale treatment (dashed border, muted values) for a reason the card cannot
+     *  see. It cannot be used to REMOVE the staleness a down link implies — see `sessionCardStale`. */
+    stale?: boolean;
+    /** Makes the card a real button. Omit for a non-interactive card. */
+    onSelect?: () => void;
+    class?: string;
+    /** Extra content appended inside the card (e.g. a product's own mode glyph). */
+    children?: ComponentChildren;
+}
+export declare function SessionCard(props: SessionCardProps): import("preact").JSX.Element;

package/dist/SessionCard.js ADDED Viewed

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+// @mythicalos/preact-ui — the `session-card` atom (design registry spec v1,
+// mythical-design/ds/components-session-card.html): avatar, name, status dot + words, a meta
+// subline, the context meter with its fixed threshold ticks, and the optional spine strip.
+//
+// Extracted from the only product that implemented it (the Control Room's rail SessionCard + its
+// derive.ts / sessionsVm.ts state-dot derivation) with that product's session view-model lifted
+// out — this component takes plain props, never a `SessionVm`.
+//
+// EVERY branch lives in `@mythicalos/ui-core`'s session-card logic module (band/status/stale/class
+// derivation, subline composition, bar geometry, spine summary); this binding renders what those
+// functions return and nothing else, so it and its React sibling cannot drift. The three honesty
+// invariants (absence is not zero · unknown is not idle · thresholds are product-tunable) are
+// enforced there and documented at the top of that file.
+//
+// The avatar is the packaged <Avatar> atom (composed, not re-rolled). The status dot is NOT
+// <StatusLine>: that atom's tone axis has no `unknown` member and it accepts no `class`, so
+// neither the hollow unknown dot nor the ≤1/s pulse could ride on it without reshaping a sibling
+// atom — same tone vocabulary, own elements (see the stylesheet's note).
+//
+// No inline `style=` anywhere (CSP style-src 'self'): the meter's fill and its 75/90 ticks — which
+// the design prototype positioned with `style="width:62%"` / `style="left:75%"` — are SVG rects
+// carrying presentation attributes, which is also the only form that can express product-tuned
+// thresholds.
+import { Fragment } from "preact";
+import { ctxBand, ctxReading, ctxBarGeom, normalizeCtxThresholds, ctxMeterClass, ctxNoteText, ctxValueText, sessionAvatarInitial, sessionCardClass, sessionCardIsStale, sessionCardStale, sessionSpineSummary, sessionStatus, sessionStatusClass, sessionStatusText, sessionSubline, spineNodeClass, CTX_BAR_VIEWBOX, CTX_THRESHOLDS_DEFAULT, } from "@mythicalos/ui-core/logic";
+import { Avatar } from "./Avatar.js";
+export { ctxBand, ctxReading, ctxBarGeom, normalizeCtxThresholds, ctxMeterClass, ctxNoteText, ctxValueText, sessionAvatarInitial, sessionCardClass, sessionCardIsStale, sessionCardStale, sessionSpineSummary, sessionStatus, sessionStatusClass, sessionStatusText, sessionSubline, spineNodeClass, };
+export function SessionCard(props) {
+    const { name, meta = [], status: statusInput, statusLabel, contextPct, thresholds = CTX_THRESHOLDS_DEFAULT, spine, selected = false, onSelect, class: cls = "", children, } = props;
+    const band = ctxBand(contextPct, thresholds);
+    // the band is part of the status derivation, not a second opinion on it: the design card's
+    // warn/error states replace the status line with the context claim
+    const status = sessionStatus(statusInput, band);
+    const stale = sessionCardStale(status, props.stale);
+    const bar = ctxBarGeom(contextPct, thresholds);
+    const subline = sessionSubline(meta);
+    const spineSummary = sessionSpineSummary(spine);
+    const body = (_jsxs(Fragment, { children: [_jsxs("span", { class: "my-session-card__head", children: [_jsx(Avatar, { initials: sessionAvatarInitial(name), class: "my-session-card__avatar" }), _jsxs("span", { class: "my-session-card__ident", children: [_jsxs("span", { class: "my-session-card__line1", children: [_jsx("b", { class: "my-session-card__name", children: name }), _jsxs("span", { class: sessionStatusClass(status), children: [_jsx("span", { class: "my-session-card__dot" }), _jsx("span", { class: "my-session-card__status-text", children: sessionStatusText(status, statusLabel) })] })] }), subline.length > 0 ? _jsx("span", { class: "my-session-card__meta", children: subline }) : null] })] }), _jsxs("span", { class: ctxMeterClass({ band, stale }), children: [_jsx("span", { class: "my-session-card__ctx-bar", children: _jsxs("svg", { class: "my-session-card__ctx-svg", viewBox: CTX_BAR_VIEWBOX, preserveAspectRatio: "none", "aria-hidden": "true", children: [_jsx("rect", { class: "my-session-card__ctx-track", x: "0", y: "0", width: bar.span, height: bar.height }), bar.fill === undefined ? null : (_jsx("rect", { class: "my-session-card__ctx-fill", x: "0", y: "0", width: bar.fill, height: bar.height })), bar.ticks.map((t) => (_jsx("rect", { class: "my-session-card__ctx-tick", x: t.x, y: "0", width: t.width, height: bar.height }, t.pct)))] }) }), _jsxs("span", { class: "my-session-card__ctx-legend", children: [_jsx("span", { class: "my-session-card__ctx-note", children: ctxNoteText(band, { stale }) }), _jsx("b", { class: "my-session-card__ctx-value", children: ctxValueText(contextPct, thresholds) })] })] }), spineSummary === undefined ? null : (_jsxs(Fragment, { children: [_jsx("span", { class: "my-session-card__spine", "aria-hidden": "true", children: spineSummary.nodes.map((node, i) => (_jsxs(Fragment, { children: [i > 0 ? _jsx("span", { class: "my-session-card__spine-seg" }) : null, _jsx("span", { class: spineNodeClass(node) })] }, i))) }), _jsxs("span", { class: "my-session-card__ctx-legend", children: [_jsx("span", { class: "my-session-card__spine-note", children: spineSummary.label }), _jsx("b", { class: "my-session-card__spine-value", children: spineSummary.value })] })] })), children] }));
+    const classes = sessionCardClass({ selected, stale, extra: cls });
+    return onSelect === undefined ? (_jsx("div", { class: classes, children: body })) : (_jsx("button", { type: "button", class: classes, "aria-pressed": selected, onClick: onSelect, children: body }));
+}

package/dist/StatTiles.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+/** @jsxImportSource preact */
+import { STAT_TILE_EMPTY, STAT_TILE_MINUS, formatStatCompact, formatStatCount, formatStatPercent, formatStatUsd, STAT_TILE_PARTS, statTileClass, statTilesClass, type StatTile, type StatTileTone } from "@mythicalos/ui-core/logic";
+export { formatStatCompact, formatStatCount, formatStatPercent, formatStatUsd, statTileClass, statTilesClass, STAT_TILE_PARTS, STAT_TILE_EMPTY, STAT_TILE_MINUS, type StatTile, type StatTileTone, };
+export interface StatTilesProps {
+    /** The tiles, in display order. A tile with no `sub` renders no sub-caption — the atom never
+     *  invents one (pass `STAT_TILE_EMPTY` if you want the placeholder line). */
+    tiles: readonly StatTile[];
+    class?: string;
+}
+export declare function StatTiles(props: StatTilesProps): import("preact").JSX.Element;

package/dist/StatTiles.js ADDED Viewed

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+/** @jsxImportSource preact */
+// @mythicalos/preact-ui — the stat-tile row (ds/components-stat-tiles.html): a wrapping row of
+// bordered tiles, each an uppercase micro key, a big mono tabular-nums value and a mono
+// sub-caption. `tone: "accent"` is the card's "brag" number; `warn`/`error` are the band tint.
+//
+// Extracted from the reference implementation in the reference product's session detail pane, which
+// hard-coded ITS five session tiles (tokens in/out, prompt cache, cost, spine savings) off a
+// `SessionVm` inside the component. That composition is the product's; this atom takes an
+// already-composed `StatTile[]` so each surface decides its own tiles and order. The value
+// formatters (and the "—" placeholder that must never become a fabricated `0`) live in
+// `@mythicalos/ui-core` and are re-exported here.
+import { STAT_TILE_EMPTY, STAT_TILE_MINUS, formatStatCompact, formatStatCount, formatStatPercent, formatStatUsd, STAT_TILE_PARTS, statTileClass, statTilesClass, } from "@mythicalos/ui-core/logic";
+export { formatStatCompact, formatStatCount, formatStatPercent, formatStatUsd, statTileClass, statTilesClass, STAT_TILE_PARTS, STAT_TILE_EMPTY, STAT_TILE_MINUS, };
+export function StatTiles(props) {
+    const { class: cls = "" } = props;
+    // A JS caller can hand a non-array where the type says `StatTile[]` (an unloaded slot); render an
+    // empty row rather than crashing on `.map` — the same "absent is not a value" rule the
+    // formatters follow.
+    const tiles = Array.isArray(props.tiles) ? props.tiles : [];
+    return (_jsx("div", { class: `${statTilesClass()} ${cls}`, children: tiles.map((t, i) => (_jsxs("div", { class: statTileClass(t.tone), children: [_jsx("div", { class: STAT_TILE_PARTS.label, children: t.label }), _jsx("div", { class: STAT_TILE_PARTS.value, children: t.value }), t.sub !== undefined ? _jsx("div", { class: STAT_TILE_PARTS.sub, children: t.sub }) : null] }, `${i}:${t.label}`))) }));
+}

package/dist/Terminal.d.ts ADDED Viewed

@@ -0,0 +1,31 @@
+/** @jsxImportSource preact */
+import { type TermRow, type TermSource, type TranscriptSegment } from "@mythicalos/ui-core/logic";
+export { TERM_CLASS, TERM_CLASSES, TERM_STALE_COPY, TERM_WAKE_UNAVAILABLE_COPY, transcriptView, type TermRow, type TermRowKind, type TermSource, type TermView, type TranscriptSegment, } from "@mythicalos/ui-core/logic";
+export interface TerminalProps {
+    /** The sole transcript input. All six arms are rendered by ui-core's `transcriptView`. */
+    source: TermSource;
+    /** Title-line text left of ` · tail · noise {on|off}` (e.g. `jacob.jsonl`). */
+    name?: string;
+    /** The noise FILTER: on ⇒ noise rows are HIDDEN and the title reads `noise on`. */
+    noiseFilterEnabled?: boolean;
+    /** Omit for a read-only pane — the title then renders as a caption, not a dead button. */
+    onToggleNoise?(): void;
+    /** Client-synthetic rows appended after the transcript (e.g. an interrupt marker). */
+    localRows?: readonly TermRow[];
+    /** Render only from the last `boundary` row on (the current wake). */
+    currentWakeOnly?: boolean;
+    history?: readonly TranscriptSegment[];
+    /** Shows the `wake unavailable` banner. Independent of the transcript branches. */
+    wakeUnavailable?: boolean;
+    /** The blinking stream caret. */
+    caret?: boolean;
+    /** Supplied truth only — `undefined` renders NO caption rather than guessing. */
+    turnInFlight?: boolean;
+    /** Omit to render no stop control at all. */
+    onStopTurn?(): void;
+    /** A stop is already in flight: the control is disabled and Ctrl-C is ignored. */
+    stopBusy?: boolean;
+    /** VISUAL weight for the stop control only — never a state claim. */
+    stopProminent?: boolean;
+}
+export declare function Terminal(props: TerminalProps): import("preact").JSX.Element;