pond-ts 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -8,7 +8,11 @@ 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.55.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.57.0...HEAD
+[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
+[0.56.1]: https://github.com/pond-ts/pond/compare/v0.56.0...v0.56.1
+[0.56.0]: https://github.com/pond-ts/pond/compare/v0.55.0...v0.56.0
 [0.55.0]: https://github.com/pond-ts/pond/compare/v0.54.0...v0.55.0
 [0.54.0]: https://github.com/pond-ts/pond/compare/v0.53.1...v0.54.0
 [0.53.1]: https://github.com/pond-ts/pond/compare/v0.53.0...v0.53.1
@@ -56,6 +60,289 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.57.0] — 2026-08-07
+
+### Added
+
+- **charts: `<Zone>` — a shaded y-span annotation.** The fourth annotation
+  mark, and the value-axis counterpart of `<Region>`: a band between two y
+  values, spanning the full plot width. The mark for a **classification of the
+  value axis** — US EPA AQI categories, heart-rate / power zones, SLO bands,
+  control-chart spec limits — where a reading only means something read against
+  a scale.
+
+  ```tsx
+  {
+    AQI_CATEGORIES.map((c) => (
+      <Zone key={c.role} from={c.from} to={c.to} axis="aqi" role={c.role} />
+    ));
+  }
+  ```
+
+  Colour comes from `theme.annotation.roles[role]`, so a zone _set_ styles as
+  one palette in the theme rather than N colours at the call site. Bounds are
+  order-free, clamped to the plot (a band past the axis domain is cut, one
+  fully outside culls), and accept `±Infinity` for genuinely open-ended bands
+  (`to={Infinity}` — AQI's "Hazardous", a `ZoneTime.openEnded` zone), so a
+  whole category table can be rendered and the axis decides what shows.
+
+  Three defaults deliberately **invert** the rest of the annotation family,
+  because a zone spans the full width and a set tiles the row:
+  `selectable={false}` (else every mousemove lights a band and its hit area
+  eats the plot's clicks), `edges={false}` (contiguous sets share every
+  interior boundary — edges-on draws each twice), and no auto-label (the bounds
+  are already legible on the y axis; the useful label is a name). `<Zone>` has
+  no `onChange` — drag-to-edit zones await a consumer.
+
+  Guide: [From a CSV to a banded chart](https://pond-ts.org/docs/how-to-guides/air-quality-bands).
+
+- **charts: `annotation.dash` — an optional dash pattern for the annotation
+  register**, per-register or per-role (`{ color, fillOpacity?, dash? }`), same
+  shape as `LineStyle.dash`. Applies to marker / baseline lines and region /
+  zone boundaries; fills are never dashed. A dashed reference line reads as
+  _placed_ rather than _measured_ — the job the annotation register exists to
+  do, and one colour alone can't always carry.
+
+- **charts: threshold-banded bars** — `<BarChart thresholds={[1, 2]}>` colours
+  one bar **along its length** against a ladder (neutral → warning → alarm), so
+  a long bar shows how far through the ladder it travelled rather than only
+  which band it ended in. Band fills come from the new
+  **`BarStyle.bands`** on the resolved theme role, overridable per chart with
+  **`<BarChart bandColors>`** — breakpoints are data, colour stays in the theme,
+  the same split `colors` already applies to a stack's group fills.
+
+  The shape was previously expressible as N `<BarChart>` layers drawn
+  outermost-first, each clipped to a band, compositing the gradient by
+  overpainting. That produces the same pixels and loses what matters: N layers
+  means N hit targets, N `SelectInfo.mark` identities and N legend rows for
+  something the reader sees as one bar. Banding is **draw-only** — the hit rect
+  is untouched, so a banded bar stays one bar. It also measures **27–49%
+  cheaper** than the layered workaround at 8–400 categories
+  (`scripts/perf-bandbar.mjs`, which interleaves the arms and prints the
+  ratios), and costs nothing when unused.
+
+  Applies to any single-value bar — `series`, `bins`, `categories`, both
+  orientations. Negatives band symmetrically on the magnitude, so a ± diverging
+  scale needs no negative breakpoints. Ignored (with a dev warning) on a
+  multi-group stack, and yields to `binColors` when both are set. Suppresses
+  envelope decimation for the same reason `binColors` does.
+
+- **charts: `<YAxis hide>`** — keep the scale, draw no gutter, reserve no
+  width. A `<YAxis>` does two jobs — it _holds the scale_ (`min`/`max`/`scale`/
+  `pad`) and it _renders a gutter_ — and there was no way to ask for the first
+  without the second. A caller could express "auto domain, no gutter" (omit the
+  axis) or "explicit domain, with a gutter", but not the pairing a fixed-domain
+  chart needs. Omitting the axis is not equivalent: the row supplies an implicit
+  auto-domain axis, which is exactly what must not be given up. `width={0}`
+  isn't either — the labels still draw, over the plot.
+
+  Gridlines are unaffected: they belong to the plot, not the gutter, and
+  `<ChartContainer grid>` already governs them.
+
+- **charts: `<ChartContainer maxBandWidth>` + `bandAlign`** — cap the **slot
+  pitch** on a category x axis and place the resulting block
+  (`'start'` (default) / `'center'` / `'end'`). A band scale otherwise spreads
+  its categories across the full plot width, so three categories in a 900px
+  panel become three 300px bars and thirty become thirty 30px ones — the same
+  chart in the same panel reading as two different charts depending on how many
+  categories the data returned. Fine for a fixed domain; wrong for a **live**
+  one, where bar width becomes a variable that moves on its own and a reader
+  can't compare the chart to itself a minute ago.
+
+  `maxBandWidth` caps the **slot**; `<BarChart gap>` still insets the bar
+  within it — one knob for pitch, one for ink. Omitting `maxBandWidth` is the
+  previous fill behaviour exactly, and a cap too loose to bind degrades back to
+  it rather than clipping. There is deliberately no `bandAlign: 'fill'`: "fill"
+  is what omitting the cap means, and a `fill` alongside a pitch cap would be a
+  contradiction rather than a choice.
+
+  **Vertical / x-axis categories only** — a `orientation="horizontal"`
+  categorical chart puts its categories on the y axis as unit slots, a
+  different mechanism this does not cap.
+
+- **charts: themed emphasis on the category path** — `BarStyle.hover` /
+  `.highlight` now apply to `categories` and horizontal bars, which routed
+  through the transposed stacked draw path and read neither. New
+  `BarStyle.selectedOutline` (the selected bar's stroke, where the default is
+  its own fill) and `BarStyle.emphasisOpacity` (the alpha a live bar pops to,
+  previously hard-coded `1`) make the emphasis tunable rather than fixed.
+
+  The _behaviour_ was defensible; the problem was that the theme accepted
+  values it would not use. `bar.hover` / `.highlight` were typed, settable and
+  documented as the emphasis channel, and silently did nothing on the most
+  common categorical chart, so a theme author set them, saw no change, and
+  could not tell whether they were wrong about the colour or the mechanism.
+  The one genuine exclusion stays and is now the only one: a `binColors` bar
+  keeps its own colour under hover/selection, because swapping a
+  zone-coloured or direction-coloured bar to a single highlight hue erases
+  what the colour encodes.
+
+### Fixed
+
+- **charts: a negative segment in a multi-group stack is no longer silently
+  dropped** ([PND-SIGNSTACK]). Positives stack **up** from the baseline and
+  negatives stack **down** from it — two running totals per bin — so the
+  **signed stacked histogram** (net flow by category, inflow/outflow, buy/sell
+  pressure by venue) renders correctly. `stackValueExtent` grew the matching
+  negative half; both had to move together, since an extent stopping at `0`
+  would clip the segments the draw path now emits.
+
+  **This is a visible behaviour change** for any existing chart feeding
+  negative values into a multi-group stack — but such a chart was previously
+  rendering _wrongly_: the dropped segments did not clamp, warn or throw, every
+  remaining segment stacked up as though they had never been in the data, and a
+  mixed-sign series came out as a confident, wrong, all-positive chart. An
+  all-positive stack is bit-identical to before. Splitting into two layers was
+  not a workaround either — the negative layer was still `G > 1`, so it was
+  dropped too.
+
+### Changed
+
+- **charts (docs): `<BarChart bins>` now states that it selects a _value_
+  axis** ([PND-TICKUNIT]), so a time-bucketed histogram fed through `bins` gets
+  the decimal 1-2-5 tick ladder rather than the duration ladder a clock
+  subdivides by — labelling e.g. 11:40 and 13:20 at a ~100-minute step. The
+  natural reading ("I have pre-binned buckets, so I'll pass `bins`") is exactly
+  what forecloses the time axis, and nothing at the call site said so. The prop
+  docs now point a time-keyed caller at `<BarChart series columns>`, where the
+  clock ticks are native. No behaviour change.
+
+## [0.56.2] — 2026-08-05
+
+### Fixed
+
+- **charts (tests only, no shipped change):** the log-axis rendered-label test
+  is no longer an exact-set assertion over every digit-bearing node in the
+  render tree. It passed on Node 22 and failed on CI's Node 18 with one extra
+  element, blocking the publish twice. The discrepancy is **unreproduced and
+  still open** — recorded as `[PND-LOGTICK-N18]` in `PND_CHARTS_PLAN.md` with
+  everything measured about it. The assertion now checks that every chosen tick
+  renders in order, which is the wiring this test exists to cover; the tick
+  _selection_ it was really about is pinned deterministically by the
+  `yTickValues` unit tests.
+
+## [0.56.1] — 2026-08-05
+
+### Fixed
+
+- **charts (tests only, no shipped change):** a log-axis test asserted on
+  rendered label _text_, parsing numbers back out of the DOM to infer scale
+  behaviour. It passed locally and failed in CI on a value it could not have
+  produced there, which blocked the v0.56.0 publish. The root cause was never
+  reproduced; rather than guess at it, the assertion now compares the rendered
+  labels against the ticks the axis is specified to draw, formatted through the
+  same formatter — deterministic regardless of locale, formatting or DOM
+  differences, and the numeric guarantee itself was already pinned directly by
+  the `yTickValues` unit tests. The published artifact is identical to what
+  v0.56.0 would have been.
+
+## [0.56.0] — 2026-08-05
+
+### Added
+
+- **charts:** **`<YAxis scale="log">` — a base-10 logarithmic y axis.** Every y
+  scale was `scaleLinear`, so data spanning orders of magnitude was
+  undrawable: on a linear axis everything below the top decade collapses onto
+  the baseline. Set `scale="log"` and the axis maps by ratio, ticking the
+  decades. `format` still formats the **value**, so a readout says `1.2 PB`
+  rather than its logarithm — the transform is in the scale, not in the data,
+  which is what keeps it transparent to every draw layer, annotation and
+  cursor readout.
+
+  A log domain cannot contain zero, and d3 maps a non-positive value to
+  **`NaN`** — a coordinate the canvas silently _drops_, which is why every
+  consequence below is about something failing invisibly rather than throwing.
+  So the axis is deliberate about it:
+  - **Domain policy matches the linear axis exactly.** Auto-fit takes the
+    smallest **positive** extent (one zero sample can't collapse the axis, and
+    a `BarChart` — whose extent always widens to include zero — can still share
+    it); a positive explicit `min`/`max` is honoured verbatim and never
+    discarded, with the _auto-fit_ side moving if the domain would otherwise
+    invert; a fully auto-fit domain is `.nice()`d out to whole powers of ten, so
+    the extremes get headroom instead of sitting clipped on the plot edge. A
+    non-positive bound has no position and is refused in favour of the data.
+    `pad` is applied multiplicatively, adding the same fraction of a decade at
+    both ends.
+  - **A value with no position on the axis renders as a gap.** Previously the
+    gap test was `Number.isFinite(value)`, and `0` is finite — so the coordinate
+    became `NaN`, the canvas dropped the path op without breaking the path, and
+    the two neighbours were joined by a straight line _over_ the missing data.
+    Lines, area fills and outlines, and band envelopes now all break there.
+  - **Layers that reach for a baseline rest on the axis floor.** `AreaChart`
+    resolves an out-of-domain `baseline` there (writing `baseline={0}` is
+    natural and correct on a linear axis), and a **stacked** bar layer starts
+    its first segment there — starting at zero made the bottom segment of every
+    stack both invisible and unhittable. Unchanged on a linear axis, where zero
+    clamped into the domain _is_ zero.
+  - **The dev-mode warning names only unambiguous mistakes**: a refused
+    `min`/`max`, negative data, or an axis with no positive data at all. It
+    deliberately says nothing about an extent of exactly `[0, hi]`, which a
+    line touching zero and a bar layer on strictly positive data both report
+    identically — warning there fired on _every_ bar chart on a log axis. It
+    warns once per distinct complaint rather than on every repaint.
+
+- **charts:** **pan and zoom now yield whole-millisecond view ranges.** A
+  wheel-zoom derives its range from pixel positions through `xScale.invert()`,
+  so the result was fractional by construction — an ordinary scroll produced
+  `1.7e12 + 0.37`. The epoch millisecond is this model's atomic unit and
+  consumers are entitled to assume it; one did, and a calendar `cursorSequence`
+  threw on a plain scroll. `zoomRange` / `panRange` round both ends, and never
+  collapse a positive span to zero width in doing so. (Core's fractional-instant
+  fix covers the same crash from the other side; this closes the class.)
+
+- **charts:** **`AreaStyle.flatFill` — stacked areas that read as slabs.** An
+  area's fill has always graded to transparent at the baseline, which is right
+  for the elevation form and wrong for a stack: every band showed the one
+  beneath it through the fade, so a stacked area was not really drawable. Set
+  `flatFill` and the fill is flat; omitted, the gradient is unchanged, so no
+  existing theme shifts. The docs theme's `seq1…seq8` area roles set it, since
+  stacking is what they exist for.
+
+- **docs theme:** **a sequential ramp — `seq1…seq8` — for charts with more
+  series than the categorical set has hues.** `--pond-viz-1…5` were, and
+  remain, the categorical set; a chart needing more slots (an eight-source
+  stack, a wall of climate stripes) now steps **tonally** through the brand
+  teal instead of introducing competing hues. Eight steps, evenly spaced
+  (~ΔL\* 9 in CIELAB), defined for light and dark, each mode's ramp containing
+  that mode's `--pond-viz-1` exactly. Exposed as `line` / `area` / `bar` theme
+  roles on `docsTheme` (Storybook) and the docs site's `useSiteChartTheme`,
+  and as an array from the site's `useSequentialRamp()`. Dev-only: the ramp
+  lives in the `docs-theme.fixture.ts` Storybook fixture and the website's
+  CSS, both excluded from the published `@pond-ts/charts` build — the library
+  still ships no palette.
+
+### Fixed
+
+- **core:** **a fractional epoch millisecond no longer crashes calendar
+  math.** `Temporal.Instant` refuses a non-integer epoch ms outright
+  (`epoch milliseconds must be an integer`), and `toPlainDateStart` passed
+  whatever it was given straight through — so realizing a `Sequence.calendar`
+  over a fractional range threw, and in a React app the exception unmounted the
+  page. A fraction is not a caller error: a chart's wheel-zoom derives its view
+  range from pixel positions via `xScale.invert()`, so an ordinary scroll
+  produces `1.7e12 + 0.37`. The instant is now floored to the millisecond
+  containing it — the epoch millisecond is this model's atomic unit and
+  calendar boundaries are themselves whole milliseconds, so the bucket
+  containing `t` and the one containing `t + 0.37` are necessarily the same,
+  and integer inputs are untouched. (`Math.floor`, not `Math.trunc`: pre-1970
+  they disagree, and `-5.5` lies inside the millisecond spanning `[-6, -5)`.)
+
+- **charts:** toggling **`<ChartContainer grid>`** now repaints immediately.
+  `Layers`' draw callback read `container.grid` but didn't depend on it, so
+  switching gridlines off changed nothing until an unrelated dependency moved —
+  in practice you had to pan or zoom a little to force the update. The same
+  omission covered `sessionDividers` and `xKind`.
+
+- **charts:** the log axis's dev-mode warning no longer requires **node's
+  ambient types**. It was guarded by a bare `process.env.NODE_ENV`, which
+  typechecks only when a tool happens to resolve `@types/node` from a parent
+  `node_modules` — so `tsc` inside the package passed while running the _same_
+  tsconfig from a consumer's directory failed with `TS2591: Cannot find name
+'process'`. That took out the docs site's TypeDoc step, and would equally hit
+  any consumer typechecking the package's sources. The guard now lives in
+  `src/dev.ts` behind a local declaration and a `typeof` check, so a browser
+  bundle with no `process` global doesn't throw at import either.
+
 ## [0.55.0] — 2026-08-04
 
 ### Added

package/dist/core/calendar.js

@@ -43,7 +43,24 @@ export function parseTimestampString(value, options = {}) {
     return Temporal.Instant.from(value).epochMilliseconds;
 }
 export function toPlainDateStart(instantMs, timeZone, unit, weekStartsOn) {
-    const zoned = Temporal.Instant.fromEpochMilliseconds(instantMs).toZonedDateTimeISO(timeZone);
+    // **Floor to the containing millisecond.** `Temporal.Instant` refuses a
+    // fractional epoch ms outright — `fromEpochMilliseconds(1577836800000.37)`
+    // throws `epoch milliseconds must be an integer` — and a fraction is not a
+    // caller error here. A chart's wheel-zoom derives its view range from pixel
+    // positions through `xScale.invert()`, so a perfectly ordinary gesture hands
+    // us `1.7e12 + 0.37`; realizing a calendar sequence over that range then
+    // crashed the page outright.
+    //
+    // Flooring is the only sane reading rather than a papering-over: the epoch
+    // millisecond *is* the atomic unit of this model, so an over-precise input
+    // can only mean the millisecond containing it, and calendar boundaries are
+    // themselves whole milliseconds — so the bucket containing `t` and the one
+    // containing `t + 0.37` are necessarily the same. Integer inputs are
+    // untouched.
+    //
+    // `Math.floor`, not `Math.trunc`: before 1970 they disagree, and `-5.5` lies
+    // inside the millisecond spanning `[-6, -5)`, which is `-6`.
+    const zoned = Temporal.Instant.fromEpochMilliseconds(Math.floor(instantMs)).toZonedDateTimeISO(timeZone);
     const date = zoned.toPlainDate();
     if (unit === 'day') {
         return date;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {