@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/style.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Immutable style descriptors — colors, text attributes, links, metadata.
+ */
+import { ColorSpec, ColorDepth } from "./color.js";
+import { type Anchor } from "./anchor.js";
+/**
+ * Canonical text-attribute inventory. Single source of truth consumed by
+ * `Style.parse` / `Style.toString` and the template bindings — adding an
+ * attribute here propagates to every styling surface without a second
+ * list to keep in sync. [LAW:one-source-of-truth]
+ */
+export declare const ATTRIBUTE_NAMES: readonly ["bold", "dim", "italic", "underline", "blink", "blink2", "reverse", "conceal", "strike", "underline2", "frame", "encircle", "overline"];
+export type AttributeName = (typeof ATTRIBUTE_NAMES)[number];
+export declare const ATTRIBUTE_SGR: Record<AttributeName, number>;
+/**
+ * Canonical short-attribute aliases (`b` → `bold`, `i` → `italic`, …).
+ * Single source of truth consumed by `Style.parse` and the template
+ * bindings — adding an alias here makes it available everywhere.
+ * [LAW:one-source-of-truth]
+ */
+export declare const ATTRIBUTE_SHORT_ALIASES: Record<string, AttributeName>;
+export interface StyleOptions {
+    color?: string | ColorSpec;
+    bgcolor?: string | ColorSpec;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    blink?: boolean;
+    blink2?: boolean;
+    reverse?: boolean;
+    conceal?: boolean;
+    strike?: boolean;
+    underline2?: boolean;
+    frame?: boolean;
+    encircle?: boolean;
+    overline?: boolean;
+    link?: string;
+    meta?: Record<string, unknown>;
+    anchor?: Anchor;
+}
+export declare class StyleSyntaxError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class Style {
+    readonly color: ColorSpec | undefined;
+    readonly bgcolor: ColorSpec | undefined;
+    readonly bold: boolean | undefined;
+    readonly dim: boolean | undefined;
+    readonly italic: boolean | undefined;
+    readonly underline: boolean | undefined;
+    readonly blink: boolean | undefined;
+    readonly blink2: boolean | undefined;
+    readonly reverse: boolean | undefined;
+    readonly conceal: boolean | undefined;
+    readonly strike: boolean | undefined;
+    readonly underline2: boolean | undefined;
+    readonly frame: boolean | undefined;
+    readonly encircle: boolean | undefined;
+    readonly overline: boolean | undefined;
+    readonly link: string | undefined;
+    readonly meta: Record<string, unknown> | undefined;
+    /**
+     * Where this style's cells sat in the output of whatever drew them; see
+     * `./anchor.ts`. It draws nothing, and it makes two styles that draw alike
+     * unequal, because they came from different places.
+     */
+    readonly anchor: Anchor | undefined;
+    constructor(options?: StyleOptions);
+    get isNull(): boolean;
+    get transparentBackground(): boolean;
+    get backgroundStyle(): Style;
+    /**
+     * This style with `overrides` in place of its own fields.
+     *
+     * [LAW:one-source-of-truth] The field list is the class's own fields, so a
+     * field added to `Style` is carried by every copy without being named here.
+     */
+    private with;
+    get withoutColor(): Style;
+    withLink(link: string | undefined): Style;
+    clearMetaAndLinks(): Style;
+    /**
+     * The same look, drawn from the place `anchor` names, or from nowhere.
+     */
+    withAnchor(anchor: Anchor | undefined): Style;
+    /**
+     * This style on the cell `cells` to the right: its anchor shifted along its
+     * row, or the style itself when it has no anchor.
+     */
+    shiftedBy(cells: number): Style;
+    /**
+     * Merges two styles. `other`'s values take priority.
+     */
+    add(other: Style | undefined): Style;
+    equals(other: Style): boolean;
+    /**
+     * The colours this style puts on screen at `colorSystem`: each flattened
+     * onto what lies beneath it — the background onto the terminal's black, the
+     * foreground onto that background — then downgraded to the depth. The one
+     * account of what a style draws: `toSgrCodes` encodes exactly these, and a
+     * renderable choosing between two ways of drawing measures them.
+     */
+    drawnColors(colorSystem?: ColorDepth): {
+        readonly color: ColorSpec | undefined;
+        readonly bgcolor: ColorSpec | undefined;
+    };
+    /**
+     * Returns the SGR parameter list this style emits (e.g. `"1;31;48;2;0;0;255"`),
+     * or `""` when the style has no SGR contribution. Excludes OSC 8 link bytes —
+     * links are not SGR. The segment encoder (`segmentsToString`) uses this
+     * string as the group key for adjacent-same-style coalescing and wraps it in
+     * `\x1b[...m`; styled text reaches the wire only through that encoder.
+     *
+     * [LAW:one-source-of-truth] One computation of SGR codes.
+     */
+    toSgrCodes(colorSystem: ColorDepth): string;
+    /**
+     * Serializes to a canonical string that round-trips through `Style.parse()`.
+     */
+    toString(): string;
+    static null(): Style;
+    static fromColor(color?: ColorSpec, bgcolor?: ColorSpec): Style;
+    static fromMeta(meta: Record<string, unknown>): Style;
+    static pickFirst(...args: (Style | undefined)[]): Style;
+    static combine(styles: (Style | undefined)[]): Style;
+    static chain(...styles: (Style | undefined)[]): Style;
+    static normalize(definition: string): string;
+    /**
+     * Parse a space-separated style definition. Cached.
+     *
+     * A definition only: `"bold red"` parses, `"repr.number"` does not. Names
+     * belong to a `Theme`, and `Theme.resolve` is where one is looked up.
+     */
+    static parse(definition: string): Style;
+}
+export declare const NULL_STYLE: Style;
+export declare class StyleStack {
+    private readonly stack;
+    constructor(base?: Style);
+    get current(): Style;
+    push(style: Style): void;
+    pop(): Style;
+}
+export declare class Theme {
+    private readonly styles;
+    constructor(definitions?: Record<string, string>, options?: {
+        inherit?: boolean;
+    });
+    get(name: string): Style | undefined;
+    /**
+     * The style a `string | Style` stands for under this theme: a name this
+     * theme defines, otherwise a definition for `Style.parse`, which throws
+     * `StyleSyntaxError` when the string is neither.
+     *
+     * [LAW:one-source-of-truth] The theme is the one map from names to styles.
+     * The lookup stays outside `Style.parse`'s process-wide cache on purpose:
+     * cached there, the first console to resolve `repr.number` would decide it
+     * for every console after it, whatever theme each was given.
+     */
+    resolve(style: string | Style): Style;
+    has(name: string): boolean;
+}
+export declare const DEFAULT_STYLES: Record<string, Style>;
+/**
+ * The theme a render resolves names against when nothing supplied one — what
+ * a renderable sees outside a `Console`, as in `renderToString`.
+ */
+export declare const DEFAULT_THEME: Theme;