mayacharts 0.1.0

package/dist/core/marks/dumbbell.d.ts

@@ -0,0 +1,3 @@
+import type { Mark } from "../types.ts";
+/** Two dots per category (series 0 = from, 1 = to) joined by a connector toned by colorBy "sign". */
+export declare const dumbbell: Mark;

package/dist/core/marks/heatmap.d.ts

@@ -0,0 +1,3 @@
+import type { Mark } from "../types.ts";
+/** x = column category, series = row category; ramp legend; labels default on at >= 24 px. */
+export declare const heatmap: Mark;

package/dist/core/marks/kpi.d.ts

@@ -0,0 +1,2 @@
+import type { Mark } from "../types.ts";
+export declare const kpi: Mark;

package/dist/core/marks/line.d.ts

@@ -0,0 +1,4 @@
+import type { Mark } from "../types.ts";
+/** Line and area share one file: crosshair contract, stack for area. */
+export declare const line: Mark;
+export declare const area: Mark;

package/dist/core/marks/scatter.d.ts

@@ -0,0 +1,2 @@
+import type { Mark } from "../types.ts";
+export declare const scatter: Mark;

package/dist/core/registry.d.ts

@@ -0,0 +1,13 @@
+import type { Mark } from "./types.ts";
+export declare const VERSION = "0.1.0";
+export declare const MAJOR = "0";
+/** type -> Mark for every registered module type (shared across bundles). */
+export declare const MODULES: Map<string, Mark>;
+/** Types that ship in core (static CORE map in render.ts). */
+export declare const CORE_TYPES: readonly ["bar", "line", "area", "scatter", "heatmap", "waterfall", "kpi", "dumbbell"];
+/** Module types and the import that provides them (for the unknown-type hint). */
+export declare const MODULE_OF: Readonly<Record<string, string>>;
+/** Not exported from the public entry: modules call it on import. First wins. */
+export declare function register(type: string, mark: Mark): void;
+/** Registered module types. */
+export declare const types: () => string[];

package/dist/core/render.d.ts

@@ -0,0 +1,8 @@
+import type { ChartSpec, Parts, RenderOptions, Row } from "./types.ts";
+export declare function renderParts<R extends object = Row>(spec: ChartSpec<R> | ChartSpec, opts?: RenderOptions): Parts;
+/** Standalone SVG string with an embedded stylesheet. */
+export declare function render<R extends object = Row>(spec: ChartSpec<R> | ChartSpec, opts?: RenderOptions): string;
+/** Inner shadow-root markup, shared by renderShell and the element. Fixed slot order. */
+export declare function shellInner(parts: Parts, css: string, nonce?: string): string;
+/** `<maya-chart>` with Declarative Shadow DOM. JSON child escapes `<` as <. */
+export declare function renderShell<R extends object = Row>(spec: ChartSpec<R> | ChartSpec, opts?: RenderOptions): string;

package/dist/core/scale.d.ts

@@ -0,0 +1,3 @@
+import type { BandScale, LinearScale } from "./types.ts";
+export declare function bandScale(domain: readonly string[], range: readonly [number, number], padInner?: number, padOuter?: number): BandScale;
+export declare function linearScale(domain: readonly [number, number], range: readonly [number, number]): LinearScale;

package/dist/core/shape.d.ts

@@ -0,0 +1,14 @@
+import type { Aggregate, ResolvedSpec, Shaped, View } from "./types.ts";
+/** Reducer for one aggregate; shared with hierarchy.ts. Empty: null (count: 0). */
+export declare function agg(kind: Aggregate): {
+    add(v: number): void;
+    value(): number | null;
+};
+interface Opts {
+    hidden?: readonly string[];
+    window?: View["window"];
+}
+export declare function shape(s: ResolvedSpec, o?: Opts | readonly string[]): Shaped;
+/** colorBy field aggregated per (category, series) like the marks; null without a field colorBy. */
+export declare function colorVals(s: ResolvedSpec): (c: string, ser: string) => number | null;
+export {};

package/dist/core/strings.d.ts

@@ -0,0 +1,37 @@
+export declare const TEXT: {
+    readonly noData: "No data";
+    readonly other: "Other";
+    readonly back: "Back";
+    readonly reset: "Reset zoom";
+    /** Live region after a measure toggle: {0} = measure title. */
+    readonly showing: "Showing {0}";
+    /** Live region after drill: {0} = branch path joined with " / ". */
+    readonly drilledInto: "Drilled into {0}";
+    /** Live region after zoom: {0}, {1} = first and last category (or range ends). */
+    readonly zoomedTo: "Zoomed to {0} – {1}";
+    /** Live region after selection: {0} = count. */
+    readonly selected: "{0} selected";
+    readonly selectionCleared: "Selection cleared";
+    /** Auto description: {0} = noun, {1} = y title, {2} = x title. */
+    readonly chartOf: "{0} chart of {1} by {2}";
+    /** Table caption when rows are capped: {0} = shown, {1} = total. */
+    readonly firstOf: "First {0} of {1} rows";
+    /** aria-label of the measure radiogroup. */
+    readonly measures: "Measure";
+    /** aria-label of the breadcrumb nav. */
+    readonly crumbs: "Drill path";
+    /** Tone text (never colour alone): colorBy "sign" and { target }. */
+    readonly positive: "positive";
+    readonly negative: "negative";
+    readonly above: "above target";
+    readonly below: "below target";
+    /** kpi delta: {0} = signed change, {1} = previous period. */
+    readonly vs: "{0} vs {1}";
+    /** kpi bullet: {0} = share of target, {1} = target. */
+    readonly ofTarget: "{0} of target {1}";
+};
+export type TextKey = keyof typeof TEXT;
+/** Localised string for `key` with `{n}` placeholders filled from `args`. */
+export declare function t(spec: {
+    text?: Partial<Record<TextKey, string>> | undefined;
+}, key: TextKey, ...args: (string | number)[]): string;

package/dist/core/svg.d.ts

@@ -0,0 +1,13 @@
+export declare function esc(s: string | number): string;
+export declare function r(n: number): number;
+export declare function el(tag: string, attrs: Record<string, string | number | boolean | null | undefined>, children?: string): string;
+/** Sentinel category for `limit`'s rolled-up rest. Cannot collide with real data text. */
+export declare const OTHER = "\0other";
+/**
+ * Mark identity: each part `encodeURIComponent`ed (lone surrogates replaced, `~` -> %7E),
+ * joined by `~`. Grammar: band `S~C`; line/area `l~S`/`a~S`; scatter `S~name` (or index);
+ * hierarchy `h~p0~p1…`; sankey node `n~depth~name`, link `k~depth~src~dst`; hexmap `g~CODE`.
+ */
+export declare const key: (...parts: unknown[]) => string;
+/** Invisible target grown to >= 24 px around a small rect mark; "" when it is big enough. */
+export declare function hit(d: Parameters<typeof el>[1], x: number, y: number, w: number, h: number): string;

package/dist/core/ticks.d.ts

@@ -0,0 +1,2 @@
+import type { Ticks } from "./types.ts";
+export declare function niceTicks(min: number, max: number, target?: number): Ticks;

package/dist/core/types.d.ts

@@ -0,0 +1,424 @@
+import type { TextKey } from "./strings.ts";
+export type { TextKey };
+/** A data row. Field values are read by name via `spec.x`, `spec.y`, `spec.series`… */
+export type Row = Readonly<Record<string, string | number | boolean | null | undefined>>;
+export type ChartType = "bar" | "line" | "area" | "scatter" | "heatmap" | "waterfall" | "kpi" | "dumbbell" | "treemap" | "sunburst" | "sankey" | "hexmap";
+export type Aggregate = "sum" | "mean" | "count" | "min" | "max";
+export type NumberPreset = "auto" | "integer" | "decimal" | "compact" | "percent" | "currency";
+export type DatePreset = "date" | "month" | "year" | "time" | "datetime";
+export type FormatPreset = NumberPreset | DatePreset;
+/** Text added around a formatted value. */
+export interface Affix {
+    prefix?: string;
+    suffix?: string;
+}
+/**
+ * One field's format: a preset, or Intl options plus `prefix`/`suffix`. Options holding
+ * any date key (`year`, `month`, `dateStyle`, `timeZone`…) are date options; else number.
+ */
+export type FieldFormat = FormatPreset | (Intl.NumberFormatOptions & Affix) | (Intl.DateTimeFormatOptions & Affix);
+export type ThemeToken = "font" | "fontSize" | "fg" | "fgMuted" | "grid" | "bg" | "accent" | "radius" | "tooltipBg" | "tooltipFg" | "focus" | "good" | "bad" | "series1" | "series2" | "series3" | "series4" | "series5" | "series6" | "series7" | "series8";
+/** Field names of row type `R` (autocompletes for typed rows; `string` for `Row`). */
+export type Field<R> = Extract<keyof R, string>;
+/**
+ * The whole public API surface. Plain JSON on purpose: it must stay serializable,
+ * LLM-generatable, diffable and hashable. Never add function-valued options.
+ * Rule: `x` is always the category and `y` always the value, whatever the orientation.
+ */
+export interface ChartSpec<R extends object = Row> {
+    /** Ignored; lets editors and LLMs find the JSON schema.
+     * @example "$schema": "https://unpkg.com/mayacharts/schema.json" */
+    $schema?: string;
+    /** Chart type. treemap/sunburst need `mayacharts/hierarchy`, sankey `flow`, hexmap `geo`.
+     * @example type: "bar" */
+    type: ChartType;
+    /** Row objects.
+     * @example data: [{ month: "Jan", revenue: 10 }] */
+    data: readonly R[];
+    /** How rows sharing a (category, series) combine. `count` counts non-null y. Default "sum".
+     * @example aggregate: "mean" */
+    aggregate?: Aggregate;
+    /** Order categories by total across all series (hidden ones too). Default: data order.
+     * @example sort: "desc" */
+    sort?: "asc" | "desc";
+    /** Keep the top N categories by total; the rest roll up into a final "Other".
+     * @example limit: 10 */
+    limit?: number;
+    /** Category field (scatter: numeric x; hexmap: US state; kpi: optional period, last one is the headline). Not used by path types.
+     * @example x: "month" */
+    x?: Field<R>;
+    /** Value field; an array adds a measure toggle, first one active.
+     * @example y: ["revenue", "units"] */
+    y: Field<R> | readonly Field<R>[];
+    /** Splits rows into series (heatmap: the row category; dumbbell: exactly two, from and to). bar line area scatter heatmap dumbbell.
+     * @example series: "region" */
+    series?: Field<R>;
+    /** Hierarchy fields, outer to inner. treemap sunburst sankey; bar/line/area with `drill` (replaces `x`).
+     * @example path: ["region", "state"] */
+    path?: readonly Field<R>[];
+    /** Bubble area field (sqrt scale). scatter only.
+     * @example size: "population" */
+    size?: Field<R>;
+    /** Point identity and tooltip title. scatter only.
+     * @example name: "country" */
+    name?: Field<R>;
+    /** x values drawn as running-total bars. waterfall only.
+     * @example totals: ["Q1", "FY"] */
+    totals?: readonly string[];
+    /** Stack series instead of grouping them. bar and area only.
+     * @example stack: true */
+    stack?: boolean;
+    /** Categories on the left axis. bar and dumbbell.
+     * @example horizontal: true */
+    horizontal?: boolean;
+    /** Second value field, drawn as a line on a right axis over the bars. Vertical bar only.
+     * @example y2: "units" */
+    y2?: Field<R>;
+    /** A preset for every `y`, or a preset / Intl options per field. Display only.
+     * @example format: { revenue: "currency", month: "month", margin: { style: "percent", suffix: " gm" } } */
+    format?: FormatPreset | Readonly<Partial<Record<Field<R>, FieldFormat>>>;
+    /** Display names by field: axis titles (shown only when set), tooltip, legend, table.
+     * @example titles: { revenue: "Revenue ($)" } */
+    titles?: Readonly<Partial<Record<Field<R>, string>>>;
+    /** Formatted values on marks. Default false (heatmap: true when cells are ≥ 24 px).
+     * @example labels: true */
+    labels?: boolean;
+    /** Localised UI strings with `{0}` placeholders (see strings.ts for keys).
+     * @example text: { noData: "Keine Daten", back: "Zurück" } */
+    text?: Readonly<Partial<Record<TextKey, string>>>;
+    /** BCP 47 locale for formatting. Default "en-US" (deterministic SSR).
+     * @example locale: "de-DE" */
+    locale?: string;
+    /** ISO 4217 code for the "currency" preset. Default "USD".
+     * @example currency: "EUR" */
+    currency?: string;
+    /** Visible heading, also the accessible name.
+     * @example title: "Revenue by month" */
+    title?: string;
+    /** Accessible description; auto-generated when omitted.
+     * @example description: "Revenue doubled from January to December." */
+    description?: string;
+    /** Fixed value-axis domain. Not allowed with a `y` array.
+     * @example yDomain: [0, 100] */
+    yDomain?: readonly [number, number];
+    /** Fixed x domain. scatter only.
+     * @example xDomain: [0, 1] */
+    xDomain?: readonly [number, number];
+    /** Hover/keyboard tooltip. Default true.
+     * @example tooltip: false */
+    tooltip?: boolean;
+    /** Legend; clicking toggles series. Default: true when `series` is set.
+     * @example legend: false */
+    legend?: boolean;
+    /** Click/Enter zooms into a branch of `path`; breadcrumb, Back and Escape pop.
+     * @example drill: true */
+    drill?: boolean;
+    /** Click/Enter/legend selects marks, others dim; Escape clears. Not with `drill`.
+     * @example select: "multi" */
+    select?: true | "multi";
+    /** Drag to zoom. line, area, scatter. Reset chip, double-click and Escape restore.
+     * @example zoom: true */
+    zoom?: boolean;
+    /** Animate updates (element only). Default true.
+     * @example animate: false */
+    animate?: boolean;
+    /** Palette in series order (max 8), or colours by series value.
+     * @example colors: { North: "#0b6", South: "oklch(.6 .17 30)" } */
+    colors?: readonly string[] | Readonly<Record<string, string>>;
+    /** Tone by sign of y, by a target, or a ramp by a numeric field. Not with `series` (dumbbell: "sign" of to minus from; kpi: target only, drawn as a bullet bar).
+     * @example colorBy: { target: 100 } */
+    colorBy?: "sign" | {
+        readonly target: number;
+    } | Field<R>;
+    /** Theme token overrides (CSS values, allowlisted).
+     * @example theme: { accent: "#0b6", font: "'Inter', sans-serif" } */
+    theme?: Readonly<Partial<Record<ThemeToken, string>>>;
+    /** Grid lines perpendicular to the value axis. Default true.
+     * @example grid: false */
+    grid?: boolean;
+    /** Bottom axis. Default true.
+     * @example xAxis: false */
+    xAxis?: boolean;
+    /** Left axis. Default true.
+     * @example yAxis: false */
+    yAxis?: boolean;
+    /** Visually hidden data table for screen readers. Default true.
+     * @example table: false */
+    table?: boolean;
+}
+/** A selected mark, by raw values (never formatted text). */
+export interface Sel {
+    x?: unknown;
+    series?: unknown;
+    name?: unknown;
+}
+/** Interaction state outside the spec. SSR can render any of it. */
+export interface View {
+    /** Active index into a `y` array. */
+    measure?: number;
+    /** Drilled branch: one raw value per `path` level, outer first. */
+    drill?: readonly string[];
+    /** Zoom: category index slice [i0, i1] (inclusive), or scatter box [x0, x1, y0, y1]. */
+    window?: readonly [number, number] | readonly [number, number, number, number];
+    /** Series keys hidden by the legend. */
+    hidden?: readonly string[];
+}
+export interface RenderOptions {
+    /** Pixel size of the plot box. Default 640 x 320. */
+    width?: number;
+    height?: number;
+    view?: View;
+    selected?: readonly Sel[];
+    /** CSP nonce for the shell's `<style>` (renderShell). */
+    nonce?: string;
+}
+export interface MayaSelectDetail {
+    selected: Sel[];
+    target: (Sel & {
+        value: unknown;
+    }) | null;
+}
+export type MayaViewDetail = View;
+export interface MayaErrorDetail {
+    code: ErrorCode;
+    path: string;
+    message: string;
+}
+export type ErrorCode = "spec-not-object" | "missing-field" | "unknown-type" | "data-not-array" | "row-not-object" | "unknown-field" | "non-numeric-y" | "non-numeric-field" | "non-positive-value" | "unknown-option" | "invalid-option" | "option-unsupported" | "stack-unsupported" | "invalid-domain" | "invalid-format" | "invalid-theme" | "unsafe-css-value" | "invalid-size" | "unknown-state" | "too-many-marks";
+/** Spec with every default and the view's measure/drill applied. From `resolve()`. */
+export interface ResolvedSpec {
+    type: ChartType;
+    /** Rows after the drill filter. */
+    data: readonly Row[];
+    /** Category field ("" for path types). With `path` + drill: the current level. */
+    x: string;
+    /** Active measure. */
+    y: string;
+    /** Every measure (`[y]` when `spec.y` is a string). */
+    measures: string[];
+    /** Index of `y` in `measures`. */
+    measure: number;
+    series: string | null;
+    /** Right-axis line measure (bar only); null when unset. */
+    y2: string | null;
+    /** Remaining path levels below the drilled branch ([] when no path). */
+    path: string[];
+    /** Applied drill values, outer first ([] at the root). */
+    drilled: string[];
+    /** Scatter zoom box [x0, x1, y0, y1] from view.window; null otherwise. */
+    window: readonly [number, number, number, number] | null;
+    size: string | null;
+    name: string | null;
+    totals: string[];
+    stack: boolean;
+    horizontal: boolean;
+    aggregate: Aggregate;
+    sort: "asc" | "desc" | null;
+    limit: number | null;
+    /** Per-field format; a bare-string `spec.format` is expanded to every measure. */
+    format: ReadonlyMap<string, FieldFormat>;
+    titles: ReadonlyMap<string, string>;
+    /** null = the type's default. */
+    labels: boolean | null;
+    text: Partial<Record<TextKey, string>>;
+    title: string | null;
+    description: string | null;
+    legend: boolean;
+    tooltip: boolean;
+    drill: boolean;
+    select: false | true | "multi";
+    zoom: boolean;
+    grid: boolean;
+    xAxis: boolean;
+    yAxis: boolean;
+    locale: string;
+    currency: string;
+    yDomain: readonly [number, number] | null;
+    xDomain: readonly [number, number] | null;
+    table: boolean;
+    animate: boolean;
+    colors: readonly string[] | ReadonlyMap<string, string> | null;
+    colorBy: "sign" | {
+        readonly target: number;
+    } | string | null;
+    theme: Partial<Record<ThemeToken, string>>;
+}
+/** One (category, series) value after grouping/stacking. */
+export interface Cell {
+    /** Category index into `Shaped.categories`. */
+    ci: number;
+    /** Series index into `Shaped.series` (0 when there is no series field). */
+    si: number;
+    /** Raw value, or null when the row is missing / null. */
+    value: number | null;
+    /** Bar/area span in data units. Grouped: [0, value]. Stacked: cumulative. */
+    y0: number;
+    y1: number;
+}
+export interface Shaped {
+    /** Category labels (String of the raw value; `OTHER` for the limit roll-up). */
+    categories: string[];
+    /** Waterfall: true where the category is in `spec.totals`. Parallel to `categories`. */
+    totals: boolean[];
+    /** Series keys in first-appearance order ([""] when there is no series field). */
+    series: string[];
+    /** Visible series only (excludes `view.hidden`), as indexes into `series`. */
+    visible: number[];
+    /** Cells for visible series, category-major order. */
+    cells: Cell[];
+    /** Min/max over all cell spans (includes 0 for bars). [0, 0] when empty. */
+    extent: [number, number];
+    /** spec.y2 aggregated per category (parallel to `categories`); [] without y2. */
+    y2: (number | null)[];
+}
+export interface BandScale {
+    domain: readonly string[];
+    /** Distance between band starts. */
+    step: number;
+    /** Width of one band. */
+    bandwidth: number;
+    /** Start coordinate of the band for `value`'s index. */
+    at(index: number): number;
+}
+export interface LinearScale {
+    domain: readonly [number, number];
+    range: readonly [number, number];
+    of(value: number): number;
+}
+/** Narrow with `"bandwidth" in s`. */
+export type Scale = BandScale | LinearScale;
+export interface Ticks {
+    /** Nice, step-aligned domain covering the input. */
+    domain: [number, number];
+    values: number[];
+    step: number;
+}
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface Layout {
+    width: number;
+    height: number;
+    /** The plot rectangle (marks live here). */
+    plot: Box;
+    /** Draw every nth x label (1 = all). */
+    xLabelEvery: number;
+}
+/** One screen axis a mark asks for. `field` names the title/format source. */
+export type Axis = {
+    kind: "band";
+    field: string;
+    domain: readonly string[];
+} | {
+    kind: "linear";
+    field: string;
+    domain: readonly [number, number];
+} | null;
+export type Fail = (code: ErrorCode, path: string, headline: string, ...details: string[]) => never;
+/** Where `ctx.label` places text relative to its anchor point. */
+export type LabelPlace = "center" | "above" | "below" | "start" | "end";
+/** Everything a mark may use. Closures are built in render.ts. */
+export interface MarkCtx {
+    spec: ResolvedSpec;
+    shaped: Shaped;
+    width: number;
+    height: number;
+    plot: Box;
+    /** Scale of the bottom (horizontal) axis; null when the mark has none. */
+    x: Scale | null;
+    /** Scale of the left (vertical) axis; null when the mark has none. */
+    y: Scale | null;
+    /** Scale of the right axis (bar with y2); null otherwise. */
+    y2: LinearScale | null;
+    /** Display text for a raw value of `field` (step = tick step for number decimals). */
+    fmt(field: string, v: unknown, step?: number): string;
+    /** Queue a value label into `<g data-maya="labels">`; false if it collided and was dropped. */
+    label(x: number, y: number, text: string, place: LabelPlace): boolean;
+    /** colorBy tone for a value: "good" | "bad", or null when colorBy is not sign/target. */
+    tone(v: number): "good" | "bad" | null;
+    /** colorBy ramp bucket 0..9 for a value of the colorBy field; null when colorBy is not a field. */
+    q(v: number): number | null;
+    /** Shared aggregation (same rules as shape: nulls skipped, count = non-null). */
+    agg(kind: Aggregate): (values: readonly (number | null | undefined)[]) => number | null;
+    fail: Fail;
+    t(key: TextKey, ...args: (string | number)[]): string;
+}
+/** Markup for each SVG group a mark fills. Absent groups render empty. */
+export interface MarkOut {
+    marks: string;
+    hits: string;
+    labels?: string;
+    legend?: string;
+    grid?: string;
+    cross?: string;
+}
+/** A chart type. Core marks live in render.ts's CORE map; modules `register()` theirs. */
+export interface Mark {
+    /** Noun for the auto description ("Bar" -> "Bar chart of …"). */
+    noun: string;
+    /** Bottom and left axes, plus an optional right linear axis (bar with y2). Absent: no axes (path types, kpi). */
+    axes?(spec: ResolvedSpec, shaped: Shaped): [bottom: Axis, left: Axis, right?: Axis];
+    /** Extra validation after the core checks (e.g. hexmap `unknown-state`). */
+    check?(spec: ChartSpec, fail: Fail): void;
+    draw(ctx: MarkCtx): MarkOut;
+}
+/** Pieces the shell and the element assemble. */
+export interface Parts {
+    /** `<svg>` markup without an embedded `<style>`. */
+    svg: string;
+    /** Legend HTML (`""` when hidden). */
+    legend: string;
+    /** Measure toggle HTML, a `.maya-ctl` radiogroup (`""` without a `y` array). */
+    controls: string;
+    /** Breadcrumb HTML, `.maya-crumbs` (`""` when not drilled). */
+    crumbs: string;
+    /** Hidden data table HTML (`""` when disabled). */
+    table: string;
+    /** Visible title HTML (`""` when no title). */
+    title: string;
+    /** Inline style for overrides from `spec.colors` / `spec.theme` (`""` when none). */
+    style: string;
+    /** The same overrides as [custom property, value] pairs (applied via CSSOM). */
+    vars: [string, string][];
+    /** Non-fatal notes for the developer (never rendered). */
+    warnings: string[];
+}
+/** Interaction state the element owns; rendered through RenderOptions.view/selected. */
+export interface State {
+    view: View;
+    selected: readonly Sel[];
+}
+/** Sent to every reducer when the element's spec object changes (incl. `el.data =`). */
+export interface SpecEvent {
+    type: "spec";
+    prev: ChartSpec | undefined;
+    next: ChartSpec;
+}
+/** What <maya-chart> hands each interaction module's `mount()`. */
+export interface Host {
+    root: ShadowRoot;
+    el: HTMLElement;
+    spec(): ChartSpec | undefined;
+    state(): State;
+    /** User-initiated transition: re-render, then dispatch maya-view / maya-select if changed. */
+    commit(next: State, target?: (Sel & {
+        value: unknown;
+    }) | null): void;
+    /** Polite live-region announcement (debounced 300 ms). */
+    announce(text: string): void;
+}
+/** Returned by `mount()`. Keyboard handlers return true when they handled the key. */
+export interface Handlers {
+    /** Abort an in-progress gesture (zoom brush). Escape priority 2. */
+    cancel?(): boolean;
+    /** Escape at this module's priority: select 3, zoom window 4, drill pop 5. */
+    escape?(): boolean;
+    /** Enter on the keyboard-active mark: drill first, then select. */
+    enter?(mark: Element): boolean;
+    /** After every paint (re-apply data-selected, restore focus). */
+    painted?(): void;
+    off(): void;
+}

package/dist/core/validate.d.ts

@@ -0,0 +1,24 @@
+import type { ChartSpec, ErrorCode, RenderOptions, ResolvedSpec, View } from "./types.ts";
+export type { ErrorCode };
+export declare class MayaSpecError extends Error {
+    readonly code: ErrorCode;
+    /** Spec path such as "y", "data[3].revenue", "theme.accent". */
+    readonly path: string;
+    constructor(code: ErrorCode, path: string, message: string);
+}
+export declare const MAX_MARKS = 5000;
+/** Every spec key (schema.json is tested against this). */
+export declare const KEYS: string[];
+export declare const ONLY: Readonly<Record<string, readonly string[]>>;
+/** Format options holding any date key are Intl.DateTimeFormat options. */
+export declare const isDateOpts: (o: object) => boolean;
+export declare const dym: (s: string, c: readonly string[]) => string;
+export declare const fail: (code: ErrorCode, path: string, headline: string, ...d: string[]) => never;
+export declare function validateSpec(spec: unknown): asserts spec is ChartSpec;
+export declare function validateOptions(opts: unknown): asserts opts is RenderOptions;
+/**
+ * Apply defaults plus the view's measure and drill. Assumes `spec` passed validateSpec.
+ * Drill keeps rows whose path[i] equals drill[i], then advances: bar/line/area take the next
+ * level as x; path types keep the remaining levels.
+ */
+export declare function resolve(spec: ChartSpec, view?: View): ResolvedSpec;

package/dist/element/animate.d.ts

@@ -0,0 +1,13 @@
+/** x, y, width, height in viewBox units. */
+export type Box = [x: number, y: number, w: number, h: number];
+export interface PatchOptions {
+    /** Entering marks start from this box; exiting marks collapse into it. */
+    origin?: Box | undefined;
+    /** Post-patch hook, called with the live svg after every patch (animated or not). */
+    after?: (svg: Element) => void;
+    /** Diff and reuse nodes, but apply every change immediately (resize). */
+    instant?: boolean;
+}
+/** Box of any mark (paths via getBBox where it exists); used to derive a drill origin. */
+export declare const boxOf: (e: Element) => Box | undefined;
+export declare function patch(box: Element, markup: string, animate: boolean, opts?: PatchOptions): void;

package/dist/element/drill.d.ts

@@ -0,0 +1,12 @@
+import type { ChartSpec, Handlers, Host, SpecEvent, State } from "../core/types.ts";
+/** `spec` is needed to gate a push (the reducer has no other access to it). */
+export type DrillEvent = {
+    type: "drill";
+    value: string;
+    spec?: ChartSpec;
+} | {
+    type: "pop";
+    depth: number;
+} | SpecEvent;
+export declare const reduce: (s: State, e: DrillEvent) => State;
+export declare const mount: (host: Host) => Handlers;

package/dist/element/html.d.ts

@@ -0,0 +1 @@
+export declare const html: (s: string) => string;

package/dist/element/maya-chart.d.ts

@@ -0,0 +1,21 @@
+import type { ChartSpec, Sel, View } from "../core/types.ts";
+export declare class MayaChart extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    static version: string;
+    get spec(): ChartSpec | undefined;
+    set spec(v: ChartSpec<any> | undefined);
+    get data(): ChartSpec["data"] | undefined;
+    set data(rows: ChartSpec["data"]);
+    /** Interaction state ({ measure, drill, window, hidden }). Setting never dispatches events. */
+    get view(): View;
+    set view(v: View);
+    /** Selected marks by raw values. Setting never dispatches events. */
+    get selected(): readonly Sel[];
+    set selected(v: readonly Sel[]);
+    attributeChangedCallback(_: string, __: string | null, v: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Standalone SVG: custom properties resolved from the computed style (dark export looks right). */
+    toSVG(): string;
+}

package/dist/element/measure.d.ts

@@ -0,0 +1,9 @@
+import type { Handlers, Host, SpecEvent, State } from "../core/types.ts";
+/** `count` (number of measures) bounds the index; without it only the lower bound applies. */
+export type MeasureEvent = {
+    type: "measure" | "pick";
+    index: number;
+    count?: number | undefined;
+} | SpecEvent;
+export declare const reduce: (s: State, e: MeasureEvent) => State;
+export declare const mount: (host: Host) => Handlers;

package/dist/element/select.d.ts

@@ -0,0 +1,14 @@
+import type { Handlers, Host, Sel, SpecEvent, State } from "../core/types.ts";
+export type SelectEvent = {
+    type: "toggle";
+    sel: Sel;
+    multi: boolean;
+} | {
+    type: "clear";
+} | SpecEvent;
+export declare function reduce(s: State, e: SelectEvent): State;
+/** Raw-value Sel of a mark, decoded from its data-key (`S~C`, scatter `S~name`, `h~…`). */
+export declare function selOf(mark: Element, type?: string): Sel | undefined;
+/** A Sel matches a mark when every field it names equals the mark's (compared as text). */
+export declare function matches(sel: Sel, mark: Element, type?: string): boolean;
+export declare function mount(host: Host): Handlers;