@regmisatyam/retex 0.1.0 → 0.2.0

package/dist/index-DJEasLJc.d.ts

@@ -0,0 +1,492 @@
+import { b as SourceRange, A as ArgumentNode, N as Node, f as CommandNode, T as Theme, R as ReactRenderFn, P as PartialTheme, V as ThemeColors, X as ThemeFonts, D as DocumentNode } from './react-B3tN1iWa.js';
+
+/**
+ * Token kinds produced by the {@link Tokenizer}.
+ *
+ * ReTeX intentionally diverges from TeX in a few places that matter for
+ * resumes:
+ *  - `%` is a *literal* percent sign (so `Reduced latency by 40%` and
+ *    `\column{40%}` work as written) rather than a comment marker.
+ *  - Comments use `%%` to end-of-line, which never collides with percentages.
+ */
+declare enum TokenType {
+    /** A command such as `\section`, `\textbf`, `\item`. The lexeme excludes the backslash. */
+    Command = "Command",
+    /** `{` — begin group / argument. */
+    LBrace = "LBrace",
+    /** `}` — end group / argument. */
+    RBrace = "RBrace",
+    /** `[` — begin optional argument. */
+    LBracket = "LBracket",
+    /** `]` — end optional argument. */
+    RBracket = "RBracket",
+    /** Run of literal text. */
+    Text = "Text",
+    /** Run of inline whitespace (spaces/tabs, single newline). */
+    Whitespace = "Whitespace",
+    /** A blank line — paragraph break. */
+    ParBreak = "ParBreak",
+    /** `\\` — explicit line break. */
+    LineBreak = "LineBreak",
+    /** `%% ...` comment (stripped from output, surfaced to editor tooling). */
+    Comment = "Comment",
+    /** End of input. */
+    EOF = "EOF"
+}
+/** A lexical token with full source provenance. */
+interface Token {
+    type: TokenType;
+    /** The exact source text of the token (backslash stripped for commands). */
+    value: string;
+    range: SourceRange;
+}
+/** Reserved single characters that the tokenizer treats specially. */
+declare const SPECIAL_CHARS: Set<string>;
+
+/** Severity levels, ordered the same way LSP orders them. */
+declare enum DiagnosticSeverity {
+    Error = "error",
+    Warning = "warning",
+    Info = "info",
+    Hint = "hint"
+}
+/**
+ * Stable, machine-readable diagnostic codes. Editors can key quick-fixes and
+ * documentation links off these rather than the (localizable) message text.
+ */
+declare enum DiagnosticCode {
+    UnexpectedToken = "RTX1001",
+    UnterminatedGroup = "RTX1002",
+    UnterminatedArgument = "RTX1003",
+    UnexpectedEOF = "RTX1004",
+    MismatchedBrace = "RTX1005",
+    UnknownCommand = "RTX2001",
+    UnknownEnvironment = "RTX2002",
+    MissingRequiredArgument = "RTX2003",
+    TooManyArguments = "RTX2004",
+    MissingEnvironmentEnd = "RTX2005",
+    MismatchedEnvironment = "RTX2006",
+    InvalidColor = "RTX3001",
+    InvalidUrl = "RTX3002",
+    InvalidDimension = "RTX3003",
+    MissingRequiredField = "RTX3004",
+    UnknownField = "RTX3005",
+    EmptyArgument = "RTX3006",
+    CommandOutsideContext = "RTX4001",
+    UnknownIcon = "RTX4002",
+    UnknownThemeColor = "RTX4003",
+    UnknownLibrary = "RTX4004",
+    LibraryRequired = "RTX4005",
+    UnsafeUrlBlocked = "RTX5001"
+}
+/** Optional quick-fix an editor can apply. */
+interface QuickFix {
+    title: string;
+    /** Replacement text for {@link Diagnostic.range}. */
+    replacement: string;
+    range?: SourceRange;
+}
+/** A single diagnostic emitted by any stage of the pipeline. */
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: DiagnosticCode;
+    message: string;
+    range: SourceRange;
+    /** Stage that produced the diagnostic, for filtering. */
+    source: "tokenizer" | "parser" | "validator" | "security";
+    /** Optional editor quick-fixes. */
+    fixes?: QuickFix[];
+}
+
+/**
+ * How a single argument should be consumed by the parser.
+ *
+ *  - `content`   — recursively parse markup (nested commands, text).
+ *  - `string`    — verbatim text; no command expansion (URLs, colors, sizes).
+ *  - `keyval`    — `key=value, key=value` map.
+ *  - `list`      — comma-separated list of trimmed strings.
+ */
+type ArgKind = "content" | "string" | "keyval" | "list";
+interface ArgSpec {
+    kind: ArgKind;
+    /** When true the argument may be absent (no diagnostic if missing). */
+    optional?: boolean;
+    /**
+     * Delimiter pair. `"brace"` (default) → `{...}`; `"bracket"` → `[...]`.
+     * An optional brace argument (e.g. an entry body) is still written with
+     * `{...}` but may be omitted.
+     */
+    delimiter?: "brace" | "bracket";
+    /** Human-readable name surfaced in hover docs / diagnostics. */
+    name?: string;
+    /** Validation hint for `string` args (drives format checks). */
+    format?: "color" | "url" | "dimension" | "text";
+}
+/**
+ * Semantic category of a command. Drives default rendering and where the
+ * command is legal.
+ *
+ *  - `inline` — flows within text (`\textbf`).
+ *  - `block`  — starts a block (`\section`, `\job`).
+ *  - `switch` — a state switch that applies to the rest of its group
+ *               (`\large`, `\bfseries`-style).
+ *  - `meta`   — document metadata that produces no inline flow on its own.
+ */
+type CommandCategory = "inline" | "block" | "switch" | "meta";
+/**
+ * A factory the parser calls once arguments are consumed, to build the AST
+ * node for a command. Returning `null` drops the command from the tree.
+ */
+type NodeBuilder = (ctx: BuildContext) => Node | Node[] | null;
+interface BuildContext {
+    name: string;
+    args: ArgumentNode[];
+    /** For switches: the trailing content the switch applies to. */
+    scope: Node[];
+    /** Emit a diagnostic from within a builder. */
+    report: (d: Omit<Diagnostic, "source">) => void;
+    /** Utilities exposed to plugin authors. */
+    utils: BuilderUtils;
+}
+interface BuilderUtils {
+    /** Flatten an argument's children into a plain string (best-effort). */
+    textOf(arg: ArgumentNode | undefined): string;
+    /** Sanitize a URL; returns `"#"` (and reports) when unsafe. */
+    safeUrl(url: string): string;
+}
+/**
+ * The contract for a command. Used by the parser (argument signature, scope
+ * behavior) and the renderers (when no native node exists, renderers consult
+ * the command's per-target `render` map).
+ */
+interface CommandDefinition {
+    name: string;
+    category?: CommandCategory;
+    /** Argument signature, in order. */
+    args?: ArgSpec[];
+    /**
+     * `true` for switches that swallow the remainder of their enclosing group
+     * as scoped content (`\large`, `\itshape`).
+     */
+    scoped?: boolean;
+    /**
+     * Builds the AST node. When omitted, the parser emits a generic
+     * {@link CommandNode} carrying the parsed arguments.
+     */
+    build?: NodeBuilder;
+    /** One-line summary for hover docs / completion detail. */
+    summary?: string;
+    /** Longer documentation (markdown) for hover. */
+    documentation?: string;
+    /** Example snippet shown in completion / hover. */
+    example?: string;
+}
+/** Environment (`\begin{x} … \end{x}`) contract. */
+interface EnvironmentDefinition {
+    name: string;
+    /**
+     * Command that introduces each entry inside the environment, e.g. `item`
+     * for `itemize`, `column` for `columns`. The parser uses this to slice
+     * the body into entries.
+     */
+    itemCommand?: string;
+    /** Commands legal as direct children (for validation). `*` allows any. */
+    allowedChildren?: string[];
+    /** Build the environment node from its parsed body. */
+    build?: (ctx: EnvBuildContext) => Node | Node[] | null;
+    summary?: string;
+    documentation?: string;
+    example?: string;
+}
+/**
+ * One entry of an `itemCommand`-delimited environment. For `itemize`, the
+ * marker command is `\item`; for `columns`, it is `\column{width}`.
+ */
+interface EnvEntry {
+    /** The marker command that introduced the entry, with its parsed arguments. */
+    marker: CommandNode;
+    /** Content nodes belonging to this entry (up to the next marker / `\end`). */
+    content: Node[];
+}
+interface EnvBuildContext {
+    name: string;
+    /** Parsed body nodes of the environment (always present). */
+    body: Node[];
+    /**
+     * When the environment declares an `itemCommand`, the body sliced into
+     * entries at each marker. `undefined` for plain block environments.
+     */
+    entries?: EnvEntry[];
+    /** Optional `[...]` arguments after `\begin{env}`. */
+    options: ArgumentNode[];
+    report: (d: Omit<Diagnostic, "source">) => void;
+    utils: BuilderUtils;
+}
+
+/**
+ * The command/environment registry. The parser consults it for argument
+ * signatures and node builders; the plugin system mutates it. A registry can
+ * be cloned cheaply so an engine instance never mutates shared global state.
+ */
+declare class CommandRegistry {
+    private commands;
+    private environments;
+    registerCommand(def: CommandDefinition): this;
+    registerEnvironment(def: EnvironmentDefinition): this;
+    getCommand(name: string): CommandDefinition | undefined;
+    getEnvironment(name: string): EnvironmentDefinition | undefined;
+    hasCommand(name: string): boolean;
+    hasEnvironment(name: string): boolean;
+    commandNames(): string[];
+    environmentNames(): string[];
+    allCommands(): CommandDefinition[];
+    allEnvironments(): EnvironmentDefinition[];
+    /** Shallow-clone the registry (definitions are shared, maps are copied). */
+    clone(): CommandRegistry;
+}
+
+/**
+ * Icon registry. Icons are stored as the inner markup of a `0 0 24 24` SVG and
+ * use `currentColor` so they inherit surrounding text color. The set is
+ * intentionally small and extensible via {@link registerIcon} / plugins.
+ *
+ * Glyphs are simplified, original representations (not vendor logo artwork) so
+ * the package carries no third-party asset licensing.
+ */
+interface IconDefinition {
+    /** Inner SVG markup (paths/shapes) with a `0 0 24 24` viewBox. */
+    body: string;
+    /** Whether shapes are stroked (true) or filled (false). */
+    stroked?: boolean;
+    /** Aliases that resolve to this icon. */
+    aliases?: string[];
+}
+/** Resolve a (possibly aliased) icon name to its canonical key. */
+declare function resolveIconName(name: string): string | undefined;
+declare function hasIcon(name: string): boolean;
+declare function getIcon(name: string): IconDefinition | undefined;
+/** Register (or override) an icon at runtime. Used by plugins. */
+declare function registerIcon(name: string, def: IconDefinition): void;
+/** All canonical icon names, for completion / docs. */
+declare function iconNames(): string[];
+/**
+ * Render an icon to an inline SVG string. Returns `null` for unknown icons so
+ * callers can emit a diagnostic and a graceful fallback.
+ */
+declare function iconToSvg(name: string, opts?: {
+    size?: number | string;
+    className?: string;
+}): string | null;
+
+/** Node types that participate in block (vertical) flow. */
+declare const BLOCK_TYPES: Set<string>;
+declare function isBlockNode(node: Node): boolean;
+/**
+ * Plugin HTML renderer. Receives the node, the active context, and a callback
+ * to recursively render child nodes to HTML.
+ */
+type HtmlRenderFn = (node: Node, ctx: HtmlRenderContext, renderChildren: (nodes: Node[]) => string) => string;
+interface HtmlRenderContext {
+    theme: Theme;
+    classPrefix: string;
+    /** Override renderers keyed by node `type` or `command:<name>`. */
+    overrides: Map<string, HtmlRenderFn>;
+    /** Render arbitrary inline/block nodes to an HTML string. */
+    renderNodes: (nodes: Node[]) => string;
+    cls: (name: string) => string;
+}
+
+/**
+ * A command definition extended with optional per-target render functions.
+ * Passing `render.html` is shorthand for registering an HTML override keyed by
+ * `command:<name>` — the common case for a plugin command with no custom AST
+ * node (e.g. `\badge{...}`).
+ */
+interface EngineCommand extends CommandDefinition {
+    render?: {
+        html?: HtmlRenderFn;
+        react?: ReactRenderFn;
+    };
+}
+/**
+ * A ReTeX plugin. Everything is optional; a plugin may contribute commands,
+ * environments, icons, renderers, theme overrides, or run arbitrary setup
+ * against the engine. Plugins never touch global state — they mutate only the
+ * engine instance they are installed on.
+ */
+interface ReTeXPlugin {
+    name: string;
+    commands?: EngineCommand[];
+    environments?: EnvironmentDefinition[];
+    icons?: Record<string, IconDefinition>;
+    /** HTML overrides keyed by node `type` or `command:<name>`. */
+    htmlRenderers?: Record<string, HtmlRenderFn>;
+    /** React overrides keyed by node `type` or `command:<name>`. */
+    reactRenderers?: Record<string, ReactRenderFn>;
+    /** A theme patch applied when the plugin is installed. */
+    theme?: PartialTheme;
+    /** Imperative hook for advanced setup. */
+    setup?: (engine: PluginHost) => void;
+}
+/** The subset of the engine surface a plugin's `setup` hook may use. */
+interface PluginHost {
+    registerCommand(def: EngineCommand): PluginHost;
+    registerEnvironment(def: EnvironmentDefinition): PluginHost;
+    registerHtmlRenderer(key: string, fn: HtmlRenderFn): PluginHost;
+    registerReactRenderer(key: string, fn: ReactRenderFn): PluginHost;
+    registerIcon(name: string, def: IconDefinition): PluginHost;
+}
+
+/**
+ * A ReTeX **library** — a named, opt-in bundle of styling capability.
+ *
+ * ReTeX's core is deliberately blank: it ships document structure and basic
+ * emphasis only. Libraries add the rest. A library is just a {@link ReTeXPlugin}
+ * with a stable `name` so it can be activated two ways:
+ *
+ *  - declaratively, from the document: `\usepackage{colors}`
+ *  - programmatically, from code: `engine.use(colorsLibrary)`
+ *
+ * Built-in libraries: `fonts`, `shapes`, `colors`, and the theme packs `modern`,
+ * `classic`, `compact`. Custom libraries can be registered with
+ * `engine.provideLibrary(lib)` (available to `\usepackage`) or installed
+ * globally with `engine.use(lib)`.
+ */
+interface ReTeXLibrary extends ReTeXPlugin {
+    name: string;
+    /** One-line description, surfaced in docs and diagnostics. */
+    summary?: string;
+}
+
+/**
+ * Commands provided by the `colors` library: `\textcolor` (an explicit
+ * hex/named color) and `\themecolor` (a swatch from the active theme). Both
+ * produce core AST nodes, so the standard renderers display them once the
+ * library is active.
+ */
+declare const colorCommands: CommandDefinition[];
+/**
+ * A catalog of ready-made color palettes. Apply one as a theme patch, e.g.
+ * `new ReTeXEngine({ theme: { colors: palettes.violet } })`, or reference its
+ * swatches from `\themecolor{...}` once `colors` is active.
+ */
+declare const palettes: Record<string, ThemeColors>;
+/**
+ * The `colors` library — text color commands plus a palette catalog.
+ *
+ * ```ts
+ * engine.use(colorsLibrary);          // or \usepackage{colors}
+ * engine.toHtml("\\textcolor{#7c3aed}{Hi}");
+ * ```
+ */
+declare const colorsLibrary: ReTeXLibrary;
+
+/**
+ * Commands provided by the `fonts` library: explicit family/size control
+ * (`\fontfamily`, `\fontsize`), the relative size switches (`\small`, `\large`,
+ * `\Large`, `\Huge`, `\normalsize`), and the monospace switch (`\ttfamily`).
+ */
+declare const fontCommands: CommandDefinition[];
+/**
+ * A catalog of vetted font stacks. Use a key as a `\fontfamily` argument, or
+ * build a `fonts` theme patch with {@link fontTheme}.
+ */
+declare const fontStacks: Record<string, string>;
+/**
+ * Build a `fonts` theme patch from named {@link fontStacks} (or raw CSS stacks).
+ *
+ * ```ts
+ * new ReTeXEngine({ theme: { fonts: fontTheme({ heading: "spaceGrotesk", body: "inter" }) } });
+ * ```
+ */
+declare function fontTheme(spec: Partial<Record<keyof ThemeFonts, string>>): ThemeFonts;
+/**
+ * The `fonts` library — font family/size control plus a stack catalog.
+ *
+ * ```ts
+ * engine.use(fontsLibrary);            // or \usepackage{fonts}
+ * engine.toHtml("{\\large \\fontfamily{Georgia}{Hi}}");
+ * ```
+ */
+declare const fontsLibrary: ReTeXLibrary;
+
+/**
+ * Commands provided by the `shapes` library: horizontal rules / dividers in a
+ * few styles, plus explicit spacing. All produce core AST nodes.
+ */
+declare const shapeCommands: CommandDefinition[];
+/**
+ * The `shapes` library — rules, dividers, and spacing.
+ *
+ * ```ts
+ * engine.use(shapesLibrary);           // or \usepackage{shapes}
+ * engine.toHtml("\\hrule \\dashrule \\vspace{1em}");
+ * ```
+ */
+declare const shapesLibrary: ReTeXLibrary;
+
+/** `\usepackage{modern}` — accent-forward look with underlined headings. */
+declare const modernLibrary: ReTeXLibrary;
+/** `\usepackage{classic}` — restrained serif look for academic CVs. */
+declare const classicLibrary: ReTeXLibrary;
+/** `\usepackage{compact}` — dense, single-accent look. */
+declare const compactLibrary: ReTeXLibrary;
+
+/** Built-in libraries, keyed by their canonical (lowercase) name. */
+declare const builtinLibraries: Record<string, ReTeXLibrary>;
+/** Resolve a (possibly aliased / differently-cased) library name. */
+declare function resolveLibraryName(name: string): string | undefined;
+/** Look up a built-in library by name (accepts aliases). */
+declare function getBuiltinLibrary(name: string): ReTeXLibrary | undefined;
+/** All built-in library names, for docs / completion. */
+declare function builtinLibraryNames(): string[];
+/**
+ * Map of every gated command name → the library that provides it. Powers the
+ * "‹\textcolor› requires \usepackage{colors}" diagnostic. Derived from the
+ * library command lists so it can never drift out of sync.
+ */
+declare const GATED_COMMANDS: Record<string, string>;
+/** A resolver from a library name to a library object. */
+type LibraryLookup = (name: string) => ReTeXLibrary | undefined;
+/**
+ * Scan a token stream for `\usepackage{...}` / `\use{...}` directives and return
+ * the requested library names (in source order, de-duplicated). Used to decide
+ * which libraries to activate *before* parsing, since a directive must enable
+ * the commands that follow it.
+ */
+declare function usedLibraryNamesFromTokens(tokens: Token[]): string[];
+/** Collect library names from `\usepackage` nodes in a parsed document. */
+declare function usedLibraryNamesFromAst(root: Node): string[];
+interface AppliedLibraries {
+    /** A clone of the base registry with the resolved libraries' commands added. */
+    registry: CommandRegistry;
+    /** The libraries that resolved successfully, in order. */
+    libraries: ReTeXLibrary[];
+    /** Requested names that did not resolve to any library. */
+    missing: string[];
+}
+/**
+ * Clone `base` and register the commands/environments of every requested
+ * library that resolves via `lookup` (built-ins by default). Never mutates the
+ * base registry.
+ */
+declare function applyLibraries(base: CommandRegistry, names: string[], lookup?: LibraryLookup): AppliedLibraries;
+/** Fold each library's theme patch over a base theme, in order. */
+declare function mergeLibraryTheme(base: Theme, libraries: ReTeXLibrary[]): Theme;
+/**
+ * Refine a diagnostic list with library-awareness:
+ *
+ *  1. Replace the generic "unknown command" diagnostic for a *gated* command
+ *     (one that lives in a library) with a clear "import the library" message.
+ *  2. Flag unknown library names in `\usepackage{...}` directives.
+ *
+ * Shared by the engine and the editor so both give identical guidance.
+ */
+declare function libraryDiagnostics(ast: DocumentNode, diagnostics: Diagnostic[], lookup?: LibraryLookup): Diagnostic[];
+/** Collect HTML/React render overrides contributed by a set of libraries. */
+declare function collectLibraryOverrides(libraries: ReTeXLibrary[]): {
+    html: Map<string, HtmlRenderFn>;
+    react: Map<string, ReactRenderFn>;
+};
+
+export { resolveLibraryName as $, type AppliedLibraries as A, BLOCK_TYPES as B, CommandRegistry as C, type Diagnostic as D, type EngineCommand as E, getBuiltinLibrary as F, GATED_COMMANDS as G, type HtmlRenderFn as H, type IconDefinition as I, getIcon as J, hasIcon as K, type LibraryLookup as L, iconNames as M, type NodeBuilder as N, iconToSvg as O, type PluginHost as P, type QuickFix as Q, type ReTeXPlugin as R, SPECIAL_CHARS as S, type Token as T, isBlockNode as U, libraryDiagnostics as V, mergeLibraryTheme as W, modernLibrary as X, palettes as Y, registerIcon as Z, resolveIconName as _, type ReTeXLibrary as a, shapeCommands as a0, shapesLibrary as a1, usedLibraryNamesFromAst as a2, usedLibraryNamesFromTokens as a3, type EnvironmentDefinition as b, type ArgKind as c, type ArgSpec as d, type BuildContext as e, type BuilderUtils as f, type CommandCategory as g, type CommandDefinition as h, DiagnosticCode as i, DiagnosticSeverity as j, type EnvBuildContext as k, type EnvEntry as l, type HtmlRenderContext as m, TokenType as n, applyLibraries as o, builtinLibraries as p, builtinLibraryNames as q, classicLibrary as r, collectLibraryOverrides as s, colorCommands as t, colorsLibrary as u, compactLibrary as v, fontCommands as w, fontStacks as x, fontTheme as y, fontsLibrary as z };