@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/types/transforms/stack.d.ts

@@ -0,0 +1,64 @@
+import { type PositionChannels, type TransformChannel } from './common';
+/** Channels both stack transforms read, by svelteplot's own names. */
+export type StackChannels = PositionChannels;
+/** The keys of {@link StackChannels}, at runtime. */
+export declare const STACK_CHANNEL_KEYS: Record<keyof PositionChannels, true>;
+/** Options both stack transforms take, flat next to the channels - same names as svelteplot's. */
+type StackOptions = {
+    /** Offset method; unset keeps svelteplot's zero baseline. */
+    offset?: 'none' | 'wiggle' | 'center' | 'normalize' | 'diverging' | null;
+    /** Series order; unset keeps the input order. */
+    order?: 'none' | 'appearance' | 'inside-out' | 'sum' | null;
+    /** Reverses the stacking order. */
+    reverse?: boolean;
+};
+/**
+ * `stackY` as a marker transform: its own props, flat, exactly as svelteplot's
+ * `stackY` takes them. `type` picks the transform; everything else is that
+ * transform's own input.
+ */
+export type StackYTransform = {
+    type: 'stackY';
+} & StackChannels & StackOptions;
+/** `stackX` as a marker transform - see {@link StackYTransform}. */
+export type StackXTransform = {
+    type: 'stackX';
+} & StackChannels & StackOptions;
+/**
+ * Channels the mosaic stacks read: the outer category, the inner category, and
+ * each cell's `value`. svelteplot reads all three straight off the rows, so
+ * they're field keys, not functions.
+ */
+export type StackMosaicChannels = {
+    data?: Record<string, unknown>[];
+    x?: string;
+    y?: string;
+    value?: string;
+    fill?: TransformChannel;
+    stroke?: TransformChannel;
+};
+/** The keys of {@link StackMosaicChannels}, at runtime - see {@link POSITION_CHANNEL_KEYS}. */
+export declare const STACK_MOSAIC_CHANNEL_KEYS: Record<keyof StackMosaicChannels, true>;
+/**
+ * Options the mosaic stacks take. svelteplot nests them as `{ x: { percent }, y: { percent } }`,
+ * which would clash with the flat `x`/`y` channels, so they're flattened here.
+ */
+type StackMosaicOptions = {
+    /** Puts `x` in fractions of the whole (0-1) instead of the values' own sums. */
+    percentX?: boolean;
+    /** Puts `y` in fractions of the whole (0-1) instead of the values' own sums. */
+    percentY?: boolean;
+};
+/**
+ * `stackMosaicX` as a marker transform: a mosaic (Marimekko) layout. Each `x`
+ * category gets a column as wide as its total `value`, split along `y` by its
+ * inner categories. Produces `x1`/`x2`/`y1`/`y2` for a `rect` marker.
+ */
+export type StackMosaicXTransform = {
+    type: 'stackMosaicX';
+} & StackMosaicChannels & StackMosaicOptions;
+/** `stackMosaicY` - see {@link StackMosaicXTransform}, with the outer categories along `y`. */
+export type StackMosaicYTransform = {
+    type: 'stackMosaicY';
+} & StackMosaicChannels & StackMosaicOptions;
+export {};

package/dist/types/transforms/stack.js

@@ -0,0 +1,12 @@
+import { POSITION_CHANNEL_KEYS } from './common';
+/** The keys of {@link StackChannels}, at runtime. */
+export const STACK_CHANNEL_KEYS = POSITION_CHANNEL_KEYS;
+/** The keys of {@link StackMosaicChannels}, at runtime - see {@link POSITION_CHANNEL_KEYS}. */
+export const STACK_MOSAIC_CHANNEL_KEYS = {
+    data: true,
+    x: true,
+    y: true,
+    value: true,
+    fill: true,
+    stroke: true
+};

package/dist/types/transforms/window.d.ts

@@ -0,0 +1,29 @@
+import type { PositionChannels } from './common';
+/** The reducers svelteplot's window transforms take by name. */
+export type WindowReducer = 'count' | 'deviation' | 'difference' | 'first' | 'last' | 'max' | 'mean' | 'median' | 'min' | 'mode' | 'ratio' | 'sum' | 'variance';
+/** Options both window transforms take, flat next to the channels - same names as svelteplot's. */
+type WindowOptions = {
+    /** The window's size, in rows (or in `interval`s, when one is set). */
+    k: number;
+    /** What each window reduces to; defaults to `mean`. */
+    reduce?: WindowReducer | ((values: any[]) => unknown);
+    /** Where each row sits in its window; defaults to `middle`. */
+    anchor?: 'start' | 'middle' | 'end';
+    /** Leaves out a window with fewer than `k` values (or than the number given), instead of reducing what it has. */
+    strict?: boolean | number;
+    /** Measures the window along the other axis in this interval (`'day'`, `7`, …) instead of in rows. */
+    interval?: number | string;
+};
+/**
+ * `windowY` as a marker transform: replaces each row's `y` (and `y1`/`y2`) with
+ * a reduction of the `k` rows around it - a moving average by default. Runs
+ * per `z` group, in row order.
+ */
+export type WindowYTransform = {
+    type: 'windowY';
+} & PositionChannels & WindowOptions;
+/** `windowX` - see {@link WindowYTransform}, on the `x` channels. */
+export type WindowXTransform = {
+    type: 'windowX';
+} & PositionChannels & WindowOptions;
+export {};

package/dist/types/transforms/window.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/ContinuousDomain.d.ts

@@ -0,0 +1,12 @@
+import type { LegendRange } from '../types/layout/legend';
+/** The domain a continuous color ramp is drawn over. */
+export declare class ContinuousDomain {
+    /**
+     * The `[min, max]` a continuous color ramp spans: the author's numeric
+     * `domain`, or the extent of `values` - reaching zero with `fromZero`.
+     * `null` when there is neither.
+     */
+    static build(authorDomain: readonly unknown[] | undefined, values: number[], fromZero?: boolean): [number, number] | null;
+    /** The domain a ramp is drawn over: the legend's narrowed range in `'rescale'` mode, `domain` otherwise. */
+    static ramp(domain: [number, number], range: Pick<LegendRange, 'mode' | 'min' | 'max'> | null | undefined): [number, number];
+}

package/dist/utils/ContinuousDomain.js

@@ -0,0 +1,19 @@
+/** The domain a continuous color ramp is drawn over. */
+export class ContinuousDomain {
+    /**
+     * The `[min, max]` a continuous color ramp spans: the author's numeric
+     * `domain`, or the extent of `values` - reaching zero with `fromZero`.
+     * `null` when there is neither.
+     */
+    static build(authorDomain, values, fromZero = false) {
+        if (authorDomain && typeof authorDomain[0] === 'number')
+            return authorDomain;
+        if (!values.length)
+            return null;
+        return [Math.min(...values, ...(fromZero ? [0] : [])), Math.max(...values)];
+    }
+    /** The domain a ramp is drawn over: the legend's narrowed range in `'rescale'` mode, `domain` otherwise. */
+    static ramp(domain, range) {
+        return range && range.mode === 'rescale' ? [range.min, range.max] : domain;
+    }
+}

package/dist/utils/Interpolation.d.ts

@@ -0,0 +1,26 @@
+import type { EasingName, EasingFn } from '../types/misc/easing';
+import type { TimeValue, TimelineInterpolation } from '../types/layout/timeline';
+import type { AxisValue } from '../types/layout/mapping';
+import type { Accessor } from '../types/plots/data/common';
+/** Easing curves, and the tweens a timeline draws between its steps. */
+export declare class Interpolation {
+    static readonly EASINGS: Record<EasingName, EasingFn>;
+    static buildEasing(easing?: EasingName | EasingFn): EasingFn;
+    /**
+     * Tweens one key-group's sorted rows at a continuous position `x`: every
+     * passed row plus the synthetic row between the two surrounding ones.
+     */
+    static tweenSeries<TRow>({ rows, x, getTime, getValue, create, segmentEasing }: {
+        rows: TRow[];
+        x: TimeValue;
+        getTime: (row: TRow) => TimeValue;
+        getValue: (row: TRow) => number;
+        create: (lower: TRow, upper: TRow, x: TimeValue, value: number) => TRow;
+        segmentEasing: EasingFn;
+    }): TRow[];
+    /** `TimelineConfig.interpolate` as a full {@link TimelineInterpolation}, with the plot's `value`/`key` as defaults. */
+    static buildTimeline<TRow extends Record<string, unknown>>(interpolate: boolean | TimelineInterpolation<TRow> | undefined, defaults: {
+        value: Accessor<TRow, AxisValue>;
+        key?: Accessor<TRow, unknown>;
+    }): TimelineInterpolation<TRow> | undefined;
+}

package/dist/utils/Interpolation.js

@@ -0,0 +1,65 @@
+/** Easing curves, and the tweens a timeline draws between its steps. */
+export class Interpolation {
+    static EASINGS = {
+        linear: (t) => t,
+        quadIn: (t) => t * t,
+        quadOut: (t) => 1 - (1 - t) * (1 - t),
+        cubicIn: (t) => t * t * t,
+        cubicOut: (t) => 1 - Math.pow(1 - t, 3),
+        quartIn: (t) => t * t * t * t,
+        quartOut: (t) => 1 - Math.pow(1 - t, 4),
+        expoOut: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t))
+    };
+    static buildEasing(easing) {
+        if (!easing)
+            return Interpolation.EASINGS.linear;
+        if (typeof easing === 'function')
+            return easing;
+        return Interpolation.EASINGS[easing] ?? Interpolation.EASINGS.linear;
+    }
+    /**
+     * Tweens one key-group's sorted rows at a continuous position `x`: every
+     * passed row plus the synthetic row between the two surrounding ones.
+     */
+    static tweenSeries({ rows, x, getTime, getValue, create, segmentEasing }) {
+        if (!rows.length)
+            return [];
+        const sorted = [...rows].sort((a, b) => Number(getTime(a)) - Number(getTime(b)));
+        if (x <= getTime(sorted[0]))
+            return [sorted[0]];
+        const result = [];
+        for (let i = 0; i < sorted.length - 1; i++) {
+            const d0 = sorted[i];
+            const d1 = sorted[i + 1];
+            const t0 = getTime(d0);
+            const t1 = getTime(d1);
+            if (x >= t1) {
+                result.push(d0);
+                continue;
+            }
+            if (x >= t0 && x < t1) {
+                const tRaw = (Number(x) - Number(t0)) / (Number(t1) - Number(t0));
+                const t = segmentEasing(tRaw);
+                const value = getValue(d0) + (getValue(d1) - getValue(d0)) * t;
+                result.push(d0);
+                result.push(create(d0, d1, x, value));
+                return result;
+            }
+        }
+        const last = sorted[sorted.length - 1];
+        if (x >= getTime(last))
+            result.push(last);
+        return result;
+    }
+    /** `TimelineConfig.interpolate` as a full {@link TimelineInterpolation}, with the plot's `value`/`key` as defaults. */
+    static buildTimeline(interpolate, defaults) {
+        if (!interpolate)
+            return undefined;
+        const config = interpolate === true ? {} : interpolate;
+        return {
+            ...config,
+            value: config.value ?? defaults.value,
+            key: config.key ?? defaults.key
+        };
+    }
+}

package/dist/utils/{color.d.ts → color/contrast.d.ts}

@@ -1,7 +1,3 @@
-export declare function resolveCssColor(color: string): string;
-export declare function normalize(v: number, min: number, max: number): number;
-/** Cycles through a discrete palette by series index — the default colour for an unstyled series. */
-export declare function paletteColor(index: number, palette: string[]): string;
 /** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
 export declare function contrastRatio(colorA: string, colorB: string): number;
 /**
@@ -11,4 +7,3 @@ export declare function contrastRatio(colorA: string, colorB: string): number;
  * `background` can't be parsed.
  */
 export declare function contrastTextColor(background: string, candidates?: string[]): string;
-export declare function makeColorScale(min: number, max: number, colorMin: string, colorMax: string): (v: number) => string;

package/dist/utils/color/contrast.js

@@ -0,0 +1,40 @@
+import { resolveCssColor, parseRgb } from './cssColor';
+function relativeLuminance([r, g, b]) {
+    const [rs, gs, bs] = [r, g, b].map((c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+/** WCAG contrast ratio between two colors, from 1 (no contrast) to 21 (black on white). */
+export function contrastRatio(colorA, colorB) {
+    const a = parseRgb(resolveCssColor(colorA));
+    const b = parseRgb(resolveCssColor(colorB));
+    if (!a || !b)
+        return 1;
+    const lA = relativeLuminance(a);
+    const lB = relativeLuminance(b);
+    const lighter = Math.max(lA, lB);
+    const darker = Math.min(lA, lB);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * The `candidates` entry with the highest WCAG contrast ratio against
+ * `background`. Defaults to plain white/black; pass a grayscale or other
+ * palette to widen the choice. Falls back to the first candidate when
+ * `background` can't be parsed.
+ */
+export function contrastTextColor(background, candidates = ['#ffffff', '#000000']) {
+    if (candidates.length === 0)
+        return '#000000';
+    let best = candidates[0];
+    let bestRatio = -Infinity;
+    for (const candidate of candidates) {
+        const ratio = contrastRatio(background, candidate);
+        if (ratio > bestRatio) {
+            bestRatio = ratio;
+            best = candidate;
+        }
+    }
+    return best;
+}

package/dist/utils/color/cssColor.d.ts

@@ -0,0 +1,4 @@
+/** Resolves a `var(--x)` reference to its computed value; any other CSS color string passes through unchanged. */
+export declare function resolveCssColor(color: string): string;
+/** Parses any CSS color syntax (hex, rgb(), oklch(), named colors, hsl(), ...) into an `[r, g, b]` (0-255) triple, or `null` if it can't be resolved. */
+export declare function parseRgb(color: string): [number, number, number] | null;

package/dist/utils/color/cssColor.js

@@ -0,0 +1,77 @@
+import { isBrowser } from '../../stores/device';
+/** Resolves a `var(--x)` reference to its computed value; any other CSS color string passes through unchanged. */
+export function resolveCssColor(color) {
+    if (!isBrowser)
+        return color;
+    if (!color.startsWith('var('))
+        return color;
+    const varName = color.slice(4, -1).trim();
+    const value = getComputedStyle(document.documentElement).getPropertyValue(varName).trim();
+    return value || color;
+}
+function clamp01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+function linearToSrgb8(c) {
+    const s = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+    return clamp01(s) * 255;
+}
+/**
+ * Parses `oklch(L C H)` directly instead of round-tripping through the
+ * browser's computed style: Chromium/Firefox serialize computed oklch()
+ * values back as oklch() (not rgb()), so the generic browser-fallback below
+ * sees an unchanged string on the second pass and its infinite-loop guard
+ * mistakes that for a parse failure.
+ */
+function parseOklch(color) {
+    const match = /^oklch\(\s*([\d.]+)(%)?\s+([\d.]+)\s+([\d.]+)/i.exec(color.trim());
+    if (!match)
+        return null;
+    const L = match[2] ? Number(match[1]) / 100 : Number(match[1]);
+    const C = Number(match[3]);
+    const H = (Number(match[4]) * Math.PI) / 180;
+    const a = C * Math.cos(H);
+    const b = C * Math.sin(H);
+    const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+    const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+    const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+    const l = l_ ** 3;
+    const m = m_ ** 3;
+    const s = s_ ** 3;
+    const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+    const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+    const bl = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+    return [linearToSrgb8(r), linearToSrgb8(g), linearToSrgb8(bl)];
+}
+/** Parses any CSS color syntax (hex, rgb(), oklch(), named colors, hsl(), ...) into an `[r, g, b]` (0-255) triple, or `null` if it can't be resolved. */
+export function parseRgb(color) {
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+    if (hex) {
+        const digits = hex[1].length === 3
+            ? hex[1]
+                .split('')
+                .map((c) => c + c)
+                .join('')
+            : hex[1];
+        const num = parseInt(digits, 16);
+        return [(num >> 16) & 255, (num >> 8) & 255, num & 255];
+    }
+    const rgb = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/i.exec(color);
+    if (rgb)
+        return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+    const oklch = parseOklch(color);
+    if (oklch)
+        return oklch;
+    // Named colors, hsl(), and any other CSS color syntax: resolved to
+    // `rgb(...)` via the browser's computed style, then reparsed.
+    if (!isBrowser)
+        return null;
+    const el = document.createElement('div');
+    el.style.color = color;
+    document.body.appendChild(el);
+    const computed = getComputedStyle(el).color;
+    document.body.removeChild(el);
+    if (!computed || computed === color)
+        return null;
+    return parseRgb(computed);
+}

package/dist/utils/color/index.d.ts

@@ -0,0 +1,3 @@
+export { resolveCssColor } from './cssColor';
+export { contrastRatio, contrastTextColor } from './contrast';
+export { normalize, paletteColor, makeColorScale, resolveColorScale } from './ramp';

package/dist/utils/color/index.js

@@ -0,0 +1,3 @@
+export { resolveCssColor } from './cssColor';
+export { contrastRatio, contrastTextColor } from './contrast';
+export { normalize, paletteColor, makeColorScale, resolveColorScale } from './ramp';

package/dist/utils/color/ramp.d.ts

@@ -0,0 +1,17 @@
+import type { ColorScaleConfig } from '../../types/layout/scales';
+/** Linearly maps `v` from `[min, max]` onto `[0, 1]`, clamped at both ends. */
+export declare function normalize(v: number, min: number, max: number): number;
+/** Cycles through a discrete palette by series index - the default colour for an unstyled series. */
+export declare function paletteColor(index: number, palette: string[]): string;
+/** A simple 2-color continuous ramp over `[min, max]`. */
+export declare function makeColorScale(min: number, max: number, colorMin: string, colorMax: string): (v: number) => string;
+/**
+ * Resolves a {@link ColorScaleConfig} into a `value => color` function - the
+ * one shared implementation for every level the config can appear at
+ * (`scales.color`, a `segments` entry, a marker's own `scales`).
+ * `computedDomain` is the fallback when `config.domain` is unset;
+ * `defaultScheme` is used when `config.scheme` is unset - the theme's own
+ * 2-color continuous ramp, or a discrete palette for a categorical domain
+ * (e.g. per-series identity colors).
+ */
+export declare function resolveColorScale(config: ColorScaleConfig | undefined, computedDomain: [number, number] | string[] | undefined, defaultScheme: NonNullable<ColorScaleConfig['scheme']>): (value: unknown) => string;

package/dist/utils/color/ramp.js

@@ -0,0 +1,110 @@
+import { interpolateRgb, piecewise } from 'd3-interpolate';
+import * as d3Chromatic from 'd3-scale-chromatic';
+import { resolveCssColor } from './cssColor';
+/** Linearly maps `v` from `[min, max]` onto `[0, 1]`, clamped at both ends. */
+export function normalize(v, min, max) {
+    if (v == null)
+        return 0;
+    const denom = max - min || 1;
+    return Math.max(0, Math.min(1, (v - min) / denom));
+}
+/** Cycles through a discrete palette by series index - the default colour for an unstyled series. */
+export function paletteColor(index, palette) {
+    if (palette.length === 0)
+        return 'currentColor';
+    return palette[index % palette.length];
+}
+/** A simple 2-color continuous ramp over `[min, max]`. */
+export function makeColorScale(min, max, colorMin, colorMax) {
+    const resolvedMin = resolveCssColor(colorMin);
+    const resolvedMax = resolveCssColor(colorMax);
+    let interpolator;
+    try {
+        interpolator = interpolateRgb(resolvedMin, resolvedMax);
+    }
+    catch {
+        return () => '#ccc';
+    }
+    return (v) => {
+        if (v == null)
+            return '#ccc';
+        const t = normalize(v, min, max);
+        return interpolator(t);
+    };
+}
+/** `{turbo: interpolateTurbo, blues: interpolateBlues, ...}`, built from every `interpolate*` d3-scale-chromatic export. */
+const NAMED_SCHEMES = Object.fromEntries(Object.entries(d3Chromatic)
+    .filter((entry) => entry[0].startsWith('interpolate'))
+    .map(([name, fn]) => [name.slice('interpolate'.length).toLowerCase(), fn]));
+/**
+ * Resolves a {@link ColorScaleConfig} into a `value => color` function - the
+ * one shared implementation for every level the config can appear at
+ * (`scales.color`, a `segments` entry, a marker's own `scales`).
+ * `computedDomain` is the fallback when `config.domain` is unset;
+ * `defaultScheme` is used when `config.scheme` is unset - the theme's own
+ * 2-color continuous ramp, or a discrete palette for a categorical domain
+ * (e.g. per-series identity colors).
+ */
+export function resolveColorScale(config, computedDomain, defaultScheme) {
+    const domain = config?.domain ?? computedDomain;
+    const scheme = config?.scheme ?? defaultScheme;
+    const unknown = config?.unknown ?? '#ccc';
+    if (!domain || domain.length === 0)
+        return () => unknown;
+    // A category → color map always resolves by direct lookup, regardless of domain shape.
+    if (typeof scheme === 'object' && !Array.isArray(scheme)) {
+        return (v) => (v == null ? unknown : (scheme[String(v)] ?? unknown));
+    }
+    // A named d3-scale-chromatic ramp (e.g. 'turbo') resolves straight to its own interpolator.
+    const namedInterpolator = typeof scheme === 'string' ? NAMED_SCHEMES[scheme.toLowerCase()] : undefined;
+    if (typeof scheme === 'string' && !namedInterpolator)
+        return () => unknown;
+    const resolvedScheme = namedInterpolator ? undefined : scheme.map(resolveCssColor);
+    if (resolvedScheme && resolvedScheme.length === 0)
+        return () => unknown;
+    if (resolvedScheme && resolvedScheme.length === 1) {
+        const only = resolvedScheme[0];
+        return () => only;
+    }
+    // Categorical domain (explicit category list): sample the ramp evenly, one stop per category.
+    if (typeof domain[0] === 'string') {
+        const categories = domain;
+        const swatches = resolvedScheme ??
+            categories.map((_, i) => namedInterpolator(categories.length > 1 ? i / (categories.length - 1) : 0));
+        return (v) => {
+            if (v == null)
+                return unknown;
+            const idx = categories.indexOf(String(v));
+            return idx < 0 ? unknown : swatches[idx % swatches.length];
+        };
+    }
+    // Continuous domain: interpolate smoothly across every scheme stop (or the named ramp directly).
+    const [lo, hi] = domain;
+    let interpolator;
+    if (namedInterpolator) {
+        interpolator = namedInterpolator;
+    }
+    else {
+        try {
+            interpolator = piecewise(interpolateRgb, resolvedScheme);
+        }
+        catch {
+            return () => unknown;
+        }
+    }
+    const pivot = config?.pivot;
+    const stopCount = resolvedScheme?.length ?? Infinity;
+    return (v) => {
+        if (v == null)
+            return unknown;
+        const n = Number(v);
+        if (Number.isNaN(n))
+            return unknown;
+        const t = pivot != null && stopCount >= 3
+            ? n <= pivot
+                ? 0.5 * normalize(n, lo, pivot)
+                : 0.5 + 0.5 * normalize(n, pivot, hi)
+            : normalize(n, lo, hi);
+        return interpolator(t);
+    };
+}

package/dist/utils/grouping.d.ts

@@ -1,4 +1,4 @@
-import type { AxisValue } from '../types/layout/scales';
+import type { AxisValue } from '../types/layout/mapping';
 import type { Series, Accessor } from '../types/plots/data/common';
 /**
  * Splits rows into ordered groups keyed by the stringified accessor value.
@@ -8,8 +8,12 @@ import type { Series, Accessor } from '../types/plots/data/common';
 export declare function groupBy<TRow extends Record<string, unknown>>(data: TRow[], by: Accessor<TRow, unknown>): Map<string, TRow[]>;
 /**
  * Adapts flat rows into the `Series[]` shape the plot expects.
- * When `z` is given, one series is produced per group (series `name` = group
- * value), which is exactly how the plot's `segments` map is keyed — so the
- * caller styles each group by its `z` value.
+ * When `grouping` is given, one series is produced per group (series `name`
+ * = group value), which is exactly how the plot's `segments` map is keyed -
+ * so the caller styles/colors each group by its own value (see
+ * `scales.color`). A position channel the author left out stays unset on
+ * every series.
  */
-export declare function buildSeries<TRow extends Record<string, unknown>>(data: TRow[], x: Accessor<TRow, AxisValue>, y: Accessor<TRow, AxisValue>, z: Accessor<TRow, unknown> | undefined, defaultName?: string): Series<TRow>[];
+export declare function buildSeries<TRow extends Record<string, unknown>>(data: TRow[], x: Accessor<TRow, AxisValue> | undefined, y: Accessor<TRow, AxisValue> | undefined, grouping: Accessor<TRow, unknown> | undefined, defaultName?: string): Series<TRow>[];
+/** A series' id: its own `id`, or its `name`. */
+export declare function seriesIdOf(series: Pick<Series, 'name' | 'id'>): string;

package/dist/utils/grouping.js

@@ -19,18 +19,27 @@ export function groupBy(data, by) {
 }
 /**
  * Adapts flat rows into the `Series[]` shape the plot expects.
- * When `z` is given, one series is produced per group (series `name` = group
- * value), which is exactly how the plot's `segments` map is keyed — so the
- * caller styles each group by its `z` value.
+ * When `grouping` is given, one series is produced per group (series `name`
+ * = group value), which is exactly how the plot's `segments` map is keyed -
+ * so the caller styles/colors each group by its own value (see
+ * `scales.color`). A position channel the author left out stays unset on
+ * every series.
  */
-export function buildSeries(data, x, y, z, defaultName = 'series') {
-    if (z === undefined) {
-        return [{ name: defaultName, x, y, data }];
+export function buildSeries(data, x, y, grouping, defaultName = 'series') {
+    if (grouping === undefined) {
+        return [{ name: defaultName, ...channels(x, y), data }];
     }
-    return [...groupBy(data, z).entries()].map(([name, rows]) => ({
+    return [...groupBy(data, grouping).entries()].map(([name, rows]) => ({
         name,
-        x,
-        y,
-        data: rows,
+        ...channels(x, y),
+        data: rows
     }));
 }
+/** The position channels a series carries: only the ones set. */
+function channels(x, y) {
+    return { ...(x !== undefined ? { x } : {}), ...(y !== undefined ? { y } : {}) };
+}
+/** A series' id: its own `id`, or its `name`. */
+export function seriesIdOf(series) {
+    return series.id ?? series.name;
+}

package/dist/utils/merge.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `patch` deep-merged over `base`: plain objects merge key by key, anything
+ * else (arrays included) in `patch` replaces, and an `undefined` in `patch`
+ * leaves `base` as it is. Either side may be absent - the other is returned.
+ */
+export declare function merge<T extends object>(base: T, patch: object | undefined): T;
+export declare function merge<T extends object>(base: T | undefined, patch: T | undefined): T | undefined;

package/dist/utils/merge.js

@@ -0,0 +1,17 @@
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function merge(base, patch) {
+    if (!base)
+        return patch;
+    if (!patch)
+        return base;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        const prev = out[key];
+        out[key] = isPlainObject(prev) && isPlainObject(value) ? merge(prev, value) : value;
+    }
+    return out;
+}

package/dist/utils/opacity.d.ts

@@ -0,0 +1,9 @@
+import type { OpacityScaleConfig } from '../types/layout/scales';
+/**
+ * Resolves an {@link OpacityScaleConfig} into a `value => opacity` function -
+ * mirrors `resolveColorScale`'s shape, but the output is always a number in
+ * roughly `[0,1]` instead of a CSS color string. Callers must apply the
+ * result as a literal constant per mark instance (never a per-row function
+ * handed straight to svelteplot) - see the type's own doc comment for why.
+ */
+export declare function resolveOpacityScale(config: OpacityScaleConfig | undefined, computedDomain: [number, number] | string[] | undefined, defaultRange: [number, number]): (value: unknown) => number;

package/dist/utils/opacity.js

@@ -0,0 +1,38 @@
+import { normalize } from './color';
+/**
+ * Resolves an {@link OpacityScaleConfig} into a `value => opacity` function -
+ * mirrors `resolveColorScale`'s shape, but the output is always a number in
+ * roughly `[0,1]` instead of a CSS color string. Callers must apply the
+ * result as a literal constant per mark instance (never a per-row function
+ * handed straight to svelteplot) - see the type's own doc comment for why.
+ */
+export function resolveOpacityScale(config, computedDomain, defaultRange) {
+    const domain = config?.domain ?? computedDomain;
+    const range = config?.range ?? defaultRange;
+    const unknown = config?.unknown ?? 1;
+    if (!domain || domain.length === 0)
+        return () => unknown;
+    if (typeof range === 'object' && !Array.isArray(range)) {
+        return (v) => (v == null ? unknown : (range[String(v)] ?? unknown));
+    }
+    if (typeof domain[0] === 'string') {
+        const categories = domain;
+        const [lo, hi] = range;
+        return (v) => {
+            if (v == null)
+                return unknown;
+            const idx = categories.indexOf(String(v));
+            if (idx < 0)
+                return unknown;
+            return categories.length > 1 ? lo + ((hi - lo) * idx) / (categories.length - 1) : lo;
+        };
+    }
+    const [dLo, dHi] = domain;
+    const [rLo, rHi] = range;
+    return (v) => {
+        if (v == null)
+            return unknown;
+        const t = normalize(Number(v), dLo, dHi);
+        return rLo + (rHi - rLo) * t;
+    };
+}