@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/layout/timeline/Timeline.svelte

@@ -1,86 +1,95 @@
 <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',
+		format = (value: TimeValue) => String(value),
+		width,
+		height
+	}: {
+		currentValue: TimeValue;
+		values: TimeValue[];
+		orientation?: Orientation;
+		/** How a step's label reads. */
+		format?: (value: TimeValue) => string;
+		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) => format(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) => format(d)}
+			{...textOffset}
+			fontSize={rule.activeFontSize}
+			fontWeight={rule.activeFontWeight}
+			fill={getConfiguration().timeline.activeColor}
+		/>
+	</Plot>
+</div>

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

@@ -3,6 +3,8 @@ type $$ComponentProps = {
     currentValue: TimeValue;
     values: TimeValue[];
     orientation?: Orientation;
+    /** How a step's label reads. */
+    format?: (value: TimeValue) => string;
     width: number;
     height: number;
 };

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;

package/dist/layout/timeline/TimelineLayout.svelte

@@ -1,186 +1,157 @@
 <script lang="ts" generics="TRow extends Record<string, unknown>">
-  import { resolveAccessor } from '../../plots/utils/accessors';
-  import Timeline from './Timeline.svelte';
-  import { resolveEasing, interpolateSeries } from '../../utils/interpolate';
-  import type {
-    Orientation,
-    TimeValue,
-    TimelineChildSnippet,
-    TimelineInterpolation,
-  } from '../../types/layout/timeline';
-  import type { Accessor } from '../../types/plots/data/common';
+	import { untrack } from 'svelte';
+	import { resolveAccessor } from '../../plots/utils/accessors';
+	import TimelineFrame from './TimelineFrame.svelte';
+	import { TimelineSteps } from './TimelineSteps';
+	import { TimelineTime } from './TimelineTime';
+	import { Interpolation } from '../../utils/Interpolation';
+	import type {
+		Orientation,
+		TimeInput,
+		TimeValue,
+		TimelineChildSnippet,
+		TimelineInterpolation
+	} from '../../types/layout/timeline';
+	import type { Accessor } from '../../types/plots/data/common';
+	import type { PlotBoxContext } from '../../types/layout/figure';
 
-  /**
-   * Couples a scrubber `progress` to a discrete sequence of time steps. It picks
-   * the selected step, filters the data down to it, splits the available box
-   * between the plot and the timeline gutter, and renders both. The plot itself
-   * is supplied as the `child` snippet, so this layout is plot-agnostic.
-   */
-  let {
-    data,
-    accessor,
-    progress,
-    values,
-    orientation = 'vertical',
-    show = true,
-    thickness = 60,
-    filterMode = 'exact',
-    interpolate,
-    width,
-    height,
-    child,
-  }: {
-    data: TRow[];
-    accessor: Accessor<TRow, TimeValue>;
-    progress: number;
-    values?: TimeValue[];
-    orientation?: Orientation;
-    show?: boolean;
-    thickness?: number;
-    filterMode?: 'exact' | 'upTo';
-    interpolate?: TimelineInterpolation<TRow>;
-    width: number;
-    height: number;
-    child: TimelineChildSnippet<TRow>;
-  } = $props();
+	/**
+	 * Couples a scrubber `progress` to a discrete sequence of time steps. It picks
+	 * the selected step, filters the data down to it, and renders the plot beside
+	 * the timeline in a `TimelineFrame`. The plot itself is supplied as the
+	 * `child` snippet, so this layout is plot-agnostic.
+	 */
+	let {
+		data,
+		accessor,
+		dateFormat,
+		progress,
+		values,
+		orientation = 'vertical',
+		show = true,
+		thickness = 60,
+		filterMode = 'exact',
+		interpolate,
+		onsteps,
+		width,
+		height,
+		child
+	}: {
+		data: TRow[];
+		accessor: Accessor<TRow, TimeInput>;
+		/** How a non-ISO date string reads. */
+		dateFormat?: string;
+		progress: number;
+		values?: TimeInput[];
+		orientation?: Orientation;
+		show?: boolean;
+		thickness?: number;
+		filterMode?: 'exact' | 'upTo';
+		interpolate?: TimelineInterpolation<TRow>;
+		/** Told the steps, and whether they are dates, when they change. */
+		onsteps?: (values: TimeValue[], temporal: boolean) => void;
+		width: number;
+		height: number;
+		child: TimelineChildSnippet<TRow>;
+	} = $props();
 
-  const getTime = $derived(resolveAccessor<TRow>(accessor));
+	const time = $derived(new TimelineTime(dateFormat));
+	const getRaw = $derived(resolveAccessor<TRow>(accessor) as (row: TRow) => unknown);
+	/** A row's step, or `undefined` when its value reads as none. */
+	const getTime = $derived((row: TRow) => time.toTime(getRaw(row)));
+	/** The rows with a step; one without shows at every step. */
+	const timed = $derived(data.filter((row) => getTime(row) !== undefined));
+	const untimed = $derived(data.filter((row) => getTime(row) === undefined));
 
-  const steps = $derived.by(() => {
-    if (values?.length) return [...values].sort((a, b) => a - b);
-    return [...new Set(data.map(getTime))].sort((a, b) => a - b);
-  });
+	const steps = $derived(
+		TimelineSteps.of(
+			values?.map((value) => time.toTime(value)).filter((v): v is TimeValue => v !== undefined),
+			timed,
+			getTime as (row: TRow) => TimeValue
+		)
+	);
+	const temporal = $derived(time.isTemporal(values?.length ? values : timed.map(getRaw)));
 
-  const progressEasingFn = $derived(resolveEasing(interpolate?.progressEasing));
-  const segmentEasingFn = $derived(resolveEasing(interpolate?.segmentEasing));
+	$effect(() => {
+		const found = steps.values;
+		const dates = temporal;
+		untrack(() => onsteps?.(found, dates));
+	});
 
-  /** Continuous scrub position across the full step domain — only meaningful when `interpolate` is set. */
-  const currentTime = $derived.by(() => {
-    if (!steps.length) return 0;
-    const t0 = steps[0];
-    const t1 = steps[steps.length - 1];
-    return t0 + (t1 - t0) * progressEasingFn(progress);
-  });
+	const progressEasingFn = $derived(Interpolation.buildEasing(interpolate?.progressEasing));
+	const segmentEasingFn = $derived(Interpolation.buildEasing(interpolate?.segmentEasing));
 
-  const selectedValue = $derived.by(() => {
-    if (!steps.length) return 0;
-    if (interpolate) {
-      return steps.reduce((best, s) =>
-        Math.abs(s - currentTime) < Math.abs(best - currentTime) ? s : best,
-      );
-    }
-    const idx = Math.min(
-      steps.length - 1,
-      Math.max(0, Math.round(progress * (steps.length - 1))),
-    );
-    return steps[idx];
-  });
+	/** Continuous scrub position across the full step domain - only meaningful when `interpolate` is set. */
+	const currentTime = $derived(steps.timeAt(progress, progressEasingFn));
 
-  function defaultCreate(_lower: TRow, upper: TRow, x: TimeValue, value: number): TRow {
-    const valueField = interpolate?.value;
-    if (typeof accessor !== 'string' || typeof valueField !== 'string') {
-      console.warn(
-        'TimelineLayout: cannot auto-build an interpolated row when `accessor` or `interpolate.value` is a function — pass `interpolate.create` explicitly.',
-      );
-      return upper;
-    }
-    return { ...upper, [accessor]: x, [valueField]: value } as TRow;
-  }
+	const selectedValue = $derived(
+		(interpolate ? steps.nearest(currentTime) : steps.at(progress)) ?? 0
+	);
 
-  const filtered = $derived.by(() => {
-    const discrete = () =>
-      filterMode === 'upTo'
-        ? data.filter((d) => getTime(d) <= selectedValue)
-        : data.filter((d) => getTime(d) === selectedValue);
+	function defaultCreate(_lower: TRow, upper: TRow, x: TimeValue, value: number): TRow {
+		const valueField = interpolate?.value;
+		if (typeof accessor !== 'string' || typeof valueField !== 'string') {
+			console.warn(
+				'TimelineLayout: cannot auto-build an interpolated row when `accessor` or `interpolate.value` is a function - pass `interpolate.create` explicitly.'
+			);
+			return upper;
+		}
+		return {
+			...upper,
+			[accessor]: time.toValueLike(x, upper[accessor]),
+			[valueField]: value
+		} as TRow;
+	}
 
-    if (!interpolate) return discrete();
-    if (!interpolate.value) {
-      console.warn('TimelineLayout: `interpolate.value` is required to tween — falling back to discrete filtering.');
-      return discrete();
-    }
+	const filtered = $derived.by(() => {
+		const discrete = () =>
+			data.filter((d) => {
+				const at = getTime(d);
+				return at === undefined || TimelineSteps.matches(at, selectedValue, filterMode);
+			});
 
-    const getKey = resolveAccessor<TRow>(interpolate.key ?? (() => '__all__'));
-    const getValue = resolveAccessor<TRow>(interpolate.value) as (d: TRow) => number;
-    const create = interpolate.create ?? defaultCreate;
+		if (!interpolate) return discrete();
+		if (!interpolate.value) {
+			console.warn(
+				'TimelineLayout: `interpolate.value` is required to tween - falling back to discrete filtering.'
+			);
+			return discrete();
+		}
 
-    const groups = new Map<string, TRow[]>();
-    for (const row of data) {
-      const key = String(getKey(row));
-      const bucket = groups.get(key);
-      if (bucket) bucket.push(row);
-      else groups.set(key, [row]);
-    }
+		const getKey = resolveAccessor<TRow>(interpolate.key ?? (() => '__all__'));
+		const getValue = resolveAccessor<TRow>(interpolate.value) as (d: TRow) => number;
+		const create = interpolate.create ?? defaultCreate;
 
-    const result: TRow[] = [];
-    for (const rows of groups.values()) {
-      const tweened = interpolateSeries({
-        rows,
-        x: currentTime,
-        getTime,
-        getValue,
-        create,
-        segmentEasing: segmentEasingFn,
-      });
-      if (filterMode === 'upTo') result.push(...tweened);
-      else if (tweened.length) result.push(tweened[tweened.length - 1]);
-    }
-    return result;
-  });
+		const groups = Map.groupBy(timed, (row) => String(getKey(row)));
 
-  const isVertical = $derived(orientation === 'vertical');
-  const gap = $derived(show ? 12 : 0);
-  const effectiveThickness = $derived(show ? thickness : 0);
-  const innerWidth = $derived(
-    Math.max(0, isVertical ? width - effectiveThickness - gap : width),
-  );
-  const innerHeight = $derived(
-    Math.max(0, isVertical ? height : height - effectiveThickness - gap),
-  );
+		const result: TRow[] = [...untimed];
+		for (const rows of groups.values()) {
+			const tweened = Interpolation.tweenSeries({
+				rows,
+				x: currentTime,
+				getTime: getTime as (row: TRow) => TimeValue,
+				getValue,
+				create,
+				segmentEasing: segmentEasingFn
+			});
+			if (filterMode === 'upTo') result.push(...tweened);
+			else if (tweened.length) result.push(tweened[tweened.length - 1]);
+		}
+		return result;
+	});
 </script>
 
-{#if isVertical}
-  <div class="dct-timeline dct-timeline--vertical" style:width="{width}px" style:height="{height}px" style:gap="{gap}px">
-    <div class="dct-timeline__plot">
-      {@render child({ selectedValue, data: filtered, width: innerWidth, height: innerHeight })}
-    </div>
-    {#if show}
-      <div class="dct-timeline__gutter" style:width="{thickness}px">
-        <Timeline currentValue={selectedValue} values={steps} orientation="vertical" width={thickness} height={innerHeight} />
-      </div>
-    {/if}
-  </div>
-{:else}
-  <div class="dct-timeline dct-timeline--horizontal" style:width="{width}px" style:height="{height}px" style:gap="{gap}px">
-    <div class="dct-timeline__plot">
-      {@render child({ selectedValue, data: filtered, width: innerWidth, height: innerHeight })}
-    </div>
-    {#if show}
-      <div class="dct-timeline__gutter" style:height="{thickness}px">
-        <Timeline currentValue={selectedValue} values={steps} orientation="horizontal" width={innerWidth} height={thickness} />
-      </div>
-    {/if}
-  </div>
-{/if}
+{#snippet plot({ width: w, height: h }: PlotBoxContext)}
+	{@render child({ selectedValue, data: filtered, width: w, height: h })}
+{/snippet}
 
-<style>
-  .dct-timeline {
-    display: flex;
-  }
-  .dct-timeline--vertical {
-    flex-direction: row;
-  }
-  .dct-timeline--horizontal {
-    flex-direction: column;
-  }
-  .dct-timeline__plot {
-    flex: 1 1 auto;
-    min-width: 0;
-    min-height: 0;
-  }
-  .dct-timeline__gutter {
-    flex: 0 0 auto;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-  }
-</style>
+<TimelineFrame
+	steps={steps.values}
+	{selectedValue}
+	{orientation}
+	{show}
+	{thickness}
+	{width}
+	{height}
+	child={plot}
+/>

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

@@ -1,16 +1,20 @@
-import type { Orientation, TimeValue, TimelineChildSnippet, TimelineInterpolation } from '../../types/layout/timeline';
+import type { Orientation, TimeInput, TimeValue, TimelineChildSnippet, TimelineInterpolation } from '../../types/layout/timeline';
 import type { Accessor } from '../../types/plots/data/common';
 declare function $$render<TRow extends Record<string, unknown>>(): {
     props: {
         data: TRow[];
-        accessor: Accessor<TRow, TimeValue>;
+        accessor: Accessor<TRow, TimeInput>;
+        /** How a non-ISO date string reads. */
+        dateFormat?: string;
         progress: number;
-        values?: TimeValue[];
+        values?: TimeInput[];
         orientation?: Orientation;
         show?: boolean;
         thickness?: number;
         filterMode?: "exact" | "upTo";
         interpolate?: TimelineInterpolation<TRow>;
+        /** Told the steps, and whether they are dates, when they change. */
+        onsteps?: (values: TimeValue[], temporal: boolean) => void;
         width: number;
         height: number;
         child: TimelineChildSnippet<TRow>;