@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/widgets/themed-widget.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ThemedWidget — a widget that draws every cell it owns from one theme's
+ * palette: the interactive widgets, as against `StaticItem`, which shows
+ * content it did not draw.
+ *
+ * [LAW:one-type-per-behavior] The theme, how it is swapped, what a disabled
+ * widget looks like, and the ground a padded row stands on are the same for
+ * every such widget, so they live here once.
+ */
+import { Style } from "../core/style.js";
+import type { TerminalTheme } from "../core/color.js";
+import { WidgetBase } from "./widget-base.js";
+import { ink } from "./ink.js";
+export declare abstract class ThemedWidget extends WidgetBase {
+    protected accessor theme: TerminalTheme;
+    constructor(theme: TerminalTheme | undefined);
+    setTheme(theme: TerminalTheme): void;
+    protected get ground(): Style;
+    protected get disabledInk(): ReturnType<typeof ink>;
+}

package/dist/widgets/themed-widget.js

@@ -0,0 +1,89 @@
+/**
+ * ThemedWidget — a widget that draws every cell it owns from one theme's
+ * palette: the interactive widgets, as against `StaticItem`, which shows
+ * content it did not draw.
+ *
+ * [LAW:one-type-per-behavior] The theme, how it is swapped, what a disabled
+ * widget looks like, and the ground a padded row stands on are the same for
+ * every such widget, so they live here once.
+ */
+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 { observableRef, action } from "mobx";
+import { Style } from "../core/style.js";
+import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
+import { WidgetBase } from "./widget-base.js";
+import { ink } from "./ink.js";
+let ThemedWidget = (() => {
+    let _classSuper = WidgetBase;
+    let _instanceExtraInitializers = [];
+    let _theme_decorators;
+    let _theme_initializers = [];
+    let _theme_extraInitializers = [];
+    let _setTheme_decorators;
+    return class ThemedWidget extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _theme_decorators = [observableRef];
+            _setTheme_decorators = [action];
+            __esDecorate(this, null, _theme_decorators, { kind: "accessor", name: "theme", static: false, private: false, access: { has: obj => "theme" in obj, get: obj => obj.theme, set: (obj, value) => { obj.theme = value; } }, metadata: _metadata }, _theme_initializers, _theme_extraInitializers);
+            __esDecorate(this, null, _setTheme_decorators, { kind: "method", name: "setTheme", static: false, private: false, access: { has: obj => "setTheme" in obj, get: obj => obj.setTheme }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        #theme_accessor_storage = (__runInitializers(this, _instanceExtraInitializers), __runInitializers(this, _theme_initializers, void 0));
+        // [LAW:types-are-the-program] @observableRef so setTheme() triggers a
+        // re-render: every draw reads its colours through this reference.
+        get theme() { return this.#theme_accessor_storage; }
+        set theme(value) { this.#theme_accessor_storage = value; }
+        constructor(theme) {
+            super();
+            __runInitializers(this, _theme_extraInitializers);
+            this.theme = theme ?? DEFAULT_TERMINAL_THEME;
+        }
+        setTheme(theme) {
+            this.theme = theme;
+        }
+        get ground() {
+            return new Style(ink(this.theme, "foreground", "background"));
+        }
+        // [LAW:one-source-of-truth] How every widget looks while disabled: the
+        // palette's de-emphasized text on its ground. WCAG sets no contrast floor for
+        // an inactive control, and this sits under the one for text on purpose.
+        get disabledInk() {
+            return ink(this.theme, "foreground-muted", "background");
+        }
+    };
+})();
+export { ThemedWidget };

package/dist/widgets/toggle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Toggle widget — on/off switch with label and variant colour.
+ * [LAW:dataflow-not-control-flow] one Segment of fixed width every render;
+ * indicator and palette keys come from observable state via lookup tables.
+ * [LAW:one-type-per-behavior] shared infrastructure inherited from WidgetBase.
+ *
+ * Visual states:
+ *   off       — "[OFF] label" with muted variant background
+ *   on        — "[ON]  label" with full variant accent background
+ *   focused   — underline on the segment (no width change)
+ *   disabled  — dimmed
+ */
+import { Segment } from "../core/segment.js";
+import type { RenderOptions } from "../core/protocol.js";
+import type { TerminalTheme } from "../core/color.js";
+import { ThemedWidget } from "./themed-widget.js";
+import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+export type ToggleVariant = "default" | "primary" | "success" | "warning" | "danger";
+export interface ToggleOptions {
+    label: string;
+    on?: boolean;
+    id?: string;
+    disabled?: boolean;
+    theme?: TerminalTheme;
+    variant?: ToggleVariant;
+}
+export declare class Toggle extends ThemedWidget {
+    readonly id: string;
+    readonly focusable = true;
+    accessor label: string;
+    accessor on: boolean;
+    accessor variant: ToggleVariant;
+    constructor(options: ToggleOptions);
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    protected draw(_options: RenderOptions): Iterable<Segment>;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/widgets/toggle.js

@@ -0,0 +1,157 @@
+/**
+ * Toggle widget — on/off switch with label and variant colour.
+ * [LAW:dataflow-not-control-flow] one Segment of fixed width every render;
+ * indicator and palette keys come from observable state via lookup tables.
+ * [LAW:one-type-per-behavior] shared infrastructure inherited from WidgetBase.
+ *
+ * Visual states:
+ *   off       — "[OFF] label" with muted variant background
+ *   on        — "[ON]  label" with full variant accent background
+ *   focused   — underline on the segment (no width change)
+ *   disabled  — dimmed
+ */
+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 { observable, action, observableRef } from "mobx";
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { cellLen } from "../core/cells.js";
+import { ThemedWidget } from "./themed-widget.js";
+import { ink } from "./ink.js";
+// onFg uses on-${accent} (WCAG-correct contrast, picked once at palette
+// build time) so the ON state stays readable on a full accent bg. Earlier
+// versions used text-${accent} here, which is mostly-accent and clashed
+// with the same accent as background. offFg keeps text-${accent} because
+// offBg is mostly-bg-tinted and the contrast holds.
+const VARIANT_KEYS = {
+    default: { onBg: "primary", onFg: "on-primary", offBg: "surface", offFg: "foreground" },
+    primary: { onBg: "primary", onFg: "on-primary", offBg: "primary-muted", offFg: "text-primary" },
+    success: { onBg: "success", onFg: "on-success", offBg: "success-muted", offFg: "text-success" },
+    warning: { onBg: "warning", onFg: "on-warning", offBg: "warning-muted", offFg: "text-warning" },
+    danger: { onBg: "error", onFg: "on-error", offBg: "error-muted", offFg: "text-error" },
+};
+let Toggle = (() => {
+    let _classSuper = ThemedWidget;
+    let _instanceExtraInitializers = [];
+    let _label_decorators;
+    let _label_initializers = [];
+    let _label_extraInitializers = [];
+    let _on_decorators;
+    let _on_initializers = [];
+    let _on_extraInitializers = [];
+    let _variant_decorators;
+    let _variant_initializers = [];
+    let _variant_extraInitializers = [];
+    let _handleKey_decorators;
+    let _handleMouse_decorators;
+    return class Toggle extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _label_decorators = [observable];
+            _on_decorators = [observable];
+            _variant_decorators = [observableRef];
+            _handleKey_decorators = [action];
+            _handleMouse_decorators = [action];
+            __esDecorate(this, null, _label_decorators, { kind: "accessor", name: "label", static: false, private: false, access: { has: obj => "label" in obj, get: obj => obj.label, set: (obj, value) => { obj.label = value; } }, metadata: _metadata }, _label_initializers, _label_extraInitializers);
+            __esDecorate(this, null, _on_decorators, { kind: "accessor", name: "on", static: false, private: false, access: { has: obj => "on" in obj, get: obj => obj.on, set: (obj, value) => { obj.on = value; } }, metadata: _metadata }, _on_initializers, _on_extraInitializers);
+            __esDecorate(this, null, _variant_decorators, { kind: "accessor", name: "variant", static: false, private: false, access: { has: obj => "variant" in obj, get: obj => obj.variant, set: (obj, value) => { obj.variant = value; } }, metadata: _metadata }, _variant_initializers, _variant_extraInitializers);
+            __esDecorate(this, null, _handleKey_decorators, { kind: "method", name: "handleKey", static: false, private: false, access: { has: obj => "handleKey" in obj, get: obj => obj.handleKey }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _handleMouse_decorators, { kind: "method", name: "handleMouse", static: false, private: false, access: { has: obj => "handleMouse" in obj, get: obj => obj.handleMouse }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        id = __runInitializers(this, _instanceExtraInitializers);
+        focusable = true;
+        #label_accessor_storage = __runInitializers(this, _label_initializers, void 0);
+        get label() { return this.#label_accessor_storage; }
+        set label(value) { this.#label_accessor_storage = value; }
+        #on_accessor_storage = (__runInitializers(this, _label_extraInitializers), __runInitializers(this, _on_initializers, void 0));
+        get on() { return this.#on_accessor_storage; }
+        set on(value) { this.#on_accessor_storage = value; }
+        #variant_accessor_storage = (__runInitializers(this, _on_extraInitializers), __runInitializers(this, _variant_initializers, void 0));
+        get variant() { return this.#variant_accessor_storage; }
+        set variant(value) { this.#variant_accessor_storage = value; }
+        constructor(options) {
+            super(options.theme);
+            __runInitializers(this, _variant_extraInitializers);
+            this.id = options.id ?? `toggle-${options.label.toLowerCase().replace(/\s+/g, "-")}`;
+            this.label = options.label;
+            this.on = options.on ?? false;
+            this.variant = options.variant ?? "default";
+            this.disabled = options.disabled ?? false;
+        }
+        // --- Event handlers ---
+        handleKey(event) {
+            if (this.disabled)
+                return;
+            if (event.key === "space") {
+                this.on = !this.on;
+                this.emitChange();
+                event.stop();
+                return;
+            }
+            if (event.key === "enter") {
+                this.emitSubmit();
+                event.stop();
+            }
+        }
+        handleMouse(event) {
+            if (this.disabled)
+                return;
+            // A release that dragged off the toggle cancels the press.
+            if (event.type === "mouse_up" && event.over) {
+                this.on = !this.on;
+                this.emitChange();
+            }
+        }
+        // --- Rendering ---
+        draw(_options) {
+            // Both indicators are exactly 5 cells: "[ON] " and "[OFF]".
+            const indicator = this.on ? "[ON] " : "[OFF]";
+            const text = `${indicator} ${this.label}`;
+            if (this.disabled) {
+                return [new Segment(text, new Style(this.disabledInk))];
+            }
+            const keys = VARIANT_KEYS[this.variant];
+            const colors = this.on ? ink(this.theme, keys.onFg, keys.onBg) : ink(this.theme, keys.offFg, keys.offBg);
+            return [new Segment(text, new Style({ ...colors, underline: this.focused }))];
+        }
+        measure(_options) {
+            // [LAW:one-source-of-truth] cellLen — see button.ts.
+            const width = 5 + 1 + cellLen(this.label);
+            return { minimum: width, maximum: width };
+        }
+    };
+})();
+export { Toggle };

package/dist/widgets/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Interactive widget event types and core interfaces.
+ * [LAW:one-source-of-truth] These types are the single authority for the widget contract.
+ * Widgets are MobX-observable state machines that implement Renderable,
+ * producing Segment[] from current state. They have no knowledge of stdin,
+ * terminal escape sequences, or their host environment.
+ */
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Segment } from "../core/segment.js";
+import type { Unsubscribe } from "../core/subscription.js";
+export interface KeyEventInit {
+    key: string;
+    character: string;
+    shift: boolean;
+    ctrl: boolean;
+    meta: boolean;
+}
+export declare class KeyEvent {
+    readonly key: string;
+    readonly character: string;
+    readonly shift: boolean;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+    private _stopped;
+    constructor(init: KeyEventInit);
+    get stopped(): boolean;
+    stop(): void;
+}
+export type KeyHandlerPriority = "high" | "normal";
+export interface KeyHandlerOptions {
+    priority?: KeyHandlerPriority;
+}
+export type ScreenMouseEvent = {
+    [T in MouseEventType]: MouseEventOf<T>;
+}[MouseEventType];
+type MouseEventType = "mouse_down" | "mouse_up" | "mouse_move" | "scroll_up" | "scroll_down";
+interface MouseEventOf<Type extends string> {
+    type: Type;
+    x: number;
+    y: number;
+    button: number;
+    shift: boolean;
+    ctrl: boolean;
+}
+export interface WidgetMouseEvent extends MouseEventOf<"mouse_down" | "mouse_up" | "mouse_move"> {
+    over: boolean;
+}
+export interface WidgetFocusEvent {
+    type: "focus" | "blur";
+}
+export interface InteractiveWidget extends Renderable, Measurable {
+    readonly id: string;
+    readonly focusable: boolean;
+    focused: boolean;
+    hovered: boolean;
+    active: boolean;
+    disabled: boolean;
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    handleFocus(event: WidgetFocusEvent): void;
+    focus(): void;
+    blur(): void;
+    setDisabled(value: boolean): void;
+    setHovered(value: boolean): void;
+    onChange(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+    onSubmit(handler: (widget: InteractiveWidget) => void): Unsubscribe;
+}
+export interface OverlayRenderable {
+    renderOverlay(options: RenderOptions): Iterable<Segment> | null;
+}
+export declare function hasOverlay(value: object): value is OverlayRenderable;
+export interface FocusManager {
+    readonly current: InteractiveWidget | null;
+    /** The widgets Tab moves between, in the order it moves. */
+    readonly widgets: readonly InteractiveWidget[];
+    next(): void;
+    prev(): void;
+    focus(widget: InteractiveWidget): void;
+    handleKey(event: KeyEvent): void;
+    onChange(handler: (current: InteractiveWidget | null) => void): Unsubscribe;
+}
+export interface FrameSource {
+    readonly focusManager: FocusManager;
+    readonly frame: readonly (readonly Segment[])[];
+    refresh(): void;
+}
+export {};

package/dist/widgets/types.js

@@ -0,0 +1,30 @@
+/**
+ * Interactive widget event types and core interfaces.
+ * [LAW:one-source-of-truth] These types are the single authority for the widget contract.
+ * Widgets are MobX-observable state machines that implement Renderable,
+ * producing Segment[] from current state. They have no knowledge of stdin,
+ * terminal escape sequences, or their host environment.
+ */
+export class KeyEvent {
+    key;
+    character;
+    shift;
+    ctrl;
+    meta;
+    _stopped = false;
+    constructor(init) {
+        this.key = init.key;
+        this.character = init.character;
+        this.shift = init.shift;
+        this.ctrl = init.ctrl;
+        this.meta = init.meta;
+    }
+    get stopped() { return this._stopped; }
+    // Claim this key. Halts further chain dispatch — no high/normal handler
+    // and no focused-widget handler downstream of the caller will see it.
+    stop() { this._stopped = true; }
+}
+export function hasOverlay(value) {
+    return ("renderOverlay" in value &&
+        typeof value.renderOverlay === "function");
+}

package/dist/widgets/widget-app.d.ts

@@ -0,0 +1,65 @@
+/**
+ * WidgetApp — an `App` whose view has widgets in it: keys reach the focused
+ * widget, the pointer reaches the widget that drew the cell under it, and a
+ * change to anything a frame read paints the next one.
+ *
+ * A widget goes wherever a renderable goes — in a `Panel`, a `Layout` pane, a
+ * `Table` cell — and nothing lays it out a second time. Everything added here
+ * reads the frame the view drew:
+ *
+ * - Focus moves in document order: the order widgets start to render in
+ *   (`RenderOptions.onDraw`), among those with a cell on the frame on screen.
+ *   Not reading order — in a `Layout` split into columns, reading order
+ *   zigzags between the columns row by row.
+ * - Overlays are painted over the view's frame, in document order, directly
+ *   below their owner's footprint (`OverlayRenderable`). Paint order is the
+ *   z-order: a later overlay covers an earlier one.
+ * - A pointer event goes to the innermost widget that drew the cell under it
+ *   (`widgetAt`), in that widget's own coordinates; the wheel goes to the
+ *   innermost `Viewport` that can move (`scrollTargetAt`).
+ *
+ * [LAW:locality-or-seam] `App` knows nothing of widgets — `host/` depends on
+ * `core/` alone — and this reaches it only through the seams it already has:
+ * the view is a renderable, and `onPaint` hears the frame.
+ */
+import { Segment } from "../core/segment.js";
+import type { Unsubscribe } from "../core/subscription.js";
+import { type AppOptions, type AppPhase } from "../host/app.js";
+import type { FocusManager, FrameSource, KeyEvent, KeyHandlerOptions, ScreenMouseEvent } from "./types.js";
+export declare class WidgetApp implements FrameSource {
+    readonly focusManager: FocusManager;
+    private readonly focus;
+    private readonly app;
+    private readonly router;
+    private readonly reaction;
+    private drawn;
+    constructor(options: AppOptions);
+    get phase(): AppPhase;
+    /** The rows on screen now, as painted: what a pointer event lands on. */
+    get frame(): readonly (readonly Segment[])[];
+    /**
+     * Take the terminal, paint the first frame, and route input to its widgets
+     * until the app stops — `App.run`, with the input.
+     */
+    run(): Promise<void>;
+    stop(): void;
+    fail(error: unknown): void;
+    /**
+     * Paint the next frame, as `App.refresh` does. A change to an observable
+     * the view read needs none; one no observable carries — a `Viewport`
+     * scrolled from a key handler — does.
+     */
+    refresh(): void;
+    suspend(): Promise<void>;
+    /** Paint at the app's rate until the returned function is called, as `App.animate` does. */
+    animate(): Unsubscribe;
+    /**
+     * Hear every key. A `high` handler hears it before the focused widget, a
+     * `normal` one after it — and after Tab has moved focus — and a handler
+     * that calls `event.stop()` ends the key there.
+     */
+    onKey(handler: (event: KeyEvent) => void, options?: KeyHandlerOptions): Unsubscribe;
+    /** Hear every pointer event, in terminal cells, before any widget does. */
+    onMouse(handler: (event: ScreenMouseEvent) => void): Unsubscribe;
+    private compose;
+}