@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/plots/heatmap/defaults.js

@@ -0,0 +1,91 @@
+import { resolveColorScale } from '../../utils/color';
+import { resolveOpacityScale } from '../../utils/opacity';
+import { ContinuousDomain } from '../../utils/ContinuousDomain';
+import { buildMarks, buildValueLabels } from './markers';
+/**
+ * HeatmapPlot's own "scales" output, over the band axes the shared phase laid
+ * out: the color domain over every cell's value (when `color` is set), and each
+ * row's own resolved color and opacity.
+ */
+function extendWithColorScales(state, ctx) {
+    const { scales, channels } = state;
+    const { range, cfg } = ctx;
+    const { color: colorAcc } = channels;
+    const rows = (state.processedData?.data ?? []);
+    const valueDomain = ContinuousDomain.build(scales.color?.domain, rows.map((d) => Number(colorAcc.accessor(d))), true) ?? [0, 1];
+    // 'rescale' reprojects the ramp onto the narrowed range; 'filter' (and no
+    // active range) keeps the original domain - only which cells are hidden
+    // changes (resolved in the "markers" phase).
+    const effectiveDomain = ContinuousDomain.ramp(valueDomain, range);
+    const colorScale = resolveColorScale({ ...scales.color, domain: effectiveDomain }, effectiveDomain, [cfg.continuous.min, cfg.continuous.max]);
+    const resolveColor = (row) => colorScale(Number(colorAcc.accessor(row)));
+    const opacityAcc = channels.opacity;
+    let opacityDomainOut;
+    const resolveOpacity = opacityAcc
+        ? (() => {
+            const rawVals = rows.map((d) => opacityAcc.accessor(d)).filter((v) => v != null);
+            const allNumeric = rawVals.every((v) => Number.isFinite(Number(v)));
+            const opacityDomain = allNumeric
+                ? rawVals.length
+                    ? [Math.min(...rawVals.map(Number)), Math.max(...rawVals.map(Number))]
+                    : [0, 1]
+                : [...new Set(rawVals.map(String))];
+            if (allNumeric && rawVals.length)
+                opacityDomainOut = opacityDomain;
+            const opacityScale = resolveOpacityScale(scales.opacity, opacityDomain, cfg.continuous.opacityRange);
+            return (row) => opacityScale(opacityAcc.accessor(row));
+        })()
+        : undefined;
+    return {
+        ...state,
+        scales: {
+            ...scales,
+            ...(colorAcc.source !== undefined ? { color: { ...scales.color, domain: valueDomain } } : {})
+        },
+        opacityDomain: opacityDomainOut,
+        resolveColor,
+        resolveOpacity
+    };
+}
+/**
+ * HeatmapPlot on the shared pipeline: both axes are categories. A heatmap's
+ * `color` is each cell's numeric value, which the "data" phase reads as a
+ * continuous channel rather than a grouping key: the rows stay one series, and
+ * author markers don't inherit it. Its own band/color scales and markers; a
+ * cell's tooltip names its coordinates and its value.
+ * Its plot defaults to: hover one cell.
+ */
+export function buildHeatmapDefaults() {
+    return {
+        data: { discreteAxes: 2 },
+        mapping: {
+            // A heatmap with no `color` still reads one per cell, as nothing.
+            extend: (state) => ({
+                ...state,
+                channels: {
+                    ...state.channels,
+                    color: state.channels.color ?? { accessor: () => undefined }
+                }
+            })
+        },
+        statistics: { inheritGrouping: false },
+        sharedScales: { fromScalesPhase: ['color'] },
+        scales: {
+            bandOrder: 'data',
+            defaults: () => ({ x: { labelAnchor: 'right' } }),
+            extend: extendWithColorScales
+        },
+        styles: { values: { show: true } },
+        markers: { marks: buildMarks, valueLabels: buildValueLabels },
+        hover: {
+            // A hovered cell reads as its formatted value.
+            label: (state) => {
+                const format = state.values?.format ?? ((v) => `${v}`);
+                const color = state.channels.color.accessor;
+                return ((row) => format(Number(color(row)), ''));
+            },
+            // A cell's color is its value, not a series'.
+            decorate: () => () => ({ series: undefined, color: undefined })
+        }
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { TextMarkerConfig } from '../../types/markers/common';
+import type { HeatmapPlotState, HeatmapPlotCtx } from '../../types/plots/heatmap/state';
+import type { ValueLabels } from '../../layout/styles/ValueLabels';
+import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+/**
+ * HeatmapPlot's `styles.values` as one `'text'` marker over the same cells
+ * the plot draws, each labelled with its own value and centred on it. Shown
+ * by default.
+ */
+export declare function buildValueLabels<TData extends Record<string, unknown>>(labels: ValueLabels, state: HeatmapPlotState<TData>, ctx: HeatmapPlotCtx): TextMarkerConfig[];
+/**
+ * HeatmapPlot's "markers" phase: one `'cell'` marker per resolved-style
+ * bucket - svelteplot's opacity/numeric scale machinery requires
+ * `fillOpacity`/`strokeWidth` to be constant per mark instance, unlike
+ * `fill`, which stays a per-row accessor.
+ */
+export declare function buildMarks<TData extends Record<string, unknown>>(state: HeatmapPlotState<TData>, ctx: HeatmapPlotCtx): AxisBasedMarkersConfig[];

package/dist/plots/heatmap/markers.js

@@ -0,0 +1,142 @@
+import { LegendState } from '../../layout/legend/LegendState.svelte';
+import { DisabledStyle } from '../../layout/legend/DisabledStyle';
+import { resolveAccessor } from '../utils/accessors';
+/** A processed channel as a per-row function. */
+function readChannel(channel) {
+    return resolveAccessor(channel);
+}
+const OPACITY_STEPS = 32;
+/**
+ * HeatmapPlot's `styles.values` as one `'text'` marker over the same cells
+ * the plot draws, each labelled with its own value and centred on it. Shown
+ * by default.
+ */
+export function buildValueLabels(labels, state, ctx) {
+    const { processedData } = state;
+    if (!processedData?.data.length)
+        return [];
+    const { font, format } = labels;
+    const getColor = state.channels.color.accessor;
+    return [
+        {
+            type: 'text',
+            data: processedData.data,
+            // Read like the cells read them, so the labels add no axis title the cells don't.
+            x: readChannel(processedData.channels.x),
+            y: readChannel(processedData.channels.y),
+            text: (d) => format(Number(getColor(d)), ''),
+            styles: {
+                ...font,
+                fill: font?.fill ?? ctx.cfg.continuous.labelColor,
+                fontSize: font?.fontSize ?? 12,
+                fontWeight: font?.fontWeight ?? 600,
+                dx: font?.dx ?? 0,
+                dy: font?.dy ?? 0,
+                textAnchor: labels.textAnchor ?? 'middle',
+                lineAnchor: font?.lineAnchor ?? 'middle'
+            }
+        }
+    ];
+}
+/**
+ * HeatmapPlot's "markers" phase: one `'cell'` marker per resolved-style
+ * bucket - svelteplot's opacity/numeric scale machinery requires
+ * `fillOpacity`/`strokeWidth` to be constant per mark instance, unlike
+ * `fill`, which stays a per-row accessor.
+ */
+export function buildMarks(state, ctx) {
+    const { segments, channels, resolveColor, resolveOpacity } = state;
+    const { range } = ctx;
+    const getColor = channels.color.accessor;
+    // The cells are the rows the "transforms" phase left, placed by its channels.
+    const processed = state.processedData;
+    const rows = processed.data;
+    const getX = readChannel(processed.channels.x);
+    const getY = readChannel(processed.channels.y);
+    /**
+     * A catch-all (no `areas`) always matches, so evaluating segments in plain
+     * array order and merging every match - as this used to do - makes a
+     * catch-all listed *after* an area-specific one (the documented, and only
+     * demonstrated, convention: baseline first, highlight second) overwrite it
+     * on every cell, since it's applied last unconditionally. Area-specific
+     * segments must always win over the catch-all regardless of list order -
+     * so the catch-all is applied once as the baseline, and only
+     * area-specific segments can override it on top, mirroring the same
+     * catch-all/area-specific priority every other plot kind's segments
+     * already follow (see `resolveSeriesSegments` in `utils/segments.ts`).
+     */
+    const segList = segments?.default ?? [];
+    const segStyleMap = (() => {
+        const map = new Map();
+        if (!segList.length)
+            return map;
+        const catchAll = segList.find((s) => !s.areas || s.areas.length === 0);
+        const areaSegs = segList.filter((s) => s.areas && s.areas.length > 0);
+        for (const d of rows) {
+            const cx = getX(d);
+            const cy = getY(d);
+            const key = `${String(cx)}::${String(cy)}`;
+            if (!map.has(key)) {
+                let styles = catchAll?.styles ? { ...catchAll.styles } : {};
+                for (const seg of areaSegs) {
+                    const matches = seg.areas.some((area) => {
+                        /* eslint-disable @typescript-eslint/no-explicit-any */
+                        const xOk = !area.x ||
+                            ((area.x.from === undefined || cx >= area.x.from) &&
+                                (area.x.to === undefined || cx <= area.x.to));
+                        const yOk = !area.y ||
+                            ((area.y.from === undefined || cy >= area.y.from) &&
+                                (area.y.to === undefined || cy <= area.y.to));
+                        /* eslint-enable @typescript-eslint/no-explicit-any */
+                        return xOk && yOk;
+                    });
+                    if (matches)
+                        styles = { ...styles, ...seg.styles };
+                }
+                map.set(key, styles);
+            }
+        }
+        return map;
+    })();
+    function rangeFilteredStyle(base, value) {
+        if (range == null || LegendState.inRange(value, range))
+            return base;
+        return { ...base, ...DisabledStyle.fill(range.disabledStyle) };
+    }
+    function getCellStyle(d) {
+        return rangeFilteredStyle(segStyleMap.get(`${String(getX(d))}::${String(getY(d))}`) ?? {}, Number(getColor(d)));
+    }
+    const styleGroups = (() => {
+        const groups = new Map();
+        for (const d of rows) {
+            const styles = getCellStyle(d);
+            const rawOpacity = resolveOpacity?.(d);
+            const opacity = rawOpacity != null ? Math.round(rawOpacity * OPACITY_STEPS) / OPACITY_STEPS : undefined;
+            const key = JSON.stringify({ styles, opacity });
+            let group = groups.get(key);
+            if (!group) {
+                group = { styles, opacity, data: [] };
+                groups.set(key, group);
+            }
+            group.data.push(d);
+        }
+        return [...groups.values()];
+    })();
+    const markers = styleGroups.map((group) => ({
+        type: 'cell',
+        data: group.data,
+        x: getX,
+        y: getY,
+        fill: (d) => group.styles.fill ?? resolveColor(d),
+        styles: {
+            fillOpacity: group.styles.fillOpacity ?? group.opacity ?? 1,
+            stroke: group.styles.stroke,
+            strokeWidth: group.styles.strokeWidth ?? 0,
+            strokeOpacity: group.styles.strokeOpacity,
+            strokeDasharray: group.styles.strokeDasharray,
+            borderRadius: group.styles.borderRadius
+        },
+        inset: 0.5
+    }));
+    return markers;
+}

package/dist/plots/histogram/Plot.svelte

@@ -0,0 +1,45 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import Plot from '../../layout/plot/Plot.svelte';
+	import { buildHistogramDefaults } from './defaults';
+	import type {
+		HistogramPlotProps,
+		HistogramPlotCoreProps
+	} from '../../types/plots/histogram/props';
+
+	/**
+	 * A histogram: each series binned on `x` - or on `y` alone, for horizontal bars - one bar per bin. 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
+	}: HistogramPlotProps<TData> = $props();
+</script>
+
+<Plot
+	core={core as HistogramPlotCoreProps<TData>}
+	defaults={buildHistogramDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>

package/dist/plots/histogram/Plot.svelte.d.ts

@@ -0,0 +1,26 @@
+import Plot from '../../layout/plot/Plot.svelte';
+import type { HistogramPlotProps } from '../../types/plots/histogram/props';
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: HistogramPlotProps<TData>;
+    exports: {};
+    bindings: "margins";
+    slots: {};
+    events: {};
+};
+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(): "margins";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData extends Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <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 Plot: $$IsomorphicComponent;
+type Plot<TData extends Record<string, unknown>> = InstanceType<typeof Plot<TData>>;
+export default Plot;

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

@@ -0,0 +1,9 @@
+import type { AxisPlotDefaults } from '../../types/phases';
+import type { HistogramPlotState, HistogramPlotCtx } from '../../types/plots/histogram/state';
+/**
+ * HistogramPlot on the shared pipeline: series read one position channel -
+ * `x`, or `y` for a horizontal histogram - binned by the plot's transforms
+ * merged over the default bin of that axis, bars from a zero baseline, and its
+ * own markers. Its plot defaults to: hover along the binned axis.
+ */
+export declare function buildHistogramDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<HistogramPlotState<TData>, HistogramPlotCtx>;

package/dist/plots/histogram/defaults.js

@@ -0,0 +1,87 @@
+import { buildMarks, buildValueLabels } from './markers';
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
+import { resolveAccessor } from '../utils/accessors';
+import { PlotAxes } from '../../phases/data/PlotAxes';
+/** One processed channel's value on a row - `undefined` for a channel the transforms didn't set. */
+function readChannel(channel) {
+    return channel === undefined
+        ? () => undefined
+        : resolveAccessor(channel);
+}
+/**
+ * The plot's own bins of its axis merged over the default one - counts per
+ * bin, with the configured inset on each side of every bar - the author's
+ * props winning, and every other transform kept after it in order. A
+ * histogram bins once, so several entries fold into one.
+ */
+function mergeBin(own, cfg, horizontal) {
+    const { inset } = cfg.histogram;
+    const base = horizontal
+        ? { type: 'binY', x: 'count', insetTop: inset, insetBottom: inset }
+        : { type: 'binX', y: 'count', insetLeft: inset, insetRight: inset };
+    const bins = own.filter((t) => t.type === base.type);
+    const others = own.filter((t) => t.type !== base.type);
+    const bin = bins.reduce((merged, t) => ({ ...merged, ...t }), base);
+    return [bin, ...others];
+}
+/**
+ * HistogramPlot on the shared pipeline: series read one position channel -
+ * `x`, or `y` for a horizontal histogram - binned by the plot's transforms
+ * merged over the default bin of that axis, bars from a zero baseline, and its
+ * own markers. Its plot defaults to: hover along the binned axis.
+ */
+export function buildHistogramDefaults() {
+    return {
+        data: { segments: { color: (style) => style?.fill, connect: false } },
+        transforms: {
+            transforms: (state, ctx) => mergeBin(state.transforms ?? [], ctx.cfg, state.axes?.isHorizontal ?? false)
+        },
+        scales: { zero: ['value'] },
+        styles: {
+            values: {
+                // An `'outside'` label sits past its bin's end, which the longest bin takes to the edge.
+                reach: (labels, state) => {
+                    if (labels.anchor !== 'outside')
+                        return [];
+                    return state.axes?.isHorizontal
+                        ? [
+                            labels.edgeBox('0', { x: 'after', y: 'middle' }, { x: labels.offset('x') }, [
+                                'right'
+                            ])
+                        ]
+                        : [
+                            labels.edgeBox('0', { x: 'middle', y: 'before' }, { y: -labels.offset('y') }, [
+                                'top'
+                            ])
+                        ];
+                }
+            }
+        },
+        markers: { marks: buildMarks, valueLabels: buildValueLabels },
+        hover: {
+            // A hovered bin is labelled with its count, and reads as its row plus its count,
+            // the edges it spans and its series.
+            label: (state) => {
+                const count = readChannel(state.processedData.channels[PlotAxes.valueOf(state)]);
+                return ((row) => String(Number(count(row))));
+            },
+            row: (state) => {
+                const { channels } = state.processedData;
+                const value = PlotAxes.valueOf(state);
+                const binned = PlotAxes.other(value);
+                const [count, from, to] = [
+                    channels[value],
+                    channels[`${binned}1`],
+                    channels[`${binned}2`]
+                ].map(readChannel);
+                return ((row) => ({
+                    ...row,
+                    count: Number(count(row)),
+                    from: Number(from(row)),
+                    to: Number(to(row)),
+                    group: row[SERIES_KEY]
+                }));
+            }
+        }
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { HistogramPlotState, HistogramPlotCtx } from '../../types/plots/histogram/state';
+import type { AxisBasedMarkersConfig, TextMarkerConfig } from '../../types/markers/common';
+import type { ValueLabels } from '../../layout/styles/ValueLabels';
+/**
+ * HistogramPlot's `styles.values` as one `'text'` marker over its non-empty
+ * bins (a `filter` on the count), each labelled with its count by `format`.
+ * `anchor` places each label along its bar: past its top (`'outside'`), just
+ * inside it (`'start'`), at its base (`'end'`), or centred (`'middle'`) -
+ * upward, or rightward on a horizontal histogram.
+ */
+export declare function buildValueLabels<TData extends Record<string, unknown>>(labels: ValueLabels, state: HistogramPlotState<TData>, ctx: HistogramPlotCtx): TextMarkerConfig[];
+/**
+ * HistogramPlot's "markers" phase: one `rect` per visual segment of each
+ * series, drawing that segment's bins, dimmed with its series. The markers
+ * the "statistics" phase already put in `state.markers` come after, and its
+ * value labels last.
+ */
+export declare function buildMarks<TData extends Record<string, unknown>>(state: HistogramPlotState<TData>, ctx: HistogramPlotCtx): AxisBasedMarkersConfig[];

package/dist/plots/histogram/markers.js

@@ -0,0 +1,89 @@
+import { ProcessedPositions } from '../../phases/transforms/ProcessedPositions';
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
+import { Transforms } from '../../phases/transforms/Transforms';
+import { resolveAccessor } from '../utils/accessors';
+import { PlotAxes } from '../../phases/data/PlotAxes';
+/**
+ * HistogramPlot's `styles.values` as one `'text'` marker over its non-empty
+ * bins (a `filter` on the count), each labelled with its count by `format`.
+ * `anchor` places each label along its bar: past its top (`'outside'`), just
+ * inside it (`'start'`), at its base (`'end'`), or centred (`'middle'`) -
+ * upward, or rightward on a horizontal histogram.
+ */
+export function buildValueLabels(labels, state, ctx) {
+    const { processedData: processed } = state;
+    if (!processed?.data.length)
+        return [];
+    const { font, anchor, format } = labels;
+    const nameOf = (d) => String(d[SERIES_KEY]);
+    const value = PlotAxes.valueOf(state);
+    const binned = PlotAxes.other(value);
+    const horizontal = value === 'x';
+    const position = ProcessedPositions.of(processed, value);
+    const read = (channel) => channel === undefined
+        ? undefined
+        : resolveAccessor(channel);
+    const topOf = (d) => Number(position[value](d));
+    const bottomOf = read(processed.channels[`${value}1`]) ?? (() => 0);
+    const countRead = read(processed.channels[value]);
+    const countOf = (d) => countRead ? Number(countRead(d)) : topOf(d) - Number(bottomOf(d));
+    const along = anchor === 'end'
+        ? bottomOf
+        : anchor === 'middle'
+            ? (d) => (topOf(d) + Number(bottomOf(d))) / 2
+            : topOf;
+    // Outward from the bar's top: past it, just inside it, or out from its base.
+    const outward = anchor === 'outside' ? 6 : anchor === 'start' ? -4 : anchor === 'end' ? 4 : 0;
+    const outwardAnchor = anchor === 'start' ? 'end' : anchor === 'middle' ? 'middle' : 'start';
+    const marker = Transforms.resolve({
+        type: 'text',
+        data: processed.data,
+        [binned]: position[binned],
+        [value]: along,
+        transforms: [{ type: 'filter', filter: (d) => countOf(d) > 0 }],
+        text: (d) => format(countOf(d), nameOf(d)),
+        styles: {
+            ...font,
+            fill: font?.fill ?? ctx.cfg.axis.color,
+            fontSize: font?.fontSize ?? 12,
+            dx: font?.dx ?? (horizontal ? outward : 0),
+            dy: font?.dy ?? (horizontal ? 0 : -outward),
+            textAnchor: labels.textAnchor ?? (horizontal ? outwardAnchor : 'middle'),
+            lineAnchor: font?.lineAnchor ??
+                (horizontal
+                    ? 'middle'
+                    : anchor === 'start'
+                        ? 'top'
+                        : anchor === 'middle'
+                            ? 'middle'
+                            : 'bottom')
+        }
+    }, processed.data);
+    return marker.data?.length ? [marker] : [];
+}
+/**
+ * HistogramPlot's "markers" phase: one `rect` per visual segment of each
+ * series, drawing that segment's bins, dimmed with its series. The markers
+ * the "statistics" phase already put in `state.markers` come after, and its
+ * value labels last.
+ */
+export function buildMarks(state, ctx) {
+    const { channels, options, transforms } = state.processedData;
+    const fillOpacity = ctx.cfg.histogram.fillOpacity;
+    const rects = (state.processedGroups ?? []).flatMap((group) => {
+        const disabled = ctx.interaction?.fillFor(group.series.name);
+        return group.visualSegments.map((seg) => Transforms.finish({
+            type: 'rect',
+            series: group.series.name,
+            data: seg.data,
+            ...channels,
+            ...options,
+            styles: {
+                fillOpacity: disabled?.fillOpacity ?? seg.styles.fillOpacity ?? fillOpacity,
+                ...(seg.styles.fill !== undefined ? { fill: seg.styles.fill } : {}),
+                ...(disabled?.fill !== undefined ? { fill: disabled.fill } : {})
+            }
+        }, transforms));
+    });
+    return rects;
+}