@pond-ts/charts 0.42.0 → 0.44.0

package/dist/bars.js

@@ -172,9 +172,12 @@ export function barAt(cs, px, py, xScale, yScale, baseline, gapPx, minWidthPx) {
     return null;
 }
 /**
- * The `[min, max]` extent of the **value (stacked) axis** — always `[0, maxTotal]`,
- * where `maxTotal` is the tallest bin's summed finite non-negative segments. `0` is
- * pulled in so the stack rests on a visible baseline (the bar analog of
+ * 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 /
+ * 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.
@@ -182,17 +185,32 @@ export function barAt(cs, px, py, xScale, yScale, baseline, gapPx, minWidthPx) {
 export function stackValueExtent(ss) {
     const G = ss.groups.length;
     let max = 0;
+    let min = 0;
     for (let b = 0; b < ss.length; b += 1) {
         let cum = 0;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            if (Number.isFinite(v) && v > 0)
-                cum += v;
+            if (!Number.isFinite(v))
+                continue;
+            if (G === 1) {
+                // Single-group: a bar honours its sign, so track both ends.
+                if (v > max)
+                    max = v;
+                if (v < min)
+                    min = v;
+            }
+            else if (v > 0) {
+                cum += v; // True stack: sum the positive segments.
+            }
         }
         if (cum > max)
             max = cum;
     }
-    return [0, max > 0 ? max : 1];
+    // Empty / all-gap / all-zero → a usable unit domain; otherwise the real extent
+    // (with 0 pulled in via the `min`/`max` seeds above).
+    if (min === 0 && max === 0)
+        return [0, 1];
+    return [min, max];
 }
 /**
  * The `[min, max]` extent of the **bin axis** — the first bin's `begin` to the
@@ -224,9 +242,14 @@ export function stackBinExtent(ss) {
 export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx) {
     const G = ss.groups.length;
     const v = ss.values[b * G + g];
-    // Skip non-finite / negative / zero: a zero segment would otherwise draw a
-    // wasted zero-extent rect (and can't be hit-tested).
-    if (!Number.isFinite(v) || v <= 0)
+    // Skip non-finite (a gap) or zero (a zero-extent rect that can't draw or be
+    // hit-tested). A **negative** value is a gap only in a true multi-group stack
+    // (`G > 1`) — stacking a negative segment is undefined. A **single-group**
+    // series (`G === 1`) is a plain bar: it honours its sign and draws from the
+    // baseline *down* to a negative value (the categorical row-read's P&L / delta
+    // case), so negatives are kept and the `Math.min/Math.max` below normalizes the
+    // below-baseline rect.
+    if (!Number.isFinite(v) || v === 0 || (v < 0 && G > 1))
         return null;
     if (orientation === 'vertical') {
         const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx);
@@ -242,8 +265,10 @@ export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, ga
 /**
  * Fill every segment of every bin in `ss`, stacking each bin's groups from the
  * value baseline outward (bottom → top vertical, left → right horizontal). A gap
- * (non-finite / negative) segment is skipped and adds nothing to the running
- * total, so the segments above it close the space. A segment matching the current
+ * (non-finite, or a negative segment of a true multi-group stack) is skipped and
+ * adds nothing to the running total, so the segments above it close the space; a
+ * single-group series draws its negative bars below the baseline (see
+ * {@link segmentRect}). A segment matching the current
  * `selection` (same series `id`, bin `key` **and** group `label`) draws in its
  * group's `highlight` **and** outlined; one matching `hover` draws in `highlight`
  * without the outline; all others use the flat `fill`. `globalAlpha` carries the
@@ -265,20 +290,27 @@ export function drawStacks(ctx, ss, orientation, xScale, yScale, style, gapPx, m
             if (rect === null)
                 continue;
             const [x0, x1, yTop, yBottom] = rect;
+            // With `marks` (the categorical axis), match on the stable per-bin name so a
+            // pinned selection survives a column reorder; otherwise on the sample `key`
+            // (begin) + group `label`, as a time / value stack does.
+            const stableMark = ss.marks?.[b];
             const matches = (m) => m !== null &&
                 m.id === seriesId &&
-                m.key === ss.begin[b] &&
-                m.label === ss.groups[g];
+                (stableMark !== undefined
+                    ? m.mark === stableMark
+                    : m.key === ss.begin[b] && m.label === ss.groups[g]);
             const selected = matches(selection);
             const isHovered = matches(hover);
             // A hovered / selected segment pops to full opacity in its own colour; a
             // resting one draws at the shared alpha.
             ctx.globalAlpha = selected || isHovered ? 1 : style.opacity;
-            ctx.fillStyle = style.fills[g];
+            // A per-bin colour (the single-series band case) overrides the group fill.
+            const fill = style.binFills?.[b] ?? style.fills[g];
+            ctx.fillStyle = fill;
             ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
             if (selected) {
                 ctx.lineWidth = style.outlineWidth;
-                ctx.strokeStyle = style.fills[g];
+                ctx.strokeStyle = fill;
                 ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
             }
         }

package/dist/box.d.ts

@@ -3,9 +3,10 @@ import type { Scale } from './line.js';
 import type { BoxStyle } from './theme.js';
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
- * whisker and highest `upper` whisker over keys where **all five** quantiles are
- * finite — or `null` if none are. Gap keys (any quantile `NaN`) are excluded,
- * matching what {@link drawBox} draws, so they don't drag the y-domain.
+ * whisker and highest `upper` whisker over the keys {@link isFiniteBox} draws
+ * (a full box needs all five quantiles; a range-only box just `lower`/`upper`) —
+ * or `null` if none are. Gap keys are excluded, matching what {@link drawBox}
+ * draws, so they don't drag the y-domain.
  *
  * Only `lower`/`upper` bound the extent: they are the outermost reach of a key
  * (the whisker ends), so `q1`/`median`/`q3` lie within `[lower, upper]` for any
@@ -44,16 +45,32 @@ export type BoxShape = 'whisker' | 'solid' | 'none';
  *   reads darker on a light ground, brighter on a dark one), no stems/outline.
  * - **`none`** — the `q1→q3` box fill + outline only, no spread marks.
  *
- * Then, if `showMedian`, the median line across the box on top. Fills are
- * bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * **Range-only** (`box.hasBox === false` — no `q1`/`q3`): there's no body, so
+ * `whisker` draws **one** full `lower→upper` stem with caps, `solid` draws just
+ * the outer bar, and `none` draws **nothing** (no body + no spread ⇒ empty — pick
+ * `whisker`/`solid` for a range-only box). `showMedian` is a no-op when the box
+ * carries no `median` (`hasMedian === false`).
  *
- * **Gap-aware**: a key with any quantile non-finite is skipped entirely (no
- * partial box) — the same contract as a band gap.
+ * Then, if `showMedian` (and a median is present), the median line on top. Fills
+ * are bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * `offsetPx` shifts every mark in pixel space (for pairing same-key marks);
+ * `capWidthPx` sets a fixed whisker-cap width (else half the box width — a small
+ * fixed cap keeps paired offset marks' T-bars from overlapping), clamped to the
+ * box width.
+ *
+ * **Gap-aware**: a key whose present quantiles aren't all finite is skipped
+ * entirely (no partial box) — the same contract as a band gap.
  *
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean): void;
-/** All five quantiles finite at `i` — i.e. this key is drawn. */
+export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean, offsetPx?: number, capWidthPx?: number): void;
+/**
+ * This key is drawable — the quantiles it actually carries are all finite at `i`.
+ * `lower`/`upper` (the whisker reach) are always required; `q1`/`q3` only when the
+ * box has a body (`hasBox !== false`), `median` only when it has a centre line
+ * (`hasMedian !== false`). So a **range-only** box (bid→ask, no body/median) draws
+ * wherever `lower`/`upper` are finite, and a full box still needs all five.
+ */
 export declare function isFiniteBox(box: BoxSeries, i: number): boolean;
 //# sourceMappingURL=box.d.ts.map

package/dist/box.js

@@ -3,9 +3,10 @@ import { barSpanPx } from './range.js';
 const WHISKER_CAP_FRACTION = 0.5;
 /**
  * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
- * whisker and highest `upper` whisker over keys where **all five** quantiles are
- * finite — or `null` if none are. Gap keys (any quantile `NaN`) are excluded,
- * matching what {@link drawBox} draws, so they don't drag the y-domain.
+ * whisker and highest `upper` whisker over the keys {@link isFiniteBox} draws
+ * (a full box needs all five quantiles; a range-only box just `lower`/`upper`) —
+ * or `null` if none are. Gap keys are excluded, matching what {@link drawBox}
+ * draws, so they don't drag the y-domain.
  *
  * Only `lower`/`upper` bound the extent: they are the outermost reach of a key
  * (the whisker ends), so `q1`/`median`/`q3` lie within `[lower, upper]` for any
@@ -56,70 +57,101 @@ export function boxIndexAtTime(box, time) {
  *   reads darker on a light ground, brighter on a dark one), no stems/outline.
  * - **`none`** — the `q1→q3` box fill + outline only, no spread marks.
  *
- * Then, if `showMedian`, the median line across the box on top. Fills are
- * bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * **Range-only** (`box.hasBox === false` — no `q1`/`q3`): there's no body, so
+ * `whisker` draws **one** full `lower→upper` stem with caps, `solid` draws just
+ * the outer bar, and `none` draws **nothing** (no body + no spread ⇒ empty — pick
+ * `whisker`/`solid` for a range-only box). `showMedian` is a no-op when the box
+ * carries no `median` (`hasMedian === false`).
  *
- * **Gap-aware**: a key with any quantile non-finite is skipped entirely (no
- * partial box) — the same contract as a band gap.
+ * Then, if `showMedian` (and a median is present), the median line on top. Fills
+ * are bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ * `offsetPx` shifts every mark in pixel space (for pairing same-key marks);
+ * `capWidthPx` sets a fixed whisker-cap width (else half the box width — a small
+ * fixed cap keeps paired offset marks' T-bars from overlapping), clamped to the
+ * box width.
+ *
+ * **Gap-aware**: a key whose present quantiles aren't all finite is skipped
+ * entirely (no partial box) — the same contract as a band gap.
  *
  * O(N) over the keys, a fixed number of path ops each — no per-key allocation
  * beyond the `barSpanPx` tuple.
  */
-export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx = 1, shape = 'whisker', showMedian = true) {
+export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx = 1, shape = 'whisker', showMedian = true, offsetPx = 0, capWidthPx) {
+    // A range-only box (bid→ask segment) has no body / median; the whisker (or the
+    // solid bar) runs the full lower→upper. Flags default true (a full box).
+    const hasBox = box.hasBox !== false;
+    const drawMedian = showMedian && box.hasMedian !== false;
     for (let i = 0; i < box.length; i += 1) {
         if (!isFiniteBox(box, i))
             continue;
-        const [x0, x1] = barSpanPx(box.x[i], box.xEnd[i], xScale, gapPx, minWidthPx);
+        const [span0, span1] = barSpanPx(box.x[i], box.xEnd[i], xScale, gapPx, minWidthPx);
+        // `offsetPx` nudges the whole mark in pixel space (zoom-stable) — for pairing
+        // same-key marks (call/put at one strike) side by side without overlap.
+        const x0 = span0 + offsetPx;
+        const x1 = span1 + offsetPx;
         const mid = (x0 + x1) / 2;
         const yLower = yScale(box.lower[i]);
-        const yQ1 = yScale(box.q1[i]);
-        const yMedian = yScale(box.median[i]);
-        const yQ3 = yScale(box.q3[i]);
         const yUpper = yScale(box.upper[i]);
+        // q1/q3 are NaN on a range-only box — read them only when there's a body.
+        const yQ1 = hasBox ? yScale(box.q1[i]) : 0;
+        const yQ3 = hasBox ? yScale(box.q3[i]) : 0;
         if (shape === 'solid') {
-            // Candlestick: a light outer bar over the full lower→upper spread, then a
-            // more-prominent inner q1→q3 box on top (same fill at rising opacity, so the
-            // inner reads darker on a light ground / brighter on a dark one). No stems,
-            // no outline.
+            // Candlestick: a light outer bar over the full lower→upper spread, then —
+            // when there's a body — a more-prominent inner q1→q3 box on top (same fill
+            // at rising opacity). No stems, no outline.
             ctx.save();
             ctx.fillStyle = style.fill;
             ctx.globalAlpha = style.fillOpacity;
             ctx.fillRect(x0, yUpper, x1 - x0, yLower - yUpper);
-            ctx.globalAlpha = Math.min(1, style.fillOpacity * 2);
-            ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            if (hasBox) {
+                ctx.globalAlpha = Math.min(1, style.fillOpacity * 2);
+                ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            }
             ctx.restore();
         }
         else {
-            // `whisker` / `none`: the graded q1→q3 box fill + outline.
-            ctx.save();
-            ctx.fillStyle = style.fill;
-            ctx.globalAlpha = style.fillOpacity;
-            ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
-            ctx.restore();
-            ctx.strokeStyle = style.stroke;
-            ctx.lineWidth = style.strokeWidth;
-            ctx.strokeRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            // `whisker` / `none`: the graded q1→q3 box fill + outline (body only).
+            if (hasBox) {
+                ctx.save();
+                ctx.fillStyle = style.fill;
+                ctx.globalAlpha = style.fillOpacity;
+                ctx.fillRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+                ctx.restore();
+                ctx.strokeStyle = style.stroke;
+                ctx.lineWidth = style.strokeWidth;
+                ctx.strokeRect(x0, yQ3, x1 - x0, yQ1 - yQ3);
+            }
             if (shape === 'whisker') {
-                // Whiskers: a stem from each box edge to the whisker end, with a cap.
-                const capHalf = ((x1 - x0) * WHISKER_CAP_FRACTION) / 2;
+                // Whiskers with end-caps. With a body: two stems (q3→upper, q1→lower).
+                // Range-only (no body): one stem spanning the full lower→upper.
+                // Cap half-width: an explicit `capWidthPx` (a fixed pixel cap — for
+                // pairing offset marks without their T-bars overlapping) else a fraction
+                // of the box width (responsive default). Never wider than the box.
+                const capHalf = capWidthPx !== undefined
+                    ? Math.min(capWidthPx, x1 - x0) / 2
+                    : ((x1 - x0) * WHISKER_CAP_FRACTION) / 2;
                 ctx.strokeStyle = style.whisker;
                 ctx.lineWidth = style.whiskerWidth;
                 ctx.beginPath();
-                // Upper: stem q3 → upper, cap at upper.
-                ctx.moveTo(mid, yQ3);
+                // Upper stem: from the box top (q3) or, range-only, from lower.
+                ctx.moveTo(mid, hasBox ? yQ3 : yLower);
                 ctx.lineTo(mid, yUpper);
                 ctx.moveTo(mid - capHalf, yUpper);
                 ctx.lineTo(mid + capHalf, yUpper);
-                // Lower: stem q1 → lower, cap at lower.
-                ctx.moveTo(mid, yQ1);
-                ctx.lineTo(mid, yLower);
+                // Lower cap (and, with a body, the lower stem q1→lower).
+                if (hasBox) {
+                    ctx.moveTo(mid, yQ1);
+                    ctx.lineTo(mid, yLower);
+                }
                 ctx.moveTo(mid - capHalf, yLower);
                 ctx.lineTo(mid + capHalf, yLower);
                 ctx.stroke();
             }
         }
-        // The median line across the box, on top — always optional.
-        if (showMedian) {
+        // The median line across the box, on top — drawn only when the box carries a
+        // median column and `showMedian` is on.
+        if (drawMedian) {
+            const yMedian = yScale(box.median[i]);
             ctx.strokeStyle = style.median;
             ctx.lineWidth = style.medianWidth;
             ctx.beginPath();
@@ -129,12 +161,24 @@ export function drawBox(ctx, box, xScale, yScale, style, gapPx = 0, minWidthPx =
         }
     }
 }
-/** All five quantiles finite at `i` — i.e. this key is drawn. */
+/**
+ * This key is drawable — the quantiles it actually carries are all finite at `i`.
+ * `lower`/`upper` (the whisker reach) are always required; `q1`/`q3` only when the
+ * box has a body (`hasBox !== false`), `median` only when it has a centre line
+ * (`hasMedian !== false`). So a **range-only** box (bid→ask, no body/median) draws
+ * wherever `lower`/`upper` are finite, and a full box still needs all five.
+ */
 export function isFiniteBox(box, i) {
-    return (Number.isFinite(box.lower[i]) &&
-        Number.isFinite(box.q1[i]) &&
-        Number.isFinite(box.median[i]) &&
-        Number.isFinite(box.q3[i]) &&
-        Number.isFinite(box.upper[i]));
+    if (!Number.isFinite(box.lower[i]) || !Number.isFinite(box.upper[i])) {
+        return false;
+    }
+    if (box.hasBox !== false &&
+        (!Number.isFinite(box.q1[i]) || !Number.isFinite(box.q3[i]))) {
+        return false;
+    }
+    if (box.hasMedian !== false && !Number.isFinite(box.median[i])) {
+        return false;
+    }
+    return true;
 }
 //# sourceMappingURL=box.js.map

package/dist/context.d.ts

@@ -1,7 +1,9 @@
 import type { ScaleLinear, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
 import type { AxisFormat } from './format.js';
+import type { Interval } from 'pond-ts';
 import type { TradingTimeScale, DiscontinuityProvider } from './tradingTimeScale.js';
+import type { ScaleBand } from './bandScale.js';
 /**
  * The frame a {@link ChartContainer} provides to its rows and the time axis.
  * The container owns the **shared x geometry**: each side is split into *slots*
@@ -64,6 +66,44 @@ export interface ContainerFrame {
      * (`yScale.invert`). The x always snaps to the data grid either way.
      */
     readonly crosshairSnap: boolean;
+    /**
+     * `cursor="region"` buckets — the intervals (from `cursorSequence`) realized
+     * over the current view, sorted + non-overlapping. `Layers` finds the one under
+     * the pointer and shades it (mapped through `xScale`, so on a trading-time axis
+     * the closed part of the bucket collapses). `undefined` when no `cursorSequence`
+     * is set.
+     */
+    readonly cursorBuckets: readonly Interval[] | undefined;
+    /**
+     * The `region`-cursor **drag anchor** in axis units (epoch ms on a time axis,
+     * the axis value on a value axis), or `null` when not dragging. A drag on a
+     * region cursor (only when {@link onRegionSelect} is set) records the press
+     * position here; the band then spans from the anchor's bucket to the pointer's
+     * bucket (extending bucket by bucket), or freeform when there are no buckets.
+     * Cleared on release.
+     */
+    readonly regionAnchor: number | null;
+    /** Set / clear the region-drag anchor (see {@link regionAnchor}). */
+    setRegionAnchor(value: number | null): void;
+    /**
+     * One-shot callback fired when a `region`-cursor **drag** is released, with the
+     * selected `[lo, hi]` span in **axis units** — epoch ms on a time axis, the axis
+     * value on a value axis (snapped to the `cursorSequence` buckets when present,
+     * else the raw drag span). The neutral numeric pair mirrors the container's
+     * polymorphic `range` input (which never takes the axis *kind* from its value);
+     * a time-axis consumer who wants a `TimeRange` constructs one from the pair.
+     * Providing it is what makes the region cursor **draggable**; the cursor does
+     * not keep the range (it reverts to the single-bucket highlight). Typical use:
+     * zoom the view, or map the span onto a subscription's range params.
+     */
+    readonly onRegionSelect: ((range: readonly [number, number]) => void) | undefined;
+    /**
+     * Require a modifier key held to start a region-drag — set to `'shift'` to make
+     * plain drag **pan** and **shift**-drag select, when `panZoom` is on. Only
+     * enforced while pan is enabled (with no pan there's no gesture to share, so the
+     * modifier is optional). `undefined` ⇒ a region-drag preempts pan.
+     */
+    readonly regionSelectModifier: 'shift' | undefined;
     /**
      * The selected mark, or `null`. Shared across rows (single selection). A layer
      * highlights the mark matching the selection's series **`id`** and the clicked
@@ -139,7 +179,7 @@ export interface ContainerFrame {
      * `invert` / `ticks` / `tickFormat` surface, but the mapping runs through
      * trading time so closed-market gaps collapse (see {@link discontinuities}).
      */
-    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale;
+    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale | ScaleBand;
     /**
      * The discontinuity provider backing a **trading-time** x axis, if one was
      * supplied to the container — closed-market time (weekends, holidays,
@@ -149,12 +189,13 @@ export interface ContainerFrame {
      */
     readonly discontinuities?: DiscontinuityProvider | undefined;
     /**
-     * The resolved kind of the shared x scale — `'time'` (a `scaleTime`) or
-     * `'value'` (a `scaleLinear`), inferred from the layers' data. `<XAxis>` reads
-     * it to pick its default tick formatter (a time format vs a number format),
-     * and the cursor readout to format the x position.
+     * The resolved kind of the shared x scale — `'time'` (a `scaleTime`),
+     * `'value'` (a `scaleLinear`), or `'category'` (a {@link ScaleBand}: an ordinal
+     * column-domain axis, one slot per category). Inferred from the layers' data.
+     * `<XAxis>` reads it to pick its default tick formatter (time / number / the
+     * category label), and the cursor readout to format the x position.
      */
-    readonly xKind: 'time' | 'value';
+    readonly xKind: 'time' | 'value' | 'category';
     /** Pan/zoom enabled — the plot drag-pans and wheel-zooms the shared time range. */
     readonly panZoom: boolean;
     /** Minimum visible duration (ms) — the zoom-in floor. */
@@ -314,17 +355,37 @@ export interface RowLayer {
     yExtent(): [number, number] | null;
     /**
      * The **kind of x axis** this layer's data lives on — `'time'` for a
-     * `TimeSeries`, `'value'` for a `ValueSeries`. The container infers the one
-     * shared x scale from its layers (all must agree — a mix is an error), so the
-     * axis kind never needs declaring. See {@link ContainerFrame.xScale}.
+     * `TimeSeries`, `'value'` for a `ValueSeries`, `'category'` for a categorical
+     * (ordinal column-domain) layer. The container infers the one shared x scale
+     * from its layers (all must agree — a mix is an error), so the axis kind never
+     * needs declaring. See {@link ContainerFrame.xScale}.
      */
-    readonly xKind: 'time' | 'value';
+    readonly xKind: 'time' | 'value' | 'category';
     /**
      * This layer's `[min, max]` along the **x** axis (the key / value-axis extent),
      * or `null` if empty. The container unions these to auto-fit the shared x
-     * domain when no explicit `range` is given.
+     * domain when no explicit `range` is given. For a `'category'` layer this is
+     * the slot extent `[0, n]` (n = category count).
      */
     xExtent(): readonly [number, number] | null;
+    /**
+     * A `'category'` layer's ordered category names (the ordinal axis domain the
+     * container builds a {@link ScaleBand} + label formatter from). `undefined` /
+     * absent for a `'time'` or `'value'` layer. Category layers in one container
+     * must agree on this list (a mix is an error), the same way {@link xKind} must.
+     */
+    xCategories?(): readonly string[] | null;
+    /**
+     * A bar/histogram layer's bar `[begin, end)` spans, as pond `Interval`s — the
+     * **region cursor's snap buckets**. When present (and no `cursorSequence` is
+     * set), a region drag snaps bar by bar and a hover highlights the bar under the
+     * pointer, so a histogram gets bin-aligned selection for free. Only a
+     * **vertical** bar layer on a **continuous** (time / value) x axis publishes
+     * them — a horizontal chart puts the value on x (snapping counts is meaningless)
+     * and a **category** (ordinal-slot) axis is excluded from the region cursor.
+     * `null` / absent otherwise.
+     */
+    binIntervals?(): readonly Interval[] | null;
     /**
      * The layer's value(s) at `time` — the nearest sample — for the scrub tracker:
      * one for a line, two (lower/upper) for a band, empty at a gap. Each carries
@@ -394,8 +455,12 @@ export interface CursorFlag {
  */
 export interface TrackerSource {
     sampleAt(time: number): readonly TrackerSample[];
-    readonly xKind: 'time' | 'value';
+    readonly xKind: 'time' | 'value' | 'category';
     xExtent(): readonly [number, number] | null;
+    /** A `'category'` source's ordered category names (see {@link RowLayer.xCategories}). */
+    xCategories?(): readonly string[] | null;
+    /** A bar/histogram source's bar `[begin, end)` spans (see {@link RowLayer.binIntervals}). */
+    binIntervals?(): readonly Interval[] | null;
 }
 /**
  * One selection — what {@link RowLayer.hitTest} returns and `onSelect` reports.
@@ -423,6 +488,16 @@ export interface SelectInfo {
     readonly color: string;
     /** Display label (`as` ?? column ?? id) — labels the selection in a readout. */
     readonly label: string;
+    /**
+     * An optional **stable per-mark identity within the layer** — a *category's
+     * column name* on the categorical axis, where every bar shares the layer's
+     * `id` but each column needs its own stable handle. When present, the
+     * highlight match + controlled `selected` echo key on `(id, mark)` instead of
+     * the sample `key`, so a pinned selection survives a column reorder / data
+     * update (the slot index is not stable; the column name is). `undefined` for
+     * marks whose sample `key` is already their identity (a time / value bar).
+     */
+    readonly mark?: string;
 }
 /** The hover snapshot handed to `onTrackerChanged` — the cursor time + every
  *  series' value there, so a consumer can render the readout outside the chart. */
@@ -446,7 +521,7 @@ export interface TrackerInfo {
  *   time pinned to the x-axis. The ChartIQ / trading-terminal readout. Values
  *   snap to the series (the axis pills read like ticks), not the raw mouse Y.
  */
-export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag' | 'crosshair';
+export type CursorMode = 'none' | 'line' | 'point' | 'inline' | 'flag' | 'crosshair' | 'region';
 /** A registered layer plus the axis id it draws against. */
 export interface LayerEntry {
     readonly layer: RowLayer;