@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/template-bindings/style-funcs.js

@@ -0,0 +1,157 @@
+/**
+ * Style-function registrations for the rich-js template binding.
+ *
+ * [LAW:one-source-of-truth] The function inventory below mirrors the
+ * string-syntax style vocabulary documented in `docs/style.md` — the two
+ * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * aliases, and the hyperlink. Each registration is a templating-time analogue
+ * of a piece of `Style.parse`, so a template fragment composed by these
+ * functions round-trips through `Style` without semantic drift.
+ *
+ * [LAW:dataflow-not-control-flow] Every function follows the same
+ * shape: child `RichText` in, `RichText` out. The styling difference
+ * lives in a captured `Style` value (or constructor closure), not in
+ * branches inside a single dispatch. That is why this file is mostly
+ * factories — the data (the colour, the attribute name) is the
+ * variability; the operation is fixed.
+ */
+import { Style, ATTRIBUTE_NAMES, ATTRIBUTE_SHORT_ALIASES, } from "../core/style.js";
+import { ColorSpec } from "../core/color.js";
+import { applyStyleToFragment } from "./helpers.js";
+function attrFunc(style) {
+    return {
+        fn: ((child) => applyStyleToFragment(child, style)),
+        argTypes: ["liftable"],
+        arity: { kind: "exact" },
+        returnType: "T",
+    };
+}
+// --- Colour sinks ---
+//
+// `fg` and `bg` are the only two colour-applying functions, and they are the
+// terminal step of the colour pipeline: `color` names a colour, the functions
+// in `color-funcs.ts` transform it, these paint it onto text.
+//
+// [LAW:composability] They replace five separate families — one function per
+// ANSI colour name (`red`, `bright_blue`, …), `hex`, `rgb`, `color` (256-index),
+// and `on` (background). Every one of those encoded *which colour* in the
+// function's identity, so the vocabulary could only grow by adding names, and
+// a colour computed at render time could not be applied at all. Here the colour
+// is an argument, so the sink admits every colour that exists and every colour
+// that will ever exist. Two functions, unbounded reach.
+//
+// [LAW:types-are-the-program] The slot accepts the full `ColorSpec.parse`
+// vocabulary, which is wider than the hex the colour math produces — and that
+// width is deliberate, not laxity. `#7aa2f7` is a *concrete* colour; `"red"`
+// and `"color(42)"` are *symbolic* ones the terminal resolves against its own
+// theme. Only concrete colours can be darkened or blended, which is why the
+// colour-math functions take hex alone; but both kinds can be painted, so the
+// sink takes the union. The type of each slot is exactly the set of values that
+// slot can mean something for.
+function colorSinkFunc(slot) {
+    return {
+        fn: ((spec, child) => applyStyleToFragment(child, new Style({ [slot]: ColorSpec.parse(spec) }))),
+        argTypes: ["string", "liftable"],
+        arity: { kind: "exact" },
+        returnType: "T",
+    };
+}
+// --- Text attributes ---
+//
+// [LAW:one-source-of-truth] The attribute and short-alias inventories
+// come from `core/style.ts`. This file derives the template registration
+// set from the same data `Style.parse` consults — adding an attribute or
+// alias in one place propagates here automatically.
+function attrStyle(name, value) {
+    return new Style({ [name]: value });
+}
+function attributeFuncs() {
+    const out = {};
+    for (const name of ATTRIBUTE_NAMES) {
+        out[name] = attrFunc(attrStyle(name, true));
+        out[`not_${name}`] = attrFunc(attrStyle(name, false));
+    }
+    for (const [alias, canonical] of Object.entries(ATTRIBUTE_SHORT_ALIASES)) {
+        out[alias] = attrFunc(attrStyle(canonical, true));
+    }
+    return out;
+}
+// --- Style spec (multi-attribute one-shot) ---
+//
+// [LAW:one-source-of-truth] `style` accepts the same space-separated grammar
+// `Style.parse` consults — i.e. the inside of `[...]` markup. There is no
+// second parser: a spec that `Style.parse` accepts produces a fragment
+// byte-equivalent to the same spec inside markup, and one that `Style.parse`
+// rejects raises the same `StyleSyntaxError` surface.
+//
+// Motivation: the per-attribute functions (`bold`, `underline`, `fg`, …)
+// compose by nesting. For "apply a fixed set of styles to this child" or
+// "apply this named style set everywhere", nesting is awkward and the
+// style description is fragmented across multiple call sites. `style`
+// collapses that to a single call, and because the spec is a string it
+// flows through Go-template `$vars` and through scope without further
+// machinery:
+//
+//   {{ $alert := "bold underline #ff6b6b" }}
+//   {{ style $alert "alarm!" }}
+//   {{ style $alert .otherField }}
+//
+// [LAW:dataflow-not-control-flow] Same shape as every other style function:
+// a `Style` value (here built by `Style.parse(spec)`) plus a child, in,
+// styled child out. The variability is the spec string; the operation is
+// fixed.
+const styleSpecFunc = {
+    fn: ((spec, child) => {
+        return applyStyleToFragment(child, Style.parse(spec));
+    }),
+    argTypes: ["string", "liftable"],
+    arity: { kind: "exact" },
+    returnType: "T",
+};
+// --- Hyperlink ---
+//
+// `link` is the cell-splitter for the multi-cell consumer contract.
+// Implementation-wise it is the same shape as any other style function:
+// it sets the `link` slot of `Style` exactly as the existing string-form
+// `link URL` does, so `{{ link "u" "x" }}` is byte-equivalent to
+// `RichText("x", { style: Style.parse("link u") })`.
+//
+// The cell-boundary signal that consumers (cc-candybar et al.) walk is
+// `theme.resolve(fragment.style).link` being truthy: a fragment whose base
+// style is a string keeps the link in a `LayeredStyle` until a theme says
+// what the string stands for. `Style.add` propagates `link`
+// through any outer wrapping call, so `{{ fg "red" (link "u" "x") }}` and
+// `{{ link "u" "x" }}` produce shapes that both qualify as cells from
+// the consumer's perspective. Outer-wins on nested links comes for free
+// from `Style.add`'s right-wins-on-conflict rule.
+//
+// [LAW:dataflow-not-control-flow] No special-case AST node, no
+// `LinkFragment` subclass, no second emitter path — the variability is
+// the value of `style.link`, not whether some control-flow branch ran.
+const linkFunc = {
+    fn: ((url, child) => {
+        return applyStyleToFragment(child, new Style({ link: url }));
+    }),
+    argTypes: ["string", "liftable"],
+    arity: { kind: "exact" },
+    returnType: "T",
+};
+// --- Public assembly ---
+/**
+ * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * attributes (canonical names, short aliases, and `not_*` negations), the
+ * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
+ *
+ * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * [LAW:one-way-deps] — nothing here imports a palette.
+ */
+export function richTextStyleFuncs() {
+    return {
+        fg: colorSinkFunc("color"),
+        bg: colorSinkFunc("bgcolor"),
+        ...attributeFuncs(),
+        link: linkFunc,
+        style: styleSpecFunc,
+    };
+}

package/dist/themes/buildPalette.d.ts

@@ -0,0 +1,57 @@
+import { ColorRgba } from "../core/color.js";
+import { Palette } from "./palette.js";
+/**
+ * Base colors required to build a full semantic palette.
+ * All are ColorRgba — callers construct from whatever source (hex, HSL, etc.).
+ */
+export interface BaseColors {
+    primary: ColorRgba;
+    secondary: ColorRgba;
+    accent: ColorRgba;
+    success: ColorRgba;
+    warning: ColorRgba;
+    error: ColorRgba;
+    background: ColorRgba;
+    foreground: ColorRgba;
+}
+type AccentKey = "primary" | "secondary" | "accent" | "success" | "warning" | "error";
+export declare const ACCENT_KEYS: readonly AccentKey[];
+/**
+ * Build a full semantic palette from base colors.
+ *
+ * Derived entries follow Textual's formulas:
+ * - `*-muted` = color blended 70% toward its opposite base role. Defined for
+ *              every accent AND for the two base roles themselves
+ *              (`foreground-muted` blends toward `background`,
+ *              `background-muted` blends toward `foreground`) — a caller
+ *              de-emphasizing body/structural text reaches for
+ *              `foreground-muted` the same way it reaches for
+ *              `primary-muted` to de-emphasize an accent.
+ * - `text-*`  = contrast text tinted 66% with the accent color, then held
+ *              to WCAG AA (4.5:1) on `*-muted` — the foreground for a
+ *              `*-muted` ground
+ * - `on-*`    = WCAG-correct contrast colour (black or white) for use as
+ *              foreground when the FULL accent is the background. Picked
+ *              by relative luminance — single source of truth so widgets
+ *              never need to invert / reverse fg/bg to get readable text.
+ * - `surface` = background blended 5% toward foreground
+ *
+ * A translucent base colour is drawn onto `background` before anything is
+ * derived from it, so `on-*` is chosen against the colour the accent is drawn
+ * as and every derived entry is opaque.
+ */
+export declare function buildPalette(name: string, dark: boolean, given: BaseColors): Palette;
+/**
+ * A palette's `text-*`: its tint held to WCAG AA on `*-muted`, moved toward
+ * the palette's own text side so it also reads on `background`, where widgets
+ * draw it too. The muted floor is the promise: where no lightness on the text
+ * side clears it, the colour that does is on the other side, and the
+ * background pair is the one given up. Every bundled palette clears both
+ * (test/themes/text-on-muted.test.ts).
+ *
+ * [LAW:single-enforcer] The one rule for the pair, for the palettes derived
+ * here and the authored ones the registry hydrates: the tint is the theme's,
+ * whether it reads is decided here.
+ */
+export declare function accentText(tint: ColorRgba, muted: ColorRgba, background: ColorRgba): ColorRgba;
+export {};

package/dist/themes/buildPalette.js

@@ -0,0 +1,100 @@
+import { blendRgb } from "../core/color.js";
+import { alphaBlend, contrastFor, ensureContrastToward } from "./colorMath.js";
+import { Palette, drawnOn } from "./palette.js";
+const MUTED_BLEND = 0.7;
+const TEXT_ALPHA = 0.66;
+const SURFACE_LIFT = 0.05;
+// WCAG AA for body text: `text-*` is the label drawn on `*-muted`.
+const TEXT_ON_MUTED = 4.5;
+export const ACCENT_KEYS = ["primary", "secondary", "accent", "success", "warning", "error"];
+/**
+ * Build a full semantic palette from base colors.
+ *
+ * Derived entries follow Textual's formulas:
+ * - `*-muted` = color blended 70% toward its opposite base role. Defined for
+ *              every accent AND for the two base roles themselves
+ *              (`foreground-muted` blends toward `background`,
+ *              `background-muted` blends toward `foreground`) — a caller
+ *              de-emphasizing body/structural text reaches for
+ *              `foreground-muted` the same way it reaches for
+ *              `primary-muted` to de-emphasize an accent.
+ * - `text-*`  = contrast text tinted 66% with the accent color, then held
+ *              to WCAG AA (4.5:1) on `*-muted` — the foreground for a
+ *              `*-muted` ground
+ * - `on-*`    = WCAG-correct contrast colour (black or white) for use as
+ *              foreground when the FULL accent is the background. Picked
+ *              by relative luminance — single source of truth so widgets
+ *              never need to invert / reverse fg/bg to get readable text.
+ * - `surface` = background blended 5% toward foreground
+ *
+ * A translucent base colour is drawn onto `background` before anything is
+ * derived from it, so `on-*` is chosen against the colour the accent is drawn
+ * as and every derived entry is opaque.
+ */
+export function buildPalette(name, dark, given) {
+    const drawn = drawnOn(name, given.background);
+    // Every base colour is derived from, and a fully transparent one draws no
+    // colour of its own to derive a muted shade or a contrast from.
+    // [LAW:no-silent-failure]
+    const draw = (key) => {
+        const colour = given[key];
+        if (colour.alpha === 0) {
+            throw new RangeError(`palette ${JSON.stringify(name)}: ${key} is fully transparent (${colour.hex}), so there is no colour to derive the palette from`);
+        }
+        return drawn(colour);
+    };
+    const base = {
+        primary: draw("primary"),
+        secondary: draw("secondary"),
+        accent: draw("accent"),
+        success: draw("success"),
+        warning: draw("warning"),
+        error: draw("error"),
+        background: given.background,
+        foreground: draw("foreground"),
+    };
+    const vars = new Map();
+    // Base entries
+    vars.set("background", base.background);
+    vars.set("foreground", base.foreground);
+    for (const key of ACCENT_KEYS) {
+        vars.set(key, base[key]);
+    }
+    // Muted variants of the two base roles, same "blend 70% toward
+    // background" formula as the accent `*-muted` family below — every
+    // base color the palette defines gets a de-emphasized variant, not just
+    // the accents. `foreground-muted` is what a caller reaches for to draw
+    // structural/contextual text (labels, punctuation, ids) at reduced visual
+    // weight without a terminal-support-dependent SGR attribute.
+    vars.set("foreground-muted", blendRgb(base.foreground, base.background, MUTED_BLEND));
+    vars.set("background-muted", blendRgb(base.background, base.foreground, MUTED_BLEND));
+    // Surface — subtle lift from background
+    vars.set("surface", blendRgb(base.background, base.foreground, SURFACE_LIFT));
+    // Derived: muted, text-, and on- for each accent.
+    // [LAW:single-enforcer] contrastFor is the only place that decides
+    // black-vs-white for "text on this accent" — widgets read on-${accent}.
+    const contrastText = contrastFor(base.background);
+    for (const key of ACCENT_KEYS) {
+        const color = base[key];
+        const muted = blendRgb(color, base.background, MUTED_BLEND);
+        vars.set(`${key}-muted`, muted);
+        vars.set(`text-${key}`, accentText(alphaBlend(color, contrastText, TEXT_ALPHA), muted, base.background));
+        vars.set(`on-${key}`, contrastFor(color));
+    }
+    return new Palette(name, dark, vars);
+}
+/**
+ * A palette's `text-*`: its tint held to WCAG AA on `*-muted`, moved toward
+ * the palette's own text side so it also reads on `background`, where widgets
+ * draw it too. The muted floor is the promise: where no lightness on the text
+ * side clears it, the colour that does is on the other side, and the
+ * background pair is the one given up. Every bundled palette clears both
+ * (test/themes/text-on-muted.test.ts).
+ *
+ * [LAW:single-enforcer] The one rule for the pair, for the palettes derived
+ * here and the authored ones the registry hydrates: the tint is the theme's,
+ * whether it reads is decided here.
+ */
+export function accentText(tint, muted, background) {
+    return ensureContrastToward(tint, muted, TEXT_ON_MUTED, contrastFor(background));
+}

package/dist/themes/colorMath.d.ts

@@ -0,0 +1,94 @@
+import { ColorDepth, ColorRgba, contrastRatio, relativeLuminance, type TerminalTheme } from "../core/color.js";
+/**
+ * Darken a color by N levels, where each level reduces HSL lightness by 10%.
+ * Negative levels lighten. Level 0 returns an equivalent triplet (after the
+ * RGB↔HSL roundtrip; values may differ by ±1 due to rounding).
+ */
+export declare function darken(color: ColorRgba, levels: number): ColorRgba;
+/**
+ * Lighten a color by N levels. Equivalent to `darken(color, -levels)`.
+ */
+export declare function lighten(color: ColorRgba, levels: number): ColorRgba;
+/**
+ * Composite `fg` over `bg` with the given alpha (0..1). At alpha=0 returns bg;
+ * at alpha=1 returns fg.
+ */
+export declare function alphaBlend(fg: ColorRgba, bg: ColorRgba, alpha: number): ColorRgba;
+/**
+ * Pick a contrasting foreground (black or white) for a background, using the
+ * WCAG relative-luminance threshold of 0.179 (the perceptually correct cutoff
+ * where black and white are equally readable). A translucent `bg` is judged
+ * as drawn: composited over `substrate` (see `drawnBackground`).
+ */
+export declare function contrastFor(bg: ColorRgba, substrate?: ColorRgba): ColorRgba;
+export { relativeLuminance, contrastRatio };
+/**
+ * Return a foreground guaranteed to clear `minRatio` against `bg`, keeping the
+ * color *recognizably itself*. If the themed `fg` already passes it is returned
+ * untouched. Otherwise its OKLCH lightness is slid toward the pole that raises
+ * contrast — holding hue, and chroma where it stays in gamut (near the poles
+ * gamut clamping may reduce chroma, but hue is preserved) — until the ratio is
+ * met, so a blue on a dark-blue background becomes a lighter blue, not white.
+ * Only when no lightness of that hue can meet the ratio (a mid-toned
+ * background where even pure black-or-white tops out below the target) does it
+ * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
+ *
+ * A translucent `bg` is measured as it is drawn — composited over
+ * `substrate`, the SGR writer's black by default — and a translucent `fg` is
+ * then flattened over that drawn background, the order the writer composites
+ * in, so the ratio is measured on what the eye actually sees and the returned
+ * color is opaque.
+ *
+ * `drawnAt` is the depth the terminal will draw the pair at. At 256 colours
+ * the terminal rounds text and background independently, and two roundings
+ * can meet in the middle, so the ratio is measured on the drawn pair: a
+ * colour that loses the floor there is replaced by the nearest cube/grey entry
+ * that clears it (whose own rounding is itself). At ANSI the terminal draws
+ * each index in its own theme's colour, so the ratio is measured on
+ * `terminal`'s sixteen: a theme whose black is light and white dark (Rosé Pine
+ * Dawn) turns the nominal table's sides over. A replacement is the colour the
+ * writer emits as the index nearest `fg` that clears the floor as `terminal`
+ * draws it. Truecolor draws the colour chosen.
+ *
+ * [LAW:single-enforcer] The one place "is this text readable, and if not fix
+ * it" is decided. Callers route every fg/bg pair through here and the
+ * unreadable state never reaches output. [LAW:dataflow-not-control-flow] the
+ * function always runs; the measured ratio (data) decides how far the
+ * lightness moves — there is no caller-side "should I check contrast" branch.
+ */
+export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number, // WCAG AA for normal text
+drawnAt?: ColorDepth, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba;
+/**
+ * `chosen` (composited opaque over `substrate`), or — when the depth the
+ * terminal draws at rounds it to a colour `accept` refuses — the colour the
+ * writer emits as the nearest entry `accept` takes. `accept` sees the
+ * candidate as drawn, and `drawn`, the same rounding for any other colour it
+ * measures against, so the caller states a floor once and it holds on the
+ * colours the terminal shows — at ANSI, `terminal`'s own sixteen, as
+ * `ensureContrast` measures there. Truecolor
+ * draws from no table, so a colour refused there has no replacement;
+ * `undefined` means nothing the depth draws is accepted.
+ *
+ * `ensureContrast` is this with a contrast ratio as the floor; this is for a
+ * floor that is not text on its background (an open state standing off every
+ * closed cell, two planes standing off each other).
+ */
+export declare function ensureDrawn(chosen: ColorRgba, drawnAt: ColorDepth, accept: (candidate: ColorRgba, drawn: (c: ColorRgba) => ColorRgba) => boolean, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba | undefined;
+/**
+ * The colour a ground is shown as at `drawnAt`: composited over `substrate`
+ * (the SGR writer's black by default), rounded to the index the writer emits
+ * at that depth, and shown as the terminal shows that index — at ANSI, in
+ * `terminal`'s own colour. The one account `ensureDrawn` and `ensureContrast`
+ * measure by, for a caller that measures a floor of its own.
+ */
+export declare function drawnColour(colour: ColorRgba, drawnAt: ColorDepth, substrate?: ColorRgba, terminal?: TerminalTheme): ColorRgba;
+/**
+ * `fg` held to `minRatio` on `bg` in truecolor, moving in lightness toward
+ * `toward` (black or white). `ensureContrast` moves toward the pole `bg`
+ * itself contrasts with; a colour that already has a side (a palette's
+ * `text-*` is its text, tinted) passes that side, since on a ground near the
+ * 0.179 cutoff both poles clear and only one also reads on everything else
+ * the colour is drawn on. Where `toward` cannot clear `minRatio` on `bg`,
+ * the floor wins over the side: the answer is `contrastFor(bg)`.
+ */
+export declare function ensureContrastToward(fg: ColorRgba, bg: ColorRgba, minRatio: number, toward: ColorRgba): ColorRgba;