@timurproko/a1 0.1.0 → 0.1.1-dev.10

package/dist/src/foundation/ui-components/mouse.js

@@ -0,0 +1,46 @@
+/**
+ * SGR mouse reporting. A screen that wants hover, click, and drag needs the
+ * terminal to send reports; nothing else in A1 turns this on, and the sequences
+ * are paired so the terminal is always left as it was found.
+ */
+export const MOUSE_TRACKING_ON = "\u001b[?1006h\u001b[?1000h\u001b[?1003h";
+export const MOUSE_TRACKING_OFF = "\u001b[?1003l\u001b[?1000l\u001b[?1006l";
+const SGR_PATTERN = /\u001b\[<(\d+);(\d+);(\d+)([Mm])/g;
+/** Extracts SGR mouse reports, leaving any keyboard input untouched. */
+export function parseMouseInput(data) {
+    if (!data.includes("\u001b[<"))
+        return { events: [], rest: data };
+    const events = [];
+    let rest = "";
+    let index = 0;
+    SGR_PATTERN.lastIndex = 0;
+    for (let match = SGR_PATTERN.exec(data); match !== null; match = SGR_PATTERN.exec(data)) {
+        rest += data.slice(index, match.index);
+        index = match.index + match[0].length;
+        const code = Number.parseInt(match[1] ?? "", 10);
+        const column = Number.parseInt(match[2] ?? "", 10);
+        const row = Number.parseInt(match[3] ?? "", 10);
+        const released = match[4] === "m";
+        if (!Number.isInteger(code) || !Number.isInteger(column) || !Number.isInteger(row))
+            continue;
+        const event = toEvent(code, column, row, released);
+        if (event !== null)
+            events.push(event);
+    }
+    rest += data.slice(index);
+    return { events: Object.freeze(events), rest };
+}
+function toEvent(code, column, row, released) {
+    if ((code & 64) !== 0) {
+        const kind = (code & 1) === 0 ? "wheel-up" : "wheel-down";
+        return { kind, button: 0, column, row };
+    }
+    const button = code & 3;
+    if ((code & 32) !== 0)
+        return { kind: "motion", button, column, row };
+    if (released)
+        return { kind: "release", button, column, row };
+    if (button === 3)
+        return { kind: "release", button: 0, column, row };
+    return { kind: "press", button, column, row };
+}

package/dist/src/foundation/ui-components/pane.d.ts

@@ -0,0 +1,33 @@
+import type { PaneRect } from "./frame.js";
+import type { RenderCacheContract } from "./revision.js";
+export interface PaneMouseEvent {
+    readonly kind: "press" | "release" | "motion" | "wheel-up" | "wheel-down";
+    /** 0 left, 1 middle, 2 right. Meaningless for wheel events. */
+    readonly button: number;
+    /** One-based column within the pane. */
+    readonly column: number;
+    /** One-based row within the pane. */
+    readonly row: number;
+}
+export interface PaneInputResult {
+    /** True when the pane handled the event; an unconsumed event continues to the host. */
+    readonly consumed: boolean;
+    /** True when the pane's appearance changed and the host should repaint. */
+    readonly render?: boolean;
+}
+export interface Pane {
+    /** Renders exactly `rect.height` rows, each at most `rect.width` columns. */
+    render(rect: PaneRect, focused: boolean): readonly string[];
+    onInput?(data: string): PaneInputResult;
+    /** Mouse events arrive in coordinates local to this pane's own origin. */
+    onMouse?(event: PaneMouseEvent): PaneInputResult;
+    /** Drops cached layout after its data changed underneath it. */
+    invalidate?(): void;
+    readonly renderCache?: RenderCacheContract;
+}
+/** Translates a host-level mouse event into one pane's local coordinates. */
+export declare function toPaneLocalMouse(event: PaneMouseEvent, origin: {
+    readonly column: number;
+    readonly row: number;
+}): PaneMouseEvent;
+export declare function isInsidePane(event: PaneMouseEvent, rect: PaneRect): boolean;

package/dist/src/foundation/ui-components/pane.js

@@ -0,0 +1,7 @@
+/** Translates a host-level mouse event into one pane's local coordinates. */
+export function toPaneLocalMouse(event, origin) {
+    return { ...event, column: event.column - origin.column + 1, row: event.row - origin.row + 1 };
+}
+export function isInsidePane(event, rect) {
+    return event.column >= 1 && event.column <= rect.width && event.row >= 1 && event.row <= rect.height;
+}

package/dist/src/foundation/ui-components/revision.d.ts

@@ -0,0 +1,35 @@
+import type { PaneRect } from "./frame.js";
+export type RenderRevisionKind = "content" | "selection" | "hover" | "layout" | "theme";
+export declare const RENDER_REVISION_KINDS: readonly RenderRevisionKind[];
+export type RenderRevisions = Readonly<Record<RenderRevisionKind, number>>;
+export declare const ZERO_REVISIONS: RenderRevisions;
+/**
+ * A component declares what changed. A host reuses a cached frame only while
+ * every declared revision and the rectangle are unchanged; a component that
+ * declares nothing is always stale rather than cached incorrectly.
+ */
+export interface RenderCacheContract {
+    revisions(): Partial<RenderRevisions>;
+}
+export declare function normalizeRevisions(revisions: Partial<RenderRevisions> | undefined): RenderRevisions;
+export declare function revisionsEqual(left: RenderRevisions, right: RenderRevisions): boolean;
+/** Bumps revisions by kind so a component can declare what it invalidated. */
+export declare class RenderRevisionTracker {
+    #private;
+    bump(kind: RenderRevisionKind): void;
+    bumpAll(): void;
+    revisions(): RenderRevisions;
+}
+/**
+ * Caches one component's frame. A component with no cache contract is rendered
+ * every time, so adoption is incremental rather than all-or-nothing.
+ */
+export declare class FrameCache {
+    #private;
+    get hits(): number;
+    get misses(): number;
+    render(component: {
+        readonly renderCache?: RenderCacheContract;
+    }, rect: PaneRect, render: () => readonly string[]): readonly string[];
+    invalidate(): void;
+}

package/dist/src/foundation/ui-components/revision.js

@@ -0,0 +1,79 @@
+export const RENDER_REVISION_KINDS = Object.freeze([
+    "content",
+    "selection",
+    "hover",
+    "layout",
+    "theme",
+]);
+export const ZERO_REVISIONS = Object.freeze({
+    content: 0,
+    selection: 0,
+    hover: 0,
+    layout: 0,
+    theme: 0,
+});
+export function normalizeRevisions(revisions) {
+    if (revisions === undefined)
+        return ZERO_REVISIONS;
+    const normalized = { ...ZERO_REVISIONS };
+    for (const kind of RENDER_REVISION_KINDS) {
+        const value = revisions[kind];
+        normalized[kind] = typeof value === "number" && Number.isFinite(value) ? value : 0;
+    }
+    return Object.freeze(normalized);
+}
+export function revisionsEqual(left, right) {
+    return RENDER_REVISION_KINDS.every(kind => left[kind] === right[kind]);
+}
+/** Bumps revisions by kind so a component can declare what it invalidated. */
+export class RenderRevisionTracker {
+    #revisions = { ...ZERO_REVISIONS };
+    bump(kind) {
+        this.#revisions[kind] += 1;
+    }
+    bumpAll() {
+        for (const kind of RENDER_REVISION_KINDS)
+            this.#revisions[kind] += 1;
+    }
+    revisions() {
+        return Object.freeze({ ...this.#revisions });
+    }
+}
+/**
+ * Caches one component's frame. A component with no cache contract is rendered
+ * every time, so adoption is incremental rather than all-or-nothing.
+ */
+export class FrameCache {
+    #cached;
+    #hits = 0;
+    #misses = 0;
+    get hits() {
+        return this.#hits;
+    }
+    get misses() {
+        return this.#misses;
+    }
+    render(component, rect, render) {
+        if (component.renderCache === undefined) {
+            this.#misses += 1;
+            this.#cached = undefined;
+            return render();
+        }
+        const revisions = normalizeRevisions(component.renderCache.revisions());
+        const cached = this.#cached;
+        if (cached
+            && cached.rect.width === rect.width
+            && cached.rect.height === rect.height
+            && revisionsEqual(cached.revisions, revisions)) {
+            this.#hits += 1;
+            return cached.lines;
+        }
+        this.#misses += 1;
+        const lines = render();
+        this.#cached = { rect: { width: rect.width, height: rect.height }, revisions, lines };
+        return lines;
+    }
+    invalidate() {
+        this.#cached = undefined;
+    }
+}

package/dist/src/foundation/ui-components/scrollbar.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One scrollbar for every scrollable surface. Hover and drag belong to a named
+ * rail rather than to a global, because two scrollable surfaces can be visible
+ * at once and a shared flag lights up the wrong one.
+ */
+export interface ScrollbarGeometry {
+    /** Rows in the track. */
+    readonly trackHeight: number;
+    /** Thumb height in rows, at least one. */
+    readonly thumbHeight: number;
+    /** Zero-based row of the thumb's top within the track. */
+    readonly thumbTop: number;
+    /** Highest scroll position the content allows. */
+    readonly maxScroll: number;
+}
+export interface ScrollbarInput {
+    readonly contentLength: number;
+    readonly viewportHeight: number;
+    readonly scroll: number;
+    readonly trackHeight: number;
+}
+/** Null when the content fits: no scrollbar is drawn and no width is reserved. */
+export declare function scrollbarGeometry(input: ScrollbarInput): ScrollbarGeometry | null;
+export declare function scrollbarReservesSpace(geometry: ScrollbarGeometry | null): boolean;
+/** True when this track row is part of the thumb. */
+export declare function isThumbRow(geometry: ScrollbarGeometry | null, trackRow: number): boolean;
+/** Scroll position for a thumb dragged to a track row. */
+export declare function scrollForThumbRow(geometry: ScrollbarGeometry | null, trackRow: number): number;
+/** Scroll position after paging on the track above or below the thumb. */
+export declare function scrollForTrackPage(geometry: ScrollbarGeometry | null, trackRow: number, scroll: number, viewportHeight: number): number;
+export interface RailPosition {
+    /** Identity of this rail. Two surfaces never share one. */
+    readonly key: string;
+    /** Column the rail is drawn in, one-based. */
+    readonly column: number;
+    /** First row of the track within the surface, zero-based. */
+    readonly rowStart: number;
+    readonly trackHeight: number;
+}
+export interface RailPointer {
+    readonly column: number;
+    readonly row: number;
+}
+/**
+ * Hover and drag state for every rail on screen. State is keyed by rail, so a
+ * pointer over one rail cannot make another appear hot, and a drag started on
+ * one rail cannot be continued by a report addressed to another.
+ */
+export declare class ScrollbarRails {
+    #private;
+    isHovered(key: string): boolean;
+    isDragging(key: string): boolean;
+    get draggingKey(): string | null;
+    /** Records the pointer position. Returns the rail it is over, if any. */
+    notePointer(rails: readonly RailPosition[], pointer: RailPointer): string | null;
+    /** Starts a drag when the pointer is on that rail's thumb. */
+    beginDrag(rail: RailPosition, geometry: ScrollbarGeometry | null, pointer: RailPointer): boolean;
+    /** Scroll position for a drag in progress, or null when this rail is not being dragged. */
+    dragTo(rail: RailPosition, geometry: ScrollbarGeometry | null, pointer: RailPointer): number | null;
+    endDrag(): void;
+    clear(): void;
+}

package/dist/src/foundation/ui-components/scrollbar.js

@@ -0,0 +1,102 @@
+/**
+ * One scrollbar for every scrollable surface. Hover and drag belong to a named
+ * rail rather than to a global, because two scrollable surfaces can be visible
+ * at once and a shared flag lights up the wrong one.
+ */
+/** Null when the content fits: no scrollbar is drawn and no width is reserved. */
+export function scrollbarGeometry(input) {
+    const { contentLength, viewportHeight, trackHeight } = input;
+    if (trackHeight <= 0 || viewportHeight <= 0)
+        return null;
+    if (contentLength <= viewportHeight)
+        return null;
+    const maxScroll = contentLength - viewportHeight;
+    const scroll = Math.min(Math.max(input.scroll, 0), maxScroll);
+    const thumbHeight = Math.max(1, Math.min(trackHeight, Math.round(trackHeight * viewportHeight / contentLength)));
+    const travel = trackHeight - thumbHeight;
+    const thumbTop = maxScroll === 0 ? 0 : Math.min(travel, Math.round(travel * scroll / maxScroll));
+    return { trackHeight, thumbHeight, thumbTop, maxScroll };
+}
+export function scrollbarReservesSpace(geometry) {
+    return geometry !== null;
+}
+/** True when this track row is part of the thumb. */
+export function isThumbRow(geometry, trackRow) {
+    if (geometry === null)
+        return false;
+    return trackRow >= geometry.thumbTop && trackRow < geometry.thumbTop + geometry.thumbHeight;
+}
+/** Scroll position for a thumb dragged to a track row. */
+export function scrollForThumbRow(geometry, trackRow) {
+    if (geometry === null)
+        return 0;
+    const travel = geometry.trackHeight - geometry.thumbHeight;
+    if (travel <= 0)
+        return 0;
+    const clamped = Math.min(Math.max(trackRow, 0), travel);
+    return Math.round(clamped * geometry.maxScroll / travel);
+}
+/** Scroll position after paging on the track above or below the thumb. */
+export function scrollForTrackPage(geometry, trackRow, scroll, viewportHeight) {
+    if (geometry === null)
+        return scroll;
+    const page = Math.max(1, viewportHeight);
+    const next = trackRow < geometry.thumbTop ? scroll - page : scroll + page;
+    return Math.min(Math.max(next, 0), geometry.maxScroll);
+}
+/**
+ * Hover and drag state for every rail on screen. State is keyed by rail, so a
+ * pointer over one rail cannot make another appear hot, and a drag started on
+ * one rail cannot be continued by a report addressed to another.
+ */
+export class ScrollbarRails {
+    #hovered = new Set();
+    #dragging;
+    isHovered(key) {
+        return this.#hovered.has(key);
+    }
+    isDragging(key) {
+        return this.#dragging?.key === key;
+    }
+    get draggingKey() {
+        return this.#dragging?.key ?? null;
+    }
+    /** Records the pointer position. Returns the rail it is over, if any. */
+    notePointer(rails, pointer) {
+        this.#hovered.clear();
+        for (const rail of rails) {
+            if (pointer.column !== rail.column)
+                continue;
+            const trackRow = pointer.row - rail.rowStart;
+            if (trackRow < 0 || trackRow >= rail.trackHeight)
+                continue;
+            this.#hovered.add(rail.key);
+            return rail.key;
+        }
+        return null;
+    }
+    /** Starts a drag when the pointer is on that rail's thumb. */
+    beginDrag(rail, geometry, pointer) {
+        if (geometry === null || pointer.column !== rail.column)
+            return false;
+        const trackRow = pointer.row - rail.rowStart;
+        if (!isThumbRow(geometry, trackRow))
+            return false;
+        this.#dragging = { key: rail.key, grabOffset: trackRow - geometry.thumbTop };
+        return true;
+    }
+    /** Scroll position for a drag in progress, or null when this rail is not being dragged. */
+    dragTo(rail, geometry, pointer) {
+        const dragging = this.#dragging;
+        if (dragging === undefined || dragging.key !== rail.key || geometry === null)
+            return null;
+        return scrollForThumbRow(geometry, pointer.row - rail.rowStart - dragging.grabOffset);
+    }
+    endDrag() {
+        this.#dragging = undefined;
+    }
+    clear() {
+        this.#hovered.clear();
+        this.#dragging = undefined;
+    }
+}

package/dist/src/foundation/ui-components/shortcuts.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shortcuts as declared data. Dispatch resolves a key through declarations
+ * rather than inline comparisons, conflicts are reported when the registry is
+ * assembled, and any listing is generated from the same declarations — so a
+ * listed shortcut is one dispatch would actually invoke.
+ */
+export interface ShortcutDeclaration {
+    /** Key token, for example `up`, `shift+down`, `ctrl+c`, or a literal character. */
+    readonly key: string;
+    /** Screen this applies to, or `global` for every screen. */
+    readonly scope: string;
+    readonly description: string;
+    /** Grouping label for the listing. */
+    readonly section?: string;
+    /**
+     * How this key reads on a screen's hint line, when it belongs there. Keys that
+     * do one thing together — the two arrows, enter and space — declare the same
+     * pair and are shown once.
+     */
+    readonly hint?: {
+        readonly keys: string;
+        readonly does: string;
+    };
+}
+export declare const GLOBAL_SCOPE = "global";
+export interface ShortcutConflict {
+    readonly key: string;
+    readonly scopes: readonly [string, string];
+    readonly descriptions: readonly [string, string];
+    readonly kind: "duplicate" | "shadowed";
+}
+export interface ShortcutRegistryResult {
+    readonly declarations: readonly ShortcutDeclaration[];
+    readonly conflicts: readonly ShortcutConflict[];
+}
+/**
+ * Assembles declarations and reports every key claimed twice in overlapping
+ * scopes. A screen claiming a global key is reported as shadowed rather than
+ * silently resolved by declaration order.
+ */
+export declare function assembleShortcuts(declarations: readonly ShortcutDeclaration[]): ShortcutRegistryResult;
+export declare function assertNoShortcutConflicts(result: ShortcutRegistryResult): void;
+export declare class ShortcutRegistry<Action extends string = string> {
+    #private;
+    declare(declaration: ShortcutDeclaration, action: Action): void;
+    /** The action this key invokes in this scope, preferring a screen over a global. */
+    resolve(key: string, scope: string): Action | null;
+    assemble(): ShortcutRegistryResult;
+    /**
+     * The hint line, in the order the screen declares its keys. It is rendered from
+     * the same declarations dispatch reads, so a key cannot be described here and
+     * bound to something else, or bound and never mentioned.
+     */
+    hint(scope: string, separator?: string): string;
+    /** The listing, derived from the declarations dispatch reads. */
+    list(scope?: string): readonly ShortcutDeclaration[];
+}

package/dist/src/foundation/ui-components/shortcuts.js

@@ -0,0 +1,81 @@
+/**
+ * Shortcuts as declared data. Dispatch resolves a key through declarations
+ * rather than inline comparisons, conflicts are reported when the registry is
+ * assembled, and any listing is generated from the same declarations — so a
+ * listed shortcut is one dispatch would actually invoke.
+ */
+export const GLOBAL_SCOPE = "global";
+function overlaps(left, right) {
+    return left === right || left === GLOBAL_SCOPE || right === GLOBAL_SCOPE;
+}
+/**
+ * Assembles declarations and reports every key claimed twice in overlapping
+ * scopes. A screen claiming a global key is reported as shadowed rather than
+ * silently resolved by declaration order.
+ */
+export function assembleShortcuts(declarations) {
+    const conflicts = [];
+    for (let left = 0; left < declarations.length; left++) {
+        for (let right = left + 1; right < declarations.length; right++) {
+            const a = declarations[left];
+            const b = declarations[right];
+            if (a === undefined || b === undefined)
+                continue;
+            if (a.key !== b.key || !overlaps(a.scope, b.scope))
+                continue;
+            conflicts.push({
+                key: a.key,
+                scopes: [a.scope, b.scope],
+                descriptions: [a.description, b.description],
+                kind: a.scope === b.scope ? "duplicate" : "shadowed",
+            });
+        }
+    }
+    return { declarations: Object.freeze([...declarations]), conflicts: Object.freeze(conflicts) };
+}
+export function assertNoShortcutConflicts(result) {
+    const duplicate = result.conflicts.find(conflict => conflict.kind === "duplicate");
+    if (duplicate) {
+        throw new Error(`shortcut ${duplicate.key} is declared twice in scope ${duplicate.scopes[0]}: `
+            + `"${duplicate.descriptions[0]}" and "${duplicate.descriptions[1]}"`);
+    }
+}
+export class ShortcutRegistry {
+    #declarations = [];
+    #actions = new Map();
+    declare(declaration, action) {
+        this.#declarations.push(declaration);
+        this.#actions.set(`${declaration.scope}\u0000${declaration.key}`, action);
+    }
+    /** The action this key invokes in this scope, preferring a screen over a global. */
+    resolve(key, scope) {
+        return this.#actions.get(`${scope}\u0000${key}`) ?? this.#actions.get(`${GLOBAL_SCOPE}\u0000${key}`) ?? null;
+    }
+    assemble() {
+        return assembleShortcuts(this.#declarations);
+    }
+    /**
+     * The hint line, in the order the screen declares its keys. It is rendered from
+     * the same declarations dispatch reads, so a key cannot be described here and
+     * bound to something else, or bound and never mentioned.
+     */
+    hint(scope, separator = " · ") {
+        const shown = new Map();
+        for (const declaration of this.#declarations) {
+            if (declaration.hint === undefined)
+                continue;
+            if (declaration.scope !== scope && declaration.scope !== GLOBAL_SCOPE)
+                continue;
+            if (!shown.has(declaration.hint.keys))
+                shown.set(declaration.hint.keys, declaration.hint.does);
+        }
+        return [...shown].map(([keys, does]) => `${keys} ${does}`).join(separator);
+    }
+    /** The listing, derived from the declarations dispatch reads. */
+    list(scope) {
+        const inScope = scope === undefined
+            ? this.#declarations
+            : this.#declarations.filter(declaration => declaration.scope === scope || declaration.scope === GLOBAL_SCOPE);
+        return Object.freeze([...inScope].sort((left, right) => (left.section ?? "").localeCompare(right.section ?? "") || left.key.localeCompare(right.key)));
+    }
+}

package/dist/src/foundation/ui-components/spans.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Replaces the visible columns `[from, to)` of `line` with `span`, preserving
+ * the styling before it and re-asserting whatever was still open afterwards, so
+ * the tail keeps the colour it had. A wide character straddling either edge is
+ * replaced by spaces rather than split.
+ */
+export declare function overlaySpan(line: string, from: number, to: number, span: string): string;

package/dist/src/foundation/ui-components/spans.js

@@ -0,0 +1,59 @@
+import { displayWidth } from "./text.js";
+/**
+ * Ported from the A1 UI reference implementation (`core/presentation/spans.ts`).
+ * Writing over part of a rendered row is not string slicing: the row carries
+ * styling and hyperlink sequences, and cutting through them either loses the
+ * styling of the tail or leaks the span's own reset into it.
+ */
+const ANSI_SEQUENCE = "\\u001b(?:\\[[0-?]*[ -/]*[@-~]|[\\]_][^\\u0007\\u001b]*(?:\\u0007|\\u001b\\\\|$))";
+const ANSI_SPLIT = new RegExp(`(${ANSI_SEQUENCE})`);
+const HYPERLINK = /^\]8;;([^]*)(?:|\\)?$/;
+const HYPERLINK_OFF = "]8;;\\";
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/**
+ * Replaces the visible columns `[from, to)` of `line` with `span`, preserving
+ * the styling before it and re-asserting whatever was still open afterwards, so
+ * the tail keeps the colour it had. A wide character straddling either edge is
+ * replaced by spaces rather than split.
+ */
+export function overlaySpan(line, from, to, span) {
+    let head = "";
+    let replay = "";
+    let tail = "";
+    let column = 0;
+    let hyperlinkOpen = false;
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        if (token.startsWith("")) {
+            if (column >= to) {
+                tail += token;
+                continue;
+            }
+            if (column < from) {
+                head += token;
+                const link = HYPERLINK.exec(token);
+                if (link)
+                    hyperlinkOpen = (link[1] ?? "").length > 0;
+            }
+            // Re-assert everything still active: the span's own reset clobbers the tail.
+            replay += token;
+            continue;
+        }
+        for (const { segment } of GRAPHEMES.segment(token)) {
+            const width = displayWidth(segment);
+            if (column + width <= from)
+                head += segment;
+            else if (column >= to)
+                tail += segment;
+            else if (column < from)
+                head += " ".repeat(from - column);
+            else if (column + width > to)
+                tail += " ".repeat(column + width - to);
+            column += width;
+        }
+    }
+    if (column < from)
+        head += " ".repeat(from - column);
+    return head + (hyperlinkOpen ? HYPERLINK_OFF : "") + span + replay + tail;
+}

package/dist/src/foundation/ui-components/status-line.d.ts

@@ -0,0 +1,16 @@
+import type { UiTheme } from "./theme.js";
+/**
+ * The one line a screen speaks on. It says the standing hint until there is
+ * something to report, and what is reported stands until it is superseded — one
+ * thing at a time, so a reader never has to work out which of two lines is now.
+ */
+export interface StatusLineInput {
+    /** What the screen always offers: its keys, usually. */
+    readonly hint: string;
+    /** Something that happened and would not otherwise be known. */
+    readonly report?: string | null;
+}
+/** What the line says: the report when there is one, else the hint. */
+export declare function statusText(input: StatusLineInput): string;
+/** The line as drawn: quiet, and set against the right edge. */
+export declare function renderStatusLine(input: StatusLineInput, width: number, theme: UiTheme): string;

package/dist/src/foundation/ui-components/status-line.js

@@ -0,0 +1,14 @@
+import { displayWidth, truncateToWidth } from "./text.js";
+/** What the line says: the report when there is one, else the hint. */
+export function statusText(input) {
+    const report = input.report ?? null;
+    return report === null || report.length === 0 ? input.hint : report;
+}
+/** The line as drawn: quiet, and set against the right edge. */
+export function renderStatusLine(input, width, theme) {
+    const text = statusText(input);
+    const painted = theme.fg("dim", text);
+    if (displayWidth(text) >= width)
+        return truncateToWidth(painted, width);
+    return `${" ".repeat(width - displayWidth(text))}${painted}`;
+}

package/dist/src/foundation/ui-components/stepper.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A value stepped through a range or through the numbers it is offered. The two
+ * are the same control: a list of numbers is a range whose entries are its ends.
+ */
+export interface NumericRange {
+    /** Smallest value accepted, or null when nothing states one. */
+    readonly minimum: number | null;
+    /** Largest value accepted, or null when nothing states one. */
+    readonly maximum: number | null;
+    /** The numbers offered, when the offer is the whole domain rather than shortcuts. */
+    readonly values: readonly number[] | null;
+}
+/** The numbers a list of choices offers, or null when it is not all numbers. */
+export declare function numericValues(choices: readonly unknown[] | null): readonly number[] | null;
+/**
+ * Where a step lands, or null when there is nowhere further to go. At an end the
+ * caller draws the control as unavailable rather than reporting a refusal.
+ */
+export declare function steppedValue(range: NumericRange, from: number, delta: -1 | 1): number | null;
+/** Which ends of the range a value can still move towards. */
+export declare function stepperEnds(range: NumericRange, from: number): {
+    readonly lower: boolean;
+    readonly raise: boolean;
+};

package/dist/src/foundation/ui-components/stepper.js

@@ -0,0 +1,33 @@
+/**
+ * A value stepped through a range or through the numbers it is offered. The two
+ * are the same control: a list of numbers is a range whose entries are its ends.
+ */
+/** The numbers a list of choices offers, or null when it is not all numbers. */
+export function numericValues(choices) {
+    if (choices === null || choices.length === 0)
+        return null;
+    const numbers = choices.filter((choice) => typeof choice === "number");
+    return numbers.length === choices.length ? [...numbers].sort((left, right) => left - right) : null;
+}
+/**
+ * Where a step lands, or null when there is nowhere further to go. At an end the
+ * caller draws the control as unavailable rather than reporting a refusal.
+ */
+export function steppedValue(range, from, delta) {
+    if (range.values !== null) {
+        const at = range.values.indexOf(from);
+        const next = (at < 0 ? 0 : at) + delta;
+        return next >= 0 && next < range.values.length ? range.values[next] ?? null : null;
+    }
+    const next = from + delta;
+    if (range.minimum !== null && next < range.minimum)
+        return null;
+    return range.maximum !== null && next > range.maximum ? null : next;
+}
+/** Which ends of the range a value can still move towards. */
+export function stepperEnds(range, from) {
+    return {
+        lower: steppedValue(range, from, -1) !== null,
+        raise: steppedValue(range, from, 1) !== null,
+    };
+}