@pond-ts/charts 0.42.0 → 0.43.0

package/dist/Layers.js

@@ -2,7 +2,8 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Children, cloneElement, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Canvas } from './Canvas.js';
 import { drawGrid, drawDividers, thinPixels } from './grid.js';
-import { cursorParts } from './tracker.js';
+import { TimeRange } from 'pond-ts';
+import { cursorParts, bandRect, regionSpan } from './tracker.js';
 import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
 import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
@@ -69,7 +70,9 @@ export function Layers({ children }) {
         // Explicit `<YAxis ticks>` drive the gridlines too, so they align with the
         // axis labels; otherwise d3 auto-picks (the default).
         const explicitY = tickValues.get(defaultAxisId);
-        const xTickVals = xScale.ticks(GRID_TICKS);
+        // A category axis draws no vertical gridlines — a line through each bar
+        // centre reads as noise; the bars are the structure.
+        const xTickVals = container.xKind === 'category' ? [] : xScale.ticks(GRID_TICKS);
         const xTicks = xTickVals.map((d) => xScale(+d));
         const yTicks = gridY
             ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
@@ -257,7 +260,29 @@ export function Layers({ children }) {
             }
             return;
         }
-        if (!c.panZoom)
+        // Region-cursor drag-select (opt-in via `onRegionSelect`, time axis only):
+        // anchor the selection at the press; the band then extends as the pointer
+        // moves (bucket by bucket with a sequence, freeform without), and release
+        // commits the range. A `regionSelectModifier` (only while `panZoom` is on)
+        // gates it behind the key so plain drag can still pan; otherwise it preempts
+        // pan (returns before the pan is armed below).
+        if (c.cursor === 'region' && c.onRegionSelect && c.xKind === 'time') {
+            const needsShift = c.regionSelectModifier === 'shift' && c.panZoom;
+            if (!needsShift || e.shiftKey) {
+                const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
+                c.setRegionAnchor(+c.xScale.invert(px));
+                c.setHoverX(px);
+                try {
+                    e.currentTarget.setPointerCapture(e.pointerId);
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            // Modifier required but not held → fall through to pan.
+        }
+        if (!c.panZoom || c.xKind === 'category')
             return;
         const r = c.timeRange;
         // Arm a potential pan: record the anchor, but DON'T capture the pointer or
@@ -287,6 +312,13 @@ export function Layers({ children }) {
             c.setHoverX(px); // share the preview x so other rows draw a guide there
             return;
         }
+        // Region drag in progress: just track the pointer x (the band spans from the
+        // anchor bucket to here); no pan, no hover hit-test.
+        if (c.regionAnchor !== null) {
+            const rect = e.currentTarget.getBoundingClientRect();
+            c.setHoverX(Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left)));
+            return;
+        }
         // A pan is only live while a button is held. A move with no buttons means
         // the press already ended without us seeing the pointerup — which the
         // deferred-capture path allows: an uncommitted (sub-slop) potential-pan
@@ -372,6 +404,22 @@ export function Layers({ children }) {
     }, []);
     const handlePointerUp = useCallback((e) => {
         const c = containerRef.current;
+        // End a region drag: commit the anchor→pointer span as a one-shot range,
+        // then clear the anchor (the cursor reverts to the single-bucket highlight).
+        if (c.regionAnchor !== null) {
+            const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
+            const span = regionSpan(c.cursorBuckets ?? [], c.regionAnchor, +c.xScale.invert(px));
+            c.setRegionAnchor(null);
+            try {
+                e.currentTarget.releasePointerCapture(e.pointerId);
+            }
+            catch {
+                /* ignore */
+            }
+            if (span)
+                c.onRegionSelect?.(new TimeRange({ start: span.start, end: span.end }));
+            return;
+        }
         if (c.creating !== null) {
             const rect = e.currentTarget.getBoundingClientRect();
             const px = Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left));
@@ -439,6 +487,10 @@ export function Layers({ children }) {
             c.setHoverY(null, null);
             return;
         }
+        // Cancel a region-drag on leave (no commit) — a safety net for the rare case
+        // where the pointer capture didn't take, so the anchor can't get stuck.
+        if (c.regionAnchor !== null)
+            c.setRegionAnchor(null);
         c.setHoverX(null);
         c.setHoverY(null, null);
         c.setHovered(null);
@@ -478,7 +530,7 @@ export function Layers({ children }) {
             return;
         const onWheel = (e) => {
             const c = containerRef.current;
-            if (!c.panZoom)
+            if (!c.panZoom || c.xKind === 'category')
                 return;
             e.preventDefault();
             const rect = el.getBoundingClientRect();
@@ -571,6 +623,22 @@ export function Layers({ children }) {
             side: axisSides.get(defaultAxisId) ?? 'left',
         };
     })();
+    // `region` cursor (time axis only): shade the span under the pointer. With a
+    // `cursorSequence` the band snaps to the bucket (and extends bucket by bucket
+    // under a drag); with none it's the **freeform** case — a bare hover draws a
+    // plain line (`regionLine`), a drag shades the raw `[anchor, pointer]`. Edges
+    // map through `xScale`, so on a trading-time axis the band crops to live time.
+    const regionActive = parts.band && container.xKind === 'time';
+    const band = regionActive && cursorTime !== null
+        ? bandRect(container.cursorBuckets ?? [], cursorTime, (v) => xScale(v), plotWidth, container.regionAnchor ?? undefined)
+        : null;
+    // Degenerate region cursor (no sequence, not mid-drag): a plain vertical line.
+    const regionLine = regionActive &&
+        container.cursorBuckets === undefined &&
+        container.regionAnchor === null &&
+        cursorX !== null &&
+        cursorX >= 0 &&
+        cursorX <= plotWidth;
     // Cross-row guide lines: the x-positions of annotations on the OTHER rows
     // (markers + region edges), so a mark on one row reads against this row's data +
     // the shared x axis. A mark's own row skips itself; baselines cast no vertical
@@ -638,7 +706,7 @@ export function Layers({ children }) {
                         top: 0,
                         left: 0,
                         pointerEvents: 'none',
-                    }, children: [parts.line &&
+                    }, children: [band !== null && (_jsx("rect", { x: band.x0, y: 0, width: band.x1 - band.x0, height: row.height, fill: cursorColor, opacity: 0.12 })), regionLine && cursorX !== null && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.line &&
                             cursorX !== null &&
                             cursorX >= 0 &&
                             cursorX <= plotWidth && (_jsx("line", { x1: Math.round(cursorX), y1: 0, x2: Math.round(cursorX), y2: row.height, stroke: cursorColor, strokeWidth: 1, shapeRendering: "crispEdges" })), parts.chip === 'flag' &&

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