@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/layout/styles/ValueLabels.js

@@ -0,0 +1,237 @@
+import { Box } from '../margins/Box';
+import { resolveAccessor } from '../../plots/utils/accessors';
+import { SERIES_ID_KEY, SERIES_KEY, TransformsPhase } from '../../phases/transforms/TransformsPhase';
+import { seriesIdOf } from '../../utils/grouping';
+import { Transforms } from '../../phases/transforms/Transforms';
+import { isGapValue } from '../../plots/utils/gaps';
+import { PlotAxes } from '../../phases/data/PlotAxes';
+/**
+ * A plot's value labels: the author's `styles.values` over the plot kind's
+ * own defaults, how their text measures, where they are expected to sit
+ * (`reach`, which the plot's margins keep room for), and what every label marker shares
+ * ({@link hooks}). The "markers" phase draws them.
+ */
+export class ValueLabels {
+    show;
+    anchor;
+    format;
+    hoverIsolate;
+    font;
+    fontSize;
+    /** The connectors of labels that had to move apart. */
+    strokeStyle;
+    /** How labels that would overlap move apart - the configuration's `text.declutter`. */
+    declutter;
+    /** Where the labels are expected to sit: boxes around their points, on the edges those can reach. */
+    reach;
+    #cfg;
+    constructor(values, cfg, options = {}, reach) {
+        this.show = values?.show ?? options.show ?? false;
+        this.anchor = values?.anchor ?? options.anchor ?? 'outside';
+        this.format = values?.format ?? options.format ?? ((v) => `${v}`);
+        this.hoverIsolate = values?.hoverIsolate ?? false;
+        this.font = values?.fontStyle;
+        this.fontSize = typeof this.font?.fontSize === 'number' ? this.font.fontSize : 12;
+        this.strokeStyle = values?.strokeStyle;
+        this.declutter = cfg.text.declutter;
+        this.#cfg = cfg;
+        this.reach = (this.show && reach?.(this)) || [];
+    }
+    /** A plot's value labels: `values` over `options`, the kind's own defaults, their reach read off `state`. */
+    static build(values, cfg, options, state) {
+        const { reach } = options;
+        return new ValueLabels(values, cfg, options, reach && ((labels) => reach(labels, state)));
+    }
+    /** One line of label text's height. */
+    get lineHeight() {
+        return this.fontSize * 1.2;
+    }
+    /** The box one label's `text` takes. */
+    textBox(text) {
+        return Box.ofText(text, this.fontSize, this.#cfg);
+    }
+    /** The labels' gap (px) from their mark along `axis`: their own `dx`/`dy`, else `fallback`. */
+    offset(axis, fallback = 6) {
+        const own = axis === 'x' ? this.font?.dx : this.font?.dy;
+        return Math.abs(typeof own === 'number' ? own : fallback);
+    }
+    /**
+     * Where a label reading `text` sits around its point: anchored `at` that
+     * offset from it (its `dx`/`dy`), on `side` of that anchor per axis - the
+     * way its `textAnchor`/`lineAnchor` set it - with the plot `edges` the
+     * point can sit on.
+     */
+    edgeBox(text, side, at, edges) {
+        const box = this.textBox(text).beside({ x: at.x ?? 0, y: at.y ?? 0 }, side);
+        return { box, edges };
+    }
+    /** Each series' value farthest from zero, read on `valueAxis` - the widest label it can show. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    extremes(series, valueAxis = 'y') {
+        return series.flatMap((s) => {
+            const accessor = s[valueAxis];
+            if (accessor === undefined)
+                return [];
+            const y = resolveAccessor(accessor);
+            let extreme;
+            for (const d of s.data) {
+                const v = Number(y(d));
+                if (!Number.isNaN(v) && (extreme === undefined || Math.abs(v) > Math.abs(extreme)))
+                    extreme = v;
+            }
+            return extreme === undefined ? [] : [{ series: s, value: extreme }];
+        });
+    }
+    /**
+     * The author's own `textAnchor`, if any. `'outside'` is a hover marker's
+     * per-point anchor; a label's own `anchor` already places it, so here it
+     * counts as unset.
+     */
+    get textAnchor() {
+        const own = this.font?.textAnchor;
+        return own === 'outside' ? undefined : own;
+    }
+    /**
+     * What every label marker shares: the plot's margins grow to fit it, it
+     * dims with its row's series, and with `hoverIsolate`, hovering it
+     * isolates that series. A row without a series gets the margins only.
+     */
+    hooks(ctx) {
+        const interaction = ctx.interaction;
+        const seriesOf = (d) => d?.[SERIES_KEY] === undefined ? undefined : String(d[SERIES_KEY]);
+        const isolate = this.hoverIsolate && interaction;
+        return {
+            fitMargins: true,
+            fillOpacity: (d) => {
+                const series = seriesOf(d);
+                return series === undefined ? undefined : interaction?.fillFor(series)?.fillOpacity;
+            },
+            onPointerEnter: isolate
+                ? (d) => interaction.isolate(seriesOf(d) ?? null)
+                : undefined,
+            onPointerLeave: isolate ? () => interaction.isolate(null) : undefined
+        };
+    }
+    /**
+     * A processed row's own value, read through its series' own value channel
+     * (`y`, or `x` on a horizontal plot) - what a label shows, even where a
+     * transform moved the row (a stacked row's top is the running total, not
+     * its own value).
+     */
+    static valueOf(state) {
+        const valueAxis = PlotAxes.valueOf(state);
+        const bySeries = new Map((state.resolvedSeries ?? []).flatMap((s) => {
+            const accessor = s[valueAxis];
+            return accessor === undefined ? [] : [[seriesIdOf(s), resolveAccessor(accessor)]];
+        }));
+        return (d) => bySeries.get(String(d[SERIES_ID_KEY]))?.(d);
+    }
+    /**
+     * A series-over-`x` plot's (line, area) labels: one `'text'` marker over
+     * the processed rows, each visible series' last row with a value
+     * (`filter` + `selectLast`, per series), at its top (a stacked row's
+     * `y2`), labelled with its own value and placed by `anchor`. Labels that
+     * would overlap fan out into a shared column (`declutter`), colored by the
+     * segment the row falls in.
+     */
+    atSeriesEnds(state) {
+        const processed = state.processedData;
+        if (!processed)
+            return [];
+        const { font, anchor, format } = this;
+        const position = TransformsPhase.processedPosition(processed);
+        const topOf = (d) => position.y(d);
+        const nameOf = (d) => String(d[SERIES_KEY]);
+        const valueOf = ValueLabels.valueOf(state);
+        const colorOf = (d) => {
+            const id = String(d[SERIES_ID_KEY]);
+            const group = state.scopedGroups?.find((g) => (g.id ?? g.name) === id);
+            const segment = group?.segments.find((seg) => seg.match(d));
+            return (segment?.color ??
+                group?.segments[0]?.color ??
+                group?.color ??
+                state.colorForSeries?.(nameOf(d)));
+        };
+        const marker = Transforms.resolve({
+            type: 'text',
+            data: processed.data,
+            x: (processed.channels.x ?? position.x),
+            y: (processed.channels.y2 ?? processed.channels.y ?? topOf),
+            grouping: SERIES_ID_KEY,
+            transforms: [
+                {
+                    type: 'filter',
+                    filter: (d) => !isGapValue(valueOf(d)) && !isGapValue(topOf(d))
+                },
+                { type: 'selectLast' }
+            ],
+            text: (d) => format(Number(valueOf(d)), nameOf(d)),
+            styles: {
+                ...font,
+                fontSize: font?.fontSize ?? 12,
+                dx: font?.dx ?? (anchor === 'start' ? 6 : anchor === 'end' ? -6 : 0),
+                dy: font?.dy ?? (anchor === 'outside' ? -8 : 0),
+                textAnchor: this.textAnchor ?? (anchor === 'start' || anchor === 'end' ? anchor : 'middle'),
+                lineAnchor: font?.lineAnchor ?? (anchor === 'outside' ? 'bottom' : 'middle')
+            },
+            fill: font?.fill ? undefined : colorOf,
+            declutter: { connector: this.strokeStyle }
+        }, processed.data);
+        return marker.data?.length ? [marker] : [];
+    }
+    /**
+     * Where {@link atSeriesEnds}' labels are expected to sit: past each
+     * series' last point, at the right edge (or the left, for labels set
+     * before their point; both for a fan of several series, which can flip),
+     * reaching up or down from the top or bottom edge. Read off the `y`
+     * domain when the scales set one, so it holds across a timeline; else off
+     * every value.
+     */
+    reachAtSeriesEnds(state) {
+        const series = state.resolvedSeries ?? [];
+        const { anchor, font, format } = this;
+        const dx = typeof font?.dx === 'number' ? font.dx : anchor === 'start' ? 6 : anchor === 'end' ? -6 : 0;
+        const dy = typeof font?.dy === 'number' ? font.dy : anchor === 'outside' ? -8 : 0;
+        const textAnchor = this.textAnchor ?? (anchor === 'start' ? 'start' : anchor === 'end' ? 'end' : 'middle');
+        const lineAnchor = font?.lineAnchor ?? (anchor === 'outside' ? 'bottom' : 'middle');
+        const side = {
+            x: textAnchor === 'start' ? 'after' : textAnchor === 'end' ? 'before' : 'middle',
+            y: lineAnchor === 'top' ? 'after' : lineAnchor === 'bottom' ? 'before' : 'middle'
+        };
+        // Labels that would overlap fan out into lanes, each one further out.
+        const { elbowGap, laneStep, labelGap } = this.declutter;
+        const lanes = elbowGap + (series.length - 1) * laneStep + labelGap;
+        const at = { x: series.length > 1 ? (Math.sign(dx) || 1) * lanes : dx, y: dy };
+        const edges = [
+            'top',
+            'bottom',
+            ...(dx < 0 ? ['left'] : []),
+            ...(dx >= 0 || series.length > 1 ? ['right'] : [])
+        ];
+        const texts = [];
+        const domain = state.scales.y?.domain;
+        if (domain && domain.length >= 2) {
+            const lo = Number(domain[0]);
+            const hi = Number(domain[domain.length - 1]);
+            for (const s of series)
+                texts.push(format(lo, s.name), format(hi, s.name));
+        }
+        else {
+            for (const s of series) {
+                if (s.y === undefined)
+                    continue;
+                const y = resolveAccessor(s.y);
+                for (const d of s.data) {
+                    const v = Number(y(d));
+                    if (!Number.isNaN(v))
+                        texts.push(format(v, s.name));
+                }
+            }
+        }
+        // +2px: canvas and SVG text can measure a pixel or so apart.
+        return texts.map((text) => {
+            const { box } = this.edgeBox(text, side, at, edges);
+            return { box: box.pad(2), edges };
+        });
+    }
+}

package/dist/layout/timeline/Timeline.svelte

@@ -1,86 +1,92 @@
 <script lang="ts">
-  import { Plot, RuleX, RuleY, Text } from 'svelteplot';
-  import type { Orientation, TimeValue } from '../../types/layout/timeline';
+	import { Plot, RuleX, RuleY, Text } from 'svelteplot';
+	import { TimelineSteps } from './TimelineSteps';
+	import { getConfiguration } from '../../configuration/config.svelte';
+	import type { Orientation, TimeValue } from '../../types/layout/timeline';
 
-  /**
-   * Purely visual time axis: a baseline rule plus the ordered step labels with
-   * the current step emphasised. It has no notion of data — it just draws the
-   * `values` it is handed and highlights `currentValue`. Colours come from CSS
-   * variables so a host app can theme it.
-   */
-  let {
-    currentValue,
-    values,
-    orientation = 'vertical',
-    width,
-    height,
-  }: {
-    currentValue: TimeValue;
-    values: TimeValue[];
-    orientation?: Orientation;
-    width: number;
-    height: number;
-  } = $props();
+	/**
+	 * Purely visual time axis: a baseline rule plus the ordered step labels with
+	 * the current step emphasised. It has no notion of data - it just draws the
+	 * `values` it is handed and highlights `currentValue`. Colours come from CSS
+	 * variables so a host app can theme it, and sizes and opacities from the
+	 * configuration's `timeline.rule`.
+	 */
+	let {
+		currentValue,
+		values,
+		orientation = 'vertical',
+		width,
+		height
+	}: {
+		currentValue: TimeValue;
+		values: TimeValue[];
+		orientation?: Orientation;
+		width: number;
+		height: number;
+	} = $props();
 
-  const isHorizontal = $derived(orientation === 'horizontal');
-  const crossKey = $derived(isHorizontal ? 'y' : 'x');
+	const config = $derived(getConfiguration());
+	const rule = $derived(config.timeline.rule);
 
-  const domain = $derived.by(() => {
-    const sorted = [...values].sort((a, b) => a - b);
-    return [sorted[0], sorted[sorted.length - 1]];
-  });
+	const isHorizontal = $derived(orientation === 'horizontal');
+	const crossKey = $derived(isHorizontal ? 'y' : 'x');
 
-  const baseValues = $derived(values.filter((v) => v !== currentValue));
-  const identity = (d: TimeValue) => d;
+	const domain = $derived(new TimelineSteps(values).domain);
 
-  const Rule = $derived(isHorizontal ? RuleY : RuleX);
+	const baseValues = $derived(values.filter((v) => v !== currentValue));
+	const identity = (d: TimeValue) => d;
 
-  const textOffset = $derived(
-    isHorizontal
-      ? { dy: -12, dx: 0, textAnchor: 'middle' as const }
-      : { dx: -8, dy: 0, textAnchor: 'end' as const },
-  );
+	const Rule = $derived(isHorizontal ? RuleY : RuleX);
 
-  const axisConfig = $derived(
-    isHorizontal
-      ? { x: { domain, ticks: [] }, y: { axis: false as const } }
-      : { y: { domain, ticks: [], reverse: true }, x: { axis: false as const } },
-  );
+	const textOffset = $derived(
+		isHorizontal
+			? { dy: -12, dx: 0, textAnchor: 'middle' as const }
+			: { dx: -8, dy: 0, textAnchor: 'end' as const }
+	);
+
+	const axisConfig = $derived(
+		isHorizontal
+			? { x: { domain, ticks: [] }, y: { axis: false as const } }
+			: { y: { domain, ticks: [], reverse: true }, x: { axis: false as const } }
+	);
 </script>
 
-<Plot
-  {width}
-  {height}
-  {...axisConfig}
-  marginTop={isHorizontal ? 32 : 0}
-  marginBottom={0}
-  marginLeft={isHorizontal ? 30 : 50}
-  marginRight={isHorizontal ? 30 : 0}
->
-  <Rule
-    {...{ [crossKey]: 0 }}
-    stroke="var(--dct-timeline-axis, currentColor)"
-    strokeOpacity={0.7}
-    strokeWidth={1.5}
-  />
+<!-- Drawn with the configuration's font even outside a figure's chrome, which would hand it down. -->
+<div style="display: contents" style:font-family={config.font}>
+	<Plot
+		{width}
+		{height}
+		{...axisConfig}
+		marginTop={isHorizontal ? 32 : 0}
+		marginBottom={0}
+		marginLeft={isHorizontal ? 30 : 50}
+		marginRight={isHorizontal ? 30 : 0}
+	>
+		<Rule
+			{...{ [crossKey]: 0 }}
+			stroke="var(--dct-timeline-axis, currentColor)"
+			strokeOpacity={rule.axisOpacity}
+			strokeWidth={rule.axisWidth}
+		/>
 
-  <Text
-    data={baseValues}
-    {...(isHorizontal ? { x: identity, y: 0 } : { x: 0, y: identity })}
-    text={(d: TimeValue) => `${d}`}
-    {...textOffset}
-    fontSize={12}
-    fill="var(--dct-timeline-axis, currentColor)"
-    fillOpacity={0.55}
-  />
+		<Text
+			data={baseValues}
+			{...isHorizontal ? { x: identity, y: 0 } : { x: 0, y: identity }}
+			text={(d: TimeValue) => `${d}`}
+			{...textOffset}
+			fontSize={rule.fontSize}
+			fill="var(--dct-timeline-axis, currentColor)"
+			fillOpacity={rule.labelOpacity}
+		/>
 
-  <Text
-    data={[currentValue]}
-    {...(isHorizontal ? { x: identity, y: 0 } : { x: 0, y: identity })}
-    text={(d: TimeValue) => `${d}`}
-    {...textOffset}
-    fontSize={20}
-    fontWeight="bold"
-    fill="var(--dct-timeline-active, #e6580d)"
-  />
-</Plot>
+		<Text
+			data={[currentValue]}
+			{...isHorizontal ? { x: identity, y: 0 } : { x: 0, y: identity }}
+			text={(d: TimeValue) => `${d}`}
+			{...textOffset}
+			fontSize={rule.activeFontSize}
+			fontWeight={rule.activeFontWeight}
+			fill={getConfiguration().timeline.activeColor}
+		/>
+	</Plot>
+</div>

package/dist/layout/timeline/TimelineFrame.svelte

@@ -0,0 +1,86 @@
+<script lang="ts">
+	import Timeline from './Timeline.svelte';
+	import type { Snippet } from 'svelte';
+	import type { Orientation, TimeValue } from '../../types/layout/timeline';
+	import type { PlotBoxContext } from '../../types/layout/figure';
+
+	/**
+	 * Splits a box between its content and a timeline gutter showing `steps`
+	 * with `selectedValue` highlighted. The content is the `child` snippet,
+	 * handed whatever box the gutter and `--dct-timeline-gap` leave.
+	 */
+	let {
+		steps,
+		selectedValue,
+		orientation = 'vertical',
+		show = true,
+		thickness = 60,
+		width,
+		height,
+		child
+	}: {
+		steps: TimeValue[];
+		selectedValue: TimeValue;
+		orientation?: Orientation;
+		show?: boolean;
+		thickness?: number;
+		width: number;
+		height: number;
+		child: Snippet<[PlotBoxContext]>;
+	} = $props();
+
+	const vertical = $derived(orientation === 'vertical');
+
+	let innerWidth = $state(0);
+	let innerHeight = $state(0);
+</script>
+
+<div
+	class="dct-timeline"
+	class:dct-timeline--horizontal={!vertical}
+	style:width="{width}px"
+	style:height="{height}px"
+>
+	<div class="dct-timeline__plot" bind:clientWidth={innerWidth} bind:clientHeight={innerHeight}>
+		{#if innerWidth > 0 && innerHeight > 0}
+			{@render child({ width: innerWidth, height: innerHeight })}
+		{/if}
+	</div>
+	{#if show}
+		<div
+			class="dct-timeline__gutter"
+			style:width={vertical ? `${thickness}px` : undefined}
+			style:height={vertical ? undefined : `${thickness}px`}
+		>
+			<Timeline
+				currentValue={selectedValue}
+				values={steps}
+				{orientation}
+				width={vertical ? thickness : width}
+				height={vertical ? height : thickness}
+			/>
+		</div>
+	{/if}
+</div>
+
+<style>
+	.dct-timeline {
+		display: flex;
+		flex-direction: row;
+		gap: var(--dct-timeline-gap, 12px);
+	}
+	.dct-timeline--horizontal {
+		flex-direction: column;
+	}
+	.dct-timeline__plot {
+		flex: 1 1 0;
+		min-width: 0;
+		min-height: 0;
+	}
+	.dct-timeline__gutter {
+		flex: 0 0 auto;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+</style>

package/dist/layout/timeline/TimelineFrame.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from 'svelte';
+import type { Orientation, TimeValue } from '../../types/layout/timeline';
+import type { PlotBoxContext } from '../../types/layout/figure';
+type $$ComponentProps = {
+    steps: TimeValue[];
+    selectedValue: TimeValue;
+    orientation?: Orientation;
+    show?: boolean;
+    thickness?: number;
+    width: number;
+    height: number;
+    child: Snippet<[PlotBoxContext]>;
+};
+declare const TimelineFrame: import("svelte").Component<$$ComponentProps, {}, "">;
+type TimelineFrame = ReturnType<typeof TimelineFrame>;
+export default TimelineFrame;