@promptctl/rich-js 0.18.1 → 0.19.0

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

@@ -13,7 +13,7 @@
 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 { ThemedWidget } from "./themed-widget.js";
 import type { KeyEvent, WidgetMouseEvent } from "./types.js";
 export type ToggleVariant = "default" | "primary" | "success" | "warning" | "danger";
 export interface ToggleOptions {
@@ -24,15 +24,13 @@ export interface ToggleOptions {
     theme?: TerminalTheme;
     variant?: ToggleVariant;
 }
-export declare class Toggle extends WidgetBase {
+export declare class Toggle extends ThemedWidget {
     readonly id: string;
     readonly focusable = true;
     accessor label: string;
     accessor on: boolean;
     accessor variant: ToggleVariant;
-    private accessor _theme;
     constructor(options: ToggleOptions);
-    setTheme(theme: TerminalTheme): void;
     handleKey(event: KeyEvent): void;
     handleMouse(event: WidgetMouseEvent): void;
     protected draw(_options: RenderOptions): Iterable<Segment>;
@@ -40,5 +38,4 @@ export declare class Toggle extends WidgetBase {
         minimum: number;
         maximum: number;
     };
-    private resolvePalette;
 }

package/dist/widgets/toggle.js

@@ -47,10 +47,9 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 import { observable, action, observableRef } from "mobx";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
-import { ColorSpec } from "../core/color.js";
 import { cellLen } from "../core/cells.js";
-import { DEFAULT_TERMINAL_THEME } from "../themes/terminalThemes.js";
-import { WidgetBase } from "./widget-base.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
@@ -64,7 +63,7 @@ const VARIANT_KEYS = {
     danger: { onBg: "error", onFg: "on-error", offBg: "error-muted", offFg: "text-error" },
 };
 let Toggle = (() => {
-    let _classSuper = WidgetBase;
+    let _classSuper = ThemedWidget;
     let _instanceExtraInitializers = [];
     let _label_decorators;
     let _label_initializers = [];
@@ -75,10 +74,6 @@ let Toggle = (() => {
     let _variant_decorators;
     let _variant_initializers = [];
     let _variant_extraInitializers = [];
-    let __theme_decorators;
-    let __theme_initializers = [];
-    let __theme_extraInitializers = [];
-    let _setTheme_decorators;
     let _handleKey_decorators;
     let _handleMouse_decorators;
     return class Toggle extends _classSuper {
@@ -87,15 +82,11 @@ let Toggle = (() => {
             _label_decorators = [observable];
             _on_decorators = [observable];
             _variant_decorators = [observableRef];
-            __theme_decorators = [observableRef];
-            _setTheme_decorators = [action];
             _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, __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);
             __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 });
@@ -111,22 +102,15 @@ let Toggle = (() => {
         #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; }
-        #_theme_accessor_storage = (__runInitializers(this, _variant_extraInitializers), __runInitializers(this, __theme_initializers, void 0));
-        // [LAW:types-are-the-program] @observableRef so setTheme() triggers a
-        // re-render — see slider.ts.
-        get _theme() { return this.#_theme_accessor_storage; }
-        set _theme(value) { this.#_theme_accessor_storage = value; }
         constructor(options) {
-            super();
-            __runInitializers(this, __theme_extraInitializers);
+            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;
-            this._theme = options.theme ?? DEFAULT_TERMINAL_THEME;
         }
-        setTheme(theme) { this._theme = theme; }
         // --- Event handlers ---
         handleKey(event) {
             if (this.disabled)
@@ -157,24 +141,17 @@ let Toggle = (() => {
             const indicator = this.on ? "[ON] " : "[OFF]";
             const text = `${indicator} ${this.label}`;
             if (this.disabled) {
-                return [new Segment(text, new Style({ color: "#666666", bgcolor: "#333333", dim: true }))];
+                return [new Segment(text, new Style(this.disabledInk))];
             }
             const keys = VARIANT_KEYS[this.variant];
-            const fg = this.resolvePalette(this.on ? keys.onFg : keys.offFg);
-            const bg = this.resolvePalette(this.on ? keys.onBg : keys.offBg);
-            return [new Segment(text, new Style({ color: fg, bgcolor: bg, underline: this.focused }))];
+            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 };
         }
-        // --- Palette resolution ---
-        resolvePalette(key) {
-            const rgba = this._theme.palette.get(key);
-            // [LAW:no-defensive-null-guards] palette must contain all keys; missing is a construction bug.
-            return ColorSpec.fromRgba(rgba);
-        }
     };
 })();
 export { Toggle };

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

@@ -51,6 +51,8 @@ export declare class WidgetApp implements FrameSource {
      */
     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

package/dist/widgets/widget-app.js

@@ -42,8 +42,10 @@ export class WidgetApp {
     constructor(options) {
         const { view } = options;
         this.reaction = new Reaction("WidgetApp", () => this.app.refresh());
-        const root = { render: (renderOptions) => this.compose(view, renderOptions) };
-        this.app = new App({ ...options, view: () => root });
+        this.app = new App({
+            ...options,
+            view: (t) => ({ render: (renderOptions) => this.compose(() => view(t), renderOptions) }),
+        });
         this.focus = new DefaultFocusManager(() => {
             const owners = ownersOn(this.app.frame);
             return this.drawn.filter((widget) => owners.has(widget));
@@ -102,6 +104,10 @@ export class WidgetApp {
     suspend() {
         return this.app.suspend();
     }
+    /** Paint at the app's rate until the returned function is called, as `App.animate` does. */
+    animate() {
+        return this.app.animate();
+    }
     /**
      * 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
@@ -176,12 +182,13 @@ function paintOverlay(lines, widget, options) {
     const at = footprintOf(lines, widget);
     if (!at)
         return;
-    // An overlay floats over the frame; no region holds it.
-    const overlay = widget.renderOverlay({ ...options, height: undefined });
+    // An overlay floats over the frame; no region holds it, and the cells right
+    // of its column are all it can reach.
+    const width = Math.max(0, options.maxWidth - at.x);
+    const overlay = widget.renderOverlay({ ...options, maxWidth: width, height: undefined });
     if (overlay === null)
         return;
-    const width = Math.max(0, options.maxWidth - at.x);
-    const rows = Segment.anchorLines(Segment.splitLines(overlay), widget, at.rows).map((line) => Segment.adjustLineLength(line, width, undefined, false));
+    const rows = Segment.anchorLines(Segment.splitLines(Segment.cropLines(overlay, width)), widget, at.rows);
     paintLines(lines, rows, at.x, at.y + at.rows);
 }
 // Paint `rows` into `lines` with its top-left cell at (x, y), growing `lines`

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

@@ -8,6 +8,7 @@
  * makeObservable call and subclasses add observables the same way.
  */
 import { Segment } from "../core/segment.js";
+import { type Style } from "../core/style.js";
 import type { RenderOptions } from "../core/protocol.js";
 import type { InteractiveWidget, KeyEvent, WidgetMouseEvent, WidgetFocusEvent } from "./types.js";
 import type { Unsubscribe } from "../core/subscription.js";
@@ -32,6 +33,7 @@ export declare abstract class WidgetBase implements InteractiveWidget {
     protected emitChange(): void;
     protected emitSubmit(): void;
     render(options: RenderOptions): Iterable<Segment>;
+    protected get ground(): Style;
     protected abstract draw(options: RenderOptions): Iterable<Segment>;
     abstract measure(options: RenderOptions): {
         minimum: number;

package/dist/widgets/widget-base.js

@@ -43,6 +43,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 };
 import { observable, action } from "mobx";
 import { Segment } from "../core/segment.js";
+import { NULL_STYLE } from "../core/style.js";
 let WidgetBase = (() => {
     let _instanceExtraInitializers = [];
     let _focused_decorators;
@@ -150,16 +151,22 @@ let WidgetBase = (() => {
         // anchor, so stamping has to follow every text layout `draw` does.
         // Every row is padded to the widest, so the widget owns its whole rectangle
         // and a click past the end of a short row still reaches it; every row ends
-        // in a newline, so a blank last row survives the next `splitLines`.
+        // in a newline, so a blank last row survives the next `splitLines`. The
+        // padding stands on `ground`, whatever the widget draws its own cells on.
         // Reporting itself before it draws is what puts a widget ahead of the
         // widgets nested in it in document order — the order focus traverses.
         render(options) {
             options.onDraw?.(this);
             const drawn = Segment.splitLines(this.draw(options));
             const [width] = Segment.getShape(drawn);
-            const lines = Segment.anchorLines(drawn.map((line) => Segment.adjustLineLength(line, width)), this);
+            const lines = Segment.anchorLines(drawn.map((line) => Segment.adjustLineLength(line, width, this.ground)), this);
             return lines.flatMap((line) => [...line, Segment.line()]);
         }
+        // What a padded row stands on. None by default: the padding shows whatever
+        // the widget is drawn over, as the cells of content it did not draw do.
+        get ground() {
+            return NULL_STYLE;
+        }
     };
 })();
 export { WidgetBase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",
@@ -70,6 +70,7 @@
     "demo:build": "tsc -p tsconfig.demo.json",
     "sessions": "tsc -p tsconfig.demo.json && node dist-demo/examples/claude-sessions/index.js",
     "strip": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-strip/index.js",
+    "effects-feel": "tsc -p tsconfig.demo.json && node dist-demo/examples/effects-feel/index.js",
     "viewport": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-viewport/index.js",
     "markup-plugins": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-markup-plugins/index.js",
     "demo-inputs": "tsc -p tsconfig.demo.json && node dist-demo/examples/rich-config/index.js",
@@ -100,16 +101,25 @@
     "node": ">=20"
   },
   "devDependencies": {
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.13",
+    "@lezer/highlight": "^1.2.5",
     "@playwright/test": "^1.63.0",
     "@promptctl/go-template-js": "^0.10.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",
+    "node-inspect-extracted": "^3.3.3",
     "semver": "^7.8.5",
     "strip-ansi": "^7.2.0",
+    "sucrase": "^3.35.1",
     "typescript": "^6.0.3",
     "vite": "^8.3.0",
     "vitepress": "^1.6.4",