@fundar/data-chart-telling 1.0.0 → 1.2.0

package/dist/layout/styles/ValueLabels.js

@@ -1,8 +1,8 @@
+import { ProcessedPositions } from '../../phases/transforms/ProcessedPositions';
 import { Box } from '../margins/Box';
-import { resolveAccessor } from '../../plots/utils/accessors';
-import { SERIES_ID_KEY, SERIES_KEY, TransformsPhase } from '../../phases/transforms/TransformsPhase';
+import { resolveAccessor } from '../../utils/accessors';
+import { SERIES_ID_KEY, SERIES_KEY } 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';
 /**
@@ -20,6 +20,8 @@ export class ValueLabels {
     fontSize;
     /** The connectors of labels that had to move apart. */
     strokeStyle;
+    /** `'series'` writes each label in its series' color; any other CSS color writes them all in it. */
+    color;
     /** 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. */
@@ -33,6 +35,7 @@ export class ValueLabels {
         this.font = values?.fontStyle;
         this.fontSize = typeof this.font?.fontSize === 'number' ? this.font.fontSize : 12;
         this.strokeStyle = values?.strokeStyle;
+        this.color = values?.color;
         this.declutter = cfg.text.declutter;
         this.#cfg = cfg;
         this.reach = (this.show && reach?.(this)) || [];
@@ -42,6 +45,18 @@ export class ValueLabels {
         const { reach } = options;
         return new ValueLabels(values, cfg, options, reach && ((labels) => reach(labels, state)));
     }
+    /** The configuration the labels were built under, for a plot kind's own label defaults. */
+    get config() {
+        return this.#cfg;
+    }
+    /**
+     * The fill every label takes whatever its series: the author's own
+     * `fontStyle.fill`, else a literal `color`. `undefined` leaves each label to
+     * its plot's default (its series' color, or the axis').
+     */
+    get fill() {
+        return this.font?.fill ?? (this.color === 'series' ? undefined : this.color);
+    }
     /** One line of label text's height. */
     get lineHeight() {
         return this.fontSize * 1.2;
@@ -132,14 +147,46 @@ export class ValueLabels {
      * (`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.
+     * segment the row falls in. A plot that labels each end of its series apart
+     * passes the `rows` and `anchor` of one end, and `lane` to route its labels
+     * out to a lane whether or not they overlap (`flip: false` keeps one on the
+     * left in the margin instead of flipping it over its points).
      */
-    atSeriesEnds(state) {
+    atSeriesEnds(state, end = {}) {
+        if (end.rows)
+            return this.#seriesEnds(state, end);
+        // A label on a series' first point would sit on its own line: it goes out to a lane instead.
+        const firsts = ValueLabels.#firstRows(state);
+        const labelled = state.labelled ?? [];
+        return [
+            ...this.#seriesEnds(state, { rows: labelled.filter((row) => !firsts.has(row)) }),
+            ...this.#seriesEnds(state, {
+                rows: labelled.filter((row) => firsts.has(row)),
+                lane: { elbowGap: ValueLabels.FIRST_LANE_GAP }
+            })
+        ];
+    }
+    /** How far (px) a lane takes the label of a series' first point from it - clear of the line that leaves it. */
+    static FIRST_LANE_GAP = 28;
+    /** The first row of every series that has more than one. */
+    static #firstRows(state) {
+        const first = new Map();
+        const counts = new Map();
+        for (const row of state.processedData?.data ?? []) {
+            const id = String(row[SERIES_ID_KEY]);
+            if (!first.has(id))
+                first.set(id, row);
+            counts.set(id, (counts.get(id) ?? 0) + 1);
+        }
+        return new Set([...first].filter(([id]) => (counts.get(id) ?? 0) > 1).map(([, row]) => row));
+    }
+    #seriesEnds(state, end) {
         const processed = state.processedData;
         if (!processed)
             return [];
-        const { font, anchor, format } = this;
-        const position = TransformsPhase.processedPosition(processed);
+        const { font, format } = this;
+        const anchor = end.anchor ?? this.anchor;
+        const position = ProcessedPositions.of(processed);
         const topOf = (d) => position.y(d);
         const nameOf = (d) => String(d[SERIES_KEY]);
         const valueOf = ValueLabels.valueOf(state);
@@ -152,33 +199,39 @@ export class ValueLabels {
                 group?.color ??
                 state.colorForSeries?.(nameOf(d)));
         };
-        const marker = Transforms.resolve({
+        const marker = {
             type: 'text',
-            data: processed.data,
+            // The rows the "transforms" phase picked for the labels: by default each series' last.
+            data: end.rows ?? state.labelled ?? [],
             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,
+                ...(this.fill ? { fill: this.fill } : {}),
                 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);
+            fill: this.fill ? undefined : colorOf,
+            declutter: {
+                connector: this.strokeStyle,
+                aligned: !!end.lane && (anchor === 'start' || anchor === 'end'),
+                elbowGap: typeof end.lane === 'object' ? end.lane.elbowGap : undefined,
+                flip: end.flip
+            }
+        };
         return marker.data?.length ? [marker] : [];
     }
+    /** The rows of a series-over-`x` plot that cannot be labelled: a gap, or a stack with no top. For the "transforms" phase's `labels.skip`. */
+    static skipGaps(state) {
+        const valueOf = ValueLabels.valueOf(state);
+        const top = ProcessedPositions.of(state.processedData).y;
+        return (row) => isGapValue(valueOf(row)) || isGapValue(top(row));
+    }
     /**
      * Where {@link atSeriesEnds}' labels are expected to sit: past each
      * series' last point, at the right edge (or the left, for labels set
@@ -187,9 +240,9 @@ export class ValueLabels {
      * domain when the scales set one, so it holds across a timeline; else off
      * every value.
      */
-    reachAtSeriesEnds(state) {
+    reachAtSeriesEnds(state, anchor = this.anchor) {
         const series = state.resolvedSeries ?? [];
-        const { anchor, font, format } = this;
+        const { 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');
@@ -202,11 +255,18 @@ export class ValueLabels {
         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 };
+        // Only a label that can sit at the plot's right end - any but a first point's - reaches that edge.
+        const selects = state.labelSelects ?? [];
+        const atRight = selects.length === 0 || selects.some((select) => select !== 'first');
+        // Likewise a label set before its point reaches the left edge only from a point that can sit there: any but a last one - or a last one that is also the first, of a series with a single point.
+        const atLeft = selects.length === 0 ||
+            selects.some((select) => select !== 'last') ||
+            series.some((s) => s.data.length < 2);
         const edges = [
             'top',
             'bottom',
-            ...(dx < 0 ? ['left'] : []),
-            ...(dx >= 0 || series.length > 1 ? ['right'] : [])
+            ...(dx < 0 && atLeft ? ['left'] : []),
+            ...((dx >= 0 || series.length > 1) && atRight ? ['right'] : [])
         ];
         const texts = [];
         const domain = state.scales.y?.domain;

package/dist/layout/timeline/Timeline.svelte

@@ -15,12 +15,15 @@
 		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();
@@ -72,7 +75,7 @@
 		<Text
 			data={baseValues}
 			{...isHorizontal ? { x: identity, y: 0 } : { x: 0, y: identity }}
-			text={(d: TimeValue) => `${d}`}
+			text={(d: TimeValue) => format(d)}
 			{...textOffset}
 			fontSize={rule.fontSize}
 			fill="var(--dct-timeline-axis, currentColor)"
@@ -82,7 +85,7 @@
 		<Text
 			data={[currentValue]}
 			{...isHorizontal ? { x: identity, y: 0 } : { x: 0, y: identity }}
-			text={(d: TimeValue) => `${d}`}
+			text={(d: TimeValue) => format(d)}
 			{...textOffset}
 			fontSize={rule.activeFontSize}
 			fontWeight={rule.activeFontWeight}

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/TimelineLayout.svelte

@@ -1,11 +1,13 @@
 <script lang="ts" generics="TRow extends Record<string, unknown>">
 	import { untrack } from 'svelte';
-	import { resolveAccessor } from '../../plots/utils/accessors';
+	import { resolveAccessor } from '../../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
@@ -22,6 +24,7 @@
 	let {
 		data,
 		accessor,
+		dateFormat,
 		progress,
 		values,
 		orientation = 'vertical',
@@ -35,28 +38,44 @@
 		child
 	}: {
 		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, whenever they change - for whoever else draws or drives the timeline. */
-		onsteps?: (values: TimeValue[]) => void;
+		/** 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(TimelineSteps.of(values, data, getTime));
+	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)));
 
 	$effect(() => {
 		const found = steps.values;
-		untrack(() => onsteps?.(found));
+		const dates = temporal;
+		untrack(() => onsteps?.(found, dates));
 	});
 
 	const progressEasingFn = $derived(Interpolation.buildEasing(interpolate?.progressEasing));
@@ -77,12 +96,19 @@
 			);
 			return upper;
 		}
-		return { ...upper, [accessor]: x, [valueField]: value } as TRow;
+		return {
+			...upper,
+			[accessor]: time.toValueLike(x, upper[accessor]),
+			[valueField]: value
+		} as TRow;
 	}
 
 	const filtered = $derived.by(() => {
 		const discrete = () =>
-			data.filter((d) => TimelineSteps.matches(getTime(d), selectedValue, filterMode));
+			data.filter((d) => {
+				const at = getTime(d);
+				return at === undefined || TimelineSteps.matches(at, selectedValue, filterMode);
+			});
 
 		if (!interpolate) return discrete();
 		if (!interpolate.value) {
@@ -96,14 +122,14 @@
 		const getValue = resolveAccessor<TRow>(interpolate.value) as (d: TRow) => number;
 		const create = interpolate.create ?? defaultCreate;
 
-		const groups = Map.groupBy(data, (row) => String(getKey(row)));
+		const groups = Map.groupBy(timed, (row) => String(getKey(row)));
 
-		const result: TRow[] = [];
+		const result: TRow[] = [...untimed];
 		for (const rows of groups.values()) {
 			const tweened = Interpolation.tweenSeries({
 				rows,
 				x: currentTime,
-				getTime,
+				getTime: getTime as (row: TRow) => TimeValue,
 				getValue,
 				create,
 				segmentEasing: segmentEasingFn

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

@@ -1,18 +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, whenever they change - for whoever else draws or drives the timeline. */
-        onsteps?: (values: TimeValue[]) => void;
+        /** Told the steps, and whether they are dates, when they change. */
+        onsteps?: (values: TimeValue[], temporal: boolean) => void;
         width: number;
         height: number;
         child: TimelineChildSnippet<TRow>;

package/dist/layout/timeline/TimelineRule.svelte

@@ -28,6 +28,7 @@
 			<Timeline
 				currentValue={timeline.value}
 				values={timeline.steps}
+				format={timeline.format}
 				orientation={timeline.orientation}
 				width={measuredWidth}
 				height={measuredHeight}

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

@@ -1,10 +1,12 @@
-import type { PlayerConfig, PlayerControl, Orientation, TimeValue, TimelineCallbacks, TimelineType } from '../../types/layout/timeline';
+import type { PlayerConfig, PlayerControl, Orientation, TimeInput, TimeValue, TimelineStep, TimelineCallbacks, TimelineType } from '../../types/layout/timeline';
 /** What a {@link TimelineState} reads from the timeline's owner, each time it needs it. */
 export type TimelineSettings = TimelineCallbacks & {
     type?: TimelineType;
     player?: PlayerConfig;
     progress?: number;
-    values?: TimeValue[];
+    values?: TimeInput[];
+    /** How a non-ISO date string in `values` reads. */
+    dateFormat?: string;
     show?: boolean;
     orientation?: Orientation;
     thickness?: number;
@@ -37,8 +39,10 @@ export declare class TimelineState {
     get shown(): boolean;
     /** The steps it moves across, ascending: the owner's `values`, else those its plots report. */
     get steps(): TimeValue[];
-    /** Reports the steps the plots found in their rows. */
-    setSteps(values: TimeValue[]): void;
+    /** Whether the steps are dates. */
+    get temporal(): boolean;
+    /** Reports the steps the plots found in their rows, and whether they are dates. */
+    setSteps(values: TimeValue[], temporal?: boolean): void;
     /** The position across the steps, `0`-`1`. */
     get progress(): number;
     /** The step the position lands on, as an index; `-1` without steps. */
@@ -55,8 +59,12 @@ export declare class TimelineState {
     get speeds(): number[];
     /** Milliseconds each step lasts at speed `1`. */
     get stepDuration(): number;
-    /** How the current step reads. */
+    /** How a step reads: the player's `format`, else a date label or the number. */
     get format(): (value: TimeValue) => string;
+    /** A step as authors see it. */
+    step(value: TimeValue): TimelineStep;
+    /** An author's step as the timeline's own, or `undefined` when it reads as none. */
+    timeOf(value: TimeInput): TimeValue | undefined;
     /** Moves to `progress` (`0`-`1`), and tells the owner. */
     seek(progress: number): void;
     /** Moves to the step at `index`. */

package/dist/layout/timeline/TimelineState.svelte.js

@@ -1,6 +1,7 @@
 import { getContext, setContext, untrack } from 'svelte';
 import { getConfiguration } from '../../configuration/config.svelte';
 import { TimelineSteps } from './TimelineSteps';
+import { TimelineTime } from './TimelineTime';
 const TIMELINE_KEY = Symbol('dct-timeline');
 /** The longest a frame counts for while playing, so a hidden tab doesn't jump ahead when it comes back. */
 const MAX_FRAME_MS = 250;
@@ -17,6 +18,7 @@ const MAX_FRAME_MS = 250;
 export class TimelineState {
     #settings;
     #steps = $state([]);
+    #temporal = $state(false);
     #own = $state(null);
     #playing = $state(false);
     #loop = $state(false);
@@ -58,14 +60,33 @@ export class TimelineState {
     }
     /** The steps it moves across, ascending: the owner's `values`, else those its plots report. */
     get steps() {
-        const values = this.#settings()?.values;
-        return values?.length ? new TimelineSteps(values).values : this.#steps;
-    }
-    /** Reports the steps the plots found in their rows. */
-    setSteps(values) {
+        const values = this.#ownerValues;
+        return values ? new TimelineSteps(values).values : this.#steps;
+    }
+    /** Whether the steps are dates. */
+    get temporal() {
+        const settings = this.#settings();
+        if (!settings?.values?.length)
+            return this.#temporal;
+        return new TimelineTime(settings.dateFormat).isTemporal(settings.values);
+    }
+    /** Reports the steps the plots found in their rows, and whether they are dates. */
+    setSteps(values, temporal = false) {
         const same = values.length === this.#steps.length && values.every((v, i) => v === this.#steps[i]);
         if (!same)
             this.#steps = values;
+        if (temporal !== this.#temporal)
+            this.#temporal = temporal;
+    }
+    /** The owner's `values` as steps, or `undefined` without any. */
+    get #ownerValues() {
+        const settings = this.#settings();
+        if (!settings?.values?.length)
+            return undefined;
+        const time = new TimelineTime(settings.dateFormat);
+        return settings.values
+            .map((value) => time.toTime(value))
+            .filter((value) => value !== undefined);
     }
     /** The position across the steps, `0`-`1`. */
     get progress() {
@@ -103,9 +124,22 @@ export class TimelineState {
     get stepDuration() {
         return (this.#settings()?.player?.stepDuration ?? getConfiguration().timeline.player.stepDuration);
     }
-    /** How the current step reads. */
+    /** How a step reads: the player's `format`, else a date label or the number. */
     get format() {
-        return this.#settings()?.player?.format ?? ((value) => String(value));
+        const own = this.#settings()?.player?.format;
+        if (own)
+            return (value) => own(this.step(value));
+        if (this.temporal)
+            return TimelineTime.dateLabel(this.steps, getConfiguration().axis.locale);
+        return (value) => String(value);
+    }
+    /** A step as authors see it. */
+    step(value) {
+        return TimelineTime.toStep(value, this.temporal);
+    }
+    /** An author's step as the timeline's own, or `undefined` when it reads as none. */
+    timeOf(value) {
+        return new TimelineTime(this.#settings()?.dateFormat).toTime(value);
     }
     /** Moves to `progress` (`0`-`1`), and tells the owner. */
     seek(progress) {
@@ -196,7 +230,7 @@ export class TimelineState {
             const value = this.value;
             untrack(() => {
                 if (last !== undefined && value !== undefined && value !== last) {
-                    this.#settings()?.onvalue?.(value);
+                    this.#settings()?.onvalue?.(this.step(value));
                 }
                 last = value;
             });

package/dist/layout/timeline/TimelineTime.d.ts

@@ -0,0 +1,18 @@
+import type { TimeValue, TimelineStep } from '../../types/layout/timeline';
+/** Reads a timeline's values (numbers, `Date`s, ISO or `dateFormat` strings) as numeric steps, and back. */
+export declare class TimelineTime {
+    #private;
+    readonly dateFormat?: string | undefined;
+    /** @param dateFormat How a non-ISO date string reads, e.g. `'DD/MM/YYYY'`. */
+    constructor(dateFormat?: string | undefined);
+    /** A value as its step, or `undefined` when it reads as none. */
+    toTime(value: unknown): TimeValue | undefined;
+    /** A step as authors see it: a `Date` when `temporal`, else the number. */
+    static toStep(value: TimeValue, temporal: boolean): TimelineStep;
+    /** Whether `values` hold dates rather than plain numbers. */
+    isTemporal(values: unknown[]): boolean;
+    /** A step written back in the same form as `like`, for interpolated rows. */
+    toValueLike(time: TimeValue, like: unknown): unknown;
+    /** A date label as precise as the steps need: year, month, day or time. */
+    static dateLabel(steps: TimeValue[], locale?: string): (time: TimeValue) => string;
+}

package/dist/layout/timeline/TimelineTime.js

@@ -0,0 +1,117 @@
+/** The `dateFormat` tokens and the UTC date part each reads or writes. */
+const TOKENS = {
+    YYYY: { group: '(\\d{4})', get: (date) => date.getUTCFullYear(), width: 4 },
+    MM: { group: '(\\d{1,2})', get: (date) => date.getUTCMonth() + 1, width: 2 },
+    DD: { group: '(\\d{1,2})', get: (date) => date.getUTCDate(), width: 2 },
+    HH: { group: '(\\d{1,2})', get: (date) => date.getUTCHours(), width: 2 },
+    mm: { group: '(\\d{1,2})', get: (date) => date.getUTCMinutes(), width: 2 },
+    ss: { group: '(\\d{1,2})', get: (date) => date.getUTCSeconds(), width: 2 }
+};
+const TOKEN_PATTERN = /YYYY|MM|DD|HH|mm|ss/g;
+/** An ISO 8601 date, from a bare year to a full date-time. */
+const ISO_DATE = /^\d{4}(-\d{2}(-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?)?)?$/;
+const DAY = 24 * 60 * 60 * 1000;
+/** Reads a timeline's values (numbers, `Date`s, ISO or `dateFormat` strings) as numeric steps, and back. */
+export class TimelineTime {
+    dateFormat;
+    /** @param dateFormat How a non-ISO date string reads, e.g. `'DD/MM/YYYY'`. */
+    constructor(dateFormat) {
+        this.dateFormat = dateFormat;
+    }
+    /** A value as its step, or `undefined` when it reads as none. */
+    toTime(value) {
+        if (typeof value === 'number')
+            return Number.isFinite(value) ? value : undefined;
+        if (value instanceof Date) {
+            const time = value.getTime();
+            return Number.isFinite(time) ? time : undefined;
+        }
+        if (typeof value !== 'string')
+            return undefined;
+        const text = value.trim();
+        if (this.dateFormat) {
+            const parsed = TimelineTime.#parse(text, this.dateFormat);
+            if (parsed !== undefined)
+                return parsed;
+        }
+        if (text !== '' && Number.isFinite(Number(text)) && !ISO_DATE.test(text))
+            return Number(text);
+        if (ISO_DATE.test(text)) {
+            // A bare year stays a year, like a number.
+            if (/^\d{4}$/.test(text))
+                return Number(text);
+            const time = Date.parse(/^\d{4}-\d{2}$/.test(text) ? `${text}-01` : text);
+            return Number.isFinite(time) ? time : undefined;
+        }
+        return undefined;
+    }
+    /** A step as authors see it: a `Date` when `temporal`, else the number. */
+    static toStep(value, temporal) {
+        return temporal ? new Date(value) : value;
+    }
+    /** Whether `values` hold dates rather than plain numbers. */
+    isTemporal(values) {
+        return values.some((value) => {
+            if (value instanceof Date)
+                return true;
+            if (typeof value !== 'string')
+                return false;
+            const text = value.trim();
+            return !/^-?\d+(\.\d+)?$/.test(text) && this.toTime(text) !== undefined;
+        });
+    }
+    /** A step written back in the same form as `like`, for interpolated rows. */
+    toValueLike(time, like) {
+        if (like instanceof Date)
+            return new Date(time);
+        if (typeof like !== 'string')
+            return time;
+        const text = like.trim();
+        if (this.dateFormat && TimelineTime.#parse(text, this.dateFormat) !== undefined) {
+            return TimelineTime.#write(new Date(time), this.dateFormat);
+        }
+        if (ISO_DATE.test(text) && !/^\d{4}$/.test(text)) {
+            return new Date(time).toISOString().slice(0, text.length);
+        }
+        return String(time);
+    }
+    /** A date label as precise as the steps need: year, month, day or time. */
+    static dateLabel(steps, locale) {
+        const dates = steps.map((time) => new Date(time));
+        const options = dates.every((d) => d.getUTCMonth() === 0 && d.getUTCDate() === 1 && d.getTime() % DAY === 0)
+            ? { year: 'numeric' }
+            : dates.every((d) => d.getUTCDate() === 1 && d.getTime() % DAY === 0)
+                ? { month: 'short', year: 'numeric' }
+                : dates.every((d) => d.getTime() % DAY === 0)
+                    ? { day: 'numeric', month: 'short', year: 'numeric' }
+                    : { dateStyle: 'medium', timeStyle: 'short' };
+        const format = new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' });
+        return (time) => format.format(new Date(time));
+    }
+    /** `text` read through `format`, or `undefined` when it does not match. */
+    static #parse(text, format) {
+        const order = [];
+        const pattern = format
+            .split(TOKEN_PATTERN)
+            .map((literal) => literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        const tokens = format.match(TOKEN_PATTERN) ?? [];
+        let source = pattern[0];
+        tokens.forEach((token, index) => {
+            order.push(token);
+            source += TOKENS[token].group + pattern[index + 1];
+        });
+        const match = new RegExp(`^${source}$`).exec(text);
+        if (!match || !order.length)
+            return undefined;
+        const parts = { YYYY: 1970, MM: 1, DD: 1, HH: 0, mm: 0, ss: 0 };
+        order.forEach((token, index) => (parts[token] = Number(match[index + 1])));
+        return Date.UTC(parts.YYYY, parts.MM - 1, parts.DD, parts.HH, parts.mm, parts.ss);
+    }
+    /** `date` written through `format`. */
+    static #write(date, format) {
+        return format.replace(TOKEN_PATTERN, (token) => {
+            const { get, width } = TOKENS[token];
+            return String(get(date)).padStart(width, '0');
+        });
+    }
+}