@promptctl/rich-js 0.26.0 → 0.28.0

package/dist/widgets/text-input.js

@@ -107,7 +107,7 @@ import { Viewport } from "../renderables/viewport.js";
 import { Animation } from "../core/animation.js";
 import { beat } from "../core/easing.js";
 import { Timeline } from "../core/timeline.js";
-import { holdOf, shownAt, stampFrame } from "../core/animation.js";
+import { placed } from "../core/animation.js";
 import { levelOf } from "../core/anchor.js";
 import { ThemedWidget } from "./themed-widget.js";
 import { ink } from "./ink.js";
@@ -244,8 +244,24 @@ function wordSpan(clusters, skipped, taken) {
  * for the next, on a `beat`. A loop, so with its motion taken out it holds lit.
  */
 const CARET_BLINK = Animation.map(beat([0.5, 0.5]), (hold) => hold === 0);
-/** The caret of a frame drawn for no moment — a `print` — which nothing moves: lit, and never changing. */
-const CARET_UNTIMED = { lit: true, hold: { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY } };
+/**
+ * The caret's blink restarted at `from`, as one animation of the frame's
+ * time: `CARET_BLINK` run forward from `from` at and after it, and backward
+ * from it before, so a timeline played backwards also finds the caret lit
+ * just after a key. Each answer is the run the time falls in, bounded at
+ * `from` where the runs meet — early where it must guess, never late. A
+ * function of `from` alone, so the frame hands it its time (`placed`).
+ */
+function caretBlink(from) {
+    const forward = Timeline.run(Timeline.play(from, 1), CARET_BLINK);
+    const backward = Timeline.run(Timeline.play(from, -1), CARET_BLINK);
+    return Animation.of({
+        at: (t) => (t >= from ? forward : backward).at(t),
+        nextChange: (t) => (t >= from ? forward.nextChange(t) : Math.min(backward.nextChange(t), from)),
+        lastChange: (t) => (t >= from ? Math.max(forward.lastChange(t), from) : backward.lastChange(t)),
+        reduced: () => CARET_BLINK.reduced(),
+    });
+}
 let TextInput = (() => {
     let _classSuper = ThemedWidget;
     let _instanceExtraInitializers = [];
@@ -255,9 +271,9 @@ let TextInput = (() => {
     let __cursor_decorators;
     let __cursor_initializers = [];
     let __cursor_extraInitializers = [];
-    let __blinkFrom_decorators;
-    let __blinkFrom_initializers = [];
-    let __blinkFrom_extraInitializers = [];
+    let __blink_decorators;
+    let __blink_initializers = [];
+    let __blink_extraInitializers = [];
     let _placeholder_decorators;
     let _placeholder_initializers = [];
     let _placeholder_extraInitializers = [];
@@ -298,7 +314,7 @@ let TextInput = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             __value_decorators = [observableRef];
             __cursor_decorators = [observableRef];
-            __blinkFrom_decorators = [observableRef];
+            __blink_decorators = [observableRef];
             _placeholder_decorators = [observableRef];
             _indicatorStyleOverride_decorators = [observableRef];
             _cursorStyleOverride_decorators = [observableRef];
@@ -328,7 +344,7 @@ let TextInput = (() => {
             __insertText_decorators = [action];
             __esDecorate(this, null, __value_decorators, { kind: "accessor", name: "_value", static: false, private: false, access: { has: obj => "_value" in obj, get: obj => obj._value, set: (obj, value) => { obj._value = value; } }, metadata: _metadata }, __value_initializers, __value_extraInitializers);
             __esDecorate(this, null, __cursor_decorators, { kind: "accessor", name: "_cursor", static: false, private: false, access: { has: obj => "_cursor" in obj, get: obj => obj._cursor, set: (obj, value) => { obj._cursor = value; } }, metadata: _metadata }, __cursor_initializers, __cursor_extraInitializers);
-            __esDecorate(this, null, __blinkFrom_decorators, { kind: "accessor", name: "_blinkFrom", static: false, private: false, access: { has: obj => "_blinkFrom" in obj, get: obj => obj._blinkFrom, set: (obj, value) => { obj._blinkFrom = value; } }, metadata: _metadata }, __blinkFrom_initializers, __blinkFrom_extraInitializers);
+            __esDecorate(this, null, __blink_decorators, { kind: "accessor", name: "_blink", static: false, private: false, access: { has: obj => "_blink" in obj, get: obj => obj._blink, set: (obj, value) => { obj._blink = value; } }, metadata: _metadata }, __blink_initializers, __blink_extraInitializers);
             __esDecorate(this, null, _placeholder_decorators, { kind: "accessor", name: "placeholder", static: false, private: false, access: { has: obj => "placeholder" in obj, get: obj => obj.placeholder, set: (obj, value) => { obj.placeholder = value; } }, metadata: _metadata }, _placeholder_initializers, _placeholder_extraInitializers);
             __esDecorate(this, null, _indicatorStyleOverride_decorators, { kind: "accessor", name: "indicatorStyleOverride", static: false, private: false, access: { has: obj => "indicatorStyleOverride" in obj, get: obj => obj.indicatorStyleOverride, set: (obj, value) => { obj.indicatorStyleOverride = value; } }, metadata: _metadata }, _indicatorStyleOverride_initializers, _indicatorStyleOverride_extraInitializers);
             __esDecorate(this, null, _cursorStyleOverride_decorators, { kind: "accessor", name: "cursorStyleOverride", static: false, private: false, access: { has: obj => "cursorStyleOverride" in obj, get: obj => obj.cursorStyleOverride, set: (obj, value) => { obj.cursorStyleOverride = value; } }, metadata: _metadata }, _cursorStyleOverride_initializers, _cursorStyleOverride_extraInitializers);
@@ -366,13 +382,12 @@ let TextInput = (() => {
         #_cursor_accessor_storage = (__runInitializers(this, __value_extraInitializers), __runInitializers(this, __cursor_initializers, void 0));
         get _cursor() { return this.#_cursor_accessor_storage; }
         set _cursor(value) { this.#_cursor_accessor_storage = value; }
-        #_blinkFrom_accessor_storage = (__runInitializers(this, __cursor_extraInitializers), __runInitializers(this, __blinkFrom_initializers, 0));
-        // When the field last took focus, a click, or a key it handled, on the
-        // frame's clock (each event's `time`): where the caret's blink restarts.
-        // The blink itself is a function of this and the time a frame is drawn
-        // for, so nothing about it is kept.
-        get _blinkFrom() { return this.#_blinkFrom_accessor_storage; }
-        set _blinkFrom(value) { this.#_blinkFrom_accessor_storage = value; }
+        #_blink_accessor_storage = (__runInitializers(this, __cursor_extraInitializers), __runInitializers(this, __blink_initializers, caretBlink(0)));
+        // The caret's blink, restarted (`caretBlink`) when the field last took
+        // focus, a click, or a key it handled, at that event's `time` on the
+        // frame's clock. Built at the event, so a frame only reads it.
+        get _blink() { return this.#_blink_accessor_storage; }
+        set _blink(value) { this.#_blink_accessor_storage = value; }
         // [LAW:single-enforcer] Every write to either half of the pair passes
         // `graphemeBoundary`, so the cursor is a cluster boundary inside `value`
         // whoever set it last — a caller replacing `value`, a click, an insert that
@@ -388,7 +403,7 @@ let TextInput = (() => {
         }
         get cursorPosition() { return this._cursor; }
         set cursorPosition(p) { this._cursor = graphemeBoundary(this._value, p); }
-        #placeholder_accessor_storage = (__runInitializers(this, __blinkFrom_extraInitializers), __runInitializers(this, _placeholder_initializers, void 0));
+        #placeholder_accessor_storage = (__runInitializers(this, __blink_extraInitializers), __runInitializers(this, _placeholder_initializers, void 0));
         get placeholder() { return this.#placeholder_accessor_storage; }
         set placeholder(value) { this.#placeholder_accessor_storage = value; }
         _maxLength = __runInitializers(this, _placeholder_extraInitializers);
@@ -468,7 +483,7 @@ let TextInput = (() => {
             this._edit(event);
             if (!event.stopped)
                 return;
-            this._blinkFrom = event.time;
+            this._blink = caretBlink(event.time);
             // An edit on the cursor's row moves no followed range, so the row is
             // brought into view here too: typing after the wheel scrolled away scrolls
             // back. The rows are the edited value's, at the width last drawn.
@@ -479,7 +494,7 @@ let TextInput = (() => {
         }
         handleFocus(event) {
             super.handleFocus(event);
-            this._blinkFrom = event.time;
+            this._blink = caretBlink(event.time);
         }
         _edit(event) {
             if (this.disabled)
@@ -653,7 +668,7 @@ let TextInput = (() => {
                 return;
             if (event.type !== "mouse_down")
                 return;
-            this._blinkFrom = event.time;
+            this._blink = caretBlink(event.time);
             // [LAW:no-silent-failure] Every cell the field draws carries its frame's
             // layout, so a press without one did not come off a frame it drew.
             const layout = layoutOn(event.cell);
@@ -1091,20 +1106,14 @@ let TextInput = (() => {
             return { lines: withArrows, layout: { drawn, kind: "rows", rows: visualRows, offset } };
         }
         // The caret's cell for the frame `options` draws: the blink restarted at the
-        // last touch, sampled at the frame's time (`shownAt`, so under reduced
-        // motion it holds lit). It runs away from the restart in either direction
-        // of time, so a timeline played backwards also finds it lit just after a
-        // key. Lit, the cell is the cursor's; dark, it is drawn as the
-        // text around it, since the cursor is a colour pair and no attribute hides
-        // it. The cell says when it next flips, which is when a host draws again.
+        // last touch, placed as every animation is (`placed`), so it draws at the
+        // frame's time, holds lit under reduced motion, and the cell says when it
+        // next flips, which is when a host draws again. A print, drawn for no
+        // moment, draws it at 0 like any placed animation. Lit, the cell is the
+        // cursor's; dark, it is drawn as the text around it, since the cursor is a
+        // colour pair and no attribute hides it.
         _caret(at, cursorStyle, contentStyle, options) {
-            const { frame } = options;
-            const blink = (time) => {
-                const shown = shownAt(Timeline.run(Timeline.play(this._blinkFrom, time < this._blinkFrom ? -1 : 1), CARET_BLINK), time, options);
-                return { lit: shown.value, hold: holdOf(shown, time) };
-            };
-            const { lit, hold } = frame === undefined ? CARET_UNTIMED : blink(frame.time);
-            return stampFrame([new Segment(at, lit ? cursorStyle : contentStyle)], hold);
+            return placed(this._blink, options, (lit) => [new Segment(at, lit ? cursorStyle : contentStyle)]);
         }
         // Whether `rows` visual rows draw a scroll arrow in the last cell of a row.
         _drawsArrows(rows) {

package/dist/widgets/themed-widget.js

@@ -80,10 +80,10 @@ let ThemedWidget = (() => {
             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.
+        // palette's disabled 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");
+            return ink(this.theme, "foreground-disabled", "background");
         }
     };
 })();

package/dist/widgets/toggle.d.ts

@@ -33,7 +33,7 @@ export declare class Toggle extends ThemedWidget {
     constructor(options: ToggleOptions);
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
-    protected draw(_options: RenderOptions): Iterable<Segment>;
+    protected draw(options: RenderOptions): Iterable<Segment>;
     measure(_options: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/widgets/toggle.js

@@ -44,9 +44,9 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
+import { labelled } from "../core/orient.js";
 import { action } from "mobx";
 import { observableRef } from "./observable.js";
-import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { cellLen } from "../core/cells.js";
 import { ThemedWidget } from "./themed-widget.js";
@@ -137,16 +137,16 @@ let Toggle = (() => {
             }
         }
         // --- Rendering ---
-        draw(_options) {
+        draw(options) {
             // Both indicators are exactly 5 cells: "[ON] " and "[OFF]".
             const indicator = this.on ? "[ON] " : "[OFF]";
-            const text = `${indicator} ${this.label}`;
+            const drawn = (style) => labelled(`${indicator} `, this.label, "", style, options.textOrder);
             if (this.disabled) {
-                return [new Segment(text, new Style(this.disabledInk))];
+                return drawn(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 }))];
+            return drawn(new Style({ ...colors, underline: this.focused }));
         }
         measure(_options) {
             // [LAW:one-source-of-truth] cellLen — see button.ts.

package/dist/widgets/types.d.ts

@@ -5,7 +5,7 @@
  * 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 { HostFrame, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import type { Segment } from "../core/segment.js";
 import type { Anchor } from "../core/anchor.js";
 import type { Unsubscribe } from "../core/subscription.js";
@@ -71,6 +71,6 @@ export interface FocusManager {
 export interface FrameSource {
     readonly focusManager: FocusManager;
     readonly frame: readonly (readonly Segment[])[];
-    readonly frameTime: number;
+    frameNow(): HostFrame;
     refresh(): void;
 }

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

@@ -26,7 +26,7 @@
  * hear the input.
  */
 import { Segment } from "../core/segment.js";
-import type { FrameHost, Presence } from "../core/protocol.js";
+import type { HostFrame, FrameHost, Presence } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import type { Clock, FrameRate } from "../core/clock.js";
 import type { Timeline } from "../core/timeline.js";
@@ -72,8 +72,8 @@ export declare class WidgetApp implements FrameSource, FrameHost {
     private get widgets();
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
-    /** The time a frame drawn now is drawn for, as `App.frameTime` reads it. */
-    get frameTime(): number;
+    /** The frame this app draws now (`FrameHost`): the App's time, on a frame this app is the host of, as its frames say. */
+    frameNow(): HostFrame;
     /**
      * Take the terminal, paint the first frame, and route input to its widgets
      * until the app stops — `App.run`, with the input.

package/dist/widgets/widget-app.js

@@ -50,7 +50,7 @@ export class WidgetApp {
         // The view is drawn inside `compose`, where what it reads is tracked —
         // a function view asked there too — and when it changes is its own to
         // say, as it would be to the App.
-        // Its frames are its own, drawn for its `frameTime`: what draws in them
+        // Its frames are its own, drawn for its `frameNow()`: what draws in them
         // is told this app is the host, not the App it paints through, so
         // `drawnBy: widgetApp` names the host its frames carry.
         this.app = new App({
@@ -65,7 +65,7 @@ export class WidgetApp {
                 const owners = ownersOn(this.app.frame);
                 return this.widgets.filter((widget) => owners.has(widget));
             },
-            frameTime: () => this.frameTime,
+            frameTime: () => this.frameNow().time,
         });
         this.focusManager = this.focus;
         this.router = new EventRouter({ source: this, focusOnClick });
@@ -118,9 +118,9 @@ export class WidgetApp {
     get frame() {
         return this.app.frame;
     }
-    /** The time a frame drawn now is drawn for, as `App.frameTime` reads it. */
-    get frameTime() {
-        return this.app.frameTime;
+    /** The frame this app draws now (`FrameHost`): the App's time, on a frame this app is the host of, as its frames say. */
+    frameNow() {
+        return { time: this.app.frameNow().time, host: this };
     }
     /**
      * Take the terminal, paint the first frame, and route input to its widgets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",
@@ -89,6 +89,7 @@
     "template-bindings": "node scripts/build-demos.ts && node dist-demo/examples/rich-template-bindings/main.js",
     "themes-and-color-studio": "node scripts/build-demos.ts && node dist-demo/examples/themes-and-color-studio/node.js",
     "terminal-host": "node scripts/build-demos.ts && node dist-demo/examples/terminal-host/main.js",
+    "terminal-colors": "node scripts/build-demos.ts && node dist-demo/examples/terminal-colors/index.js",
     "test:demos": "playwright test"
   },
   "keywords": [
@@ -123,14 +124,14 @@
     "@codemirror/view": "^6.43.13",
     "@lezer/highlight": "^1.2.5",
     "@playwright/test": "^1.63.0",
-    "@promptctl/go-template-js": "^0.10.0",
+    "@promptctl/go-template-js": "0.12.0",
     "@types/markdown-it": "^14.2.0",
     "@types/node": "^26.5.1",
     "@types/semver": "^7.8.0",
     "@xterm/headless": "^6.0.0",
     "markdown-it": "^14.3.2",
     "markdown-it-container": "^4.0.0",
-    "mobx": "^7.0.3",
+    "mobx": "7.0.3",
     "node-inspect-extracted": "^3.3.3",
     "semver": "^7.8.5",
     "strip-ansi": "^7.2.0",
@@ -141,7 +142,7 @@
     "vitest": "^5.0.0"
   },
   "peerDependencies": {
-    "@promptctl/go-template-js": "^0.10.0",
+    "@promptctl/go-template-js": "^0.12.0",
     "mobx": "^7.0.3"
   },
   "peerDependenciesMeta": {