@pond-ts/charts 0.42.0 → 0.44.0

package/dist/ScatterChart.d.ts

@@ -1,8 +1,21 @@
-import type { SeriesSchema, TimeSeries } from 'pond-ts';
+import { ValueSeries } from 'pond-ts';
+import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
 import { type ColorEncoding, type RadiusEncoding } from './encoding.js';
-export interface ScatterChartProps<S extends SeriesSchema> {
-    /** The source series. Its key column supplies the time axis (each point's x). */
-    series: TimeSeries<S>;
+export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
+    /**
+     * The source series. A `TimeSeries` scatters against the time axis; a
+     * `ValueSeries` (`series.byValue('cumDist')`, or `ValueSeries.fromColumns`
+     * for natively value-keyed data — IV marks keyed by strike) against its
+     * value axis — the container infers which from the data, no axis-type prop
+     * (mirrors `<LineChart>`). Either way the key / axis column supplies each
+     * point's x and `column` supplies y.
+     *
+     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call,
+     * so passing `series={s.byValue('dist')}` inline re-registers this layer
+     * every render — memoize the projection (`useMemo`) on a frequently
+     * re-rendering chart.
+     */
+    series: TimeSeries<S> | ValueSeries<VS>;
     /** Name of the numeric value column — each point's y. */
     column: string;
     /**
@@ -24,6 +37,11 @@ export interface ScatterChartProps<S extends SeriesSchema> {
      * the key the controlled `selected` echo, dedup, and (later) multi-select all
      * match on — so a selection survives a data update where a sample `key` goes
      * stale.
+     *
+     * A point's identity within the series is its **x** (key / axis value). The
+     * key contract allows duplicate x's (equal timestamps; a value-axis plateau
+     * from `byValue('cumDist')`) — points sharing an x share identity, so
+     * selecting one highlights the last drawn point at that x.
      */
     id?: string;
     /**
@@ -59,6 +77,14 @@ export interface ScatterChartProps<S extends SeriesSchema> {
      * dense scatter is noise; this is for a handful of called-out marks.
      */
     label?: string | boolean;
+    /**
+     * A **pixel** shift applied to every point's x — zoom-stable. **Default `0`.**
+     * For pairing marks that share a key side by side (a call and a put mark at one
+     * strike: `offset={-4}` / `offset={+4}`). Pairs with `<BoxPlot offset>`; on the
+     * scatter the shift is exact — both the draw and the click hit-test move
+     * together, so a nudged point still selects.
+     */
+    offset?: number;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -66,7 +92,8 @@ export interface ScatterChartProps<S extends SeriesSchema> {
     index?: number;
 }
 /**
- * A scatter draw layer: one mark per finite point at `(time, column-value)`,
+ * A scatter draw layer: one mark per finite point at `(x, column-value)`
+ * — x from the series' key / axis column (time or value axis) —
  * with **data-driven radius + colour** (the signed-off exception — encode from
  * columns via scales, not a per-event style callback). Reads `column` into a
  * {@link ChartSeries} (gaps as NaN → no mark), registers into the enclosing
@@ -92,5 +119,5 @@ export interface ScatterChartProps<S extends SeriesSchema> {
  * </Layers>
  * ```
  */
-export declare function ScatterChart<S extends SeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, index, }: ScatterChartProps<S>): null;
+export declare function ScatterChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, offset, index, }: ScatterChartProps<S, VS>): null;
 //# sourceMappingURL=ScatterChart.d.ts.map

package/dist/ScatterChart.js

@@ -1,11 +1,13 @@
 import { useContext, useEffect, useMemo } from 'react';
-import { fromTimeSeries } from './data.js';
+import { ValueSeries } from 'pond-ts';
+import { fromTimeSeries, fromValueSeries } from './data.js';
 import { drawScatter, hitTestScatter, nearestIndex, scatterExtent, } from './scatter.js';
 import { resolveEncoding, } from './encoding.js';
 import { ContainerContext, LayersContext } from './context.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
- * A scatter draw layer: one mark per finite point at `(time, column-value)`,
+ * A scatter draw layer: one mark per finite point at `(x, column-value)`
+ * — x from the series' key / axis column (time or value axis) —
  * with **data-driven radius + colour** (the signed-off exception — encode from
  * columns via scales, not a per-event style callback). Reads `column` into a
  * {@link ChartSeries} (gaps as NaN → no mark), registers into the enclosing
@@ -31,7 +33,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, index = 0, }) {
+export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, offset = 0, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<ScatterChart> must be rendered inside a <ChartContainer>');
@@ -40,7 +42,9 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
     if (layers === null) {
         throw new Error('<ScatterChart> must be rendered inside a <Layers>');
     }
-    const cs = useMemo(() => fromTimeSeries(series, column), [series, column]);
+    const cs = useMemo(() => series instanceof ValueSeries
+        ? fromValueSeries(series, column)
+        : fromTimeSeries(series, column), [series, column]);
     // Styling: semantic identifier → theme scatter style. The single styling
     // channel for the base mark.
     const { scatter } = container.theme;
@@ -53,13 +57,26 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
     // pulls a named numeric column to a Float64Array (gaps NaN) — the same path
     // fromTimeSeries uses; an unknown / non-numeric column throws there (eager,
     // so a typo surfaces at render, not silently as base-styled points).
-    const encoding = useMemo(() => resolveEncoding(cs, style.radius, style.color, radius, color, (col) => fromTimeSeries(series, col).y), [cs, style.radius, style.color, radius, color, series]);
+    const encoding = useMemo(() => resolveEncoding(cs, style.radius, style.color, radius, color, (col) => series instanceof ValueSeries
+        ? fromValueSeries(series, col).y
+        : fromTimeSeries(series, col).y), [cs, style.radius, style.color, radius, color, series]);
     // Per-point label accessor: a column name reads that field, `true` reads the
     // plotted column, anything else (false / omitted) ⇒ no labels.
     const labelAt = useMemo(() => {
         if (label === undefined || label === false)
             return undefined;
         const field = label === true ? column : label;
+        if (series instanceof ValueSeries) {
+            // Columnar read — a ValueSeries has no per-row events. The field is a
+            // runtime string, cast onto the schema-literal column name (the same
+            // pattern as data.ts' readValueColumn). A gap or an unknown column reads
+            // undefined => no label at that point.
+            const col = series.column(field);
+            return (i) => {
+                const v = col?.read(i);
+                return v === undefined || v === null ? undefined : String(v);
+            };
+        }
         return (i) => {
             // series.at(i) is O(1) per row (columnar eventAt cache), so a label per
             // point stays cheap. The field is a runtime string → cast off the literal-
@@ -71,26 +88,28 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
             return v === undefined || v === null ? undefined : String(v);
         };
     }, [label, column, series]);
-    // The point's stable key is its event begin (epoch ms) — the same as cs.x[i],
-    // which is the key column's begin buffer. Used for selection identity.
+    // The point's stable key is its x — the event begin (epoch ms) on a time
+    // axis, the axis value on a value axis; either way it's cs.x[i], the key
+    // column's begin buffer. Used for selection identity.
     const keyAt = useMemo(() => (i) => cs.x[i], [cs]);
     const entry = useMemo(() => ({
         layer: {
             yExtent: () => scatterExtent(cs),
-            xKind: 'time',
+            // The container infers the shared x scale's kind + auto-fit domain from
+            // its layers: a ValueSeries scatters 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]],
-            sampleAt: (time) => {
+            sampleAt: (x) => {
                 // No readout past the data (tracker policy — the dot snaps to a drawn
-                // mark, never extrapolates past the span); bounds from the time axis.
-                if (cs.length === 0 ||
-                    time < cs.x[0] ||
-                    time > cs.x[cs.length - 1]) {
+                // mark, never extrapolates past the span); bounds from the columnar x
+                // axis (epoch ms or axis value — the bisect doesn't care).
+                if (cs.length === 0 || x < cs.x[0] || x > cs.x[cs.length - 1]) {
                     return [];
                 }
                 // Nearest *drawn* point by index (skips gaps) — O(log N). Reading by
                 // index gives the value, the snap-to x, and the encoded colour in one
                 // shot, so the readout swatch matches the mark the user sees.
-                const i = nearestIndex(cs, time);
+                const i = nearestIndex(cs, x);
                 if (i < 0)
                     return [];
                 return [
@@ -108,9 +127,9 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
             ...(id === undefined
                 ? {}
                 : {
-                    hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, id, seriesLabel),
+                    hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, id, seriesLabel, offset),
                 }),
-            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id),
+            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id, offset),
         },
         axisId: axis,
         index,
@@ -126,6 +145,7 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
         labelAt,
         font,
         container.selected,
+        offset,
         axis,
         index,
     ]);

package/dist/XAxis.js

@@ -8,6 +8,36 @@ const TICK_STRIP = 22;
 /** Extra height reserved for an axis `label` line. */
 const LABEL_STRIP = 16;
 const TICK_COUNT = 5;
+/**
+ * Thin + truncate a **category** axis's labels so a dense axis stays legible: keep
+ * every `stride`-th label (so a kept label has room), and ellipsize one that still
+ * overruns its space. `stride` grows with the longest label vs the per-category
+ * slot width, so a few short categories keep every full label and many long ones
+ * decimate. A rough `fontSize`-based width estimate (no DOM measure) — good enough
+ * for placement; the exact metric is the browser's. Rotation is a later option.
+ */
+function thinCategoryLabels(ticks, plotWidth, fontSize) {
+    const n = ticks.length;
+    const slot = plotWidth / n; // per-category width in px
+    // Before first layout `plotWidth` is 0 → `slot` is 0 and the stride/room math
+    // below goes to Infinity/NaN. Nothing is visible at zero width anyway, so pass
+    // the ticks through untouched until a real width arrives.
+    if (!(slot > 0))
+        return [...ticks];
+    const charW = fontSize * 0.62; // ~average glyph advance
+    const longest = Math.min(12, ticks.reduce((m, t) => Math.max(m, t.label.length), 1));
+    const stride = Math.max(1, Math.ceil((longest * charW) / slot));
+    const room = Math.max(1, Math.floor((slot * stride) / charW));
+    const out = [];
+    for (let i = 0; i < n; i += stride) {
+        const s = ticks[i].label;
+        out.push({
+            x: ticks[i].x,
+            label: s.length <= room ? s : `${s.slice(0, Math.max(1, room - 1))}…`,
+        });
+    }
+    return out;
+}
 /**
  * The shared **x axis**, a sibling of {@link YAxis} for the horizontal axis. A
  * child of {@link ChartContainer}, rendered as DOM chrome (crisp text,
@@ -39,7 +69,11 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // (a time specifier through the time scale, a number specifier through the
     // value scale); otherwise the container's shared formatter — the one the
     // cursor readout uses, so a tick and the cursor read identically.
-    const fmt = format === undefined
+    const fmt = 
+    // A category axis labels by name (the container's `formatTime` = the band
+    // scale's label lookup); a d3 number/time `format` can't name a category, so
+    // it's ignored here (customize the labels in the `categories` data instead).
+    format === undefined || xKind === 'category'
         ? formatTime
         : xKind === 'time'
             ? resolveTimeFormat(xScale, TICK_COUNT, format)
@@ -90,12 +124,17 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
         markerLanes.set(t.id, lane);
     }
     const maxPillLane = Math.max(0, pillLaneEnds.length - 1);
-    const placed = customTicks
+    const rawTicks = customTicks
         ? customTicks.map((t) => ({ x: xScale(t.at), label: t.label }))
         : xScale.ticks(TICK_COUNT).map((d) => ({
             x: xScale(d),
             label: fmt(+d),
         }));
+    // A category axis ticks once per category; thin + truncate its labels when they
+    // crowd (an explicit `customTicks` axis keeps its labels verbatim).
+    const placed = xKind === 'category' && customTicks === undefined && rawTicks.length > 1
+        ? thinCategoryLabels(rawTicks, plotWidth, theme.font.size)
+        : rawTicks;
     const onTop = side === 'top';
     // Axis pills (marker / crosshair) sit at the same offset as the tick labels so
     // they line up with their tick-label neighbours (matches `labelOffset` below).

package/dist/annotations.d.ts

@@ -1,4 +1,4 @@
-import { type AnnotationSpec, type LabelPlacement } from './context.js';
+import { type AnnotationSpec, type ContainerFrame, type LabelPlacement } from './context.js';
 /**
  * Lane placement for the **top-flag** labels (markers + regions). Returns, per
  * slot key, its {@link LabelPlacement}. Baselines (label anchored at their own y)
@@ -16,6 +16,21 @@ import { type AnnotationSpec, type LabelPlacement } from './context.js';
  *   label) so the static labels hold their lanes as it crosses them.
  */
 export declare function computeLabelLanes(annotations: readonly AnnotationSpec[], toPixel: (axisX: number) => number, draggingKey?: symbol | null): Map<symbol, LabelPlacement>;
+/**
+ * Snap a dragged plot-pixel `px` to the nearest **guideline** within
+ * {@link SNAP_PX} — another annotation's x, **or** a trading-axis **disjoint
+ * boundary** (a session collapse point). Returns the **axis** value to snap to,
+ * or `null` if none is near (the caller keeps the raw position). Excludes the
+ * dragging mark's own `key`, and reads the same registry the guides draw from,
+ * so a drag visibly clicks onto the lines you can see.
+ *
+ * At a disjoint boundary the close and the next open share a pixel, so the value
+ * depends on which side of it the pointer is on (see below). Nearest-pixel wins
+ * across both kinds of target, so an annotation sitting *exactly* on a boundary
+ * open ties and — processed first — takes it (its own guideline), which is the
+ * same instant the right-side heuristic would pick anyway.
+ */
+export declare function snapToGuides(container: ContainerFrame, selfKey: symbol, px: number): number | null;
 /**
  * Order two region bounds so `from ≤ to`. A region **edge resize** pivots around
  * the *opposite* (fixed) edge: the dragged value `v` and the pivot are ordered
@@ -28,6 +43,27 @@ export declare function orderRegion(v: number, pivot: number): {
     from: number;
     to: number;
 };
+/** The slice of a scale a rigid pixel-move needs: value → pixel and back.
+ *  `invert` may return a `Date` (a d3 `scaleTime`) — the move coerces with `+`. */
+interface InvertibleScale {
+    (value: number): number;
+    invert(pixel: number): number | Date;
+}
+/**
+ * Translate a region's `[from, to]` by `dpx` **plot-pixels** through `scale`, so
+ * the box moves rigidly in *pixel* space — each edge's pixel position shifts by
+ * the same `dpx`, then inverts back to an axis value.
+ *
+ * This is the move that stays correct on a **discontinuous** (trading-time) axis:
+ * a shared *value* delta (`from + Δt`) would move the two edges by unequal pixels
+ * when they sit in different gap-contexts, distorting the box as it crosses a
+ * collapsed gap. On a continuous (affine) scale it is identical to the value-delta
+ * move, so this is a no-op there.
+ */
+export declare function moveRegionByPixels(scale: InvertibleScale, from: number, to: number, dpx: number): {
+    from: number;
+    to: number;
+};
 export interface MarkerProps {
     /** x position in axis units — epoch ms on a time axis, the value on a value
      *  axis. (The generalisation of the mockup's "time line": a mark at an x, time
@@ -157,4 +193,5 @@ export interface RegionProps {
 /** A shaded span over an x range — a lap, a zone, a selected interval. Its label
  *  flies as a flag off the left edge. */
 export declare function Region({ from, to, label, id, selected, selectable, hovered, editing, onChange, edges, }: RegionProps): import("react/jsx-runtime").JSX.Element;
+export {};
 //# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.js

@@ -257,13 +257,20 @@ function useAnnotationHover(container, id, hovered) {
 /** Pixel radius within which a drag snaps to a guideline (another mark's x). */
 const SNAP_PX = 6;
 /**
- * Snap a dragged plot-pixel `px` to the nearest **guideline** — another
- * annotation's x — within {@link SNAP_PX}. Returns that guideline's **axis** value
- * to snap to, or `null` if none is near (the caller keeps the raw position).
- * Excludes the dragging mark's own `key`, and reads the same registry the guides
- * draw from, so a drag visibly clicks onto the lines you can see.
+ * Snap a dragged plot-pixel `px` to the nearest **guideline** within
+ * {@link SNAP_PX} — another annotation's x, **or** a trading-axis **disjoint
+ * boundary** (a session collapse point). Returns the **axis** value to snap to,
+ * or `null` if none is near (the caller keeps the raw position). Excludes the
+ * dragging mark's own `key`, and reads the same registry the guides draw from,
+ * so a drag visibly clicks onto the lines you can see.
+ *
+ * At a disjoint boundary the close and the next open share a pixel, so the value
+ * depends on which side of it the pointer is on (see below). Nearest-pixel wins
+ * across both kinds of target, so an annotation sitting *exactly* on a boundary
+ * open ties and — processed first — takes it (its own guideline), which is the
+ * same instant the right-side heuristic would pick anyway.
  */
-function snapToGuides(container, selfKey, px) {
+export function snapToGuides(container, selfKey, px) {
     // The container's snap toggle gates guideline snapping — off ⇒ the drag keeps
     // its raw position (no clicking onto neighbours).
     if (!container.snap)
@@ -281,6 +288,23 @@ function snapToGuides(container, selfKey, px) {
             }
         }
     }
+    // Disjoint boundaries: on a trading-time axis a session close and the next
+    // open collapse to the **same pixel**, so a boundary is one snap target with
+    // two possible instants. Snap to the one on the side of the boundary the
+    // pointer is on — left of it → the pre-gap edge (the previous session's
+    // *close*, `clampDown` out of the gap); at/right of it → the post-gap *open*.
+    const disc = container.discontinuities;
+    if (disc?.boundaries) {
+        const [d0, d1] = container.timeRange;
+        for (const open of disc.boundaries(d0, d1)) {
+            const bpx = container.xScale(open);
+            const d = Math.abs(bpx - px);
+            if (d < bestDist) {
+                bestDist = d;
+                best = px < bpx ? disc.clampDown(open - 1) : open;
+            }
+        }
+    }
     return best;
 }
 /**
@@ -294,6 +318,23 @@ function snapToGuides(container, selfKey, px) {
 export function orderRegion(v, pivot) {
     return v <= pivot ? { from: v, to: pivot } : { from: pivot, to: v };
 }
+/**
+ * Translate a region's `[from, to]` by `dpx` **plot-pixels** through `scale`, so
+ * the box moves rigidly in *pixel* space — each edge's pixel position shifts by
+ * the same `dpx`, then inverts back to an axis value.
+ *
+ * This is the move that stays correct on a **discontinuous** (trading-time) axis:
+ * a shared *value* delta (`from + Δt`) would move the two edges by unequal pixels
+ * when they sit in different gap-contexts, distorting the box as it crosses a
+ * collapsed gap. On a continuous (affine) scale it is identical to the value-delta
+ * move, so this is a no-op there.
+ */
+export function moveRegionByPixels(scale, from, to, dpx) {
+    return {
+        from: +scale.invert(scale(from) + dpx),
+        to: +scale.invert(scale(to) + dpx),
+    };
+}
 /** A label chip — the cursor value flag's shape (shared {@link flagChipStyle}:
  *  filled, no outline) with text in the annotation register. */
 function Chip({ theme, color, style, children, }) {
@@ -550,25 +591,27 @@ export function Region({ from, to, label, id, selected = false, selectable = tru
                                     const s = dragRef.current;
                                     if (s === null)
                                         return;
-                                    // Raw position = start + TOTAL pointer delta (snap-independent),
-                                    // so dragging past SNAP_PX escapes a snapped edge.
-                                    const delta = +container.xScale.invert(px) -
-                                        +container.xScale.invert(s.startPx);
-                                    let nf = s.from + delta;
-                                    let nt = s.to + delta;
-                                    // Snap whichever edge lands near a guideline, keeping the width —
-                                    // output only, so the raw drift above can pull free of it.
-                                    const sf = snapToGuides(container, selfKey, container.xScale(nf));
-                                    const st = snapToGuides(container, selfKey, container.xScale(nt));
-                                    if (sf !== null) {
-                                        nt += sf - nf;
-                                        nf = sf;
-                                    }
-                                    else if (st !== null) {
-                                        nf += st - nt;
-                                        nt = st;
-                                    }
-                                    onChange?.({ from: nf, to: nt });
+                                    // Rigid move by the TOTAL pointer *pixel* delta from the press
+                                    // origin — each edge shifts the same pixels through the scale, so
+                                    // the box holds its shape even across a collapsed gap (a shared
+                                    // value-delta would drift the edges apart there).
+                                    const moved = moveRegionByPixels(container.xScale, s.from, s.to, px - s.startPx);
+                                    // Snap either edge to a guideline, shifting BOTH by the same pixel
+                                    // correction so the box keeps its width; snap-independent, so a
+                                    // drag past SNAP_PX releases cleanly.
+                                    const fpx = container.xScale(moved.from);
+                                    const tpx = container.xScale(moved.to);
+                                    const sf = snapToGuides(container, selfKey, fpx);
+                                    const st = snapToGuides(container, selfKey, tpx);
+                                    const d = sf !== null
+                                        ? container.xScale(sf) - fpx
+                                        : st !== null
+                                            ? container.xScale(st) - tpx
+                                            : 0;
+                                    onChange?.({
+                                        from: +container.xScale.invert(fpx + d),
+                                        to: +container.xScale.invert(tpx + d),
+                                    });
                                 } }), editable && (_jsxs(_Fragment, { children: [_jsx(DragArea, { x: xa - EDGE_GRAB / 2, y: 0, w: EDGE_GRAB, h: h, cursor: "ew-resize", editable: editable, onHover: reportHover, onSelect: select, onEdit: edit, onDragActive: (a) => container.setDragging(a ? selfKey : null), onDragStart: () => {
                                             edgeRef.current = to; // the fixed pivot = the far edge
                                         }, onDrag: (px) => onChange?.(orderRegion(snapToGuides(container, selfKey, px) ??

package/dist/bandScale.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A d3-scale-shaped **ordinal band scale** for a categorical x-axis — the
+ * transpose view's "columns on x" (categorical-axis RFC, Phase 1). It exposes the
+ * slice of the d3 scale surface `@pond-ts/charts` actually uses, so it drops in
+ * wherever the container's `xScale` goes (the same trick {@link TradingTimeScale}
+ * uses for a discontinuous time axis).
+ *
+ * **Numeric slot-index domain (the load-bearing choice).** The domain is
+ * `[0, n]` — one unit slot per category, slot `i` occupying `[i, i+1]` — *not* a
+ * `string[]`. So the pixel **mapping stays linear** and the container's numeric
+ * domain / auto-fit / `range` pipeline is untouched; a bar layer draws each
+ * category with the ordinary `barSpanPx(i, i+1, …)`. The category-ness lives in
+ * three methods only:
+ *
+ * - {@link ScaleBand.ticks} → the band **centres** (`i + 0.5`), one per category;
+ * - {@link ScaleBand.invert} → snaps a pixel to the nearest slot's centre (the
+ *   categorical crosshair UX, and it keeps the `+xScale.invert` call sites happy);
+ * - {@link ScaleBand.label} → the category name at a slot (the axis formatter).
+ *
+ * The category labels are carried alongside for {@link ScaleBand.label}; the
+ * numeric domain is authoritative for geometry.
+ */
+export interface ScaleBand {
+    /** Slot value (`i` = left edge, `i + 0.5` = centre) → pixel. Linear. */
+    (value: number): number;
+    /** Pixel → the nearest slot's **centre** value (`i + 0.5`), clamped to a real slot. */
+    invert(pixel: number): number;
+    /** One tick per category, at its band **centre** (`i + 0.5`). */
+    ticks(count?: number): number[];
+    /**
+     * A formatter mapping a slot value → the category name (the numeric `specifier`
+     * is ignored — a category axis labels by name, not a number format). Present so
+     * the scale is a safe drop-in wherever the container resolves a `tickFormat`.
+     */
+    tickFormat(count?: number, specifier?: string): (value: number) => string;
+    /** One slot's width in pixels (`|range| / slots`). The bar's `gap` insets within it. */
+    bandwidth(): number;
+    /** Slot pitch in pixels — same as {@link bandwidth} (padding is the bar's `gap`). */
+    step(): number;
+    /** The category name at slot value `v` (`categories[floor(v)]`), or `''`. */
+    label(value: number): string;
+    domain(): [number, number];
+    domain(next: readonly [number, number]): ScaleBand;
+    range(): [number, number];
+    range(next: readonly [number, number]): ScaleBand;
+    copy(): ScaleBand;
+}
+/**
+ * Build a {@link ScaleBand} over an ordered list of category names. Configure like
+ * a d3 scale: `scaleBand(tickers).domain([0, n]).range([0, width])` — the
+ * container sets `domain([0, n])` from the layer's slot extent and `range([0,
+ * plotWidth])`. `categories` supplies the labels; the domain drives the geometry,
+ * so the two must agree on count (`categories.length === n`), which they do when
+ * both come from the same layer's `xCategories()` / slot extent.
+ */
+export declare function scaleBand(categories: readonly string[]): ScaleBand;
+//# sourceMappingURL=bandScale.d.ts.map

package/dist/bandScale.js

@@ -0,0 +1,67 @@
+import { scaleLinear } from 'd3-scale';
+/**
+ * Build a {@link ScaleBand} over an ordered list of category names. Configure like
+ * a d3 scale: `scaleBand(tickers).domain([0, n]).range([0, width])` — the
+ * container sets `domain([0, n])` from the layer's slot extent and `range([0,
+ * plotWidth])`. `categories` supplies the labels; the domain drives the geometry,
+ * so the two must agree on count (`categories.length === n`), which they do when
+ * both come from the same layer's `xCategories()` / slot extent.
+ */
+export function scaleBand(categories) {
+    let domain = [0, Math.max(1, categories.length)];
+    let range = [0, 1];
+    const lin = scaleLinear();
+    const sync = () => lin.domain(domain).range(range);
+    /** Slot count = the domain width (the container sets `[0, n]`). */
+    const slots = () => Math.max(0, Math.round(domain[1] - domain[0]));
+    const scale = ((value) => {
+        sync();
+        return lin(value);
+    });
+    scale.invert = (pixel) => {
+        sync();
+        const v = lin.invert(pixel);
+        const n = slots();
+        if (n === 0)
+            return domain[0];
+        // Snap to the nearest slot's centre, clamped to a real slot.
+        const i = Math.min(n - 1, Math.max(0, Math.floor(v - domain[0])));
+        return domain[0] + i + 0.5;
+    };
+    scale.ticks = () => {
+        const n = slots();
+        const out = [];
+        for (let i = 0; i < n; i += 1)
+            out.push(domain[0] + i + 0.5);
+        return out;
+    };
+    scale.bandwidth = () => {
+        const n = slots();
+        if (n === 0)
+            return 0;
+        return Math.abs((range[1] - range[0]) / n);
+    };
+    scale.step = scale.bandwidth;
+    scale.label = (value) => {
+        const i = Math.floor(value - domain[0]);
+        return i >= 0 && i < categories.length ? categories[i] : '';
+    };
+    scale.tickFormat = () => scale.label;
+    function domainFn(next) {
+        if (next === undefined)
+            return [domain[0], domain[1]];
+        domain = [next[0], next[1]];
+        return scale;
+    }
+    scale.domain = domainFn;
+    function rangeFn(next) {
+        if (next === undefined)
+            return [range[0], range[1]];
+        range = [next[0], next[1]];
+        return scale;
+    }
+    scale.range = rangeFn;
+    scale.copy = () => scaleBand(categories).domain(domain).range(range);
+    return scale;
+}
+//# sourceMappingURL=bandScale.js.map

package/dist/bars.d.ts

@@ -118,18 +118,33 @@ export interface StackStyle {
     readonly fills: readonly string[];
     readonly opacity: number;
     readonly outlineWidth: number;
+    /**
+     * Optional **per-bin** fill override, aligned index-for-index to the bins
+     * (bin `b` uses `binFills[b]`), taking precedence over the per-group
+     * {@link fills} for that whole bin. This is the single-series band case —
+     * colour each bar by its category (heart-rate / power zones, value bands) —
+     * so it's normally paired with a `G === 1` stack. A `null`/`undefined` entry
+     * falls back to the group fill.
+     */
+    readonly binFills?: readonly (string | undefined)[];
 }
 /** The narrowed selection / hover identity a stacked segment matches against:
- *  the series `id`, the bin's `begin` (its `key`), and the group (its `label`). */
+ *  the series `id`, the bin's `begin` (its `key`), and the group (its `label`).
+ *  When the series carries `marks` (the categorical axis), the match keys on the
+ *  stable `mark` (the column name) instead of the `key` slot index. */
 export interface StackMark {
     readonly id: string;
     readonly key: number;
     readonly label: string;
+    readonly mark?: string;
 }
 /**
- * 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.
@@ -162,8 +177,10 @@ export declare function segmentRect(ss: StackedBarSeries, b: number, g: number,
 /**
  * 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