@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/strip.d.ts

@@ -27,7 +27,7 @@
  */
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import { type Renderable, type RenderOptions } from "./protocol.js";
+import { type Measurable, type Renderable, type RenderOptions } from "./protocol.js";
 /**
  * Items in a `Strip` expose their per-edge style so joiners can paint the
  * transition glyph at each boundary.
@@ -52,90 +52,132 @@ export interface Joiner<T extends StyledRenderable = StyledRenderable> {
      */
     join(left: T | null, right: T | null): Renderable;
 }
-export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable {
+export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
     readonly items: readonly T[];
     readonly joiner: Joiner<T>;
     constructor(items: readonly T[], joiner: Joiner<T>);
     render(options: RenderOptions): Iterable<Segment>;
+    /**
+     * [LAW:one-source-of-truth] The width of the one row it draws, and that is
+     * both bounds: the row never wraps and no item is offered less than the whole
+     * width, so there is no narrower strip to report as a minimum. Read off the
+     * drawing rather than summed from the items' measurements, which describe
+     * how an item could be drawn, not how the walk draws it.
+     */
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}
+/**
+ * A colour a joiner's cell is drawn in. Each variant names where the colour
+ * comes from when the join is drawn:
+ *   • an `edge` — a neighbour's ground (`bg`) or text (`fg`) at the column
+ *     facing the join, read through `StyledRenderable.edgeStyle`;
+ *   • a `role` — a style name, resolved against the render's theme, whose
+ *     foreground colour is the colour;
+ *   • a `mix` — two colours blended at `t` (0 is the first, 1 the second).
+ */
+export type Paint = {
+    readonly edge: "left" | "right";
+    readonly part: "bg" | "fg";
+} | {
+    readonly role: string;
+} | {
+    readonly mix: readonly [Paint, Paint, number];
+};
+/**
+ * A `Paint`, or `"ground"`: the terminal's own background, whose colour nobody
+ * knows. That is why it is never mixed (`Paint` excludes it), and why a cell
+ * may put it on one side only. As a cell's `fg` it is drawn in reverse video —
+ * the glyph's ink shows the terminal's background through a cell filled with
+ * the `bg` colour — so an inverted shape is the same glyph, never a glyph of
+ * its own.
+ */
+export type CellColor = Paint | "ground";
+/**
+ * One styled run of a join. A `oneOf` glyph is a set any member of which may
+ * stand in the cell; every member has the same width, because consumers
+ * measure a join by rendering it.
+ */
+export interface JoinCell {
+    readonly glyph: string | {
+        readonly oneOf: readonly string[];
+    };
+    readonly fg: CellColor;
+    readonly bg: CellColor;
 }
 /**
- * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
- * arrow between them to be seen. Below it the arrow is drawn in a colour the
- * eye cannot tell from its own background, so the joiner draws the divider
+ * The cells a joiner draws at each kind of join:
+ *   • `seam` — between two neighbours;
+ *   • `divider` — in the seam's place where the two grounds are drawn as one
+ *     colour (see `SEAM_MIN_DELTA_E`), so the seam would vanish into them;
+ *     the same width as `seam`;
+ *   • `lead` — where a run is entered from nothing: the strip's start, or a
+ *     neighbour with no ground for the seam to paint. It cannot name `left`;
+ *   • `tail` — where a run leaves into nothing. It cannot name `right`.
+ */
+export interface JoinShape {
+    readonly seam: readonly JoinCell[];
+    readonly divider: readonly JoinCell[];
+    readonly lead: readonly JoinCell[];
+    readonly tail: readonly JoinCell[];
+}
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for a seam drawn
+ * between them to be seen. Below it the seam is drawn in a colour the eye
+ * cannot tell from its own background, so the joiner draws the divider
  * instead. Twice the ~.02 threshold of a visible difference, because a seam is
  * one cell wide.
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
-export interface PowerlineJoinerOptions {
-    /** Glyph for every join between two coloured items. */
-    glyph: string;
-    /**
-     * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
-     * in the left item's text colour — the arrow itself would vanish into the
-     * shared background.
-     */
-    divider: string;
-    /**
-     * Glyph for every join a coloured item is entered from nothing — the strip's
-     * start, or a colourless left neighbour — painted in the right item's
-     * background. `""` begins a coloured run flat.
-     */
-    lead: string;
-    /**
-     * Glyph for every join a coloured item leaves into nothing — the strip's end,
-     * or a colourless right neighbour — painted in the left item's background.
-     * `""` ends a coloured run flat.
-     */
-    tail: string;
-}
 /**
- * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
- * led by U+E0D7 (Nerd Fonts ple-left_hard_divider_inverse, the right-arrow's
- * inverse) and tailed by the arrow itself. The lead leaves empty a triangle
- * whose base is its cell's left edge and whose point touches the first item, so
- * the run opens notched — as if an arrow before it pointed in — rather than
- * with a shape pointing out. The notch is the terminal's own background showing
- * through, never a colour painted to imitate it, so it matches under a
- * translucent terminal background too. The lead is a Powerline Extra glyph: a
- * classic powerline font lacks it.
+ * The one joiner: what it draws at each join is the `JoinShape` it is given,
+ * so a new joiner is a value, never a class.
+ *
+ * Which part a join draws is read off its two neighbours. A neighbour is
+ * missing at the strip's ends, and counts as missing — an endpoint — when the
+ * shape paints with its ground anywhere and it has none to paint. With both present the
+ * join is the seam, or the divider where the two grounds are drawn as one
+ * colour at `options.colorSystem`; with only the right, the lead; with only
+ * the left, the tail; with neither, nothing.
+ *
+ * `ascii` is the shape an ASCII-only output draws instead, whole.
  */
-export declare const POWERLINE_JOINER_GLYPHS: Readonly<PowerlineJoinerOptions>;
-export declare class PowerlineJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _glyphs;
-    constructor(options?: PowerlineJoinerOptions);
-    join(left: T | null, right: T | null): Renderable;
-}
-export interface CapsuleJoinerOptions {
-    /** Left-cap glyph (default: U+E0B6, powerline rounded left). */
-    left?: string;
-    /** Right-cap glyph (default: U+E0B4, powerline rounded right). */
-    right?: string;
-    /** Separator inserted between adjacent capsules in the middle position. */
-    separator?: string;
-}
-export declare class CapsuleJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _caps;
-    private readonly _separator;
-    constructor(options?: CapsuleJoinerOptions);
-    _emit(left: T | null, right: T | null, options: RenderOptions): Iterable<Segment>;
-    join(left: T | null, right: T | null): Renderable;
-}
-export interface PlainJoinerOptions {
-    separator?: string;
-    style?: Style;
-}
-export declare class PlainJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _separator;
-    private readonly _style;
-    constructor(options?: PlainJoinerOptions);
-    join(left: T | null, right: T | null): Renderable;
-}
-export interface GradientJoinerOptions {
-    /** Number of cells between adjacent items (default: 4). */
-    steps?: number;
-}
-export declare class GradientJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _steps;
-    constructor(options?: GradientJoinerOptions);
+export declare class CellJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
+    readonly shape: JoinShape;
+    readonly ascii: JoinShape;
+    private readonly _forms;
+    constructor(shape: JoinShape, ascii: JoinShape);
     join(left: T | null, right: T | null): Renderable;
 }
+/**
+ * The powerline joiner: U+E0B0 (right-arrow) in the left ground over the
+ * right, divided by U+E0B1 (thin right-arrow) in the left item's text. The
+ * lead is the arrow with the left ground replaced by the terminal's — drawn
+ * in reverse video it leaves a notch whose base is the cell's left edge, inked
+ * in the terminal's background colour. That ink is opaque, so under a
+ * translucent terminal the notch does not let what is behind it through. The
+ * tail is the arrow over the terminal's ground.
+ * ASCII draws `>` everywhere and begins each run flat.
+ */
+export declare const POWERLINE_JOINER: CellJoiner<StyledRenderable>;
+/**
+ * Rounded pills: each run opened by U+E0B6 and closed by U+E0B4, both in its
+ * ground over the terminal's, a space between pills. ASCII draws `(` and `)`.
+ */
+export declare const CAPSULE_JOINER: CellJoiner<StyledRenderable>;
+/**
+ * ` | ` between every pair of items, in the theme's `strip.separator` colour;
+ * nothing at the ends. Its shape names no neighbour, so it joins items with no
+ * ground too.
+ */
+export declare const PLAIN_JOINER: CellJoiner<StyledRenderable>;
+/**
+ * A ramp of `steps` cells from the left ground to the right. Each cell is the
+ * half block U+258C, ink on its left half and ground on its right, so it
+ * carries two samples; ASCII draws a space, keeping the grounds alone. Nothing
+ * at the ends, or beside a neighbour with no ground — there is no colour to
+ * ramp toward.
+ */
+export declare function gradientJoiner(steps?: number): CellJoiner;