@promptctl/rich-js 0.8.0 → 0.10.0

package/README.md

@@ -16,6 +16,25 @@ Works on Linux, macOS, and Windows. Requires Node.js >= 20. ESM-only.
 npm install @promptctl/rich-js
 ```
 
+### Entry points
+
+Most of the library comes from the package name itself — `Console`, `Table`, `Panel`, `Tree`, and everything else in the snippets below. Four areas sit behind package subpaths instead — worth knowing before you go looking for one of them in the main entry point and find nothing there:
+
+| Import from | What lives there | What you install yourself | Why it's separate |
+|---|---|---|---|
+| `@promptctl/rich-js/widgets` | Button, Checkbox, Toggle, TextInput, Dropdown, Slider, and the screen that mounts them | `mobx` | Carries a third-party runtime dependency of its own — MobX, for widget state |
+| `@promptctl/rich-js/template-bindings` | The styling vocabulary as Go-template functions, so styled text can be authored as a template | `@promptctl/go-template-js` | Carries a third-party runtime dependency of its own — the Go-template engine, for parsing and evaluating the templates |
+| `@promptctl/rich-js/host` | `TerminalHost`, `BrowserTerminalHost`, `hostStream` — the seam between rendering and a terminal | Nothing | A program that just wants to write bytes through a host shouldn't pay for the widget set to do it |
+| `@promptctl/rich-js/node/save`, `/node/prompt`, `/node/traceback`, `/node/terminal-host` | File export, readline input, the crash handler, and the node TTY host | Nothing | Each one reads node built-ins, and keeping them off the main entry point is what keeps that entry point browser-safe |
+
+Those two peer dependencies are yours to install — `npm install @promptctl/rich-js` deliberately fetches neither, because a program that prints a table shouldn't acquire a state library or a template engine to do it. Add the ones you need:
+
+```sh
+npm install @promptctl/rich-js mobx @promptctl/go-template-js
+```
+
+Import `@promptctl/rich-js/widgets` without MobX, or `@promptctl/rich-js/template-bindings` without the engine, and the import itself fails, with `ERR_MODULE_NOT_FOUND`. The main entry point is unaffected — every snippet on this page that imports from `@promptctl/rich-js` runs on the plain install.
+
 ## Using the Console
 
 Import and construct a `Console` object:
@@ -145,7 +164,7 @@ await progress.run(async () => {
 For situations where it is hard to calculate progress, use `Status` to display a spinner animation with a message:
 
 ```typescript
-import { Console } from "@promptctl/rich-js";
+import { Console, Status } from "@promptctl/rich-js";
 
 const console = new Console();
 
@@ -268,6 +287,54 @@ installTraceback();
 
 </details>
 
+<details>
+<summary>Interactive Widgets</summary>
+
+Everything above draws once and returns. Widgets stay on screen and respond — a button that highlights under the cursor, a text field with a cursor you can move, a dropdown you filter by typing. They come from the `widgets` subpath and need MobX installed alongside the package (see [Entry points](#entry-points)).
+
+```typescript
+import { Button, TextInput, DefaultScreen, EventRouter } from "@promptctl/rich-js/widgets";
+import { NodeTerminalHost } from "@promptctl/rich-js/node/terminal-host";
+
+const host = new NodeTerminalHost();
+const screen = new DefaultScreen({ host });
+const router = new EventRouter({ screen, host });
+
+const name = new TextInput({ placeholder: "your name" });
+const submit = new Button({ label: "Submit", variant: "primary" });
+
+const quit = (): void => {
+  router.stop();
+  screen.stop();
+  host.write("\n");
+};
+
+submit.onSubmit(() => {
+  quit();
+  host.write(`hello, ${name.value}\n`);
+  process.exit(0);
+});
+
+// Raw mode swallows Ctrl+C, so the app has to handle it itself.
+router.onKey(
+  (event) => {
+    if (event.ctrl && event.key === "c") {
+      quit();
+      process.exit(0);
+    }
+  },
+  { priority: "high" },
+);
+
+screen.mount(name, submit);
+screen.start();
+router.start();
+```
+
+`DefaultScreen` builds a focus manager when you don't pass one, so the `TextInput` has focus before the user touches anything and Tab moves between the two widgets. The screen re-renders through a MobX reaction: change a widget's state and the frame redraws itself, with no explicit repaint call anywhere. See [docs/widgets.md](docs/widgets.md) for the full widget set, key dispatch, layout placements, and how to write your own.
+
+</details>
+
 ## Custom Renderables
 
 All Rich renderables use the `Renderable` protocol. You can implement your own:

package/dist/core/box.d.ts

@@ -1,27 +1,46 @@
 /**
  * Box-drawing character sets for borders and table grids.
+ *
+ * A style is declared as an 8x4 character grid — one line per row a table can
+ * draw, one column per position within that row:
+ *
+ *     ┌─┬┐   top border
+ *     │ ││   header content
+ *     ├─┼┤   header separator
+ *     │ ││   body content
+ *     ├─┼┤   row separator
+ *     ├─┼┤   footer separator
+ *     │ ││   footer content
+ *     └─┴┘   bottom border
+ *
+ * [LAW:one-source-of-truth] The grid is the shape the reference implementation
+ * (Python Rich's `box.py`) publishes these glyphs in, so a constant below can
+ * be diffed against it character for character. The eighteen named fields this
+ * replaced were a second, differently-shaped map of the same territory, and it
+ * had drifted: seven of the nineteen constants carried wrong glyphs, and the
+ * field named `mid` held the reference's line 3 while the reference's `mid_*`
+ * is line 4 — so reading the reference name-for-name swapped a separator for a
+ * content row. Named row fields are gone for that reason; a row is reached by
+ * what it is (`getRow`, `getContentChars`), never by a name that can be
+ * mismatched to a line.
  */
 import { Segment } from "./segment.js";
 import type { Style } from "./style.js";
-export interface BoxChars {
-    topLeft: string;
-    top: string;
-    topDivider: string;
-    topRight: string;
-    headLeft: string;
-    headVertical: string;
-    headRight: string;
-    midLeft: string;
-    mid: string;
-    midVertical: string;
-    midRight: string;
-    bottomLeft: string;
-    bottom: string;
-    bottomDivider: string;
-    bottomRight: string;
+/** A rule spanning the table: the top and bottom borders, and every separator. */
+export interface EdgeChars {
     left: string;
+    horizontal: string;
+    cross: string;
     right: string;
+}
+/**
+ * The verticals framing a row of cells. A content line of the grid has no
+ * horizontal of its own — its fill column is a placeholder the cells occupy.
+ */
+export interface ContentChars {
+    left: string;
     vertical: string;
+    right: string;
 }
 export type RowLevel = "head" | "row" | "foot" | "mid";
 export interface SubstituteOptions {
@@ -29,44 +48,79 @@ export interface SubstituteOptions {
     safe?: boolean;
 }
 export declare class Box {
-    readonly topLeft: string;
-    readonly top: string;
-    readonly topDivider: string;
-    readonly topRight: string;
-    readonly headLeft: string;
-    readonly headVertical: string;
-    readonly headRight: string;
-    readonly midLeft: string;
-    readonly mid: string;
-    readonly midVertical: string;
-    readonly midRight: string;
-    readonly bottomLeft: string;
-    readonly bottom: string;
-    readonly bottomDivider: string;
-    readonly bottomRight: string;
-    readonly left: string;
-    readonly right: string;
-    readonly vertical: string;
-    constructor(chars: BoxChars);
+    readonly top: EdgeChars;
+    readonly bottom: EdgeChars;
+    private readonly grid;
+    private readonly ascii;
+    private readonly headContent;
+    private readonly headSeparator;
+    private readonly bodyContent;
+    private readonly rowSeparator;
+    private readonly footSeparator;
+    private readonly footContent;
+    /**
+     * [LAW:parse-dont-validate] The one crossing between a grid string and box
+     * glyphs. A `Box` cannot exist without eight rows of four characters, so no
+     * consumer below ever re-checks the shape of the data it reads.
+     */
+    constructor(grid: string);
     /**
      * Renders the top border row for given column widths.
      */
     getTop(widths: readonly number[], style?: Style, edge?: boolean): Segment[];
     /**
-     * Renders a separator row.
+     * Renders the separator drawn *above* a row at `level` — the head separator
+     * under the header, the row separator between body rows, the foot separator
+     * above the footer.
      */
     getRow(widths: readonly number[], level: RowLevel, style?: Style, edge?: boolean): Segment[];
+    /**
+     * The verticals that frame a content row at `level` — the counterpart to
+     * `getRow`, which draws the separator between two such rows.
+     */
+    getContentChars(level: RowLevel): ContentChars;
     /**
      * Renders the bottom border row.
      */
     getBottom(widths: readonly number[], style?: Style, edge?: boolean): Segment[];
     /**
-     * Returns a new Box with characters substituted for ASCII or safe alternatives.
-     * asciiOnly: all characters become ASCII (+, -, |)
-     * safe: problematic characters (e.g. rounded corners) replaced with square equivalents
+     * The box to draw with when the platform cannot render this one as written.
+     *
+     * `asciiOnly` gives up a box that spends non-ASCII glyphs for `ASCII`, and
+     * leaves the four already-ASCII styles as they are — a caller that chose
+     * MARKDOWN or ASCII_DOUBLE_HEAD asked for that frame and it is already
+     * drawable, so answering with `ASCII` would trade a frame the terminal
+     * supports for a different one it equally supports. `safe` squares off the
+     * rounded corners a legacy Windows terminal draws as blanks.
      */
     substitute(options?: SubstituteOptions): Box;
     private safeSubstitute;
+    /**
+     * The nearest box that spends no special glyphs on a header — what a table
+     * with `showHeader: false` draws with. A box whose head row already matches
+     * its body is its own answer, so this is the identity for fourteen of the
+     * nineteen shipped styles.
+     *
+     * It stands beside `substitute` rather than joining it because the two ask
+     * unrelated questions: `substitute` asks what the *platform* can draw, this
+     * asks what the *table* contains. Nothing correlates them, so a caller that
+     * wants both wants both, and a shared options bag would only multiply the
+     * combinations either one has to reason about. [LAW:no-mode-explosion]
+     *
+     * [LAW:types-are-the-program] The relation is keyed on the grid, not on
+     * object identity as the reference's dict is. A `Box` is wholly determined by
+     * its grid — that is what the constructor takes and all eight rows derive
+     * from — so two boxes with one grid must answer this alike. Identity keying
+     * would say otherwise the moment a box arrived by any route but the shipped
+     * constant, and `safeSubstitute` above builds exactly such a box: a fresh
+     * instance carrying an unchanged grid.
+     */
+    plainHeaded(): Box;
+    /**
+     * [LAW:dataflow-not-control-flow] Every full-width rule the box can draw is
+     * this one loop; which rule it is arrives as four characters, not a branch.
+     */
+    private getEdge;
     private getRowChars;
 }
 export declare const ASCII: Box;

package/dist/core/box.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../src/core/box.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"box.d.ts","sourceRoot":"","sources":["../../src/core/box.ts"],"names":[],"mappings":"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"}