@fundar/data-chart-telling 1.1.0 → 1.2.0

package/dist/plots/ranking/cleveland/defaults.js

@@ -0,0 +1,66 @@
+import { ClevelandMarkers } from './ClevelandMarkers';
+import { ClevelandRanges } from './ClevelandRanges';
+import { NiceTicks } from '../../../layout/scales/NiceTicks';
+import { PlotAxes } from '../../../phases/data/PlotAxes';
+/**
+ * The domain a plot of intervals fits to them on its value axis, niced to as many
+ * ticks as fit the plot. Left out when the author pins the axis, or there is
+ * nothing to fit.
+ */
+function fitInterval(state, fromBaseline) {
+    const axis = PlotAxes.valueOf(state);
+    const scale = state.scales[axis];
+    if (scale?.domain != null || scale?.ticks != null || typeof scale?.nice === 'boolean')
+        return {};
+    const { entries } = ClevelandRanges.of(state, fromBaseline, {}, true);
+    if (entries.length === 0)
+        return {};
+    const lo = Math.min(...entries.map((entry) => entry.from));
+    const hi = Math.max(...entries.map((entry) => entry.to));
+    if (!(hi > lo))
+        return {};
+    return {
+        [axis]: { domain: NiceTicks.fit(state, axis, lo, hi, NiceTicks.toleranceOf(scale?.nice)) }
+    };
+}
+/**
+ * ClevelandPlot on the shared pipeline, and the base of its wrappers: per
+ * category along one category axis - `x`, or `y` for sideways rows, as the
+ * "data" phase reads it off the values - one dot for each series that has a
+ * value there, joined by a connector from the lowest to the highest. The
+ * `options` set one plot of the family apart: its name, its configuration
+ * block, whether the baseline is an end of the range (a lollipop's stem), and
+ * what it checks about the series before drawing. Its plot defaults to hover
+ * along the category axis.
+ */
+export function buildClevelandDefaults(options = { name: 'ClevelandPlot', config: 'cleveland' }) {
+    const markers = new ClevelandMarkers(options);
+    return {
+        data: {
+            discreteAxes: 1,
+            segments: {
+                color: (style) => style?.dots?.dotFill ?? style?.stroke?.stroke,
+                connect: false
+            }
+        },
+        scales: {
+            // A stem rises from the baseline, which the value axis then reaches.
+            zero: options.fromBaseline ? ['value'] : [],
+            bandOrder: 'data',
+            // An interval's ends are values the axis must reach, and the dots alone do not say where they are.
+            fit: options.interval
+                ? (state) => fitInterval(state, options.fromBaseline ?? false)
+                : undefined,
+            defaults: (_state, ctx) => ({
+                category: {
+                    paddingInner: ctx.cfg[options.config].paddingInner,
+                    paddingOuter: ctx.cfg[options.config].paddingOuter
+                }
+            })
+        },
+        // A dot is labelled by what its category's dots say: the first, the highest... of each.
+        transforms: { labels: { group: 'category', skip: ClevelandRanges.skipGaps } },
+        styles: { values: { reach: markers.reach } },
+        markers: { marks: markers.marks, valueLabels: markers.valueLabels }
+    };
+}

package/dist/plots/ranking/dumbbell/Plot.svelte

@@ -0,0 +1,45 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import Plot from '../../../layout/plot/Plot.svelte';
+	import { buildDumbbellDefaults } from './defaults';
+	import type {
+		DumbbellPlotProps,
+		DumbbellPlotCoreProps
+	} from '../../../types/plots/ranking/dumbbell/props';
+
+	/**
+	 * A dumbbell plot: per category, the values of exactly two series as two dots joined by a connector, so the gap between them reads at a glance. Upright, or sideways when the categories run along `y`. Draws from pre-built `series` or flat `data` rows. For another number of series, see `LollipopPlot` and `ClevelandPlot`.
+	 * 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
+	}: DumbbellPlotProps<TData> = $props();
+</script>
+
+<Plot
+	core={core as DumbbellPlotCoreProps<TData>}
+	defaults={buildDumbbellDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>

package/dist/plots/ranking/dumbbell/Plot.svelte.d.ts

@@ -0,0 +1,26 @@
+import Plot from '../../../layout/plot/Plot.svelte';
+import type { DumbbellPlotProps } from '../../../types/plots/ranking/dumbbell/props';
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: DumbbellPlotProps<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/ranking/dumbbell/defaults.d.ts

@@ -0,0 +1,9 @@
+import type { AxisPlotDefaults } from '../../../types/phases';
+import type { DumbbellPlotState, DumbbellPlotCtx } from '../../../types/plots/ranking/dumbbell/state';
+/**
+ * DumbbellPlot on the shared pipeline: a ClevelandPlot of exactly two series,
+ * so every category is two dots joined by a connector - the change, or the gap,
+ * between them. It warns when it has another number of series, which
+ * `LollipopPlot` (one) and `ClevelandPlot` (any) are for.
+ */
+export declare function buildDumbbellDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<DumbbellPlotState<TData>, DumbbellPlotCtx>;

package/dist/plots/ranking/dumbbell/defaults.js

@@ -0,0 +1,19 @@
+import { buildClevelandDefaults } from '../cleveland/defaults';
+/**
+ * DumbbellPlot on the shared pipeline: a ClevelandPlot of exactly two series,
+ * so every category is two dots joined by a connector - the change, or the gap,
+ * between them. It warns when it has another number of series, which
+ * `LollipopPlot` (one) and `ClevelandPlot` (any) are for.
+ */
+export function buildDumbbellDefaults() {
+    return buildClevelandDefaults({
+        name: 'DumbbellPlot',
+        config: 'dumbbell',
+        validate: ({ seriesCount }) => seriesCount !== 2
+            ? `a dumbbell joins exactly two series, but it has ${seriesCount}. ` +
+                (seriesCount === 1
+                    ? 'Use LollipopPlot for one series.'
+                    : 'Use ClevelandPlot for any number of series.')
+            : undefined
+    });
+}

package/dist/plots/ranking/forest/Plot.svelte

@@ -0,0 +1,42 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import Plot from '../../../layout/plot/Plot.svelte';
+	import { buildForestDefaults } from './defaults';
+	import type { ForestPlotProps, ForestPlotCoreProps } from '../../../types/plots/ranking/forest/props';
+
+	/**
+	 * A forest plot: per category, a dot - an estimate - on a stem that spans its interval, given by each row's `lower` and `upper` (or an `error` either side of it), upright or sideways when the categories run along `y`. Draws from pre-built `series` or flat `data` rows. For several series sharing a category, see `facet`, `DumbbellPlot` and `ClevelandPlot`.
+	 * 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
+	}: ForestPlotProps<TData> = $props();
+</script>
+
+<Plot
+	core={core as ForestPlotCoreProps<TData>}
+	defaults={buildForestDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>

package/dist/plots/ranking/forest/Plot.svelte.d.ts

@@ -0,0 +1,26 @@
+import Plot from '../../../layout/plot/Plot.svelte';
+import type { ForestPlotProps } from '../../../types/plots/ranking/forest/props';
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: ForestPlotProps<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/ranking/forest/defaults.d.ts

@@ -0,0 +1,11 @@
+import type { AxisPlotDefaults } from '../../../types/phases';
+import type { ForestPlotState, ForestPlotCtx } from '../../../types/plots/ranking/forest/state';
+/**
+ * ForestPlot on the shared pipeline: a ClevelandPlot whose dot is an estimate
+ * and whose stem is its interval - each row's `lower` and `upper`, or `error`
+ * either side of it. One interval per category, so it warns when a category
+ * has values in several series, which `ClevelandPlot` and `DumbbellPlot` are
+ * for - or `facet`, to compare the series side by side. The value axis fits the
+ * intervals' ends.
+ */
+export declare function buildForestDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<ForestPlotState<TData>, ForestPlotCtx>;

package/dist/plots/ranking/forest/defaults.js

@@ -0,0 +1,20 @@
+import { buildClevelandDefaults } from '../cleveland/defaults';
+/**
+ * ForestPlot on the shared pipeline: a ClevelandPlot whose dot is an estimate
+ * and whose stem is its interval - each row's `lower` and `upper`, or `error`
+ * either side of it. One interval per category, so it warns when a category
+ * has values in several series, which `ClevelandPlot` and `DumbbellPlot` are
+ * for - or `facet`, to compare the series side by side. The value axis fits the
+ * intervals' ends.
+ */
+export function buildForestDefaults() {
+    return buildClevelandDefaults({
+        name: 'ForestPlot',
+        config: 'forest',
+        interval: true,
+        validate: ({ maxSeriesPerCategory }) => maxSeriesPerCategory > 1
+            ? 'a forest plot draws one interval per category, but a category has values in several series. ' +
+                'Split the series into panels with `facet`.'
+            : undefined
+    });
+}

package/dist/plots/ranking/lollipop/Plot.svelte

@@ -0,0 +1,45 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import Plot from '../../../layout/plot/Plot.svelte';
+	import { buildLollipopDefaults } from './defaults';
+	import type {
+		LollipopPlotProps,
+		LollipopPlotCoreProps
+	} from '../../../types/plots/ranking/lollipop/props';
+
+	/**
+	 * A lollipop plot: one value per category as a dot on a thin stem that rises from the baseline, upright, or sideways when the categories run along `y`. Draws from pre-built `series` or flat `data` rows. For several series per category, see `DumbbellPlot` and `ClevelandPlot`.
+	 * 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
+	}: LollipopPlotProps<TData> = $props();
+</script>
+
+<Plot
+	core={core as LollipopPlotCoreProps<TData>}
+	defaults={buildLollipopDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>

package/dist/plots/ranking/lollipop/Plot.svelte.d.ts

@@ -0,0 +1,26 @@
+import Plot from '../../../layout/plot/Plot.svelte';
+import type { LollipopPlotProps } from '../../../types/plots/ranking/lollipop/props';
+declare function $$render<TData extends Record<string, unknown>>(): {
+    props: LollipopPlotProps<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/ranking/lollipop/defaults.d.ts

@@ -0,0 +1,9 @@
+import type { AxisPlotDefaults } from '../../../types/phases';
+import type { LollipopPlotState, LollipopPlotCtx } from '../../../types/plots/ranking/lollipop/state';
+/**
+ * LollipopPlot on the shared pipeline: a ClevelandPlot of one value per
+ * category, whose stem rises from the baseline - zero, or the nearest end of a
+ * pinned value domain - to the dot. It warns when a category has values in
+ * several series, which `DumbbellPlot` and `ClevelandPlot` are for.
+ */
+export declare function buildLollipopDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<LollipopPlotState<TData>, LollipopPlotCtx>;

package/dist/plots/ranking/lollipop/defaults.js

@@ -0,0 +1,18 @@
+import { buildClevelandDefaults } from '../cleveland/defaults';
+/**
+ * LollipopPlot on the shared pipeline: a ClevelandPlot of one value per
+ * category, whose stem rises from the baseline - zero, or the nearest end of a
+ * pinned value domain - to the dot. It warns when a category has values in
+ * several series, which `DumbbellPlot` and `ClevelandPlot` are for.
+ */
+export function buildLollipopDefaults() {
+    return buildClevelandDefaults({
+        name: 'LollipopPlot',
+        config: 'lollipop',
+        fromBaseline: true,
+        validate: ({ maxSeriesPerCategory }) => maxSeriesPerCategory > 1
+            ? 'a lollipop draws one value per category, but a category has values in several series. ' +
+                'Use DumbbellPlot for two series, or ClevelandPlot for any number.'
+            : undefined
+    });
+}

package/dist/plots/utils/RowNumbers.d.ts

@@ -0,0 +1,16 @@
+/** The accessors a plot reads a row's interval from. */
+export type IntervalAccessors = {
+    lower?: unknown;
+    upper?: unknown;
+    error?: unknown;
+};
+/** The numbers a plot reads off a row: a single value, or the interval around one. */
+export declare class RowNumbers {
+    /** A number of a row: a literal, or read through a field key or a function of the row; `undefined` where it is not a finite number. */
+    static of(source: unknown, row: unknown): number | undefined;
+    /**
+     * The ends of a row's interval: its `lower` and `upper`, or `error` either side of
+     * `value`; the value itself where it has none. Always holds the value.
+     */
+    static interval(accessors: IntervalAccessors, row: unknown, value: number): [number, number];
+}

package/dist/plots/utils/RowNumbers.js

@@ -0,0 +1,24 @@
+import { resolveAccessor } from '../../utils/accessors';
+/** The numbers a plot reads off a row: a single value, or the interval around one. */
+export class RowNumbers {
+    /** A number of a row: a literal, or read through a field key or a function of the row; `undefined` where it is not a finite number. */
+    static of(source, row) {
+        if (source === undefined)
+            return undefined;
+        const raw = typeof source === 'number' ? source : resolveAccessor(source)(row);
+        const value = Number(raw);
+        return raw === null || raw === '' || !Number.isFinite(value) ? undefined : value;
+    }
+    /**
+     * The ends of a row's interval: its `lower` and `upper`, or `error` either side of
+     * `value`; the value itself where it has none. Always holds the value.
+     */
+    static interval(accessors, row, value) {
+        const error = RowNumbers.of(accessors.error, row);
+        const lower = RowNumbers.of(accessors.lower, row);
+        const upper = RowNumbers.of(accessors.upper, row);
+        const low = lower ?? (error === undefined ? value : value - error);
+        const high = upper ?? (error === undefined ? value : value + error);
+        return [Math.min(low, value), Math.max(high, value)];
+    }
+}

package/dist/plots/utils/gaps.js

@@ -1,5 +1,5 @@
 import { seriesIdOf } from '../../utils/grouping';
-import { resolveAccessor } from './accessors';
+import { resolveAccessor } from '../../utils/accessors';
 import { Interpolation } from '../../utils/Interpolation';
 const DEFAULT_KEY = 'default';
 /**

package/dist/plots/utils/segments.js

@@ -1,4 +1,4 @@
-import { resolveAccessor } from './accessors';
+import { resolveAccessor } from '../../utils/accessors';
 import { merge } from '../../utils/merge';
 const DEFAULT_KEY = 'default';
 /**