@pond-ts/charts 0.57.0 → 0.59.0

package/dist/Legend.js

@@ -112,8 +112,10 @@ export function Legend({ placement = 'top-right', items, onRowClick, onRowHover,
     // dulls (the ticker-compare treatment) — quieter and clearer than
     // decorating the selected item itself. Only when the selection points at an
     // item of THIS legend, so selecting an off-legend mark dulls nothing.
-    const selectedId = container?.selected?.id;
-    const anySelected = selectedId !== undefined && entries.some((it) => it.id === selectedId);
+    // Any member of the selection set that names an item of THIS legend
+    // ([PND-MULTISEL]); selecting an off-legend mark still dulls nothing.
+    const selectedIds = container?.selected ?? [];
+    const anySelected = entries.some((it) => it.id !== undefined && selectedIds.some((m) => m.id === it.id));
     const enter = (item) => {
         if (onRowHover)
             return onRowHover(item);
@@ -154,8 +156,10 @@ export function Legend({ placement = 'top-right', items, onRowClick, onRowHover,
             const interactive = onRowClick !== undefined ||
                 onRowHover !== undefined ||
                 (item.id !== undefined && container !== null);
-            const selected = item.id !== undefined && container?.selected?.id === item.id;
-            const hovered = item.id !== undefined && container?.hovered?.id === item.id;
+            const selected = item.id !== undefined &&
+                (container?.selected ?? []).some((m) => m.id === item.id);
+            const hovered = item.id !== undefined &&
+                (container?.hovered ?? []).some((m) => m.id === item.id);
             return (_jsxs("div", { onPointerEnter: () => enter(item), onPointerLeave: () => leave(item), onClick: () => click(item), style: {
                     display: 'flex',
                     alignItems: 'center',

package/dist/LineChart.d.ts

@@ -14,6 +14,23 @@ export interface LineChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * is what bred react-timeseries-charts' styling bugs; restyle via the theme).
      */
     as?: string;
+    /**
+     * **Opt in to selection** — the layer identity a `<Selector>` /
+     * `<MultiSelector>` reports and a `selected` entry names. **Omitted ⇒ the
+     * trace is inert**, exactly as every other layer's `id` gates it.
+     *
+     * A trace's selection is not shaped like a bar's, because **a trace has no
+     * marks** ([PND-TRACESEL]):
+     *
+     * - a **click** commits a **series-scoped** {@link SelectInfo} — `key` and
+     *   `value` are `NaN`, because no sample was selected, and a stable `mark`
+     *   carries the identity so the documented deselect-toggle works;
+     * - a **sweep** commits a {@link SpanSelection} with **no marks**. The span
+     *   _is_ the selection. A trace's samples are usually undrawn and there are
+     *   several per pixel, so "the samples you swept" is a set you never
+     *   expressed — take the span and slice your own series with it.
+     */
+    id?: string;
     /**
      * Which `<YAxis>` (by its `id`) this line scales against — picks the *scale*,
      * where `as` picks the *style* (separate concerns). **Omitted ⇒ the row's
@@ -107,6 +124,6 @@ export type LineChartProps<S extends SeriesSchema = SeriesSchema, VS extends Val
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, curve, gaps, sessionBreaks, decimate, legend, index, }: LineChartProps<S, VS>): null;
+export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, id, curve, gaps, sessionBreaks, decimate, legend, index, }: LineChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=LineChart.d.ts.map

package/dist/LineChart.js

@@ -1,10 +1,11 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
 import { assertNumericColumn, fromTimeSeries, fromValueSeries, } from './data.js';
-import { drawLine, yExtent } from './line.js';
+import { drawLine, drawPartitioned, plotExtentOf, sliceTrace, strokeSpanEdges, traceHitIndex, traceStateStyle, yExtent, } from './line.js';
+import { sweepSpan } from './sweep.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
-import { ContainerContext, LayersContext } from './context.js';
+import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /** Stable empty boundary list — so `sessionBreaks={false}` keeps a referentially
@@ -16,7 +17,7 @@ const NO_BREAKS = [];
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export function LineChart({ series, column, readout, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, decimate = true, legend, index = 0, }) {
+export function LineChart({ series, column, readout, as: semantic, axis, id, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<LineChart> must be rendered inside a <ChartContainer>');
@@ -64,6 +65,56 @@ export function LineChart({ series, column, readout, as: semantic, axis, curve,
         }
         return provider.boundaries(cs.x[0], cs.x[cs.length - 1]);
     }, [sessionBreaks, container.discontinuities, cs]);
+    // ── The trace's interaction state ([PND-TRACESEL]).
+    //
+    // Read here so a selection change re-registers the layer and the canvas
+    // repaints — the same plumbing `<BarChart>` uses. Reference-stable when
+    // nothing names this layer, so an unrelated selection elsewhere in the
+    // container neither re-identifies this entry nor repaints it.
+    const selectedEntries = container.selected;
+    const hoveredEntries = container.hovered;
+    // The committed spans, plus the **live** ones of a sweep in flight. A
+    // previewed span draws exactly as a committed one, so releasing changes
+    // nothing visually — the preview cannot promise a picture the commit does not
+    // deliver. The live channel wins while it is non-empty, because during a drag
+    // it IS the current answer.
+    const previewing = container.previewSpans.length > 0;
+    const allSpans = previewing
+        ? container.previewSpans
+        : container.selectedSpans;
+    const traceState = useMemo(() => {
+        if (id === undefined)
+            return 'rest';
+        // A span on THIS layer is handled by the partitioned draw below, not by a
+        // whole-series state: the emphasis is a region, not the series.
+        if (allSpans.some((sp) => sp.id === id))
+            return 'rest';
+        const mine = (e) => e.id === id;
+        if (selectedEntries.some(mine))
+            return 'selected';
+        if (hoveredEntries.some(mine))
+            return 'hover';
+        // Something else is selected ⇒ recede. Nothing dims while the selection is
+        // empty: with nothing selected there is nothing to recede *from*, the same
+        // rule `BarStyle.dimmed` states for the marks.
+        if (selectedEntries.length > 0 || allSpans.length > 0)
+            return 'dimmed';
+        return 'rest';
+    }, [id, selectedEntries, hoveredEntries, allSpans]);
+    // The swept window on this layer, in **key units** — mapped to pixels at draw
+    // time, because that is when the scale is known.
+    // **`spanColor` only when this is the ONLY swept trace.** The hue is
+    // justified by identity not being in question inside a single series — but
+    // sweep two traces and both would go blue, so inside the window you could no
+    // longer tell them apart, which is the very thing the rule exists to prevent.
+    // With more than one, the window thickens and every trace keeps its colour.
+    const soleSpannedTrace = allSpans.length === 1;
+    const spanX = useMemo(() => {
+        if (id === undefined)
+            return null;
+        const mine = allSpans.find((sp) => sp.id === id);
+        return mine === undefined ? null : mine.x;
+    }, [id, allSpans]);
     const entry = useMemo(() => ({
         layer: {
             as: semantic,
@@ -72,6 +123,44 @@ export function LineChart({ series, column, readout, as: semantic, axis, curve,
             // its layers: a ValueSeries plots on a value axis, a TimeSeries on time.
             xKind: series instanceof ValueSeries ? 'value' : 'time',
             xExtent: () => cs.length === 0 ? null : [cs.x[0], cs.x[cs.length - 1]],
+            // ── Selection, gated on `id` exactly as every other layer ([PND-TRACESEL]).
+            ...(id === undefined
+                ? {}
+                : {
+                    // A trace is 1-D in x: the value axis says nothing about what a
+                    // drag covered, so no rect and no y window.
+                    sweepsRect: false,
+                    sweepAxis: 'x',
+                    sweepSpanOnly: true,
+                    hitTest: (px, py, xScale, yScale) => {
+                        const i = traceHitIndex(cs, px, py, xScale, yScale);
+                        if (i === null)
+                            return null;
+                        return {
+                            id,
+                            // **Series-scoped**: no sample was selected, because a
+                            // sample is not a mark. `NaN` is what that already means
+                            // (see `SelectInfo.key`), and the stable `mark` below is
+                            // what gives the entry an identity — `sameMark` prefers it
+                            // over `key`, so two clicks anywhere on the trace are the
+                            // same selection and re-clicking deselects. Without the
+                            // `mark` they never would: `NaN !== NaN`.
+                            key: NaN,
+                            value: NaN,
+                            color: style.color,
+                            label,
+                            mark: label,
+                        };
+                    },
+                    beginSweep: () => cs.length === 0
+                        ? null
+                        : sweepSpan({
+                            id,
+                            // Clamped to the trace's own span, so a drag off the end
+                            // does not commit a range the series never covered.
+                            bounds: [cs.x[0], cs.x[cs.length - 1]],
+                        }),
+                }),
             sampleAt: (x) => {
                 // No readout past the data (tracker policy — nearest clamps to an
                 // endpoint outside the span); bounds from the columnar x axis.
@@ -122,7 +211,61 @@ export function LineChart({ series, column, readout, as: semantic, axis, curve,
                     ]
                     : [];
             },
-            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity, sessionBreakInstants, decimate),
+            draw: (ctx, xScale, yScale) => {
+                const stroke = (st, alpha, only) => () => {
+                    const prior = ctx.globalAlpha;
+                    const priorCap = ctx.lineCap;
+                    if (alpha !== 1)
+                        ctx.globalAlpha = prior * alpha;
+                    // Round the emphasised segment's ends. Only meaningful on a sliced
+                    // path, whose endpoints ARE the window's — a clipped stroke is
+                    // sheared vertically and no cap shows.
+                    if (only !== undefined)
+                        ctx.lineCap = 'round';
+                    const out = drawLine(ctx, only ?? cs, xScale, yScale, st, curveFactory, gaps, gapConnectorOpacity, sessionBreakInstants, decimate);
+                    ctx.globalAlpha = prior;
+                    ctx.lineCap = priorCap;
+                    return out;
+                };
+                // No window on this layer ⇒ one pass, in the series' own state.
+                if (spanX === null) {
+                    const [st, alpha] = traceStateStyle(style, traceState);
+                    return stroke(st, alpha)();
+                }
+                // A window: the trace outside it recedes and the portion inside is
+                // emphasised — the trace's answer to lighting the covered marks.
+                // `spanColor` is the one hue a trace's state may take, because inside
+                // a single series identity is not in question; with none themed the
+                // window just thickens.
+                // EXPERIMENT: annotation-register rules at the window's edges,
+                // underneath the trace ink (drawn first). See `strokeSpanEdges`.
+                //
+                // **Committed spans only.** While the drag is live the brush band
+                // already strokes its own edges at the same two x positions, so
+                // drawing these too put two rules a fraction of a pixel apart on each
+                // boundary — which read as one muddy smear rather than as either. The
+                // handoff is the honest reading anyway: the band is the gesture's
+                // mark and belongs to the drag; these preview the annotation you
+                // would get, and belong to the result.
+                if (!previewing)
+                    strokeSpanEdges(ctx, [xScale(spanX[0]), xScale(spanX[1])], ctx.canvas.height, container.theme.annotation?.spanEdge ?? '#f0b26b');
+                const [outStyle, outAlpha] = traceStateStyle(style, 'dimmed');
+                const [inStyle] = traceStateStyle(style, 'selected');
+                // The emphasised pass strokes a **slice** of the trace rather than
+                // the whole thing clipped, so its ends are real path ends and can be
+                // rounded. With nothing of the trace inside the window there is
+                // nothing to emphasise, and the muted pass alone is the picture.
+                const inner = sliceTrace(cs, spanX[0], spanX[1]);
+                const inInk = style.spanColor === undefined || !soleSpannedTrace
+                    ? inStyle
+                    : { ...inStyle, color: style.spanColor };
+                return drawPartitioned(ctx, [xScale(spanX[0]), xScale(spanX[1])], plotExtentOf(ctx, xScale, yScale).height, stroke(outStyle, outAlpha), inner === null
+                    ? () => ({ sourceCount: 0, drawnCount: 0, decimated: false })
+                    : stroke(inInk, 1, inner), false, 
+                // The round cap overhangs the boundary by half its width; keep the
+                // muted trace out from under it.
+                inInk.width / 2, plotExtentOf(ctx, xScale, yScale).width);
+            },
         },
         axisId: axis,
         index,
@@ -140,6 +283,11 @@ export function LineChart({ series, column, readout, as: semantic, axis, curve,
         sessionBreakInstants,
         decimate,
         axis,
+        id,
+        traceState,
+        spanX,
+        soleSpannedTrace,
+        previewing,
         index,
     ]);
     // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
@@ -159,6 +307,19 @@ export function LineChart({ series, column, readout, as: semantic, axis, curve,
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // Advertise selectability (only when an `id` was given) — the same
+    // registration `<BarChart>`/`<ScatterChart>`/`<BoxPlot>`/`<HeatMap>` make.
+    // A trace became selectable in [PND-TRACESEL] but never joined this set, so
+    // the container's "wired but nothing is selectable" guard fired on every
+    // trace-only chart that *was* correctly wired, and told the consumer to add
+    // an `id` to a mark layer they hadn't mounted.
+    const { registerSelectable, unregisterSelectable } = container;
+    useEffect(() => {
+        if (id === undefined)
+            return;
+        registerSelectable(slot);
+        return () => unregisterSelectable(slot);
+    }, [registerSelectable, unregisterSelectable, slot, id]);
     // And a legend row: the readout identity + the resolved line style, so a
     // `<Legend>` swatch can never drift from what the canvas draws.
     const legendRows = useMemo(() => {

package/dist/ListTable.d.ts

@@ -12,22 +12,49 @@
  * shared shell can evolve without a compatibility contract.
  */
 import { type ReactNode } from 'react';
+import type { SelectModifiers } from './context.js';
 import type { ListCellSpec, ListRow } from './list.js';
 import type { ChartTheme } from './theme.js';
+/**
+ * A row's interaction state, handed to {@link ListTableProps.renderGlyphs} so
+ * the glyphs can follow it — the fill is the one channel the shell cannot
+ * paint for them.
+ *
+ * `dimmed` is derived, not passed in: it means *something else* is selected.
+ * Nothing dims while the selection is empty, because with nothing selected
+ * there is nothing to recede from — the same rule `BarStyle.dimmed` states
+ * for the canvas.
+ */
+export interface ListRowState {
+    readonly selected: boolean;
+    readonly hovered: boolean;
+    readonly dimmed: boolean;
+}
 export interface ListTableProps<R extends ListRow> {
     /** Rows in display order (the caller sorts). */
     readonly rows: readonly R[];
     /** Which sister is rendering — stamped as `data-list` for styling/tests. */
     readonly kind: 'bar' | 'box';
     /** The glyph cell's content for one row (the bar / box lines). */
-    readonly renderGlyphs: (row: R) => ReactNode;
+    readonly renderGlyphs: (row: R, state: ListRowState) => ReactNode;
     readonly before?: readonly ListCellSpec<R>[] | undefined;
     readonly after?: readonly ListCellSpec<R>[] | undefined;
     readonly renderExpanded?: ((row: R) => ReactNode) | undefined;
     readonly defaultExpanded?: readonly string[] | undefined;
     readonly onExpandToggle?: ((key: string, expanded: boolean) => void) | undefined;
-    readonly selected?: string | null | undefined;
+    /** Selected row(s) — one key, a set of them, or nothing. Widened to match
+     *  {@link ListTableProps.hovered}; see `<BarList selected>`. */
+    readonly selected?: string | readonly string[] | null | undefined;
     readonly onRowClick?: ((row: R) => void) | undefined;
+    /** Plural select — a click's one row, or a drag's run. See `<BarList
+     *  onRowSelect>`; mounting it is what enables the drag. */
+    readonly onRowSelect?: ((rows: readonly R[], modifiers: SelectModifiers) => void) | undefined;
+    /** Controlled hover — one row key, a set of them, or nothing. Omitted ⇒
+     *  uncontrolled (the shell tracks the pointer itself, as it always has). */
+    readonly hovered?: string | readonly string[] | null | undefined;
+    /** Hover out: the entered row, or `null` on leaving every row. Fires in
+     *  controlled and uncontrolled mode alike, deduped by row key. */
+    readonly onHover?: ((row: R | null) => void) | undefined;
     readonly divided?: boolean | undefined;
     /** Draw the vertical **baseline rule** at the scale origin (the glyph
      *  cell's left edge) — the shared reference the eye aligns rows against. */
@@ -47,5 +74,5 @@ export interface ListTableProps<R extends ListRow> {
 /** The shared text ink: the band-label tone when the theme has one (stronger
  *  than tick labels — these cells are primary content), else the tick ink. */
 export declare function listInk(theme: ChartTheme): string;
-export declare function ListTable<R extends ListRow>({ rows, kind, renderGlyphs, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, divided, baseline, markers, theme, }: ListTableProps<R>): import("react/jsx-runtime").JSX.Element;
+export declare function ListTable<R extends ListRow>({ rows, kind, renderGlyphs, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, hovered, onHover, divided, baseline, markers, theme, }: ListTableProps<R>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ListTable.d.ts.map