@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/widgets/hit.d.ts

@@ -11,6 +11,7 @@
  * 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 type { Anchor } from "../core/anchor.js";
 import { Segment } from "../core/segment.js";
 import type { Scrollable } from "../core/protocol.js";
 import type { InteractiveWidget } from "./types.js";
@@ -50,6 +51,11 @@ export declare function originOf(frame: readonly (readonly Segment[])[], widget:
  * or through a widget nested in its output.
  */
 export declare function drew(frame: readonly (readonly Segment[])[], widget: InteractiveWidget, x: number, y: number): boolean;
+/**
+ * What `widget`'s own draw stamped on the cell at column `x` of row `y` of
+ * `frame`, inside its stamp, or `undefined` when it drew none of it.
+ */
+export declare function cellOf(frame: readonly (readonly Segment[])[], widget: InteractiveWidget, x: number, y: number): Anchor | undefined;
 /**
  * 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

package/dist/widgets/hit.js

@@ -11,7 +11,7 @@
  * 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 { drawnBy } from "../core/anchor.js";
+import { drawnBy, levelOf } from "../core/anchor.js";
 import { Segment } from "../core/segment.js";
 import { isScrollable } from "../core/protocol.js";
 import { WidgetBase } from "./widget-base.js";
@@ -75,6 +75,13 @@ export function originOf(frame, widget) {
 export function drew(frame, widget, x, y) {
     return drawnBy(Segment.anchorAt(frame, x, y), widget);
 }
+/**
+ * What `widget`'s own draw stamped on the cell at column `x` of row `y` of
+ * `frame`, inside its stamp, or `undefined` when it drew none of it.
+ */
+export function cellOf(frame, widget, x, y) {
+    return levelOf(Segment.anchorAt(frame, x, y), widget)?.inner;
+}
 /**
  * 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

package/dist/widgets/index.d.ts

@@ -4,7 +4,7 @@ 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 type { WidgetAppOptions } from "./widget-app.js";
+export type { WidgetAppOptions, WidgetPresence } from "./widget-app.js";
 export { Button } from "./button.js";
 export type { ButtonVariant, ButtonOptions } from "./button.js";
 export { Checkbox } from "./checkbox.js";

package/dist/widgets/observable.d.ts

@@ -0,0 +1,23 @@
+/**
+ * observable — the widgets' state carrier: mobx's `observableRef` accessor
+ * decorator, refusing a write during a render or measure the widget was not
+ * made in.
+ *
+ * A render changes nothing (`src/core/state.ts`). `State` refuses a write in
+ * its setter; a widget's state is a mobx observable, whose setter is mobx's, so
+ * the refusal is an interceptor every instance registers on each of its
+ * observables as it is made, holding the pass it was made in. `core/` cannot do
+ * this itself: mobx is an optional peer, reachable only through `./widgets`.
+ *
+ * There is no deep `observable`. It turns an array or object into a mobx one
+ * whose contents are written without the interceptor, so a refusal on the
+ * accessor alone would be a refusal of half the writes. A held value is
+ * replaced whole, and the render-purity gate reports one whose type can be
+ * written in place.
+ *
+ * Every observable accessor in `src/widgets/` is declared with this, never
+ * with mobx's own: `test/seam/render-purity.ts` sanctions an accessor
+ * decorated from this module and reports any other as a writable property.
+ */
+/** mobx's `observableRef` (the reference, not its contents), refusing a write during a render or measure. */
+export declare function observableRef<This extends object, Value>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): ClassAccessorDecoratorResult<This, Value>;

package/dist/widgets/observable.js

@@ -0,0 +1,43 @@
+/**
+ * observable — the widgets' state carrier: mobx's `observableRef` accessor
+ * decorator, refusing a write during a render or measure the widget was not
+ * made in.
+ *
+ * A render changes nothing (`src/core/state.ts`). `State` refuses a write in
+ * its setter; a widget's state is a mobx observable, whose setter is mobx's, so
+ * the refusal is an interceptor every instance registers on each of its
+ * observables as it is made, holding the pass it was made in. `core/` cannot do
+ * this itself: mobx is an optional peer, reachable only through `./widgets`.
+ *
+ * There is no deep `observable`. It turns an array or object into a mobx one
+ * whose contents are written without the interceptor, so a refusal on the
+ * accessor alone would be a refusal of half the writes. A held value is
+ * replaced whole, and the render-purity gate reports one whose type can be
+ * written in place.
+ *
+ * Every observable accessor in `src/widgets/` is declared with this, never
+ * with mobx's own: `test/seam/render-purity.ts` sanctions an accessor
+ * decorated from this module and reports any other as a writable property.
+ */
+import { observableRef as mobxObservableRef, intercept } from "mobx";
+import { activePass } from "../core/protocol.js";
+import { refuseRenderWrite } from "../core/state.js";
+/** mobx's accessor decorator, typed as what it returns for an accessor: a `get`, a `set` and an `init`, always all three. */
+const mobxRef = mobxObservableRef;
+/** mobx's `observableRef` (the reference, not its contents), refusing a write during a render or measure. */
+export function observableRef(target, context) {
+    const inner = mobxRef(target, context);
+    return {
+        ...inner,
+        init(value) {
+            const initial = inner.init.call(this, value);
+            const owner = activePass();
+            // [LAW:single-enforcer] The rule is `State`'s, applied by its one enforcer.
+            intercept(this, context.name, (change) => {
+                refuseRenderWrite(owner);
+                return change;
+            });
+            return initial;
+        },
+    };
+}

package/dist/widgets/slider.d.ts

@@ -40,7 +40,7 @@ export declare class Slider extends ThemedWidget {
     accessor max: number;
     accessor step: number;
     accessor width: number;
-    private _dragging;
+    private accessor _dragging;
     constructor(options?: SliderOptions);
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;

package/dist/widgets/slider.js

@@ -51,7 +51,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { observable, action, observableRef } from "mobx";
+import { action } from "mobx";
+import { observableRef } from "./observable.js";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { drawable } from "../core/protocol.js";
@@ -76,17 +77,21 @@ let Slider = (() => {
     let _width_decorators;
     let _width_initializers = [];
     let _width_extraInitializers = [];
+    let __dragging_decorators;
+    let __dragging_initializers = [];
+    let __dragging_extraInitializers = [];
     let _handleKey_decorators;
     let _handleMouse_decorators;
     let _setValue_decorators;
     return class Slider extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _value_decorators = [observable];
+            _value_decorators = [observableRef];
             _min_decorators = [observableRef];
             _max_decorators = [observableRef];
             _step_decorators = [observableRef];
             _width_decorators = [observableRef];
+            __dragging_decorators = [observableRef];
             _handleKey_decorators = [action];
             _handleMouse_decorators = [action];
             _setValue_decorators = [action];
@@ -95,6 +100,7 @@ let Slider = (() => {
             __esDecorate(this, null, _max_decorators, { kind: "accessor", name: "max", static: false, private: false, access: { has: obj => "max" in obj, get: obj => obj.max, set: (obj, value) => { obj.max = value; } }, metadata: _metadata }, _max_initializers, _max_extraInitializers);
             __esDecorate(this, null, _step_decorators, { kind: "accessor", name: "step", static: false, private: false, access: { has: obj => "step" in obj, get: obj => obj.step, set: (obj, value) => { obj.step = value; } }, metadata: _metadata }, _step_initializers, _step_extraInitializers);
             __esDecorate(this, null, _width_decorators, { kind: "accessor", name: "width", static: false, private: false, access: { has: obj => "width" in obj, get: obj => obj.width, set: (obj, value) => { obj.width = value; } }, metadata: _metadata }, _width_initializers, _width_extraInitializers);
+            __esDecorate(this, null, __dragging_decorators, { kind: "accessor", name: "_dragging", static: false, private: false, access: { has: obj => "_dragging" in obj, get: obj => obj._dragging, set: (obj, value) => { obj._dragging = value; } }, metadata: _metadata }, __dragging_initializers, __dragging_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);
             __esDecorate(this, null, _setValue_decorators, { kind: "method", name: "setValue", static: false, private: false, access: { has: obj => "setValue" in obj, get: obj => obj.setValue }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -117,9 +123,12 @@ let Slider = (() => {
         #width_accessor_storage = (__runInitializers(this, _step_extraInitializers), __runInitializers(this, _width_initializers, void 0));
         get width() { return this.#width_accessor_storage; }
         set width(value) { this.#width_accessor_storage = value; }
-        _dragging = (__runInitializers(this, _width_extraInitializers), false);
+        #_dragging_accessor_storage = (__runInitializers(this, _width_extraInitializers), __runInitializers(this, __dragging_initializers, false));
+        get _dragging() { return this.#_dragging_accessor_storage; }
+        set _dragging(value) { this.#_dragging_accessor_storage = value; }
         constructor(options = {}) {
             super(options.theme);
+            __runInitializers(this, __dragging_extraInitializers);
             this.id = options.id ?? `slider-${Math.random().toString(36).slice(2, 8)}`;
             this.min = options.min ?? 0;
             this.max = options.max ?? 100;

package/dist/widgets/static-item.d.ts

@@ -22,7 +22,7 @@ export interface StaticItemOptions {
 export declare class StaticItem extends WidgetBase {
     readonly id: string;
     readonly focusable = false;
-    private readonly renderFn;
+    private readonly body;
     private readonly measureFn;
     constructor(options: StaticItemOptions);
     handleKey(_event: KeyEvent): void;

package/dist/widgets/static-item.js

@@ -11,27 +11,26 @@
  * renderable.
  */
 import { Segment } from "../core/segment.js";
+import { render } from "../core/protocol.js";
 import { WidgetBase } from "./widget-base.js";
 export class StaticItem extends WidgetBase {
     id;
     focusable = false;
-    renderFn;
+    // The body as a renderable either way: a function is one that holds nothing.
+    body;
     measureFn;
     constructor(options) {
         super();
         this.id = options.id;
         const r = options.render;
-        this.renderFn =
-            typeof r === "function"
-                ? (opts) => r(opts)
-                : (opts) => r.render(opts);
+        this.body = typeof r === "function" ? { render: r } : r;
         this.measureFn = options.measure;
     }
     // Static items don't respond to keys. WidgetBase.handleMouse / handleFocus
     // are already no-ops, so we only need to satisfy the abstract handleKey.
     handleKey(_event) { }
     draw(options) {
-        return this.renderFn(options);
+        return render(this.body, options);
     }
     measure(options) {
         if (this.measureFn)
@@ -41,7 +40,7 @@ export class StaticItem extends WidgetBase {
         // values too, not just the "\n" sentinel segment. Walking segments and
         // testing `seg.text === "\n"` miscounts widths for any renderable
         // that emits "a\nb" as a single segment.
-        const segments = Array.from(this.renderFn(options));
+        const segments = Array.from(render(this.body, options));
         const lines = Segment.splitLines(segments);
         let max = 0;
         for (const line of lines) {

package/dist/widgets/text-input.d.ts

@@ -3,10 +3,12 @@
  *
  * Two modes:
  *   - single-line (default): Enter submits; newlines in value are rendered
- *                            as a literal `↵` glyph if they ever appear.
+ *                            as a literal `↵` glyph if they ever appear, and
+ *                            any other glyph of zero cells as `◌`.
  *   - multi-line  (`multiline: true`): Enter inserts a `\n`; `value` may
  *                            contain logical line breaks; Up/Down navigate
  *                            between logical lines preserving column intent.
+ *                            A glyph of zero cells is drawn as `◌` here too.
  *
  * [LAW:dataflow-not-control-flow] cursor and value are observable data; the
  * keymap dispatches to small `@action` mutators that all flow through the
@@ -66,23 +68,25 @@ import { type CellCol, type CodePoint, type CodeUnit } from "../core/cells.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";
+import type { KeyEvent, WidgetFocusEvent, WidgetMouseEvent } from "./types.js";
 /**
  * A soft-wrap strategy. Given one logical line of text and cell-width budgets,
- * return the visual sub-rows that line wraps into. The first sub-row uses
- * `firstWidth` as its capacity; every subsequent (continuation) sub-row uses
- * `continuationWidth` (typically `firstWidth - cellLen(continuationMarker)`).
+ * return the visual sub-rows that line wraps into. The line arrives as the
+ * widget shows it — each glyph of zero cells already its one-cell `◌`, each
+ * glyph of a password its mask — so the budget counts the cells drawn. The
+ * first sub-row uses `firstWidth` as its capacity; every subsequent
+ * (continuation) sub-row uses `continuationWidth` (typically
+ * `firstWidth - cellLen(continuationMarker)`).
  *
- * Each returned row carries:
- *   - `content` — the displayed text for that visual row (the widget prepends
- *     the continuation marker itself; the strategy never includes it).
- *   - `start`   — code-unit offset into the *logical line* where `content`
- *     begins, so the widget can map visual positions back to absolute `value`
- *     offsets for cursor projection.
+ * Each returned row is the stretch `[start, end)` of the line as given that
+ * the row draws; the widget draws the matching stretch of `value` and
+ * prepends the continuation marker itself.
  *
- * [LAW:types-are-the-program] Budget params are `CellCol`; `start` is
- * `CodePoint` (a `CodeUnit` on a code-point boundary) — the type system
- * prevents mixing these integer spaces inside a custom strategy.
+ * [LAW:types-are-the-program] A row names where it falls in the line rather
+ * than carrying text of its own, so it cannot draw anything the line does not
+ * hold. Budget params are `CellCol`; offsets are `CodePoint` (a `CodeUnit` on
+ * a code-point boundary) — the type system prevents mixing these integer
+ * spaces inside a custom strategy.
  *
  * Built-in: `charGreedyWrap` (break at any character at the width limit).
  * Custom: any function matching this signature. Template-aware wrapping
@@ -94,9 +98,10 @@ export type WrapStrategy = (logicalLine: string, budget: {
     continuationWidth: CellCol;
 }) => readonly WrapRow[];
 export interface WrapRow {
-    readonly content: string;
-    /** Code-point offset into the logical line where `content` begins. */
+    /** Offset into the line as given where the row begins. */
     readonly start: CodePoint;
+    /** Offset into the line as given where the row ends, exclusive. */
+    readonly end: CodePoint;
 }
 /**
  * Character-greedy soft wrap. Breaks at any character once `firstWidth`
@@ -106,7 +111,7 @@ export interface WrapRow {
  *
  * Wide characters (CJK, emoji) are treated as atomic: a char that would
  * straddle the budget is moved to the next row rather than split, and one too
- * wide for the whole budget is force-taken — see `cellStepFrom`.
+ * wide for the whole budget is force-taken — see `cellRows`.
  */
 export declare const charGreedyWrap: WrapStrategy;
 export interface TextInputOptions {
@@ -163,10 +168,11 @@ export interface TextInputOptions {
      *     area on the first/last visible row when scroll is possible in that
      *     direction. Fully self-contained — host needs no wiring.
      *   - `"indices"`: the widget suppresses in-content arrows and instead
-     *     publishes `scrollIndicatorText` (e.g. `"[14/102]"`) for the host
-     *     (typically a `Panel`'s `bottomRightAccessory`) to display in the
-     *     border. Useful when the surrounding chrome should carry the
-     *     indicator so widget content area stays untouched.
+     *     answers `scrollIndicatorText(frame)` (e.g. `"[14/102]"`) for a frame
+     *     it is drawn in, which a `Panel`'s `bottomRightAccessory` function
+     *     hands it, to display in the border. Useful when the surrounding
+     *     chrome should carry the indicator so widget content area stays
+     *     untouched.
      *   - `"none"`: no indicator at all.
      */
     scrollIndicator?: "arrows" | "indices" | "none";
@@ -192,6 +198,7 @@ export declare class TextInput extends ThemedWidget {
     readonly focusable = true;
     private accessor _value;
     private accessor _cursor;
+    private accessor _blinkFrom;
     get value(): string;
     set value(v: string);
     get cursorPosition(): CodePoint;
@@ -209,35 +216,23 @@ export declare class TextInput extends ThemedWidget {
     accessor indicatorStyleOverride: Style | undefined;
     accessor cursorStyleOverride: Style | undefined;
     accessor contentStyleOverride: Style | undefined;
-    /**
-     * Last computed visual-row decomposition. Cached at the end of `render()`
-     * so vertical motion (Up/Down) can step row-by-row without re-running the
-     * wrap strategy. Null before the first render — vertical motion falls
-     * back to logical-line motion in that case.
-     *
-     * [LAW:dataflow-not-control-flow] One source of truth for "what does Up
-     * mean right now": the row table the renderer just produced. No parallel
-     * "where would the cursor go" math; both the renderer and the keymap
-     * read from the same array.
-     */
-    private _visualRows;
-    private _preferredColumn;
-    private _killBuffer;
-    private _scrollStart;
-    private _singleLineViewportStart;
-    private _singleLineAsciiOnly;
+    private readonly _preferredColumn;
+    private readonly _killBuffer;
+    private readonly _drawn;
+    private readonly _viewport;
     readonly multiline: boolean;
     constructor(options?: TextInputOptions);
     handleKey(event: KeyEvent): void;
+    handleFocus(event: WidgetFocusEvent): void;
+    private _edit;
     handleMouse(event: WidgetMouseEvent): void;
     setHovered(value: boolean): void;
     moveCharLeft(): void;
     moveCharRight(): void;
     moveLineUp(): void;
     moveLineDown(): void;
+    private _moveLine;
     private _clampColForRow;
-    private _cursorVisualRow;
-    private _cursorVisualCol;
     moveLineStart(): void;
     moveLineEnd(): void;
     moveDocStart(): void;
@@ -257,27 +252,38 @@ export declare class TextInput extends ThemedWidget {
     private _insertText;
     protected get ground(): Style;
     protected draw(options: RenderOptions): Iterable<Segment>;
+    private _shownAs;
     private _shown;
+    private _shownCells;
+    private _offsetAtShownCell;
+    private _singleLine;
+    private _showsPlaceholder;
     private _renderSingleLine;
     private _renderMultiline;
+    private _caret;
+    private _drawsArrows;
     private _emitRowContent;
-    private _computeVisualRows;
-    measure(_options: RenderOptions): {
+    private _rows;
+    measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
     };
     /**
      * `[X/Y]` scroll-position string when there's actually something to
      * scroll, else `undefined`. X is the cursor's 1-indexed visual row; Y is
-     * the total visual row count. Reads cached state populated by the most
-     * recent `render()` — call from a `Panel.bottomRightAccessory` thunk so
-     * it evaluates after content has been rendered for the current frame.
+     * the total visual row count. Hand it a frame this field is drawn in — a
+     * `Panel`'s `bottomRightAccessory` function is handed its body's:
+     *
+     *   bottomRightAccessory: (body) => input.scrollIndicatorText(body)
+     *
+     * It counts the rows that frame laid out, read off the field's own cells, so
+     * it is right on the frame it labels however deep the field sits in it.
      *
      * Returns `undefined` when:
      *   - `scrollIndicator` is not `"indices"`, or
      *   - `maxRows` is unset, or total visual rows ≤ maxRows (nothing to
      *     scroll), or
-     *   - no render has happened yet (cache is empty).
+     *   - `frame` shows none of the field's rows (a width too narrow to draw it).
      */
-    get scrollIndicatorText(): string | undefined;
+    scrollIndicatorText(frame: readonly (readonly Segment[])[]): string | undefined;
 }