@timurproko/a1 0.1.1-dev.5 → 0.1.1-dev.7

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

@@ -0,0 +1,245 @@
+import { displayWidth, faint, truncateToWidth } from "./text.js";
+const MAX_VALUE_LENGTH = 4_096;
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** Character class for a word boundary: 0 space, 1 word, 2 anything else. */
+function charClass(character) {
+    if (/\s/.test(character))
+        return 0;
+    if (/[\p{L}\p{N}_]/u.test(character))
+        return 1;
+    return 2;
+}
+/**
+ * Where a word jump to the left lands: past any whitespace, then past the run of
+ * characters of one class, so a word and a run of punctuation each count as one.
+ */
+export function wordLeft(text, from) {
+    const graphemes = [...GRAPHEMES.segment(text.slice(0, from))].map(entry => entry.segment);
+    let at = from;
+    let index = graphemes.length - 1;
+    while (index >= 0 && charClass(graphemes[index] ?? "") === 0)
+        at -= (graphemes[index--] ?? "").length;
+    if (index >= 0) {
+        const cls = charClass(graphemes[index] ?? "");
+        while (index >= 0 && charClass(graphemes[index] ?? "") === cls)
+            at -= (graphemes[index--] ?? "").length;
+    }
+    return at;
+}
+/** Where a word jump to the right lands, by the same rules mirrored. */
+export function wordRight(text, from) {
+    const graphemes = [...GRAPHEMES.segment(text.slice(from))].map(entry => entry.segment);
+    let at = from;
+    let index = 0;
+    while (index < graphemes.length && charClass(graphemes[index] ?? "") === 0)
+        at += (graphemes[index++] ?? "").length;
+    if (index < graphemes.length) {
+        const cls = charClass(graphemes[index] ?? "");
+        while (index < graphemes.length && charClass(graphemes[index] ?? "") === cls)
+            at += (graphemes[index++] ?? "").length;
+    }
+    return at;
+}
+/**
+ * A single-line editable value with a caret and horizontal scrolling. Accept and
+ * cancel are reported distinctly so a caller can commit or discard; cancelling
+ * never changes the caller's value.
+ */
+export class LineInput {
+    #value;
+    #caret;
+    #offset = 0;
+    constructor(value = "") {
+        this.#value = value.slice(0, MAX_VALUE_LENGTH);
+        this.#caret = this.#value.length;
+    }
+    get value() {
+        return this.#value;
+    }
+    get caret() {
+        return this.#caret;
+    }
+    setValue(value) {
+        this.#value = value.slice(0, MAX_VALUE_LENGTH);
+        this.#caret = Math.min(this.#caret, this.#value.length);
+        this.#offset = 0;
+    }
+    insert(text) {
+        const printable = [...text].filter(character => {
+            const code = character.codePointAt(0) ?? 0;
+            return code >= 0x20 && code !== 0x7f;
+        }).join("");
+        if (printable.length === 0)
+            return;
+        const next = this.#value.slice(0, this.#caret) + printable + this.#value.slice(this.#caret);
+        if (next.length > MAX_VALUE_LENGTH)
+            return;
+        this.#value = next;
+        this.#caret += printable.length;
+    }
+    backspace() {
+        if (this.#caret === 0)
+            return;
+        this.#value = this.#value.slice(0, this.#caret - 1) + this.#value.slice(this.#caret);
+        this.#caret -= 1;
+    }
+    deleteForward() {
+        if (this.#caret >= this.#value.length)
+            return;
+        this.#value = this.#value.slice(0, this.#caret) + this.#value.slice(this.#caret + 1);
+    }
+    moveCaret(delta) {
+        this.#caret = Math.min(Math.max(this.#caret + delta, 0), this.#value.length);
+    }
+    /** Moves the caret one word, in whichever direction the sign says. */
+    moveCaretByWord(direction) {
+        this.#caret = direction < 0 ? wordLeft(this.#value, this.#caret) : wordRight(this.#value, this.#caret);
+    }
+    /** Removes the word before the caret, leaving the caret where it began. */
+    deleteWordBefore() {
+        const to = wordLeft(this.#value, this.#caret);
+        if (to >= this.#caret)
+            return;
+        this.#value = this.#value.slice(0, to) + this.#value.slice(this.#caret);
+        this.#caret = to;
+    }
+    /** Removes the word after the caret, leaving the caret where it is. */
+    deleteWordAfter() {
+        const to = wordRight(this.#value, this.#caret);
+        if (to <= this.#caret)
+            return;
+        this.#value = this.#value.slice(0, this.#caret) + this.#value.slice(to);
+    }
+    moveCaretToStart() {
+        this.#caret = 0;
+    }
+    moveCaretToEnd() {
+        this.#caret = this.#value.length;
+    }
+    /** Visible slice for a width, scrolled so the caret stays on screen. */
+    view(width) {
+        if (width <= 0)
+            return { text: "", caretColumn: 0 };
+        const before = this.#value.slice(0, this.#caret);
+        const caretWidth = displayWidth(before);
+        if (caretWidth < this.#offset)
+            this.#offset = caretWidth;
+        if (caretWidth >= this.#offset + width)
+            this.#offset = caretWidth - width + 1;
+        if (this.#offset < 0)
+            this.#offset = 0;
+        let start = 0;
+        let consumed = 0;
+        for (const character of this.#value) {
+            if (consumed >= this.#offset)
+                break;
+            consumed += displayWidth(character);
+            start += character.length;
+        }
+        return {
+            text: truncateToWidth(this.#value.slice(start), width),
+            caretColumn: Math.max(0, Math.min(width, caretWidth - this.#offset)),
+        };
+    }
+}
+/** Applies one key to the input and reports whether the caller should commit. */
+export function handleLineInputKey(input, data) {
+    if (data === "\r" || data === "\n")
+        return { kind: "accepted", value: input.value };
+    if (data === "\u001b" || data === "\u0003")
+        return { kind: "cancelled" };
+    // A word delete is decided before a plain one: on Windows Terminal the raw
+    // backspace byte IS ctrl+backspace, and the plain branch would swallow it.
+    if (data === "\b" || data === "\u001b\u007f" || data === "\u0017") {
+        input.deleteWordBefore();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[3;5~" || data === "\u001b[3;3~" || data === "\u001bd") {
+        input.deleteWordAfter();
+        return { kind: "editing" };
+    }
+    if (data === "\u007f") {
+        input.backspace();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[3~") {
+        input.deleteForward();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[1;5D" || data === "\u001b[1;3D" || data === "\u001bb") {
+        input.moveCaretByWord(-1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[1;5C" || data === "\u001b[1;3C" || data === "\u001bf") {
+        input.moveCaretByWord(1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[D") {
+        input.moveCaret(-1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[C") {
+        input.moveCaret(1);
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[H" || data === "\u0001") {
+        input.moveCaretToStart();
+        return { kind: "editing" };
+    }
+    if (data === "\u001b[F" || data === "\u0005") {
+        input.moveCaretToEnd();
+        return { kind: "editing" };
+    }
+    // Any other escape sequence is a key this input has no answer for - a page
+    // key, a function key, a chord. It is swallowed rather than typed, because the
+    // one thing it certainly is not is text the reader meant to enter.
+    if (data.startsWith("\u001b"))
+        return { kind: "editing" };
+    input.insert(data);
+    return { kind: "editing" };
+}
+/**
+ * The prompt the reference draws at the head of an input row, in the grey it
+ * uses for one (#9AA0A6), painted foreground-only so anything drawn behind the
+ * row survives.
+ */
+/** A rule drawn in the prompt's own grey, as the reference rules an input row. */
+export function promptRule(width) {
+    return `\u001b[38;2;154;160;166m${"─".repeat(Math.max(0, width))}\u001b[39m`;
+}
+export const PROMPT_GLYPH = `\u001b[38;2;154;160;166m❯\u001b[39m `;
+/**
+ * The caret the reference draws: the cell under it is reversed rather than given
+ * a colour of its own, so it reads as a block in whatever theme is in use.
+ */
+export function caretCell(text) {
+    return `\u001b[7m${text}\u001b[27m`;
+}
+/** The input row as the reference draws one, padded to exactly the width. */
+export function renderInputRow(input, width, options = {}) {
+    const inner = Math.max(0, width - 2);
+    const view = input.view(inner);
+    const placeholder = options.placeholder ?? "";
+    const empty = view.text.length === 0 && placeholder.length > 0;
+    const before = view.text.slice(0, view.caretColumn);
+    const under = view.text.slice(view.caretColumn, view.caretColumn + 1) || " ";
+    const after = view.text.slice(view.caretColumn + 1);
+    // Typed text is left unpainted, the caret reverses its cell, and the
+    // placeholder is quietened by weight rather than by a colour of its own.
+    const body = empty
+        ? `${caretCell(placeholder.slice(0, 1))}${faint(placeholder.slice(1))}`
+        : `${before}${caretCell(under)}${after}`;
+    const plain = empty
+        ? placeholder
+        : `${view.text}${view.caretColumn >= view.text.length ? " " : ""}`;
+    const row = padVisible(truncateToWidth(`${PROMPT_GLYPH}${body}`, width), width, `❯ ${plain}`);
+    if (options.ruled === false)
+        return { lines: [row] };
+    const rule = promptRule(width);
+    return { lines: [rule, row, rule] };
+}
+/** Pads by visible width, so styling escapes do not shift the layout. */
+function padVisible(line, width, raw) {
+    const visible = displayWidth(raw);
+    return visible >= width ? line : line + " ".repeat(width - visible);
+}

package/dist/src/foundation/ui-components/list-block.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A grouped list: group headers, selectable elements, notes, and spacers. While
+ * the top visible row belongs to a group, that group's header stays pinned as
+ * the first rendered row, so the reader always knows which group is on screen.
+ */
+export type ListRow<T> = {
+    readonly kind: "group";
+    readonly group: string;
+    readonly title: string;
+} | {
+    readonly kind: "element";
+    readonly group: string;
+    readonly key: string;
+    readonly selectable: boolean;
+    readonly value: T;
+} | {
+    readonly kind: "note";
+    readonly group: string;
+    readonly text: string;
+} | {
+    readonly kind: "spacer";
+};
+export interface ListRowSpan {
+    readonly from: number;
+    readonly to: number;
+}
+export declare function rowKey<T>(row: ListRow<T> | undefined): string | undefined;
+export declare function selectableIndexes<T>(rows: readonly ListRow<T>[]): readonly number[];
+export declare function indexOfKey<T>(rows: readonly ListRow<T>[], key: string | undefined): number;
+/** Clamped movement between selectable rows. No wrap-around. */
+export declare function moveSelection<T>(rows: readonly ListRow<T>[], current: number, delta: number): number;
+/**
+ * Forward lands on the first element of the next group. Backward lands on the
+ * first element of the current group, or the previous group's when already
+ * there. Groups with no selectable element are skipped; edges stay put.
+ */
+export declare function blockJumpTarget<T>(rows: readonly ListRow<T>[], current: number, delta: number): number | undefined;
+/** The block containing `index`: its header through the row before the next header. */
+export declare function blockRowSpan<T>(rows: readonly ListRow<T>[], index: number): ListRowSpan;
+/** The header pinned above the body when the top visible row belongs to a group. */
+export declare function stickyHeaderFor<T>(rows: readonly ListRow<T>[], scroll: number): string | undefined;
+/** One blank row above the first group while the list is scrolled to the top. */
+export declare function topPaddingRows(scroll: number): number;
+/** Rows of content visible after the padding and any pinned header. */
+export declare function visibleRowCount<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number): number;
+export declare function maxScrollFor<T>(rows: readonly ListRow<T>[], bodyHeight: number): number;
+export declare function clampScroll<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number): {
+    readonly scroll: number;
+    readonly visible: number;
+};
+/**
+ * Scroll that brings the selection into view, moving the least it can. A reveal
+ * span asks for a whole block; a block taller than the viewport is shown from
+ * its header instead.
+ */
+export declare function scrollForSelection<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number, selected: number, reveal?: ListRowSpan): number;
+export interface ListLayout {
+    readonly scroll: number;
+    readonly visible: number;
+    readonly stickyHeader: string | undefined;
+    readonly topPadding: number;
+    /** Row indexes rendered in the body, in order. */
+    readonly rowIndexes: readonly number[];
+}
+/** Everything a renderer needs for one frame, derived rather than remembered. */
+export declare function layoutList<T>(rows: readonly ListRow<T>[], bodyHeight: number, scroll: number): ListLayout;

package/dist/src/foundation/ui-components/list-block.js

@@ -0,0 +1,176 @@
+/**
+ * A grouped list: group headers, selectable elements, notes, and spacers. While
+ * the top visible row belongs to a group, that group's header stays pinned as
+ * the first rendered row, so the reader always knows which group is on screen.
+ */
+export function rowKey(row) {
+    return row !== undefined && row.kind === "element" && row.selectable ? row.key : undefined;
+}
+export function selectableIndexes(rows) {
+    const indexes = [];
+    rows.forEach((row, index) => {
+        if (rowKey(row) !== undefined)
+            indexes.push(index);
+    });
+    return indexes;
+}
+export function indexOfKey(rows, key) {
+    if (key !== undefined) {
+        const found = rows.findIndex(row => rowKey(row) === key);
+        if (found >= 0)
+            return found;
+    }
+    return selectableIndexes(rows)[0] ?? -1;
+}
+/** Clamped movement between selectable rows. No wrap-around. */
+export function moveSelection(rows, current, delta) {
+    const selectable = selectableIndexes(rows);
+    if (selectable.length === 0)
+        return -1;
+    const position = selectable.indexOf(current);
+    if (position < 0)
+        return selectable[0] ?? -1;
+    const next = Math.min(Math.max(position + delta, 0), selectable.length - 1);
+    return selectable[next] ?? current;
+}
+function firstElementOfBlock(rows, headerIndex) {
+    for (let index = headerIndex + 1; index < rows.length && rows[index]?.kind !== "group"; index++) {
+        if (rowKey(rows[index]) !== undefined)
+            return index;
+    }
+    return undefined;
+}
+function headerAbove(rows, index) {
+    for (let cursor = Math.min(index, rows.length - 1); cursor >= 0; cursor--) {
+        if (rows[cursor]?.kind === "group")
+            return cursor;
+    }
+    return -1;
+}
+/**
+ * Forward lands on the first element of the next group. Backward lands on the
+ * first element of the current group, or the previous group's when already
+ * there. Groups with no selectable element are skipped; edges stay put.
+ */
+export function blockJumpTarget(rows, current, delta) {
+    if (current < 0 || rows.length === 0)
+        return undefined;
+    const header = headerAbove(rows, current);
+    if (header < 0)
+        return undefined;
+    const blocks = [];
+    for (let index = 0; index < rows.length; index++) {
+        if (rows[index]?.kind === "group" && firstElementOfBlock(rows, index) !== undefined)
+            blocks.push(index);
+    }
+    const position = blocks.indexOf(header);
+    if (position < 0)
+        return undefined;
+    if (delta > 0) {
+        if (position >= blocks.length - 1)
+            return undefined;
+        const next = blocks[position + 1];
+        return next === undefined ? undefined : firstElementOfBlock(rows, next);
+    }
+    const own = firstElementOfBlock(rows, header);
+    if (own !== undefined && own < current)
+        return own;
+    if (position <= 0)
+        return undefined;
+    const previous = blocks[position - 1];
+    return previous === undefined ? undefined : firstElementOfBlock(rows, previous);
+}
+/** The block containing `index`: its header through the row before the next header. */
+export function blockRowSpan(rows, index) {
+    if (rows.length === 0)
+        return { from: 0, to: 0 };
+    const start = Math.min(Math.max(index, 0), rows.length - 1);
+    const from = Math.max(headerAbove(rows, start), 0);
+    let to = rows.length - 1;
+    for (let cursor = start + 1; cursor < rows.length; cursor++) {
+        if (rows[cursor]?.kind === "group") {
+            to = cursor - 1;
+            break;
+        }
+    }
+    return { from, to };
+}
+/** The header pinned above the body when the top visible row belongs to a group. */
+export function stickyHeaderFor(rows, scroll) {
+    const row = rows[scroll];
+    if (row === undefined || (row.kind !== "element" && row.kind !== "note"))
+        return undefined;
+    const header = headerAbove(rows, scroll);
+    const headerRow = header < 0 ? undefined : rows[header];
+    return headerRow !== undefined && headerRow.kind === "group" ? headerRow.title : undefined;
+}
+/** One blank row above the first group while the list is scrolled to the top. */
+export function topPaddingRows(scroll) {
+    return scroll <= 0 ? 1 : 0;
+}
+/** Rows of content visible after the padding and any pinned header. */
+export function visibleRowCount(rows, bodyHeight, scroll) {
+    const reserved = topPaddingRows(scroll) + (stickyHeaderFor(rows, scroll) === undefined ? 0 : 1);
+    return Math.max(1, bodyHeight - reserved);
+}
+export function maxScrollFor(rows, bodyHeight) {
+    let scroll = Math.max(0, rows.length - 1);
+    for (let pass = 0; pass < 8; pass++) {
+        const next = Math.max(0, rows.length - visibleRowCount(rows, bodyHeight, scroll));
+        if (next === scroll)
+            break;
+        scroll = next;
+    }
+    return scroll;
+}
+export function clampScroll(rows, bodyHeight, scroll) {
+    const bounded = Math.min(Math.max(scroll, 0), maxScrollFor(rows, bodyHeight));
+    return { scroll: bounded, visible: visibleRowCount(rows, bodyHeight, bounded) };
+}
+/**
+ * Scroll that brings the selection into view, moving the least it can. A reveal
+ * span asks for a whole block; a block taller than the viewport is shown from
+ * its header instead.
+ */
+export function scrollForSelection(rows, bodyHeight, scroll, selected, reveal) {
+    let next = scroll;
+    for (let pass = 0; pass < 2; pass++) {
+        const visible = visibleRowCount(rows, bodyHeight, next);
+        if (selected >= 0) {
+            if (reveal && reveal.to - reveal.from < visible) {
+                if (reveal.from < next)
+                    next = reveal.from;
+                if (reveal.to >= next + visible)
+                    next = reveal.to - visible + 1;
+            }
+            else if (reveal) {
+                next = reveal.from;
+            }
+            else {
+                if (selected < next)
+                    next = selected;
+                if (selected >= next + visible)
+                    next = selected - visible + 1;
+            }
+        }
+        next = clampScroll(rows, bodyHeight, next).scroll;
+    }
+    return next;
+}
+/** Everything a renderer needs for one frame, derived rather than remembered. */
+export function layoutList(rows, bodyHeight, scroll) {
+    const clamped = clampScroll(rows, bodyHeight, scroll);
+    const sticky = stickyHeaderFor(rows, clamped.scroll);
+    const padding = topPaddingRows(clamped.scroll);
+    const indexes = [];
+    for (let offset = 0; offset < clamped.visible && clamped.scroll + offset < rows.length; offset++) {
+        indexes.push(clamped.scroll + offset);
+    }
+    return {
+        scroll: clamped.scroll,
+        visible: clamped.visible,
+        stickyHeader: sticky,
+        topPadding: padding,
+        rowIndexes: Object.freeze(indexes),
+    };
+}

package/dist/src/foundation/ui-components/list-view.d.ts

@@ -0,0 +1,66 @@
+import type { UiTheme } from "./theme.js";
+/**
+ * A list of things that each carry a label and a value. It owns where a value
+ * starts, how a row reads when it is selected or pointed at, and which part of a
+ * row the pointer is on — so a screen decides what a row means and this decides
+ * how it looks and where it can be touched.
+ */
+/** The part of a row the pointer is over. A label selects; a value acts. */
+export type ListRegion = "label" | "value" | "minus" | "plus";
+/** Columns a stepper's controls occupy on either side of the value. */
+export declare const STEPPER_RESERVE = 2;
+export interface ListViewRow {
+    /** Identity of the row, as the screen knows it. */
+    readonly key: string;
+    readonly label: string;
+    /** The value as it should read. Formatting belongs to the screen. */
+    readonly value: string;
+    /** Trailing note, such as where a value came from. */
+    readonly suffix?: string;
+    /**
+     * Present when the value is stepped. Each end says whether it can still act;
+     * an end that cannot is drawn as unavailable rather than explaining itself.
+     */
+    readonly stepper?: {
+        readonly lower: boolean;
+        readonly raise: boolean;
+    };
+}
+export interface ListRowState {
+    /** The keyboard's row. */
+    readonly selected: boolean;
+    /** The pointer's row, and where on it the pointer is. */
+    readonly hovered: boolean;
+    readonly region: ListRegion;
+}
+/** Where a row was drawn, so a later pointer report can be read against it. */
+export interface ListRowPlacement {
+    readonly key: string;
+    readonly screenRow: number;
+    readonly valueColumn: number;
+    readonly valueWidth: number;
+    readonly stepper: boolean;
+}
+/**
+ * The column every value begins at: past the widest label, with room to breathe,
+ * and with the stepper's columns reserved for every row when any row has one, so
+ * a number does not shift its own value out of the column it shares.
+ */
+export declare function valueColumnFor(rows: readonly ListViewRow[], indent?: number, gap?: number): number;
+/** A group's name, above the rows that belong to it. */
+export declare function renderGroupHeader(title: string, width: number, theme: UiTheme): string;
+/**
+ * One row, painted. The label carries the selection, the value carries the
+ * pointer, and the stepper appears only when the pointer is on the value it
+ * belongs to — an affordance, not decoration.
+ */
+export declare function renderListRow(row: ListViewRow, state: ListRowState, valueColumn: number, width: number, theme: UiTheme): string;
+/** A line that stands in for rows: why a group has none, or what it is waiting on. */
+export declare function renderNote(text: string, width: number, theme: UiTheme): string;
+/** Where the value of a row starts and ends, for reading a pointer against it. */
+export declare function placementFor(row: ListViewRow, screenRow: number, valueColumn: number, hovered: boolean): ListRowPlacement;
+/**
+ * The part of a row a column falls on. The stepper's controls sit in the columns
+ * reserved before and after the value, so they are only reachable while drawn.
+ */
+export declare function regionAt(placement: ListRowPlacement, column: number): ListRegion;

package/dist/src/foundation/ui-components/list-view.js

@@ -0,0 +1,76 @@
+import { displayWidth, truncateToWidth } from "./text.js";
+/** Columns a stepper's controls occupy on either side of the value. */
+export const STEPPER_RESERVE = 2;
+/**
+ * The column every value begins at: past the widest label, with room to breathe,
+ * and with the stepper's columns reserved for every row when any row has one, so
+ * a number does not shift its own value out of the column it shares.
+ */
+export function valueColumnFor(rows, indent = 4, gap = 2) {
+    const widest = Math.max(0, ...rows.map(row => displayWidth(row.label)));
+    const stepper = rows.some(row => row.stepper !== undefined) ? STEPPER_RESERVE : 0;
+    return indent + widest + gap + stepper;
+}
+/** A group's name, above the rows that belong to it. */
+export function renderGroupHeader(title, width, theme) {
+    return truncateToWidth(theme.fg("accent", theme.bold(title)), width);
+}
+/**
+ * One row, painted. The label carries the selection, the value carries the
+ * pointer, and the stepper appears only when the pointer is on the value it
+ * belongs to — an affordance, not decoration.
+ */
+export function renderListRow(row, state, valueColumn, width, theme) {
+    const cursor = state.selected ? "→ " : "  ";
+    const leftRaw = `${cursor}  ${row.label}`;
+    const left = `${theme.fg("accent", cursor)}  ${theme.fg(state.selected ? "accent" : "text", row.label)}`;
+    const gap = Math.max(2, valueColumn - displayWidth(leftRaw));
+    // Pointing anywhere on the row is pointing at the item; pointing at the value
+    // is what brightens it. The selection speaks through the label alone.
+    const valueHovered = state.hovered && state.region !== "label";
+    const stepper = row.stepper !== undefined && valueHovered;
+    const value = theme.fg(valueHovered ? "text" : "muted", row.value);
+    const minus = stepper
+        ? row.stepper?.lower === true
+            ? theme.fg(state.region === "minus" ? "text" : "dim", "- ")
+            : theme.disabled("- ")
+        : "";
+    const plus = stepper
+        ? row.stepper?.raise === true
+            ? theme.fg(state.region === "plus" ? "text" : "dim", " +")
+            : theme.disabled(" +")
+        : "";
+    const indent = Math.max(2, stepper ? gap - STEPPER_RESERVE : gap);
+    const suffix = row.suffix === undefined ? "" : theme.fg("dim", `  ${row.suffix}`);
+    return truncateToWidth(`${left}${" ".repeat(indent)}${minus}${value}${plus}${suffix}`, width);
+}
+/** A line that stands in for rows: why a group has none, or what it is waiting on. */
+export function renderNote(text, width, theme) {
+    return truncateToWidth(theme.fg("muted", `    ${text}`), width);
+}
+/** Where the value of a row starts and ends, for reading a pointer against it. */
+export function placementFor(row, screenRow, valueColumn, hovered) {
+    const stepper = row.stepper !== undefined && hovered;
+    return {
+        key: row.key,
+        screenRow,
+        valueColumn: stepper ? valueColumn - STEPPER_RESERVE : valueColumn,
+        valueWidth: displayWidth(row.value),
+        stepper,
+    };
+}
+/**
+ * The part of a row a column falls on. The stepper's controls sit in the columns
+ * reserved before and after the value, so they are only reachable while drawn.
+ */
+export function regionAt(placement, column) {
+    const start = placement.valueColumn + 1;
+    const end = start + placement.valueWidth;
+    if (column >= start && column <= end)
+        return "value";
+    if (placement.stepper && column >= start - STEPPER_RESERVE && column < start)
+        return "minus";
+    if (placement.stepper && column > end && column <= end + STEPPER_RESERVE)
+        return "plus";
+    return "label";
+}

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

@@ -0,0 +1,15 @@
+import type { PaneMouseEvent } from "./pane.js";
+/**
+ * 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 declare const MOUSE_TRACKING_ON = "\u001B[?1006h\u001B[?1000h\u001B[?1003h";
+export declare const MOUSE_TRACKING_OFF = "\u001B[?1003l\u001B[?1000l\u001B[?1006l";
+export interface ParsedMouseInput {
+    readonly events: readonly PaneMouseEvent[];
+    /** Input with every mouse report removed, for ordinary key handling. */
+    readonly rest: string;
+}
+/** Extracts SGR mouse reports, leaving any keyboard input untouched. */
+export declare function parseMouseInput(data: string): ParsedMouseInput;