@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/plots/pyramid/Plot.svelte

@@ -1,369 +1,41 @@
 <script lang="ts" generics="TData extends Record<string, unknown>">
-	import { resolveAccessor } from '../utils/accessors';
-	import { getConfiguration } from '../../configuration/config.svelte';
-	import { paletteColor } from '../../utils/color';
-	import { buildSeries } from '../../utils/grouping';
-	import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
-	import {
-		disabledFillOverride,
-		resolveEffectiveDisabledStyle
-	} from '../utils/legendDisabled';
-	import { buildPyramidBarMarkers } from './buildPyramidBarMarkers';
-	import {
-		createLabelMarginTracker,
-		halfDimensionOverflowCap
-	} from '../utils/labelOverflow.svelte';
-	import { estimateValueLabelMargin } from '../utils/valueLabelMargin';
-	import {
-		buildGroupedSeries,
-		validateSegments,
-		buildScopedMarkerGroups
-	} from '../utils/segments';
-	import { isGapValue, resolveGapsForSeries, resolveDiscreteGapFills } from '../utils/gaps';
-	import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
-	import ValueLabels from './ValueLabels.svelte';
-	import {
-		hasHoverMarker,
-		resolveHoverStrategy,
-		resolveHoverSync
-	} from '../../layout/tooltip/utils';
-	import type { BasePlotProps } from '../../types/plots/props';
-	import type { AxisValue, AxisBasedScalesConfig } from '../../types/layout/scales';
-	import type { Series, SeriesProps, DataProps } from '../../types/plots/data/common';
-	import type { GapsAwarePlotStylesConfig } from '../../types/layout/styles';
-	import type { ValueAnchor } from '../../types/plots/constants';
-	import type { BarSegmentStyle } from '../../types/plots/segments/common';
-	import type { AxisBasedMarkersConfig } from '../../types/markers/common';
-	import type { LegendDisabledStyle } from '../../types/layout/legend';
-	import type { MarginOverflow } from '../utils/labelOverflow.svelte';
+	import Plot from '../../layout/plot/Plot.svelte';
+	import { buildPyramidDefaults } from './defaults';
+	import type { PyramidPlotProps, PyramidPlotCoreProps } from '../../types/plots/pyramid/props';
 
 	/**
-	 * A population-pyramid-style diverging bar chart: each series is mirrored
-	 * left or right of a shared zero baseline along a categorical band axis.
-	 * Mirrors the bar/line plot contract — series in, marks out — so the
-	 * chart-level container/timeline/facet/legend wrap it unchanged. Like
-	 * `LinePlot`/`BarPlot`, accepts either pre-built `series` or flat `data` +
-	 * `x`/`y`/`z` accessors.
-	 *
-	 * Side assignment is automatic: series names are sorted alphabetically and
-	 * the first goes left, the second right. Pass `scales.z.reverse: true` to
-	 * flip the order.
+	 * A population-pyramid-style diverging bar plot: horizontal when its categories run along `y`, vertical when they run along `x`. 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.
 	 */
-
-	type PyramidSide = 'left' | 'right';
-	type InternalSeries = Series<TData> & { side: PyramidSide };
-
-	type Props = BasePlotProps<
-		SeriesProps<TData> | DataProps<TData>,
-		TData,
-		GapsAwarePlotStylesConfig<BarSegmentStyle>,
-		BarSegmentStyle,
-		AxisBasedMarkersConfig,
-		AxisBasedScalesConfig<TData>
-	>;
-
 	let {
-		width,
-		height,
-		series,
-		data,
-		x: magnitude,
-		y: category,
-		z: sides,
-		styles = {},
-		scales = {},
-		margins,
-		segments = {},
-		markers = [],
-		tooltip = undefined
-	}: Props = $props();
-
-	$effect(() => {
-		validateSegments(segments);
-	});
-
-	const cfg = $derived(getConfiguration());
-	const legendInteraction = $derived(getLegendInteraction());
-	const hoverIsolate = $derived(styles.values?.hoverIsolate ?? false);
-
-	// A value label hovered while `styles.values.hoverIsolate` is on dims
-	// every other series exactly like a legend toggle would — local to this
-	// one `<Plot>` instance (not the shared HoverStore) so the gesture can't
-	// leak into unrelated tooltip/crosshair behavior.
-	let hoverIsolatedSeries = $state<string | null>(null);
-
-	function effectiveDisabledFor(name: string): LegendDisabledStyle | undefined {
-		return resolveEffectiveDisabledStyle(
-			name,
-			legendInteraction,
-			cfg.legend.disabledOpacity,
-			hoverIsolate,
-			hoverIsolatedSeries
-		);
-	}
-
-	const leftColor = $derived(styles.colors?.left ?? paletteColor(0, cfg.palette));
-	const rightColor = $derived(styles.colors?.right ?? paletteColor(1, cfg.palette));
-	const showVals = $derived(styles.values?.show ?? false);
-	const formatValue = $derived(styles.values?.format ?? ((v: number) => `${v}`));
-	const valAnchor = $derived<ValueAnchor>(styles.values?.anchor ?? 'outside');
-
-	// Sort series names alphabetically; even index → left, odd → right.
-	// scales.z.reverse flips the assignment so the second name goes left.
-	const zReversed = $derived(scales.z?.reverse ?? false);
-	const resolvedSeries = $derived.by((): InternalSeries[] => {
-		const base: Series<TData>[] = series ?? buildSeries(data!, category!, magnitude!, sides);
-		const sortedNames = [...base.map((s) => s.name)].sort((a, b) => a.localeCompare(b));
-		return base.map((s) => {
-			const idx = sortedNames.indexOf(s.name);
-			const side: PyramidSide = (idx % 2 === 0) !== zReversed ? 'left' : 'right';
-			return { ...s, side };
-		});
-	});
-
-	const groupedSeries = $derived(
-		// connect: false — bars are discrete; there's no visual gap between
-		// adjacent categories to bridge (see buildGroupedSeries's own doc).
-		buildGroupedSeries<InternalSeries, BarSegmentStyle>(resolvedSeries, segments, false)
-	);
-
-	function signedValue(s: InternalSeries, d: TData): number {
-		const v = Math.abs(Number(resolveAccessor(s.y)(d)));
-		return s.side === 'left' ? -v : v;
-	}
-
-	// Signs an already-resolved magnitude (e.g. a gap-fill's interpolated
-	// value, which has no row of its own to read via `signedValue`).
-	function signFor(s: InternalSeries, magnitude: number): number {
-		return s.side === 'left' ? -magnitude : magnitude;
-	}
-
-	// Fills leading/internal/trailing missing-data holes with an
-	// interpolated, distinctly-styled bar, resolved per series like
-	// `segments` — see `GapsAwarePlotStylesConfig` (`types/layout/styles.ts`).
-	const gaps = $derived(styles.gaps ?? {});
-	const gapFillMaps = $derived(
-		new Map(
-			resolvedSeries.map((s) => [
-				s.name,
-				resolveDiscreteGapFills(s, resolveGapsForSeries(gaps, s.name))
-			])
-		)
-	);
-
-	// svelteplot's `Pointer` rebuilds its quadtree from shallow-cloned rows
-	// (`{ ...d }`), never the original references, so a row's owning series
-	// can't be recovered by identity once hover is active. Pre-compute
-	// everything `getX`/`getY`/`labelFor` need as plain enumerable properties —
-	// they survive the clone automatically.
-	type TaggedRow = TData & {
-		__side: string;
-		__x: number;
-		__y: AxisValue;
-		__label: string;
-		__series: string;
-	};
-
-	const flat = $derived.by((): TaggedRow[] =>
-		resolvedSeries.flatMap((s) => {
-			const getCategory = resolveAccessor(s.x);
-			const getMagnitude = resolveAccessor(s.y);
-			return s.data
-				.filter((d) => !isGapValue(getMagnitude(d)))
-				.map((d) => {
-					const v = Math.abs(Number(getMagnitude(d)));
-					return {
-						...d,
-						__side: s.side,
-						__x: s.side === 'left' ? -v : v,
-						__y: getCategory(d) as AxisValue,
-						__label: formatValue(v, s.name),
-						__series: s.name
-					} as TaggedRow;
-				});
-		})
-	);
-
-	const getX = (d: TaggedRow) => d.__x;
-	const getY = (d: TaggedRow) => d.__y;
-	const labelFor = (d: TaggedRow) => d.__label;
-
-	// A legend-disabled series is dimmed on the bar itself, but never surfaces
-	// in hover/tooltip — its points are simply absent from the candidate list.
-	const hoverPoints = $derived(
-		flat
-			.filter((d) => !legendInteraction?.disabledSeries.has(d.__series))
-			.map((d) => ({
-				x: d.__x,
-				y: d.__y,
-				row: d,
-				label: d.__label,
-				series: d.__series,
-				color: d.__side === 'left' ? leftColor : rightColor
-			}))
-	);
-
-	const yDomain = $derived([
-		...new Set(
-			resolvedSeries.flatMap((s) => {
-				const getCategory = resolveAccessor(s.x);
-				return s.data.map((d) => getCategory(d) as AxisValue);
-			})
-		)
-	]);
-
-	const maxMagnitude = $derived.by(() => {
-		const vals = resolvedSeries.flatMap((s) => {
-			const getMagnitude = resolveAccessor(s.y);
-			const fillMap = gapFillMaps.get(s.name);
-			return s.data.flatMap((d) => {
-				const raw = getMagnitude(d);
-				if (!isGapValue(raw)) return [Math.abs(Number(raw))];
-				const fill = fillMap?.get(d);
-				return fill ? [Math.abs(fill.value)] : [];
-			});
-		});
-		return vals.length ? Math.max(...vals) : 1;
-	});
-
-	// The single, fully-resolved scales object BasePlotLayout reads for
-	// everything (ticks, grid, sort, and the real svelteplot scale) — avoids
-	// keeping a second, separately-defaulted copy of `scales.x`/`scales.y`
-	// (our own diverging-domain + band-scale defaults) out of sync with the
-	// one actually forwarded.
-	const resolvedScales = $derived<AxisBasedScalesConfig<TData>>({
-		...scales,
-		x: {
-			domain: [-maxMagnitude, maxMagnitude],
-			tickFormat: (v: unknown) => formatValue(Math.abs(Number(v)), ''),
-			...(scales.x ?? {})
-		},
-		y: { type: 'band', padding: 0.2, domain: yDomain, ...(scales.y ?? {}) }
-	});
-
-	const hover = $derived({
-		active: tooltip != null || hasHoverMarker(markers),
-		points: hoverPoints,
-		label: labelFor,
-		strategy: resolveHoverStrategy(tooltip?.strategy, markers, 'y'),
-		sync: resolveHoverSync(tooltip?.sync, markers),
-		tooltip
-	});
-
-	const pyramidMarkers = $derived(
-		buildPyramidBarMarkers({
-			groupedSeries,
-			valueFor: signedValue,
-			signFor,
-			colorFor: (s) => (s.side === 'left' ? leftColor : rightColor),
-			disabledFillFor: (name) => disabledFillOverride(effectiveDisabledFor(name)),
-			gapFillMaps
-		})
-	);
-
-	const scopedGroups = $derived(
-		buildScopedMarkerGroups<TData, InternalSeries, BarSegmentStyle>({
-			groupedSeries,
-			segments,
-			colorFor: (series) => (series.side === 'left' ? leftColor : rightColor),
-			segmentColorFor: (style, defaultColor) => style?.fill ?? defaultColor
-		})
-	);
-
-	// Estimated overflow for an `'outside'`- or `'start'`-anchored value label
-	// (both anchor at the row's own full magnitude, pushed further outward —
-	// see `ValueLabels.svelte`'s `xFn`) at the most extreme value on each
-	// side of the whole dataset, not just the current frame, so it stays
-	// stable across a timeline scrubber instead of resetting to zero and
-	// regrowing on every tick. `'middle'`/`'end'` anchor inside the bar,
-	// toward its own zero baseline, so they carry no such risk.
-	const valueLabelFloor = $derived.by((): MarginOverflow | undefined => {
-		if (!showVals || valAnchor === 'middle' || valAnchor === 'end') return undefined;
-		const font = styles.values?.fontStyle;
-		const fontSize = typeof font?.fontSize === 'number' ? font.fontSize : 12;
-		const canvasFont = `${fontSize}px ${cfg.font === 'inherit' ? 'sans-serif' : cfg.font}`;
-		const offset = Math.abs(typeof font?.dx === 'number' ? font.dx : 6);
-
-		const leftTexts: string[] = [];
-		const rightTexts: string[] = [];
-		for (const s of resolvedSeries) {
-			const sy = resolveAccessor(s.y);
-			let extreme = 0;
-			let extremeRow: TData | undefined;
-			for (const d of s.data) {
-				const v = Math.abs(Number(sy(d)));
-				if (Number.isNaN(v)) continue;
-				if (extremeRow === undefined || v > extreme) {
-					extreme = v;
-					extremeRow = d;
-				}
-			}
-			if (extremeRow === undefined) continue;
-			const text = formatValue(extreme, s.name);
-			if (s.side === 'left') leftTexts.push(text);
-			else rightTexts.push(text);
-		}
-		const left = estimateValueLabelMargin(leftTexts, { canvasFont, reach: offset });
-		const right = estimateValueLabelMargin(rightTexts, { canvasFont, reach: offset });
-		return { left, right, top: 0, bottom: 0 };
-	});
-
-	// See `halfDimensionOverflowCap`'s own doc comment.
-	const maxLabelOverflow = $derived(halfDimensionOverflowCap(width, height));
-
-	// A pyramid bar's value label can grow past the plot's own content box —
-	// `valueLabelFloor` covers the common case up front; each label's own
-	// rendered overflow still feeds `labelMargin.report` for whatever that
-	// estimate doesn't cover. See `labelOverflow.svelte.ts`.
-	const labelMargin = createLabelMarginTracker(
-		() => margins,
-		() => resolvedSeries,
-		() => valueLabelFloor ?? { left: 0, right: 0, top: 0, bottom: 0 },
-		() => maxLabelOverflow
-	);
+		title,
+		subtitle,
+		caption,
+		header,
+		footer,
+		legend,
+		order,
+		timeline,
+		facet,
+		tooltip,
+		margins = $bindable(),
+		...core
+	}: PyramidPlotProps<TData> = $props();
 </script>
 
-<BasePlotLayout
-	{width}
-	{height}
-	{styles}
-	data={flat}
-	{getX}
-	{getY}
-	{hover}
-	scales={resolvedScales}
-	{...labelMargin.plotProps}
-	xTickRotate={resolvedScales?.x?.tickRotate}
-	markers={[...pyramidMarkers, ...markers]}
-	seriesData={resolvedSeries}
-	{scopedGroups}
->
-	{#snippet children({ numericMargins })}
-		{#if showVals}
-			{#each groupedSeries as group (group.series.name)}
-				<ValueLabels
-					{group}
-					{valAnchor}
-					{formatValue}
-					values={styles.values}
-					axisColor={cfg.axis.color}
-					disabled={effectiveDisabledFor(group.series.name)}
-					{width}
-					{height}
-					{numericMargins}
-					onHoverSeries={hoverIsolate
-						? () => {
-								hoverIsolatedSeries = group.series.name;
-							}
-						: undefined}
-					onHoverEnd={hoverIsolate
-						? () => {
-								hoverIsolatedSeries = null;
-							}
-						: undefined}
-					onOverflow={labelMargin.report}
-				/>
-			{/each}
-		{/if}
-	{/snippet}
-</BasePlotLayout>
+<Plot
+	core={core as PyramidPlotCoreProps<TData>}
+	defaults={buildPyramidDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>

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

@@ -1,12 +1,9 @@
-import type { BasePlotProps } from '../../types/plots/props';
-import type { AxisBasedScalesConfig } from '../../types/layout/scales';
-import type { SeriesProps, DataProps } from '../../types/plots/data/common';
-import type { GapsAwarePlotStylesConfig } from '../../types/layout/styles';
-import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+import Plot from '../../layout/plot/Plot.svelte';
+import type { PyramidPlotProps } from '../../types/plots/pyramid/props';
 declare function $$render<TData extends Record<string, unknown>>(): {
-    props: BasePlotProps<SeriesProps<TData> | DataProps<TData>, TData, GapsAwarePlotStylesConfig<import("../..").AreaStyle>, import("../..").AreaStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
+    props: PyramidPlotProps<TData>;
     exports: {};
-    bindings: "";
+    bindings: "margins";
     slots: {};
     events: {};
 };
@@ -14,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 {

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

@@ -0,0 +1,13 @@
+import type { AxisPlotDefaults } from '../../types/phases';
+import type { PyramidPlotState, PyramidPlotCtx } from '../../types/plots/pyramid/state';
+/**
+ * PyramidPlot on the shared pipeline. Its `x`/`y` are the visual axes: the one
+ * holding categories (read off the values by the "data" phase) runs the bars,
+ * so categories on `y` make the classic horizontal pyramid and categories on
+ * `x` a vertical one. Series take sides by the alphabetical order of their
+ * names (first left, or bottom), flipped by `scales.grouping.reverse`, and
+ * colors follow that same order. A bar's tooltip reads its side, then its
+ * category and magnitude.
+ * Its plot defaults to: hover along the category axis; the tween is of the magnitude, keyed by category and side.
+ */
+export declare function buildPyramidDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<PyramidPlotState<TData>, PyramidPlotCtx>;

package/dist/plots/pyramid/defaults.js

@@ -0,0 +1,86 @@
+import { PlotAxes } from '../../phases/data/PlotAxes';
+import { buildMarks, buildValueLabels } from './markers';
+import { ValueLabels } from '../../layout/styles/ValueLabels';
+import { seriesIdOf } from '../../utils/grouping';
+import { isGapValue } from '../utils/gaps';
+import { SERIES_ID_KEY, TransformsPhase } from '../../phases/transforms/TransformsPhase';
+const byName = (a, b) => a.name.localeCompare(b.name);
+/**
+ * PyramidPlot on the shared pipeline. Its `x`/`y` are the visual axes: the one
+ * holding categories (read off the values by the "data" phase) runs the bars,
+ * so categories on `y` make the classic horizontal pyramid and categories on
+ * `x` a vertical one. Series take sides by the alphabetical order of their
+ * names (first left, or bottom), flipped by `scales.grouping.reverse`, and
+ * colors follow that same order. A bar's tooltip reads its side, then its
+ * category and magnitude.
+ * Its plot defaults to: hover along the category axis; the tween is of the magnitude, keyed by category and side.
+ */
+export function buildPyramidDefaults() {
+    return {
+        data: {
+            discreteAxes: 1,
+            segments: { color: (style) => style?.fill, connect: false },
+            orderSeries: (series, state) => {
+                const sorted = [...series].sort(byName).map((s) => s.name);
+                const reversed = state.scales.grouping?.reverse ?? false;
+                return series.map((s) => {
+                    const side = (sorted.indexOf(s.name) % 2 === 0) !== reversed ? 'left' : 'right';
+                    return { ...s, side };
+                });
+            },
+            colorOrder: (series) => [...series].sort(byName)
+        },
+        scales: {
+            // Both sides read as magnitudes, on an axis as long below zero as above it.
+            symmetric: ['value'],
+            bandOrder: 'data',
+            defaults: () => ({
+                category: { padding: 0.2 },
+                value: { tickFormat: (v) => String(Math.abs(Number(v))) }
+            })
+        },
+        styles: {
+            values: {
+                // A label past its bar's end reaches out on its own side, the longest bar's to the edge.
+                reach: (labels, state) => {
+                    if (labels.anchor === 'middle' || labels.anchor === 'end')
+                        return [];
+                    const axis = PlotAxes.valueOf(state);
+                    const isHorizontal = state.axes?.isHorizontal ?? true;
+                    const offset = labels.offset(axis);
+                    return labels.extremes(state.resolvedSeries ?? [], axis).map(({ series, value }) => {
+                        const left = series.side === 'left';
+                        const text = labels.format(Math.abs(value), series.name);
+                        return isHorizontal
+                            ? labels.edgeBox(text, { x: left ? 'before' : 'after', y: 'middle' }, { x: left ? -offset : offset }, [left ? 'left' : 'right'])
+                            : labels.edgeBox(text, { x: 'middle', y: left ? 'after' : 'before' }, { y: left ? offset : -offset }, [left ? 'bottom' : 'top']);
+                    });
+                }
+            }
+        },
+        markers: { marks: buildMarks, valueLabels: buildValueLabels },
+        hover: {
+            // A bar sits at its signed magnitude - below or left of the baseline on the first
+            // side - and its category, and reads as its magnitude.
+            position: (state) => {
+                const value = PlotAxes.valueOf(state);
+                const place = TransformsPhase.processedPosition(state.processedData, value);
+                const valueOf = ValueLabels.valueOf(state);
+                const sideOf = new Map((state.resolvedSeries ?? []).map((s) => [seriesIdOf(s), s.side]));
+                const signed = (row) => {
+                    const raw = valueOf(row);
+                    if (isGapValue(raw))
+                        return raw;
+                    const magnitude = Math.abs(Number(raw));
+                    return sideOf.get(String(row[SERIES_ID_KEY])) === 'left' ? -magnitude : magnitude;
+                };
+                return value === 'x' ? { x: signed, y: place.y } : { x: place.x, y: signed };
+            },
+            label: (state) => {
+                const valueOf = ValueLabels.valueOf(state);
+                return (row) => String(Math.abs(Number(valueOf(row))));
+            }
+        },
+        timeline: { interpolation: { value: 'value', key: ['category', 'grouping'] } }
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { TextMarkerConfig } from '../../types/markers/common';
+import type { PyramidPlotState, PyramidPlotCtx } from '../../types/plots/pyramid/state';
+import type { ValueLabels } from '../../layout/styles/ValueLabels';
+import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+/**
+ * PyramidPlot's `styles.values` as one `'text'` marker per series, over the
+ * same processed rows its bars draw (gap rows never get a label), mirrored to
+ * its own side of the shared zero baseline. `anchor` places each label along
+ * its bar: past its end (`'outside'`/`'start'`), at the baseline (`'end'`),
+ * or centred (`'middle'`). On a vertical pyramid the sides run down and up.
+ */
+export declare function buildValueLabels<TData extends Record<string, unknown>>(labels: ValueLabels, state: PyramidPlotState<TData>, ctx: PyramidPlotCtx): TextMarkerConfig[];
+/**
+ * PyramidPlot's "markers" phase: one `role: 'segment'` bar per visual
+ * segment, along the category axis the "data" phase read (horizontal bars for
+ * categories on y, signed magnitude on x; vertical ones the other way) and with
+ * no insets - prepended onto whatever the "statistics" phase already put in
+ * `state.markers`. Emits no `role: 'hitArea'` markers - PyramidPlot's hover
+ * matches nearest points rather than hit-testing category bands.
+ */
+export declare function buildMarks<TData extends Record<string, unknown>>(state: PyramidPlotState<TData>, ctx: PyramidPlotCtx): AxisBasedMarkersConfig[];