@pond-ts/charts 0.48.1 → 0.49.0

package/dist/Layers.js

@@ -7,12 +7,12 @@ import { resolveSelection } from './select.js';
 import { panRange, zoomRange, panRangeTrading, zoomRangeTrading, } from './viewport.js';
 import { flagChipStyle, flagChipX, axisPillX, axisPillStyle } from './chip.js';
 import { ContainerContext, LayersContext, RowContext, } from './context.js';
-/** **Y**-gridline tick count. **Must match the y-axis label counts** (`YAxis`
- *  `TICK_COUNT`, `ChartRow` `AXIS_TICK_COUNT`) — horizontal gridlines and the y
- *  labels are both derived from `ticks(count)`, so they only line up while the
- *  counts agree; kept at 5 across all three. The **x** side instead reads the
- *  container's shared `xTickCount` (as `<XAxis>` and `formatTime` do), which is
- *  width-derived on a trading-time axis. */
+/** Fallback **y**-gridline tick count, used only before the row publishes its
+ *  resolved `tickCounts` (pre-registration). Normally the gridlines read the
+ *  default axis's resolved count from `row.tickCounts` — the same value the
+ *  `<YAxis>` labels use — so they line up by construction (was three hardcoded
+ *  `5`s agreeing by convention). The **x** side reads the container's shared
+ *  `xTickCount`, width-derived on a trading-time axis. */
 const GRID_TICKS = 5;
 /** Minimum px between `'labeled'` session dividers — thins dense collapse
  *  points (e.g. a daily chart where every candle is a new session) so the axis
@@ -79,7 +79,7 @@ export function Layers({ children }) {
     }), [row.registerLayer, row.unregisterLayer]);
     const background = container.theme.background;
     const { grid: gridColor, gridDash } = container.theme.axis;
-    const { layers, yScales, formats, defaultAxisId, tickValues, axisSides } = row;
+    const { layers, yScales, formats, defaultAxisId, tickValues, tickCounts, axisSides, } = row;
     // x geometry is shared and lives on the container (uniform across rows), and
     // so is the x tick count — vertical gridlines must sit under the `<XAxis>`
     // labels, which pass the same `xTickCount` to the same scale.
@@ -101,8 +101,12 @@ export function Layers({ children }) {
         // The reference grid — behind the data, opt-out via `grid={false}` for
         // a clean backdrop (session dividers below stay independent of it).
         if (container.grid) {
+            // Auto gridlines use the default axis's RESOLVED tick count (the row's
+            // single source, height-derived or an explicit `<YAxis tickCount>`), so
+            // a gridline sits under every `<YAxis>` label and no more.
+            const yCount = tickCounts.get(defaultAxisId) ?? GRID_TICKS;
             const yTicks = gridY
-                ? (explicitY ?? gridY.ticks(GRID_TICKS)).map((t) => gridY(t))
+                ? (explicitY ?? gridY.ticks(yCount)).map((t) => gridY(t))
                 : [];
             // On a calendar axis the verticals are the FULL grain populations —
             // every day in the month, every month in the year, every aligned
@@ -213,6 +217,7 @@ export function Layers({ children }) {
         xTickCount,
         defaultAxisId,
         tickValues,
+        tickCounts,
         background,
         gridColor,
         gridDash,
@@ -347,6 +352,16 @@ export function Layers({ children }) {
     const [createPt, setCreatePt] = useState(null);
     const [drawFrom, setDrawFrom] = useState(null);
     const drawFromRef = useRef(null);
+    // The region-select drag anchor, mirrored for the gesture handlers (the same
+    // ref+state discipline as `drawFromRef`): the container's `regionAnchor`
+    // STATE is only how the rows paint the band; the gesture logic must never
+    // read it back, because a batched pointer stream (automation, jsdom, a very
+    // fast flick under load) delivers down→up before the down's setState commits
+    // — the up would see `regionAnchor === null`, silently drop the select, and
+    // the late-committing anchor would then stick (#508 item 7). Trusted
+    // human-paced input hides this (React flushes trusted discrete events
+    // synchronously); the ref is correct under both.
+    const regionAnchorRef = useRef(null);
     const handlePointerDown = useCallback((e) => {
         clickStartRef.current = { x: e.clientX, y: e.clientY };
         const c = containerRef.current;
@@ -380,7 +395,8 @@ export function Layers({ children }) {
             const needsShift = c.regionSelectModifier === 'shift' && c.panZoom;
             if (!needsShift || e.shiftKey) {
                 const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
-                c.setRegionAnchor(+c.xScale.invert(px));
+                regionAnchorRef.current = +c.xScale.invert(px);
+                c.setRegionAnchor(regionAnchorRef.current); // paint-only mirror
                 c.setHoverX(px);
                 try {
                     e.currentTarget.setPointerCapture(e.pointerId);
@@ -423,8 +439,9 @@ export function Layers({ children }) {
             return;
         }
         // Region drag in progress: just track the pointer x (the band spans from the
-        // anchor bucket to here); no pan, no hover hit-test.
-        if (c.regionAnchor !== null) {
+        // anchor bucket to here); no pan, no hover hit-test. Gesture truth is the
+        // ref — the state mirror may not have committed yet (see regionAnchorRef).
+        if (regionAnchorRef.current !== null) {
             const rect = e.currentTarget.getBoundingClientRect();
             c.setHoverX(Math.max(0, Math.min(c.plotWidth, e.clientX - rect.left)));
             return;
@@ -516,9 +533,14 @@ export function Layers({ children }) {
         const c = containerRef.current;
         // End a region drag: commit the anchor→pointer span as a one-shot range,
         // then clear the anchor (the cursor reverts to the single-bucket highlight).
-        if (c.regionAnchor !== null) {
+        // The anchor is read from the ref, never the state mirror — under a batched
+        // pointer stream the state hasn't committed yet and the select would be
+        // silently dropped (and the anchor stuck). See regionAnchorRef.
+        if (regionAnchorRef.current !== null) {
+            const anchor = regionAnchorRef.current;
+            regionAnchorRef.current = null;
             const px = Math.max(0, Math.min(c.plotWidth, e.clientX - e.currentTarget.getBoundingClientRect().left));
-            const span = regionSpan(c.cursorBuckets ?? [], c.regionAnchor, +c.xScale.invert(px));
+            const span = regionSpan(c.cursorBuckets ?? [], anchor, +c.xScale.invert(px));
             c.setRegionAnchor(null);
             try {
                 e.currentTarget.releasePointerCapture(e.pointerId);
@@ -599,6 +621,7 @@ export function Layers({ children }) {
         }
         // Cancel a region-drag on leave (no commit) — a safety net for the rare case
         // where the pointer capture didn't take, so the anchor can't get stuck.
+        regionAnchorRef.current = null;
         if (c.regionAnchor !== null)
             c.setRegionAnchor(null);
         c.setHoverX(null);
@@ -838,7 +861,7 @@ export function Layers({ children }) {
                             ? `${plotWidth - timeX + 4}px`
                             : undefined,
                         color: cursorColor,
-                    }, children: formatTime(cursorTime) })), parts.chip === 'inline' &&
+                    }, children: (container.formatReadout ?? formatTime)(cursorTime) })), parts.chip === 'inline' &&
                     trackerSamples.map((s, i) => {
                         // Flip the chip left of its dot near the right edge so it stays in-plot.
                         const flip = s.px > plotWidth * LABEL_FLIP_FRACTION;

package/dist/Legend.d.ts

@@ -0,0 +1,62 @@
+import type { LegendItemInput } from './swatch.js';
+import { type ChartTheme } from './theme.js';
+/** Where the in-container legend card anchors, relative to the rows block. */
+export type LegendPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export interface LegendProps {
+    /**
+     * Which corner of the **rows block** the card anchors to (8px inset).
+     * **Omitted ⇒ `'top-right'`.** Ignored in standalone `items` mode outside a
+     * container, where the card renders in normal flow (the consumer places it).
+     */
+    placement?: LegendPlacement;
+    /**
+     * **Escape hatch — explicit rows.** Renders exactly these (in order, no
+     * dedup) instead of the container's registry, and works **outside** a
+     * `<ChartContainer>` (a dashboard-side key). Each row is a `label` +
+     * resolved {@link SwatchSpec} (+ optional `id` for the interactions).
+     */
+    items?: readonly LegendItemInput[];
+    /**
+     * Row click. **Omitted ⇒ the id-gated default:** a row whose layer has an
+     * `id` toggles the container selection (the same `select()` path a mark
+     * click uses); rows without an `id` are inert. Provide to take over (e.g.
+     * a consumer-side show/hide toggle — visibility stays consumer-side by
+     * design, a legend mutating composition would be a second styling channel).
+     */
+    onRowClick?: (row: LegendItemInput) => void;
+    /**
+     * Row hover (`null` on leave). **Omitted ⇒ the id-gated default:** hovering
+     * a row with an `id` echoes into the container's `hovered` channel — the
+     * same one an in-plot hover drives — and clears on leave.
+     */
+    onRowHover?: (row: LegendItemInput | null) => void;
+    /** Theme for the **standalone** (`items`, outside-a-container) mode, where
+     *  there is no frame to read one from. **Omitted ⇒ the container's theme,
+     *  else {@link defaultTheme}.** */
+    theme?: ChartTheme;
+}
+/**
+ * The **series key** — one row per registered draw layer: a swatch of the
+ * layer's *resolved* style (so the key can never drift from the plot) and its
+ * readout identity (`as ?? column`, or the layer's `legend="name"` override).
+ * A child of {@link ChartContainer} (anywhere — it reads the registry, not its
+ * position): renders a small card anchored to a corner of the rows block.
+ *
+ * - **Rows** follow chart-row order, then declaration order (the z-order
+ *   convention); two layers sharing an identity (`id ?? label`) collapse to
+ *   one row, exactly as the tracker readout merges keys.
+ * - **A layer opts out** with `legend={false}`, or renames its row with
+ *   `legend="Display name"`.
+ * - **Interactivity is id-gated** (the selection contract): rows whose layer
+ *   has an `id` echo hover into the container and toggle selection on click;
+ *   `onRowHover` / `onRowClick` take over when provided. The selected row
+ *   reads emphasized; the hovered row tints.
+ * - **Scope follows placement:** at the container level it lists **all** rows;
+ *   placed inside a `<Layers>` it **scopes to that `<ChartRow>`** and anchors
+ *   to that row's plot (like an annotation) — a per-row legend needs no prop.
+ * - **Standalone mode:** `<Legend items={…}>` renders explicit rows — inside
+ *   a container (replacing the registry) or entirely outside one (a
+ *   dashboard-side key; pass `theme` there).
+ */
+export declare function Legend({ placement, items, onRowClick, onRowHover, theme: themeProp, }: LegendProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=Legend.d.ts.map

package/dist/Legend.js

@@ -0,0 +1,169 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext } from 'react';
+import { ContainerContext, RowContext } from './context.js';
+import { buildChartLegend } from './useChartLegend.js';
+import { defaultTheme } from './theme.js';
+/** One 20×12 swatch glyph, drawn from the layer's resolved style. */
+function SwatchGlyph({ spec }) {
+    const w = 20;
+    const h = 12;
+    const mid = h / 2;
+    switch (spec.kind) {
+        case 'line': {
+            const sw = Math.min(spec.width, 4);
+            // A dashed series hand-renders as exactly THREE dashes — a canonical
+            // "dashed" glyph at swatch scale — rather than scaling the layer's own
+            // dash cadence into 20px (which can alias to 1 or 7 dashes and stop
+            // reading as dashed at all). Colour/width stay the resolved style.
+            if (spec.dash && spec.dash.length > 0) {
+                return (_jsxs("g", { stroke: spec.color, strokeWidth: sw, strokeLinecap: "butt", children: [_jsx("line", { x1: 0, y1: mid, x2: 4.6, y2: mid }), _jsx("line", { x1: 7.7, y1: mid, x2: 12.3, y2: mid }), _jsx("line", { x1: 15.4, y1: mid, x2: w, y2: mid })] }));
+            }
+            return (_jsx("line", { x1: 0, y1: mid, x2: w, y2: mid, stroke: spec.color, strokeWidth: sw }));
+        }
+        case 'area':
+            return (_jsxs("g", { children: [_jsx("rect", { x: 0, y: 3, width: w, height: h - 3, fill: spec.fill, fillOpacity: spec.fillOpacity }), _jsx("line", { x1: 0, y1: 3, x2: w, y2: 3, stroke: spec.line, strokeWidth: 1.5 })] }));
+        case 'band':
+            return (_jsx("rect", { x: 0, y: 2, width: w, height: h - 4, fill: spec.fill, fillOpacity: spec.opacity }));
+        case 'scatter': {
+            const r = Math.min(spec.radius, 5);
+            return (_jsx("circle", { cx: w / 2, cy: mid, r: r, fill: spec.color, stroke: spec.outline, strokeWidth: spec.outline !== undefined ? 1 : 0 }));
+        }
+        case 'box': {
+            const sw = Math.min(spec.whiskerWidth, 3);
+            return (_jsxs("g", { stroke: spec.whisker, strokeWidth: sw, children: [_jsx("line", { x1: w / 2, y1: 1, x2: w / 2, y2: h - 1 }), _jsx("line", { x1: w / 2 - 4, y1: 1, x2: w / 2 + 4, y2: 1 }), _jsx("line", { x1: w / 2 - 4, y1: h - 1, x2: w / 2 + 4, y2: h - 1 })] }));
+        }
+        case 'bar':
+            // A centred rounded square — reads as "a fill" without pretending to be
+            // a bar of any particular width (#512 follow-up feedback, second pass:
+            // centred in the swatch box like the other glyphs).
+            return (_jsx("rect", { x: (w - 10) / 2, y: 1, width: 10, height: 10, rx: 2, fill: spec.fill }));
+        case 'candle':
+            return (_jsxs("g", { children: [_jsx("line", { x1: 5.5, y1: 0, x2: 5.5, y2: h, stroke: spec.up, strokeWidth: 1 }), _jsx("rect", { x: 3, y: 2, width: 5, height: h - 5, fill: spec.up }), _jsx("line", { x1: 14.5, y1: 0, x2: 14.5, y2: h, stroke: spec.down, strokeWidth: 1 }), _jsx("rect", { x: 12, y: 3, width: 5, height: h - 5, fill: spec.down })] }));
+    }
+}
+/** The card's corner offsets — anchored to the **plot area**, not the rows
+ *  block: the horizontal inset adds the container's axis gutter on that side,
+ *  so a left placement never sits over the y-axis labels (#512 follow-up
+ *  feedback). Vertically the rows block already IS the plot (the x-axis strip
+ *  renders outside it). */
+function placementStyle(placement, leftGutter, rightGutter) {
+    switch (placement) {
+        case 'top-left':
+            return { top: 8, left: leftGutter + 8 };
+        case 'top-right':
+            return { top: 8, right: rightGutter + 8 };
+        case 'bottom-left':
+            return { bottom: 8, left: leftGutter + 8 };
+        case 'bottom-right':
+            return { bottom: 8, right: rightGutter + 8 };
+    }
+}
+/**
+ * The **series key** — one row per registered draw layer: a swatch of the
+ * layer's *resolved* style (so the key can never drift from the plot) and its
+ * readout identity (`as ?? column`, or the layer's `legend="name"` override).
+ * A child of {@link ChartContainer} (anywhere — it reads the registry, not its
+ * position): renders a small card anchored to a corner of the rows block.
+ *
+ * - **Rows** follow chart-row order, then declaration order (the z-order
+ *   convention); two layers sharing an identity (`id ?? label`) collapse to
+ *   one row, exactly as the tracker readout merges keys.
+ * - **A layer opts out** with `legend={false}`, or renames its row with
+ *   `legend="Display name"`.
+ * - **Interactivity is id-gated** (the selection contract): rows whose layer
+ *   has an `id` echo hover into the container and toggle selection on click;
+ *   `onRowHover` / `onRowClick` take over when provided. The selected row
+ *   reads emphasized; the hovered row tints.
+ * - **Scope follows placement:** at the container level it lists **all** rows;
+ *   placed inside a `<Layers>` it **scopes to that `<ChartRow>`** and anchors
+ *   to that row's plot (like an annotation) — a per-row legend needs no prop.
+ * - **Standalone mode:** `<Legend items={…}>` renders explicit rows — inside
+ *   a container (replacing the registry) or entirely outside one (a
+ *   dashboard-side key; pass `theme` there).
+ */
+export function Legend({ placement = 'top-right', items, onRowClick, onRowHover, theme: themeProp, }) {
+    const container = useContext(ContainerContext);
+    if (container === null && items === undefined) {
+        throw new Error('<Legend> must be inside a <ChartContainer> (or be given explicit `items`)');
+    }
+    // A RowContext in scope (the card is inside a <Layers>) narrows the registry
+    // to that row's layers AND means we're already inside the row's plot cell —
+    // so the corner inset drops the axis gutter (see placementStyle below).
+    const row = useContext(RowContext);
+    const theme = themeProp ?? container?.theme ?? defaultTheme;
+    const slot = theme.legend ?? {
+        background: theme.chip?.background ?? '#ffffff',
+        border: theme.axis.grid,
+        text: theme.axis.label,
+    };
+    // The shared headless core (also `useChartLegend`'s) — rows + the id-gated
+    // hover/select verbs — so the built-in card and a custom-rendered legend
+    // can never disagree. `null` in standalone `items` mode (no chart to sync).
+    const legend = container !== null ? buildChartLegend(container, row?.rowKey) : null;
+    // The card renders a flat item list — `rows` is grouped by chart row, so
+    // flatten it (a scoped legend has one group anyway).
+    const entries = items ?? legend.rows.flatMap((r) => r.items);
+    if (entries.length === 0)
+        return null;
+    // Selection reads by CONTRAST: the selected item goes bold and every other
+    // dulls (the ticker-compare treatment) — quieter and clearer than
+    // decorating the selected item itself. Only when the selection points at an
+    // item of THIS legend, so selecting an off-legend mark dulls nothing.
+    const selectedId = container?.selected?.id;
+    const anySelected = selectedId !== undefined && entries.some((it) => it.id === selectedId);
+    const enter = (item) => {
+        if (onRowHover)
+            return onRowHover(item);
+        legend?.hover(item);
+    };
+    const leave = (item) => {
+        if (onRowHover)
+            return onRowHover(null);
+        if (item.id !== undefined)
+            legend?.hover(null);
+    };
+    const click = (item) => {
+        if (onRowClick)
+            return onRowClick(item);
+        legend?.select(item);
+    };
+    // Standalone (no container): a normal-flow card the consumer places.
+    const positioned = container !== null;
+    return (_jsx("div", { "data-legend": "", style: {
+            ...(positioned
+                ? {
+                    position: 'absolute',
+                    // Row-scoped (inside the plot cell): no gutter inset — the cell
+                    // already starts at the plot edge. Container-level: inset by the
+                    // axis gutter so the card clears the y-axis labels.
+                    ...placementStyle(placement, row !== null ? 0 : container.leftGutter, row !== null ? 0 : container.rightGutter),
+                    zIndex: 5,
+                }
+                : { display: 'inline-block' }),
+            background: slot.background,
+            border: `1px solid ${slot.border}`,
+            borderRadius: 4,
+            padding: '4px 8px',
+            font: `${theme.font.size}px ${theme.font.family}`,
+            color: slot.text,
+            lineHeight: 1.6,
+        }, children: entries.map((item) => {
+            const interactive = onRowClick !== undefined ||
+                onRowHover !== undefined ||
+                (item.id !== undefined && container !== null);
+            const selected = item.id !== undefined && container?.selected?.id === item.id;
+            const hovered = item.id !== undefined && container?.hovered?.id === item.id;
+            return (_jsxs("div", { onPointerEnter: () => enter(item), onPointerLeave: () => leave(item), onClick: () => click(item), style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 6,
+                    cursor: interactive ? 'pointer' : 'default',
+                    fontWeight: selected ? 600 : 400,
+                    opacity: anySelected && !selected ? 0.45 : 1,
+                    background: hovered ? slot.border : 'transparent',
+                    borderRadius: 2,
+                    padding: '0 2px',
+                }, children: [_jsx("svg", { width: 20, height: 12, style: { flex: 'none' }, children: _jsx(SwatchGlyph, { spec: item.swatch }) }), _jsx("span", { children: item.label })] }, item.id !== undefined ? `${item.id}${item.label}` : item.label));
+        }) }));
+}
+//# sourceMappingURL=Legend.js.map

package/dist/LineChart.d.ts

@@ -1,5 +1,6 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { DecimateOption } from './decimate.js';
 import { type Curve } from './curve.js';
 import { type GapMode } from './gaps.js';
 export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
@@ -63,6 +64,24 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
      * no-op on a continuous axis (no provider) or a provider without `boundaries`.
      */
     sessionBreaks?: boolean;
+    /**
+     * **M4 viewport decimation** (charts decimator wave). **Omitted ⇒ `true`**:
+     * once the visible data is denser than ~2 samples per device pixel, the line
+     * is drawn from the per-pixel-column min/max/first/last (a pixel-identical
+     * polyline of O(plot width) points) instead of every sample — so a 1M-point
+     * series pans at interactive rates. It is **visually lossless** (a perf knob,
+     * not a style), and applies only to the honest default draw: a solid line with
+     * `gaps="empty"`, a linear `curve`, and no `sessionBreaks` (other modes draw
+     * full-resolution until later phases wire them). Pass `false` to always draw
+     * every point, or `{ threshold }` to tune the samples-per-pixel factor.
+     */
+    decimate?: DecimateOption;
+    /**
+     * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
+     * row's display name. **Omitted ⇒ a row named by the layer's readout
+     * identity** (`as` ?? `column`). The swatch is the resolved line style.
+     */
+    legend?: boolean | string;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -75,5 +94,5 @@ export interface LineChartProps<S extends SeriesSchema = SeriesSchema, VS extend
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, sessionBreaks, index, }: LineChartProps<S, VS>): null;
+export declare function LineChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, axis, curve, gaps, sessionBreaks, decimate, legend, index, }: LineChartProps<S, VS>): null;
 //# sourceMappingURL=LineChart.d.ts.map

package/dist/LineChart.js

@@ -5,6 +5,7 @@ import { drawLine, yExtent } from './line.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { ContainerContext, LayersContext } from './context.js';
+import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /** Stable empty boundary list — so `sessionBreaks={false}` keeps a referentially
  *  constant array and the layer entry isn't rebuilt every render. */
@@ -15,7 +16,7 @@ const NO_BREAKS = [];
  * (scaling against its `axis`), and renders nothing to the DOM — the row draws
  * it. The line breaks at gaps rather than spanning them.
  */
-export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, index = 0, }) {
+export function LineChart({ series, column, as: semantic, axis, curve, gaps = DEFAULT_GAP_MODE, sessionBreaks = false, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<LineChart> must be rendered inside a <ChartContainer>');
@@ -81,7 +82,7 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
                     ? [{ x: e.begin(), value: v, color: style.color, label }]
                     : [];
             },
-            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity, sessionBreakInstants),
+            draw: (ctx, xScale, yScale) => drawLine(ctx, cs, xScale, yScale, style, curveFactory, gaps, gapConnectorOpacity, sessionBreakInstants, decimate),
         },
         axisId: axis,
         index,
@@ -95,6 +96,7 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
         gaps,
         gapConnectorOpacity,
         sessionBreakInstants,
+        decimate,
         axis,
         index,
     ]);
@@ -115,6 +117,25 @@ export function LineChart({ series, column, as: semantic, axis, curve, gaps = DE
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // And a legend row: the readout identity + the resolved line style, so a
+    // `<Legend>` swatch can never drift from what the canvas draws.
+    const legendRows = useMemo(() => {
+        const name = legendLabelFor(legend, label);
+        return name === null
+            ? null
+            : [
+                {
+                    label: name,
+                    swatch: {
+                        kind: 'line',
+                        color: style.color,
+                        width: style.width,
+                        dash: style.dash,
+                    },
+                },
+            ];
+    }, [legend, label, style]);
+    useLegendItems(container, slot, index, legendRows);
     return null;
 }
 //# sourceMappingURL=LineChart.js.map

package/dist/ScatterChart.d.ts

@@ -85,6 +85,13 @@ export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS ext
      * together, so a nudged point still selects.
      */
     offset?: number;
+    /**
+     * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
+     * row's display name. **Omitted ⇒ a row named by the layer's readout
+     * identity** (`as` ?? `column`). The swatch is the resolved base dot style
+     * (a data-driven `radius`/`color` encoding shows its base, not the range).
+     */
+    legend?: boolean | string;
     /**
      * @internal Declaration position among the `<Layers>` children, injected by
      * `Layers` so z-order follows JSX order. Do not set.
@@ -119,5 +126,5 @@ export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS ext
  * </Layers>
  * ```
  */
-export declare function ScatterChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, offset, index, }: ScatterChartProps<S, VS>): null;
+export declare function ScatterChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, offset, legend, index, }: ScatterChartProps<S, VS>): null;
 //# sourceMappingURL=ScatterChart.d.ts.map

package/dist/ScatterChart.js

@@ -4,6 +4,7 @@ import { fromTimeSeries, fromValueSeries } from './data.js';
 import { drawScatter, hitTestScatter, nearestIndex, scatterExtent, } from './scatter.js';
 import { resolveEncoding, } from './encoding.js';
 import { ContainerContext, LayersContext } from './context.js';
+import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /**
  * A scatter draw layer: one mark per finite point at `(x, column-value)`
@@ -33,7 +34,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, offset = 0, index = 0, }) {
+export function ScatterChart({ series, column, as: semantic, id, axis, radius, color, label, offset = 0, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<ScatterChart> must be rendered inside a <ChartContainer>');
@@ -163,6 +164,28 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // And a legend row: the readout identity + the resolved base dot (a fixed
+    // `radius` number shows at size; an encoding shows the style's base radius).
+    // Carries the layer's `id` so the legend's default interactions are id-gated
+    // exactly like the mark's own.
+    const legendRows = useMemo(() => {
+        const name = legendLabelFor(legend, seriesLabel);
+        return name === null
+            ? null
+            : [
+                {
+                    label: name,
+                    id,
+                    swatch: {
+                        kind: 'scatter',
+                        color: style.color,
+                        radius: typeof radius === 'number' ? radius : style.radius,
+                        outline: style.outline,
+                    },
+                },
+            ];
+    }, [legend, seriesLabel, id, style, radius]);
+    useLegendItems(container, slot, index, legendRows);
     // Advertise selectability (only when an `id` was given) so the container can
     // warn if selection is wired but nothing is selectable.
     const { registerSelectable, unregisterSelectable } = container;

package/dist/XAxis.js

@@ -158,6 +158,13 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // Split from `fmt` so an axis's terse tick labels never leak into the cursor /
     // marker readouts, which stay full timestamps.
     const tickFmt = flatFmt ?? (stacked ? baseFmt : undefined) ?? fmt;
+    // The **readout** formatter — the cursor pill + marker indicator pills. A
+    // container `cursorFormat` wins even over an explicit axis `format` (pill
+    // precedence `cursorFormat → axis format → container`): the readout is its
+    // own channel, so precise-pill-over-terse-ticks works on any axis kind. A
+    // `transform`ed axis is exempt — its pill speaks the derived unit, which a
+    // data-unit `cursorFormat` can't address.
+    const readoutFmt = transform === undefined ? (container.formatReadout ?? fmt) : fmt;
     // Marker annotations that opted into an axis indicator (`<Marker indicator>`)
     // pin their **time** to this shared x-axis — a pill at `at`, in the annotation
     // colour, reading like a tick. An indicator always shows the axis coordinate
@@ -181,7 +188,7 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
             key: a.key,
             id: a.id ?? `marker-at-${at}`,
             x: xScale(at),
-            text: fmt(at),
+            text: readoutFmt(at),
         };
     })
         .filter((t) => t.x >= 0 && t.x <= plotWidth);
@@ -411,6 +418,6 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                             transform: 'translateX(-50%)',
                             [onTop ? 'bottom' : 'top']: `${pillOffset}px`,
                             zIndex: 3,
-                        }, children: fmt(+xScale.invert(cursorX)) })] }))] }));
+                        }, children: readoutFmt(+xScale.invert(cursorX)) })] }))] }));
 }
 //# sourceMappingURL=XAxis.js.map

package/dist/YAxis.d.ts

@@ -60,6 +60,14 @@ export interface YAxisProps {
         readonly at: number;
         readonly label: string;
     }>;
+    /**
+     * Target number of **auto** ticks — the `count` passed to `scale.ticks()`
+     * (d3 returns nice 1-2-5 values near it, not exactly this many). **Omitted ⇒
+     * derived from the row height** so a short strip isn't crushed with a tall
+     * row's density (mirrors the width-derived x axis). Ignored when explicit
+     * {@link ticks} are given (those set both labels and gridlines directly).
+     */
+    tickCount?: number;
     /**
      * Render the tick labels at the domain extremes (the top & bottom ticks)?
      * **Default `true`.** `false` drops just those two numbers — the gridlines
@@ -92,5 +100,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, min, max, format, ticks, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, min, max, format, ticks, tickCount, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -4,7 +4,10 @@ import { ContainerContext, RowContext } from './context.js';
 import { resolveAxisFormat } from './format.js';
 import { useSlotKey } from './use-slot-key.js';
 const DEFAULT_WIDTH = 50;
-const TICK_COUNT = 5;
+/** Fallback tick count before the row has published its resolved count (the
+ *  first render, pre-registration). The row's height-derived value takes over
+ *  immediately after. */
+const DEFAULT_TICK_COUNT = 5;
 /**
  * A y-axis for a {@link ChartRow}, rendered as DOM chrome (not canvas) so the
  * text is crisp, themeable, and accessible. Registers its id / side / width /
@@ -13,7 +16,7 @@ const TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -32,8 +35,21 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
         labelPlacement,
         format,
         tickValues: ticks?.map((t) => t.at),
+        tickCount,
         index,
-    }), [id, side, width, min, max, pad, labelPlacement, format, ticks, index]);
+    }), [
+        id,
+        side,
+        width,
+        min,
+        max,
+        pad,
+        labelPlacement,
+        format,
+        ticks,
+        tickCount,
+        index,
+    ]);
     // A stable per-instance slot (see useSlotKey) keeps this axis in a fixed
     // registry position, so a min/max/side change updates in place rather than
     // re-appending (which would move the first axis behind a later one and
@@ -48,14 +64,19 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, pad =
     }, [registerAxis, slot, spec]);
     const { theme } = container;
     const yScale = row.yScales.get(id);
+    // The auto-tick count — the row resolves it (explicit `tickCount` else
+    // height-derived) and both this axis's labels AND the row's gridlines read
+    // the same value, so a label and its gridline can't drift apart.
+    const count = row.tickCounts.get(id) ?? DEFAULT_TICK_COUNT;
     // Same formatter the readout uses (resolved per axis on the row), so a tick and
-    // a cursor value read identically.
-    const fmt = yScale ? resolveAxisFormat(yScale, TICK_COUNT, format) : String;
+    // a cursor value read identically. `count` calibrates the default formatter's
+    // precision to the tick density, exactly as the axis is.
+    const fmt = yScale ? resolveAxisFormat(yScale, count, format) : String;
     // Explicit `{ at, label }` ticks render verbatim (each label at its `at`),
     // overriding the auto-picked d3 ticks; otherwise label the scale's ticks via `fmt`.
     const tickList = ticks
         ? ticks.map((t) => ({ value: t.at, label: t.label }))
-        : (yScale ? yScale.ticks(TICK_COUNT) : []).map((t) => ({
+        : (yScale ? yScale.ticks(count) : []).map((t) => ({
             value: t,
             label: fmt(t),
         }));