@fundar/data-chart-telling 0.0.64 → 1.0.0

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

@@ -0,0 +1,226 @@
+import { getContext, setContext, untrack } from 'svelte';
+import { getConfiguration } from '../../configuration/config.svelte';
+import { TimelineSteps } from './TimelineSteps';
+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;
+/**
+ * One figure's timeline: where it is across its steps, and whether it is
+ * playing, looping and how fast. Shared by everything in the figure - the
+ * plots that slice their rows by it, the player bar that draws it, and what
+ * the user builds with `useFigure().timeline`.
+ *
+ * The position is the owner's `progress` until the player (or a reader)
+ * moves it; from then on it is theirs, until the owner's `progress` changes.
+ * Create it during component init and call {@link watch} there.
+ */
+export class TimelineState {
+    #settings;
+    #steps = $state([]);
+    #own = $state(null);
+    #playing = $state(false);
+    #loop = $state(false);
+    #speed = $state(1);
+    constructor(settings) {
+        this.#settings = settings;
+        untrack(() => {
+            this.#loop = settings()?.player?.loop ?? false;
+            this.#speed = settings()?.player?.speed ?? 1;
+        });
+    }
+    /** The enclosing figure's timeline, or `null` outside one. Call during component init. */
+    static current() {
+        return getContext(TIMELINE_KEY) ?? null;
+    }
+    /** Makes `state` the timeline of everything below. Call during component init. */
+    static provide(state) {
+        setContext(TIMELINE_KEY, state);
+        return state;
+    }
+    /** Whether its owner set a timeline at all. */
+    get enabled() {
+        return this.#settings() !== undefined;
+    }
+    get type() {
+        return this.#settings()?.type ?? 'player';
+    }
+    /** Which way a `'rule'` runs; a `'player'` is always horizontal. */
+    get orientation() {
+        return this.type === 'player' ? 'horizontal' : (this.#settings()?.orientation ?? 'vertical');
+    }
+    /** How much room a `'rule'` takes across, in px. */
+    get thickness() {
+        return this.#settings()?.thickness ?? getConfiguration().timeline.thickness;
+    }
+    /** Whether the owner wants it drawn. */
+    get shown() {
+        return this.#settings()?.show !== false;
+    }
+    /** 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 same = values.length === this.#steps.length && values.every((v, i) => v === this.#steps[i]);
+        if (!same)
+            this.#steps = values;
+    }
+    /** The position across the steps, `0`-`1`. */
+    get progress() {
+        const external = this.#settings()?.progress ?? 0;
+        return this.#own && this.#own.base === external ? this.#own.value : external;
+    }
+    /** The step the position lands on, as an index; `-1` without steps. */
+    get index() {
+        const count = this.steps.length;
+        return count === 0 ? -1 : Math.min(count - 1, Math.round(this.progress * (count - 1)));
+    }
+    /** The step the position lands on, or `undefined` without steps. */
+    get value() {
+        return this.steps[this.index];
+    }
+    get playing() {
+        return this.#playing;
+    }
+    get loop() {
+        return this.#loop;
+    }
+    /** The playing speed, as a multiple of {@link stepDuration}. */
+    get speed() {
+        return this.#speed;
+    }
+    /** The controls the player bar draws, in order. */
+    get controls() {
+        return this.#settings()?.player?.controls ?? getConfiguration().timeline.player.controls;
+    }
+    /** The speeds the speed control cycles through. */
+    get speeds() {
+        return this.#settings()?.player?.speeds ?? getConfiguration().timeline.player.speeds;
+    }
+    /** Milliseconds each step lasts at speed `1`. */
+    get stepDuration() {
+        return (this.#settings()?.player?.stepDuration ?? getConfiguration().timeline.player.stepDuration);
+    }
+    /** How the current step reads. */
+    get format() {
+        return this.#settings()?.player?.format ?? ((value) => String(value));
+    }
+    /** Moves to `progress` (`0`-`1`), and tells the owner. */
+    seek(progress) {
+        const next = Math.min(1, Math.max(0, progress));
+        if (next === this.progress)
+            return;
+        this.#own = { base: this.#settings()?.progress ?? 0, value: next };
+        this.#settings()?.onprogress?.(next);
+    }
+    /** Moves to the step at `index`. */
+    seekIndex(index) {
+        const count = this.steps.length;
+        this.seek(count > 1 ? Math.min(count - 1, Math.max(0, index)) / (count - 1) : 0);
+    }
+    /** Moves to the step closest to `value`. */
+    seekValue(value) {
+        const nearest = new TimelineSteps(this.steps).nearest(value);
+        if (nearest !== undefined)
+            this.seekIndex(this.steps.indexOf(nearest));
+    }
+    next() {
+        this.seekIndex(this.index + 1);
+    }
+    previous() {
+        this.seekIndex(this.index - 1);
+    }
+    play() {
+        if (this.#playing || this.steps.length < 2)
+            return;
+        if (this.progress >= 1)
+            this.seek(0);
+        this.#playing = true;
+        this.#settings()?.player?.onplay?.(true);
+    }
+    pause() {
+        if (!this.#playing)
+            return;
+        this.#playing = false;
+        this.#settings()?.player?.onplay?.(false);
+    }
+    toggle() {
+        if (this.#playing)
+            this.pause();
+        else
+            this.play();
+    }
+    setLoop(loop) {
+        if (loop === this.#loop)
+            return;
+        this.#loop = loop;
+        this.#settings()?.player?.onloop?.(loop);
+    }
+    setSpeed(speed) {
+        if (!(speed > 0) || speed === this.#speed)
+            return;
+        this.#speed = speed;
+        this.#settings()?.player?.onspeed?.(speed);
+    }
+    /** Takes the next of `speeds` after the current one, from the first again after the last. */
+    cycleSpeed() {
+        const { speeds } = this;
+        if (speeds.length === 0)
+            return;
+        const at = speeds.indexOf(this.#speed);
+        this.setSpeed(speeds[(at + 1) % speeds.length]);
+    }
+    /**
+     * Moves the position on by `elapsed` milliseconds of playing. At the end it
+     * starts again from the first step when looping, and stops otherwise.
+     */
+    advance(elapsed) {
+        const count = this.steps.length;
+        if (!this.#playing || count < 2)
+            return;
+        const span = (this.stepDuration / this.#speed) * (count - 1);
+        const next = this.progress + Math.min(elapsed, MAX_FRAME_MS) / span;
+        if (next < 1)
+            return this.seek(next);
+        if (this.#loop)
+            return this.seek(next - 1);
+        this.seek(1);
+        this.pause();
+    }
+    /** Starts what the timeline does by itself: playing, the owner's `onvalue` and `autoplay`. Call during component init. */
+    watch() {
+        let last;
+        $effect(() => {
+            const value = this.value;
+            untrack(() => {
+                if (last !== undefined && value !== undefined && value !== last) {
+                    this.#settings()?.onvalue?.(value);
+                }
+                last = value;
+            });
+        });
+        let autoplayed = false;
+        $effect(() => {
+            if (autoplayed || this.steps.length < 2)
+                return;
+            autoplayed = true;
+            if (untrack(() => this.#settings()?.player?.autoplay))
+                untrack(() => this.play());
+        });
+        $effect(() => {
+            if (!this.#playing)
+                return;
+            let frame = 0;
+            let previous = performance.now();
+            const tick = (now) => {
+                untrack(() => this.advance(now - previous));
+                previous = now;
+                frame = requestAnimationFrame(tick);
+            };
+            frame = requestAnimationFrame(tick);
+            return () => cancelAnimationFrame(frame);
+        });
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { EasingFn } from '../../types/misc/easing';
+import type { TimeValue } from '../../types/layout/timeline';
+/**
+ * A timeline's distinct steps, ascending: where a scrubber `progress`
+ * (`0`-`1`) lands on them, the span they cover and which rows a step shows.
+ */
+export declare class TimelineSteps {
+    readonly values: TimeValue[];
+    constructor(values: Iterable<TimeValue>);
+    /** The steps the author listed in `values` or, without any, the times of `rows`. */
+    static of<TRow>(values: TimeValue[] | undefined, rows: TRow[], getTime: (row: TRow) => TimeValue): TimelineSteps;
+    /** Whether a row at time `value` shows in `step`: at it, or up to it. */
+    static matches(value: unknown, step: TimeValue, mode?: 'exact' | 'upTo'): boolean;
+    get first(): TimeValue | undefined;
+    get last(): TimeValue | undefined;
+    /** The first and last step - empty without any. */
+    get domain(): TimeValue[];
+    /** The step a scrubber `progress` snaps to, or `undefined` without steps. */
+    at(progress: number): TimeValue | undefined;
+    /** The continuous time `progress` is at across the steps, eased - `0` without steps. */
+    timeAt(progress: number, easing: EasingFn): number;
+    /** The step closest to `time`, or `undefined` without steps. */
+    nearest(time: number): TimeValue | undefined;
+}

package/dist/layout/timeline/TimelineSteps.js

@@ -0,0 +1,48 @@
+/**
+ * A timeline's distinct steps, ascending: where a scrubber `progress`
+ * (`0`-`1`) lands on them, the span they cover and which rows a step shows.
+ */
+export class TimelineSteps {
+    values;
+    constructor(values) {
+        this.values = [...new Set(values)].sort((a, b) => a - b);
+    }
+    /** The steps the author listed in `values` or, without any, the times of `rows`. */
+    static of(values, rows, getTime) {
+        return new TimelineSteps(values?.length ? values : rows.map(getTime));
+    }
+    /** Whether a row at time `value` shows in `step`: at it, or up to it. */
+    static matches(value, step, mode = 'exact') {
+        return mode === 'upTo' ? Number(value) <= step : Number(value) === step;
+    }
+    get first() {
+        return this.values[0];
+    }
+    get last() {
+        return this.values[this.values.length - 1];
+    }
+    /** The first and last step - empty without any. */
+    get domain() {
+        const { first, last } = this;
+        return first === undefined || last === undefined ? [] : [first, last];
+    }
+    /** The step a scrubber `progress` snaps to, or `undefined` without steps. */
+    at(progress) {
+        const { values } = this;
+        if (!values.length)
+            return undefined;
+        const index = Math.round(progress * (values.length - 1));
+        return values[Math.min(values.length - 1, Math.max(0, index))];
+    }
+    /** The continuous time `progress` is at across the steps, eased - `0` without steps. */
+    timeAt(progress, easing) {
+        const { first, last } = this;
+        if (first === undefined || last === undefined)
+            return 0;
+        return first + (last - first) * easing(progress);
+    }
+    /** The step closest to `time`, or `undefined` without steps. */
+    nearest(time) {
+        return this.values.reduce((best, step) => best === undefined || Math.abs(step - time) < Math.abs(best - time) ? step : best, undefined);
+    }
+}

package/dist/layout/tooltip/Tooltip.svelte

@@ -1,95 +1,92 @@
-<script lang="ts">
-  import type { Snippet } from 'svelte';
-  import { resolveTooltipPlacement } from './resolveTooltipPlacement';
-  import type { TooltipAnchorX, TooltipAnchorY } from '../../types/layout/tooltip';
+<script lang="ts" generics="TRow extends Record<string, unknown>">
+	import type { Snippet } from 'svelte';
+	import { TooltipState } from './TooltipState.svelte';
+	import type { TooltipAnchorX, TooltipAnchorY } from '../../types/layout/tooltip';
 
-  /**
-   * Presentational tooltip positioned at `(x, y)` within a `position: relative`
-   * parent. It is styled entirely from the `--dct-tooltip-*` variables that
-   * {@link ChartContainer} stamps from the config, so it themes for free. Plots
-   * that implement hovering can render this with their own content snippet.
-   *
-   * Placement is boundary-aware: it prefers sitting `anchorX`/`anchorY` of the
-   * point (default: to the right and below — clear of the cursor so the
-   * tooltip never covers what's being hovered), falling back toward the
-   * opposite side (via the centered position) when the preferred side would
-   * overflow the `bounds` box — see `resolveTooltipPlacement`.
-   */
-  let {
-    x,
-    y,
-    visible = true,
-    background,
-    color,
-    bounds,
-    plain = false,
-    anchorX = 'right',
-    anchorY = 'bottom',
-    children,
-  }: {
-    x: number;
-    y: number;
-    visible?: boolean;
-    background?: string;
-    color?: string;
-    /** Box the tooltip must stay within — usually the hosting plot's width/height. */
-    bounds?: { width: number; height: number };
-    /**
-     * Drops the default dark box (background/padding/border) so a custom
-     * `content` snippet fully owns its own look. Set whenever the caller
-     * supplies `content` — the drop shadow and border radius still apply,
-     * so a custom card can match its own corners via `--dct-tooltip-radius`.
-     */
-    plain?: boolean;
-    /** Preferred horizontal anchor relative to the cursor. Defaults to `'right'`. */
-    anchorX?: TooltipAnchorX;
-    /** Preferred vertical anchor relative to the cursor. Defaults to `'bottom'`. */
-    anchorY?: TooltipAnchorY;
-    children: Snippet;
-  } = $props();
+	/**
+	 * A plot's floating tooltip at `(x, y)`, inside a `position: relative`
+	 * parent and themed by the `--dct-tooltip-*` variables. It reads the rows
+	 * the hover matched: its own `content` snippet, given every row, or each
+	 * row's `format` text, one per line. It sits at `anchorX`/`anchorY` of the
+	 * point (default right and below) and moves over where it would leave its
+	 * plot's box - or `bounds`, when given. See {@link TooltipState}.
+	 */
+	let {
+		visible,
+		x,
+		y,
+		rows,
+		format,
+		content,
+		bounds,
+		anchorX = 'right',
+		anchorY = 'bottom',
+		background,
+		color
+	}: {
+		visible: boolean;
+		x: number;
+		y: number;
+		/** Every row the hover matched. */
+		rows: TRow[];
+		format: (row: TRow) => string;
+		/** Custom tooltip body, given every row; replaces the `format` text and the default box. */
+		content?: Snippet<[{ rows: TRow[] }]>;
+		/** Box the tooltip must stay within. Defaults to its plot's box. */
+		bounds?: { width: number; height: number };
+		/** Preferred horizontal side of the point. Defaults to `'right'`. */
+		anchorX?: TooltipAnchorX;
+		/** Preferred vertical side of the point. Defaults to `'bottom'`. */
+		anchorY?: TooltipAnchorY;
+		background?: string;
+		color?: string;
+	} = $props();
 
-  let boxWidth = $state(0);
-  let boxHeight = $state(0);
-
-  const placement = $derived(
-    resolveTooltipPlacement({ x, y, boxWidth, boxHeight, bounds, anchorX, anchorY }),
-  );
+	const tooltip = new TooltipState({
+		point: () => ({ x, y }),
+		anchor: () => ({ x: anchorX, y: anchorY }),
+		bounds: () => bounds
+	});
 </script>
 
 {#if visible}
-  <div
-    class="dct-tooltip"
-    class:dct-tooltip--plain={plain}
-    bind:clientWidth={boxWidth}
-    bind:clientHeight={boxHeight}
-    style:left="{placement.left}px"
-    style:top="{placement.top}px"
-    style:background={background}
-    style:color={color}
-  >
-    {@render children()}
-  </div>
+	<div
+		class="dct-tooltip"
+		class:dct-tooltip--plain={!!content}
+		bind:clientWidth={tooltip.width}
+		bind:clientHeight={tooltip.height}
+		style:left="{tooltip.box.left}px"
+		style:top="{tooltip.box.top}px"
+		style:background
+		style:color
+	>
+		{#if content}
+			{@render content({ rows })}
+		{:else}
+			{TooltipState.text(rows, format)}
+		{/if}
+	</div>
 {/if}
 
 <style>
-  .dct-tooltip {
-    position: absolute;
-    z-index: 10;
-    pointer-events: none;
-    background: var(--dct-tooltip-bg, #111827);
-    color: var(--dct-tooltip-color, #fff);
-    font-size: var(--dct-tooltip-size, 0.8125rem);
-    padding: var(--dct-tooltip-pad, 0.5rem 0.75rem);
-    border-radius: var(--dct-tooltip-radius, 0.375rem);
-    border: var(--dct-tooltip-border, none);
-    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.18);
-    white-space: pre-line;
-    line-height: 1.35;
-  }
+	.dct-tooltip {
+		position: absolute;
+		z-index: 10;
+		pointer-events: none;
+		background: var(--dct-tooltip-bg, #111827);
+		color: var(--dct-tooltip-color, #fff);
+		font-size: var(--dct-tooltip-size, 0.8125rem);
+		padding: var(--dct-tooltip-pad, 0.5rem 0.75rem);
+		border-radius: var(--dct-tooltip-radius, 0.375rem);
+		border: var(--dct-tooltip-border, none);
+		box-shadow: 0 2px 8px rgba(0, 0, 0, 0.18);
+		white-space: pre-line;
+		line-height: 1.35;
+	}
 
-  .dct-tooltip--plain {
-    background: transparent;
-    padding: 0;
-    border: none;
-  }
+	.dct-tooltip--plain {
+		background: transparent;
+		padding: 0;
+		border: none;
+	}
 </style>

package/dist/layout/tooltip/Tooltip.svelte.d.ts

@@ -1,29 +1,48 @@
 import type { Snippet } from 'svelte';
 import type { TooltipAnchorX, TooltipAnchorY } from '../../types/layout/tooltip';
-type $$ComponentProps = {
-    x: number;
-    y: number;
-    visible?: boolean;
-    background?: string;
-    color?: string;
-    /** Box the tooltip must stay within — usually the hosting plot's width/height. */
-    bounds?: {
-        width: number;
-        height: number;
+declare function $$render<TRow extends Record<string, unknown>>(): {
+    props: {
+        visible: boolean;
+        x: number;
+        y: number;
+        /** Every row the hover matched. */
+        rows: TRow[];
+        format: (row: TRow) => string;
+        /** Custom tooltip body, given every row; replaces the `format` text and the default box. */
+        content?: Snippet<[{
+            rows: TRow[];
+        }]>;
+        /** Box the tooltip must stay within. Defaults to its plot's box. */
+        bounds?: {
+            width: number;
+            height: number;
+        };
+        /** Preferred horizontal side of the point. Defaults to `'right'`. */
+        anchorX?: TooltipAnchorX;
+        /** Preferred vertical side of the point. Defaults to `'bottom'`. */
+        anchorY?: TooltipAnchorY;
+        background?: string;
+        color?: string;
     };
-    /**
-     * Drops the default dark box (background/padding/border) so a custom
-     * `content` snippet fully owns its own look. Set whenever the caller
-     * supplies `content` — the drop shadow and border radius still apply,
-     * so a custom card can match its own corners via `--dct-tooltip-radius`.
-     */
-    plain?: boolean;
-    /** Preferred horizontal anchor relative to the cursor. Defaults to `'right'`. */
-    anchorX?: TooltipAnchorX;
-    /** Preferred vertical anchor relative to the cursor. Defaults to `'bottom'`. */
-    anchorY?: TooltipAnchorY;
-    children: Snippet;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
 };
-declare const Tooltip: import("svelte").Component<$$ComponentProps, {}, "">;
-type Tooltip = ReturnType<typeof Tooltip>;
+declare class __sveltets_Render<TRow extends Record<string, unknown>> {
+    props(): ReturnType<typeof $$render<TRow>>['props'];
+    events(): ReturnType<typeof $$render<TRow>>['events'];
+    slots(): ReturnType<typeof $$render<TRow>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TRow extends Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TRow>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TRow>['props']>, ReturnType<__sveltets_Render<TRow>['events']>, ReturnType<__sveltets_Render<TRow>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TRow>['bindings']>;
+    } & ReturnType<__sveltets_Render<TRow>['exports']>;
+    <TRow extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TRow>['props']> & {}): ReturnType<__sveltets_Render<TRow>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Tooltip: $$IsomorphicComponent;
+type Tooltip<TRow extends Record<string, unknown>> = InstanceType<typeof Tooltip<TRow>>;
 export default Tooltip;

package/dist/layout/tooltip/TooltipState.svelte.d.ts

@@ -0,0 +1,61 @@
+import { Box } from '../margins/Box';
+import type { PlotAxes } from '../../phases/data/PlotAxes';
+import type { ProcessedData, ProcessedRow } from '../../types/phases';
+import type { TooltipAnchorX, TooltipAnchorY } from '../../types/layout/tooltip';
+import type { Series } from '../../types/plots/data/common';
+/** What a tooltip is shown from, each read reactively. */
+export type TooltipInputs = {
+    /** The point it sits beside. */
+    point: () => {
+        x: number;
+        y: number;
+    };
+    /** The side of the point it prefers, per axis. */
+    anchor: () => {
+        x: TooltipAnchorX;
+        y: TooltipAnchorY;
+    };
+    /** The box it must stay within. Unset, its plot's. */
+    bounds: () => {
+        width: number;
+        height: number;
+    } | undefined;
+};
+/**
+ * One tooltip: how big it rendered (`width`, `height`, bound to its element),
+ * where that puts it (`box`) - beside its point on its preferred side, moving
+ * over where it would leave its plot's box, as the plot's {@link PlotMargins}
+ * places it - and how its rows read. Its statics are the text a plot's
+ * default tooltip reads. Create it during component init.
+ */
+export declare class TooltipState {
+    #private;
+    width: number;
+    height: number;
+    constructor(inputs: TooltipInputs);
+    /** Where the tooltip sits. */
+    readonly box: Box;
+    /** The text `rows` read as through `format`, one line each. */
+    static text<TRow>(rows: TRow[], format: (row: TRow) => string): string;
+    /** A value as plain text: a date as a locale date, anything else as itself. */
+    static value(value: unknown): string;
+    /**
+     * How a hovered row reads by default, on every plot: its series, when the
+     * plot groups its rows; then where it sits - `category: value` when one
+     * axis is a band of categories (the row's own value, as its series reads
+     * it), else `x: y` as the transforms left them; then the value its color
+     * shows, when that is a number (a heatmap's cells).
+     */
+    static default(state: {
+        processedData?: ProcessedData;
+        resolvedSeries?: Series<Record<string, unknown>>[];
+        channels?: {
+            grouping?: unknown;
+            color?: {
+                accessor: (row: never) => unknown;
+                source?: unknown;
+            };
+        };
+        axes?: PlotAxes;
+    }): (row: ProcessedRow) => string;
+}