@promptctl/rich-js 0.19.0 → 0.21.0

package/dist/core/strip.d.ts

@@ -25,6 +25,7 @@
  * single-style invariant on the cell type — the terminal supports per-column
  * styling, so the cell type does too.
  */
+import type { Anchor } from "./anchor.js";
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
 import { type Measurable, type Renderable, type RenderOptions } from "./protocol.js";
@@ -44,14 +45,58 @@ import { type Measurable, type Renderable, type RenderOptions } from "./protocol
 export interface StyledRenderable extends Renderable {
     edgeStyle(side: "left" | "right", options: RenderOptions): Style;
 }
+/**
+ * Where a join sits in its strip. `index` counts joins from the strip's start:
+ * the join before item `i` is `i`, and the end after the last of `n` items is
+ * `n`. It names the seam, not the line it lands on, so where a `FlexStrip`
+ * wraps, the end cap and the next line's lead both carry the index of the seam
+ * the wrap replaced — and every seam that survives a wrap keeps its own.
+ */
+export interface JoinContext {
+    readonly index: number;
+}
 export interface Joiner<T extends StyledRenderable = StyledRenderable> {
     /**
      * `left === null` marks the start endpoint; `right === null` marks the end
      * endpoint. The joiner decides what an endpoint looks like — typically
      * fg-only with no bg so the strip blends into the terminal background.
      */
-    join(left: T | null, right: T | null): Renderable;
+    join(left: T | null, right: T | null, context: JoinContext): Renderable;
 }
+/**
+ * The owner every cell a strip's joiner draws is stamped with
+ * (`Segment.anchorLines`), whatever the joiner: a seam is told by what drew
+ * it, never by its glyph, which an ASCII joiner draws otherwise and a lead may
+ * not draw at all. An effect reads it to leave a seam out of the words it
+ * keeps legible (`drawnOf`, `../renderables/effect.ts`).
+ *
+ * Inside it, every cell a `CellJoiner` draws names whose colour each of its
+ * two sides shows (`colorsOwnedBy`). One seam cell can show two neighbours —
+ * a powerline arrow is inked in the fill it points out of, over the fill it
+ * points into — so a cell has no single owner; each side has one.
+ */
+export declare const JOIN: object;
+/**
+ * Which of a cell's two colours on screen are `owner`'s: both, for a cell
+ * `owner` drew, itself or through an owner nested in its output; for a cell a
+ * `CellJoiner` drew, the sides shown in `owner`'s colour.
+ */
+export declare function colorsOwnedBy(anchor: Anchor | undefined, owner: object): {
+    readonly fg: boolean;
+    readonly bg: boolean;
+};
+/**
+ * [LAW:single-enforcer] What `joiner` draws at one join, every cell stamped
+ * as `JOIN`'s: the one way `Strip` and `FlexStrip` draw a join.
+ */
+export declare function drawJoin<T extends StyledRenderable>(joiner: Joiner<T>, left: T | null, right: T | null, context: JoinContext): Renderable;
+/**
+ * [LAW:single-enforcer] What `item` draws, every cell stamped as the item's,
+ * so whoever holds the composed row reads which item drew a cell however the
+ * row was laid out or wrapped: the one way `Strip` and `FlexStrip` draw an
+ * item.
+ */
+export declare function drawItem(item: StyledRenderable): Renderable;
 export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
     readonly items: readonly T[];
     readonly joiner: Joiner<T>;
@@ -70,83 +115,121 @@ export declare class Strip<T extends StyledRenderable = StyledRenderable> implem
     };
 }
 /**
- * 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
- * instead. Twice the ~.02 threshold of a visible difference, because a seam is
- * one cell wide.
+ * 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 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;
-}
+export type Paint = {
+    readonly edge: "left" | "right";
+    readonly part: "bg" | "fg";
+} | {
+    readonly role: string;
+} | {
+    readonly mix: readonly [Paint, Paint, number];
+};
 /**
- * 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.
- */
-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;
+ * 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. Which member stands is hashed from the
+ * join's part, its `index` and the cell's place in it, so it holds still from
+ * frame to frame while the items before it do, and differs from seam to seam
+ * even between the same two colours.
+ */
+export interface JoinCell {
+    readonly glyph: string | {
+        readonly oneOf: readonly string[];
+    };
+    readonly fg: CellColor;
+    readonly bg: CellColor;
 }
-export interface GradientJoinerOptions {
-    /** Number of cells between adjacent items (default: 4). */
-    steps?: number;
+/**
+ * The cells a joiner draws at each kind of join:
+ *   • `seam` — between two neighbours;
+ *   • `divider` — in the seam's place where every seam cell's ink is drawn
+ *     indistinct from its own ground (see `SEAM_MIN_DELTA_E`), so the seam
+ *     would vanish;
+ *     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[];
 }
-export declare class GradientJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _steps;
-    constructor(options?: GradientJoinerOptions);
-    join(left: T | null, right: T | null): Renderable;
+/**
+ * The least ΔE_OK a seam cell's ink must differ from its own ground by for the
+ * seam to be seen. Below it the eye cannot tell the ink from the ground,
+ * 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;
+/**
+ * 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 every seam cell's ink is drawn
+ * indistinct from its ground 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 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, { index }: JoinContext): Renderable;
 }
+/**
+ * The bundled joiners, by name. What each draws is `docs/strip.md`'s
+ * "Built-in joiners"; a name from config is read with `joinerNamed`.
+ */
+export declare const JOINERS: Readonly<{
+    powerline: CellJoiner<StyledRenderable>;
+    prism: CellJoiner<StyledRenderable>;
+    slant: CellJoiner<StyledRenderable>;
+    backslant: CellJoiner<StyledRenderable>;
+    flame: CellJoiner<StyledRenderable>;
+    pixel: CellJoiner<StyledRenderable>;
+    ice: CellJoiner<StyledRenderable>;
+    bubble: CellJoiner<StyledRenderable>;
+    capsule: CellJoiner<StyledRenderable>;
+    wrapper: CellJoiner<StyledRenderable>;
+    metro: CellJoiner<StyledRenderable>;
+    stitch: CellJoiner<StyledRenderable>;
+    torn: CellJoiner<StyledRenderable>;
+    plain: CellJoiner<StyledRenderable>;
+}>;
+/**
+ * The bundled joiner `name` names — a name read from config, parsed. Throws on
+ * any other string, naming the ones there are; an own-key test, so `toString`
+ * and the rest of `Object.prototype` are not joiners.
+ */
+export declare function joinerNamed(name: string): CellJoiner;
+/**
+ * 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;