@pond-ts/charts 0.56.2 → 0.58.0

package/dist/bars.d.ts

@@ -1,7 +1,7 @@
 import type { BarSeries, StackedBarSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BarStyle } from './theme.js';
-import type { LayerDrawStats } from './context.js';
+import type { LayerDrawStats, SpanSelection } from './context.js';
 import { type DecimateOption } from './decimate.js';
 /**
  * Bar growth direction — the histogram orientation. `'vertical'` bars grow **up**
@@ -56,6 +56,84 @@ export declare function resolveBarBaseline(yScale: Scale): number;
  * separates columns visually without carving a dead channel out of the target.
  */
 export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+/**
+ * The value-space span `[lo, hi]` of **threshold band `k`** along a bar running
+ * from `base` to `v`, or `null` when the bar doesn't reach that band.
+ *
+ * A threshold ladder colours one bar **along its length** — neutral up to the
+ * first threshold, then warning, then alarm — so a long bar shows how far
+ * through the ladder it travelled rather than only which band it ended in. With
+ * `thresholds = [t0, t1]` there are three bands: `[0, t0)`, `[t0, t1)`,
+ * `[t1, ∞)`. Band `k` spans magnitudes `[thresholds[k-1] ?? 0, thresholds[k] ??
+ * ∞)`, each end clipped to the bar's own magnitude — so a bar that stops inside
+ * band 1 yields a truncated band 1 and `null` for band 2.
+ *
+ * **Breakpoints are absolute data values, not offsets from the baseline** — a
+ * `thresholds={[1, 2]}` ladder means "warning above 1, alarm above 2" in the
+ * axis's own units, which is what a threshold means everywhere else. They are
+ * matched on the **magnitude** and applied to whichever side of zero the bar
+ * is on, so a bar hanging below the baseline walks the same ladder downward
+ * and a ±3.5 diverging scale bands symmetrically without the caller supplying
+ * negative breakpoints. (An asymmetric ladder would need signed breakpoints;
+ * deferred until a consumer pulls — see [PND-BANDBAR2].)
+ *
+ * The painted span is then **clipped to what the bar actually draws**, which
+ * is what makes a domain that excludes zero behave: with `<YAxis min={10}>` a
+ * bar rests on 10, so a `[1, 2]` ladder leaves it entirely in the top band
+ * rather than banding at 11 and 12. Measuring the ladder from the *resolved
+ * baseline* instead would silently shift every breakpoint by the axis floor —
+ * exactly the class of quiet wrongness this feature exists to remove.
+ *
+ * Note this is **draw-only geometry**. Hit-testing still treats the bar as one
+ * target ({@link barSlotRect} / {@link barAt}), which is the whole reason this
+ * is a mark rather than the N-layer overpaint recipe it replaces: one bar keeps
+ * one hit region, one stable `mark`, and one legend row.
+ *
+ * `thresholds` is assumed ascending and finite — {@link normalizeThresholds}
+ * enforces that once at the prop boundary rather than per bar per frame.
+ */
+export declare function bandSpan(base: number, v: number, thresholds: readonly number[], k: number): [lo: number, hi: number] | null;
+/**
+ * A resolved threshold ladder: ascending `thresholds` (from
+ * {@link normalizeThresholds}) paired with the `colors` each band draws in,
+ * `colors[k]` for the band above `thresholds[k - 1]`. Assembled by `BarChart`
+ * from `<BarChart bandColors>` → {@link BarStyle.bands}, so — like
+ * {@link StackStyle} — the draw layer stays theme-free and unit-testable.
+ *
+ * `colors` is guaranteed `thresholds.length + 1` long by the time it reaches a
+ * draw path; a short ladder is resolved (and warned about) at the boundary.
+ */
+export interface BandLadder {
+    readonly thresholds: readonly number[];
+    readonly colors: readonly string[];
+}
+/**
+ * Validate + freeze a caller's threshold ladder once, at the prop boundary.
+ * Returns the ascending, strictly-positive, finite breakpoints — or `null` when
+ * there is no usable ladder left, so the caller keeps the flat path.
+ *
+ * Sorting rather than rejecting an out-of-order ladder is deliberate — the
+ * bands are defined by their boundaries, so `[2, 1]` and `[1, 2]` describe the
+ * same three bands and there is no second reading to guess at.
+ *
+ * Three kinds of entry are **dropped**:
+ *
+ * - **non-finite** — would swallow every band above it;
+ * - **negative** — the ladder is walked on the *magnitude* and mirrored onto
+ *   whichever side of zero the bar is on, so a negative breakpoint has no
+ *   meaning. Left in, `[-2, -1]` silently clipped every lower band away and
+ *   painted the whole bar in the final colour — a one-colour bar that looks
+ *   deliberate (Codex adversarial review). Signed breakpoints are the
+ *   asymmetric-ladder feature deferred in [PND-BANDBAR2], not this;
+ * - **zero** — band 0 already starts at zero, so a `0` breakpoint describes an
+ *   empty band and shifts every colour by one.
+ *
+ * Dropping rather than throwing matches how the rest of this prop behaves
+ * (a short colour ladder degrades, it doesn't fail), and `BarChart` dev-warns
+ * whenever normalization removed anything — a silently-ignored breakpoint is
+ * the failure mode this whole feature exists to avoid.
+ */
+export declare function normalizeThresholds(thresholds: readonly number[] | undefined): readonly number[] | null;
 /**
  * The narrowed selection / hover identity a **single-series** bar matches
  * against: the layer's series `id`, the sample's `key` (its `begin`), and — when
@@ -68,6 +146,21 @@ export interface BarMark {
     readonly key: number;
     readonly mark?: string;
 }
+/**
+ * Stroke a selected mark's outline **inside** its ink rect. Canvas strokes
+ * centre on the path, so a plain `strokeRect(x0, yTop, …)` paints
+ * `lineWidth / 2` *outside* the rect — which, with the default
+ * `outlineWidth: 1.5` against the default `gap: 1`, is enough to bridge the
+ * whole inter-bar gap from both sides: a swept run of selected bars fused
+ * into one unreadable block (you could not count them). Insetting the path by
+ * half the line width keeps every stroked pixel within the bar's own ink, so
+ * adjacent selected marks stay separated by exactly the gap the resting bars
+ * show. A mark too thin to contain its outline (either dimension
+ * `<= lineWidth`) skips the stroke — the highlight fill is already the
+ * signal, and an outline wider than the bar would only smear into the
+ * neighbours this exists to keep distinct.
+ */
+export declare function strokeSelectedOutline(ctx: CanvasRenderingContext2D, x0: number, x1: number, yTop: number, yBottom: number, lineWidth: number): void;
 /**
  * Fill one rectangle per bar in `cs`, each spanning its key's `[begin, end]`
  * (inset by `gapPx`) from the resolved `baseline` to the value.
@@ -120,7 +213,7 @@ export interface BarMark {
  * repaint them one flat colour; per-bar-coloured layers draw every visible bar.
  * Returns {@link LayerDrawStats} for `onDrawStats`.
  */
-export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: BarMark | null, hovered: BarMark | null, decimate?: DecimateOption, binFills?: readonly (string | undefined)[]): LayerDrawStats;
+export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: readonly BarMark[], hovered: readonly BarMark[], decimate?: DecimateOption, binFills?: readonly (string | undefined)[], banding?: BandLadder, spans?: readonly SpanSelection[]): LayerDrawStats;
 /**
  * The index of the bar whose key span `[begin, end]` contains `time` — the bar
  * **under the cursor** — or `-1` if `time` falls in no bar's span. This is the
@@ -222,6 +315,80 @@ export interface StackStyle {
      * falls back to the group fill.
      */
     readonly binFills?: readonly (string | undefined)[];
+    /**
+     * The **selected** segment's fill, and `hover` the pointer-over one — the
+     * three-step `fill → hover → highlight` emphasis {@link BarStyle} has always
+     * carried and this path used to ignore ([PND-CATEMPH]).
+     *
+     * **Only applied when there is no meaning-carrying colour to destroy**, i.e.
+     * when {@link binFills} is unset. A per-bin-coloured bar keeps its own colour
+     * and pops {@link emphasisOpacity} instead — swapping a zone-coloured or
+     * direction-coloured bar to one highlight hue would erase what the colour
+     * encodes, which is the one *design* exclusion rather than a path accident.
+     *
+     * The friction this closes wasn't the behaviour, which is defensible: it was
+     * that `theme.bar.hover` / `.highlight` were typed, settable, documented as
+     * the emphasis channel, and silently did nothing on the most common
+     * categorical chart. A theme author set them, saw no change, and had no way
+     * to tell whether they were wrong about the colour or about the mechanism.
+     */
+    readonly highlight?: string;
+    /** See {@link highlight}. Falls back to `highlight` when unset. */
+    readonly hover?: string;
+    /**
+     * Stroke for the selected segment's outline. Defaults to the segment's own
+     * resolved fill (the shipped behaviour). Set it to give the category path a
+     * themed selection cue that works even where the fill can't change — the
+     * `binFills` case, where the alpha pop is otherwise the only signal.
+     */
+    readonly selectedOutline?: string;
+    /**
+     * The alpha a hovered / selected segment pops to. **Default `1`** (the
+     * shipped behaviour). Lower it for a subtler emphasis on a dense stack —
+     * previously the pop was hard-coded and the only tunable was the resting
+     * {@link opacity}, so a theme could not adjust the *difference* between
+     * resting and live, only the floor.
+     */
+    readonly emphasisOpacity?: number;
+    /**
+     * Fill for a segment **not** in a non-empty selection set — the themed
+     * de-emphasis ([PND-MULTISEL], RFC A2.3). Unset ⇒ nothing dims, so this is
+     * opt-in and back-compatible. Unlike {@link highlight}, this **does** apply
+     * over {@link binFills}: dimming is about recession, not identity, so a
+     * zone-coloured bar can recede without its colour changing meaning — the
+     * dimmed value simply replaces it while it is out of the set.
+     */
+    readonly dimmed?: string;
+    /**
+     * Per-group {@link dimmed}, parallel to {@link fills} — the resolved
+     * `theme.bar.default.groupsDimmed` ramp. Set only for a **group-ramped**
+     * stack; `undefined` falls back to the flat {@link dimmed}.
+     *
+     * A stack dimmed to one colour stops being a stack — the segment boundaries
+     * vanish and the receded bins read as solid blocks, which is exactly the
+     * structure a selection wants to keep visible for comparison.
+     */
+    readonly dimmedFills?: readonly string[];
+    /**
+     * Per-group {@link hover}, parallel to {@link fills} — the resolved
+     * `theme.bar.default.groupsHover` ramp. Set only for a **group-ramped**
+     * stack; `undefined` falls back to the flat {@link hover}.
+     *
+     * A single hover colour repaints the pointed-at segment in a hue belonging
+     * to another group, so hovering erases the ramp exactly where the reader is
+     * looking — and block-scoped hover erases the whole bin.
+     */
+    readonly hoverFills?: readonly string[];
+    /**
+     * Whether {@link fills} carry **group identity** (a resolved group ramp)
+     * rather than being one repeated role colour.
+     *
+     * When they do, a selected segment keeps its own fill and the outline plus
+     * the receded neighbours are the cue — the same exclusion {@link binFills}
+     * already gets, and for the same reason: replacing a meaning-carrying colour
+     * with the flat `highlight` destroys the thing the selection is *about*.
+     */
+    readonly groupColored?: boolean;
 }
 /** The narrowed selection / hover identity a stacked segment matches against:
  *  the series `id`, the bin's `begin` (its `key`), and the group (its `label`).
@@ -235,14 +402,20 @@ export interface StackMark {
 }
 /**
  * The `[min, max]` extent of the **value (stacked) axis**. For a true multi-group
- * stack it is `[0, maxTotal]`, where `maxTotal` is the tallest bin's summed finite
- * non-negative segments. For a **single-group** series (`G === 1` — the plain /
+ * stack it is `[minNegTotal, maxPosTotal]` — each bin's positive segments summed
+ * upward and its negative segments summed downward, tracked separately
+ * ([PND-SIGNSTACK]). For a **single-group** series (`G === 1` — the plain /
  * categorical bar case) it spans the values' own `[min, max]`, so a **negative**
  * bar's floor is in the domain (segments below the baseline stay visible). `0` is
  * always pulled in so the bars rest on a visible baseline (the bar analog of
  * {@link barExtent}). An empty / all-gap series returns `[0, 1]` so the axis still
  * has a usable domain. Feeds the y auto-fit for a vertical histogram, the x
  * auto-fit for a horizontal one.
+ *
+ * The negative half is new: this used to sum only positives, matching a draw
+ * path that dropped negative segments outright. Both halves changed together —
+ * an extent that stopped at `0` below would clip the very segments the draw
+ * path now emits.
  */
 export declare function stackValueExtent(ss: StackedBarSeries): [number, number];
 /**
@@ -299,7 +472,7 @@ export declare function segmentRect(ss: StackedBarSeries, b: number, g: number,
  *
  * O(N·G) over bins × groups, one fill (+ optional stroke) per drawn segment.
  */
-export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBarSeries, orientation: Orientation, xScale: Scale, yScale: Scale, style: StackStyle, gapPx: number, minSpanPx: number, seriesId: string | undefined, selection: StackMark | null, hover: StackMark | null): void;
+export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBarSeries, orientation: Orientation, xScale: Scale, yScale: Scale, style: StackStyle, gapPx: number, minSpanPx: number, seriesId: string | undefined, selection: readonly StackMark[], hover: readonly StackMark[], banding?: BandLadder, spans?: readonly SpanSelection[]): void;
 /**
  * Hit-test plot-pixel `(px, py)` against `ss`'s stacked segments — the **first**
  * segment whose rect contains the point, or `null`. The geometry is