@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/widgets/focus-manager.js

@@ -0,0 +1,191 @@
+/**
+ * FocusManager — which widget has focus, over the widgets on the frame.
+ * [LAW:one-source-of-truth] single authority for which widget has focus.
+ * [LAW:dataflow-not-control-flow] focus transitions are observable state;
+ * widgets react to focus/blur events, the manager never skips dispatch.
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { action, observableRef } from "mobx";
+let DefaultFocusManager = (() => {
+    let _instanceExtraInitializers = [];
+    let _currentWidget_decorators;
+    let _currentWidget_initializers = [];
+    let _currentWidget_extraInitializers = [];
+    let _next_decorators;
+    let _prev_decorators;
+    let _focus_decorators;
+    let _settle_decorators;
+    let _clear_decorators;
+    let _setFocus_decorators;
+    return class DefaultFocusManager {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _currentWidget_decorators = [observableRef];
+            _next_decorators = [action];
+            _prev_decorators = [action];
+            _focus_decorators = [action];
+            _settle_decorators = [action];
+            _clear_decorators = [action];
+            _setFocus_decorators = [action];
+            __esDecorate(this, null, _currentWidget_decorators, { kind: "accessor", name: "currentWidget", static: false, private: false, access: { has: obj => "currentWidget" in obj, get: obj => obj.currentWidget, set: (obj, value) => { obj.currentWidget = value; } }, metadata: _metadata }, _currentWidget_initializers, _currentWidget_extraInitializers);
+            __esDecorate(this, null, _next_decorators, { kind: "method", name: "next", static: false, private: false, access: { has: obj => "next" in obj, get: obj => obj.next }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _prev_decorators, { kind: "method", name: "prev", static: false, private: false, access: { has: obj => "prev" in obj, get: obj => obj.prev }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _focus_decorators, { kind: "method", name: "focus", static: false, private: false, access: { has: obj => "focus" in obj, get: obj => obj.focus }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _settle_decorators, { kind: "method", name: "settle", static: false, private: false, access: { has: obj => "settle" in obj, get: obj => obj.settle }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _clear_decorators, { kind: "method", name: "clear", static: false, private: false, access: { has: obj => "clear" in obj, get: obj => obj.clear }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setFocus_decorators, { kind: "method", name: "setFocus", static: false, private: false, access: { has: obj => "setFocus" in obj, get: obj => obj.setFocus }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        onScreen = __runInitializers(this, _instanceExtraInitializers);
+        #currentWidget_accessor_storage = __runInitializers(this, _currentWidget_initializers, null);
+        get currentWidget() { return this.#currentWidget_accessor_storage; }
+        set currentWidget(value) { this.#currentWidget_accessor_storage = value; }
+        changeHandlers = (__runInitializers(this, _currentWidget_extraInitializers), new Set());
+        /**
+         * `onScreen` is the widgets on the frame on screen, in document order.
+         *
+         * [LAW:one-source-of-truth] It is asked every time rather than kept: a list
+         * of the widgets held here would be a second picture of the frame, and
+         * wrong from the next paint.
+         */
+        constructor(onScreen) {
+            this.onScreen = onScreen;
+        }
+        get current() {
+            return this.currentWidget;
+        }
+        get widgets() {
+            return this.onScreen().filter(takesFocus);
+        }
+        next() {
+            const focusable = this.widgets;
+            if (focusable.length === 0)
+                return;
+            const currentIdx = this.currentWidget ? focusable.indexOf(this.currentWidget) : -1;
+            const nextIdx = (currentIdx + 1) % focusable.length;
+            this.setFocus(focusable[nextIdx]);
+        }
+        prev() {
+            const focusable = this.widgets;
+            if (focusable.length === 0)
+                return;
+            const currentIdx = this.currentWidget ? focusable.indexOf(this.currentWidget) : -1;
+            const prevIdx = currentIdx <= 0 ? focusable.length - 1 : currentIdx - 1;
+            this.setFocus(focusable[prevIdx]);
+        }
+        // A widget not on screen yet can take focus: an app that is about to show
+        // it focuses it first, and the frame that shows it keeps it (`settle`).
+        focus(widget) {
+            if (!takesFocus(widget))
+                return;
+            this.setFocus(widget);
+        }
+        /**
+         * Put focus where the frame just painted lets it rest: it stays on a widget
+         * the view drew (`drawn`) that can take it, and otherwise moves to the first
+         * one on screen that can, or to none.
+         *
+         * Drawn, not on screen: a widget cropped for the moment — the terminal
+         * shrank, a viewport scrolled, an overlay covers it — is still in the view,
+         * and keeps focus and whatever focus holds, like a half-typed filter.
+         *
+         * [LAW:single-enforcer] The one place focus follows the frame — onto the
+         * first widget when the app starts, off a widget that stopped being drawn
+         * or was disabled.
+         */
+        settle(drawn) {
+            const current = this.currentWidget;
+            if (current && takesFocus(current) && drawn.includes(current))
+                return;
+            const first = this.widgets[0];
+            if (first)
+                this.setFocus(first);
+            else
+                this.clear();
+        }
+        onChange(handler) {
+            this.changeHandlers.add(handler);
+            return () => this.changeHandlers.delete(handler);
+        }
+        // [LAW:single-enforcer] FocusManager owns Tab/Shift+Tab semantics. The
+        // router registers this as a normal-priority handler at construction —
+        // it runs after the focused widget, so a widget can `event.stop()`
+        // to suppress traversal (e.g. Dropdown when its overlay is open).
+        handleKey(event) {
+            if (event.key !== "tab")
+                return;
+            if (event.shift)
+                this.prev();
+            else
+                this.next();
+            event.stop();
+        }
+        // --- Private ---
+        // No focus is where `settle` leaves an app with nothing to focus, and only
+        // there: anywhere else the next frame would put focus back on the first
+        // widget, so there is no public way in.
+        clear() {
+            if (!this.currentWidget)
+                return;
+            // [LAW:single-enforcer] WidgetBase.focus()/blur() route through
+            // handleFocus; calling it here as well would dispatch twice and run any
+            // subclass side effect (e.g. Dropdown clearing its filter) twice.
+            this.currentWidget.blur();
+            this.currentWidget = null;
+            this.emitChange();
+        }
+        setFocus(widget) {
+            if (this.currentWidget === widget)
+                return;
+            // [LAW:single-enforcer] focus()/blur() already dispatch handleFocus —
+            // see clear() for the rationale.
+            if (this.currentWidget)
+                this.currentWidget.blur();
+            this.currentWidget = widget;
+            widget.focus();
+            this.emitChange();
+        }
+        emitChange() {
+            for (const handler of this.changeHandlers) {
+                handler(this.currentWidget);
+            }
+        }
+    };
+})();
+export { DefaultFocusManager };
+function takesFocus(widget) {
+    return widget.focusable && !widget.disabled;
+}

package/dist/widgets/hit.d.ts

@@ -0,0 +1,64 @@
+/**
+ * widgetAt — which widget drew a cell of a painted frame, and where in its
+ * own output that cell sits; scrollTargetAt — what the wheel over that cell
+ * moves.
+ *
+ * A widget stamps every cell it draws (`WidgetBase.render`), and a
+ * `Scrollable` such as `Viewport` every cell it shows, around its content's
+ * stamps. The stamp rides
+ * through every container on the cell's `Style`, and the frame a screen paints
+ * is therefore its own hit map: nothing lays widgets out a second time to
+ * answer "what is under the pointer", so the answer cannot disagree with what
+ * the user sees. Z-order is paint order — whoever painted a cell last owns it.
+ */
+import { Segment } from "../core/segment.js";
+import type { Scrollable } from "../core/protocol.js";
+import type { InteractiveWidget } from "./types.js";
+/** A pointer position resolved to the widget that drew it. */
+export interface WidgetHit {
+    readonly widget: InteractiveWidget;
+    /** Column of the cell in the widget's own output. */
+    readonly col: number;
+    /** Row of the cell in the widget's own output. */
+    readonly row: number;
+}
+/**
+ * The innermost widget that drew the cell at column `x` of row `y` of
+ * `frame`, or `undefined` when no widget drew it. A widget nested inside
+ * another widget's output wins over the one containing it.
+ */
+export declare function widgetAt(frame: readonly (readonly Segment[])[], x: number, y: number): WidgetHit | undefined;
+/**
+ * The innermost `Scrollable` that drew the cell at column `x` of row `y` of
+ * `frame` and that `scrollBy(lines)` would move, or `undefined` when none
+ * did. A widget drawn inside it does not hide it: the widget's anchor is
+ * nested in its. One that cannot move that way — a viewport whose content
+ * fits, or that is at that end — passes the wheel to the one around it.
+ */
+export declare function scrollTargetAt(frame: readonly (readonly Segment[])[], x: number, y: number, lines: number): Scrollable | undefined;
+/**
+ * Where `widget`'s output starts in `frame` — the cell its own row 0, column
+ * 0 falls on — read off the first cell it drew, or `undefined` when it drew
+ * none.
+ */
+export declare function originOf(frame: readonly (readonly Segment[])[], widget: InteractiveWidget): {
+    x: number;
+    y: number;
+} | undefined;
+/**
+ * Whether `widget` drew the cell at column `x` of row `y` of `frame`, itself
+ * or through a widget nested in its output.
+ */
+export declare function drew(frame: readonly (readonly Segment[])[], widget: InteractiveWidget, x: number, y: number): boolean;
+/**
+ * Where `widget`'s footprint sits in `frame`: the cell its row 0, column 0
+ * falls on, and how many of its rows the frame shows down to its lowest — or
+ * `undefined` when the frame does not show its row 0.
+ */
+export declare function footprintOf(frame: readonly (readonly Segment[])[], widget: InteractiveWidget): {
+    x: number;
+    y: number;
+    rows: number;
+} | undefined;
+/** Every owner that drew a cell of `frame`, at every depth of nesting. */
+export declare function ownersOn(frame: readonly (readonly Segment[])[]): Set<object>;

package/dist/widgets/hit.js

@@ -0,0 +1,113 @@
+/**
+ * widgetAt — which widget drew a cell of a painted frame, and where in its
+ * own output that cell sits; scrollTargetAt — what the wheel over that cell
+ * moves.
+ *
+ * A widget stamps every cell it draws (`WidgetBase.render`), and a
+ * `Scrollable` such as `Viewport` every cell it shows, around its content's
+ * stamps. The stamp rides
+ * through every container on the cell's `Style`, and the frame a screen paints
+ * is therefore its own hit map: nothing lays widgets out a second time to
+ * answer "what is under the pointer", so the answer cannot disagree with what
+ * the user sees. Z-order is paint order — whoever painted a cell last owns it.
+ */
+import { Segment } from "../core/segment.js";
+import { isScrollable } from "../core/protocol.js";
+import { WidgetBase } from "./widget-base.js";
+/**
+ * The innermost widget that drew the cell at column `x` of row `y` of
+ * `frame`, or `undefined` when no widget drew it. A widget nested inside
+ * another widget's output wins over the one containing it.
+ */
+export function widgetAt(frame, x, y) {
+    const hit = innermost(frame, x, y, (owner) => (owner instanceof WidgetBase ? owner : undefined));
+    return hit && { widget: hit.owner, col: hit.col, row: hit.row };
+}
+/**
+ * The innermost `Scrollable` that drew the cell at column `x` of row `y` of
+ * `frame` and that `scrollBy(lines)` would move, or `undefined` when none
+ * did. A widget drawn inside it does not hide it: the widget's anchor is
+ * nested in its. One that cannot move that way — a viewport whose content
+ * fits, or that is at that end — passes the wheel to the one around it.
+ */
+export function scrollTargetAt(frame, x, y, lines) {
+    return innermost(frame, x, y, (owner) => isScrollable(owner) && owner.canScrollBy(lines) ? owner : undefined)?.owner;
+}
+/**
+ * The innermost owner of the cell at column `x` of row `y` of `frame` that
+ * `accept` turns into a `T`, with the cell's place in that owner's output.
+ *
+ * [LAW:parse-dont-validate] An anchor's owner is any object; `accept` is
+ * where it becomes the kind of owner the caller asked for, or nothing.
+ */
+function innermost(frame, x, y, accept) {
+    let found;
+    for (let a = Segment.anchorAt(frame, x, y); a; a = a.inner) {
+        const owner = accept(a.owner);
+        if (owner)
+            found = { owner, col: a.col, row: a.row };
+    }
+    return found;
+}
+/**
+ * Where `widget`'s output starts in `frame` — the cell its own row 0, column
+ * 0 falls on — read off the first cell it drew, or `undefined` when it drew
+ * none.
+ */
+export function originOf(frame, widget) {
+    for (let y = 0; y < frame.length; y++) {
+        let start = 0;
+        for (const segment of frame[y]) {
+            for (let a = segment.style?.anchor; a; a = a.inner) {
+                if (a.owner === widget)
+                    return { x: start - a.col, y: y - a.row };
+            }
+            start += segment.cellLength;
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether `widget` drew the cell at column `x` of row `y` of `frame`, itself
+ * or through a widget nested in its output.
+ */
+export function drew(frame, widget, x, y) {
+    for (let a = Segment.anchorAt(frame, x, y); a; a = a.inner)
+        if (a.owner === widget)
+            return true;
+    return false;
+}
+/**
+ * Where `widget`'s footprint sits in `frame`: the cell its row 0, column 0
+ * falls on, and how many of its rows the frame shows down to its lowest — or
+ * `undefined` when the frame does not show its row 0.
+ */
+export function footprintOf(frame, widget) {
+    let origin;
+    let rows = 0;
+    for (let y = 0; y < frame.length; y++) {
+        let start = 0;
+        for (const segment of frame[y]) {
+            for (let a = segment.style?.anchor; a; a = a.inner) {
+                if (a.owner !== widget)
+                    continue;
+                if (a.row === 0 && !origin)
+                    origin = { x: start - a.col, y };
+                rows = Math.max(rows, a.row + 1);
+            }
+            start += segment.cellLength;
+        }
+    }
+    return origin && { ...origin, rows };
+}
+/** Every owner that drew a cell of `frame`, at every depth of nesting. */
+export function ownersOn(frame) {
+    const owners = new Set();
+    for (const line of frame) {
+        for (const segment of line) {
+            for (let a = segment.style?.anchor; a; a = a.inner)
+                owners.add(a.owner);
+        }
+    }
+    return owners;
+}

package/dist/widgets/index.d.ts

@@ -0,0 +1,20 @@
+export type { KeyEventInit, KeyHandlerPriority, KeyHandlerOptions, ScreenMouseEvent, WidgetMouseEvent, WidgetFocusEvent, InteractiveWidget, OverlayRenderable, FocusManager, } from "./types.js";
+export { hasOverlay, KeyEvent } from "./types.js";
+export { StaticItem } from "./static-item.js";
+export type { StaticItemOptions } from "./static-item.js";
+export { WidgetBase } from "./widget-base.js";
+export { WidgetApp } from "./widget-app.js";
+export { Button } from "./button.js";
+export type { ButtonVariant, ButtonOptions } from "./button.js";
+export { Checkbox } from "./checkbox.js";
+export type { CheckboxOptions } from "./checkbox.js";
+export { Toggle } from "./toggle.js";
+export type { ToggleVariant, ToggleOptions } from "./toggle.js";
+export { TextInput, charGreedyWrap } from "./text-input.js";
+export type { TextInputOptions, WrapStrategy, WrapRow } from "./text-input.js";
+export { Dropdown } from "./dropdown.js";
+export type { DropdownOptions } from "./dropdown.js";
+export { Slider } from "./slider.js";
+export type { SliderOptions } from "./slider.js";
+export { widgetAt } from "./hit.js";
+export type { WidgetHit } from "./hit.js";

package/dist/widgets/index.js

@@ -0,0 +1,14 @@
+export { hasOverlay, KeyEvent } from "./types.js";
+export { StaticItem } from "./static-item.js";
+export { WidgetBase } from "./widget-base.js";
+export { WidgetApp } from "./widget-app.js";
+export { Button } from "./button.js";
+export { Checkbox } from "./checkbox.js";
+export { Toggle } from "./toggle.js";
+export { TextInput, charGreedyWrap } from "./text-input.js";
+export { Dropdown } from "./dropdown.js";
+export { Slider } from "./slider.js";
+export { widgetAt } from "./hit.js";
+// The terminal seam is not re-exported here. It lives on the `host` subpath,
+// and a second path to `TerminalHost` would be the two-clocks problem the
+// subpath split exists to remove.

package/dist/widgets/slider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Slider widget — numeric value within [min, max] with step increments.
+ * [LAW:dataflow-not-control-flow] every render emits exactly `width`
+ * track cells; the marker cell index is data, not a branch.
+ * [LAW:one-type-per-behavior] shared infrastructure inherited from
+ * WidgetBase.
+ *
+ * Visual:
+ *   track    — `width` cells of "─" (ASCII fallback "-")
+ *   marker   — "●" (ASCII fallback "*") at round((value - min) / range * (width - 1))
+ *   filled   — cells left of and including the marker use primary fg
+ *              on the default terminal bg
+ *   unfilled — cells right of the marker use surface fg on the default
+ *              terminal bg (no explicit bgcolor — the unfilled track
+ *              should sit transparently against whatever the panel /
+ *              parent paints underneath)
+ *   focused  — underline on the segments
+ *   disabled — dim
+ */
+import { Segment } from "../core/segment.js";
+import { type RenderOptions } from "../core/protocol.js";
+import type { TerminalTheme } from "../core/color.js";
+import { WidgetBase } from "./widget-base.js";
+import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+export interface SliderOptions {
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    width?: number;
+    id?: string;
+    disabled?: boolean;
+    theme?: TerminalTheme;
+}
+export declare class Slider extends WidgetBase {
+    readonly id: string;
+    readonly focusable = true;
+    accessor value: number;
+    accessor min: number;
+    accessor max: number;
+    accessor step: number;
+    accessor width: number;
+    private accessor _theme;
+    private _dragging;
+    constructor(options?: SliderOptions);
+    setTheme(theme: TerminalTheme): void;
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    private setValue;
+    private setValueFromMouseX;
+    protected draw(options: RenderOptions): Iterable<Segment>;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    private resolvePalette;
+}