@promptctl/rich-js 0.15.0 → 0.16.0

package/dist/core/strip.d.ts

@@ -67,7 +67,7 @@ export declare class Strip<T extends StyledRenderable = StyledRenderable> implem
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
 export interface PowerlineJoinerOptions {
-    /** Glyph used for every join. */
+    /** Glyph for every join between two coloured items. */
     glyph: string;
     /**
      * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
@@ -75,12 +75,30 @@ export interface PowerlineJoinerOptions {
      * 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 pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
+/**
+ * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
+ * led by U+E0B2 (left-arrow) and tailed by the arrow itself — so a strip's two
+ * ends are one shape.
+ */
 export declare const POWERLINE_JOINER_GLYPHS: Readonly<PowerlineJoinerOptions>;
 export declare class PowerlineJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
     private readonly _glyph;
     private readonly _divider;
+    private readonly _lead;
+    private readonly _tail;
     constructor(options?: PowerlineJoinerOptions);
     join(left: T | null, right: T | null): Renderable;
 }

package/dist/core/strip.js

@@ -101,6 +101,18 @@ function bgAsFg(edge) {
 function paintableBg(bg) {
     return bg !== undefined && !bg.isDefault ? bg : undefined;
 }
+// A cap or arrow is its cell continuing: that cell's ground as the writer draws
+// it, so a translucent ground is not composited a second time over whatever it
+// enters.
+function drawnGround(bg) {
+    return new Style({ bgcolor: bg }).drawnColors().bgcolor;
+}
+// A cap is its glyph in its cell's ground, and "" is a flat end: no glyph, so
+// no segment — the same output as a join with nothing to paint.
+function* cap(glyph, bg) {
+    if (glyph !== "")
+        yield new Segment(glyph, new Style({ color: drawnGround(bg) }));
+}
 // --- PowerlineJoiner ---
 /**
  * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
@@ -130,27 +142,42 @@ function vanishes(arrow, colorSystem) {
         ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
         : color.number === bgcolor.number;
 }
-/** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
-export const POWERLINE_JOINER_GLYPHS = Object.freeze({ glyph: "\ue0b0", divider: "\ue0b1" });
+/**
+ * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
+ * led by U+E0B2 (left-arrow) and tailed by the arrow itself — so a strip's two
+ * ends are one shape.
+ */
+export const POWERLINE_JOINER_GLYPHS = Object.freeze({
+    glyph: "\ue0b0",
+    divider: "\ue0b1",
+    lead: "\ue0b2",
+    tail: "\ue0b0",
+});
 export class PowerlineJoiner {
     _glyph;
     _divider;
+    _lead;
+    _tail;
     constructor(options = POWERLINE_JOINER_GLYPHS) {
         this._glyph = options.glyph;
         this._divider = options.divider;
+        this._lead = options.lead;
+        this._tail = options.tail;
     }
     join(left, right) {
-        // [LAW:dataflow-not-control-flow] One expression for all three positions
-        // (start cap, mid-join, end cap). The powerline separator is painted in the
-        // LEFT edge's bg — the colour bleeding rightward — over the RIGHT edge's bg.
-        // The endpoints are not control-flow special cases; they are the DATA cases
+        // [LAW:dataflow-not-control-flow] One table for all three positions (start
+        // cap, mid-join, end cap), read off which side has a colour to paint. The
+        // endpoints are not control-flow special cases; they are the DATA cases
         // where a neighbour (hence its bg) is absent:
-        //   • no left bg — the start cap, OR a left item with no background — has no
-        //     colour to bleed, so there is no separator to paint and the join
-        //     yields nothing. (This matches vim-airline / tmux-powerline: a
-        //     colourless arrow is not drawn.)
-        //   • no right bg — the end cap — bleeds the left colour out over the
-        //     terminal background (fg = left bg, no bg).
+        //   • both bgs — the arrow in the LEFT bg (the colour bleeding rightward)
+        //     over the RIGHT bg.
+        //   • left bg only — the end cap, OR a coloured item before a colourless
+        //     one — the tail bleeds the left colour out over the terminal
+        //     background (fg = left bg, no bg).
+        //   • right bg only — the start cap, OR a colourless item before a coloured
+        //     one — the lead: the right colour reaching back over the terminal
+        //     background (fg = right bg, no bg).
+        //   • neither — nothing to paint, so the join yields nothing.
         // Equal REAL bgs still emit: a same-bg seam between two distinct items is a
         // structural boundary, never suppressed. The arrow would be drawn in its own
         // background colour there and vanish, so the seam is the DIVIDER instead, in
@@ -165,17 +192,22 @@ export class PowerlineJoiner {
         // both to undefined so an explicit `… on default` cannot smuggle a separator.
         const glyph = this._glyph;
         const divider = this._divider;
+        const lead = this._lead;
+        const tail = this._tail;
         return deferred(function* (options) {
             const leftEdge = left?.edgeStyle("right", options);
             const leftBg = paintableBg(leftEdge?.bgcolor);
-            if (leftBg === undefined)
-                return;
             const rightBg = paintableBg(right?.edgeStyle("left", options).bgcolor);
-            // The arrow is the left cell continuing: its ground as the writer draws
-            // it, so a translucent ground is not composited a second time over the
-            // right one.
-            const leftDrawn = new Style({ bgcolor: leftBg }).drawnColors().bgcolor;
-            const arrow = new Style({ color: leftDrawn, bgcolor: rightBg });
+            if (leftBg === undefined) {
+                if (rightBg !== undefined)
+                    yield* cap(lead, rightBg);
+                return;
+            }
+            if (rightBg === undefined) {
+                yield* cap(tail, leftBg);
+                return;
+            }
+            const arrow = new Style({ color: drawnGround(leftBg), bgcolor: rightBg });
             // The divider is the left item's text on the left item's own ground,
             // so it reads exactly as well as that item's text does, at any depth.
             yield vanishes(arrow, options.colorSystem)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "type": "module",
   "sideEffects": false,