@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/phases/transforms/methods/OrderTransform.js

@@ -0,0 +1,43 @@
+import { sort, shuffle, reverse, filter, select } from 'svelteplot';
+import { POSITION_CHANNEL_KEYS } from '../../../types/transforms/common';
+import { SORT_CHANNEL_KEYS } from '../../../types/transforms/sort';
+import { FILTER_CHANNEL_KEYS } from '../../../types/transforms/filter';
+import { PositionTransform } from './PositionTransform';
+/** Transforms that choose and order rows: sort, shuffle, reverse, filter and select. */
+export class OrderTransform {
+    static sort = {
+        channelKeys: SORT_CHANNEL_KEYS,
+        run: sort
+    };
+    static shuffle = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: (channels, options) => shuffle(channels, {
+            seed: options.seed ?? PositionTransform.DEFAULT_SEED
+        })
+    };
+    static reverse = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: (channels) => reverse(channels)
+    };
+    static filter = {
+        channelKeys: FILTER_CHANNEL_KEYS,
+        run: (channels) => filter(channels)
+    };
+    static select = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: (channels, options) => select(channels, options.select)
+    };
+    static first = OrderTransform.#selectBy('first');
+    static last = OrderTransform.#selectBy('last');
+    static minX = OrderTransform.#selectBy({ x: 'min' });
+    static maxX = OrderTransform.#selectBy({ x: 'max' });
+    static minY = OrderTransform.#selectBy({ y: 'min' });
+    static maxY = OrderTransform.#selectBy({ y: 'max' });
+    /** A `select` with what it keeps fixed: the shorthands `selectFirst`, `selectMaxY`, ... */
+    static #selectBy(by) {
+        return {
+            channelKeys: POSITION_CHANNEL_KEYS,
+            run: (channels) => select(channels, by)
+        };
+    }
+}

package/dist/phases/transforms/methods/PerGroup.d.ts

@@ -0,0 +1,11 @@
+import type { TransformAdapter } from '../../../types/phases/transforms/adapter';
+/** Runs transforms that ignore `z` once per group. */
+export declare class PerGroup {
+    /**
+     * Runs a transform that ignores `z` once per `z` group, then joins the groups'
+     * output rows back together. Each output row is tagged with its group - under
+     * `z`'s own field, or {@link GROUP_KEY} for a function - since such a transform
+     * may build its rows from scratch, without the source row's fields.
+     */
+    static run(run: TransformAdapter['run']): TransformAdapter['run'];
+}

package/dist/phases/transforms/methods/PerGroup.js

@@ -0,0 +1,39 @@
+/** The field a `PerGroup.run` output row carries its group under, when `z` is a function. */
+const GROUP_KEY = '__group_z';
+/** Runs transforms that ignore `z` once per group. */
+export class PerGroup {
+    /**
+     * Runs a transform that ignores `z` once per `z` group, then joins the groups'
+     * output rows back together. Each output row is tagged with its group - under
+     * `z`'s own field, or {@link GROUP_KEY} for a function - since such a transform
+     * may build its rows from scratch, without the source row's fields.
+     */
+    static run(run) {
+        return (channels, options) => {
+            const { z, data, ...rest } = channels;
+            const rows = data ?? [];
+            if (z == null || !rows.length)
+                return run(channels, options);
+            const read = typeof z === 'function' ? z : (d) => d[z];
+            const key = typeof z === 'function' ? GROUP_KEY : z;
+            const groups = new Map();
+            for (const row of rows) {
+                const value = read(row);
+                const group = groups.get(value);
+                if (group)
+                    group.push(row);
+                else
+                    groups.set(value, [row]);
+            }
+            const outputs = [...groups].map(([value, groupRows]) => {
+                const out = run({ ...rest, data: groupRows }, options);
+                return { out, value };
+            });
+            return {
+                ...outputs[0].out,
+                data: outputs.flatMap(({ out, value }) => (out.data ?? []).map((row) => ({ ...row, [key]: value }))),
+                z: key
+            };
+        };
+    }
+}

package/dist/phases/transforms/methods/PositionTransform.d.ts

@@ -0,0 +1,15 @@
+import type { TransformAdapter } from '../../../types/phases/transforms/adapter';
+/** Interval, jitter and shift transforms, by axis. */
+export declare class PositionTransform {
+    #private;
+    /** The seed a random transform uses when none is given, so it draws the same way on every render. */
+    static readonly DEFAULT_SEED = 42;
+    /** A small seeded PRNG (mulberry32): the same seed always yields the same sequence in [0, 1). */
+    static seededRandom(seed: number): () => number;
+    static readonly intervalX: TransformAdapter;
+    static readonly intervalY: TransformAdapter;
+    static readonly jitterX: TransformAdapter;
+    static readonly jitterY: TransformAdapter;
+    static readonly shiftX: TransformAdapter;
+    static readonly shiftY: TransformAdapter;
+}

package/dist/phases/transforms/methods/PositionTransform.js

@@ -0,0 +1,74 @@
+import { intervalX, intervalY, jitterX, jitterY, shiftX, shiftY } from 'svelteplot';
+import { POSITION_CHANNEL_KEYS } from '../../../types/transforms/common';
+import { INTERVAL_CHANNEL_KEYS } from '../../../types/transforms/interval';
+import { AnchorBar } from './AnchorBar';
+/** Interval, jitter and shift transforms, by axis. */
+export class PositionTransform {
+    /** The seed a random transform uses when none is given, so it draws the same way on every render. */
+    static DEFAULT_SEED = 42;
+    /** A small seeded PRNG (mulberry32): the same seed always yields the same sequence in [0, 1). */
+    static seededRandom(seed) {
+        let state = seed | 0;
+        return () => {
+            state = (state + 0x6d2b79f5) | 0;
+            let t = Math.imul(state ^ (state >>> 15), 1 | state);
+            t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        };
+    }
+    static intervalX = {
+        channelKeys: INTERVAL_CHANNEL_KEYS,
+        run: PositionTransform.#runInterval(intervalX),
+        finish: AnchorBar.toZero('y')
+    };
+    static intervalY = {
+        channelKeys: INTERVAL_CHANNEL_KEYS,
+        run: PositionTransform.#runInterval(intervalY),
+        finish: AnchorBar.toZero('x')
+    };
+    static jitterX = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: (channels, options) => jitterX(channels, PositionTransform.#jitterOptions(options, 'x'))
+    };
+    static jitterY = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: (channels, options) => jitterY(channels, PositionTransform.#jitterOptions(options, 'y'))
+    };
+    // svelteplot takes the amount itself as the second argument, not an options object.
+    static shiftX = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: (channels, options) => shiftX(channels, options.by)
+    };
+    static shiftY = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: (channels, options) => shiftY(channels, options.by)
+    };
+    /**
+     * Runs an interval transform. svelteplot reads `interval` next to the channels,
+     * in a single argument, and hands it back with them; it's dropped from the
+     * output, since on a `rect` it would read as the rect's own `interval` and
+     * widen the already-widened edges again.
+     */
+    static #runInterval(transform) {
+        return (channels) => {
+            const out = { ...transform(channels) };
+            delete out.interval;
+            return out;
+        };
+    }
+    /**
+     * The flat jitter options back into svelteplot's own: `distribution` is its
+     * `type`, and the noise is seeded unless a `source` is given. Each axis has its
+     * own default seed: with the same one, `jitterX` and `jitterY` would draw the
+     * same offsets and move every point along a diagonal.
+     */
+    static #jitterOptions(options, axis) {
+        const distribution = options.distribution ?? 'uniform';
+        const defaultSeed = axis === 'x' ? PositionTransform.DEFAULT_SEED : PositionTransform.DEFAULT_SEED + 1;
+        const source = options.source ??
+            PositionTransform.seededRandom(options.seed ?? defaultSeed);
+        return distribution === 'normal'
+            ? { type: 'normal', std: options.std, source }
+            : { type: 'uniform', width: options.width, source };
+    }
+}

package/dist/phases/transforms/methods/StackTransform.d.ts

@@ -0,0 +1,8 @@
+import type { TransformAdapter } from '../../../types/phases/transforms/adapter';
+/** svelteplot's stack transforms, by axis. */
+export declare class StackTransform {
+    static readonly y: TransformAdapter;
+    static readonly x: TransformAdapter;
+    static readonly mosaicX: TransformAdapter;
+    static readonly mosaicY: TransformAdapter;
+}

package/dist/phases/transforms/methods/StackTransform.js

@@ -0,0 +1,29 @@
+import { stackX, stackY, stackMosaicX, stackMosaicY } from 'svelteplot';
+import { STACK_CHANNEL_KEYS, STACK_MOSAIC_CHANNEL_KEYS } from '../../../types/transforms/stack';
+/** The flat `percentX`/`percentY` back into svelteplot's nested `{ x: { percent }, y: { percent } }`. */
+function mosaicOptions(options) {
+    return {
+        x: { percent: options.percentX === true },
+        y: { percent: options.percentY === true }
+    };
+}
+/** svelteplot's stack transforms, by axis. */
+export class StackTransform {
+    // No fixes: svelteplot's own output already carries each layer's `y1`/`y2` (or `x1`/`x2`).
+    static y = {
+        channelKeys: STACK_CHANNEL_KEYS,
+        run: stackY
+    };
+    static x = {
+        channelKeys: STACK_CHANNEL_KEYS,
+        run: stackX
+    };
+    static mosaicX = {
+        channelKeys: STACK_MOSAIC_CHANNEL_KEYS,
+        run: (channels, options) => stackMosaicX(channels, mosaicOptions(options))
+    };
+    static mosaicY = {
+        channelKeys: STACK_MOSAIC_CHANNEL_KEYS,
+        run: (channels, options) => stackMosaicY(channels, mosaicOptions(options))
+    };
+}

package/dist/phases/transforms/methods/WindowTransform.d.ts

@@ -0,0 +1,8 @@
+import type { TransformAdapter } from '../../../types/phases/transforms/adapter';
+/** Sliding-window and Bollinger transforms, by axis. */
+export declare class WindowTransform {
+    static readonly windowX: TransformAdapter;
+    static readonly windowY: TransformAdapter;
+    static readonly bollingerX: TransformAdapter;
+    static readonly bollingerY: TransformAdapter;
+}

package/dist/phases/transforms/methods/WindowTransform.js

@@ -0,0 +1,23 @@
+import { windowX, windowY, bollingerX, bollingerY } from 'svelteplot';
+import { POSITION_CHANNEL_KEYS } from '../../../types/transforms/common';
+import { PerGroup } from './PerGroup';
+/** Sliding-window and Bollinger transforms, by axis. */
+export class WindowTransform {
+    static windowX = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: windowX
+    };
+    static windowY = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: windowY
+    };
+    // svelteplot's Bollinger bands run over every row at once, so they're run per group here.
+    static bollingerX = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: PerGroup.run(bollingerX)
+    };
+    static bollingerY = {
+        channelKeys: POSITION_CHANNEL_KEYS,
+        run: PerGroup.run(bollingerY)
+    };
+}

package/dist/plots/area/Plot.svelte

@@ -0,0 +1,42 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import Plot from '../../layout/plot/Plot.svelte';
+	import { buildAreaDefaults } from './defaults';
+	import type { AreaPlotProps, AreaPlotCoreProps } from '../../types/plots/area/props';
+
+	/**
+	 * An area per series, filled from its own baseline. Draws from pre-built `series` or flat `data` rows.
+	 * Optional chrome (`title`, `subtitle`, `caption`, `header`, `footer`,
+	 * `legend`) frames it; `timeline` and `facet` slice its `data` rows.
+	 * `margins` is bindable: it reports the margin the plot settled on.
+	 */
+	let {
+		title,
+		subtitle,
+		caption,
+		header,
+		footer,
+		legend,
+		order,
+		timeline,
+		facet,
+		tooltip,
+		margins = $bindable(),
+		...core
+	}: AreaPlotProps<TData> = $props();
+</script>
+
+<Plot
+	core={core as AreaPlotCoreProps<TData>}
+	defaults={buildAreaDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>

package/dist/plots/{heatmap/ValueLabels.svelte.d.ts → area/Plot.svelte.d.ts}

@@ -1,17 +1,9 @@
-import type { AxisValue } from '../../types/layout/scales';
-import type { ValuesStyle } from '../../types/layout/styles';
+import Plot from '../../layout/plot/Plot.svelte';
+import type { AreaPlotProps } from '../../types/plots/area/props';
 declare function $$render<TData extends Record<string, unknown>>(): {
-    props: {
-        data: TData[];
-        getX: (d: TData) => AxisValue;
-        getY: (d: TData) => AxisValue;
-        getZ: (d: TData) => unknown;
-        formatValue: (value: number, seriesName: string) => string;
-        values: ValuesStyle | undefined;
-        defaultColor: string;
-    };
+    props: AreaPlotProps<TData>;
     exports: {};
-    bindings: "";
+    bindings: "margins";
     slots: {};
     events: {};
 };
@@ -19,7 +11,7 @@ declare class __sveltets_Render<TData extends Record<string, unknown>> {
     props(): ReturnType<typeof $$render<TData>>['props'];
     events(): ReturnType<typeof $$render<TData>>['events'];
     slots(): ReturnType<typeof $$render<TData>>['slots'];
-    bindings(): "";
+    bindings(): "margins";
     exports(): {};
 }
 interface $$IsomorphicComponent {
@@ -29,6 +21,6 @@ interface $$IsomorphicComponent {
     <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
-declare const ValueLabels: $$IsomorphicComponent;
-type ValueLabels<TData extends Record<string, unknown>> = InstanceType<typeof ValueLabels<TData>>;
-export default ValueLabels;
+declare const Plot: $$IsomorphicComponent;
+type Plot<TData extends Record<string, unknown>> = InstanceType<typeof Plot<TData>>;
+export default Plot;

package/dist/plots/area/defaults.d.ts

@@ -0,0 +1,4 @@
+import type { AxisPlotDefaults } from '../../types/phases';
+import type { AreaPlotState, AreaPlotCtx } from '../../types/plots/area/state';
+/** AreaPlot on the shared pipeline: areas from a zero baseline, author markers taking the plot's `x`/`y`, and its own markers. Its plot defaults to: hover along x, cumulative timeline tweening `y` per series. */
+export declare function buildAreaDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<AreaPlotState<TData>, AreaPlotCtx>;

package/dist/plots/area/defaults.js

@@ -0,0 +1,21 @@
+import { buildMarks } from './markers';
+/** AreaPlot on the shared pipeline: areas from a zero baseline, author markers taking the plot's `x`/`y`, and its own markers. Its plot defaults to: hover along x, cumulative timeline tweening `y` per series. */
+export function buildAreaDefaults() {
+    return {
+        data: { segments: { color: (style) => style?.fill } },
+        statistics: { inheritPositions: true },
+        scales: { zero: ['y'] },
+        styles: {
+            values: {
+                anchor: 'start',
+                format: (v, name) => `${name} - ${v}`,
+                reach: (labels, state) => labels.reachAtSeriesEnds(state)
+            }
+        },
+        markers: {
+            marks: buildMarks,
+            valueLabels: (labels, state) => labels.atSeriesEnds(state)
+        },
+        timeline: { filterMode: 'upTo', interpolation: { value: 'y', key: ['grouping'] } }
+    };
+}

package/dist/plots/area/markers.d.ts

@@ -0,0 +1,14 @@
+import type { AreaPlotState, AreaPlotCtx } from '../../types/plots/area/state';
+import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+/**
+ * AreaPlot's "markers" phase: one `area` per visual segment of each series,
+ * drawing the rows the "transforms" phase left (stacked, when the plot
+ * stacks). The markers the "statistics" phase already put in `state.markers`
+ * come after, so they render on top, and its value labels last - one at the
+ * end of each series, like LinePlot's.
+ *
+ * A series toggled off in the legend (style mode), or dimmed by hovering
+ * another series' value label, dims its own areas' fill to
+ * `legend.disabledOpacity`, in place, so a stack keeps its full extent.
+ */
+export declare function buildMarks<TData extends Record<string, unknown>>(state: AreaPlotState<TData>, ctx: AreaPlotCtx): AxisBasedMarkersConfig[];

package/dist/plots/area/markers.js

@@ -0,0 +1,39 @@
+import { Transforms } from '../../phases/transforms/Transforms';
+/**
+ * AreaPlot's "markers" phase: one `area` per visual segment of each series,
+ * drawing the rows the "transforms" phase left (stacked, when the plot
+ * stacks). The markers the "statistics" phase already put in `state.markers`
+ * come after, so they render on top, and its value labels last - one at the
+ * end of each series, like LinePlot's.
+ *
+ * A series toggled off in the legend (style mode), or dimmed by hovering
+ * another series' value label, dims its own areas' fill to
+ * `legend.disabledOpacity`, in place, so a stack keeps its full extent.
+ */
+export function buildMarks(state, ctx) {
+    const { resolvedSeries = [] } = state;
+    const { channels, options, transforms } = state.processedData;
+    const { cfg } = ctx;
+    // A fill opacity per series name, for the dim: a legend-off series fades to
+    // the legend's disabled opacity, every other one keeps the area default.
+    const fillOpacityOf = (name) => {
+        const off = ctx.interaction?.dimmed(name);
+        return off ? (off.opacity ?? cfg.legend.disabledOpacity) : cfg.area.fillOpacity;
+    };
+    const dimmed = resolvedSeries.some((s) => ctx.interaction?.dimmed(s.name));
+    const opacityScale = {
+        range: Object.fromEntries(resolvedSeries.map((s) => [s.name, fillOpacityOf(s.name)]))
+    };
+    // The dim channel: each area reads its own series name, looked up in `opacityScale`.
+    const dimByName = (name) => dimmed ? { opacity: () => name, scales: { opacity: opacityScale } } : {};
+    const areas = (state.processedGroups ?? []).flatMap((group) => group.visualSegments.map((seg) => Transforms.finish({
+        type: 'area',
+        series: group.series.name,
+        data: seg.data,
+        ...channels,
+        ...options,
+        styles: seg.styles,
+        ...dimByName(group.series.name)
+    }, transforms)));
+    return areas;
+}