@blueprint-chart/lib 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pirhoo and Blueprint Chart contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @blueprint-chart/lib
+
+Core library for Blueprint Chart — a DSL-driven charting engine built on D3.
+
+## Install
+
+```bash
+npm install @blueprint-chart/lib
+```
+
+## Quick start
+
+The simplest way to render a chart is the IIFE runtime, which auto-scans the document for embedded chart definitions and renders each one inline (inside a sandboxed iframe inserted before the script tag):
+
+```html
+<script src="https://unpkg.com/@blueprint-chart/lib/dist/lib/lib.iife.js"></script>
+
+<script type="application/blueprint-chart">
+  chart MyChart {
+    data { values = "[[0,1],[1,4],[2,2]]" }
+    series "line" { color = "steelblue" }
+  }
+</script>
+```
+
+For programmatic use in an ES module project, the lib exposes the underlying primitives: `parse` (DSL → AST), `buildChartOptions` (AST → render options), `createFrame`/`createCanvas`, and the chart registry (`registerChart`, `getChart`). See [src/index.ts](https://github.com/blueprint-chart/blueprint-chart/blob/main/packages/lib/src/index.ts) for the full public API.
+
+## DSL Grammar
+
+The chart DSL is defined by a PEG grammar in `src/dsl/grammar.peggy` and compiled to `src/dsl/grammar.js` using [Peggy](https://peggyjs.org/).
+
+### EBNF Overview
+
+```
+Chart       = "chart" Identifier "{" ChartMember* "}"
+ChartMember = DataBlock | Colorize | AreaFill | Annotation | Series | Scene | Property
+
+DataBlock   = "data" "{" Property* "}"
+Colorize    = "colorize" String "{" Property* "}"
+AreaFill    = "areafill" String String "{" Property* "}"
+Annotation  = "annotation" String "{" Property* "}"
+Series      = "series" String "{" Property* "}"
+Scene       = "scene" String "{" SceneMember* "}"
+SceneMember = DataBlock | Colorize | AreaFill | Annotation | Property
+
+Property    = PropertyKey "=" PropertyValue
+PropertyKey = String | Identifier
+PropertyValue = Number "%" | Number | String | Identifier
+
+Identifier  = [a-zA-Z_#][a-zA-Z0-9_#-]*
+Number      = [0-9]+("."[0-9]+)?
+String      = '"' (EscapeSequence | [^"\\])* '"'
+```
+
+### Example
+
+```
+chart horizontal-bar {
+  title = "Revenue by Region"
+  sort = descending
+
+  data {
+    "North America" = 75%
+    "Europe" = 53.85%
+    "Asia" = 44%
+  }
+
+  colorize "North America" {
+    color = "#e53e3e"
+    label = "Leader"
+  }
+
+  scene "Focus" {
+    sort = ascending
+    colorize "Asia" {
+      color = "#38a169"
+    }
+  }
+}
+```
+
+## AST Node Types
+
+| Node | Fields |
+|------|--------|
+| `ChartNode` | `chartType`, `properties`, `data`, `colorizes`, `areaFills`, `annotations`, `series`, `scenes` |
+| `PropertyNode` | `key`, `value`, `isPercentage` |
+| `DataNode` | `entries` (PropertyNode[]) |
+| `ColorizeNode` | `target`, `properties` |
+| `AreaFillNode` | `from`, `to`, `properties` |
+| `AnnotationNode` | `target`, `properties` |
+| `SeriesNode` | `name`, `properties` |
+| `SceneNode` | `name`, `properties`, `data`, `colorizes`, `areaFills`, `annotations` |
+
+## Regenerating the Parser
+
+The generated parser (`src/dsl/grammar.js`) is checked into git so downstream packages can import lib source directly without a build step.
+
+To regenerate after editing `grammar.peggy`:
+
+```sh
+pnpm --filter @blueprint-chart/lib run generate:parser
+```
+
+This also runs automatically before `build` and `test` via `prebuild`/`pretest` hooks.
+
+## Color Palettes
+
+The built-in color palettes are curated from [pypalettes](https://github.com/y-sunflower/pypalettes) by Joseph Music, a collection of 2700+ color palettes for data visualization. Licensed under MIT.

package/dist/charts/axis/axis-service.d.ts

@@ -0,0 +1,55 @@
+import { AnyXScale } from './horizontal-axis';
+import { AxisOptions } from '../types';
+import * as d3 from 'd3';
+export interface AxisServiceConfig {
+    vertical?: {
+        scale: d3.ScaleLinear<number, number> | d3.ScaleLogarithmic<number, number> | d3.ScaleSymLog<number, number> | d3.ScaleBand<string>;
+        height: number;
+        options: AxisOptions;
+    };
+    horizontal?: {
+        scale: AnyXScale;
+        height: number;
+        options: AxisOptions;
+    };
+    order?: 'vertical-first' | 'horizontal-first';
+}
+export declare class AxisService {
+    private vGroup;
+    private hGroup;
+    private vChart;
+    private hChart;
+    private container;
+    private initialized;
+    private constructor();
+    static for(container: HTMLElement): AxisService;
+    static clear(container: HTMLElement): void;
+    /**
+     * Remove axis groups from DOM before replaceChildren().
+     * The groups are kept in memory for reattachment.
+     */
+    detach(): void;
+    /**
+     * Insert axis wrapper groups into the given chartArea.
+     * On first call, creates new D3Blueprint instances.
+     * On subsequent calls, reinserts the existing groups.
+     *
+     * When marginDelta is provided (dx/dy from previous to current margin),
+     * axis groups are wrapped in a compensating transform that transitions
+     * to identity, preventing visual jumps when the chartArea origin shifts.
+     */
+    attach(chartArea: SVGGElement, marginDelta?: {
+        dx: number;
+        dy: number;
+    }): void;
+    /**
+     * Configure and draw both axes.
+     */
+    update(config: AxisServiceConfig): void;
+    private updateVertical;
+    private updateHorizontal;
+    /**
+     * Tear down the service and remove from the WeakMap.
+     */
+    destroy(): void;
+}

package/dist/charts/axis/horizontal-axis.d.ts

@@ -0,0 +1,58 @@
+import { D3Blueprint } from 'd3-blueprint';
+import { AxisOptions } from '../types';
+import { detectDates, DateGranularity } from '../date-parse';
+import * as d3 from 'd3';
+interface AxisDatum {
+    placeholder: true;
+}
+/**
+ * Wrap a label across multiple lines by splitting on whitespace so each line
+ * fits within `maxWidthPx`. Returns `null` when it cannot be made to fit —
+ * either because a single word exceeds the width or the content requires more
+ * than `maxLines`. Used to avoid rotating labels when wrapping suffices.
+ */
+declare function wrapLabel(label: string, maxWidthPx: number, maxLines?: number): string[] | null;
+type AnyXScale = d3.ScaleBand<string> | d3.ScalePoint<string> | d3.ScaleLinear<number, number> | d3.ScaleSymLog<number, number> | d3.ScaleTime<number, number>;
+declare function buildTickFormatter(fmt: string | null, labels: string[]): ((d: string | d3.NumberValue) => string) | null;
+declare function thinLabels(domain: string[], availableWidth: number, formatter?: ((d: string | d3.NumberValue) => string) | null): string[];
+/**
+ * Decide whether horizontal tick labels should be rotated 90° to avoid overlap.
+ * Applies only to ordinal (band/point) scales — time/linear scales thin instead.
+ *
+ * Ordinal domains of date-parseable labels (e.g. `"2024-01", "2024-02"…`) are
+ * treated as continuous: auto mode thins them rather than rotating. An explicit
+ * `labelRotation='vertical'` still forces rotation so the user override wins.
+ *
+ * - `labelRotation='vertical'` → always rotates (when domain has ≥2 entries).
+ * - `labelRotation='horizontal'` → never rotates.
+ * - `labelRotation='auto'` → rotates when the longest formatted label exceeds
+ *   the per-tick band step and the domain is discrete (non-date).
+ */
+declare function willRotateLabels(domain: string[], availableWidth: number, labelRotation: string, formatter?: ((d: string | d3.NumberValue) => string) | null): boolean;
+/**
+ * Estimate the pixel height needed below the chart for x-axis labels when
+ * rotated 90°. Returns 0 for empty label lists.
+ */
+declare function estimateRotatedAxisHeight(labels: string[], formatter?: ((d: string | d3.NumberValue) => string) | null): number;
+/**
+ * Resolve the bottom margin needed for the x-axis, accounting for rotation.
+ * Returns the rotated height when rotation will apply and it exceeds
+ * `defaultBottom`; otherwise undefined (caller keeps its default).
+ *
+ * Chart types call this before `createCanvas` so the canvas reserves enough
+ * space for rotated labels to render within the SVG bounds.
+ */
+declare function resolveHorizontalAxisBottom(labels: string[], availableWidth: number, options?: {
+    labelRotation?: string;
+    numberFormat?: string | null;
+    labelPosition?: string;
+    tickFormat?: ((label: string) => string) | null;
+}, defaultBottom?: number): number | undefined;
+export declare class HorizontalAxisChart extends D3Blueprint<AxisDatum[]> {
+    initialize(): void;
+    private applyAxis;
+    postDraw(): void;
+}
+export declare function renderHorizontalAxis(chartArea: SVGGElement, scale: AnyXScale, height: number, options?: AxisOptions, priorAxisElement?: Element | null): SVGGElement;
+export { thinLabels, buildTickFormatter, detectDates, willRotateLabels, estimateRotatedAxisHeight, resolveHorizontalAxisBottom, wrapLabel, };
+export type { AnyXScale, DateGranularity };

package/dist/charts/axis/index.d.ts

@@ -0,0 +1,4 @@
+export { renderVerticalAxis } from './vertical-axis';
+export { renderHorizontalAxis } from './horizontal-axis';
+export { AxisService } from './axis-service';
+export type { AxisServiceConfig } from './axis-service';

package/dist/charts/axis/vertical-axis.d.ts

@@ -0,0 +1,12 @@
+import { D3Blueprint } from 'd3-blueprint';
+import { AxisOptions } from '../types';
+import * as d3 from 'd3';
+interface AxisDatum {
+    placeholder: true;
+}
+export declare class VerticalAxisChart extends D3Blueprint<AxisDatum[]> {
+    initialize(): void;
+    postDraw(): void;
+}
+export declare function renderVerticalAxis(chartArea: SVGGElement, scale: d3.ScaleLinear<number, number> | d3.ScaleLogarithmic<number, number> | d3.ScaleBand<string>, height: number, options?: AxisOptions, priorAxisElement?: Element | null): SVGGElement;
+export {};

package/dist/charts/canvas/canvas.d.ts

@@ -0,0 +1,45 @@
+import { Margin } from '../types';
+export interface CanvasElements {
+    svg: SVGSVGElement;
+    chartArea: SVGGElement;
+    width: number;
+    height: number;
+    margin: Margin;
+}
+/**
+ * Compute the margin delta between a prior cached margin and the current one.
+ * In constrained mode, uses `stableTop` (renderer-only margin, excluding
+ * headerH) so the dy doesn't include header height changes. This prevents
+ * axes from sliding vertically when the header wraps differently.
+ */
+export declare function computeMarginDelta(priorMargin: Pick<Margin, 'top' | 'left'> | undefined, currentMargin: Margin): {
+    dx: number;
+    dy: number;
+} | undefined;
+/**
+ * Estimate the pixel width of the widest tick label for a vertical axis.
+ * Uses an offscreen canvas for measurement, falling back to character-count estimation.
+ */
+export declare function estimateVerticalLabelWidth(values: number[], range?: {
+    min?: number;
+    max?: number;
+}, numberFormat?: string | null, scaleType?: string): number;
+/**
+ * Estimate the pixel width of the widest string label (for band/category axes).
+ */
+export declare function estimateCategoryLabelWidth(labels: string[]): number;
+/**
+ * Compute margin overrides based on axis label positions.
+ * When labels are inside or off, the corresponding margin is removed
+ * so the chart area is flush with the container edges.
+ * "auto" resolves based on available container width.
+ */
+export declare function labelPositionMargins(containerWidth: number, verticalLabelPosition?: string, horizontalLabelPosition?: string, verticalDirection?: string, verticalLabelWidth?: number, showHorizontalAxis?: boolean): Partial<Margin>;
+/**
+ * Return the inner content dimensions of an element (excluding CSS padding).
+ */
+export declare function contentSize(el: HTMLElement): {
+    width: number;
+    height: number;
+};
+export declare function createCanvas(body: HTMLElement, margin?: Partial<Margin>): CanvasElements;

package/dist/charts/chart-helpers.d.ts

@@ -0,0 +1,3 @@
+import { ChartData, ChartOptions, ChartTypeOptions } from './types';
+export declare function parseData(raw: string): ChartData;
+export declare function buildChartOptions(opts: Partial<ChartTypeOptions>, backgroundColor?: string): Partial<ChartOptions>;

package/dist/charts/colorblind.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Color Vision Deficiency (CVD) simulation using Brettel/Viénot matrices.
+ * Creates SVG `<filter>` elements with `<feColorMatrix>` for live preview,
+ * and programmatic simulation for accessibility analysis.
+ */
+export type CvdType = 'protanopia' | 'deuteranopia' | 'tritanopia';
+/**
+ * Returns the SVG filter element ID for a given CVD type.
+ */
+export declare function getCvdFilterId(type: CvdType): string;
+/**
+ * Creates an SVG `<filter>` element with an `<feColorMatrix>` for the given CVD type.
+ * The filter can be applied via CSS `filter: url(#<id>)`.
+ */
+export declare function createCvdSvgFilter(type: CvdType): SVGFilterElement;
+/**
+ * Simulate how a color appears under a given CVD type.
+ * Returns a hex string.
+ */
+export declare function simulateCvdColor(hex: string, type: CvdType): string;
+export interface CvdIssue {
+    type: CvdType;
+    label: string;
+    pairs: Array<{
+        a: string;
+        b: string;
+        deltaE: number;
+    }>;
+}
+/**
+ * Check an array of colors for distinguishability under each CVD type.
+ * Returns issues only for types where at least one pair falls below the threshold.
+ */
+export declare function checkCvdColors(colors: string[]): CvdIssue[];

package/dist/charts/contrast.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Returns '#fff' or '#333' — whichever has better contrast against `bg`.
+ */
+export declare function contrastTextColor(bg: string): string;
+/**
+ * Compute WCAG 2.1 contrast ratio between two colors.
+ * Returns a value between 1 and 21.
+ */
+export declare function wcagContrastRatio(fg: string, bg: string): number;
+/**
+ * Determine WCAG conformance level from a contrast ratio.
+ * AAA ≥ 7, AA ≥ 4.5, otherwise Fail.
+ */
+export declare function wcagLevel(ratio: number): 'AAA' | 'AA' | 'Fail';
+/**
+ * Resolve the effective background color of an element by walking up the DOM.
+ * Falls back to '#fff' when running outside a browser or when nothing is found.
+ */
+export declare function resolveBackgroundColor(el?: Element | null): string;
+/**
+ * Ensures `color` is readable against `bg`.
+ * Darkens or lightens the colour until the contrast ratio reaches MIN_CONTRAST.
+ * `bg` can be a CSS color string; defaults to '#fff'.
+ */
+export declare function readableColor(color: string, bg?: string): string;
+/**
+ * Adjusts an array of colors so that:
+ * 1. Every color is readable against `bg` (WCAG contrast ratio >= 3).
+ * 2. Adjacent colors are perceptually distinguishable (deltaE >= 12).
+ *
+ * Only lightness is changed — hue and saturation are preserved.
+ */
+export declare function adjustColorsForBackground(colors: string[], bg: string): string[];

package/dist/charts/curves.d.ts

@@ -0,0 +1,2 @@
+import * as d3 from 'd3';
+export declare function resolveCurve(name: string | undefined): d3.CurveFactory;

package/dist/charts/date-parse.d.ts

@@ -0,0 +1,12 @@
+export type DateGranularity = 'year' | 'month' | 'day' | 'datetime';
+export declare function parseDate(s: string): Date | null;
+/**
+ * Parse a string as a date (returning epoch ms) or as a plain number.
+ * Date strings take precedence so that e.g. "2020" becomes epoch ms for
+ * Jan 1 2020 rather than the number 2020.
+ */
+export declare function parseDateOrNumber(s: string): number | undefined;
+export declare function detectDates(labels: string[]): {
+    dates: Date[];
+    granularity: DateGranularity;
+} | null;

package/dist/charts/defaults/expectations.d.ts

@@ -0,0 +1,2 @@
+import { Matrix } from './types';
+export declare const MATRIX: Matrix;

package/dist/charts/defaults/helpers.d.ts

@@ -0,0 +1,6 @@
+import { ChartType } from '../../enums';
+/**
+ * Asserts that a chart type's option default matches the expected value.
+ * Failure messages cite the wiki rule for traceability.
+ */
+export declare function expectDefault(chart: ChartType, optionKey: string, expected: unknown, rule: string): void;

package/dist/charts/defaults/types.d.ts

@@ -0,0 +1,61 @@
+import { ChartType } from '../../enums';
+export declare const Concern: {
+    readonly DirectLabelling: "directLabelling";
+    readonly Legend: "legend";
+    readonly ValueLabels: "valueLabels";
+    readonly AxisLabels: "axisLabels";
+    readonly Gridlines: "gridlines";
+    readonly Ticks: "ticks";
+    readonly AxisLines: "axisLines";
+    readonly AxisScaleRange: "axisScaleRange";
+    readonly ColorPalette: "colorPalette";
+    readonly Crosshair: "crosshair";
+    readonly Tooltips: "tooltips";
+    readonly LineInterpolation: "lineInterpolation";
+    readonly LineSymbols: "lineSymbols";
+    readonly BarLayout: "barLayout";
+    readonly PieDonutLayout: "pieDonutLayout";
+    readonly Stacking: "stacking";
+    readonly Sort: "sort";
+    readonly RendererConstants: "rendererConstants";
+};
+export type Concern = typeof Concern[keyof typeof Concern];
+export declare const ALL_CONCERNS: readonly Concern[];
+export declare const AUDITED_CHART_TYPES: readonly ChartType[];
+export interface AssertedCell {
+    status: 'asserted';
+    kind?: never;
+    optionKey: string;
+    target: unknown;
+    rule: string;
+    notes?: string;
+}
+export interface AssertedRendererCell {
+    status: 'asserted';
+    kind: 'rendererConstant';
+    importPath: string;
+    exportName: string;
+    target: unknown;
+    rule: string;
+}
+export interface TodoCell {
+    status: 'todo';
+    optionKey: string;
+    current: unknown;
+    target: unknown;
+    rule: string;
+    notes?: string;
+}
+export interface NaCell {
+    status: 'na';
+    reason: string;
+}
+export interface OpenCell {
+    status: 'open';
+    optionKey?: string;
+    current?: unknown;
+    notes: string;
+}
+export type Cell = AssertedCell | AssertedRendererCell | TodoCell | NaCell | OpenCell;
+export type ConcernMatrix = Partial<Record<ChartType, Cell>>;
+export type Matrix = Record<Concern, ConcernMatrix>;

package/dist/charts/format-helpers.d.ts

@@ -0,0 +1,31 @@
+export interface ParsedNumberFormat {
+    prefix: string;
+    d3Spec: string;
+    suffix: string;
+}
+/**
+ * Fix legacy d3-format specifiers.
+ * Converts wrapping parens `(,.0f)` to d3-correct prefix-only `(,.0f`.
+ */
+export declare function safeD3Spec(fmt: string): string;
+/** @deprecated Use safeD3Spec instead */
+export declare const safeFormat: typeof safeD3Spec;
+/**
+ * Parse a number format string into its components.
+ *
+ * Supports two formats:
+ * - Plain d3-format: `,.0f`, `(,.2f`
+ * - Pipe-delimited with prefix/suffix: `$|,.0f|`, `|,.0f|%`, `$|,.2f|M`
+ *
+ * Legacy paren format `(,.0f)` is auto-corrected to `(,.0f`.
+ */
+export declare function parseNumberFormat(fmt: string): ParsedNumberFormat;
+/**
+ * Build a tick formatter function from a number format string.
+ * Returns null if the format string is empty.
+ *
+ * Handles prefix/suffix via pipe syntax: `$|,.0f|M` → "$1,234M"
+ */
+export declare function buildNumberFormatter(fmt: string): ((value: number | {
+    valueOf(): number;
+}) => string) | null;

package/dist/charts/frame/frame.d.ts

@@ -0,0 +1,8 @@
+import { FrameOptions } from '../types';
+export interface FrameElements {
+    wrapper: HTMLElement;
+    header: HTMLElement;
+    body: HTMLElement;
+    footer: HTMLElement;
+}
+export declare function createFrame(container: HTMLElement, options?: FrameOptions): FrameElements;

package/dist/charts/index.d.ts

@@ -0,0 +1,17 @@
+export type { ChartData, ChartOptions, ChartRenderer, ChartOptionDef, ChartTypeOptions, ChartTypeOptionKey, LineStyle, ColorizeConfig, HighlightConfig, AxisOptions, FrameOptions, AreaFillConfig, AnnotationConfig, LineSymbolConfig, SeriesOverride, Margin, } from './types';
+export { createFrame } from './frame/frame';
+export type { FrameElements } from './frame/frame';
+export { createCanvas } from './canvas/canvas';
+export type { CanvasElements } from './canvas/canvas';
+export { renderVerticalAxis } from './axis/vertical-axis';
+export { renderHorizontalAxis } from './axis/horizontal-axis';
+export { AxisService } from './axis/axis-service';
+export type { AxisServiceConfig } from './axis/axis-service';
+export { renderLegend } from './legend/legend';
+export { registerChart, getChart, getChartOptions, listCharts } from './registry';
+export { parseData, buildChartOptions } from './chart-helpers';
+export { resolveSeriesColor, isSeriesHidden } from './series-helpers';
+export { computeStack, computeStack100 } from './stack-helpers';
+export { getDefaultTransitionMs, DEFAULT_TRANSITION_MS, snapshotForFadeOut, commitFadeOut, fadeIn } from './motion';
+export { getCachedChart, setCachedChart, clearCachedChart } from './transition-cache';
+export type { CachedChart } from './transition-cache';

package/dist/charts/legend/legend-size.d.ts

@@ -0,0 +1,5 @@
+export declare function estimateLegendSize(labels: string[], position: string, availableWidth?: number): {
+    width: number;
+    height: number;
+};
+export declare function estimateDirectLabelWidth(labels: string[]): number;

package/dist/charts/legend/legend.d.ts

@@ -0,0 +1,4 @@
+export declare function renderLegend(chartArea: SVGGElement, labels: string[], colors?: string[], yOffset?: number, position?: string, anchor?: string, chartWidth?: number, chartHeight?: number, xOffset?: number, valueSuffixes?: string[], frameInset?: {
+    left?: number;
+    right?: number;
+}): SVGGElement;

package/dist/charts/line-symbols.d.ts

@@ -0,0 +1,9 @@
+import { LineSymbolConfig } from './types';
+import * as d3 from 'd3';
+export declare function shouldShowSymbol(index: number, total: number, showOn: LineSymbolConfig['showOn']): boolean;
+export declare function renderLineSymbols(parent: d3.Selection<SVGGElement, unknown, null, undefined>, points: {
+    cx: number;
+    cy: number;
+    color: string;
+    index: number;
+}[], total: number, config: LineSymbolConfig, transition?: boolean): void;

package/dist/charts/motion.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Returns 0 when the user prefers reduced motion, otherwise returns the input duration.
+ */
+export declare function getTransitionDuration(ms: number): number;
+export declare const DEFAULT_TRANSITION_MS = 500;
+/**
+ * Call at the start of each render() function to control whether transitions play.
+ * Pass `true` for scene transitions, `false` (default) for initial / non-scene renders.
+ */
+export declare function setRenderTransition(enabled: boolean): void;
+/**
+ * Returns the current scene transition duration, respecting `prefers-reduced-motion`.
+ * Returns 0 when not in a scene transition (i.e. setRenderTransition(false) was last called).
+ */
+export declare function getDefaultTransitionMs(): number;
+/**
+ * Reinsert prior elements into a parent, wrapping them in a compensating
+ * `<g translate(dx,dy)>` that transitions to identity over the default
+ * duration.  This corrects for chartArea origin shifts (e.g. when legend
+ * toggles change margins) so that prior elements don't visually jump.
+ *
+ * When dx/dy are both 0, elements are appended directly without a wrapper.
+ */
+export declare function reinsertWithOffset(parent: Element, elements: Element[], dx: number, dy: number): void;
+/**
+ * Fade an element in using the Web Animations API.
+ * Respects `prefers-reduced-motion` via `getTransitionDuration`.
+ */
+export declare function fadeIn(el: Element, ms?: number): void;
+/**
+ * Capture a visual snapshot of the container's current content as a
+ * detached overlay element.  Call this *before* clearing the container.
+ *
+ * After the new chart is rendered, append the returned overlay to the
+ * container via `commitFadeOut()` — it will sit on top and fade to
+ * transparent, then self-remove.
+ *
+ * Returns `null` when reduced-motion is active or the container is empty.
+ */
+export declare function snapshotForFadeOut(container: HTMLElement, ms?: number): HTMLElement | null;
+/**
+ * Append a previously-created fade-out overlay to the container and
+ * start its opacity animation.  The overlay removes itself on finish.
+ */
+export declare function commitFadeOut(container: HTMLElement, overlay: HTMLElement, ms?: number): void;

package/dist/charts/palettes.d.ts

@@ -0,0 +1,7 @@
+export interface PaletteEntry {
+    name: string;
+    label: string;
+    colors: readonly string[];
+}
+export declare function resolvePalette(paletteName: string | undefined): string[] | undefined;
+export declare function listPalettes(): PaletteEntry[];

package/dist/charts/plugins/annotations/context.d.ts

@@ -0,0 +1,17 @@
+import { AnnotationSnapshot } from './snapshots';
+import type * as d3 from 'd3';
+export interface AnnotationContext {
+    scaleX: d3.ScaleBand<string> | d3.ScalePoint<string> | d3.ScaleTime<number, number> | d3.ScaleLinear<number, number>;
+    scaleY: d3.ScaleLinear<number, number> | d3.ScaleSymLog<number, number>;
+    data: {
+        label: string;
+        value: number;
+    }[];
+    width: number;
+    height: number;
+    backgroundColor?: string;
+    orientation?: 'horizontal';
+    transition?: boolean;
+    /** Pre-computed snapshots of old annotation positions (captured before DOM is cleared). */
+    priorAnnotations?: Map<string, AnnotationSnapshot>;
+}

package/dist/charts/plugins/annotations/direction-helpers.d.ts

@@ -0,0 +1,14 @@
+import { CompassDirection } from '../../types';
+export declare const DIRECTION_VECTORS: Record<CompassDirection, {
+    dx: number;
+    dy: number;
+}>;
+export declare const RECT_ANCHOR: Record<CompassDirection, {
+    nx: number;
+    ny: number;
+}>;
+export declare function computeDirectionOffset(direction: CompassDirection, distance: number): {
+    dx: number;
+    dy: number;
+};
+export declare function rotateDirectionForHorizontal(dir: CompassDirection): CompassDirection;

package/dist/charts/plugins/annotations/free-renderer.d.ts

@@ -0,0 +1,4 @@
+import { AnnotationConfig } from '../../types';
+import { AnnotationContext } from './context';
+import * as d3 from 'd3';
+export declare function renderFreeAnnotation(g: d3.Selection<SVGGElement, unknown, null, undefined>, ann: AnnotationConfig, ctx: AnnotationContext, index: number): void;