@pond-ts/charts 0.56.2 → 0.58.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

@@ -26,6 +26,22 @@ import type { DecimateOption } from './decimate.js';
  *   (`Array<{ start, end, …aggregates }>`); the names are **aggregate
  *   fields** of the record, not schema columns, so they stay `string`. Pair
  *   with `ordinal` for a band axis.
+ *
+ *   **`bins` selects a *value* axis, so a time-bucketed histogram fed this way
+ *   gets decimal ticks** ([PND-TICKUNIT]). A `TimeSeries`/`Map` bins on time; a
+ *   `ValueSeries`/`bins`-array bins on a value axis — which means the tick
+ *   ladder is the plain 1-2-5 walk, not the **duration** ladder a clock
+ *   subdivides by (15s and 30s are round durations where 20s and 50s are not).
+ *   A minute-of-day histogram passed as `bins` therefore labels something like
+ *   11:40 and 13:20 — real times at a ~100-minute step — and nothing at the
+ *   call site says why.
+ *
+ *   The natural reading ("I have pre-binned buckets, so I'll pass `bins`") is
+ *   exactly what forecloses the time axis. For a **time-keyed** histogram use
+ *   the series door instead — `<BarChart series columns>` on a time-keyed wide
+ *   series — and the clock ticks are native with no workaround.
+ *   `<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
@@ -116,6 +132,58 @@ export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extend
      * carry many bars' colours, so every visible bar draws.
      */
     binColors?: readonly (string | undefined)[];
+    /**
+     * **Threshold breakpoints** — colour each bar *along its length* against a
+     * ladder, so a long bar shows how far through the ladder it travelled rather
+     * than only which band it ended in. Breakpoints are **absolute data values**
+     * in the axis's own units — `[1, 2]` means "warning above 1, alarm above 2",
+     * not offsets from wherever the bar happens to rest — and `n` of them make
+     * `n + 1` bands. Each must be finite and greater than zero; anything else is
+     * dropped with a dev warning (the ladder is walked on the magnitude, so a
+     * negative breakpoint is not expressible).
+     *
+     * ```tsx
+     * // neutral to 1, warning 1–2, alarm above 2
+     * <BarChart categories={cats} thresholds={[1, 2]} />
+     * ```
+     *
+     * Band fills come from {@link BarStyle.bands} on the resolved role
+     * (`theme.bar[as] ?? theme.bar.default`), overridden by {@link bandColors}.
+     * Breakpoints are data and live here; colour stays in the theme — the same
+     * split as `colors` over the stack's group fills.
+     *
+     * **A banded bar is still one bar.** It keeps one hit region, one stable
+     * `SelectInfo.mark` and one legend row — which is the whole difference from
+     * the N-overlaid-layers recipe this replaces, where each band was separately
+     * hittable and separately listed. Selection and hover pop the opacity and
+     * keep the band colours (as `binColors` does), outlining in the colour of the
+     * band the value actually reached.
+     *
+     * **Negatives band symmetrically**: the ladder is walked on the magnitude and
+     * re-signed, so a bar hanging below the baseline reads the same ±ladder
+     * without negative breakpoints. Out-of-order entries are sorted (the bands
+     * are defined by their boundaries, so there is no second reading) and
+     * non-finite ones dropped.
+     *
+     * Applies to any **single-value** bar — a `series`/`bins` chart, `categories`,
+     * and both orientations. On a genuine **multi-group stack** it is ignored
+     * with a dev warning: a segment that is already one slice of a total has no
+     * defined banding. Set with `binColors` it also yields (per-bar colour is the
+     * more specific answer) and warns. **Disables envelope decimation** for the
+     * same reason `binColors` does.
+     */
+    thresholds?: readonly number[];
+    /**
+     * Call-site override for the {@link thresholds} band fills — `bandColors[k]`
+     * paints the band above `thresholds[k - 1]`, so a ladder of `n` thresholds
+     * reads `n + 1` entries. Omitted ⇒ {@link BarStyle.bands} from the theme.
+     *
+     * Prefer the theme for anything a design system owns; this is the escape
+     * hatch for a one-off ladder that shouldn't mint a theme role. If neither
+     * source supplies enough entries, the shortfall falls back to the flat fill
+     * and dev-warns rather than silently drawing an unbanded bar.
+     */
+    bandColors?: readonly string[];
     /**
      * Bar growth direction (the histogram orientation). **Default `'vertical'`.**
      *
@@ -220,14 +288,21 @@ export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends Valu
  * domain spans zero, or on the axis floor when an explicit `<YAxis min>` sits
  * above zero (see {@link resolveBarBaseline}).
  *
- * **Baseline (stacked).** A stack is **cumulative from value 0** — the segments
- * sum upward from the zero line, so its value axis **must include 0**. The
- * auto-fit guarantees this: {@link stackValueExtent} always returns `[0, maxTotal]`.
- * An explicit `<YAxis min>` **above** 0 is therefore unsupported for a stack — it
- * would hide the bottom of the cumulative column; only the portion above the floor
- * draws (clipped cleanly at the plot floor, as any bar below an explicit floor is).
- * Segment values are assumed **non-negative** (a negative or zero segment is
- * skipped — diverging stacks are out of scope).
+ * **Baseline (stacked).** A stack is **cumulative from value 0** — so its value
+ * axis **must include 0**. The auto-fit guarantees this:
+ * {@link stackValueExtent} returns `[minNegativeTotal, maxPositiveTotal]`, both
+ * seeded at `0`. An explicit `<YAxis min>` **above** 0 is therefore unsupported
+ * for a stack — it would hide the bottom of the cumulative column; only the
+ * portion above the floor draws (clipped cleanly at the plot floor, as any bar
+ * below an explicit floor is).
+ *
+ * **Signed stacks are supported** ([PND-SIGNSTACK]): each bin keeps two running
+ * totals, so positive segments stack **up** from the zero line and negative
+ * ones stack **down** from it — the signed histogram (net flow by category,
+ * inflow/outflow, buy/sell pressure by venue). A **zero** segment is still
+ * skipped, having no extent to draw or hit-test. This changed in the
+ * threshold-banding wave: negative segments were previously dropped outright
+ * and silently, so a mixed-sign series rendered as an all-positive chart.
  *
  * **Interaction (opt-in via `id`).** Hover lights the bar / segment under the
  * cursor (hit-tested by pixel rect, so it works in both orientations); click
@@ -244,6 +319,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, 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, decimate, legend, index, }: BarChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=BarChart.d.ts.map