@fundar/data-chart-telling 0.0.1

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

@@ -0,0 +1,11 @@
+import type { Orientation, TimeValue } from '../../types/charts/common';
+type $$ComponentProps = {
+    currentValue: TimeValue;
+    values: TimeValue[];
+    orientation?: Orientation;
+    width: number;
+    height: number;
+};
+declare const Timeline: import("svelte").Component<$$ComponentProps, {}, "">;
+type Timeline = ReturnType<typeof Timeline>;
+export default Timeline;

package/dist/layout/timeline/TimelineLayout.svelte

@@ -0,0 +1,181 @@
+<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/charts/common';
+  import type { Accessor } from '../../types/plots/common';
+
+  /**
+   * 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',
+    thickness = 60,
+    filterMode = 'exact',
+    interpolate,
+    width,
+    height,
+    child,
+  }: {
+    data: TRow[];
+    accessor: Accessor<TRow, TimeValue>;
+    progress: number;
+    values?: TimeValue[];
+    orientation?: Orientation;
+    thickness?: number;
+    filterMode?: 'exact' | 'upTo';
+    interpolate?: TimelineInterpolation<TRow>;
+    width: number;
+    height: number;
+    child: TimelineChildSnippet<TRow>;
+  } = $props();
+
+  const getTime = $derived(resolveAccessor<TRow>(accessor));
+
+  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 progressEasingFn = $derived(resolveEasing(interpolate?.progressEasing));
+  const segmentEasingFn = $derived(resolveEasing(interpolate?.segmentEasing));
+
+  /** 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 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];
+  });
+
+  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 filtered = $derived.by(() => {
+    const discrete = () =>
+      filterMode === 'upTo'
+        ? data.filter((d) => getTime(d) <= selectedValue)
+        : data.filter((d) => getTime(d) === selectedValue);
+
+    if (!interpolate) return discrete();
+    if (!interpolate.value) {
+      console.warn('TimelineLayout: `interpolate.value` is required to tween — falling back to discrete filtering.');
+      return discrete();
+    }
+
+    const getKey = resolveAccessor<TRow>(interpolate.key ?? (() => '__all__'));
+    const getValue = resolveAccessor<TRow>(interpolate.value) as (d: TRow) => number;
+    const create = interpolate.create ?? defaultCreate;
+
+    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 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 isVertical = $derived(orientation === 'vertical');
+  const gap = 12;
+  const innerWidth = $derived(
+    Math.max(0, isVertical ? width - thickness - gap : width),
+  );
+  const innerHeight = $derived(
+    Math.max(0, isVertical ? height : height - thickness - gap),
+  );
+</script>
+
+{#if isVertical}
+  <div class="dct-timeline dct-timeline--vertical" style:width="{width}px" style:height="{height}px">
+    <div class="dct-timeline__plot">
+      {@render child({ selectedValue, data: filtered, width: innerWidth, height: innerHeight })}
+    </div>
+    <div class="dct-timeline__gutter" style:width="{thickness}px">
+      <Timeline currentValue={selectedValue} values={steps} orientation="vertical" width={thickness} height={innerHeight} />
+    </div>
+  </div>
+{:else}
+  <div class="dct-timeline dct-timeline--horizontal" style:width="{width}px" style:height="{height}px">
+    <div class="dct-timeline__plot">
+      {@render child({ selectedValue, data: filtered, width: innerWidth, height: innerHeight })}
+    </div>
+    <div class="dct-timeline__gutter" style:height="{thickness}px">
+      <Timeline currentValue={selectedValue} values={steps} orientation="horizontal" width={innerWidth} height={thickness} />
+    </div>
+  </div>
+{/if}
+
+<style>
+  .dct-timeline {
+    display: flex;
+  }
+  .dct-timeline--vertical {
+    flex-direction: row;
+    gap: 12px;
+  }
+  .dct-timeline--horizontal {
+    flex-direction: column;
+    gap: 12px;
+  }
+  .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>

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

@@ -0,0 +1,38 @@
+import type { Orientation, TimeValue, TimelineChildSnippet, TimelineInterpolation } from '../../types/charts/common';
+import type { Accessor } from '../../types/plots/common';
+declare function $$render<TRow extends Record<string, unknown>>(): {
+    props: {
+        data: TRow[];
+        accessor: Accessor<TRow, TimeValue>;
+        progress: number;
+        values?: TimeValue[];
+        orientation?: Orientation;
+        thickness?: number;
+        filterMode?: "exact" | "upTo";
+        interpolate?: TimelineInterpolation<TRow>;
+        width: number;
+        height: number;
+        child: TimelineChildSnippet<TRow>;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+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 TimelineLayout: $$IsomorphicComponent;
+type TimelineLayout<TRow extends Record<string, unknown>> = InstanceType<typeof TimelineLayout<TRow>>;
+export default TimelineLayout;

package/dist/layout/tooltip/Tooltip.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  /**
+   * 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.
+   */
+  let {
+    x,
+    y,
+    visible = true,
+    background,
+    color,
+    children,
+  }: {
+    x: number;
+    y: number;
+    visible?: boolean;
+    background?: string;
+    color?: string;
+    children: Snippet;
+  } = $props();
+</script>
+
+{#if visible}
+  <div
+    class="dct-tooltip"
+    style:left="{x}px"
+    style:top="{y}px"
+    style:background={background}
+    style:color={color}
+  >
+    {@render children()}
+  </div>
+{/if}
+
+<style>
+  .dct-tooltip {
+    position: absolute;
+    z-index: 10;
+    transform: translate(-50%, -110%);
+    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;
+  }
+</style>

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

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    x: number;
+    y: number;
+    visible?: boolean;
+    background?: string;
+    color?: string;
+    children: Snippet;
+};
+declare const Tooltip: import("svelte").Component<$$ComponentProps, {}, "">;
+type Tooltip = ReturnType<typeof Tooltip>;
+export default Tooltip;

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

@@ -0,0 +1,52 @@
+import type { HoverStore, HoverPoint } from '../../types/layout/tooltip';
+import type { AxisValue } from '../../types/plots/common';
+/**
+ * The plot-agnostic hover state machine shared by every plot. Given reactive
+ * accessors for the current hover store, this facet's id, and the local points,
+ * it produces everything a plot needs to render: the highlight points, the
+ * crosshair rule positions, and the floating-tooltip state — plus the event
+ * handlers that feed (and broadcast to) the shared store.
+ *
+ * Kept generic so line / bar / heatmap reuse it unchanged; only the points and
+ * accessors they pass in differ.
+ */
+export declare function createHoverController<T extends Record<string, unknown>>(args: {
+    hover: () => HoverStore;
+    facetId: () => string;
+    points: () => HoverPoint<T>[];
+    getX: () => (d: T) => AxisValue;
+    getY: () => (d: T) => AxisValue;
+    /** Short label drawn next to the highlight dot (e.g. the value). */
+    label: () => (row: T) => string;
+    format: () => (row: T) => string;
+    /** Named subset of series the tooltip text/content should be limited to. */
+    seriesFilter?: () => string[] | undefined;
+    /** This facet's own box, used to convert the cursor to/from a sync-broadcast fraction. */
+    width: () => number;
+    height: () => number;
+}): {
+    onPointer: (data: T[]) => void;
+    onMove: (e: PointerEvent) => void;
+    onLeave: () => void;
+    readonly points: {
+        x: AxisValue;
+        y: AxisValue;
+        label: string;
+        series: string | undefined;
+    }[];
+    readonly matchedRows: HoverPoint<T>[];
+    readonly ruleX: AxisValue | null;
+    readonly ruleY: AxisValue | null;
+    readonly impliesRuleX: boolean;
+    readonly impliesRuleY: boolean;
+    readonly showTooltip: boolean;
+    readonly tooltipText: string;
+    readonly tooltipPosition: {
+        x: number;
+        y: number;
+    } | null;
+    readonly cursor: {
+        x: number;
+        y: number;
+    } | null;
+};

package/dist/layout/tooltip/controller.svelte.js

@@ -0,0 +1,128 @@
+import { eq, matchByStrategy, impliesRuleX, impliesRuleY, filterBySeries, } from './utils';
+/**
+ * The plot-agnostic hover state machine shared by every plot. Given reactive
+ * accessors for the current hover store, this facet's id, and the local points,
+ * it produces everything a plot needs to render: the highlight points, the
+ * crosshair rule positions, and the floating-tooltip state — plus the event
+ * handlers that feed (and broadcast to) the shared store.
+ *
+ * Kept generic so line / bar / heatmap reuse it unchanged; only the points and
+ * accessors they pass in differ.
+ */
+export function createHoverController(args) {
+    let cursor = $state(null);
+    // svelteplot's `Pointer` hands back cloned rows (not the original
+    // references), so a row's series can't be looked up by identity — find it
+    // by value against the locally-known, already-tagged points instead.
+    const seriesForRow = (row) => {
+        const x = args.getX()(row);
+        const y = args.getY()(row);
+        return args.points().find((p) => eq(p.x, x) && eq(p.y, y))?.series;
+    };
+    // Points matched in THIS facet. Non-source facets only react when sync is
+    // enabled. The strategy in the shared store determines how points are found.
+    const matched = $derived.by(() => {
+        const h = args.hover();
+        const isSource = h.source === args.facetId();
+        if (!isSource && !h.sync)
+            return [];
+        return matchByStrategy(args.points(), h);
+    });
+    const matchedRows = $derived(filterBySeries(matched, args.seriesFilter?.()));
+    // Points highlighted in THIS facet for the in-SVG marker — no series
+    // filtering, since that's the tooltip text's concern, not the marker's.
+    const highlight = $derived(matched.map(({ x, y, label, series }) => ({ x, y, label, series })));
+    // Raw hover position — available whenever there are matched points.
+    // PlotLayout gates actual display with impliesRuleX/Y + the marker's ruleX/Y props.
+    const ruleX = $derived(matched.length > 0 ? args.hover().activeX : null);
+    const ruleY = $derived(matched.length > 0 ? args.hover().activeY : null);
+    // Whether the current strategy implies a crosshair rule on each axis by default.
+    const _impliesRuleX = $derived(impliesRuleX(args.hover().strategy));
+    const _impliesRuleY = $derived(impliesRuleY(args.hover().strategy));
+    const showTooltip = $derived.by(() => {
+        if (matchedRows.length === 0)
+            return false;
+        const h = args.hover();
+        if (h.source === args.facetId())
+            return cursor != null;
+        return h.sync;
+    });
+    const tooltipText = $derived(matchedRows.length ? matchedRows.map((p) => args.format()(p.row)).join('\n\n') : '');
+    function onPointer(data) {
+        const h = args.hover();
+        if (data.length) {
+            h.activeX = args.getX()(data[0]);
+            h.activeY = args.getY()(data[0]);
+            h.activeSeries = seriesForRow(data[0]) ?? null;
+            h.source = args.facetId();
+        }
+        else if (h.source === args.facetId()) {
+            h.activeX = null;
+            h.activeY = null;
+            h.activeSeries = null;
+            h.source = null;
+        }
+    }
+    function onMove(e) {
+        const rect = e.currentTarget.getBoundingClientRect();
+        const x = e.clientX - rect.left;
+        const y = e.clientY - rect.top;
+        cursor = { x, y };
+        const w = args.width();
+        const h = args.height();
+        if (w > 0 && h > 0)
+            args.hover().cursorFrac = { x: x / w, y: y / h };
+    }
+    function onLeave() {
+        cursor = null;
+        const h = args.hover();
+        if (h.source === args.facetId()) {
+            h.activeX = null;
+            h.activeY = null;
+            h.activeSeries = null;
+            h.cursorFrac = null;
+            h.source = null;
+        }
+    }
+    const tooltipPosition = $derived.by(() => {
+        if (cursor)
+            return cursor;
+        const frac = args.hover().cursorFrac;
+        return frac ? { x: frac.x * args.width(), y: frac.y * args.height() } : null;
+    });
+    return {
+        onPointer,
+        onMove,
+        onLeave,
+        get points() {
+            return highlight;
+        },
+        get matchedRows() {
+            return matchedRows;
+        },
+        get ruleX() {
+            return ruleX;
+        },
+        get ruleY() {
+            return ruleY;
+        },
+        get impliesRuleX() {
+            return _impliesRuleX;
+        },
+        get impliesRuleY() {
+            return _impliesRuleY;
+        },
+        get showTooltip() {
+            return showTooltip;
+        },
+        get tooltipText() {
+            return tooltipText;
+        },
+        get tooltipPosition() {
+            return tooltipPosition;
+        },
+        get cursor() {
+            return cursor;
+        },
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { HoverStore } from '../../types/layout/tooltip';
+/** Create + register the shared hover store. Call during component init. */
+export declare function provideHover(): HoverStore;
+/** Read the shared hover store, or `null` when there is no provider. */
+export declare function getHover(): HoverStore | null;
+/** A private hover store for a plot used outside of a {@link Chart}. */
+export declare function createHover(): HoverStore;

package/dist/layout/tooltip/hover.svelte.js

@@ -0,0 +1,28 @@
+import { getContext, setContext } from 'svelte';
+const HOVER_KEY = Symbol('dct-hover');
+function blank() {
+    return {
+        activeX: null,
+        activeY: null,
+        activeSeries: null,
+        cursorFrac: null,
+        source: null,
+        strategy: 'x',
+        sync: false,
+    };
+}
+/** Create + register the shared hover store. Call during component init. */
+export function provideHover() {
+    const store = $state(blank());
+    setContext(HOVER_KEY, store);
+    return store;
+}
+/** Read the shared hover store, or `null` when there is no provider. */
+export function getHover() {
+    return getContext(HOVER_KEY) ?? null;
+}
+/** A private hover store for a plot used outside of a {@link Chart}. */
+export function createHover() {
+    const store = $state(blank());
+    return store;
+}

package/dist/layout/tooltip/utils.d.ts

@@ -0,0 +1,41 @@
+import type { AxisValue } from '../../types/plots/common';
+import type { Marker, HoverMarkerConfig } from '../../types/plots/markers';
+import type { HoverStore, HoverStrategy, HoverPoint, TooltipProp, TooltipOptions } from '../../types/layout/tooltip';
+/** Value equality that also handles `Date` (compared by timestamp). */
+export declare function eq(a: AxisValue, b: AxisValue): boolean;
+/**
+ * Given the shared hover state, return the local points that should be
+ * highlighted using the store's current strategy.
+ */
+export declare function matchByStrategy<T>(points: HoverPoint<T>[], hover: HoverStore): HoverPoint<T>[];
+/** Whether the strategy implies an x crosshair rule by default. */
+export declare function impliesRuleX(strategy: HoverStrategy): boolean;
+/** Whether the strategy implies a y crosshair rule by default. */
+export declare function impliesRuleY(strategy: HoverStrategy): boolean;
+/** Normalize the author-facing prop into a resolved object. */
+export declare function resolveTooltip<TRow extends Record<string, unknown>>(tooltip: TooltipProp<TRow> | undefined, defaultStrategy: HoverStrategy): {
+    enabled: boolean;
+    strategy: HoverStrategy;
+    sync: boolean;
+    format?: (row: TRow) => string;
+    series?: string[];
+    content?: TooltipOptions<TRow>['content'];
+};
+/**
+ * Resolve the strategy that should drive the shared hover store:
+ * the tooltip's own `strategy` wins when tooltip text is enabled, else the first
+ * hover marker's `strategy`, else the chart kind's default.
+ */
+export declare function resolveHoverStrategy(tooltipStrategy: HoverStrategy | undefined, markers: Marker[] | undefined, defaultStrategy: HoverStrategy): HoverStrategy;
+/**
+ * Resolve whether the hover should be broadcast across facets:
+ * the tooltip's own `sync` wins when tooltip text is enabled, else the first
+ * hover marker's `sync`, else false.
+ */
+export declare function resolveHoverSync(tooltipSync: boolean | undefined, markers: Marker[] | undefined): boolean;
+/** Whether any marker in the list is a hover marker. */
+export declare function hasHoverMarker(markers: Marker[] | undefined): boolean;
+/** First hover marker in the list, if any. */
+export declare function findHoverMarker(markers: Marker[] | undefined): HoverMarkerConfig | undefined;
+/** Narrow matched points down to a named subset of series (no-op if `series` is empty/undefined). */
+export declare function filterBySeries<T>(points: HoverPoint<T>[], series?: string[]): HoverPoint<T>[];

package/dist/layout/tooltip/utils.js

@@ -0,0 +1,78 @@
+/** Value equality that also handles `Date` (compared by timestamp). */
+export function eq(a, b) {
+    if (a instanceof Date && b instanceof Date)
+        return +a === +b;
+    return a === b;
+}
+/**
+ * Given the shared hover state, return the local points that should be
+ * highlighted using the store's current strategy.
+ */
+export function matchByStrategy(points, hover) {
+    const { strategy, activeX, activeY, activeSeries } = hover;
+    if (strategy === 'x') {
+        return activeX == null ? [] : points.filter((p) => eq(p.x, activeX));
+    }
+    if (strategy === 'y') {
+        return activeY == null ? [] : points.filter((p) => eq(p.y, activeY));
+    }
+    // 'punctual': exact XY match, respecting series identity when both sides carry it
+    if (activeX == null || activeY == null)
+        return [];
+    return points.filter((p) => eq(p.x, activeX) &&
+        eq(p.y, activeY) &&
+        (activeSeries == null || p.series == null || p.series === activeSeries));
+}
+/** Whether the strategy implies an x crosshair rule by default. */
+export function impliesRuleX(strategy) {
+    return strategy === 'x' || strategy === 'punctual';
+}
+/** Whether the strategy implies a y crosshair rule by default. */
+export function impliesRuleY(strategy) {
+    return strategy === 'y' || strategy === 'punctual';
+}
+/** Normalize the author-facing prop into a resolved object. */
+export function resolveTooltip(tooltip, defaultStrategy) {
+    if (!tooltip)
+        return { enabled: false, strategy: defaultStrategy, sync: false };
+    if (tooltip === true)
+        return { enabled: true, strategy: defaultStrategy, sync: false };
+    return {
+        enabled: true,
+        strategy: tooltip.strategy ?? defaultStrategy,
+        sync: tooltip.sync ?? false,
+        format: tooltip.format,
+        series: tooltip.series,
+        content: tooltip.content,
+    };
+}
+/**
+ * Resolve the strategy that should drive the shared hover store:
+ * the tooltip's own `strategy` wins when tooltip text is enabled, else the first
+ * hover marker's `strategy`, else the chart kind's default.
+ */
+export function resolveHoverStrategy(tooltipStrategy, markers, defaultStrategy) {
+    return tooltipStrategy ?? findHoverMarker(markers)?.strategy ?? defaultStrategy;
+}
+/**
+ * Resolve whether the hover should be broadcast across facets:
+ * the tooltip's own `sync` wins when tooltip text is enabled, else the first
+ * hover marker's `sync`, else false.
+ */
+export function resolveHoverSync(tooltipSync, markers) {
+    return tooltipSync ?? findHoverMarker(markers)?.sync ?? false;
+}
+/** Whether any marker in the list is a hover marker. */
+export function hasHoverMarker(markers) {
+    return (markers ?? []).some((m) => m.type === 'hover');
+}
+/** First hover marker in the list, if any. */
+export function findHoverMarker(markers) {
+    return (markers ?? []).find((m) => m.type === 'hover');
+}
+/** Narrow matched points down to a named subset of series (no-op if `series` is empty/undefined). */
+export function filterBySeries(points, series) {
+    if (!series || series.length === 0)
+        return points;
+    return points.filter((p) => p.series != null && series.includes(p.series));
+}