@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/core/color.d.ts

@@ -1,7 +1,8 @@
 /**
  * Terminal color representation, parsing, downgrading, and ANSI code generation.
  */
-import type { Env } from "./env.js";
+import { type Env } from "./env.js";
+import { type TextOrder } from "./text-order.js";
 import type { Palette } from "../themes/palette.js";
 /**
  * Immutable RGBA color value. Alpha defaults to 1 (fully opaque).
@@ -34,12 +35,12 @@ export declare class ColorRgba {
     compositeOver(bg: ColorRgba): ColorRgba;
 }
 /**
- * The surface a terminal draws a translucent colour over. A terminal cannot
+ * The surface a terminal draws a translucent color over. A terminal cannot
  * know what lies under its cells, so the SGR writer (`Style.toSgrCodes`), the
  * exports that picture its output (`resolveLook`), the strip's seam test and
  * the contrast choosers (`themes/colorMath`) all composite over this one
- * colour. [LAW:one-source-of-truth] One constant, so
- * the colour text is chosen against is the colour the writer draws.
+ * color. [LAW:one-source-of-truth] One constant, so
+ * the color text is chosen against is the color the writer draws.
  */
 export declare const SURFACE_BLACK: ColorRgba;
 /**
@@ -63,7 +64,7 @@ export declare function rgbDistance(a: ColorRgba, b: ColorRgba): number;
 /**
  * An indexed palette: entry `i` of `colors` is terminal index `firstIndex + i`.
  * `firstIndex` lets a table hold only the part of a palette a downgrade may
- * choose (the 256-colour cube and grey ramp start at 16) while every index it
+ * choose (the 256-color cube and grey ramp start at 16) while every index it
  * reports is the terminal's own.
  */
 export declare class ColorTable {
@@ -97,7 +98,7 @@ export declare class ColorTable {
     private nearestReadable;
     /**
      * The nearest entry to `value` (the distance `match` uses) among those
-     * `accept` takes, given each entry's colour and terminal index; `undefined`
+     * `accept` takes, given each entry's color and terminal index; `undefined`
      * when it takes none. Entries are offered nearest-first (ties to the lower
      * index) and the first taken wins, so an expensive predicate runs only as
      * far out as the answer. Uncached: the predicate is the caller's, and a
@@ -125,8 +126,8 @@ declare const COLOR_SYSTEM_DEPTHS: {
     readonly none: null;
 };
 /**
- * A colour system by name: `"auto"` detects it from the environment, and each
- * other name is a fixed depth — `"none"` no colour. `ColorDepth.WINDOWS` has
+ * A color system by name: `"auto"` detects it from the environment, and each
+ * other name is a fixed depth — `"none"` no color. `ColorDepth.WINDOWS` has
  * no name; pass the enum value where a `ColorDepth` is accepted.
  */
 export type ColorSystemName = "auto" | keyof typeof COLOR_SYSTEM_DEPTHS;
@@ -142,22 +143,16 @@ export type ColorSystemName = "auto" | keyof typeof COLOR_SYSTEM_DEPTHS;
  * in the env values, not in which checks execute.
  */
 export declare function detectColorSystem(options?: DetectColorOptions): ColorDepth | null;
-/**
- * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
- * as Emacs' shell mode sets it. It takes no colour and nothing that moves the
- * cursor.
- */
-export declare function isDumbTerminal(env: Env): boolean;
 /**
  * Where segments are written, as everything the serializer (`segmentsToString`)
- * needs to know about it: the colour depth SGR is drawn at, whether OSC 8
+ * needs to know about it: the color depth SGR is drawn at, whether OSC 8
  * hyperlinks are emitted, and whether the reader there asked for reduced
  * motion — under which the terminal's own blink is not asked for
  * (`shownOn`, `./render.ts`). The serializer takes this value whole, so a
  * fact the encoding comes to need joins it here rather than the serializer's
  * signature.
  */
-export interface Destination {
+export interface OutputTarget {
     readonly colorSystem: ColorDepth | null;
     readonly hyperlinks: boolean;
     /**
@@ -166,29 +161,33 @@ export interface Destination {
      * drawn and how it is encoded take one preference.
      */
     readonly reducedMotion: boolean;
+    /** What the destination does with direction; `./text-order.ts` owns the three. */
+    readonly textOrder: TextOrder;
 }
 /**
- * What `resolveDestination` is told about where it writes beyond the colour
+ * What `resolveOutputTarget` is told about where it writes beyond the color
  * spec: what detection probes, and the reader's preference for motion, which
  * no spec or terminal reports, so the program hands it in. Absent, everything
  * moves.
  */
 export interface DestinationOptions extends DetectColorOptions {
     reducedMotion?: boolean;
+    /** The order the program knows its destination takes. Absent, `detectTextOrder` decides. */
+    textOrder?: TextOrder;
 }
 /**
- * Resolve a colour spec into a `Destination`.
+ * Resolve a color spec into an `OutputTarget`.
  *
  * [LAW:single-enforcer] The one place a spec becomes both facts. A hyperlink is
- * not a colour: an explicit depth — `"none"` and `null` included — states a
- * colour choice and keeps links, and under `"auto"` links follow what the
+ * not a color: an explicit depth — `"none"` and `null` included — states a
+ * color choice and keeps links, and under `"auto"` links follow what the
  * terminal can take (no TTY, TERM=dumb: none) while NO_COLOR and FORCE_COLOR=0,
- * colour preferences, leave them alone. A FORCE_COLOR that forces colour on
+ * color preferences, leave them alone. A FORCE_COLOR that forces color on
  * declares the destination takes escapes, so it keeps links on a pipe too.
  */
-export declare function resolveDestination(spec: ColorSystemName | ColorDepth | null, options?: DestinationOptions): Destination;
+export declare function resolveOutputTarget(spec: ColorSystemName | ColorDepth | null, options?: DestinationOptions): OutputTarget;
 /**
- * Resolve a colour system name into a `ColorDepth` (or `null` for no color).
+ * Resolve a color system name into a `ColorDepth` (or `null` for no color).
  *
  * `"auto"` triggers env-based detection; every other name is a fixed depth.
  * A name outside the vocabulary — reachable only from untyped JavaScript —
@@ -209,12 +208,12 @@ export declare class ColorSpec {
     constructor(name: string, type: ColorDepth, number?: number, value?: ColorRgba);
     get isDefault(): boolean;
     /**
-     * The colour every terminal draws this spec as, where that is fixed — before
+     * The color every terminal draws this spec as, where that is fixed — before
      * any alpha is flattened, so a translucent value is drawn composited over
      * its ground (`flattenAlpha`) and should be measured that way: a
-     * truecolor value, or a 256-colour cube or grey-ramp entry (xterm fixes
+     * truecolor value, or a 256-color cube or grey-ramp entry (xterm fixes
      * indices 16–255, and `fromAnsi` types only those as EIGHT_BIT). ANSI 0–15,
-     * the default colour and a blend reaching either are the terminal theme's
+     * the default color and a blend reaching either are the terminal theme's
      * own, so they have none.
      */
     get fixedValue(): ColorRgba | undefined;
@@ -251,48 +250,48 @@ export declare class ColorSpec {
     static fromRgba(value: ColorRgba): ColorSpec;
     static fromRgb(r: number, g: number, b: number): ColorSpec;
     /**
-     * The colour `t` of the way from `from` to `to`: what `blend(from,to,t)`
-     * parses to. Two fixed colours mix to a fixed colour. A mix reaching a
-     * theme's own colour stays a mix until it is drawn, so whatever theme draws
+     * The color `t` of the way from `from` to `to`: what `blend(from,to,t)`
+     * parses to. Two fixed colors mix to a fixed color. A mix reaching a
+     * theme's own color stays a mix until it is drawn, so whatever theme draws
      * an end draws the mix from it: exported under a theme whose `blue` is
      * #61afef, a mix with `blue` starts from #61afef. A terminal is told its RGB
      * under the standard table, the only one a render has.
      *
-     * Each end is one opaque colour: `default` is no colour to mix, and a
+     * Each end is one opaque color: `default` is no color to mix, and a
      * translucent end has no one shade until it is laid on a ground.
      */
     static blend(from: ColorSpec, to: ColorSpec, t: number): ColorSpec;
     /**
      * The spec that draws `value` nearest to it at `depth` on a terminal known
-     * to show `theme`, as the colour of the glyph (`foreground`) or of the
+     * to show `theme`, as the color of the glyph (`foreground`) or of the
      * ground. Where `downgrade` knows no terminal, and so rounds only against
-     * colours every terminal fixes (or, at sixteen colours, the stock
-     * sixteen), this rounds against every colour the depth can write whose
-     * look `theme` fixes: the default colour, the theme's sixteen, and at 256
-     * colours the cube and grey ramp too. A colour read off any of those and
-     * moved a little is drawn as the colour it came from — or, where the theme
-     * gives two slots one colour, as the lower slot, which looks the same.
+     * colors every terminal fixes (or, at sixteen colors, the stock
+     * sixteen), this rounds against every color the depth can write whose
+     * look `theme` fixes: the default color, the theme's sixteen, and at 256
+     * colors the cube and grey ramp too. A color read off any of those and
+     * moved a little is drawn as the color it came from — or, where the theme
+     * gives two slots one color, as the lower slot, which looks the same.
      *
-     * `value` is opaque: a translucent colour has no one look until it is laid
+     * `value` is opaque: a translucent color has no one look until it is laid
      * on a ground (`flattenAlpha`).
      */
     static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalColors, foreground: boolean): ColorSpec;
     /**
-     * Every colour `depth` writes by index, each with the colour a terminal
+     * Every color `depth` writes by index, each with the color a terminal
      * known to show `theme` draws it in, lowest index first: the theme's
-     * sixteen, and at 256 colours the cube and grey ramp after them. Each is
-     * drawn alike as glyph and as ground, which the default colour is not, so
-     * it is not among them. Truecolor writes a colour itself and the default
-     * depth only the default, so neither writes any by index. The colours
+     * sixteen, and at 256 colors the cube and grey ramp after them. Each is
+     * drawn alike as glyph and as ground, which the default color is not, so
+     * it is not among them. Truecolor writes a color itself and the default
+     * depth only the default, so neither writes any by index. The colors
      * `matchOn` rounds to, but for the default, read off the same two tables.
      */
     static indexed(depth: ColorDepth, theme: TerminalColors): readonly (readonly [ColorSpec, ColorRgba])[];
     /**
-     * The spec a slot is written in once its colour moves from `was`, what its
+     * The spec a slot is written in once its color moves from `was`, what its
      * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or
      * none, where the written spec is as near `now` as that match. A move the
-     * depth cannot show is no move, so below truecolor a colour moved a little
-     * off any colour the depth can write — a theme slot, the default colour,
+     * depth cannot show is no move, so below truecolor a color moved a little
+     * off any color the depth can write — a theme slot, the default color,
      * the cube — keeps the spec it was written in.
      */
     static matchMove(was: ColorRgba, now: ColorRgba, depth: ColorDepth, theme: TerminalColors, foreground: boolean): ColorSpec | undefined;
@@ -303,7 +302,7 @@ export declare class ColorSpec {
     static parse(colorString: string): ColorSpec;
     private performDowngrade;
 }
-/** Six hex digits, no `#`, as an opaque colour. @throws {ColorParseError} on anything else. */
+/** Six hex digits, no `#`, as an opaque color. @throws {ColorParseError} on anything else. */
 export declare function parseRgbHex(hex: string): ColorRgba;
 /** Eight hex digits, no `#`, the last pair alpha. @throws {ColorParseError} on anything else. */
 export declare function parseRgbaHex(hex: string): ColorRgba;
@@ -314,7 +313,7 @@ export declare function parseRgbaHex(hex: string): ColorRgba;
 export declare function parseHexColor(literal: string): ColorRgba;
 export declare function blendRgb(color1: ColorRgba, color2: ColorRgba, crossFade?: number): ColorRgba;
 /**
- * What a terminal draws with: the part of a `TerminalTheme` a colour resolves
+ * What a terminal draws with: the part of a `TerminalTheme` a color resolves
  * against.
  */
 export declare class TerminalColors {
@@ -325,12 +324,12 @@ export declare class TerminalColors {
     constructor(backgroundColor: ColorRgba, foregroundColor: ColorRgba, ansiColors: ColorTable);
 }
 /**
- * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
+ * A terminal theme — surface/foreground baseline, the sixteen ANSI colors,
  * and a semantic palette.
  *
- * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
+ * **`ansiColors` is the theme's own sixteen colors**, the shades a terminal
  * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
- * is ANSI colour 1 under every theme; which red that is, is the theme's to say,
+ * is ANSI color 1 under every theme; which red that is, is the theme's to say,
  * as it is in Rich, where each `TerminalTheme` carries its own table.
  */
 export declare class TerminalTheme extends TerminalColors {
@@ -340,15 +339,15 @@ export declare class TerminalTheme extends TerminalColors {
 export declare const STANDARD_TABLE: ColorTable;
 export declare const EIGHT_BIT_TABLE: ColorTable;
 /**
- * What a downgrade to 256 colours may choose: the cube and the grey ramp,
- * indices 16–255. Indices 0–15 are the terminal's own ANSI colours, which
+ * What a downgrade to 256 colors may choose: the cube and the grey ramp,
+ * indices 16–255. Indices 0–15 are the terminal's own ANSI colors, which
  * every theme redefines, so their RGB is unknown and a match against them is
  * a guess; Python Rich never picks them either.
  */
 export declare const EIGHT_BIT_DOWNGRADE_TABLE: ColorTable;
 export declare const WINDOWS_TABLE: ColorTable;
 /**
- * The terminal a colour at `depth` is drawn by: `theme`, or when a caller names
+ * The terminal a color at `depth` is drawn by: `theme`, or when a caller names
  * none, the one the depth assumes — the Windows console at WINDOWS, the VGA
  * sixteen otherwise — for `ColorSpec.getTruecolor` and the contrast measurement
  * that reads it. (Widgets fall back to `DEFAULT_TERMINAL_THEME`, which carries a
@@ -356,9 +355,9 @@ export declare const WINDOWS_TABLE: ColorTable;
  */
 export declare function resolveTerminal(theme: TerminalColors | undefined, depth: ColorDepth): TerminalColors;
 /**
- * The table a downgrade to `depth` rounds a fixed colour against.
- * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a colour is
- * written as from it, and colorMath hands back its entries as colours the
+ * The table a downgrade to `depth` rounds a fixed color against.
+ * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a color is
+ * written as from it, and colorMath hands back its entries as colors the
  * writer rounds to those same indices.
  */
 export declare function downgradeTable(depth: ColorDepth.EIGHT_BIT | ColorDepth.STANDARD | ColorDepth.WINDOWS): ColorTable;