@pond-ts/charts 0.58.0 → 0.59.0

package/dist/YAxis.js

@@ -17,7 +17,7 @@ const DEFAULT_TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -35,6 +35,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         // and layers still bind to it, which is the whole point of the prop.
         width: hide ? 0 : width,
         scale,
+        linearWindow,
         min,
         max,
         pad,
@@ -49,6 +50,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         width,
         hide,
         scale,
+        linearWindow,
         min,
         max,
         pad,

package/dist/bars.d.ts

@@ -55,7 +55,7 @@ export declare function resolveBarBaseline(yScale: Scale): number;
  * hit region are deliberately *not* the same geometry: the `gapPx` inset
  * separates columns visually without carving a dead channel out of the target.
  */
-export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number, maxWidthPx?: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
 /**
  * The value-space span `[lo, hi]` of **threshold band `k`** along a bar running
  * from `base` to `v`, or `null` when the bar doesn't reach that band.
@@ -306,6 +306,9 @@ export interface StackStyle {
     readonly fills: readonly string[];
     readonly opacity: number;
     readonly outlineWidth: number;
+    /** Cap on a segment's ink span in px, centred in the slot — the stacked
+     *  counterpart of `BarStyle.maxWidth` ([PND-BARWIDTH]). Omitted ⇒ uncapped. */
+    readonly maxWidth?: number;
     /**
      * Optional **per-bin** fill override, aligned index-for-index to the bins
      * (bin `b` uses `binFills[b]`), taking precedence over the per-group
@@ -457,7 +460,7 @@ export declare function stackBase(orientation: Orientation, xScale: Scale, yScal
  * is unfloored. Shared by {@link drawStacks} and {@link stackAt} so the drawn rect
  * and the hit rect are identical.
  */
-export declare function segmentRect(ss: StackedBarSeries, b: number, g: number, orientation: Orientation, xScale: Scale, yScale: Scale, cumBefore: number, gapPx: number, minSpanPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+export declare function segmentRect(ss: StackedBarSeries, b: number, g: number, orientation: Orientation, xScale: Scale, yScale: Scale, cumBefore: number, gapPx: number, minSpanPx: number, maxSpanPx?: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
 /**
  * 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
@@ -484,5 +487,9 @@ export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBar
  * O(N·G) over bins × groups (no spatial index — histogram bin/group counts are
  * small; click / hover are cheap events).
  */
-export declare function stackAt(ss: StackedBarSeries, px: number, py: number, orientation: Orientation, xScale: Scale, yScale: Scale, gapPx: number, minSpanPx: number): [bin: number, group: number, begin: number, name: string, value: number] | null;
+export declare function stackAt(ss: StackedBarSeries, px: number, py: number, orientation: Orientation, xScale: Scale, yScale: Scale, gapPx: number, minSpanPx: number, 
+/** Must match the draw's cap ([PND-BARWIDTH]) — this function's whole
+ *  contract is that its rect is the drawn rect, so a cap applied to one and
+ *  not the other silently drifts the hit target off the ink. */
+maxSpanPx?: number): [bin: number, group: number, begin: number, name: string, value: number] | null;
 //# sourceMappingURL=bars.d.ts.map

package/dist/bars.js

@@ -73,11 +73,11 @@ export function resolveBarBaseline(yScale) {
  * hit region are deliberately *not* the same geometry: the `gapPx` inset
  * separates columns visually without carving a dead channel out of the target.
  */
-export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
+export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx, maxWidthPx) {
     const v = cs.y[i];
     if (!Number.isFinite(v))
         return null;
-    const [x0, x1] = barSpanPx(cs.begin[i], cs.end[i], xScale, gapPx, minWidthPx);
+    const [x0, x1] = barSpanPx(cs.begin[i], cs.end[i], xScale, gapPx, minWidthPx, maxWidthPx);
     const yValue = yScale(v);
     const yBase = yScale(baseline);
     return [x0, x1, Math.min(yValue, yBase), Math.max(yValue, yBase)];
@@ -430,7 +430,7 @@ spans = NO_SPANS) {
         : null;
     let drawn = 0;
     for (let i = vStart; i < vEnd; i += 1) {
-        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth);
+        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth, style.maxWidth);
         if (rect === null)
             continue;
         const [x0, x1, yTop, yBottom] = rect;
@@ -779,7 +779,7 @@ export function stackBase(orientation, xScale, yScale) {
  * is unfloored. Shared by {@link drawStacks} and {@link stackAt} so the drawn rect
  * and the hit rect are identical.
  */
-export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx) {
+export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx, maxSpanPx) {
     const G = ss.groups.length;
     const v = ss.values[b * G + g];
     // Skip non-finite (a gap) or zero (a zero-extent rect that can't draw or be
@@ -801,12 +801,12 @@ export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, ga
     if (!Number.isFinite(v) || v === 0)
         return null;
     if (orientation === 'vertical') {
-        const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx);
+        const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx, maxSpanPx);
         const yA = yScale(cumBefore);
         const yB = yScale(cumBefore + v);
         return [x0, x1, Math.min(yA, yB), Math.max(yA, yB)];
     }
-    const [y0, y1] = barSpanPx(ss.begin[b], ss.end[b], yScale, gapPx, minSpanPx);
+    const [y0, y1] = barSpanPx(ss.begin[b], ss.end[b], yScale, gapPx, minSpanPx, maxSpanPx);
     const xA = xScale(cumBefore);
     const xB = xScale(cumBefore + v);
     return [Math.min(xA, xB), Math.max(xA, xB), y0, y1];
@@ -865,7 +865,7 @@ spans = NO_SPANS) {
         let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx, style.maxWidth);
             if (Number.isFinite(v)) {
                 if (v > 0)
                     cumPos += v;
@@ -1011,7 +1011,11 @@ spans = NO_SPANS) {
  * O(N·G) over bins × groups (no spatial index — histogram bin/group counts are
  * small; click / hover are cheap events).
  */
-export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx) {
+export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx, 
+/** Must match the draw's cap ([PND-BARWIDTH]) — this function's whole
+ *  contract is that its rect is the drawn rect, so a cap applied to one and
+ *  not the other silently drifts the hit target off the ink. */
+maxSpanPx) {
     const G = ss.groups.length;
     const base = stackBase(orientation, xScale, yScale);
     for (let b = 0; b < ss.length; b += 1) {
@@ -1021,7 +1025,7 @@ export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanP
         let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx, maxSpanPx);
             if (Number.isFinite(v)) {
                 if (v > 0)
                     cumPos += v;

package/dist/context.d.ts

@@ -1597,17 +1597,17 @@ export interface LayerEntry {
 }
 /** A y-axis declared in a {@link ChartRow} via `<YAxis>`. */
 /** Which scale a y axis maps its domain through. */
-export type YScaleKind = 'linear' | 'log';
+export type YScaleKind = 'linear' | 'log' | 'symlog';
 /**
- * A row's resolved y scale — d3's `scaleLinear()`, or `scaleLog()` when the
- * axis asks for `scale="log"`.
+ * A row's resolved y scale — d3's `scaleLinear()`, `scaleLog()` when the axis
+ * asks for `scale="log"`, or `scaleSymlog()` for `scale="symlog"`.
  *
  * Deliberately the **continuous-numeric** supertype rather than `ScaleLinear`:
  * every consumer (the axis labels, the row's gridlines, the cursor readout, and
  * every draw layer) only ever calls it, or reads `domain` / `range` / `ticks` /
- * `tickFormat` / `invert` — the surface both scales share. Keeping the shared
- * type here is what lets a log axis be transparent to the draw layers instead
- * of every layer growing a branch.
+ * `tickFormat` / `invert` — the surface all three scales share. Keeping the
+ * shared type here is what lets a log or symlog axis be transparent to the draw
+ * layers instead of every layer growing a branch.
  */
 export type YScale = ScaleContinuousNumeric<number, number>;
 export interface AxisSpec {
@@ -1617,6 +1617,11 @@ export interface AxisSpec {
     readonly width: number;
     /** Which scale the axis maps its domain through ({@link YAxisProps.scale}). */
     readonly scale: YScaleKind;
+    /** `scale="symlog"`'s linear window as a **fraction of the domain's largest
+     *  magnitude** ({@link YAxisProps.linearWindow}) — `undefined` on any other
+     *  scale. Domain-relative rather than absolute so it survives a domain change
+     *  without a recompute ([PND-SYMLOG]). */
+    readonly linearWindow?: number | undefined;
     /** Explicit domain bounds, or `undefined` to auto-fit linked layers. */
     readonly min: number | undefined;
     readonly max: number | undefined;

package/dist/data.d.ts

@@ -499,6 +499,44 @@ export interface CategoryDatum {
     readonly label: string;
     readonly value: number;
 }
+/**
+ * One category of a **stacked** category chart ([PND-CATSTACK]) — a label plus a
+ * value **per group**, read by name through `<BarChart columns>`.
+ *
+ * The `values` record is the shape the list family already uses
+ * (`ListRow.values`), deliberately: "a row with named values" is one concept in
+ * this library and a category with several groups is exactly that. A missing or
+ * non-finite entry reads as a gap, so a group absent from one category is a hole
+ * rather than a zero — the same rule every other reader applies.
+ */
+export interface CategoryStackDatum {
+    readonly label: string;
+    readonly values: Readonly<Record<string, number | undefined>>;
+}
+/**
+ * Build a {@link StackedBarSeries} from ordered categories carrying a value
+ * **per group** — the stacked counterpart of {@link categoryStack}
+ * ([PND-CATSTACK]).
+ *
+ * Geometry is identical to the single-value case (one unit slot `[i, i+1]` per
+ * category, `marks` carrying the names), so the categorical axis derives its
+ * ordered labels exactly as before and a pinned selection still keys on the
+ * stable name. Only `groups` and the `values` layout differ, and both match
+ * {@link stacksFromColumns} — `values[i * G + g]`, bin-major — so this reaches
+ * the shipped `drawStacks` path with no new draw code.
+ *
+ * **Why this replaces a real workaround.** Composing the same picture from one
+ * `<BarChart categories>` layer per cumulative total (drawn outermost-first so
+ * each overpaints the one beneath) costs three things a first-class stack does
+ * not: hand-assembled legends, label thinning that cannot see the other layers,
+ * and — since selection entries key on `(layer id, mark)` — a controlled set
+ * that must be replicated across every segment layer, where missing one makes a
+ * selected bar recede *from the waist up*. With one layer and one `mark` per
+ * bar, that last failure is not expressible.
+ *
+ * O(n·G) with one `Float64Array` allocation, matching `stacksFromColumns`.
+ */
+export declare function categoryStacks(records: readonly CategoryStackDatum[], columns: readonly string[]): StackedBarSeries;
 /**
  * Build a {@link StackedBarSeries} (single group, `G === 1`) from an ordered list
  * of `{ label, value }` categories — one **unit slot** `[i, i+1]` per category, in

package/dist/data.js

@@ -619,6 +619,49 @@ export function stacksFromBins(bins, columns, options = {}) {
     }
     return { begin, end, groups: columns, values, length: n };
 }
+/**
+ * Build a {@link StackedBarSeries} from ordered categories carrying a value
+ * **per group** — the stacked counterpart of {@link categoryStack}
+ * ([PND-CATSTACK]).
+ *
+ * Geometry is identical to the single-value case (one unit slot `[i, i+1]` per
+ * category, `marks` carrying the names), so the categorical axis derives its
+ * ordered labels exactly as before and a pinned selection still keys on the
+ * stable name. Only `groups` and the `values` layout differ, and both match
+ * {@link stacksFromColumns} — `values[i * G + g]`, bin-major — so this reaches
+ * the shipped `drawStacks` path with no new draw code.
+ *
+ * **Why this replaces a real workaround.** Composing the same picture from one
+ * `<BarChart categories>` layer per cumulative total (drawn outermost-first so
+ * each overpaints the one beneath) costs three things a first-class stack does
+ * not: hand-assembled legends, label thinning that cannot see the other layers,
+ * and — since selection entries key on `(layer id, mark)` — a controlled set
+ * that must be replicated across every segment layer, where missing one makes a
+ * selected bar recede *from the waist up*. With one layer and one `mark` per
+ * bar, that last failure is not expressible.
+ *
+ * O(n·G) with one `Float64Array` allocation, matching `stacksFromColumns`.
+ */
+export function categoryStacks(records, columns) {
+    const n = records.length;
+    const G = columns.length;
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    const values = new Float64Array(n * G);
+    const marks = new Array(n);
+    for (let i = 0; i < n; i += 1) {
+        begin[i] = i;
+        end[i] = i + 1;
+        marks[i] = records[i].label;
+        const row = records[i].values;
+        for (let g = 0; g < G; g += 1) {
+            const v = row[columns[g]];
+            // A missing key and a non-finite value are the same thing here: no bar.
+            values[i * G + g] = typeof v === 'number' && Number.isFinite(v) ? v : NaN;
+        }
+    }
+    return { begin, end, groups: columns, values, length: n, marks };
+}
 /**
  * Build a {@link StackedBarSeries} (single group, `G === 1`) from an ordered list
  * of `{ label, value }` categories — one **unit slot** `[i, i+1]` per category, in

package/dist/format.d.ts

@@ -47,6 +47,9 @@ interface Tickable {
     tickFormat(count: number, specifier?: string): (value: number) => string;
     /** Present on d3's `scaleLog` and on no other continuous scale. */
     base?: () => number;
+    /** Present on d3's `scaleSymlog` and on no other continuous scale — the linear
+     *  window's half-width in data units. */
+    constant?: () => number;
     domain?: () => number[];
 }
 /**
@@ -75,6 +78,18 @@ interface Tickable {
  * applies the specifier to whatever it is handed, which is what every consumer
  * of this function actually wants; the axis's own tick *thinning* is handled by
  * `yTickValues`, not here.
+ *
+ * **A symlog scale's precision comes from its knee, not its span** ([PND-SYMLOG]).
+ * `scaleSymlog.tickFormat` is `linearish`, so it derives precision from the
+ * domain — and a symlog axis is chosen precisely when the interesting values are
+ * *orders of magnitude smaller* than the domain. On `[-1, 1]` with a `0.02` knee
+ * the ladder emits `-0.02, 0, 0.02` and a span-derived formatter labels all three
+ * **`"0.0"`**: three ticks at three positions asserting the same value, on the
+ * axis whose whole purpose was to separate them. Formatting through a linear
+ * scale over `[-knee, knee]` calibrates to the smallest magnitude the ladder can
+ * emit. It changes nothing when the knee is already coarse (a 20k knee on a ±1M
+ * domain formats identically), and the cursor readout inherits the same extra
+ * precision — which is wanted, since near-zero is where a symlog readout is read.
  */
 export declare function resolveAxisFormat(scale: Tickable, count: number, format: AxisFormat | undefined): (value: number) => string;
 /** The slice of a d3 **time** scale {@link resolveTimeFormat} needs. A d3

package/dist/format.js

@@ -25,13 +25,28 @@ import { scaleLinear } from 'd3-scale';
  * applies the specifier to whatever it is handed, which is what every consumer
  * of this function actually wants; the axis's own tick *thinning* is handled by
  * `yTickValues`, not here.
+ *
+ * **A symlog scale's precision comes from its knee, not its span** ([PND-SYMLOG]).
+ * `scaleSymlog.tickFormat` is `linearish`, so it derives precision from the
+ * domain — and a symlog axis is chosen precisely when the interesting values are
+ * *orders of magnitude smaller* than the domain. On `[-1, 1]` with a `0.02` knee
+ * the ladder emits `-0.02, 0, 0.02` and a span-derived formatter labels all three
+ * **`"0.0"`**: three ticks at three positions asserting the same value, on the
+ * axis whose whole purpose was to separate them. Formatting through a linear
+ * scale over `[-knee, knee]` calibrates to the smallest magnitude the ladder can
+ * emit. It changes nothing when the knee is already coarse (a 20k knee on a ±1M
+ * domain formats identically), and the cursor readout inherits the same extra
+ * precision — which is wanted, since near-zero is where a symlog readout is read.
  */
 export function resolveAxisFormat(scale, count, format) {
     if (typeof format === 'function')
         return format;
+    const knee = typeof scale.constant === 'function' ? Math.abs(scale.constant()) : 0;
     const source = typeof scale.base === 'function' && typeof scale.domain === 'function'
         ? scaleLinear().domain(scale.domain())
-        : scale;
+        : Number.isFinite(knee) && knee > 0
+            ? scaleLinear().domain([-knee, knee])
+            : scale;
     return format !== undefined
         ? source.tickFormat(count, format)
         : source.tickFormat(count);

package/dist/index.d.ts

@@ -73,8 +73,8 @@ export type { RegionProps, BaselineProps, MarkerProps, ZoneProps, } from './anno
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, barsFromBins, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, transposeRow, } from './data.js';
-export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, StackedBarSeries, BinRecord, StacksFromBinsOptions, CategoryDatum, RowAt, TransposeRowOptions, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, barsFromBins, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, categoryStacks, transposeRow, } from './data.js';
+export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, StackedBarSeries, BinRecord, StacksFromBinsOptions, CategoryDatum, CategoryStackDatum, RowAt, TransposeRowOptions, } from './data.js';
 export type { Orientation } from './bars.js';
 export type { RadiusEncoding, ColorEncoding } from './encoding.js';
 export type { Curve } from './curve.js';

package/dist/index.js

@@ -68,6 +68,11 @@ export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeri
 stacksFromGroups, stacksFromColumns, stacksFromBins, 
 // Categorical row-read: one bar per `{ label, value }` on the category axis.
 categoryStack, 
+// …and its stacked sibling: one bar per `{ label, values }`, segments named by
+// `columns` ([PND-CATSTACK]). Public for the same reason every reader above is
+// — a caller assembling a `StackedBarSeries` by hand needs it — and because
+// API.md already documented it as public while `index.ts` did not export it.
+categoryStacks, 
 // The transpose reader — one row of a wide series read across into categories.
 transposeRow, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';

package/dist/range.d.ts

@@ -10,6 +10,19 @@
  * A span that the gap would invert (narrower than `minWidthPx` after the inset)
  * collapses to a `minWidthPx` mark centred in the slot, so a too-thin bucket
  * stays visible and the bar never flips inside-out.
+ *
+ * `maxWidthPx` caps the **ink** and is applied *after* the inset, centred in the
+ * slot ([PND-BARWIDTH]). It is the missing half of the width vocabulary: `gapPx`
+ * is a *relative* inset, so on its own bar width is always `slot - gap` and
+ * fattens with the slot. Two independent sizes — slots spreading to fill the
+ * plot, ink pinned to N px — is what makes a measure comparable **between**
+ * panes, since a bar that widens with its pane reads as a different weight of
+ * the same thing. Expressing that with the relative knob alone requires
+ * predicting the slot width and back-solving the gap, which re-derives this
+ * function's arithmetic in consumer code.
+ *
+ * `minWidthPx` still wins: a cap below the floor yields the floor, so the two
+ * bounds can never invert the rect.
  */
-export declare function barSpanPx(beginMs: number, endMs: number, xScale: (value: number) => number, gapPx?: number, minWidthPx?: number): [number, number];
+export declare function barSpanPx(beginMs: number, endMs: number, xScale: (value: number) => number, gapPx?: number, minWidthPx?: number, maxWidthPx?: number): [number, number];
 //# sourceMappingURL=range.d.ts.map

package/dist/range.js

@@ -10,15 +10,36 @@
  * A span that the gap would invert (narrower than `minWidthPx` after the inset)
  * collapses to a `minWidthPx` mark centred in the slot, so a too-thin bucket
  * stays visible and the bar never flips inside-out.
+ *
+ * `maxWidthPx` caps the **ink** and is applied *after* the inset, centred in the
+ * slot ([PND-BARWIDTH]). It is the missing half of the width vocabulary: `gapPx`
+ * is a *relative* inset, so on its own bar width is always `slot - gap` and
+ * fattens with the slot. Two independent sizes — slots spreading to fill the
+ * plot, ink pinned to N px — is what makes a measure comparable **between**
+ * panes, since a bar that widens with its pane reads as a different weight of
+ * the same thing. Expressing that with the relative knob alone requires
+ * predicting the slot width and back-solving the gap, which re-derives this
+ * function's arithmetic in consumer code.
+ *
+ * `minWidthPx` still wins: a cap below the floor yields the floor, so the two
+ * bounds can never invert the rect.
  */
-export function barSpanPx(beginMs, endMs, xScale, gapPx = 0, minWidthPx = 1) {
+export function barSpanPx(beginMs, endMs, xScale, gapPx = 0, minWidthPx = 1, maxWidthPx) {
     const a = xScale(beginMs);
     const b = xScale(endMs);
     const lo = Math.min(a, b);
     const hi = Math.max(a, b);
     const inset = gapPx / 2;
-    const x0 = lo + inset;
-    const x1 = hi - inset;
+    let x0 = lo + inset;
+    let x1 = hi - inset;
+    // The cap reads on the INSET span, not the raw slot, so `gap` keeps its
+    // meaning as the minimum breathing room: a bar is never wider than the gap
+    // allows, and never wider than the cap, whichever binds first.
+    if (maxWidthPx !== undefined && maxWidthPx > 0 && x1 - x0 > maxWidthPx) {
+        const mid = (lo + hi) / 2;
+        x0 = mid - maxWidthPx / 2;
+        x1 = mid + maxWidthPx / 2;
+    }
     if (x1 - x0 >= minWidthPx)
         return [x0, x1];
     const mid = (lo + hi) / 2;

package/dist/theme.d.ts

@@ -296,10 +296,14 @@ export interface ChartTheme {
      *
      * So the two values here are the ones with no canvas counterpart: the row
      * **band** tints. Everything else resolves from tokens that already exist
-     * and are per-metric where they should be — a selected fill takes
-     * {@link BarStyle.highlight}, a dimmed one {@link BarStyle.dimmed} — so a
-     * consumer who themes their bars gets a coherent list without theming it
-     * twice.
+     * and are per-metric where they should be — a selected glyph fill takes
+     * `bar[as].highlight` and a dimmed one `bar[as].dimmed` — so a consumer who
+     * themes their bars gets a coherent list without theming it twice.
+     *
+     * **To be unambiguous, because this reads as a list of fields on this
+     * block:** `highlight` / `dimmed` are **`BarStyle`** tokens, resolved through
+     * `theme.bar[as]`. They are not fields of `theme.list` and there is no
+     * `list.dimmed` — this register carries exactly the five values below.
      *
      * **The rail is deliberately NOT per-metric.** There is one rail per row
      * and a row may carry several metrics, so it cannot resolve through
@@ -730,6 +734,28 @@ export interface BarStyle {
     readonly highlight: string;
     readonly gap: number;
     readonly minWidth: number;
+    /**
+     * Cap on a bar's **ink** width in px, applied after the `gap` inset and
+     * centred in the slot ([PND-BARWIDTH]). **Omitted ⇒ uncapped** — a bar is
+     * `slot - gap` wide, as it always was.
+     *
+     * It is the missing half of the width vocabulary, and the reason it cannot be
+     * spelled with `gap` alone: `gap` is a *relative* inset, so bar width tracks
+     * the slot and fattens as the plot widens. A **fixed** ink width is what makes
+     * a measure comparable *between* panes — bars that widen with their pane read
+     * as different weights of the same thing. Wanting both (slots spreading to
+     * fill, ink pinned) needs two independent knobs; with one, a consumer has to
+     * predict the slot width and back-solve the gap, re-deriving pond's own layout
+     * arithmetic in their code.
+     *
+     * Pairs with `<ChartContainer maxBandWidth>`, which caps the **slot**: that
+     * one decides how far the bars spread, this one how wide the ink is inside
+     * whatever slot results. `minWidth` still wins if the two would invert.
+     *
+     * `<BarChart maxBarWidth>` overrides this per layer, the same relationship
+     * `gap` has.
+     */
+    readonly maxWidth?: number;
     readonly outlineWidth: number;
     /**
      * Optional distinct **hover** fill, so a bar can read a three-step emphasis —
@@ -757,6 +783,11 @@ export interface BarStyle {
      *   both states so a red/green volume bar keeps its meaning while live —
      *   the one *design* exclusion rather than a path consequence.
      *
+     * **Scope note: that `binColors` exclusion is about the LIVE states only.**
+     * It does not carry over to {@link dimmed}, which *replaces* a per-bar fill
+     * on an unselected bar — see that token, which spells out the asymmetry and
+     * why emphasis preserves a per-bar colour while recession suppresses it.
+     *
      * The **decimated** dense-bar pass also draws the flat fill only, as it
      * already did for `highlight`.
      */
@@ -859,6 +890,29 @@ export interface BarStyle {
      * component, and drifted immediately — one consumer had three charts using
      * `color-mix` at 22%, 28% and 30% for the same concept, in the same week, for
      * no reason. One theme value fixes that permanently.
+     *
+     * **It OVERRIDES a per-bar fill, unlike the live states.** This is the one
+     * place `dimmed` and {@link hover} deliberately disagree, and the asymmetry
+     * is easy to read the wrong way round:
+     *
+     * - **{@link binColors} / {@link binFills}:** an unselected bar paints
+     *   `dimmed`, discarding its own colour. (Hover and selection do the
+     *   opposite — they keep the per-bar colour and pop the alpha, so a
+     *   red/green volume bar stays red/green while live.)
+     * - **{@link bands} / thresholds:** an unselected banded bar draws **flat**
+     *   in `dimmed`, discarding the ladder entirely rather than dimming each
+     *   band.
+     * - **A multi-group stack** resolves per group through
+     *   {@link StackStyle.dimmedFills} first, falling back to this flat value —
+     *   a stack dimmed to one colour stops reading as a stack.
+     *
+     * The rule behind all three: a per-bar or per-band colour encodes *what the
+     * value is*, and a receded bar's whole job is to stop competing over that.
+     * Emphasis preserves meaning; recession suppresses it. So a chart that keeps
+     * `binColors` or `thresholds` for reasons unrelated to selection still gets
+     * a visible de-emphasis for free, and does **not** need to dim inside its own
+     * colour arrays. (Asked by a consumer who reasonably generalized `hover`'s
+     * `binColors` exclusion to this token; the exclusion is live-states-only.)
      */
     readonly dimmed?: string;
 }

package/dist/yticks.d.ts

@@ -23,6 +23,9 @@ interface TickableScale {
     domain(): number[];
     /** Present on d3's `scaleLog` and on no other continuous scale. */
     base?: () => number;
+    /** Present on d3's `scaleSymlog` and on no other continuous scale — the
+     *  linear window's half-width, i.e. the knee ([PND-SYMLOG]). */
+    constant?: () => number;
 }
 /**
  * The y tick **values** a `<YAxis>`'s labels and the row's gridlines draw —

package/dist/yticks.js

@@ -61,6 +61,8 @@ export function resolveYTickCount(height, explicit) {
  * approach `resolveBarBaseline` takes to read `.domain()`.
  */
 export function yTickValues(scale, count) {
+    if (typeof scale.constant === 'function')
+        return symlogTickValues(scale, count);
     if (typeof scale.base !== 'function')
         return scale.ticks(count);
     const domain = scale.domain();
@@ -80,4 +82,106 @@ export function yTickValues(scale, count) {
         out.push(10 ** e);
     return out;
 }
+/**
+ * Tick values for a **symlog** axis — linear through zero, logarithmic beyond
+ * ([PND-SYMLOG]).
+ *
+ * **This is the feature, not a refinement of it.** d3's `scaleSymlog` supplies
+ * the transform but its `ticks()` is `linearish` — evenly spaced in *value*. On
+ * a ±1M domain with a 20k knee that yields `-1M, -500k, 0, 500k, 1M`: **nothing
+ * at all below the knee**, which is the region a symlog axis exists to reveal.
+ * The mapping does spread that region generously (0→250px, 20k→294px,
+ * 100k→364px on a 500px range), so such a chart is readable-but-unlabelled —
+ * confidently gridded on the one part of the scale that isn't the point. Owning
+ * the ladder is therefore inseparable from owning the transform.
+ *
+ * The ladder, and why each piece is there:
+ *
+ * - **Zero, always.** It is the axis's centre of symmetry and the one value a
+ *   symlog scale is chosen to keep visible.
+ * - **The knee, ±`constant`.** Where the reading changes from linear to
+ *   logarithmic. Unlabelled, a reader has no way to know which régime a given
+ *   gap belongs to, and the same pixel distance means different things either
+ *   side of it.
+ * - **Decades beyond the knee, mirrored.** What a log plot is conventionally
+ *   gridded on, thinned by the same "every `k`th power of ten" rule the log path
+ *   above uses, so it degrades predictably as the row shrinks instead of
+ *   exploding.
+ * - **Bounds are NOT labelled.** A data-derived bound is rarely round, so
+ *   printing it puts an arbitrary number next to a decade — the noise a log grid
+ *   exists to avoid.
+ *
+ * Below one decade of span past the knee there is nothing to grid
+ * logarithmically, so it defers to `scale.ticks(count)` — which is linear, and
+ * correct, because inside the knee symlog *is* linear.
+ *
+ * **Clip first, then thin — never the other way round.** A pan/zoom (or explicit
+ * bounds) can leave a window that contains *none* of the ideal ladder:
+ * `[510_000, 990_000]` with a 19_800 knee excludes zero, both knees, and its one
+ * candidate decade, so an order that thinned a symmetric ladder and clipped
+ * afterwards handed **`[]`** to the labels and the gridlines — an axis with no
+ * ticks at all, which reads as a rendering failure rather than as a scale. The
+ * budget is likewise spent on what *survives* the domain, not on an ideal
+ * two-sided ladder, so an asymmetric window is not thinned as if it were twice
+ * its size. If nothing survives, the linear ticks are the honest answer.
+ *
+ * Detection is structural, matching the log path's use of `base()`: `constant()`
+ * exists on `scaleSymlog` and on no other continuous scale.
+ */
+function symlogTickValues(scale, count) {
+    const domain = scale.domain();
+    const lo = Math.min(domain[0], domain[domain.length - 1]);
+    const hi = Math.max(domain[0], domain[domain.length - 1]);
+    const knee = Math.abs(scale.constant?.() ?? 1);
+    const maxAbs = Math.max(Math.abs(lo), Math.abs(hi));
+    // Finiteness is checked, not assumed: an explicit `max={Infinity}` reaches here
+    // intact, and `floor(log10(Infinity))` is `Infinity` — which made the decade
+    // loop's `e += step` a no-op and hung the render in a `for` that could never
+    // end. d3's own linear ticks return `[]` on such a domain, so deferring is both
+    // safe and the truthful answer for a domain with no finite extent.
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || !Number.isFinite(knee))
+        return scale.ticks(count);
+    if (!(knee > 0) || !(maxAbs > knee) || !(hi > lo))
+        return scale.ticks(count);
+    // The ladder starts at the first decade **at least half a decade above the
+    // knee** (`× √10`), not merely above it. `ceil(log10(knee))` alone puts a
+    // decade arbitrarily close to the knee tick whenever the knee lands just under
+    // a power of ten — a data-derived `maxAbs` of 4.95e6 gives a 99k knee and a
+    // 100k decade, two ticks a few pixels apart whose labels round to the *same
+    // string*. Since the knee itself is always drawn, dropping that decade loses
+    // no information; a chart that prints one number twice at two positions is
+    // reporting something false about the scale.
+    const firstExp = Math.ceil(Math.log10(knee) + 0.5);
+    const lastExp = Math.floor(Math.log10(maxAbs));
+    const inDomain = (v) => v >= lo && v <= hi;
+    // Zero and ±knee are the fixed part of the ladder — kept whole, never thinned,
+    // because they are what distinguishes a symlog axis from a log one.
+    const fixed = [0, knee, -knee].filter(inDomain);
+    // Every decade past the knee that the domain actually contains, in ascending
+    // magnitude, each carrying whichever of ±10^e survived.
+    const rungs = [];
+    for (let e = firstExp; e <= lastExp; e += 1) {
+        const pair = [10 ** e, -(10 ** e)].filter(inDomain);
+        if (pair.length > 0)
+            rungs.push(pair);
+    }
+    // No rung survives ⇒ there is no logarithmic region to grid, so the linear
+    // ticks are the answer — the same reasoning as the knee-swallows-the-domain
+    // guard above, and the case that used to produce an empty axis. Note this also
+    // covers a window sitting *between* the knee and the first decade.
+    if (rungs.length === 0)
+        return scale.ticks(count);
+    // Thin the SURVIVING rungs to what is left of the budget after the fixed
+    // ticks. Stepping by magnitude keeps a rung's ± pair together, so the grid
+    // stays symmetric wherever the domain is.
+    const budget = Math.max(2, count);
+    const total = rungs.reduce((n, pair) => n + pair.length, 0);
+    const room = Math.max(1, budget - fixed.length);
+    const step = Math.max(1, Math.ceil(total / room));
+    const out = new Set(fixed);
+    for (let i = 0; i < rungs.length; i += step)
+        for (const v of rungs[i])
+            out.add(v);
+    return [...out].sort((a, b) => a - b);
+}
 //# sourceMappingURL=yticks.js.map