@pond-ts/charts 0.55.0 → 0.57.0

package/dist/domain.js

@@ -1,4 +1,4 @@
-import { scaleLinear } from 'd3-scale';
+import { scaleLinear, scaleLog } from 'd3-scale';
 /**
  * Resolve a y-axis `[lo, hi]` domain from its explicit bounds and the extents of
  * the layers linked to it. An `undefined` bound auto-fits the data: with no
@@ -20,8 +20,17 @@ import { scaleLinear } from 'd3-scale';
  * `pad × span` on each side — headroom without hand-computing bounds, useful to
  * lift a tight **explicit** domain off the plot edges. Applied last, to whatever
  * domain was resolved (explicit or auto); `0` is a no-op.
+ *
+ * `scale` selects the spacing. `'log'` delegates to {@link resolveLogDomain},
+ * which applies **every policy above** — verbatim explicit bounds, an auto-fit
+ * side that moves rather than a caller's bound being discarded, `.nice()` on a
+ * fully auto-fit domain — and differs only where a log axis forces it to: a
+ * non-positive bound has no position and is refused, and `pad` is a fraction of
+ * the *decades* spanned rather than of the difference.
  */
-export function resolveYDomain(min, max, extents, pad = 0) {
+export function resolveYDomain(min, max, extents, pad = 0, scale = 'linear') {
+    if (scale === 'log')
+        return resolveLogDomain(min, max, extents, pad);
     const result = resolveBase(min, max, extents);
     if (pad) {
         const [lo, hi] = result;
@@ -30,6 +39,190 @@ export function resolveYDomain(min, max, extents, pad = 0) {
     }
     return result;
 }
+/** Smallest positive value a log domain will fall back to when the data offers
+ *  nothing positive at all. Arbitrary but finite — a log scale has no natural
+ *  zero to anchor on, and `[0, 1]` (the linear empty-data domain) has no
+ *  position for its own low end: `scaleLog().domain([0, 1])(x)` is `NaN` for
+ *  every `x`, which poisons every coordinate drawn against it. */
+const LOG_EMPTY_LO = 1;
+const LOG_EMPTY_HI = 10;
+/**
+ * The log analog of {@link resolveBase} + padding.
+ *
+ * The **policy** is deliberately identical to linear's, so `scale="log"` changes
+ * how a domain is spaced and not what the props mean:
+ *
+ * - **Two explicit bounds are verbatim** (an inverted pair is a deliberate axis
+ *   flip; we don't second-guess it).
+ * - **A partial explicit bound is never discarded.** When one side is explicit
+ *   and the resolved domain would invert, the **auto-fit** side moves — exactly
+ *   as {@link resolveBase} does. (This inverted the caller's policy until the
+ *   log-axis review: `resolveLogDomain(undefined, 100, [[1000, 2000]])` returned
+ *   `[1000, 10000]`, silently throwing away the requested `max` and putting the
+ *   axis three decades from where it was asked to be.)
+ * - **A fully auto-fit domain is `.nice()`d**, the promise {@link resolveYDomain}
+ *   already documents. `scaleLog().nice()` extends to whole powers of ten, so
+ *   the extremes get headroom instead of sitting clipped against the plot edge
+ *   and the decade ticks land on the domain bounds.
+ *
+ * Two things differ from linear, and both are consequences of the same fact —
+ * that a log axis has no position for zero:
+ *
+ * - **Non-positive bounds are unusable.** Auto-fit takes the smallest
+ *   *positive* extent rather than the smallest, so one zero sample doesn't
+ *   collapse the axis; an explicit non-positive `min`/`max` is ignored in
+ *   favour of the data (a caller asking for `min={0}` on a log axis has asked
+ *   for `NaN` — see {@link logAxisWarning} — which we will not hand to a scale).
+ *   A bound refused this way is treated as *absent* from here on, so the side
+ *   that survives is still honoured as an explicit bound.
+ * - **Padding is multiplicative.** `pad` is a *fraction of the domain*, and on
+ *   a log axis the domain's span is a ratio, not a difference. Padding
+ *   additively would add a constant number of bytes to a decade — invisible at
+ *   the top, enormous at the bottom. Applying it in log space adds the same
+ *   *fraction of a decade* at both ends, which is what the linear behaviour
+ *   looks like to the eye. (The expression is sign-correct on a flipped domain
+ *   for the same reason linear's is: `log10(hi/lo)` goes negative, so both ends
+ *   still move outward.)
+ */
+function resolveLogDomain(min, max, extents, pad) {
+    // A non-positive explicit bound is refused, and from here on is simply absent
+    // — so `max={1e6}` with a refused `min={0}` still behaves as "explicit top,
+    // auto-fit floor" rather than falling into the both-explicit branch.
+    const explicitLo = min !== undefined && min > 0 ? min : undefined;
+    const explicitHi = max !== undefined && max > 0 ? max : undefined;
+    const [lo, hi] = resolveLogBase(explicitLo, explicitHi, extents);
+    if (!pad)
+        return [lo, hi];
+    // A fraction of the *decades* spanned, added at each end.
+    const decades = Math.log10(hi / lo) * pad;
+    return [lo / 10 ** decades, hi * 10 ** decades];
+}
+/** {@link resolveLogDomain} minus the padding — the domain itself. */
+function resolveLogBase(explicitLo, explicitHi, extents) {
+    // Both bounds explicit (and positive): trust them verbatim, matching
+    // `resolveBase` — including an intentional flip.
+    if (explicitLo !== undefined && explicitHi !== undefined) {
+        return [explicitLo, explicitHi];
+    }
+    let dataLo = Infinity;
+    let dataHi = -Infinity;
+    for (const e of extents) {
+        if (!e)
+            continue;
+        // The low end walks both ends of the extent: a series whose min is 0 or
+        // negative can still have a positive max, and that max is the only
+        // positive floor it can offer.
+        if (e[0] > 0 && e[0] < dataLo)
+            dataLo = e[0];
+        else if (e[1] > 0 && e[1] < dataLo)
+            dataLo = e[1];
+        if (e[1] > dataHi)
+            dataHi = e[1];
+    }
+    if (dataLo === Infinity || !(dataHi > 0)) {
+        // Nothing positive to fit — the log counterpart of linear's `[0, 1]`.
+        dataLo = LOG_EMPTY_LO;
+        dataHi = LOG_EMPTY_HI;
+    }
+    else if (dataLo === dataHi) {
+        // Flat — give it room, so a constant line sits mid-row rather than on an
+        // edge (linear's ±1, expressed as a ratio: half a decade each way).
+        dataLo /= 10 ** 0.5;
+        dataHi *= 10 ** 0.5;
+    }
+    let lo = explicitLo ?? dataLo;
+    let hi = explicitHi ?? dataHi;
+    // A partial explicit bound can sit at or past the auto-fit other side. Keep
+    // the axis ascending by moving the *auto-fit* side — never discard the
+    // caller's explicit bound. Exactly one side is explicit here: both-explicit
+    // returned early, and a both-auto domain can't invert after the guards above.
+    if (lo >= hi) {
+        if (explicitLo === undefined)
+            lo = hi / 10; // hi is explicit → preserve it
+        else
+            hi = lo * 10; // lo is explicit → preserve it
+    }
+    // Fully auto-fit → round out to whole powers of ten, for headroom and so the
+    // decade ticks reach the domain bounds. A partial/full explicit bound is left
+    // exact, exactly as `resolveBase` leaves it.
+    if (explicitLo === undefined && explicitHi === undefined) {
+        return scaleLog().domain([lo, hi]).nice().domain();
+    }
+    return [lo, hi];
+}
+/**
+ * Does resolving this axis's domain need its layers' extents walked?
+ * `yExtent()` is O(points) per layer, so the caller only pays it when a side
+ * actually auto-fits.
+ *
+ * A log axis **refuses a non-positive bound** ({@link resolveLogDomain}), which
+ * means such a bound is not a bound: that side auto-fits and needs the data. The
+ * naive `min === undefined || max === undefined` test misses this, and the miss
+ * is silent — `<YAxis scale="log" min={0} max={1e6}>` looked fully explicit, so
+ * no extents were gathered, so the refused floor fell back to the empty-data
+ * placeholder instead of the data's own floor. (`resolveLogDomain`'s unit tests
+ * passed throughout: they hand it the extents directly, which is precisely what
+ * the component was not doing.)
+ */
+export function needsExtents(axis) {
+    if (axis.scale === 'log') {
+        return (!(axis.min !== undefined && axis.min > 0) ||
+            !(axis.max !== undefined && axis.max > 0));
+    }
+    return axis.min === undefined || axis.max === undefined;
+}
+/**
+ * The dev-mode complaint a `scale="log"` axis has about its own bounds and the
+ * data linked to it, or `null` when it has none. Pure, so the policy is unit
+ * tested directly rather than through a rendered console spy.
+ *
+ * **Every case here is unambiguous**, which is the whole design constraint. The
+ * previous version warned whenever a linked extent reached zero, and that fires
+ * on *every* `BarChart` — `barExtent` always widens its low end to `0` so a bar
+ * can reach its baseline, whether or not the data goes anywhere near it. So the
+ * `WithBars` story warned, on strictly positive data, with text asserting
+ * something false about it. A dev warning that cries wolf gets muted, and then
+ * the real ones are lost too.
+ *
+ * The cost of that precision is the one genuinely ambiguous shape: an extent of
+ * exactly `[0, hi]`, which is what a line touching zero *and* a bar layer on
+ * positive data both report. It is not warned about. That case is no longer
+ * silent, though — a sample with no position on the axis now renders as a
+ * **gap** rather than being bridged straight over, so the picture itself says
+ * the data is missing there.
+ */
+export function logAxisWarning(axis, extents) {
+    if (axis.scale !== 'log')
+        return null;
+    const reasons = [];
+    // `!(x > 0)` rather than `x <= 0` so a NaN bound is caught too — it is refused
+    // by the same rule and is just as invisible.
+    if (axis.min !== undefined && !(axis.min > 0)) {
+        reasons.push(`min={${axis.min}} was ignored (it is not a positive number)`);
+    }
+    if (axis.max !== undefined && !(axis.max > 0)) {
+        reasons.push(`max={${axis.max}} was ignored (it is not a positive number)`);
+    }
+    const present = extents.filter((e) => e !== null);
+    if (present.some((e) => e[0] < 0)) {
+        reasons.push('data linked to this axis includes negative values');
+    }
+    // Independent of the above, not an `else`: an axis whose data is *entirely*
+    // non-positive is both negative-valued and undrawable, and the second fact is
+    // the one that explains the empty plot.
+    if (present.length > 0 && !present.some((e) => e[1] > 0)) {
+        // There is data, and none of it is positive — the whole axis is a fallback
+        // domain and nothing will be drawn against it.
+        reasons.push(`no data linked to this axis is positive, so the domain fell back to ` +
+            `[${LOG_EMPTY_LO}, ${LOG_EMPTY_HI}]`);
+    }
+    if (reasons.length === 0)
+        return null;
+    return (`<YAxis id="${axis.id}" scale="log">: ${reasons.join('; ')}. ` +
+        'A log scale has no position for zero or negative numbers (d3 maps them ' +
+        'to NaN), so such values are refused as bounds and are not drawn. Filter ' +
+        'them out, or use the default linear scale.');
+}
 function resolveBase(min, max, extents) {
     // Both bounds explicit: trust them verbatim (allows an intentional flip).
     if (min !== undefined && max !== undefined)

package/dist/format.d.ts

@@ -45,6 +45,9 @@ export type CursorFormat = string | ((value: number, ctx: {
  *  optional specifier. A d3 `ScaleLinear` / `ScaleTime` satisfies it. */
 interface Tickable {
     tickFormat(count: number, specifier?: string): (value: number) => string;
+    /** Present on d3's `scaleLog` and on no other continuous scale. */
+    base?: () => number;
+    domain?: () => number[];
 }
 /**
  * Resolve an {@link AxisFormat} (or `undefined`) to a `(value) => string`
@@ -55,6 +58,23 @@ interface Tickable {
  * - a **specifier string** → `scale.tickFormat(count, specifier)` — d3 applies
  *   the specifier, so the readout matches ticks formatted the same way;
  * - **`undefined`** → `scale.tickFormat(count)` — the scale's default.
+ *
+ * **A log scale is formatted through a linear one over the same domain.**
+ * `scaleLog.tickFormat` is not a value formatter — it is a *tick* formatter,
+ * and it deliberately returns `''` for anything it doesn't consider a
+ * significant tick:
+ *
+ * ```
+ * scaleLog().domain([1.9e10, 2.6e17]).tickFormat(6, '.3s')(1.97e17) === ''
+ * ```
+ *
+ * That is correct for axis labels (it is how a log axis thins them) and
+ * catastrophic for the cursor readout, `YAxisIndicator` and `Baseline` chips,
+ * which share this formatter and ask it about arbitrary values — they would
+ * render blank for almost every real number. A linear scale's `tickFormat`
+ * 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.
  */
 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

@@ -1,11 +1,4 @@
-/**
- * Axis value formatting — the single formatter shared by an axis's tick labels
- * and the cursor readout, so a value reads the same in both places (the readout
- * "matches the axes"). d3-style: a format **specifier string** (e.g. `'.0%'`,
- * `',.2f'`) is applied through the scale's own `tickFormat` (the same path d3
- * uses for the ticks), a **function** is used verbatim, and `undefined` falls
- * back to the scale's default `tickFormat`.
- */
+import { scaleLinear } from 'd3-scale';
 /**
  * Resolve an {@link AxisFormat} (or `undefined`) to a `(value) => string`
  * formatter, given the `scale` it formats against and the axis `count` (so the
@@ -15,13 +8,33 @@
  * - a **specifier string** → `scale.tickFormat(count, specifier)` — d3 applies
  *   the specifier, so the readout matches ticks formatted the same way;
  * - **`undefined`** → `scale.tickFormat(count)` — the scale's default.
+ *
+ * **A log scale is formatted through a linear one over the same domain.**
+ * `scaleLog.tickFormat` is not a value formatter — it is a *tick* formatter,
+ * and it deliberately returns `''` for anything it doesn't consider a
+ * significant tick:
+ *
+ * ```
+ * scaleLog().domain([1.9e10, 2.6e17]).tickFormat(6, '.3s')(1.97e17) === ''
+ * ```
+ *
+ * That is correct for axis labels (it is how a log axis thins them) and
+ * catastrophic for the cursor readout, `YAxisIndicator` and `Baseline` chips,
+ * which share this formatter and ask it about arbitrary values — they would
+ * render blank for almost every real number. A linear scale's `tickFormat`
+ * 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.
  */
 export function resolveAxisFormat(scale, count, format) {
     if (typeof format === 'function')
         return format;
+    const source = typeof scale.base === 'function' && typeof scale.domain === 'function'
+        ? scaleLinear().domain(scale.domain())
+        : scale;
     return format !== undefined
-        ? scale.tickFormat(count, format)
-        : scale.tickFormat(count);
+        ? source.tickFormat(count, format)
+        : source.tickFormat(count);
 }
 /**
  * The time analog of {@link resolveAxisFormat} — resolve an {@link AxisFormat}

package/dist/gaps.d.ts

@@ -72,6 +72,39 @@ export interface GapEdge {
     /** Pixel y of the next-good sample (`toIndex`). */
     readonly toY: number;
 }
+/**
+ * Return `values` with every entry that has **no position on `scale`** replaced
+ * by `NaN` — i.e. converted into the gap signal the rest of this module, the
+ * `.defined` predicates, and the affine draw loops already speak. Returns the
+ * input array itself (no copy) when nothing needs gapping, which is the
+ * overwhelmingly common case.
+ *
+ * **Why the raw value is not the right test.** Every gap check in this package
+ * asks `Number.isFinite(value)`, and `0` is finite — so on a **log** axis a zero
+ * sample sailed through as real data, d3 emitted `lineTo(x, NaN)` for it, and
+ * the canvas spec says a path op with a non-finite coordinate is *dropped*. Not
+ * drawn as a break: dropped. The pen stays where it was, the next point draws
+ * from there, and the two neighbours of the missing sample join with a straight
+ * line — a bridge over absent data, which is the one thing
+ * `docs/rfcs/charts.md` trap #2 exists to prevent, arrived at silently by a
+ * chart that had asked for the honest `'empty'` mode.
+ *
+ * Testing the **scaled** coordinate instead is both the honest answer and the
+ * general one: it needs no knowledge of which scale kind is in play, and any
+ * future scale with a restricted domain (`sqrt`, `pow` with a fractional
+ * exponent) inherits it. Normalizing to `NaN` here rather than special-casing
+ * three `.defined` predicates means the gap *modes* keep working too — a
+ * `'dashed'` connector spans it, `'none'` interpolates across it, `'fade'`
+ * drops to the floor at it — instead of the value being invisible to
+ * {@link collectGapEdges} and {@link bridgeGaps}, which read the values directly.
+ *
+ * **Costs nothing on a linear axis.** An affine scale ({@link affineOf}) maps
+ * every finite value to a finite pixel by construction, so there is nothing to
+ * find and the walk is skipped outright. That is also exactly the condition
+ * under which the callers take their affine fast path, so the O(N) probe only
+ * ever runs where the draw was already on the d3-scale path.
+ */
+export declare function gapUnscalable(values: Float64Array, length: number, scale: Scale): Float64Array;
 /**
  * Return a copy of `values` with **interior** gaps (NaN runs that have a finite
  * sample on each side) linearly interpolated across, for the `none` mode — so d3

package/dist/gaps.js

@@ -1,3 +1,4 @@
+import { affineOf } from './affine.js';
 /** The default gap mode — break at the gap, leave a hole (today's behavior). */
 export const DEFAULT_GAP_MODE = 'empty';
 /**
@@ -6,6 +7,54 @@ export const DEFAULT_GAP_MODE = 'empty';
  * inferred bridge reads as secondary to measured data.
  */
 export const DEFAULT_GAP_CONNECTOR_OPACITY = 0.5;
+/**
+ * Return `values` with every entry that has **no position on `scale`** replaced
+ * by `NaN` — i.e. converted into the gap signal the rest of this module, the
+ * `.defined` predicates, and the affine draw loops already speak. Returns the
+ * input array itself (no copy) when nothing needs gapping, which is the
+ * overwhelmingly common case.
+ *
+ * **Why the raw value is not the right test.** Every gap check in this package
+ * asks `Number.isFinite(value)`, and `0` is finite — so on a **log** axis a zero
+ * sample sailed through as real data, d3 emitted `lineTo(x, NaN)` for it, and
+ * the canvas spec says a path op with a non-finite coordinate is *dropped*. Not
+ * drawn as a break: dropped. The pen stays where it was, the next point draws
+ * from there, and the two neighbours of the missing sample join with a straight
+ * line — a bridge over absent data, which is the one thing
+ * `docs/rfcs/charts.md` trap #2 exists to prevent, arrived at silently by a
+ * chart that had asked for the honest `'empty'` mode.
+ *
+ * Testing the **scaled** coordinate instead is both the honest answer and the
+ * general one: it needs no knowledge of which scale kind is in play, and any
+ * future scale with a restricted domain (`sqrt`, `pow` with a fractional
+ * exponent) inherits it. Normalizing to `NaN` here rather than special-casing
+ * three `.defined` predicates means the gap *modes* keep working too — a
+ * `'dashed'` connector spans it, `'none'` interpolates across it, `'fade'`
+ * drops to the floor at it — instead of the value being invisible to
+ * {@link collectGapEdges} and {@link bridgeGaps}, which read the values directly.
+ *
+ * **Costs nothing on a linear axis.** An affine scale ({@link affineOf}) maps
+ * every finite value to a finite pixel by construction, so there is nothing to
+ * find and the walk is skipped outright. That is also exactly the condition
+ * under which the callers take their affine fast path, so the O(N) probe only
+ * ever runs where the draw was already on the d3-scale path.
+ */
+export function gapUnscalable(values, length, scale) {
+    if (affineOf(scale) !== null)
+        return values;
+    let out = null;
+    for (let i = 0; i < length; i += 1) {
+        const v = values[i];
+        if (!Number.isFinite(v) || Number.isFinite(scale(v)))
+            continue;
+        // Copy lazily — a log axis whose data never touches zero (the normal case)
+        // pays a scan and no allocation.
+        if (out === null)
+            out = values.slice();
+        out[i] = NaN;
+    }
+    return out ?? values;
+}
 /**
  * Return a copy of `values` with **interior** gaps (NaN runs that have a finite
  * sample on each side) linearly interpolated across, for the `none` mode — so d3

package/dist/index.d.ts

@@ -64,8 +64,8 @@ export { scaleTradingTime } from './tradingTimeScale.js';
 export type { TradingTimeScale, DiscontinuityProvider, TimeGrain, } from './tradingTimeScale.js';
 export { scaleBand } from './bandScale.js';
 export type { ScaleBand } from './bandScale.js';
-export { Region, Baseline, Marker } from './annotations.js';
-export type { RegionProps, BaselineProps, MarkerProps } from './annotations.js';
+export { Region, Baseline, Marker, Zone } from './annotations.js';
+export type { RegionProps, BaselineProps, MarkerProps, ZoneProps, } from './annotations.js';
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';

package/dist/index.js

@@ -51,8 +51,9 @@ export { scaleTradingTime } from './tradingTimeScale.js';
 // The ordinal category (band) scale — the transpose view's "columns on x" axis.
 export { scaleBand } from './bandScale.js';
 // Annotations — user-authored marks in the turquoise register (distinct from the
-// data): a shaded span, a horizontal value line, a vertical x line.
-export { Region, Baseline, Marker } from './annotations.js';
+// data): a shaded x span, a horizontal value line, a vertical x line, and a
+// shaded y span (`<Zone>` — value-axis classifications: AQI categories, HR zones).
+export { Region, Baseline, Marker, Zone } from './annotations.js';
 // Axis indicators — a value pill pinned to an axis edge (the ChartIQ live tag).
 // `createLiveValue` is the high-frequency, isolated-repaint update path.
 export { YAxisIndicator, createLiveValue } from './indicators.js';

package/dist/line.js

@@ -2,7 +2,7 @@ import { line as d3line, curveLinear } from 'd3-shape';
 import { cullChartSeries } from './culling.js';
 import { decimateM4Cached } from './decimate.js';
 import { affineOf } from './affine.js';
-import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
+import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, gapUnscalable, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 /** Shared empty boundary list — passed to `sessionRuns` when a decimated series
  *  already carries its session breaks as baked-in `NaN` points. */
 const EMPTY_BOUNDARIES = [];
@@ -131,6 +131,15 @@ export function drawLine(ctx, cs, xScale, yScale, style, curve = curveLinear, ga
     else {
         cs = cullChartSeries(source, xScale);
     }
+    // Normalize any value with **no position on the y scale** (a zero or negative
+    // sample on a log axis) into the ordinary NaN gap signal, so every consumer
+    // below — the `.defined` break, `bridgeGaps`, `collectGapEdges` — treats it as
+    // the absence it is instead of emitting a dropped `lineTo(x, NaN)` that
+    // silently bridges its neighbours. A no-op on an affine (linear) y scale; see
+    // {@link gapUnscalable}.
+    const scaledY = gapUnscalable(cs.y, cs.length, yScale);
+    if (scaledY !== cs.y)
+        cs = { ...cs, y: scaledY };
     // Split into independent index runs at each boundary; no boundary inside the
     // data ⇒ one run over the whole series (the hot path — no slicing, so the draw
     // is byte-identical to the pre-boundary single pass). When the series was

package/dist/theme.d.ts

@@ -179,20 +179,36 @@ export interface ChartTheme {
         readonly color: string;
         readonly fillOpacity: number;
         readonly depth: readonly [number, number, number];
+        /**
+         * Optional dash pattern for the register's **lines** — px on/off lengths,
+         * the same shape as {@link LineStyle.dash} (`[6, 4]` = 6 on, 4 off). Omit or
+         * `[]` for solid strokes. Applies to a marker's / baseline's line and to
+         * region + zone boundaries; fills are never dashed.
+         *
+         * Worth reaching for when marks share a plot with data lines: a *dashed*
+         * reference line reads as placed rather than measured, doing the "this isn't
+         * data" work that colour alone can't when the register hue is near a series
+         * hue. Set it per {@link roles | role} to dash one kind of mark only.
+         */
+        readonly dash?: readonly number[];
         /**
          * **Optional per-role overrides** — a small map from a role name to its
-         * `color` (and optionally `fillOpacity`), so distinct marks can be styled
-         * at once without splitting the whole register: a `<Baseline role="atm">`
-         * green, a `<Marker role="ref">` in another hue, each still drawn through
+         * `color` (and optionally `fillOpacity` / `dash`), so distinct marks can be
+         * styled at once without splitting the whole register: a `<Baseline
+         * role="atm">` green, a `<Marker role="ref">` in another hue, a `<Zone
+         * role="good">` per band of a value-axis scale — each still drawn through
          * the shared {@link depth} ramp. A mark's `role` resolves
-         * `roles[role] ?? { color, fillOpacity }` (an unknown/unset role is the
-         * base register). Colour stays a **theme** concern — there is no per-mark
-         * colour prop (the one-styling-channel discipline).
+         * `roles[role] ?? { color, fillOpacity, dash }` (an unknown/unset role is
+         * the base register). Colour stays a **theme** concern — there is no
+         * per-mark colour prop (the one-styling-channel discipline), which is why a
+         * *scale* of bands (AQI categories, HR zones) is a role map and not six
+         * colours at the call site.
          */
         readonly roles?: {
             readonly [role: string]: {
                 readonly color: string;
                 readonly fillOpacity?: number;
+                readonly dash?: readonly number[];
             };
         };
     };
@@ -315,6 +331,18 @@ export interface AreaStyle {
     readonly width: number;
     readonly fill: string;
     readonly fillOpacity: number;
+    /**
+     * Fill flat instead of grading to transparent at the baseline. Default
+     * (omitted / `false`) keeps the gradient — the elevation look a single area
+     * wants.
+     *
+     * Set it for **stacked** areas. A stack is drawn as overlapping cumulative
+     * bands, so a fade to transparent at the baseline lets every band below show
+     * through the one above it and the composition reads as mush. A flat fill is
+     * what makes the slabs opaque to each other. (`fillOpacity` still applies, so
+     * a stack can be uniformly translucent — just not *graded*.)
+     */
+    readonly flatFill?: boolean;
 }
 /**
  * A resolved bar style: the flat `fill` (scaled by `opacity`, 0–1) plus the
@@ -360,6 +388,45 @@ export interface BarStyle {
      * already did for `highlight`.
      */
     readonly hover?: string;
+    /**
+     * The **threshold-band ladder** — ordered fills for a bar coloured *along its
+     * length* against `<BarChart thresholds>`: `bands[0]` up to the first
+     * threshold, `bands[1]` between the first and second, and so on. A ladder of
+     * `n` thresholds reads `n + 1` entries.
+     *
+     * This lives on `BarStyle` rather than as a `theme.bar.bands` sibling because
+     * `theme.bar` is a semantic **map** (`{ default, [semantic]: BarStyle }`) — a
+     * top-level key would collide with a role of that name. Per-role is also the
+     * more useful shape: `bar.default.bands` and `bar.capacity.bands` can differ,
+     * and the ladder resolves through the same `bar[semantic] ?? bar.default`
+     * lookup as every other bar colour.
+     *
+     * **Overridden by `<BarChart bandColors>`** at the call site. If neither
+     * resolves enough entries for the ladder, the bar falls back to its flat
+     * {@link fill} and (in dev) warns — a silently-unbanded bar is exactly the
+     * failure mode [PND-BANDBAR2] exists to remove.
+     *
+     * Read by the single-series `drawBars` path and by the `G === 1` stacked path
+     * (which is where `categories` and every horizontal bar live). A genuine
+     * **multi-group stack** ignores it and warns: banding a segment that is
+     * already one slice of a total has no defined meaning.
+     */
+    readonly bands?: readonly string[];
+    /**
+     * Stroke for a **selected** bar's outline, where the default is the bar's own
+     * resolved fill. The one selection cue that still works when the fill cannot
+     * change — a `binColors` bar keeps its own colour by design, so without this
+     * the alpha pop was the whole signal and nothing about it was themeable
+     * ([PND-CATEMPH]).
+     */
+    readonly selectedOutline?: string;
+    /**
+     * The alpha a hovered / selected bar pops to. **Default `1`** (the shipped
+     * behaviour). Previously the pop was hard-coded, so a theme could set the
+     * resting {@link opacity} floor but not the *difference* between resting and
+     * live — which is the part that reads as emphasis.
+     */
+    readonly emphasisOpacity?: number;
 }
 /**
  * The neutral default theme. `default` / `primary` match the M1 `LineChart`

package/dist/theme.js

@@ -109,6 +109,11 @@ export const defaultTheme = {
             gap: 1,
             minWidth: 1,
             outlineWidth: 1.5,
+            // The default threshold ladder: the bar's own blue as the in-range band,
+            // then amber, then red. Three entries serves the common two-threshold
+            // ok/warning/alarm ladder out of the box; a longer `thresholds` needs a
+            // longer ladder from the theme or `bandColors`.
+            bands: ['#2563eb', '#e8a13c', '#d64545'],
         },
         secondary: {
             fill: '#e8836b',

package/dist/viewport.d.ts

@@ -26,7 +26,9 @@ export type TimeRange = readonly [number, number];
 export declare function clampToBounds(range: TimeRange, bounds: TimeRange): [number, number];
 /**
  * Shift a range by `dt` ms (drag-pan). The caller signs `dt` from the gesture —
- * dragging the plot right reveals earlier data, i.e. a negative `dt`.
+ * dragging the plot right reveals earlier data, i.e. a negative `dt`. The result
+ * is snapped to whole milliseconds ({@link roundRange}) — `dt` comes from a pixel
+ * delta through `xScale.invert()`, so it is fractional by construction.
  */
 export declare function panRange(range: TimeRange, dt: number): [number, number];
 /**
@@ -34,6 +36,12 @@ export declare function panRange(range: TimeRange, dt: number): [number, number]
  * the pivot held fixed (the time under the cursor stays put). Clamped so the
  * duration never drops below `minDuration` (the zoom-in floor); at the floor the
  * pivot keeps its fractional position in the window.
+ *
+ * The result is snapped to whole milliseconds ({@link roundRange}). `minDuration`
+ * is applied **before** the snap, so the floor is honoured in the units the
+ * caller expressed it in; a `minDuration` below 1 ms cannot be represented and
+ * lands on the 1 ms floor the snap guarantees, which is the finest view this
+ * model has.
  */
 export declare function zoomRange(range: TimeRange, pivot: number, factor: number, minDuration?: number): [number, number];
 /**