@pond-ts/charts 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.58.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.59.0...HEAD
+[0.59.0]: https://github.com/pond-ts/pond/compare/v0.58.0...v0.59.0
 [0.58.0]: https://github.com/pond-ts/pond/compare/v0.57.0...v0.58.0
 [0.57.0]: https://github.com/pond-ts/pond/compare/v0.56.2...v0.57.0
 [0.56.2]: https://github.com/pond-ts/pond/compare/v0.56.1...v0.56.2
@@ -61,6 +62,148 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.59.0] — 2026-08-11
+
+### Added
+
+- **charts: `<YAxis scale="symlog">` — linear through zero, logarithmic beyond**
+  ([PND-SYMLOG]). The third `scale` kind, for a **diverging** measure spanning
+  orders of magnitude on both sides of zero. `scale="log"` cannot express that
+  domain at all (no zero, no negatives) and `scale="linear"` flattens everything
+  outside the top decade onto the axis line — so the small and mid-range values,
+  usually the finding, become unreadable.
+
+  The knee is set by the new **`linearWindow`** prop as a _fraction of the
+  domain's largest magnitude_ (default `0.02`): on a ±1M domain the axis is
+  linear through ±20k and logarithmic beyond. Relative rather than absolute so
+  it survives a domain change with no arithmetic at the call site. Values are
+  strictly monotonic across the knee, and zero has a real position. A fraction
+  outside `(0, 1]` is unusable as a knee, so the axis draws with the default and
+  dev-warns which window is in force.
+
+  **The tick ladder is pond's, not d3's.** `scaleSymlog` supplies the transform
+  but ticks it _linearly_, which puts every label in the top decade and none in
+  the linear window the scale exists to open up. `<YAxis scale="symlog">` grids
+  zero, ±the knee, and mirrored decades beyond it, thinned to the tick budget
+  the same way the log path thins its decades, clipped to the domain. When
+  `linearWindow` swallows the domain there is nothing left to grid
+  logarithmically, and the axis defers to the linear ticks — which is correct,
+  not a fallback: inside the knee, symlog _is_ linear.
+
+  It removes a workaround whose cost was **silence**: pre-transforming values
+  into a ±1 plot space with a linear axis pinned to `[-1, 1]` leaves tick
+  positions in plot space while their labels must read in real units, so
+  computing the two by different routes yields a chart that confidently labels
+  positions it does not occupy — no exception, no visual artifact.
+
+  **If you are replacing a hand-rolled curve, the shape will shift.** `symlog` is
+  the single smooth `sign(x) · log1p(|x / knee|)`, not two joined segments; a
+  hand-rolled curve that is exactly linear below the knee and `log10` above is the
+  same family with a different shape. Migrating one, a consumer measured small
+  values at **roughly half** their former height (on a ±9M domain, 283k moved from
+  0.44 to 0.24 of the half-plot above the zero line) with order, tail dominance and
+  the several-fold lift over a linear axis all preserved. No `linearWindow` recovers the piecewise shape — the
+  difference is the curve, not the knee.
+
+- **charts: `<BarChart maxBarWidth>` — cap a bar's ink independently of its slot**
+  ([PND-BARWIDTH]). Applied after the `gap` inset and centred in the slot, with
+  `theme.bar[as].maxWidth` as the fallback (the same relationship `gap` has) and
+  uncapped when neither is set.
+
+  It is the **absolute** half of the width vocabulary. `gap` is _relative_, so
+  with it alone bar width is always `slot - gap` and fattens as the plot widens
+  — and a fixed ink width is what makes a measure comparable **between** panes,
+  since bars that widen with their pane read as different weights of the same
+  thing. Neither existing spelling expresses "spread the slots, pin the bar":
+  `maxBandWidth = barWidth + gap` pins the bar but stops the slots spreading,
+  and `maxBandWidth = slotCap` spreads them but lets the bar grow. The
+  workaround was to compute `gap` from the band width you predicted the library
+  would pick — a re-derivation of pond's layout arithmetic in consumer code,
+  which goes silently wrong the moment that rule changes on either side.
+
+  Pairs with `<ChartContainer maxBandWidth>` (which caps the **slot**) and
+  `minWidth` still wins if the two bounds would invert. **A single-series bar's
+  hit target stays its whole slot**, so narrow ink costs nothing in clickability;
+  on a **stacked** chart the cap does narrow the target, because a stack must
+  hit-test its drawn segment rect to resolve which segment.
+
+- **charts: `<BarChart categories columns>` — a first-class stacked category
+  chart** ([PND-CATSTACK]). Each datum is `{ label, values }` and `columns`
+  names the groups to stack bottom → top, the same relationship
+  `series` + `columns` already has. New `categoryStacks` reader and
+  `CategoryStackDatum` type; geometry, `marks` and the categorical axis are
+  unchanged from the single-value case, so this reaches the shipped
+  `drawStacks` path with no new draw code. A missing or non-finite group reads
+  as a **gap**, not a zero.
+
+  **It removes a workaround with three costs**, the third only visible since
+  0.58.0: composing the picture from one `categories` layer per _cumulative
+  total_ (drawn outermost-first so each overpaints the one beneath) meant a
+  hand-assembled legend, label thinning blind to the sibling layers, and — because
+  a selection entry keys on `(layer id, mark)` — a controlled set replicated
+  across every segment layer, where missing one made a selected bar recede
+  **from the waist up**. Because `marks` is indexed by **bin**, one entry naming
+  `(id, mark)` now matches every segment of a bar, so that failure is not
+  expressible rather than merely fixed.
+
+### Fixed
+
+- **charts: a selected segment of a stack with `colors` no longer collapses to
+  the flat `highlight`.** `StackStyle.groupColored` — the "a selected segment
+  keeps its own fill" exclusion — was gated on the _theme ramp_ having painted
+  the stack, so a call site passing `colors` lost it and both segments of a
+  selected bar went one `highlight` blue, losing the segment distinction exactly
+  where the reader is looking. The gate's stated reason ("a ramp entry the call
+  site overrode is no longer the ramp's colour, so its receded counterpart would
+  be wrong") applies to the _derived_ companions `dimmedFills` / `hoverFills`,
+  which must invent a per-group colour; `groupColored` derives nothing. It now
+  gates on **whether the resolved fills actually differ**, so a `colors` map keeps
+  its colours under selection, while a multi-group stack under a theme that gives
+  its groups no distinct colours at all (no ramp, no roles, no `colors` — e.g.
+  `estelaTheme`) still takes the themed `highlight`, because there is no
+  meaning-carrying colour there to preserve and suppressing the highlight would
+  leave selection invisible. Found building [PND-CATSTACK], where the old gate made
+  the first-class stack render _worse_ under selection than the workaround it
+  replaces; the second half was found in review, since every story and test renders
+  `defaultTheme`, whose ramp hides the difference.
+
+- **all packages: `API.md` now ships inside the npm tarball.** The agent-facing
+  map of every public export across the six packages — one line per export with
+  its purpose and source path — was repo-only, so an agent working in a
+  _consuming_ repo had to crawl `node_modules/*/dist/*.d.ts` or go to the
+  network to learn the surface. It is now copied in by each package's existing
+  `prepack` (the same mechanism that already ships `README`, `LICENSE` and
+  `CHANGELOG`) and listed in `files`. ~69kB per tarball.
+
+  Every package carries the same **monorepo-wide** copy rather than a
+  per-package slice, deliberately: the packages compose, and knowing what is
+  next door is most of the value. The header now names its audience and
+  resolves repo-relative source paths against GitHub, since inside
+  `node_modules` a bare `packages/core/src/…` points nowhere.
+
+- **charts: `BarStyle.dimmed`'s precedence over per-bar and per-band colour is
+  documented, and pinned.** A consumer migrating onto 0.58.0 read
+  `BarStyle.hover`'s documented `binColors` exclusion ("pops each bar's _own_
+  fill"), reasonably generalized it to `dimmed`, concluded their `binColors` and
+  `thresholds` charts would get no de-emphasis, and was about to hand-dim inside
+  their own colour arrays. The opposite is true: **an unselected bar takes
+  `dimmed`, discarding its per-bar colour, and a banded bar draws flat rather
+  than dimming each band.** The asymmetry is deliberate — emphasis preserves a
+  per-bar colour because that colour is what the value means, while a receded
+  bar's job is to stop competing over meaning — but only `hover` said anything,
+  so generalizing was the natural read. `dimmed` now spells out all three paths
+  (`binColors`/`binFills`, bands/thresholds, and the per-group stack fallback
+  through `StackStyle.dimmedFills`), `hover` scopes its exclusion to the live
+  states, and three tests pin the behaviour.
+
+- **charts: the `theme.list` register no longer reads as if it carries
+  `dimmed`.** Its doc mentioned `highlight`/`dimmed` while explaining that a
+  list resolves glyph state through the bar tokens — accurate, but sitting in a
+  sentence about per-metric resolution it read as a field list, and cost the
+  same consumer a couple of passes to rule out a missing `list.dimmed`. Now
+  states explicitly that those are `BarStyle` tokens resolved via
+  `theme.bar[as]`, and that this register carries exactly its five values.
+
 ## [0.58.0] — 2026-08-10
 
 ### Added

package/dist/BarChart.d.ts

@@ -1,6 +1,6 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
-import { type BinRecord, type CategoryDatum } from './data.js';
+import { type BinRecord, type CategoryDatum, type CategoryStackDatum } from './data.js';
 import { type Orientation } from './bars.js';
 import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
@@ -43,11 +43,17 @@ import type { DecimateOption } from './decimate.js';
  *   `<ChartContainer origin>` does not rescue it: it relabels a value axis but
  *   does not re-ladder it.
  * - **`categories`** — an ordered `{ label, value }[]`, one bar per category.
- *   Takes **no** `column`/`columns` (each datum carries its own value).
- *   Vertical puts the categories on the ordinal **x** axis (the container's
- *   band scale); `orientation="horizontal"` puts them on **y** as unit slots
- *   and the value on x, and a `<YAxis>` with no explicit `ticks` labels one
- *   per category automatically ([PND-HCAT]).
+ *   Takes no `column`. Vertical puts the categories on the ordinal **x** axis
+ *   (the container's band scale); `orientation="horizontal"` puts them on **y**
+ *   as unit slots and the value on x, and a `<YAxis>` with no explicit `ticks`
+ *   labels one per category automatically ([PND-HCAT]).
+ * - **`categories` + `columns`** — a **stacked** category chart
+ *   ([PND-CATSTACK]): each datum is `{ label, values }` and `columns` names the
+ *   groups to stack, bottom → top. The same relationship `series` + `columns`
+ *   already has, so a category stack is now a first-class shape rather than one
+ *   `categories` layer per cumulative total. One layer means one `mark` per
+ *   bar, so **one selection entry lights the whole bar** and the composed
+ *   workaround's per-layer replication is unnecessary.
  *
  * **Live charts:** `series.byValue(…)` / `.toMap()` mint fresh objects each
  * call, so an inline `series={…}` re-registers this layer every render — on a
@@ -95,6 +101,12 @@ type BarChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSerie
     bins?: never;
     column?: never;
     columns?: never;
+} | {
+    categories: readonly CategoryStackDatum[];
+    columns: readonly string[];
+    series?: never;
+    bins?: never;
+    column?: never;
 };
 /** The props every {@link BarChartSource} mode shares. */
 export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
@@ -230,6 +242,43 @@ export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extend
      * would invert collapses to the style's `minWidth`.
      */
     gap?: number;
+    /**
+     * Cap on a bar's **ink** width in px — applied after the `gap` inset and
+     * centred in its slot ([PND-BARWIDTH]). **Omitted ⇒ the theme's `bar`
+     * `maxWidth`, and uncapped if that is unset too** (a bar is `slot - gap`
+     * wide, as it always was).
+     *
+     * This is the *absolute* half of the width vocabulary. `gap` is **relative**,
+     * so with it alone bar width is always `slot - gap` and fattens as the plot
+     * widens; a fixed ink width is what makes a measure comparable **between**
+     * panes, since bars that widen with their pane read as different weights of
+     * the same thing.
+     *
+     * Pairs with `<ChartContainer maxBandWidth>`: that caps the **slot** (how far
+     * the bars spread), this caps the **ink** inside whatever slot results. The
+     * two are independent, which is the point — neither spelling alone expresses
+     * "spread the slots, pin the bar":
+     *
+     * - `maxBandWidth = barWidth + gap` pins the bar but stops the slots
+     *   spreading;
+     * - `maxBandWidth = slotCap` spreads them but lets the bar grow.
+     *
+     * `theme.bar[as].minWidth` still wins if the two bounds would invert, so the
+     * rect can never flip.
+     *
+     * **On a stacked chart the cap narrows the hit target too**, because a stack
+     * hit-tests its drawn segment rect (it must, to resolve *which* segment).
+     * A single-series bar is unaffected: it hit-tests its whole slot, so the ink
+     * can be narrow while the target stays full width.
+     *
+     * That holds in **both orientations**, and costs a deliberate guard to keep:
+     * a single-series *horizontal* chart shares the oriented draw/hit path with
+     * stacks, so the cap is withheld from its hit rect explicitly (`groups.length >
+     * 1`). Vertical charts get it for free — `barSlotRect` takes no cap. Don't
+     * "simplify" that guard away: the rule follows from segment disambiguation,
+     * which is a property of a stack, not of an axis.
+     */
+    maxBarWidth?: number;
     /**
      * **M4 column decimation** (charts decimator wave). **Omitted ⇒ `true`**: once
      * the visible bars are denser than ~2 per device pixel (each slot < ~1px), the
@@ -319,6 +368,6 @@ export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends Valu
  * </Layers>
  * ```
  */
-export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation, ordinal, id, axis, gap, decimate, legend, index, }: BarChartProps<S, VS>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation, ordinal, id, axis, gap, maxBarWidth, decimate, legend, index, }: BarChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=BarChart.d.ts.map

package/dist/BarChart.js

@@ -1,6 +1,6 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { Interval, ValueSeries } from 'pond-ts';
-import { barsFromTimeSeries, barsFromBins, barsFromValueSeries, categoryStack, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
+import { barsFromTimeSeries, barsFromBins, barsFromValueSeries, categoryStack, categoryStacks, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
 import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, normalizeThresholds, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
 import { spansForLayer } from './span.js';
 import { isDev } from './dev.js';
@@ -60,7 +60,7 @@ const EMPTY_MARKS = [];
  * </Layers>
  * ```
  */
-export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation = 'vertical', ordinal = false, id, axis, gap, maxBarWidth, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -78,8 +78,11 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         throw new Error('<BarChart> needs exactly one of `series`, `bins`, or `categories`');
     }
     if (categories !== undefined) {
-        if (column !== undefined || columns !== undefined) {
-            throw new Error('<BarChart categories> takes no `column`/`columns` (each datum carries its own value)');
+        if (column !== undefined) {
+            throw new Error('<BarChart categories> takes no `column` — a single-value datum carries its own `value`, and a stacked one names its groups with `columns`');
+        }
+        if (columns !== undefined && columns.length === 0) {
+            throw new Error('<BarChart categories> with `columns` needs at least one group name');
         }
     }
     const isMap = series instanceof Map;
@@ -105,10 +108,21 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     // horizontal bar) so one oriented draw path covers it.
     const shape = useMemo(() => {
         if (categories !== undefined) {
-            // Categorical row-read: one unit-slot bar per category (G === 1), drawn on
-            // the container's band scale. The reused stacked geometry — only the axis
+            // Categorical row-read: one unit-slot bar per category, drawn on the
+            // container's band scale. The reused stacked geometry — only the axis
             // (band scale + labels) is new.
-            return { kind: 'stacked', ss: categoryStack(categories) };
+            //
+            // With `columns` it is a real multi-group stack ([PND-CATSTACK]): same
+            // slots, same `marks`, `G > 1`. Because `marks` is indexed by BIN, one
+            // selection entry naming `(id, mark)` matches every segment of a bar —
+            // which is the property that made the hand-composed workaround's
+            // "recedes from the waist up" bug inexpressible here.
+            return {
+                kind: 'stacked',
+                ss: columns !== undefined
+                    ? categoryStacks(categories, columns)
+                    : categoryStack(categories),
+            };
         }
         if (bins !== undefined) {
             const cols = columns ?? (column !== undefined ? [column] : undefined);
@@ -250,6 +264,19 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     // The stacked path's bar-thickness floor comes from `bar.default` (not the `as`
     // role — `as` is single-series only), matching how `gapPx` sources its default.
     const stackMinWidth = bar.default.minWidth;
+    // Same sourcing as `gapPx`: the prop wins, else the theme token, else
+    // uncapped ([PND-BARWIDTH]). `bar.default` rather than the `as` role for the
+    // stacked ceiling, for the reason above.
+    const maxWidthPx = maxBarWidth ?? bar.default.maxWidth;
+    // The single-series draw takes a `BarStyle` straight from the theme, so the
+    // prop override is applied by shadowing the token — same relationship `gap`
+    // has, and with the prop absent the role's own `maxWidth` (if any) already
+    // rides along untouched. Only the INK path gets this: `barSlotRect` (the hit
+    // region) stays the whole slot, so a narrow capped bar keeps a full-width
+    // target — the deliberate ink/hit split `gapPx` already relies on.
+    const singleDrawStyle = useMemo(() => maxBarWidth !== undefined
+        ? { ...singleStyle, maxWidth: maxBarWidth }
+        : singleStyle, [singleStyle, maxBarWidth]);
     // ── Threshold ladder ([PND-BANDBAR2]) ────────────────────────────────────
     // Resolved once here rather than per bar per frame: normalize the breakpoints
     // (sort, drop non-finite), then pair them with `bandColors` → the role's
@@ -351,11 +378,38 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
             (ramp !== undefined ? at(ramp, i) : base.fill));
         // A ramp entry the call site overrode is no longer the ramp's colour, so
         // its receded counterpart would be wrong — the whole ramp only means
-        // anything when it is the ramp that painted it.
+        // anything when it is the ramp that painted it. This gates the *derived*
+        // companions (`dimmedFills` / `hoverFills`), which need a counterpart per
+        // group and cannot invent one for an arbitrary call-site colour.
         const ramped = ramp !== undefined && colors === undefined;
+        // `groupColored` derives nothing — it only says "a selected segment keeps
+        // its own fill rather than taking the flat `highlight`", because the colour
+        // is meaning-carrying.
+        //
+        // So the condition is exactly **"do the fills actually differ"**, read off
+        // the resolved `fills` rather than inferred from anything upstream of them.
+        // Both cheaper inferences are wrong, and each was shipped in turn:
+        //
+        //  - Gating on `ramped` (the ramp painted it) meant a stack with `colors`
+        //    collapsed BOTH segments of a selected bar to one `highlight` blue —
+        //    losing the segment distinction exactly where the reader is looking. A
+        //    call site naming its groups' colours is *more* deliberate than a
+        //    fallback ramp, not less. Found building [PND-CATSTACK].
+        //  - Gating on `groups.length > 1` (my fix for that) is wrong in the other
+        //    direction: a multi-group stack under a theme with **no** group ramp, no
+        //    `colors` and no per-group roles resolves every fill to `base.fill`, so
+        //    claiming the colour carries meaning suppresses the highlight and leaves
+        //    *nothing* — selection becomes invisible. `estelaTheme` is exactly that
+        //    theme, and it ships. Found by Layer-2 review, which is the only way it
+        //    could have been: every story and test renders `defaultTheme`, whose ramp
+        //    makes the two gates indistinguishable.
+        //
+        // Reading `fills` also handles the degenerate `colors` map that assigns one
+        // colour to every group: nothing is distinguished, so the highlight applies.
+        const groupColoured = new Set(fills).size > 1;
         return {
             fills,
-            ...(ramped ? { groupColored: true } : {}),
+            ...(groupColoured ? { groupColored: true } : {}),
             ...(ramped && rampDim !== undefined
                 ? {
                     dimmedFills: (groups ?? []).map((_g, i) => at(rampDim, i)),
@@ -380,9 +434,10 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                 ? { emphasisOpacity: base.emphasisOpacity }
                 : {}),
             ...(base.dimmed !== undefined ? { dimmed: base.dimmed } : {}),
+            ...(maxWidthPx !== undefined ? { maxWidth: maxWidthPx } : {}),
             ...(binColors !== undefined ? { binFills: binColors } : {}),
         };
-    }, [bar, groups, colors, binColors]);
+    }, [bar, groups, colors, binColors, maxWidthPx]);
     // The current selection / hover, narrowed to the identity the highlight match
     // needs. For a stack that's (id, key, label = group); the single path uses just
     // (id, key). Read here so a change re-registers the layer → the canvas repaints.
@@ -525,7 +580,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                     },
                                 }),
                         }),
-                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder, layerSpans),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleDrawStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder, layerSpans),
                 },
                 axisId: axis,
                 index,
@@ -563,7 +618,20 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                     ? {}
                     : {
                         hitTest: (px, py, xScale, yScale) => {
-                            const hit = stackAt(ss, px, py, orientation, xScale, yScale, gapPx, stackMinWidth);
+                            // The cap reaches the hit rect ONLY for a real stack, where the
+                            // rect is what resolves *which segment* was hit and so must be
+                            // the drawn one. A single-series chart has one segment per slot
+                            // and nothing to disambiguate, so narrowing its target buys
+                            // nothing and costs clickability.
+                            //
+                            // This path serves single-series **horizontal** charts as well as
+                            // stacks (see the branch comment above), which is how the prop's
+                            // documented guarantee — "a single-series bar hit-tests its whole
+                            // slot" — was true only of vertical ones. Found by Layer-2 review;
+                            // the fix is to make the guarantee orientation-independent rather
+                            // than to narrow the claim, since the reason for the split is
+                            // segment disambiguation and that is a property of the *stack*.
+                            const hit = stackAt(ss, px, py, orientation, xScale, yScale, gapPx, stackMinWidth, ss.groups.length > 1 ? maxWidthPx : undefined);
                             if (hit === null)
                                 return null;
                             const [bi, g, begin, name, value] = hit;
@@ -656,6 +724,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         categoryLabels,
         orientation,
         singleStyle,
+        singleDrawStyle,
         stackStyle,
         binColors,
         bandLadder,
@@ -664,6 +733,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         gapPx,
         decimate,
         stackMinWidth,
+        maxWidthPx,
         selection,
         hover,
         layerSpans,

package/dist/ChartRow.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, Fragment, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
-import { scaleLinear, scaleLog } from 'd3-scale';
+import { scaleLinear, scaleLog, scaleSymlog } from 'd3-scale';
 import { isDev } from './dev.js';
 import { useIndexedChildren } from './child-index.js';
 import { logAxisWarning, needsExtents, resolveYDomain } from './domain.js';
@@ -11,6 +11,41 @@ import { useSlotKey } from './use-slot-key.js';
 import { LegacyCursor } from './cursors.js';
 import { YAxis } from './YAxis.js';
 import { ContainerContext, RowContext, } from './context.js';
+/**
+ * `scale="symlog"`'s default linear window — the knee at **2% of the domain's
+ * largest magnitude** ([PND-SYMLOG]). Chosen because it is what the reporting
+ * consumer's own transform used (`maxAbs / 50`), and confirmed with them as
+ * generalizing: every caller they had passed the data's own max-abs, and none
+ * had a case for an absolute constant.
+ */
+const DEFAULT_LINEAR_WINDOW = 0.02;
+/**
+ * `scaleSymlog`'s `constant` (the linear window's half-width in data units) for
+ * an axis's domain-relative {@link YAxisProps.linearWindow} ([PND-SYMLOG]).
+ *
+ * **The clamp is the point.** d3's symlog transform is
+ * `sign(x)·log1p(|x / constant|)`, so a `constant` of `0` — or of
+ * `Number.MIN_VALUE`, which the first version of this "clamped" to — divides
+ * every sample by ~zero, and `(∞ − ∞) / (∞ − ∞)` makes **every mapped pixel
+ * `NaN`**: a blank plot, `NaN` gridline coordinates, no error. That is strictly
+ * worse than the mistake it was guarding, so an unusable fraction (non-finite,
+ * `<= 0`, or `> 1`) falls back to the **default** and dev-warns (see the
+ * `linearWindow` diagnostics below) rather than being nudged to a value that
+ * technically satisfies `> 0`.
+ *
+ * A degenerate all-zero domain has no magnitude to take a fraction *of*, so the
+ * knee falls back to `1`; the axis is linear across it either way.
+ */
+function symlogConstant(linearWindow, lo, hi) {
+    const usable = linearWindow !== undefined &&
+        Number.isFinite(linearWindow) &&
+        linearWindow > 0 &&
+        linearWindow <= 1;
+    const fraction = usable ? linearWindow : DEFAULT_LINEAR_WINDOW;
+    const maxAbs = Math.max(Math.abs(lo), Math.abs(hi));
+    const knee = fraction * maxAbs;
+    return Number.isFinite(knee) && knee > 0 ? knee : 1;
+}
 /** Sentinel id for the implicit axis a row gets when no `<YAxis>` is declared. */
 const IMPLICIT_AXIS_ID = '__default__';
 /** Element-wise compare of two optional number arrays (an axis's tick values) —
@@ -43,6 +78,10 @@ function axisSpecEqual(a, b) {
         a.side === b.side &&
         a.width === b.width &&
         a.scale === b.scale &&
+        // Easy to forget when adding a scale-shaping field, and the failure is
+        // silent: an axis whose `linearWindow` alone changed would be discarded by
+        // the guard and keep drawing with the previous knee.
+        a.linearWindow === b.linearWindow &&
         // Object.is (not ===) so a degenerate NaN bound compares equal to itself and
         // doesn't re-register every render.
         Object.is(a.min, b.min) &&
@@ -253,7 +292,16 @@ export function ChartRow({ height, cursor, children }) {
             // `scaleLog` and `scaleLinear` share the call/ticks/tickFormat/invert
             // surface every consumer uses (see `YScale`), so choosing between them
             // here is the whole of log support — no draw layer branches on it.
-            const base = ax.scale === 'log' ? scaleLog() : scaleLinear();
+            // `scaleSymlog` shares the same call/ticks/tickFormat/invert surface, so
+            // as with log, choosing it here is the whole of symlog support — no draw
+            // layer branches on it. Its `constant` (the linear window's half-width) is
+            // resolved from the axis's DOMAIN-RELATIVE fraction: absolute would need
+            // recomputing whenever the domain moved ([PND-SYMLOG]).
+            const base = ax.scale === 'log'
+                ? scaleLog()
+                : ax.scale === 'symlog'
+                    ? scaleSymlog().constant(symlogConstant(ax.linearWindow, lo, hi))
+                    : scaleLinear();
             const s = base.domain([lo, hi]).range([height, topHeader]);
             // 2-D pan/zoom is carried as a **pixel** transform (`k`, `ty`) so one
             // gesture serves every axis in the row whatever its units, and all of them
@@ -319,6 +367,46 @@ export function ChartRow({ height, cursor, children }) {
             }
         }
     }, [effectiveAxes, layerList, defaultAxisId]);
+    // Dev-mode diagnostics for `linearWindow` ([PND-SYMLOG]). Both cases it covers
+    // are *silent* otherwise, which is the whole reason it exists: a
+    // `linearWindow` on a linear or log axis is read by nothing, and a fraction
+    // outside `(0, 1]` is unusable as a knee (see `symlogConstant`), so the axis
+    // silently draws with the **default** window instead of the one asked for.
+    // Neither throws and neither looks broken — it just isn't the scale the call
+    // site asked for.
+    //
+    // Same shape as the log diagnostics above: an effect rather than the memo, and
+    // deduped in `warnedRef` under a suffixed key so it cannot collide with the
+    // log message stored under the bare axis id.
+    useEffect(() => {
+        if (!isDev)
+            return;
+        const warned = warnedRef.current;
+        for (const ax of effectiveAxes) {
+            const key = `${ax.id}:linearWindow`;
+            const w = ax.linearWindow;
+            let message = null;
+            if (w !== undefined && ax.scale !== 'symlog') {
+                message =
+                    `<YAxis id="${ax.id}"> sets linearWindow=${w} but scale is ` +
+                        `"${ax.scale}" — linearWindow only applies to scale="symlog" and is ` +
+                        `ignored here.`;
+            }
+            else if (w !== undefined && (!Number.isFinite(w) || w <= 0 || w > 1)) {
+                message =
+                    `<YAxis id="${ax.id}"> has linearWindow=${w}, outside (0, 1] — the ` +
+                        `axis is drawing with the default ${DEFAULT_LINEAR_WINDOW} instead. ` +
+                        `It is a fraction of the domain's largest magnitude, so 0.02 means ` +
+                        `"linear through 2% of the domain".`;
+            }
+            if (message === null)
+                warned.delete(key);
+            else if (warned.get(key) !== message) {
+                warned.set(key, message);
+                console.warn(message);
+            }
+        }
+    }, [effectiveAxes]);
     // Resolved auto-tick count per axis — explicit `<YAxis tickCount>` else
     // height-derived (see resolveYTickCount). The single source the `<YAxis>`
     // labels, the readout formatter (below), and the `Layers` gridlines all read,

package/dist/YAxis.d.ts

@@ -46,8 +46,64 @@ export interface YAxisProps {
      *
      * A dev-mode warning fires for the cases that are unambiguously a mistake: a
      * refused bound, negative data, or an axis with no positive data at all.
+     *
+     * `'symlog'` is **linear through zero, logarithmic beyond** — for data that
+     * spans orders of magnitude *on both sides of zero*, which `'log'` cannot
+     * express at all (it admits no zero and no negatives). The linear window is
+     * {@link linearWindow}. Because it admits zero, it resolves its domain on the
+     * ordinary **linear** path: no positive-only bound refusal, no rounding out to
+     * decades, no gapping of non-positive samples.
+     *
+     * **The axis owns tick placement, and that is the substance of the feature.**
+     * d3's symlog supplies the transform but ticks it *linearly*, which on a ±1M
+     * domain with a 20k knee labels nothing below the knee — the exact region the
+     * scale was chosen to reveal. pond grids it on zero, the knee (±`linearWindow ×
+     * maxAbs`) and mirrored decades beyond, thinned by the same rule the log axis
+     * uses. See `yticks.ts`.
+     *
+     * **The curve is `log1p`, not piecewise — read this before replacing a
+     * hand-rolled one.** "Linear through zero, logarithmic beyond" describes how the
+     * axis *reads*, not two joined segments: `scaleSymlog` is the single smooth
+     * `sign(x) · log1p(|x / knee|)`, so there is no exact boundary at which one law
+     * stops and the other starts. A common hand-rolled curve *is* piecewise —
+     * exactly linear below the knee, `log10` above — and the two are the same family
+     * with materially different shape. Swapping one for the other, a reporting
+     * consumer measured small values landing at **roughly half** their former height
+     * (a ±9M domain: 283k went from 0.44 to 0.24 of the half-plot above the zero
+     * line), while order, the dominance of the tail, and a several-fold lift over a
+     * linear axis all held — the chart still says the same thing, but it does not
+     * say it identically.
+     *
+     * **No `linearWindow` recovers a piecewise shape.** The same consumer tried: a
+     * smaller window fits the large values while overshooting the small ones about
+     * 2×, because the difference is the curve, not the knee. If you need the
+     * piecewise curve exactly, you need your own transform — which is the thing this
+     * scale exists to let you delete, so weigh that before reaching for it.
+     */
+    scale?: 'linear' | 'log' | 'symlog';
+    /**
+     * `scale="symlog"`'s **linear window**, as a fraction of the domain's largest
+     * magnitude. **Default `0.02`** — the knee sits at 2% of `maxAbs`, so a ±1M
+     * domain is linear through ±20k and logarithmic beyond. Ignored on any other
+     * scale.
+     *
+     * **Domain-relative, not absolute** (d3's own `constant` is absolute). A chart
+     * that re-keys to the largest magnitude on every update would otherwise need
+     * the constant recomputed each tick, and would drift silently the moment
+     * someone forgot — the fraction survives a domain change with no call-site
+     * arithmetic at all.
+     *
+     * Precisely: a fraction of the **resolved domain before any pan/zoom** — the
+     * one the axis's `min`/`max`/`pad`/auto-fit produce. A 2-D gesture is carried
+     * as a *pixel* transform and the knee is deliberately **not** recomputed from
+     * the zoomed window, so zooming moves the plot without moving the boundary
+     * between the two régimes underneath it. (Recomputing would make the same
+     * datum linear at one zoom level and logarithmic at the next.)
+     *
+     * A value outside `(0, 1]` cannot be a knee; the axis draws with the default
+     * instead and dev-warns which window is in force.
      */
-    scale?: 'linear' | 'log';
+    linearWindow?: number;
     /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
     min?: number;
     max?: number;
@@ -155,5 +211,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function YAxis({ id, side, label, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map