@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/markup.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Markup — BBCode-inspired markup parser for inline styling.
+ * Parses `[bold red]text[/bold red]` into RichText with styled spans.
+ *
+ * Plugin tags ([LAW:locality-or-seam]): a `MarkupRegistry` lets consumers
+ * register tag handlers without forking the parser. When the parser sees
+ * `[name attrs...]inner[/name]` and `name` is registered, it parses attrs,
+ * renders the inner markup as the child `RichText`, and calls the handler —
+ * splicing the `RichText` it returns into the output. The
+ * built-in style dialect and the plugin dialect are routed by the registry,
+ * which is the single trust boundary between them.
+ *
+ * Plugin pairs must nest. The built-in dialect admits non-strict nesting
+ * (`[bold]a[italic]b[/bold]c[/italic]`) because a style is an annotation and
+ * annotations may overlap freely; a plugin tag is a replacement whose handler
+ * takes one contiguous `inner`, so an overlapping pair has no slice to hand it
+ * and is rejected with a `MarkupSyntaxError`. For the same reason a style tag
+ * may not open on one side of a plugin tag and close on the other.
+ */
+import { Style } from "./style.js";
+import { RichText } from "./text.js";
+import type { RenderOptions as DrawOptions } from "./protocol.js";
+export declare class Tag {
+    readonly name: string;
+    readonly parameters: string | undefined;
+    constructor(name: string, parameters?: string);
+    toString(): string;
+    get markup(): string;
+}
+export declare class MarkupError extends Error {
+    constructor(message: string);
+}
+/**
+ * A markup string that cannot be parsed, with where it went wrong.
+ *
+ * [LAW:types-are-the-program] A subclass rather than optional fields on
+ * `MarkupError`, because the parent is also what `MarkupRegistry.register`
+ * throws, and a registration has no source text to point into. Every error this
+ * class describes has a location, so none of its fields is optional and no
+ * caller has to ask whether one is present — `instanceof` is the only question.
+ *
+ * [LAW:one-source-of-truth] The constructor takes the facts the parser holds —
+ * the string, the offset of the offending tag, what was open — and derives
+ * `line`, `column` and the message from them, so the numbers a caller reads
+ * and the caret the message draws cannot disagree.
+ */
+export declare class MarkupSyntaxError extends MarkupError {
+    /** The problem alone, with no location, for callers building their own message. */
+    readonly reason: string;
+    /** The whole markup string that failed, as the caller passed it. */
+    readonly markup: string;
+    /** Index into `markup` of the tag the parser rejected. */
+    readonly offset: number;
+    /** 1-based line of `offset`; lines are separated by `\n`. */
+    readonly line: number;
+    /** 1-based column of `offset` within its line, in UTF-16 code units. */
+    readonly column: number;
+    /**
+     * The opening tags still open at `offset`, outermost first, as written.
+     */
+    readonly openTags: readonly string[];
+    constructor(reason: string, markup: string, offset: number, openTags: readonly string[]);
+}
+/**
+ * Escapes markup characters so they render as literal text.
+ *
+ * [LAW:one-source-of-truth] The inverse of the two ways the parser reads a
+ * backslash run in front of a bracket, over the same `TAG_BODY`: before a tag
+ * the run is halved and an odd one left over escapes it, so the run is doubled
+ * and one added; before any other bracket one `\[` becomes `[`, so one
+ * backslash is added.
+ *
+ * No bracket in the output can open a tag, whatever it is joined to. A bracket
+ * whose tag the text ends before finishing — `[link=x` — is escaped as a tag,
+ * because the next fragment's `]` would finish it; when what follows is instead
+ * the caller's own tag, a backslash run in front of it renders doubled. A
+ * trailing run is doubled for the same reason: `escape("C:\\")` spliced before
+ * `[/bold]` would otherwise escape the closing tag, so at the very end of a
+ * string it renders doubled. The grammar cannot tell those cases apart, and
+ * both choices fail visibly rather than let input open or escape a tag.
+ *
+ * Rich's `escape` escapes only a finished tag and doubles only a trailing run
+ * of one, so input can drop a backslash, escape the closing tag after it, or
+ * open a tag across a join. All three are departures on purpose.
+ */
+export declare function escape(text: string): string;
+export interface MarkupTagContext {
+    /** Parsed `key=value` attributes from the opening tag. */
+    attrs: Record<string, string>;
+    /**
+     * Inner markup, already parsed (registry-aware) into a `RichText`. It carries
+     * no `baseStyle`: that is painted once, under the whole output, so it sits
+     * beneath whatever the handler returns.
+     */
+    children: RichText;
+    /** Raw inner markup text (between the opening tag's `]` and the closing tag's `[`). */
+    raw: string;
+}
+export type MarkupTagHandler = (ctx: MarkupTagContext) => RichText;
+export declare class MarkupRegistry {
+    private readonly _handlers;
+    register(name: string, handler: MarkupTagHandler): void;
+    unregister(name: string): void;
+    has(name: string): boolean;
+    get(name: string): MarkupTagHandler | undefined;
+}
+export declare const globalMarkupRegistry: MarkupRegistry;
+export interface RenderMarkupOptions {
+    registry?: MarkupRegistry;
+    baseStyle?: string | Style;
+    emoji?: boolean;
+}
+/**
+ * Plugin-aware markup render. Always returns a `RichText`. Built-in style
+ * tags become spans; registered plugin tags are resolved by their handler,
+ * whose returned `RichText` stands in the output where its pair stood, under
+ * any style tag that encloses the pair.
+ */
+export declare function renderMarkup(markup: string, options?: RenderMarkupOptions): RichText;
+/**
+ * A string as the text it draws, before any highlighting: read as markup
+ * unless `markup` is false, its emoji codes replaced either way, as Rich's
+ * `render_str` reads one, its `end` the default line end Rich's leaves it.
+ * [LAW:single-enforcer]
+ */
+export declare function readStr(source: string, markup: boolean): RichText;
+/**
+ * The highlighter a string is drawn with under `settings`: its `highlighter`
+ * while `highlight` is not false — Rich's `render_str`, which highlights with
+ * `console.highlighter` when `highlight` is true or left to the console.
+ * [LAW:single-enforcer]
+ */
+export declare function activeHighlighter(settings: Pick<DrawOptions, "highlight" | "highlighter">): DrawOptions["highlighter"];
+/**
+ * A string as the text it draws, the way Rich's `render_str` makes one: read
+ * by `readStr` under `markup`, then highlighted by `activeHighlighter`.
+ * `print` and every renderable that is handed a string both draw it this way,
+ * so a console's settings mean the same thing wherever the string lands.
+ */
+export declare function renderStr(source: string, settings: Pick<DrawOptions, "markup" | "highlight" | "highlighter">): RichText;