@diagrammo/dgmo 0.63.0 → 0.64.1

package/dist/dgmo-router-Dd5PTjxl.d.ts

@@ -1,540 +0,0 @@
-type DgmoSeverity = 'error' | 'warning';
-interface DgmoError {
-    line: number;
-    column?: number;
-    message: string;
-    severity: DgmoSeverity;
-    /**
-     * Optional stable diagnostic code (e.g. 'E_ARROW_SUBSTRING_IN_LABEL').
-     * Additive; pre-existing diagnostics omit this field and existing
-     * substring-on-`.message` assertions keep working unchanged.
-     */
-    code?: string;
-}
-declare function makeDgmoError(line: number, message: string, severity?: DgmoSeverity, code?: string): DgmoError;
-/** Runtime params passed to `emit()` and forwarded to a message builder. */
-type DiagnosticParams = Record<string, unknown>;
-/**
- * Parameter type for a `DiagnosticSpec.message` builder body. Typed loosely
- * (`any`) on purpose: builders are hand-authored interpolation bags keyed by
- * ad-hoc names, and dgmo's tsconfig enables `noPropertyAccessFromIndexSignature`
- * (which forbids `p.name` dot-access on a `Record<string, unknown>`). Using
- * `any` here keeps builder bodies readable (`p.name`) instead of forcing
- * `p['name']` bracket access at every interpolation site.
- */
-type DiagnosticMessageParams = any;
-interface DiagnosticSpec {
-    /** Stable diagnostic code, e.g. `'E_MAP_UNKNOWN_PLACE'`. */
-    code: string;
-    /** Severity — must agree with the `E_`/`W_`/`I_` code prefix. */
-    severity: DgmoSeverity;
-    /** Owning chart type (`'map'`, `'swimlane'`, …) or `null` for universal/global codes. */
-    chartType: string | null;
-    /** Short human label for the catalog UI. */
-    title: string;
-    /**
-     * Canonical message wording. A plain string for static messages, or a
-     * builder `(params) => string` when the message interpolates runtime
-     * values. The builder must tolerate being called with `{}` so the
-     * catalog can show a representative message without live params.
-     */
-    message: string | ((params: DiagnosticMessageParams) => string);
-    /** Optional fix guidance shown alongside the message. */
-    hint?: string;
-    /** Minimal `.dgmo` source that triggers this diagnostic (for docs/console). */
-    example?: string;
-}
-/** Optional extras when emitting (currently just an explicit column). */
-interface EmitOptions {
-    column?: number;
-}
-/**
- * Emit a diagnostic from its `DiagnosticSpec`. The code, severity, and
- * canonical wording all come from the spec — call sites supply only the
- * line and the interpolation params, so the code/severity can never drift
- * out of sync with the declared spec. Replaces the per-parser
- * `push`/`err`/`fail` wrappers that each re-declared this shape.
- */
-declare function emit(spec: DiagnosticSpec, line: number, params?: DiagnosticParams, opts?: EmitOptions): DgmoError;
-declare function formatDgmoError(err: DgmoError): string;
-
-/**
- * Compact view state schema (ADR-6).
- * All fields optional. Only non-default values are encoded.
- * `tag: null` means "user chose none"; absent `tag` means "use DSL default" (ADR-5).
- */
-interface CompactViewState {
-    tag?: string | null;
-    cs?: number[];
-    cg?: string[];
-    swim?: string | null;
-    cl?: string[];
-    cc?: string[];
-    rm?: string;
-    htv?: Record<string, string[]>;
-    ha?: string[];
-    sem?: boolean;
-    cm?: boolean;
-    c4l?: string;
-    c4s?: string;
-    c4c?: string;
-    rps?: number;
-    spd?: number;
-    io?: Record<string, number>;
-    hd?: boolean;
-    cbd?: boolean;
-    rq?: string;
-    an?: boolean;
-    fl?: boolean;
-}
-interface DecodedDiagramUrl {
-    dsl: string;
-    viewState: CompactViewState;
-    palette?: string;
-    theme?: 'light' | 'dark';
-    filename?: string;
-}
-interface EncodeDiagramUrlOptions {
-    baseUrl?: string;
-    viewState?: CompactViewState;
-    palette?: string;
-    theme?: 'light' | 'dark';
-    filename?: string;
-}
-type EncodeDiagramUrlResult = {
-    url: string;
-    error?: undefined;
-} | {
-    url?: undefined;
-    error: 'too-large';
-    compressedSize: number;
-    limit: number;
-};
-/**
- * Encode a CompactViewState to a compressed string for URL embedding.
- * Returns empty string if state has no keys (ADR-4).
- */
-declare function encodeViewState(state: CompactViewState): string;
-/**
- * Decode a compressed view state string back to CompactViewState.
- * Returns empty object on failure (no crash).
- */
-declare function decodeViewState(encoded: string): CompactViewState;
-/**
- * Compress a DGMO DSL string into a shareable URL.
- * Returns `{ url }` on success, or `{ error: 'too-large', compressedSize, limit }` if the
- * compressed payload exceeds the 8 KB limit.
- */
-declare function encodeDiagramUrl(dsl: string, options?: EncodeDiagramUrlOptions): EncodeDiagramUrlResult;
-/**
- * Decode a DGMO DSL string and view state from a URL query string or hash.
- * Accepts any of:
- *   - `?dgmo=<payload>&vs=<state>`
- *   - `#dgmo=<payload>&vs=<state>` (backwards compat)
- *   - `dgmo=<payload>`
- *   - `<bare payload>`
- *
- * Returns `{ dsl, viewState }`. The DSL is empty string on invalid input.
- */
-declare function decodeDiagramUrl(hash: string): DecodedDiagramUrl;
-
-/**
- * Color definitions for a single mode (light or dark).
- * 10 semantic UI colors + 9 named accent colors = 19 total.
- *
- * `readonly` on every field (and the nested `colors` map) by design —
- * palettes flow from the registry into every renderer; nothing in the
- * pipeline should ever mutate a palette in place.
- */
-interface PaletteColors {
-    /** Main background (#eceff4 light / #2e3440 dark for Nord) */
-    readonly bg: string;
-    /** Cards, panels (#e5e9f0 / #3b4252) */
-    readonly surface: string;
-    /** Popovers, dropdowns (#e5e9f0 / #434c5e) */
-    readonly overlay: string;
-    /** Borders, dividers, muted (#d8dee9 / #4c566a) */
-    readonly border: string;
-    /** Primary text (#2e3440 / #eceff4) */
-    readonly text: string;
-    /** Secondary/diminished text (#4c566a / #d8dee9) */
-    readonly textMuted: string;
-    /**
-     * Light-mode arg for `contrastText()` when text is rendered on a
-     * tinted shape fill (e.g. `shapeFill()` output). Must guarantee
-     * ≥ 4.5:1 WCAG AA against any `shapeFill()` the palette can produce.
-     * Distinct from `colors.white` because palette-aesthetic anchors don't
-     * always meet contrast requirements (TD-5).
-     */
-    readonly textOnFillLight: string;
-    /** Dark-mode counterpart to `textOnFillLight`. */
-    readonly textOnFillDark: string;
-    /** Primary accent — buttons, links */
-    readonly primary: string;
-    /** Secondary accent */
-    readonly secondary: string;
-    /** Tertiary accent */
-    readonly accent: string;
-    /** Error/danger */
-    readonly destructive: string;
-    /**
-     * Used for: inline annotations (red), pie charts, cScale,
-     * series rotation, journey actors, Gantt tasks.
-     */
-    readonly colors: {
-        readonly red: string;
-        readonly orange: string;
-        readonly yellow: string;
-        readonly green: string;
-        readonly blue: string;
-        readonly purple: string;
-        readonly teal: string;
-        readonly cyan: string;
-        readonly gray: string;
-        readonly black: string;
-        readonly white: string;
-    };
-}
-/**
- * Complete palette definition. One object per color scheme.
- * This is what palette authors create — the single artifact for NFR1.
- *
- * Palettes are immutable from the consumer's perspective; the registry
- * hands out the same frozen-shape object on every `getPalette(id)`.
- */
-interface PaletteConfig {
-    /** Registry key: 'nord', 'slate', 'catppuccin' */
-    readonly id: string;
-    /** Display name: 'Nord', 'Slate', 'Catppuccin' */
-    readonly name: string;
-    /** Light mode color definitions */
-    readonly light: PaletteColors;
-    /** Dark mode color definitions */
-    readonly dark: PaletteColors;
-}
-
-/** A single entry inside a tag group: `Value color` */
-interface TagEntry {
-    readonly value: string;
-    readonly color: string;
-    /**
-     * The color NAME the author wrote (one of the recognized palette names),
-     * when the entry declared an explicit color. Absent for bare/auto-colored
-     * entries. `color` above is always the RESOLVED hex (auto and explicit are
-     * indistinguishable there); this preserves the authored-vs-auto distinction
-     * so a GUI editor can round-trip an explicit color through a reparse.
-     */
-    readonly authoredColor?: string;
-    readonly lineNumber: number;
-}
-/**
- * A tag group block: heading + entries.
- *
- * Parser internals build via `Writable<TagGroup>` from `utils/brand.ts`;
- * once returned to a chart-type parser, consumers see the readonly view.
- */
-interface TagGroup {
-    readonly name: string;
-    readonly alias?: string;
-    readonly entries: readonly TagEntry[];
-    /** Default value for nodes without explicit metadata. First entry unless another is marked `default`. */
-    readonly defaultValue?: string;
-    readonly lineNumber: number;
-}
-/**
- * DOM-safe key for a tag group — used wherever the group name becomes a
- * `data-tag-*` attribute suffix, an entity metadata key, or an `active-tag`
- * match target. For a single-identifier name (the only form the parser used to
- * accept) this is exactly `name.toLowerCase()`, so swapping it in for existing
- * diagrams is byte-identical. A quoted multi-word name (`tag "Trust Zone" as tz`)
- * slugs to a hyphenated identifier (`trust-zone`) so it never produces an
- * invalid DOM attribute name; the original `name` is kept for the legend label.
- */
-declare function tagAttrKey(name: string): string;
-/**
- * The categorical name cycle used to auto-assign colors to bare tag values,
- * in deterministic order. Aliased to the shared {@link CATEGORICAL_COLOR_ORDER}
- * (RGB-seeded, max-contrast, neutrals excluded) so tag swatches and data-chart
- * series colors share one canonical rotation. If a group has more colorless
- * entries than free categorical names, the cycle wraps.
- */
-declare const autoTagColorCycle: readonly string[];
-
-/** Validate that a hex string is well-formed (#RGB or #RRGGBB). */
-declare function isValidHex(value: string): boolean;
-/**
- * Register a palette. Called at module initialization.
- * Validates that all 19 color fields per mode are present and valid hex.
- * Throws on malformed palettes to catch errors at startup, not at render time.
- */
-declare function registerPalette(palette: PaletteConfig): void;
-/** Get palette by id. Silently returns the default palette if id is unrecognized. */
-declare function getPalette(id: string): PaletteConfig;
-/**
- * Resolve a palette by id, falling back to the default palette when the id is
- * unregistered. If a `warn` callback is supplied, it is invoked once with a
- * human-readable fallback message on a miss — the single place the "resolve,
- * fall back, warn" policy lives, so each host can surface it its own way
- * (console.warn, Obsidian Notice, MCP response). Silent when the id resolves or
- * when no callback is passed.
- */
-declare function resolvePaletteOrFallback(id: string, warn?: (message: string) => void): PaletteConfig;
-/** List all registered palettes alphabetically (for the selector UI). */
-declare function getAvailablePalettes(): PaletteConfig[];
-
-interface ChartTypeMeta {
-    readonly id: string;
-    readonly description: string;
-    readonly fallback?: true;
-    /**
-     * Routable but never OFFERED. The type parses, routes and renders like any
-     * other, but no surface that enumerates types for a human or a model may list
-     * it — nobody hand-authors one, so a picker entry would produce a file the
-     * user cannot complete.
-     *
-     * Honoured at five edges, and deliberately NOT inside `getAllChartTypes()`,
-     * which keeps meaning "everything routable":
-     *   1. `cli.ts` — `dgmo types` (plain and `--json`)
-     *   2. `completion-registry.ts` — the chart-type completion popup
-     *   3. `dgmo-mcp/src/index.ts` — the `list_chart_types` tool
-     *   4. `dgmo-mcp/src/suggest/scoring.ts` — the suggester's candidate pool
-     *   5. `scripts/gen-ai-core.mjs` — the generated AI core every model reads
-     * `tests/internal-chart-types.test.ts` is this flag's specification; without
-     * it the flag is a convention and the next refactor drops an edge silently.
-     */
-    readonly internal?: true;
-}
-declare const chartTypesData: readonly [{
-    readonly id: "journey-map";
-    readonly description: "User experience flow with emotion scores, phases, and annotations";
-}, {
-    readonly id: "c4";
-    readonly description: "System architecture (context, container, component, deployment)";
-}, {
-    readonly id: "er";
-    readonly description: "Database schemas and relationships";
-}, {
-    readonly id: "class";
-    readonly description: "UML class hierarchies";
-}, {
-    readonly id: "sequence";
-    readonly description: "Message request and response interaction flows";
-    readonly fallback: true;
-}, {
-    readonly id: "state";
-    readonly description: "State machine / lifecycle transitions";
-}, {
-    readonly id: "infra";
-    readonly description: "Infrastructure traffic flow with RPS computation";
-}, {
-    readonly id: "gantt";
-    readonly description: "Project scheduling with task dependencies and milestones";
-}, {
-    readonly id: "pert";
-    readonly description: "Project network with three-point estimates, critical path, and uncertainty (Beta-PERT, Monte Carlo)";
-}, {
-    readonly id: "swimlane";
-    readonly description: "Cross-functional process flow with lanes, phases and gateways (BPMN-style)";
-}, {
-    readonly id: "version-control";
-    readonly description: "Git / version-control branch-and-merge graph: commits, branches, merges, rebase, HEAD and remote-tracking (gitGraph-style)";
-}, {
-    readonly id: "timeline";
-    readonly description: "Events, eras, and date ranges";
-}, {
-    readonly id: "event-line";
-    readonly description: "Annotated narrative timeline — events on a horizontal line with descriptions (not the date-scaled timeline)";
-}, {
-    readonly id: "body";
-    readonly description: "Human anatomy figure annotated by muscle/bone/joint name — for medical, exercise, and educational diagrams";
-}, {
-    readonly id: "org";
-    readonly description: "Reporting hierarchy";
-}, {
-    readonly id: "family";
-    readonly description: "Family tree / genealogy: unions (couples), children, remarriage, adoption, and GEDCOM-style metadata";
-}, {
-    readonly id: "sitemap";
-    readonly description: "Site / app navigation structure";
-}, {
-    readonly id: "bracket";
-    readonly description: "Single-elimination tournament bracket: winners auto-advance up a tree; seed the field for a day-0 skeleton or list results for a casual bracket, with two sides mirroring inward to a championship";
-}, {
-    readonly id: "kanban";
-    readonly description: "Task board columns";
-}, {
-    readonly id: "raci";
-    readonly description: "Tasks × roles responsibility matrix with constraint linting";
-}, {
-    readonly id: "tech-radar";
-    readonly description: "Technology adoption quadrants (adopt/trial/assess/hold)";
-}, {
-    readonly id: "mindmap";
-    readonly description: "Radial hierarchy of ideas branching from a central topic";
-}, {
-    readonly id: "wireframe";
-    readonly description: "Low-fidelity UI layout with panels, controls, and annotations";
-}, {
-    readonly id: "cycle";
-    readonly description: "Cyclical process visualization (PDCA, OODA, DevOps loops)";
-}, {
-    readonly id: "pyramid";
-    readonly description: "Stacked hierarchy of layers with descriptions (Maslow, DIKW)";
-}, {
-    readonly id: "ring";
-    readonly description: "Concentric rings showing nested or hierarchical categories (read core-out)";
-}, {
-    readonly id: "treemap";
-    readonly description: "Nested rectangles sized by value — show a hierarchy’s proportions (budgets, disk usage, portfolios) with color by category, value heatmap, or branch";
-}, {
-    readonly id: "block";
-    readonly description: "Block diagram: an author-controlled grid of rectangular blocks with nested, collapsible containers — system/hardware/architecture layouts where the 2-D arrangement is the meaning";
-}, {
-    readonly id: "sketch";
-    readonly description: "GUI-first constrained canvas: uniformly-sized shapes placed freely on a snap grid, arrows between them, meaning through tags — the markup is generated by the canvas editor";
-}, {
-    readonly id: "goal";
-    readonly description: "Single progress-toward-a-target value (now vs target) as a progress bar, thermometer, or gauge — KPIs, fundraising, quotas, completion";
-}, {
-    readonly id: "countdown";
-    readonly description: "Live \"N days until X\" that ticks every second and is accurate on every load — trip dates, launches, deadlines; the only dynamic chart type";
-}, {
-    readonly id: "clock";
-    readonly description: "Live world-clock board: current time for people/places across time zones, ticking every second, with optional working-hours status and sundown line";
-}, {
-    readonly id: "map";
-    readonly description: "Geographic concept map: highlight/score regions, drop points of interest, connect with routes or edges";
-}, {
-    readonly id: "quadrant";
-    readonly description: "2x2 positioning matrix";
-}, {
-    readonly id: "venn";
-    readonly description: "Set overlaps";
-}, {
-    readonly id: "funnel";
-    readonly description: "Conversion pipeline";
-}, {
-    readonly id: "slope";
-    readonly description: "Change between 2 time periods";
-}, {
-    readonly id: "sankey";
-    readonly description: "Flow / allocation visualization";
-}, {
-    readonly id: "arc";
-    readonly description: "Network relationships (linear or circular via `layout`)";
-}, {
-    readonly id: "wordcloud";
-    readonly description: "Term frequency visualization";
-}, {
-    readonly id: "heatmap";
-    readonly description: "Matrix intensity visualization";
-}, {
-    readonly id: "function";
-    readonly description: "Mathematical expressions";
-}, {
-    readonly id: "bar";
-    readonly description: "Categorical comparisons for 3 - 5 figures";
-    readonly fallback: true;
-}, {
-    readonly id: "line";
-    readonly description: "Trends over time";
-    readonly fallback: true;
-}, {
-    readonly id: "pie";
-    readonly description: "Part-to-whole proportions";
-}, {
-    readonly id: "radar";
-    readonly description: "Multi-dimensional metrics";
-}, {
-    readonly id: "polar-area";
-    readonly description: "Radial bar chart";
-}, {
-    readonly id: "scatter";
-    readonly description: "2D data points or bubble chart";
-}, {
-    readonly id: "flowchart";
-    readonly description: "Decision trees and process flows";
-    readonly fallback: true;
-}, {
-    readonly id: "boxes-and-lines";
-    readonly description: "General-purpose node-edge diagrams with groups and tags";
-    readonly fallback: true;
-}, {
-    readonly id: "live-link";
-    readonly description: "A pointer to a diagram published at Diagrammo Cloud";
-    readonly internal: true;
-}];
-/**
- * Every chart type the router can dispatch — the "routable" set.
- *
- * Distinct from the "offered" set (`utils/offered-types.ts`), which drops the
- * `internal` types nobody hand-authors. A live link is routable but never
- * offered.
- *
- * This union is the reason the id list lives here: `chart-type-registry.ts`
- * keys its `Record` by it, so a chart type missing from the registry is a
- * compile error, and `ALL_CHART_TYPES` / the editor's `CHART_TYPES` derive from
- * the same array rather than restating it.
- */
-type ChartTypeId = (typeof chartTypesData)[number]['id'];
-declare const chartTypes: readonly ChartTypeMeta[];
-
-/** User-visible rendering category for dispatch and routing. */
-type RenderCategory = 'data-chart' | 'visualization' | 'diagram';
-
-/**
- * Extracts the chart type from raw file content.
- * First tries the first non-empty, non-comment line as a bare chart type name
- * (e.g., `gantt Product Launch`).
- * Falls back to inference when no explicit chart type is found.
- */
-declare function parseDgmoChartType(content: string): string | null;
-
-/**
- * Returns the render category for a given chart type, or `null` if unknown.
- * Use this instead of the internal framework map for dispatch in consumers.
- */
-declare function getRenderCategory(chartType: string): RenderCategory | null;
-/**
- * Returns true if the chart type is an extended chart type
- * handled by parseExtendedChart (scatter, sankey, function, heatmap, funnel).
- * Returns false for standard chart types and all other types.
- */
-declare function isExtendedChartType(chartType: string): boolean;
-/**
- * Returns all supported chart type identifiers in canonical (tier) order,
- * derived from `chartTypes`. Consumers that need alphabetical order should
- * call `.sort()` explicitly.
- */
-declare function getAllChartTypes(): string[];
-/**
- * Canonical descriptions for every supported chart type. Derived from
- * `chartTypes` so there is exactly one place to update when adding a new
- * type. Consumed by the CLI `dgmo types` command, the editor autocomplete
- * popup, and the MCP `list_chart_types` tool.
- */
-declare const CHART_TYPE_DESCRIPTIONS: Record<string, string>;
-type ParseResult = {
-    diagnostics: readonly DgmoError[];
-};
-type ParseFn = (content: string) => ParseResult;
-/**
- * Maps every chart-type id to the parser that handles it, DERIVED from
- * `CHART_TYPE_REGISTRY` (src/chart-type-registry.ts). Adding a new chart type
- * means adding ONE descriptor there plus its `chartTypes` metadata entry; the
- * `chart-type-registry.test.ts` cross-check asserts the registry, `chartTypes`,
- * the render-category sites, and the export handlers all stay in sync.
- */
-declare const chartTypeParsers: ReadonlyArray<readonly [string, ParseFn]>;
-/** Ids in the same order as `chartTypeParsers`; used for cross-checks. */
-declare const knownChartTypeIds: readonly string[];
-/**
- * Parse DGMO content and return diagnostics without rendering.
- * Useful for the CLI and editor to surface all errors before attempting render.
- */
-declare function parseDgmo(content: string): {
-    diagnostics: DgmoError[];
-    chartType: string | null;
-};
-
-export { isExtendedChartType as A, isValidHex as B, type CompactViewState as C, type DiagnosticSpec as D, type EmitOptions as E, knownChartTypeIds as F, makeDgmoError as G, parseDgmoChartType as H, registerPalette as I, tagAttrKey as J, type PaletteConfig as P, type RenderCategory as R, type TagGroup as T, type DgmoError as a, type ChartTypeId as b, type ChartTypeMeta as c, type DgmoSeverity as d, type DiagnosticParams as e, type PaletteColors as f, chartTypes as g, emit as h, formatDgmoError as i, getPalette as j, type TagEntry as k, CHART_TYPE_DESCRIPTIONS as l, type DecodedDiagramUrl as m, type EncodeDiagramUrlOptions as n, type EncodeDiagramUrlResult as o, parseDgmo as p, autoTagColorCycle as q, resolvePaletteOrFallback as r, chartTypeParsers as s, decodeDiagramUrl as t, decodeViewState as u, encodeDiagramUrl as v, encodeViewState as w, getAllChartTypes as x, getAvailablePalettes as y, getRenderCategory as z };