@pond-ts/charts 0.57.0 → 0.59.0

package/dist/theme.d.ts

@@ -89,6 +89,24 @@ export interface ChartTheme {
         readonly default: CandleStyle;
         readonly [semantic: string]: CandleStyle;
     };
+    /**
+     * Map from a heat map's semantic identifier to its **interaction states**
+     * ({@link HeatMap}). Optional throughout; with no `heat` slot a live cell
+     * takes the pre-states treatment (one outline per cell, in
+     * `bar.highlight`).
+     *
+     * **Only the states, and deliberately so.** A heat map's *geometry* is
+     * bar-family — the slot gap, the minimum bin width, the outline weight —
+     * and it reads all of it from `bar[semantic] ?? bar.default`, which is
+     * right: a cell is a bar's slot with colour instead of height. What it
+     * cannot share is state styling, because a bar's fill is free and a cell's
+     * fill **is the datum** (see {@link HeatStates}). So the split is between
+     * the two things, not an accident of where the tokens landed.
+     */
+    readonly heat?: {
+        readonly default: HeatStates;
+        readonly [semantic: string]: HeatStates;
+    };
     /**
      * Map from a bar's semantic identifier to its style — the fill, the
      * selected-bar highlight, and the slot gap / minimum width ({@link BarChart}).
@@ -143,6 +161,29 @@ export interface ChartTheme {
     };
     /** Crosshair / tracker stroke colour. Falls back to {@link axis.label} if unset. */
     readonly cursor?: string;
+    /**
+     * The **drag band** — the live region the shared brush paints while a drag
+     * is in flight (`<RangeCursor>`'s band and `<MultiSelector>`'s sweep are the
+     * same pixels; see `renderBrushBand`). `fill` washes the covered span and
+     * `edge` hairlines its two boundaries at 1px, so the band has a readable
+     * start/end while the gesture is still live.
+     *
+     * **Optional, and back-compatible when omitted:** with no `brush` the band
+     * falls back to the cursor ink at 0.12 with no edges — byte-for-byte what
+     * every theme drew before this token existed. `defaultTheme` opts in with
+     * the *selection* blue at 7%: the band is about to become a selection, so it
+     * should be the same hue as one (whereas the resting bars are teal).
+     */
+    readonly brush?: {
+        /**
+         * The band's wash. Drawn at **full element opacity**, so carry the alpha
+         * in the colour (`rgba(…, 0.07)`) — a solid hex here paints over the marks
+         * the band is supposed to be previewing.
+         */
+        readonly fill: string;
+        /** Stroke for the band's 1px start/end edges. Omit for a fill-only band. */
+        readonly edge?: string;
+    };
     /**
      * Readout chip background (the `flag` / `inline` tracker modes). The value text
      * is the series colour; this is the panel behind it. Falls back to the plot
@@ -177,6 +218,18 @@ export interface ChartTheme {
      */
     readonly annotation?: {
         readonly color: string;
+        /**
+         * **EXPERIMENTAL ([PND-ANNSNAP]).** Ink for the vertical rules at a swept
+         * window's edges — a preview of what promoting the sweep to an annotation
+         * would look like. Lighter than {@link color} because these mark a
+         * *candidate* range rather than a committed mark. **Omitted ⇒ a light
+         * orange fallback.**
+         *
+         * Not settled: the rules are drawn canvas-side, under the trace ink,
+         * whereas a real annotation renders in the SVG overlay above it. If the
+         * look is kept, that mismatch has to be resolved rather than papered over.
+         */
+        readonly spanEdge?: string;
         readonly fillOpacity: number;
         readonly depth: readonly [number, number, number];
         /**
@@ -223,6 +276,62 @@ export interface ChartTheme {
         readonly border: string;
         readonly text: string;
     };
+    /**
+     * The **row-chart register** — `<BarList>` / `<BoxList>`, whose row states
+     * live on chrome the canvas has no equivalent of.
+     *
+     * A row chart cannot signal state the way a column chart does. Two reasons,
+     * and the second is the load-bearing one:
+     *
+     * - **The row is the target, not the bar.** A vertical bar can be its own
+     *   hit area because every mark spans the full column width; a row's mark
+     *   is as short as its value, so a 4% row would be a 30px sliver. The
+     *   label gutter, the track and the trailing value are one target, and the
+     *   thing that lights has to be the whole **band**.
+     * - **The band carries selection alone.** In a multi-metric row the fill
+     *   *is* the identity of the metric, so it cannot also carry state — the
+     *   same channel rule the canvas marks follow. Band + rail must read as
+     *   selected with no help from the fill, and designing the single-metric
+     *   case that way too means one treatment covers every row chart.
+     *
+     * So the two values here are the ones with no canvas counterpart: the row
+     * **band** tints. Everything else resolves from tokens that already exist
+     * and are per-metric where they should be — a selected glyph fill takes
+     * `bar[as].highlight` and a dimmed one `bar[as].dimmed` — so a consumer who
+     * themes their bars gets a coherent list without theming it twice.
+     *
+     * **To be unambiguous, because this reads as a list of fields on this
+     * block:** `highlight` / `dimmed` are **`BarStyle`** tokens, resolved through
+     * `theme.bar[as]`. They are not fields of `theme.list` and there is no
+     * `list.dimmed` — this register carries exactly the five values below.
+     *
+     * **The rail is deliberately NOT per-metric.** There is one rail per row
+     * and a row may carry several metrics, so it cannot resolve through
+     * `bar[as]` the way a fill does; it lives here with the bands.
+     *
+     * **Optional, and back-compatible when omitted:** with no `list` the rows
+     * keep exactly the pre-token look — a hover band from `legend.border`, a
+     * selection rail from the annotation register, and no dimmed state at all.
+     */
+    readonly list?: {
+        /** Row stripe behind the hovered row — the whole band, gutter to value. */
+        readonly hoverBand: string;
+        /** The hovered row's 3px inset left edge. Never the selection hue. */
+        readonly hoverRail: string;
+        /** Row stripe behind a selected row. */
+        readonly selectedBand: string;
+        /** The selected row's 3px inset left edge. */
+        readonly selectedRail: string;
+        /**
+         * Reference ink — per-row target markers, thresholds, reference ticks.
+         *
+         * **Reserved away from the selection hue on purpose.** On a bullet row
+         * the marker sits *inside* the mark that selection recolors, so a tick
+         * in the selection blue is the one collision the rest of the language
+         * cannot absorb: you could not tell a target from a selected bar.
+         */
+        readonly markerInk: string;
+    };
 }
 /** A resolved line style: stroke colour + width (px). */
 export interface LineStyle {
@@ -237,6 +346,41 @@ export interface LineStyle {
      * observed one at a glance.
      */
     readonly dash?: readonly number[];
+    /**
+     * Stroke width when this trace is the **selected series**, and for the
+     * emphasised portion of a swept window. **Omitted ⇒ `width * 2`.**
+     *
+     * **State on a trace is WEIGHT, not hue** — the channel rule, and the same
+     * answer `<Candlestick>` got. A line's **colour is its identity**: it is how
+     * a reader tells one series from another in a multi-series plot, so a
+     * selected line that turned blue would trade the distinction they need for
+     * one they already have from the chrome. Thickening says "this one" without
+     * spending the channel that says "which one".
+     */
+    readonly selectedWidth?: number;
+    /** Stroke width on **hover** — the transient echo of `selectedWidth`.
+     *  **Omitted ⇒ `selectedWidth`**, so hover previews the committed weight. */
+    readonly hoverWidth?: number;
+    /**
+     * Alpha for a trace that is **outside** the active selection — another
+     * series is selected, or this trace is outside a swept window.
+     * **Omitted ⇒ `0.32`**, the value the rest of the palette recedes to.
+     *
+     * Alpha rather than a colour, deliberately: a muted line must still read as
+     * *which* series it is, so its hue has to survive being pushed back.
+     */
+    readonly dimmedOpacity?: number;
+    /**
+     * Ink for the **swept window's** emphasised portion. **Omitted ⇒ the trace
+     * keeps its own colour and only thickens.**
+     *
+     * This is the one place a trace's state may take a hue, and the reason is
+     * that a window is a **region of one series** — identity is not in question
+     * there, because you can see which line you swept. So the region can read as
+     * the same act as the brush band that made it (the selection blue), where a
+     * whole-series selection cannot.
+     */
+    readonly spanColor?: string;
 }
 /** A resolved band style: fill colour + opacity (0–1) for the variance envelope. */
 export interface BandStyle {
@@ -265,6 +409,123 @@ export interface ScatterStyle {
     readonly selectedWidth: number;
     /** Colour of the optional per-point text label. */
     readonly label: string;
+    /**
+     * The **interaction states** — fill and size per state, and the whole
+     * styling channel for a live point when set. Unset ⇒ the pre-states
+     * behaviour exactly: every point keeps its resting fill and radius, and a
+     * live one is merely re-ringed in `selectedOutline`/`selectedWidth`.
+     *
+     * A scatter can afford what a candle cannot. A candle's hue *is* its
+     * meaning (rising vs falling), so it carries state in weight and alpha
+     * alone; a heat cell's colour is its value, so it carries state in chrome.
+     * A point's colour encodes nothing by default, so it is free to recolour —
+     * and it also has a channel none of the column marks have: **size**.
+     *
+     * That is why hover and selection split the channels rather than sharing
+     * them. See {@link ScatterStates}.
+     */
+    readonly states?: ScatterStates;
+}
+/**
+ * A scatter point's per-state fill and size ({@link ScatterStyle.states}).
+ *
+ * The radii are given in px against {@link ScatterStyle.radius}, and applied
+ * as the **ratio** between them — so a data-driven `radius` encoding still
+ * grows and shrinks by the same proportion instead of being flattened to one
+ * size the moment a point goes live.
+ */
+export interface ScatterStates {
+    /**
+     * Fill for a **hovered** point — or one under a live drag rect, which is
+     * the same state (the sweep lights its covered marks through the plural
+     * `hovered`). A brightened form of the resting colour, not a new hue: the
+     * preview says "these are the ones", and saying it in the committed colour
+     * would make the preview and the commit read alike.
+     */
+    readonly hover: string;
+    /** Hovered radius (px). Hover is the state that spends **size** — it is the
+     *  channel a lone pointer-over can afford, and a hover does not have to
+     *  survive being read against a whole field of committed marks. */
+    readonly hoverRadius: number;
+    /**
+     * Fill for a **selected** point. Its radius is deliberately left at
+     * {@link ScatterStyle.radius}: selection spends **hue** instead, so
+     * committing a sweep does not reflow the cloud under the pointer.
+     */
+    readonly selected: string;
+    /** The ring around a live (hovered or selected) point — what keeps
+     *  overlapping points countable once a whole swept region shares one fill. */
+    readonly halo: string;
+    /** Halo width (px); `0` draws none. */
+    readonly haloWidth: number;
+    /**
+     * Radius (px) of a point **outside a non-empty selection**. It shrinks as
+     * well as fading because alpha alone at these levels thins a cloud to
+     * nearly nothing, and the shape of the unselected field is the thing a
+     * scatter's background is *for*.
+     */
+    readonly dimmedRadius: number;
+    /** Alpha of a point outside a non-empty selection. */
+    readonly dimmedOpacity: number;
+}
+/**
+ * A heat map's **interaction states** ({@link ChartTheme.heat}).
+ *
+ * A cell has no spare channel at all. A bar's fill is free, so a bar swaps it;
+ * a point's colour encodes nothing by default, so a point recolours *and*
+ * resizes. A cell's colour **is** its value, and its rect is the grid — so
+ * every state here is **chrome added around the cell** or a transform applied
+ * uniformly to all of them, and none of them repaints a cell in a colour the
+ * ramp could also have produced.
+ */
+export interface HeatStates {
+    /**
+     * The flat overlay painted over a cell **outside a non-empty selection** —
+     * carry the alpha in the colour (`rgba(255,255,255,0.62)`), because it is
+     * composited over the cell, not applied as one.
+     *
+     * **A flat overlay, not `globalAlpha`, and the difference is the whole
+     * point.** Alpha and value are the same channel on a ramp, so fading a cell
+     * slides it along the scale — a dimmed dark cell becomes a resting mid one.
+     * An overlay is *uniform and monotonic*: every cell moves by the same
+     * transform, so the ramp's **order survives inside the veiled set** and only
+     * the cross-set comparison is ambiguous — which is exactly what the
+     * {@link perimeter} is there to disambiguate.
+     *
+     * It is also why this is a colour and not a number: opacity composites with
+     * whatever is *behind* the cell (a gridline, a non-white background, another
+     * layer), so the same value would veil to different colours in different
+     * charts. An overlay is a property of the cell.
+     */
+    readonly veil: string;
+    /**
+     * The hovered cell's **double ring**, outer colour first — two concentric
+     * rings of {@link ringWidth}, both inside the cell.
+     *
+     * A single ring cannot work against a ramp: a light ring vanishes at the
+     * pale end and a dark one at the dark end, and a cell can be anywhere on the
+     * scale. The pair guarantees one of the two reads wherever the cell happens
+     * to sit. (The same problem `bar.binFills` has, and a better answer than
+     * picking one colour and hoping.)
+     */
+    readonly hoverRing: readonly [string, string];
+    /** Width of each of the two hover rings, in px. */
+    readonly ringWidth: number;
+    /**
+     * The selected region's **perimeter** — one outline around the union of
+     * selected cells, not one per cell.
+     *
+     * Per-cell outlines are what this replaces, and the reason is legible in any
+     * screenshot of them: a bordered grid is mostly border, and every interior
+     * line says nothing, because it is interior to the selection. Drawn by
+     * suppressing each cell edge whose neighbour is also selected, so a
+     * selection in several disconnected pieces gets one outline **per piece**,
+     * and a hole in the middle of one gets its own — no connectivity pass, and
+     * no assumption that a selection is a single rectangle.
+     */
+    readonly perimeter: string;
+    /** Perimeter stroke width, in px. */
+    readonly perimeterWidth: number;
 }
 /**
  * A resolved box-and-whisker style ({@link BoxPlot}). The q1→q3 box is a filled
@@ -282,6 +543,68 @@ export interface BoxStyle {
     readonly medianWidth: number;
     readonly whisker: string;
     readonly whiskerWidth: number;
+    /**
+     * The **tint ladder** — one four-step ladder per interaction state, and the
+     * whole styling channel for a box when set. Unset ⇒ the flat
+     * `fill`/`stroke`/`median`/`whisker` tokens above, unchanged.
+     *
+     * Every mark of a box reads its step from the *same* ladder
+     * ({@link BoxLadder} documents which step is which), so a state change is a
+     * **single palette swap** rather than four independent colour decisions.
+     * That is what keeps the quantile read intact across states: the ladder
+     * carries its meaning in *lightness*, so moving the whole ladder — brighter
+     * teal on hover, blue when committed — leaves every relationship between the
+     * marks untouched.
+     *
+     * Two consequences worth stating, because both are the opposite of what the
+     * multi-hue `bar` palette needs:
+     *
+     * - **Shift the ladder, not one step.** Recolouring only the median, or only
+     *   the body, breaks the read. All four steps move together and keep their
+     *   relative lightness spacing.
+     * - **Dim without desaturating.** A single-hue ladder has nothing to muddy
+     *   into, so {@link dimmedOpacity} alone is the receded state — no
+     *   desaturated companion ladder of the kind `bar.groupsDimmed` needs.
+     */
+    readonly states?: BoxStates;
+    /**
+     * Stroke width for a **selected** box's hairlines — the body outline and the
+     * whiskers both. Unset ⇒ they keep {@link strokeWidth} / {@link whiskerWidth}.
+     *
+     * A hairline cannot carry a state in hue alone: at 1px a colour change is
+     * nearly invisible, and the whisker is the mark that reaches furthest. A
+     * weight change is legible at any width, so selection bumps it (1 → 1.5 on
+     * `defaultTheme`) alongside the ladder swap.
+     */
+    readonly selectedStrokeWidth?: number;
+}
+/**
+ * A box's four tint steps, lightest → darkest. Which mark reads which step:
+ *
+ * | step | box plot        | quantile bands |
+ * | ---- | --------------- | -------------- |
+ * | `0`  | body fill / the solid shape's outer bar | outer band |
+ * | `1`  | the solid shape's inner q1→q3 bar        | inner band |
+ * | `2`  | body stroke + whiskers                   | —          |
+ * | `3`  | the median rule                          | median rule |
+ *
+ * Steps are *positions on one hue's lightness ramp*, not four palette entries —
+ * a ladder whose steps don't descend in lightness stops encoding anything.
+ */
+export type BoxLadder = readonly [string, string, string, string];
+/** The per-state ladders (see {@link BoxStyle.states}). */
+export interface BoxStates {
+    /** Nothing selected anywhere. */
+    readonly rest: BoxLadder;
+    /** Pointer over this box — a preview of what a click would commit, so it
+     *  sits between {@link rest} and {@link selected} in strength. */
+    readonly hover: BoxLadder;
+    /** Committed. Pairs with {@link BoxStyle.selectedStrokeWidth}. */
+    readonly selected: BoxLadder;
+    /** How far a box **outside** a non-empty selection recedes — the
+     *  {@link rest} ladder at this alpha. No separate ladder, and deliberately
+     *  no desaturation (see {@link BoxStyle.states}). */
+    readonly dimmedOpacity: number;
 }
 /**
  * A resolved candlestick style ({@link Candlestick}). A candle is unreadable in
@@ -309,6 +632,41 @@ export interface CandleStyle {
         readonly body: string;
         readonly wick: string;
     };
+    /**
+     * The **interaction state** cues — and note what is *missing* from them.
+     *
+     * A `bar` swaps its fill and a `box` rotates its whole tint ladder, because
+     * on those marks hue is free: the meaning lives in position and in lightness
+     * ordering. **A candle's hue is its meaning** — rising vs falling is the
+     * first thing anyone reads off it — so a candle introduces *no state colour
+     * at all*, not even for its outline. Every cue here is a change of weight or
+     * of alpha:
+     *
+     * - **Live** (hovered *or* selected) — the candle **grows**: its body is
+     *   stroked in its own colour and its lines thicken to
+     *   {@link liveWickWidth}, so the mark gets a little heavier and nothing
+     *   else about it changes. Nothing is recoloured, and nothing is added that
+     *   the chart doesn't otherwise draw.
+     * - **Selected** — the same, plus the rest of the field recedes to
+     *   {@link dimmedOpacity}. The dimming is what separates a committed
+     *   selection from a passing hover, since the lit mark looks identical
+     *   either way.
+     *
+     * That last point is deliberate but worth knowing: hover and selection are
+     * distinguished by what happens to the *other* candles, not by this one.
+     *
+     * Both optional; unset ⇒ a display-only candle exactly as before.
+     */
+    readonly dimmedOpacity?: number;
+    /**
+     * Line weight for a **live** (hovered or selected) candle — its wick, and
+     * the stroke around its body that makes the mark grow.
+     *
+     * Unlike {@link BoxStyle.selectedStrokeWidth}, which only selection triggers,
+     * this fires on hover too: a box announces hover by moving its tint ladder,
+     * and a candle has no ladder to move.
+     */
+    readonly liveWickWidth?: number;
     /** Doji (open === close) — body + wick colours; falls back to `rising` if unset. */
     readonly neutral?: {
         readonly body: string;
@@ -343,6 +701,25 @@ export interface AreaStyle {
      * a stack can be uniformly translucent — just not *graded*.)
      */
     readonly flatFill?: boolean;
+    /**
+     * Interaction state, the area's counterpart of `LineStyle`'s
+     * ([PND-TRACESEL]) — and the channels differ because what carries the mark
+     * differs. An area's mark is its **fill**, so state is the fill's *strength*
+     * plus the edge's weight; a line's mark is a stroke, so state is weight alone.
+     *
+     * `selectedWidth` thickens the edge, `selectedFillOpacity` strengthens the
+     * fill, `dimmedOpacity` recedes the whole shape, and `spanColor` is the one
+     * hue a swept **window** may take (identity is not in question inside a
+     * single series — see `LineStyle.spanColor`).
+     */
+    readonly selectedWidth?: number;
+    /** Fill opacity when selected. **Omitted ⇒ `min(fillOpacity * 2, 1)`.** */
+    readonly selectedFillOpacity?: number;
+    /** Alpha for an area outside the active selection. **Omitted ⇒ `0.32`.** */
+    readonly dimmedOpacity?: number;
+    /** Ink for a swept window's emphasised portion (edge + fill).
+     *  **Omitted ⇒ the area keeps its own colours and only strengthens.** */
+    readonly spanColor?: string;
 }
 /**
  * A resolved bar style: the flat `fill` (scaled by `opacity`, 0–1) plus the
@@ -357,6 +734,28 @@ export interface BarStyle {
     readonly highlight: string;
     readonly gap: number;
     readonly minWidth: number;
+    /**
+     * Cap on a bar's **ink** width in px, applied after the `gap` inset and
+     * centred in the slot ([PND-BARWIDTH]). **Omitted ⇒ uncapped** — a bar is
+     * `slot - gap` wide, as it always was.
+     *
+     * It is the missing half of the width vocabulary, and the reason it cannot be
+     * spelled with `gap` alone: `gap` is a *relative* inset, so bar width tracks
+     * the slot and fattens as the plot widens. A **fixed** ink width is what makes
+     * a measure comparable *between* panes — bars that widen with their pane read
+     * as different weights of the same thing. Wanting both (slots spreading to
+     * fill, ink pinned) needs two independent knobs; with one, a consumer has to
+     * predict the slot width and back-solve the gap, re-deriving pond's own layout
+     * arithmetic in their code.
+     *
+     * Pairs with `<ChartContainer maxBandWidth>`, which caps the **slot**: that
+     * one decides how far the bars spread, this one how wide the ink is inside
+     * whatever slot results. `minWidth` still wins if the two would invert.
+     *
+     * `<BarChart maxBarWidth>` overrides this per layer, the same relationship
+     * `gap` has.
+     */
+    readonly maxWidth?: number;
     readonly outlineWidth: number;
     /**
      * Optional distinct **hover** fill, so a bar can read a three-step emphasis —
@@ -384,6 +783,11 @@ export interface BarStyle {
      *   both states so a red/green volume bar keeps its meaning while live —
      *   the one *design* exclusion rather than a path consequence.
      *
+     * **Scope note: that `binColors` exclusion is about the LIVE states only.**
+     * It does not carry over to {@link dimmed}, which *replaces* a per-bar fill
+     * on an unselected bar — see that token, which spells out the asymmetry and
+     * why emphasis preserves a per-bar colour while recession suppresses it.
+     *
      * The **decimated** dense-bar pass also draws the flat fill only, as it
      * already did for `highlight`.
      */
@@ -412,6 +816,50 @@ export interface BarStyle {
      * already one slice of a total has no defined meaning.
      */
     readonly bands?: readonly string[];
+    /**
+     * The **stack group ramp** — ordered fills for a *multi-group* stack's
+     * segments, `groups[0]` for the first (bottom / left) group. Cycles when the
+     * stack has more groups than the ramp has entries.
+     *
+     * Sibling of {@link bands}, and here for the same reason (a `theme.bar`
+     * top-level key would collide with a role of that name) — but a different
+     * axis: `bands` colours one bar *along its length* against a threshold
+     * ladder, this colours *across the groups* of one bin.
+     *
+     * **Multi-group only.** A ramp exists to tell groups apart, so with one group
+     * there is nothing to tell apart and the bar keeps its {@link fill} — which
+     * is what keeps every categorical and single-series chart (both of which run
+     * the stacked draw path with `G === 1`) exactly as it was.
+     *
+     * Resolution order per group: `<BarChart colors>` → a theme role named after
+     * the group (`bar.web`) → this ramp → {@link fill}. So a named role still
+     * wins, and the ramp is the fallback that makes an *unthemed* stack legible
+     * instead of painting every segment one colour.
+     */
+    readonly groups?: readonly string[];
+    /**
+     * The receded counterpart of {@link groups}, same order and cycling — what a
+     * segment fades to when a selection exists elsewhere.
+     *
+     * Per-group rather than the flat {@link dimmed}, because a stack dimmed to a
+     * single colour stops being a stack: the segment boundaries vanish and the
+     * unselected columns read as solid blocks. Each entry is its ramp colour
+     * desaturated and lightened, so the bin keeps its structure while clearly
+     * receding.
+     */
+    readonly groupsDimmed?: readonly string[];
+    /**
+     * The **hovered** counterpart of {@link groups}, same order and cycling.
+     *
+     * Per-group for the reason the flat {@link hover} cannot be: one hover
+     * colour repaints whichever segment the pointer is over in a hue belonging
+     * to a different group, so pointing at a stack momentarily *erases the
+     * ramp* — and under a `<MultiSelector>`, where hover is block-scoped, it
+     * erases the whole bin at once. Each entry is its ramp colour brightened
+     * (same hue, lighter), the same relationship {@link fill} has to
+     * {@link hover}.
+     */
+    readonly groupsHover?: 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
@@ -427,13 +875,70 @@ export interface BarStyle {
      * live — which is the part that reads as emphasis.
      */
     readonly emphasisOpacity?: number;
+    /**
+     * The fill for a bar that is **not** in a non-empty selection set — the
+     * "everything else recedes" state a chart used as a filter control needs
+     * ([PND-MULTISEL]).
+     *
+     * **Opt-in by construction:** a theme that sets no `dimmed` dims nothing, so
+     * existing charts are untouched (RFC `selection.md` A2.3 — the library never
+     * auto-dims; the theme carries the selection-state styling and the library
+     * references it by state). Nothing dims while the set is empty either: with
+     * no selection there is nothing to recede *from*.
+     *
+     * It exists because "not in the selection" was otherwise re-invented per
+     * component, and drifted immediately — one consumer had three charts using
+     * `color-mix` at 22%, 28% and 30% for the same concept, in the same week, for
+     * no reason. One theme value fixes that permanently.
+     *
+     * **It OVERRIDES a per-bar fill, unlike the live states.** This is the one
+     * place `dimmed` and {@link hover} deliberately disagree, and the asymmetry
+     * is easy to read the wrong way round:
+     *
+     * - **{@link binColors} / {@link binFills}:** an unselected bar paints
+     *   `dimmed`, discarding its own colour. (Hover and selection do the
+     *   opposite — they keep the per-bar colour and pop the alpha, so a
+     *   red/green volume bar stays red/green while live.)
+     * - **{@link bands} / thresholds:** an unselected banded bar draws **flat**
+     *   in `dimmed`, discarding the ladder entirely rather than dimming each
+     *   band.
+     * - **A multi-group stack** resolves per group through
+     *   {@link StackStyle.dimmedFills} first, falling back to this flat value —
+     *   a stack dimmed to one colour stops reading as a stack.
+     *
+     * The rule behind all three: a per-bar or per-band colour encodes *what the
+     * value is*, and a receded bar's whole job is to stop competing over that.
+     * Emphasis preserves meaning; recession suppresses it. So a chart that keeps
+     * `binColors` or `thresholds` for reasons unrelated to selection still gets
+     * a visible de-emphasis for free, and does **not** need to dim inside its own
+     * colour arrays. (Asked by a consumer who reasonably generalized `hover`'s
+     * `binColors` exclusion to this token; the exclusion is live-states-only.)
+     */
+    readonly dimmed?: string;
 }
 /**
- * The neutral default theme. `default` / `primary` match the M1 `LineChart`
- * colour (`#2563eb`) so adopting the theme channel doesn't shift existing
- * renders. `primary` / `secondary` / `context` are a built-in generic role
- * vocabulary; an unrecognised (e.g. domain-specific) identifier falls back to
- * `default`.
+ * The neutral default theme. The shared data hue is a cerulean (`#0284c7`)
+ * across `line` / `band` / `area` / `scatter` / `box` / candle-rising, chosen
+ * to clear the bar palette's *selection* blue (`#3F5BE0`) — the original M1
+ * royal blue (`#2563eb`) sat ~ΔE 5 from it, so a line drawn over bars read as
+ * nearly the selection colour. `primary` / `secondary` / `context` are a
+ * built-in generic role vocabulary; an unrecognised (e.g. domain-specific)
+ * identifier falls back to `default`.
+ *
+ * **Spreading this inherits every slot you don't override** — including colours
+ * for layers you haven't added yet, so a `{ ...defaultTheme, bar: … }` theme
+ * paints this blue the first time someone drops in a `<LineChart>`. That is the
+ * intended workflow, not a trap: take the defaults, change the one or two things
+ * that are yours. A design system that must own *every* colour should assert on
+ * that in its own test rather than catch it in review — walk the resolved theme
+ * for values outside your palette ([PND-THEMEBASE]).
+ *
+ * **The `bar` slot is the exception to "one blue".** Bars carry an interaction
+ * state (rest / hover / selected / dimmed), and encoding four states as four
+ * shades of one hue is unreadable — so `bar.default` runs its own
+ * **interaction-state palette**: teal at rest, blue when selected, brighter
+ * teal on hover. See the comment on that slot, and `brush` for the matching
+ * drag band.
  */
 export declare const defaultTheme: ChartTheme;
 /**