@faintshadow/flarecharts 26.3.1

package/dist/core/context.svelte.d.ts

@@ -0,0 +1,140 @@
+import { SvelteSet } from 'svelte/reactivity';
+import type { NormalizedPoint, XValue } from './normalize.js';
+import type { AnyScale, ScaleDomain, ScaleKind } from './scales.js';
+import type { StackExtents, StackOffset, StackOrder } from './stack.js';
+import type { KeyNavPosition } from './keynav.js';
+import type { ChartOptions } from './types.js';
+/** Stacking participation (bars AND areas): series sharing an id accumulate. */
+export interface StackedSeriesOptions {
+    id: string;
+    /** How the stack sits (normal/percent anchor at zero; stream/silhouette float). */
+    offset: StackOffset;
+    /** Layer ordering within the stack. */
+    order?: StackOrder;
+}
+/** What a mark component registers: its normalized points plus display metadata. */
+export interface RegisteredSeries<T = unknown> {
+    points: NormalizedPoint<T>[];
+    name?: string;
+    /** Resolved CSS color string (var() included). Falls back to the palette slot. */
+    color?: string;
+    /** Bar series claim a side-by-side slot in the band and force zero into the y domain. */
+    isBar?: boolean;
+    /** Present when the series stacks (bars or areas). */
+    stacked?: StackedSeriesOptions;
+    /** Box/range series: claims a categorical slot like bars, but does NOT anchor at zero. */
+    isBox?: boolean;
+    /** Per-point [lo, hi] value extents; the y domain spans these instead of p.y.
+     *  Used by range marks (box plots now; candlestick later). */
+    yExtents?: [number, number][];
+    /** Accessible series description (announced when keyboard focus enters the series). */
+    description?: string;
+    /** Per-point announcement override for keyboard navigation. */
+    describePoint?: (point: NormalizedPoint<unknown>) => string | undefined;
+}
+/** A registered series as exposed on the context (legend/tooltip read these). */
+export interface SeriesEntry {
+    index: number;
+    points: NormalizedPoint<unknown>[];
+    name?: string;
+    color: string;
+    visible: boolean;
+    isBar?: boolean;
+    stacked?: StackedSeriesOptions;
+    isBox?: boolean;
+    yExtents?: [number, number][];
+    description?: string;
+    describePoint?: (point: NormalizedPoint<unknown>) => string | undefined;
+}
+export interface SeriesRegistration {
+    /** Zero-based registration order — drives the default palette slot and identifies the series. */
+    index: number;
+    unregister: () => void;
+}
+export declare class ChartContext {
+    #private;
+    /** Container size, bound by <Chart> via bind:clientWidth/Height (SSR-safe: stays 0 on the server). */
+    width: number;
+    height: number;
+    /** Pointer position in PLOT-AREA coordinates, or null when outside. Written by <Chart>. */
+    pointer: {
+        x: number;
+        y: number;
+    } | null;
+    /** Keyboard-focused point (arrow-key navigation), or null. */
+    activePoint: KeyNavPosition | null;
+    /** Series indices currently hidden (legend toggle). */
+    readonly hiddenSeries: SvelteSet<number>;
+    constructor(options: () => ChartOptions);
+    get options(): ChartOptions;
+    padding: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    innerWidth: number;
+    innerHeight: number;
+    /** All registered series with metadata, in registration order (hidden ones included). */
+    seriesEntries: SeriesEntry[];
+    xType: ScaleKind;
+    yType: ScaleKind;
+    xDomain: ScaleDomain;
+    /** Stack extents for a bar series (by registration index), keyed by stackKey(x). */
+    stackFor: (seriesIndex: number) => StackExtents | undefined;
+    /**
+     * Side-by-side slot layout for bar series: each unstacked bar series gets
+     * its own slot, each stack group shares one. Hidden series free their slot.
+     */
+    barSlots: {
+        count: number;
+        bySeries: Map<number, number>;
+    };
+    yDomain: ScaleDomain;
+    xScale: AnyScale;
+    yScale: AnyScale;
+    /** Pixel position for an x value (band scales: band center). NaN if unmappable. */
+    xPos: (value: XValue) => number;
+    /** Pixel position for a y value. NaN if unmappable. */
+    yPos: (value: XValue) => number;
+    xTicks: (count?: number) => XValue[];
+    yTicks: (count?: number) => XValue[];
+    xTickFormat: (count?: number) => ((value: XValue) => string);
+    yTickFormat: (count?: number) => ((value: XValue) => string);
+    /**
+     * Mark components call this once at init with a reactive getter for their
+     * series. Domains re-derive whenever any registered getter's value changes.
+     * Call `unregister` on destroy.
+     */
+    registerSeries(get: () => RegisteredSeries): SeriesRegistration;
+    /** The keyboard focus expressed as a plot-area position (for tooltip/crosshair). */
+    keyboardPointer: {
+        x: number;
+        y: number;
+    } | null;
+    /** What interaction layers should react to: the mouse, else the keyboard focus. */
+    hoverPointer: {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Move keyboard focus by points (dPoint, ±Infinity = Home/End) and/or
+     * series (dSeries). Returns the focused entry+point for announcements.
+     */
+    moveFocusBy(dPoint: number, dSeries: number): {
+        entry: SeriesEntry;
+        point: NormalizedPoint<unknown>;
+    } | null;
+    clearFocus(): void;
+    /** Legend toggle: hide/show a series by its registration index. */
+    toggleSeries(index: number): void;
+    isSeriesVisible: (index: number) => boolean;
+    /**
+     * Resolve a series color. An override (any CSS color string, including
+     * `var(--whatever)`) passes through untouched — never parsed, never
+     * converted. Otherwise the palette slot for the series index.
+     */
+    seriesColor(index: number, override?: string): string;
+}
+export declare function setChartContext(ctx: ChartContext): ChartContext;
+export declare function getChartContext(): ChartContext;

package/dist/core/context.svelte.js

@@ -0,0 +1,294 @@
+/**
+ * Reactive chart context — the foundation pattern (documented in ARCHITECTURE.md).
+ *
+ * <Chart> constructs ONE ChartContext instance and shares it via setContext.
+ * Context itself is set once and never replaced; reactivity lives INSIDE the
+ * instance: dimensions and pointer are $state (bound/written by <Chart>),
+ * everything else is $derived from those + the options closure + the series
+ * registry. Children read `ctx.xScale` etc. and re-render exactly when the
+ * underlying state moves.
+ *
+ * Mark components register a getter for their series (points + name + color);
+ * scale domains derive from the union of VISIBLE registered series unless
+ * pinned via axis options — which is why a legend toggle recomputes domains
+ * for free, and why pinned domains don't move.
+ */
+import { getContext, setContext } from 'svelte';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { max, min } from 'd3-array';
+import { createScale, scalePos, scaleTicks, scaleTickFormat } from './scales.js';
+import { seriesColorVar } from './palette.js';
+import { stackSeries } from './stack.js';
+import { moveFocus } from './keynav.js';
+const DEFAULT_PADDING = { top: 12, right: 16, bottom: 32, left: 44 };
+export class ChartContext {
+    /** Container size, bound by <Chart> via bind:clientWidth/Height (SSR-safe: stays 0 on the server). */
+    width = $state(0);
+    height = $state(0);
+    /** Pointer position in PLOT-AREA coordinates, or null when outside. Written by <Chart>. */
+    pointer = $state(null);
+    /** Keyboard-focused point (arrow-key navigation), or null. */
+    activePoint = $state(null);
+    /** Series indices currently hidden (legend toggle). */
+    hiddenSeries = new SvelteSet();
+    #options;
+    #registry = new SvelteMap();
+    #seriesCount = 0;
+    constructor(options) {
+        this.#options = options;
+    }
+    get options() {
+        return this.#options();
+    }
+    padding = $derived.by(() => ({ ...DEFAULT_PADDING, ...this.#options().padding }));
+    innerWidth = $derived(Math.max(0, this.width - this.padding.left - this.padding.right));
+    innerHeight = $derived(Math.max(0, this.height - this.padding.top - this.padding.bottom));
+    /** All registered series with metadata, in registration order (hidden ones included). */
+    seriesEntries = $derived.by(() => {
+        const out = [];
+        for (const { index, get } of this.#registry.values()) {
+            const { points, name, color, isBar, stacked, isBox, yExtents, description, describePoint } = get();
+            out.push({
+                index,
+                points,
+                name,
+                color: color ?? seriesColorVar(index),
+                visible: !this.hiddenSeries.has(index),
+                isBar,
+                stacked,
+                isBox,
+                yExtents,
+                description,
+                describePoint
+            });
+        }
+        return out.sort((a, b) => a.index - b.index);
+    });
+    /** Points of VISIBLE series only — what domains derive from. */
+    #allPoints = $derived(this.seriesEntries.filter((e) => e.visible).flatMap((e) => e.points));
+    xType = $derived.by(() => {
+        const explicit = this.#options().x?.type;
+        if (explicit)
+            return explicit;
+        const probe = this.#allPoints.find((p) => p.x != null);
+        if (!probe)
+            return 'linear';
+        if (probe.x instanceof Date)
+            return 'time';
+        if (typeof probe.x === 'string')
+            return 'band';
+        return 'linear';
+    });
+    yType = $derived.by(() => this.#options().y?.type ?? 'linear');
+    xDomain = $derived.by(() => {
+        const o = this.#options().x;
+        if (this.xType === 'band') {
+            if (o?.categories)
+                return o.categories;
+            const seen = new Set();
+            for (const p of this.#allPoints) {
+                if (p.x != null)
+                    seen.add(String(p.x));
+            }
+            return [...seen];
+        }
+        const values = [];
+        for (const p of this.#allPoints) {
+            if (typeof p.x === 'number' || p.x instanceof Date)
+                values.push(p.x);
+        }
+        const lo = o?.min ?? min(values) ?? 0;
+        const hi = o?.max ?? max(values) ?? 1;
+        return [lo, hi];
+    });
+    /**
+     * Stacked [y0, y1] extents (value space) per bar series, computed across
+     * VISIBLE members of each stack group — toggling a series re-stacks.
+     */
+    #stacks = $derived.by(() => {
+        const groups = new Map();
+        for (const e of this.seriesEntries) {
+            if (!e.visible || !e.stacked)
+                continue;
+            let group = groups.get(e.stacked.id);
+            if (!group) {
+                group = { offset: e.stacked.offset, order: e.stacked.order, series: [] };
+                groups.set(e.stacked.id, group);
+            }
+            // Members share an id; the last seen offset/order wins for the group.
+            group.offset = e.stacked.offset;
+            if (e.stacked.order)
+                group.order = e.stacked.order;
+            group.series.push({ key: e.index, points: e.points });
+        }
+        const out = new Map();
+        for (const group of groups.values()) {
+            for (const [key, extents] of stackSeries(group.series, {
+                offset: group.offset,
+                order: group.order
+            })) {
+                out.set(key, extents);
+            }
+        }
+        return out;
+    });
+    /** Stack extents for a bar series (by registration index), keyed by stackKey(x). */
+    stackFor = (seriesIndex) => this.#stacks.get(seriesIndex);
+    /**
+     * Side-by-side slot layout for bar series: each unstacked bar series gets
+     * its own slot, each stack group shares one. Hidden series free their slot.
+     */
+    barSlots = $derived.by(() => {
+        const keys = [];
+        const bySeries = new Map();
+        for (const e of this.seriesEntries) {
+            if (!e.visible || !(e.isBar || e.isBox))
+                continue;
+            const key = e.stacked ? `stack:${e.stacked.id}` : `series:${e.index}`;
+            let slot = keys.indexOf(key);
+            if (slot === -1) {
+                keys.push(key);
+                slot = keys.length - 1;
+            }
+            bySeries.set(e.index, slot);
+        }
+        return { count: Math.max(1, keys.length), bySeries };
+    });
+    yDomain = $derived.by(() => {
+        const o = this.#options().y;
+        if (this.yType === 'band')
+            return o?.categories ?? [];
+        const values = [];
+        let hasBars = false;
+        for (const e of this.seriesEntries) {
+            if (!e.visible)
+                continue;
+            if (e.isBar)
+                hasBars = true;
+            const stacked = e.stacked ? this.#stacks.get(e.index) : undefined;
+            if (stacked) {
+                for (const [y0, y1] of stacked.values())
+                    values.push(y0, y1);
+            }
+            else if (e.yExtents) {
+                for (const [lo, hi] of e.yExtents)
+                    values.push(lo, hi);
+            }
+            else {
+                for (const p of e.points) {
+                    if (p.y != null)
+                        values.push(p.y);
+                }
+            }
+        }
+        let lo = o?.min ?? min(values) ?? 0;
+        let hi = o?.max ?? max(values) ?? 1;
+        // Bars are anchored at zero, so zero always belongs in the domain.
+        if (o?.includeZero || hasBars) {
+            lo = Math.min(0, lo);
+            hi = Math.max(0, hi);
+        }
+        if (lo === hi)
+            hi = lo + 1; // degenerate domain → give the scale some room
+        return [lo, hi];
+    });
+    xScale = $derived.by(() => createScale({
+        kind: this.xType,
+        domain: this.xDomain,
+        range: [0, this.innerWidth],
+        nice: this.#options().x?.nice,
+        bandPadding: this.#options().x?.bandPadding
+    }));
+    yScale = $derived.by(() => createScale({
+        kind: this.yType,
+        domain: this.yDomain,
+        range: [this.innerHeight, 0],
+        nice: this.#options().y?.nice,
+        bandPadding: this.#options().y?.bandPadding
+    }));
+    #autoXTickCount = $derived(Math.max(2, Math.min(10, Math.round(this.innerWidth / 80))));
+    #autoYTickCount = $derived(Math.max(2, Math.min(10, Math.round(this.innerHeight / 50))));
+    /** Pixel position for an x value (band scales: band center). NaN if unmappable. */
+    xPos = (value) => scalePos(this.xScale, value);
+    /** Pixel position for a y value. NaN if unmappable. */
+    yPos = (value) => scalePos(this.yScale, value);
+    xTicks = (count) => scaleTicks(this.xScale, count ?? this.#autoXTickCount);
+    yTicks = (count) => scaleTicks(this.yScale, count ?? this.#autoYTickCount);
+    xTickFormat = (count) => scaleTickFormat(this.xScale, count ?? this.#autoXTickCount);
+    yTickFormat = (count) => scaleTickFormat(this.yScale, count ?? this.#autoYTickCount);
+    /**
+     * Mark components call this once at init with a reactive getter for their
+     * series. Domains re-derive whenever any registered getter's value changes.
+     * Call `unregister` on destroy.
+     */
+    registerSeries(get) {
+        const id = Symbol('fc-series');
+        const index = this.#seriesCount++;
+        this.#registry.set(id, { index, get });
+        return {
+            index,
+            unregister: () => {
+                this.#registry.delete(id);
+            }
+        };
+    }
+    /** The keyboard focus expressed as a plot-area position (for tooltip/crosshair). */
+    keyboardPointer = $derived.by(() => {
+        const active = this.activePoint;
+        if (!active)
+            return null;
+        const entry = this.seriesEntries.find((e) => e.index === active.series);
+        const point = entry?.points[active.point];
+        if (!entry || !entry.visible || !point || point.y == null)
+            return null;
+        const x = this.xPos(point.x);
+        const y = this.yPos(point.y);
+        return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null;
+    });
+    /** What interaction layers should react to: the mouse, else the keyboard focus. */
+    hoverPointer = $derived(this.pointer ?? this.keyboardPointer);
+    /**
+     * Move keyboard focus by points (dPoint, ±Infinity = Home/End) and/or
+     * series (dSeries). Returns the focused entry+point for announcements.
+     */
+    moveFocusBy(dPoint, dSeries) {
+        const visible = this.seriesEntries.filter((e) => e.visible);
+        const next = moveFocus(visible, this.activePoint, dPoint, dSeries);
+        if (!next)
+            return null;
+        this.activePoint = next;
+        const entry = this.seriesEntries.find((e) => e.index === next.series);
+        return { entry, point: entry.points[next.point] };
+    }
+    clearFocus() {
+        this.activePoint = null;
+    }
+    /** Legend toggle: hide/show a series by its registration index. */
+    toggleSeries(index) {
+        if (this.hiddenSeries.has(index))
+            this.hiddenSeries.delete(index);
+        else
+            this.hiddenSeries.add(index);
+    }
+    isSeriesVisible = (index) => !this.hiddenSeries.has(index);
+    /**
+     * Resolve a series color. An override (any CSS color string, including
+     * `var(--whatever)`) passes through untouched — never parsed, never
+     * converted. Otherwise the palette slot for the series index.
+     */
+    seriesColor(index, override) {
+        return override ?? seriesColorVar(index);
+    }
+}
+const CONTEXT_KEY = Symbol('flarechart');
+export function setChartContext(ctx) {
+    setContext(CONTEXT_KEY, ctx);
+    return ctx;
+}
+export function getChartContext() {
+    const ctx = getContext(CONTEXT_KEY);
+    if (!ctx) {
+        throw new Error('flarechart: this component must be rendered inside a <Chart>.');
+    }
+    return ctx;
+}

package/dist/core/curves.d.ts

@@ -0,0 +1,4 @@
+import type { CurveFactory } from 'd3-shape';
+export type CurveName = 'linear' | 'monotone' | 'natural' | 'step' | 'basis' | 'bump';
+/** Resolve a curve by name, or pass a d3 CurveFactory straight through. */
+export declare function curveFor(curve?: CurveName | CurveFactory): CurveFactory;

package/dist/core/curves.js

@@ -0,0 +1,13 @@
+import { curveBasis, curveBumpX, curveLinear, curveMonotoneX, curveNatural, curveStepAfter } from 'd3-shape';
+const CURVES = {
+    linear: curveLinear,
+    monotone: curveMonotoneX,
+    natural: curveNatural,
+    step: curveStepAfter,
+    basis: curveBasis,
+    bump: curveBumpX
+};
+/** Resolve a curve by name, or pass a d3 CurveFactory straight through. */
+export function curveFor(curve = 'linear') {
+    return typeof curve === 'function' ? curve : CURVES[curve];
+}

package/dist/core/hit.d.ts

@@ -0,0 +1,34 @@
+import type { NormalizedPoint, XValue } from './normalize.js';
+export type TooltipMode = 'bisect-x' | 'nearest' | 'band';
+export interface HitResult<T = unknown> {
+    point: NormalizedPoint<T>;
+    px: number;
+    py: number;
+    /** Horizontal distance (bisect-x) or euclidean distance (nearest) to the probe. */
+    distance: number;
+}
+/** One series' contribution to a tooltip. `datum` is the consumer's original item. */
+export interface TooltipPoint<T = unknown> {
+    x: XValue;
+    y: number | null;
+    datum: T;
+    pointIndex: number;
+    seriesIndex: number;
+    seriesName?: string;
+    color: string;
+    px: number;
+    py: number;
+}
+export interface TooltipData<T = unknown> {
+    /** The anchor x value (shared tooltips group on this). */
+    x: XValue;
+    px: number;
+    py: number;
+    points: TooltipPoint<T>[];
+}
+/** Nearest point by x pixel position (binary search; data assumed in x order). */
+export declare function hitBisectX<T>(points: readonly NormalizedPoint<T>[], xPos: (value: XValue) => number, yPos: (value: XValue) => number, probePx: number): HitResult<T> | null;
+/** Nearest point by euclidean distance (scatter-style hovering). */
+export declare function hitNearest<T>(points: readonly NormalizedPoint<T>[], xPos: (value: XValue) => number, yPos: (value: XValue) => number, probePx: number, probePy: number): HitResult<T> | null;
+/** All non-gap points of a series sitting on a band category. */
+export declare function hitsAtBand<T>(points: readonly NormalizedPoint<T>[], category: string): NormalizedPoint<T>[];

package/dist/core/hit.js

@@ -0,0 +1,43 @@
+/**
+ * Pure hit-testing math for tooltips and crosshairs. No DOM, no Svelte —
+ * components feed in plot-area pixel coordinates and position functions.
+ * Gap points (y == null) and unmappable x values never match.
+ */
+import { bisectNearest } from './bisect.js';
+/** Nearest point by x pixel position (binary search; data assumed in x order). */
+export function hitBisectX(points, xPos, yPos, probePx) {
+    const usable = [];
+    for (const point of points) {
+        if (point.y == null)
+            continue;
+        const px = xPos(point.x);
+        if (Number.isFinite(px))
+            usable.push({ point, px });
+    }
+    if (usable.length === 0)
+        return null;
+    const index = bisectNearest(usable.map((u) => u.px), probePx);
+    const { point, px } = usable[index];
+    return { point, px, py: yPos(point.y), distance: Math.abs(px - probePx) };
+}
+/** Nearest point by euclidean distance (scatter-style hovering). */
+export function hitNearest(points, xPos, yPos, probePx, probePy) {
+    let best = null;
+    for (const point of points) {
+        if (point.y == null)
+            continue;
+        const px = xPos(point.x);
+        const py = yPos(point.y);
+        if (!Number.isFinite(px) || !Number.isFinite(py))
+            continue;
+        const distance = Math.hypot(px - probePx, py - probePy);
+        if (!best || distance < best.distance) {
+            best = { point, px, py, distance };
+        }
+    }
+    return best;
+}
+/** All non-gap points of a series sitting on a band category. */
+export function hitsAtBand(points, category) {
+    return points.filter((p) => p.y != null && String(p.x) === category);
+}

package/dist/core/keynav.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Keyboard point-navigation math — pure, tested.
+ *
+ * Arrow keys move between points (skipping gaps, clamping at the ends) and
+ * between series (preserving the point position, snapped to the nearest
+ * non-gap point). ±Infinity jumps to the first/last point (Home/End).
+ */
+import type { NormalizedPoint } from './normalize.js';
+export interface KeyNavSeries {
+    /** Registration index (stable identity). */
+    index: number;
+    points: readonly NormalizedPoint<unknown>[];
+}
+export interface KeyNavPosition {
+    /** Series registration index. */
+    series: number;
+    /** Point index within that series' points array. */
+    point: number;
+}
+export declare function moveFocus(seriesList: readonly KeyNavSeries[], current: KeyNavPosition | null, dPoint: number, dSeries: number): KeyNavPosition | null;

package/dist/core/keynav.js

@@ -0,0 +1,41 @@
+function nonGapIndices(points) {
+    const out = [];
+    for (let i = 0; i < points.length; i++) {
+        if (points[i].y != null)
+            out.push(i);
+    }
+    return out;
+}
+export function moveFocus(seriesList, current, dPoint, dSeries) {
+    const usable = seriesList.filter((s) => s.points.some((p) => p.y != null));
+    if (usable.length === 0)
+        return null;
+    let seriesPos = current ? usable.findIndex((s) => s.index === current.series) : -1;
+    if (seriesPos === -1) {
+        // No (valid) focus yet → land on the first point of the first series.
+        const first = usable[0];
+        return { series: first.index, point: nonGapIndices(first.points)[0] };
+    }
+    seriesPos = Math.max(0, Math.min(usable.length - 1, seriesPos + dSeries));
+    const target = usable[seriesPos];
+    const indices = nonGapIndices(target.points);
+    if (dSeries !== 0) {
+        // Switching series: keep the point position, snapped to the nearest non-gap.
+        const cur = current.point;
+        let best = indices[0];
+        for (const i of indices) {
+            if (Math.abs(i - cur) < Math.abs(best - cur))
+                best = i;
+        }
+        return { series: target.index, point: best };
+    }
+    const currentPos = indices.indexOf(current.point);
+    let nextPos;
+    if (dPoint === Number.POSITIVE_INFINITY)
+        nextPos = indices.length - 1;
+    else if (dPoint === Number.NEGATIVE_INFINITY)
+        nextPos = 0;
+    else
+        nextPos = Math.max(0, Math.min(indices.length - 1, (currentPos === -1 ? 0 : currentPos) + dPoint));
+    return { series: target.index, point: indices[nextPos] };
+}

package/dist/core/labels.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Point/bar label placement with basic collision avoidance — pure math.
+ *
+ * Greedy keep-first strategy: candidates are processed left-to-right; a label
+ * whose estimated box would overlap the previously kept one is skipped.
+ * Labels near the top edge flip below their anchor. Width is estimated from
+ * character count (no DOM measurement — SSR-safe and cheap).
+ */
+export interface LabelCandidate {
+    /** Anchor position in plot-area pixels (e.g. the data point). */
+    px: number;
+    py: number;
+    text: string;
+}
+export interface PlacedLabel {
+    /** Final text position (text-anchor: middle, y is the baseline). */
+    x: number;
+    y: number;
+    text: string;
+    /** True when the label flipped below its anchor (top-edge avoidance). */
+    below: boolean;
+    px: number;
+    py: number;
+}
+export interface LabelPlacementOptions {
+    bounds: {
+        width: number;
+        height: number;
+    };
+    /** Distance between anchor and label, default 8. */
+    offset?: number;
+    /** Used for box estimation and below-flip placement, default 10. */
+    fontSize?: number;
+    /** Estimated px per character, default fontSize * 0.62. */
+    charWidth?: number;
+    /** Minimum horizontal gap between neighbouring labels, default 4. */
+    gap?: number;
+}
+export declare function placeLabels(candidates: readonly LabelCandidate[], options: LabelPlacementOptions): PlacedLabel[];

package/dist/core/labels.js

@@ -0,0 +1,27 @@
+export function placeLabels(candidates, options) {
+    const offset = options.offset ?? 8;
+    const fontSize = options.fontSize ?? 10;
+    const charWidth = options.charWidth ?? fontSize * 0.62;
+    const gap = options.gap ?? 4;
+    const { width, height } = options.bounds;
+    const sorted = [...candidates].sort((a, b) => a.px - b.px);
+    const placed = [];
+    let lastRight = -Infinity;
+    for (const candidate of sorted) {
+        if (!Number.isFinite(candidate.px) || !Number.isFinite(candidate.py))
+            continue;
+        const boxWidth = Math.max(charWidth, candidate.text.length * charWidth);
+        const half = boxWidth / 2;
+        // Clamp into the plot horizontally (labels at the edges shift inward).
+        const x = Math.max(half, Math.min(width - half, candidate.px));
+        if (x - half < lastRight + gap)
+            continue; // would overlap the previous label
+        const below = candidate.py - offset - fontSize < 0;
+        let y = below ? candidate.py + offset + fontSize : candidate.py - offset;
+        if (y > height)
+            y = candidate.py - offset;
+        placed.push({ x, y, text: candidate.text, below, px: candidate.px, py: candidate.py });
+        lastRight = x + half;
+    }
+    return placed;
+}

package/dist/core/merge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Options precedence merge — Data chain, as one tiny utility:
+ *
+ *   chart defaults < chart-level plotOptions < per-series options < per-point options
+ *
+ * Call it with layers in ascending precedence; later layers win:
+ *
+ *   mergeOptions(defaults, plotOptions, series.options, point.options)
+ *
+ * Rules:
+ *   - plain objects merge recursively
+ *   - everything else (arrays, Dates, functions, class instances, scalars) replaces
+ *   - `undefined` values are skipped (do not overwrite)
+ *   - `null` values DO overwrite (explicit "clear this option")
+ *   - inputs are never mutated; nested plain objects are cloned
+ */
+export declare function mergeOptions<T>(...layers: ReadonlyArray<Partial<T> | null | undefined>): T;