@pond-ts/charts 0.57.0 → 0.59.0

package/dist/AreaChart.d.ts

@@ -14,6 +14,17 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * single styling channel).
      */
     as?: string;
+    /**
+     * **Opt in to selection** — see `<LineChart id>`; the currency is identical
+     * because the premise is ([PND-TRACESEL]): a click commits a **series-scoped**
+     * `SelectInfo` (`NaN` key/value plus a stable `mark`), a sweep commits a
+     * `SpanSelection` with **no marks**.
+     *
+     * What differs is only the **hit test**: an area is a filled region, so the
+     * pointer counts as on it when it lies **between the trace and the
+     * baseline** — the whole shape is the target, not the 1.5px edge.
+     */
+    id?: string;
     /**
      * Which `<YAxis>` (by its `id`) this area scales against — picks the *scale*,
      * where `as` picks the *style*. **Omitted ⇒ the row's default axis.**
@@ -140,6 +151,6 @@ export declare function resolveAreaBaseline(baseline: number | undefined, yScale
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -1,10 +1,12 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
 import { assertNumericColumn, fromTimeSeries, fromValueSeries, } from './data.js';
-import { areaExtent, drawArea } from './area.js';
+import { areaExtent, areaHitIndex, areaStateStyle, drawArea } from './area.js';
+import { drawPartitioned, plotExtentOf, strokeSpanEdges, } 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';
 /** Read a d3 linear scale's domain lower bound (the axis floor) from the plain
@@ -54,7 +56,7 @@ function domainFloor(yScale) {
  * </Layers>
  * ```
  */
-export function AreaChart({ series, column, readout, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
+export function AreaChart({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
@@ -91,6 +93,45 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
     // Faintness of the inferred dashed connectors (dashed / step) — theme-level,
     // falling back to the shared default so a theme without it still renders faint.
     const gapConnectorOpacity = container.theme.gap?.connectorOpacity ?? DEFAULT_GAP_CONNECTOR_OPACITY;
+    // ── The trace's interaction state ([PND-TRACESEL]) — see `<LineChart>` for
+    // the reasoning; this is the same derivation over `AreaStyle`'s channels.
+    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';
+        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';
+        if (selectedEntries.length > 0 || allSpans.length > 0)
+            return 'dimmed';
+        return 'rest';
+    }, [id, selectedEntries, hoveredEntries, allSpans]);
+    // **`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,
@@ -99,6 +140,36 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
             // 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` ([PND-TRACESEL]). Same currency as
+            // `<LineChart>`; only `hitTest` differs, because a fill is not a stroke.
+            ...(id === undefined
+                ? {}
+                : {
+                    sweepsRect: false,
+                    sweepAxis: 'x',
+                    sweepSpanOnly: true,
+                    hitTest: (px, py, xScale, yScale) => {
+                        const i = areaHitIndex(cs, baseline, px, py, xScale, yScale);
+                        if (i === null)
+                            return null;
+                        return {
+                            id,
+                            // Series-scoped, with a stable `mark` for identity — see
+                            // `<LineChart>`'s hitTest for why both halves are needed.
+                            key: NaN,
+                            value: NaN,
+                            color: style.fill,
+                            label,
+                            mark: label,
+                        };
+                    },
+                    beginSweep: () => cs.length === 0
+                        ? null
+                        : sweepSpan({
+                            id,
+                            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.
@@ -151,16 +222,49 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
                     ]
                     : [];
             },
-            draw: (ctx, xScale, yScale) => drawArea(ctx, cs, xScale, yScale, style, 
-            // Omitted baseline rests on the axis floor (resolved late from the
-            // scale, so it tracks the auto-fit domain); a fixed baseline is used
-            // verbatim.
-            // A log axis has no position for zero — or anything at or below
-            // it — so an explicit out-of-domain `baseline` would scale to
-            // `NaN` and poison every coordinate in the fill path. Fall back
-            // to the axis floor, which is exactly what an omitted baseline
-            // already resolves to.
-            resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate),
+            draw: (ctx, xScale, yScale) => {
+                const fill = (st, alpha) => () => {
+                    const prior = ctx.globalAlpha;
+                    if (alpha !== 1)
+                        ctx.globalAlpha = prior * alpha;
+                    const out = drawAreaWith(st);
+                    ctx.globalAlpha = prior;
+                    return out;
+                };
+                if (spanX === null) {
+                    const [st, alpha] = areaStateStyle(style, traceState);
+                    return fill(st, alpha)();
+                }
+                // 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] = areaStateStyle(style, 'dimmed');
+                const [inStyle] = areaStateStyle(style, 'selected');
+                return drawPartitioned(ctx, [xScale(spanX[0]), xScale(spanX[1])], plotExtentOf(ctx, xScale, yScale).height, fill(outStyle, outAlpha), fill(style.spanColor === undefined || !soleSpannedTrace
+                    ? inStyle
+                    : { ...inStyle, color: style.spanColor, fill: style.spanColor }, 1), true, 0, plotExtentOf(ctx, xScale, yScale).width);
+                function drawAreaWith(st) {
+                    return drawArea(ctx, cs, xScale, yScale, st, 
+                    // Omitted baseline rests on the axis floor (resolved late from the
+                    // scale, so it tracks the auto-fit domain); a fixed baseline is used
+                    // verbatim.
+                    // A log axis has no position for zero — or anything at or below
+                    // it — so an explicit out-of-domain `baseline` would scale to
+                    // `NaN` and poison every coordinate in the fill path. Fall back
+                    // to the axis floor, which is exactly what an omitted baseline
+                    // already resolves to.
+                    resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate);
+                }
+            },
         },
         axisId: axis,
         index,
@@ -178,6 +282,11 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
         gapConnectorOpacity,
         decimate,
         axis,
+        id,
+        traceState,
+        spanX,
+        soleSpannedTrace,
+        previewing,
         index,
     ]);
     // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
@@ -194,6 +303,15 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // Advertise selectability (only when an `id` was given) — see the same block
+    // in `LineChart.tsx` for why a trace was missing from this set.
+    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 area style (top line
     // over the translucent fill), so a `<Legend>` swatch can never drift.
     const legendRows = useMemo(() => {

package/dist/BarChart.d.ts

@@ -1,6 +1,6 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
-import { type BinRecord, type CategoryDatum } from './data.js';
+import { type BinRecord, type CategoryDatum, type CategoryStackDatum } from './data.js';
 import { type Orientation } from './bars.js';
 import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
@@ -43,11 +43,17 @@ import type { DecimateOption } from './decimate.js';
  *   `<ChartContainer origin>` does not rescue it: it relabels a value axis but
  *   does not re-ladder it.
  * - **`categories`** — an ordered `{ label, value }[]`, one bar per category.
- *   Takes **no** `column`/`columns` (each datum carries its own value).
- *   Vertical puts the categories on the ordinal **x** axis (the container's
- *   band scale); `orientation="horizontal"` puts them on **y** as unit slots
- *   and the value on x, and a `<YAxis>` with no explicit `ticks` labels one
- *   per category automatically ([PND-HCAT]).
+ *   Takes no `column`. Vertical puts the categories on the ordinal **x** axis
+ *   (the container's band scale); `orientation="horizontal"` puts them on **y**
+ *   as unit slots and the value on x, and a `<YAxis>` with no explicit `ticks`
+ *   labels one per category automatically ([PND-HCAT]).
+ * - **`categories` + `columns`** — a **stacked** category chart
+ *   ([PND-CATSTACK]): each datum is `{ label, values }` and `columns` names the
+ *   groups to stack, bottom → top. The same relationship `series` + `columns`
+ *   already has, so a category stack is now a first-class shape rather than one
+ *   `categories` layer per cumulative total. One layer means one `mark` per
+ *   bar, so **one selection entry lights the whole bar** and the composed
+ *   workaround's per-layer replication is unnecessary.
  *
  * **Live charts:** `series.byValue(…)` / `.toMap()` mint fresh objects each
  * call, so an inline `series={…}` re-registers this layer every render — on a
@@ -95,6 +101,12 @@ type BarChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSerie
     bins?: never;
     column?: never;
     columns?: never;
+} | {
+    categories: readonly CategoryStackDatum[];
+    columns: readonly string[];
+    series?: never;
+    bins?: never;
+    column?: never;
 };
 /** The props every {@link BarChartSource} mode shares. */
 export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
@@ -230,6 +242,43 @@ export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extend
      * would invert collapses to the style's `minWidth`.
      */
     gap?: number;
+    /**
+     * Cap on a bar's **ink** width in px — applied after the `gap` inset and
+     * centred in its slot ([PND-BARWIDTH]). **Omitted ⇒ the theme's `bar`
+     * `maxWidth`, and uncapped if that is unset too** (a bar is `slot - gap`
+     * wide, as it always was).
+     *
+     * This is the *absolute* half of the width vocabulary. `gap` is **relative**,
+     * so with it alone bar width is always `slot - gap` and fattens as the plot
+     * widens; a fixed ink width is what makes a measure comparable **between**
+     * panes, since bars that widen with their pane read as different weights of
+     * the same thing.
+     *
+     * Pairs with `<ChartContainer maxBandWidth>`: that caps the **slot** (how far
+     * the bars spread), this caps the **ink** inside whatever slot results. The
+     * two are independent, which is the point — neither spelling alone expresses
+     * "spread the slots, pin the bar":
+     *
+     * - `maxBandWidth = barWidth + gap` pins the bar but stops the slots
+     *   spreading;
+     * - `maxBandWidth = slotCap` spreads them but lets the bar grow.
+     *
+     * `theme.bar[as].minWidth` still wins if the two bounds would invert, so the
+     * rect can never flip.
+     *
+     * **On a stacked chart the cap narrows the hit target too**, because a stack
+     * hit-tests its drawn segment rect (it must, to resolve *which* segment).
+     * A single-series bar is unaffected: it hit-tests its whole slot, so the ink
+     * can be narrow while the target stays full width.
+     *
+     * That holds in **both orientations**, and costs a deliberate guard to keep:
+     * a single-series *horizontal* chart shares the oriented draw/hit path with
+     * stacks, so the cap is withheld from its hit rect explicitly (`groups.length >
+     * 1`). Vertical charts get it for free — `barSlotRect` takes no cap. Don't
+     * "simplify" that guard away: the rule follows from segment disambiguation,
+     * which is a property of a stack, not of an axis.
+     */
+    maxBarWidth?: number;
     /**
      * **M4 column decimation** (charts decimator wave). **Omitted ⇒ `true`**: once
      * the visible bars are denser than ~2 per device pixel (each slot < ~1px), the
@@ -319,6 +368,6 @@ export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends Valu
  * </Layers>
  * ```
  */
-export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation, ordinal, id, axis, gap, decimate, legend, index, }: BarChartProps<S, VS>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation, ordinal, id, axis, gap, maxBarWidth, decimate, legend, index, }: BarChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=BarChart.d.ts.map