@pond-ts/charts 0.62.0 → 0.63.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.62.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.63.0...HEAD
+[0.63.0]: https://github.com/pond-ts/pond/compare/v0.62.0...v0.63.0
 [0.62.0]: https://github.com/pond-ts/pond/compare/v0.61.0...v0.62.0
 [0.61.0]: https://github.com/pond-ts/pond/compare/v0.60.0...v0.61.0
 [0.60.0]: https://github.com/pond-ts/pond/compare/v0.59.0...v0.60.0
@@ -65,6 +66,105 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.63.0] — 2026-08-18
+
+### Added
+
+- `@pond-ts/charts`: **axis pan/zoom**, behind a new
+  **`<ChartContainer axisPanZoom>`** (`'none'` — the default — / `'x'` / `'y'` /
+  `'xy'`). Opted in, the `<XAxis>` strip and each `<YAxis>` gutter become
+  grabbable, and **double-click** puts one back (the declared `range` on x, its
+  fit on y). The cursor stays an ordinary arrow at rest and becomes directional
+  (`↕` / `↔`) only while a gesture is running.
+
+  **The opt-in is deliberately separate from `panZoom`, in both directions.** An
+  already-interactive chart does not grow axis gestures on upgrade — nothing
+  changes for any existing chart — and a chart can scale its y axes with
+  `panZoom` off entirely, which is what you want when the plot's drag belongs to
+  a selection sweep.
+
+  **The x strip is the canvas gesture, moved to the axis** — drag pans, wheel
+  zooms about the pointer — reusing the plot's own domain-space maths, so
+  `bounds` and `minDuration` still fence the view and a trading-time axis still
+  pans and floors in _trading_ time. A category axis has no continuous domain and
+  stays inert.
+
+  **A y gutter zooms, and only the axis you grabbed** — its sibling and every
+  other row hold still. That needed a new per-axis pixel transform
+  (`RowFrame.axisTransforms`, layered under the container's uniform
+  `yTransform`), since the uniform one exists precisely so a _plot_ gesture never
+  has to pick an axis; unlike it, this is not floored at `k ≥ 1`, because
+  squashing an axis you grabbed is the point.
+
+- `@pond-ts/charts`: **`<YAxis onBoundsChange>`** — the auto-vs-manual hand-off
+  for a scaled y axis. Fires with the `[min, max]` a gutter gesture reached, and
+  with `null` when the axis is released back to auto-fit, so a UI can show the
+  bounds, badge the scale "manual", and offer a toggle back. Providing it makes
+  the axis **controlled** (the gesture only reports; `min`/`max` fed back are
+  what it draws), exactly as `onTimeRangeChange` does for the x view; omit it and
+  the axis holds the zoom itself. `ContainerFrame` also gains `seedRange` — the
+  declared view, as against the gestured `timeRange` — which is the x reset's
+  target.
+
+- **charts: `<ChartContainer height>` + `<ChartRow flex>` — container-owned
+  vertical layout** ([PND-HEIGHT]). `height` takes a pixel number or `'auto'`
+  (measured by the same `ResizeObserver` as `width="auto"`); omitted stays the
+  classic mode where rows declare pixels. A managed container renders as a
+  **flex column** — the rows block flexes, the x-axis strip keeps its natural
+  height — and flex rows (a bare `<ChartRow>` is `flex={1}`) divide what the
+  browser says is left, then read that height back for their y-scales.
+
+  The design constraint was that **CSS does the subtraction**: the axis
+  strip's height depends on its `label`, the theme font size, the tick
+  ladder's calendar band row at the current grain, and stacked marker pills —
+  it is not a constant a caller can subtract, and every consumer who tried
+  carried a wrong one (`20` and `24` in one codebase; this site's own
+  resizable-panels recipe said `22`). It also means non-row children between
+  rows — the recipe's draggable splitter — keep taking their natural space,
+  so that recipe reduces to its drag handler: one flex row absorbing slack
+  over one fixed row the drag resizes, no `AXIS_H`, no measuring hook.
+
+  A flex row paints nothing until its first measurement, latches its last
+  non-zero height while hidden (a `display: none` tab switch keeps its
+  scales), and warns in dev when mounted in a container that never sizes it.
+  The container **warns in dev when a measured dimension stays 0** — the
+  unconstrained-parent deadlock, which for height is the _default_ (a
+  flex-column child's height is its content) rather than an edge case.
+
+  Fixed-`height` rows keep their pixels everywhere, managed or not; a
+  container with no `height` behaves exactly as before.
+
+### Fixed
+
+- **charts: the crosshair's value pill lands on the axis that measured the
+  value, in that axis's colour.** With two y-axes on one side, the pill was
+  placed by side alone — always against the plot edge — so a reading taken off
+  the **outer** axis appeared over the **inner** axis's ticks, in the cursor's
+  grey: a number pinned to a ruler that never measured it. The reticle picks one
+  series, so the resolved sample now carries its axis's gutter **offset** (the
+  reserved widths of the columns between it and the plot) and its
+  `<YAxis color>`, and the pill uses both — position _and_ ink say which of two
+  stacked scales the number is on. A single axis per side is unchanged (offset
+  `0`), as is an axis that sets no colour (the theme's cursor ink).
+
+  A pill placed further out is now **bridged back to the plot edge** by a 1px
+  connector in its own colour — the y-side twin of the crosshair's x-axis time
+  connector, without which a pill a column out reads as a value floating in a
+  gutter. It draws at half opacity because, unlike the time connector's empty
+  strip, it crosses another axis's tick labels; nothing is drawn on the innermost
+  axis, where the pill already meets the line.
+
+  `<YAxis color>` is now part of the axis's registered spec rather than
+  presentation-only, because the pill is drawn by the row's cursor overlay, not
+  by `<YAxis>`. `<Baseline indicator>` — the other on-axis value pill — got the
+  same placement fix and the same connector. New `Cursors/Crosshair` stories fan
+  the states out (`AxisColor`, `StackedAxes`, `StackedAxesColored`,
+  `StackedAxesLeft`, `StackedAxesBothSides`).
+
+  Not covered: `<YAxisIndicator>` still takes an explicit `side` alongside its
+  `axis`, so it can be pointed at a gutter its axis isn't in; reconciling those
+  two props is a public-API question, left for its own change.
+
 ## [0.62.0] — 2026-08-16
 
 ### Added

package/dist/ChartContainer.d.ts

@@ -294,6 +294,48 @@ export interface ChartContainerProps {
      * render.
      */
     width?: number | 'auto';
+    /**
+     * Total height in CSS pixels, or `'auto'` to fill the available height —
+     * **the container-owned vertical layout** ([PND-HEIGHT]). Omitted means the
+     * classic mode: rows declare pixel heights and the container's height is
+     * their sum.
+     *
+     * With a height, the container renders as a **flex column** — the rows
+     * block flexes, the x-axis strip keeps its natural height at the bottom —
+     * and `<ChartRow flex>` rows (a bare `<ChartRow>` is `flex={1}`) divide
+     * whatever the browser says is left. That "whatever the browser says" is
+     * the point: the axis strip's height depends on its `label`, the theme's
+     * font size, whether the tick ladder is showing its calendar band row at
+     * the current grain, and how many marker pills stack — it is not a constant
+     * a caller could subtract, and every consumer who tried carried a wrong
+     * number (20, 24, and the recipe's 22 were all in the wild for one strip).
+     * CSS does the subtraction, so there is no number to know.
+     *
+     * A single full-bleed chart is therefore zero arithmetic:
+     *
+     * ```tsx
+     * <ChartContainer width="auto" height="auto">
+     *   <ChartRow>
+     *     <YAxis id="v" />
+     *     <Layers>…</Layers>
+     *   </ChartRow>
+     * </ChartContainer>
+     * ```
+     *
+     * Fixed-`height` rows keep their pixels inside a managed container, and
+     * non-row children (a draggable splitter between two rows) take their
+     * natural space — so the resizable-panels shape becomes one `flex` row
+     * absorbing slack over one fixed row the drag resizes, with no reserved
+     * strip constant and no measuring hook.
+     *
+     * `'auto'` measures with the same `ResizeObserver` as `width="auto"`, gates
+     * the first paint until both needed dimensions exist, latches the last
+     * non-zero size while hidden, and — because a flex-**column** child's
+     * height defaults to its content — **warns in dev when a measured dimension
+     * stays 0**: the parent needs a definite height, or the deadlock is the
+     * default.
+     */
+    height?: number | 'auto';
     /** Vertical space between rows in CSS pixels (not under the axis). Default 0. */
     rowGap?: number;
     /**
@@ -438,8 +480,38 @@ export interface ChartContainerProps {
      * The boolean form is the back-compat shorthand (`true` ⇒ `'panZoom'`,
      * `false` ⇒ `'none'`). Bound the reachable range with {@link bounds}
      * (zoom-out / pan extent) and {@link minDuration} (zoom-in floor).
+     *
+     * **This prop is about the plot only.** Gestures on the axis strips are a
+     * separate opt-in — see {@link axisPanZoom} — so turning pan/zoom on here does
+     * not silently make the axes grabbable.
      */
     panZoom?: boolean | 'none' | 'pan' | 'panZoom' | 'panZoomX' | 'panZoomY' | 'panZoomXY';
+    /**
+     * Which **axis strips** take gestures — the opt-in for grabbing an axis, and
+     * **`'none'` by default** so no existing chart changes behaviour:
+     *
+     * - `'none'` (or `false`, the **default**) — the strips are inert chrome.
+     * - `'x'` — the `<XAxis>` strip **pans on drag and zooms on wheel**, exactly as
+     *   the plot's own gestures do (same maths, same sign, same {@link bounds} /
+     *   {@link minDuration} fences). Double-click returns to the declared
+     *   {@link range}. A category axis has no continuous domain and stays inert.
+     * - `'y'` — each `<YAxis>` gutter **zooms that one axis** on drag or wheel,
+     *   double-click releasing it back to its fit. Report it to a scale UI with
+     *   {@link YAxisProps.onBoundsChange}.
+     * - `'xy'` (or `true`) — both.
+     *
+     * **Deliberately independent of {@link panZoom}**, in both directions. A chart
+     * can scale its y axes without letting the plot capture vertical drags (which
+     * would fight a selection sweep), and an interactive plot does not hand its
+     * axes gestures nobody asked for. The one thing they share is the view itself:
+     * the x strip moves the same range the plot's pan does, and reports through
+     * {@link onTimeRangeChange} the same way.
+     *
+     * The pairing to reach for on a time-series chart is
+     * `panZoom="panZoom" axisPanZoom="xy"` — drag the plot to pan, drag the x strip
+     * to pan, wheel either to zoom, and drag a y gutter to override its fit.
+     */
+    axisPanZoom?: boolean | 'none' | 'x' | 'y' | 'xy';
     /**
      * **Outer pan/zoom extent** — `[min, max]` (same units as {@link range}) the
      * view can never move outside. Panning into an edge stops there (the window

package/dist/ChartContainer.js

@@ -58,17 +58,24 @@ function normalizeRange(range) {
  * ChartContainerProps.width} and {@link AutoWidthContainer}.
  */
 export function ChartContainer(props) {
-    const { width } = props;
+    const { width, height } = props;
     // The measure pass is a *different component* rather than a branch inside
     // the resolved one, because the resolved container may not render at all
-    // until a width exists — and ~60 hooks cannot be conditional. Choosing the
-    // component by the prop's kind (number vs auto) means flipping a container
-    // between fixed and auto remounts it; that is a layout change, and a
-    // remount is the honest response to one.
-    if (typeof width === 'number') {
-        return _jsx(ResolvedChartContainer, { ...props, width: width });
+    // until its dimensions exist — and ~60 hooks cannot be conditional. Choosing
+    // the component by the props' kinds (number vs auto) means flipping between
+    // fixed and auto remounts; that is a layout change, and a remount is the
+    // honest response to one.
+    //
+    // The dimensions default differently, deliberately: an omitted `width`
+    // means `'auto'` (a chart must have a width, and filling is the sensible
+    // way to get one), while an omitted `height` means *unmanaged* — the
+    // classic mode where rows declare pixel heights and the container is their
+    // sum. `'auto'` height is opt-in because it changes who answers "how tall
+    // is a row".
+    if (typeof width === 'number' && height !== 'auto') {
+        return _jsx(ResolvedChartContainer, { ...props, width: width, height: height });
     }
-    return _jsx(AutoWidthContainer, { ...props });
+    return _jsx(AutoSizeContainer, { ...props });
 }
 /**
  * The `width="auto"` half: render a plain full-width box, measure it, and
@@ -88,24 +95,47 @@ export function ChartContainer(props) {
  *    never overflow its own measurement. A caller who wants a bordered frame
  *    puts it on a wrapper *outside* the container.
  */
-function AutoWidthContainer(props) {
+function AutoSizeContainer(props) {
     const boxRef = useRef(null);
-    const [measured, setMeasured] = useState(0);
+    const [measured, setMeasured] = useState({ width: 0, height: 0 });
+    // Which dimensions this instance is responsible for. A numeric width with
+    // height="auto" measures height only, and vice versa.
+    const needWidth = typeof props.width !== 'number';
+    const needHeight = props.height === 'auto';
+    // The needs, readable from the long-lived measure closure without going
+    // stale — `props.width` can legally flip number ↔ 'auto' without leaving
+    // this component (the dispatcher only remounts on the managed/unmanaged
+    // boundary).
+    const needsRef = useRef({ needWidth, needHeight });
+    needsRef.current = { needWidth, needHeight };
     useLayoutEffect(() => {
         const el = boxRef.current;
         if (el === null)
             return;
         const measure = () => setMeasured((prev) => {
-            const next = Math.round(el.getBoundingClientRect().width);
-            // **Latch the last non-zero width.** A box measures 0 whenever it is
-            // not laid out — most often because an ancestor went `display: none`
-            // (a tab switch, a collapsed accordion), which is a *hidden* chart,
-            // not a resized one. Writing that 0 through would unmount the resolved
-            // container and discard everything it owns: pan/zoom position,
-            // selection, hover, and every layer's memoized draw state, all
-            // rebuilt on the way back. Keeping the stale width holds the chart
-            // mounted through the hide, and the next real measurement corrects it.
-            return next > 0 ? next : prev;
+            const need = needsRef.current;
+            const r = el.getBoundingClientRect();
+            // **Latch the last non-zero value, per dimension.** A box measures 0
+            // whenever it is not laid out — most often because an ancestor went
+            // `display: none` (a tab switch, a collapsed accordion), which is a
+            // *hidden* chart, not a resized one. Writing that 0 through would
+            // unmount the resolved container and discard everything it owns:
+            // pan/zoom position, selection, hover, and every layer's memoized
+            // draw state, all rebuilt on the way back. Keeping the stale value
+            // holds the chart mounted through the hide, and the next real
+            // measurement corrects it.
+            const w = Math.round(r.width);
+            const h = Math.round(r.height);
+            // Track only the dimensions this instance is responsible for
+            // (Layer-2 review find): a width-only container that also stored
+            // height would re-render its whole tree on every *content*-height
+            // change — the classic splitter drag, an axis strip growing a band
+            // row — where the pre-[PND-HEIGHT] width-only measure bailed.
+            const width = need.needWidth && w > 0 ? w : prev.width;
+            const height = need.needHeight && h > 0 ? h : prev.height;
+            return width === prev.width && height === prev.height
+                ? prev
+                : { width, height };
         });
         measure();
         // Guarded rather than assumed: a non-browser render target (SSR, an older
@@ -117,10 +147,58 @@ function AutoWidthContainer(props) {
         ro.observe(el);
         return () => ro.disconnect();
     }, []);
-    return (_jsx("div", { ref: boxRef, style: { width: '100%' }, children: measured > 0 && _jsx(ResolvedChartContainer, { ...props, width: measured }) }));
+    const width = needWidth ? measured.width : props.width;
+    const height = needHeight
+        ? measured.height
+        : props.height;
+    const ready = width > 0 && (!needHeight || measured.height > 0);
+    // **A measured dimension that stays 0 is a standing deadlock, not a slow
+    // start** — the parent's size is content-derived and the chart is the
+    // content that would have given it one, so nothing will ever paint and
+    // nothing errors. Worse for height than width: a flex-*column* child's
+    // height defaults to `auto`, so there the deadlock is the default, not an
+    // edge case. Say so once, in dev, after layout has had ample time.
+    const warnedZeroRef = useRef(false);
+    useEffect(() => {
+        if (!isDev || ready || warnedZeroRef.current)
+            return;
+        const t = setTimeout(() => {
+            if (ready || warnedZeroRef.current)
+                return;
+            const el = boxRef.current;
+            if (el === null)
+                return;
+            const r = el.getBoundingClientRect();
+            const stuck = [
+                ...(needWidth && Math.round(r.width) === 0 ? ['width'] : []),
+                ...(needHeight && Math.round(r.height) === 0 ? ['height'] : []),
+            ];
+            if (stuck.length === 0)
+                return;
+            warnedZeroRef.current = true;
+            console.warn(`[pond-charts] <ChartContainer> measured ${stuck.join(' and ')} of 0 ` +
+                `and it has not changed — the chart will stay blank. The measured ` +
+                `box fills its parent, so the parent needs a definite ` +
+                `${stuck.join('/')} (a sized ancestor, a flex basis, or ` +
+                `\`min-${stuck[0]}: 0\` on a flex child); a parent sized by its ` +
+                `own content deadlocks, because the chart is that content.`);
+        }, ZERO_SIZE_WARNING_MS);
+        return () => clearTimeout(t);
+    }, [ready, needWidth, needHeight]);
+    return (_jsx("div", { ref: boxRef, style: {
+            width: '100%',
+            // Only claim the parent's height when asked to measure it: a
+            // width-only auto container must keep its intrinsic height (the rows'
+            // sum), or every pre-[PND-HEIGHT] consumer's layout changes.
+            ...(needHeight ? { height: '100%', minHeight: 0 } : {}),
+        }, children: ready && (_jsx(ResolvedChartContainer, { ...props, width: width, height: height })) }));
 }
+/** How long a measured dimension may stay 0 before the dev warning names the
+ *  deadlock (see {@link AutoSizeContainer}). Long enough for any real layout
+ *  pass; a chart legitimately gated this long is not painting anyway. */
+const ZERO_SIZE_WARNING_MS = 600;
 /** {@link ChartContainer} with its width resolved to a concrete pixel number. */
-function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidth, bandAlign = 'start', width, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, panZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, xScale: xScaleKind = 'linear', grid = true, sessionDividers = 'none', children, }) {
+function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidth, bandAlign = 'start', width, height, rowGap = 0, showAxis = true, trackerPosition, onTrackerChanged, onDrawStats, panZoom = false, axisPanZoom = false, bounds, onTimeRangeChange, minDuration = 1, cursor: cursorProp, cursorSequence: cursorSequenceProp, onRegionSelect, regionSelectModifier, cursorTime: cursorTimeProp, crosshairSnap: crosshairSnapProp, editAnnotations = false, creating = null, onCreate, onSelectAnnotation, onHoverAnnotation, onEditAnnotation, snap = true, timeFormat, cursorFormat: cursorFormatProp, origin, theme, discontinuities, calendar, spacing, xScale: xScaleKind = 'linear', grid = true, sessionDividers = 'none', children, }) {
     // ── Legacy cursor props (deprecated) ───────────────────────────────────────
     // The string surface keeps working for one minor: the resolved mode is
     // synthesized into the equivalent mounted preset below (`<LegacyCursor>`),
@@ -128,6 +206,10 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
     // *explicitly* set (never on the defaults). Mounted cursor components in the
     // same scope override the shim. See docs/rfcs/interaction.md §9 / A4.4.
     const cursor = cursorProp ?? DEFAULT_CURSOR_MODE;
+    // [PND-HEIGHT] Whether this container owns vertical layout (see the
+    // `height` prop). Carried on the frame so a `<ChartRow flex>` can tell a
+    // home that can size it from one that never will.
+    const managesHeight = height !== undefined;
     // [PND-IGNITECAT] The declared slot list, normalized to `null` when absent
     // and held by **content** identity. An inline `categories={['a', 'b']}` is a
     // fresh array every render; keying the kind/scale memos off the raw prop
@@ -221,6 +303,11 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         panZoom === 'panZoomX' ||
         panZoom === 'panZoomXY';
     const zoomY = panZoom === 'panZoomY' || panZoom === 'panZoomXY';
+    // Axis-strip gestures are their own opt-in (see `axisPanZoom`), so they are
+    // resolved from that prop alone — never from `panZoom`, which would make every
+    // already-interactive chart grow axis gestures on upgrade.
+    const axisPanZoomX = axisPanZoom === true || axisPanZoom === 'x' || axisPanZoom === 'xy';
+    const axisPanZoomY = axisPanZoom === true || axisPanZoom === 'y' || axisPanZoom === 'xy';
     const panX = zoomX || panZoom === 'pan';
     const panY = zoomY;
     const panEnabled = panX || panY;
@@ -244,7 +331,14 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         const k = Math.max(1, next.k);
         setYTransform((prev) => prev.k === k && prev.ty === next.ty ? prev : { k, ty: next.ty });
     }, []);
-    const interactive = panEnabled || zoomEnabled;
+    // The x **strip**'s gestures move the same view the plot's do, so they must
+    // make the container own a view as well. Leaving `axisPanZoomX` out of this
+    // silently broke the headline combination — `axisPanZoom="x"` with the default
+    // `panZoom="none"`: `applyRange` wrote `internalRange` while `view` kept
+    // reading `seed`, so an uncontrolled strip captured the drag and drew nothing.
+    // (`axisPanZoomY` is absent on purpose: a gutter zoom is per-axis row state,
+    // not the shared x view.)
+    const interactive = panEnabled || zoomEnabled || axisPanZoomX;
     // The explicit base domain from `range` (a tuple or a TimeRange). `undefined`
     // ⇒ auto-fit (resolved from the layers below). Pan/zoom seeds from it; `seed`
     // is the placeholder while auto-fitting.
@@ -1210,6 +1304,11 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
     // it lives in `cursorFrame` below, [PND-HOVCTX] — but the tuple stays a memo
     // to hold the line for every other rebuild path.)
     const timeRangeTuple = useMemo(() => [d0, d1], [d0, d1]);
+    // The declared view (`range`), as against the gestured one above — the x
+    // strip's double-click reset target. Memoized on its endpoints for the same
+    // reason `timeRangeTuple` is: it sits on the frame, and a fresh tuple each
+    // render would re-identify it for every draw callback that reads the frame.
+    const seedRangeTuple = useMemo(() => [seed[0], seed[1]], [seed[0], seed[1]]);
     // The per-move cursor state, split into its own context so a mousemove
     // re-identifies only this small object — not the ~50-field frame below, which
     // stays stable across hovers so `YAxis` / `Bar` / `Box` don't re-render. See
@@ -1221,6 +1320,10 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
     }), [cursorX, hoverPoint]);
     const frame = useMemo(() => ({
         timeRange: timeRangeTuple,
+        seedRange: seedRangeTuple,
+        axisPanZoomX,
+        axisPanZoomY,
+        managesHeight,
         width,
         theme: theme ?? defaultTheme,
         plotWidth,
@@ -1302,6 +1405,10 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
         firstRowKey,
     }), [
         timeRangeTuple,
+        seedRangeTuple,
+        axisPanZoomX,
+        axisPanZoomY,
+        managesHeight,
         width,
         theme,
         plotWidth,
@@ -1385,13 +1492,33 @@ function ResolvedChartContainer({ range, categories: categoriesProp, maxBandWidt
                     // The 'line' default nobody asked for is IMPLICIT — the one cursor a
                     // <MultiSelector>'s resting block preview may replace with the
                     // brush band. An explicit `cursor` prop (any mode) still wins.
-                    implicit: cursorProp === undefined }), _jsxs("div", { style: { width: `${width}px` }, children: [_jsx("div", { style: {
+                    implicit: cursorProp === undefined }), _jsxs("div", { style: {
+                        width: `${width}px`,
+                        // [PND-HEIGHT] A managed height makes the outer box a flex
+                        // column: the rows block below flexes, the axis strip keeps its
+                        // natural height at the bottom, and CSS subtracts one from the
+                        // other. That subtraction being layout rather than arithmetic is
+                        // the feature — the strip's height varies with label, font size,
+                        // calendar bands and pill lanes, so no constant is correct.
+                        ...(height !== undefined
+                            ? {
+                                height: `${height}px`,
+                                display: 'flex',
+                                flexDirection: 'column',
+                            }
+                            : {}),
+                    }, children: [_jsx("div", { style: {
                                 display: 'flex',
                                 flexDirection: 'column',
                                 gap: `${rowGap}px`,
                                 // The positioned ancestor for overlay chrome (`<Legend>`): the
                                 // card anchors to the rows block, never the axis strip below.
                                 position: 'relative',
+                                // The rows block takes what the axis strip leaves. `minHeight:
+                                // 0` lets it shrink below its content — without it a flex
+                                // child's floor is its content and nothing can ever get
+                                // smaller.
+                                ...(height !== undefined ? { flex: '1 1 0%', minHeight: 0 } : {}),
                             }, children: children }), showAxis && _jsx(TimeAxis, {})] })] }) }));
 }
 //# sourceMappingURL=ChartContainer.js.map

package/dist/ChartRow.d.ts

@@ -1,8 +1,44 @@
 import { type ReactNode } from 'react';
 import { type CursorMode } from './context.js';
 export interface ChartRowProps {
-    /** Row height in CSS pixels. */
-    height: number;
+    /**
+     * Row height in CSS pixels — the **fixed** sizing mode. Omit it (or pass
+     * {@link flex}) to let the row share the container's remaining height
+     * instead; a bare `<ChartRow>` means `flex={1}`.
+     */
+    height?: number;
+    /**
+     * Share of the container's **remaining** height ([PND-HEIGHT]) — the
+     * CSS-flex sizing mode, and what an omitted `height` defaults to (`1`).
+     *
+     * The remainder is what CSS flex layout says it is: the container's height
+     * minus its axis strip, minus every fixed-`height` row, minus any non-row
+     * children you placed between rows (a draggable splitter), minus `rowGap`s.
+     * That is deliberate — the row's box is `flex: <n> 1 0`, so **the browser
+     * does the subtraction** and there is no strip-height constant for a caller
+     * to know, guess, or drift on (the reporting consumer had `20` and `24` in
+     * one codebase for a strip that is actually 22 — *when it is not showing a
+     * calendar band row or marker pills, which change it*). The row then reads
+     * back the height the layout gave it and builds its y-scales from that.
+     *
+     * Mixing modes is the point, not an edge case: a price row over a volume
+     * row is `<ChartRow flex={3}>` over `<ChartRow flex={1}>`; the splitter
+     * shape is one `flex` row that absorbs slack over one fixed row the drag
+     * resizes.
+     *
+     * **Needs a container that manages height** — `<ChartContainer
+     * height={number | 'auto'}>`. Inside a container with no height, a flex
+     * row's box has nothing to flex into, collapses to zero, and stays gated
+     * out; dev builds warn.
+     *
+     * A flex row's first useful paint waits for its first measurement — by
+     * **timing**, not a gate: the first render does execute children at height
+     * 0 (a 0-height canvas draws nothing), and the layout effect's synchronous
+     * setState delivers the real height before the browser paints. Like the
+     * container's `width="auto"`, it keeps its last non-zero height while
+     * hidden, so a `display: none` tab switch does not discard its scales.
+     */
+    flex?: number;
     /**
      * Cursor presentation for this row, overriding the container's default
      * ({@link ChartContainerProps.cursor}). Omit to inherit. See {@link CursorMode}.
@@ -32,5 +68,5 @@ export interface ChartRowProps {
  * Children lay out left-to-right in author order, so `<YAxis side="left"/>` goes
  * before `<Layers/>` and `<YAxis side="right"/>` after.
  */
-export declare function ChartRow({ height, cursor, children }: ChartRowProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChartRow({ height: heightProp, flex, cursor, children, }: ChartRowProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChartRow.d.ts.map