@svgrid/grid 3.0.1 → 3.0.3

package/src/SvGridChart.svelte

@@ -7,7 +7,8 @@
    * focus tooltips, a clickable legend that toggles series, optional data
    * labels, and an `onSelect` drill hook. No external charting dependency.
    */
-  import { buildChart, DEFAULT_PALETTE, formatChartValue, type ChartSpec, type ChartSelection } from './chart'
+  import type { Snippet } from 'svelte'
+  import { buildChart, chartScales, DEFAULT_PALETTE, formatChartValue, sliceChartWindow, type ChartSpec, type ChartSelection, type ChartGeometry, type ChartScales } from './chart'
 
   type Props = {
     spec: ChartSpec
@@ -42,6 +43,67 @@
      *  fit exactly - used by the docked panel to size the chart to its body. */
     width?: number
     height?: number
+    /**
+     * Draw your own marks in the chart's own coordinates - the custom-series
+     * seam. `underlay` paints beneath the built-in marks (bands, shaded
+     * regions, a background you want the bars to sit on); `overlay` paints
+     * above them but below the crosshair and the hit layer, so tooltips and
+     * clicks keep working over whatever you draw.
+     *
+     * Both receive the laid-out geometry and its scales, so a custom mark lands
+     * on exactly the axis the built-in ones did:
+     *
+     * ```svelte
+     * <SvChart {spec}>
+     *   {#snippet overlay({ geo, xOf, yOf })}
+     *     <circle cx={xOf(3)} cy={yOf(120)} r="5" fill="tomato" />
+     *   {/snippet}
+     * </SvChart>
+     * ```
+     *
+     * `xOf` / `yOf` are null for the types with no cartesian axes (pie, gauge,
+     * treemap, sankey, calendar, radar, funnel); `geo` is always there.
+     */
+    underlay?: Snippet<[ChartRenderContext]>
+    overlay?: Snippet<[ChartRenderContext]>
+    /**
+     * Let a reader pin annotations on the plot. Adds an "Annotate" toggle to
+     * the toolbar; while it is on, clicking the plot fires `onAnnotate` with
+     * the point that was clicked, and clicking an existing marker fires
+     * `onAnnotationRemove` with its index.
+     *
+     * The chart does NOT store them. It owns the gesture - which you cannot
+     * build from outside, because drag is already zoom and click is already
+     * drill - and hands back the data point; where the annotations live, and
+     * whether they survive a reload, is the host's business. Put what comes
+     * back into `spec.annotations` and they render like any other.
+     */
+    annotatable?: boolean
+    /**
+     * A point the reader picked while annotating. It is a DATA point, not a
+     * pixel: annotate mode takes over the category gesture, so a note anchors
+     * to the category it was pinned on and stays there when the chart is
+     * re-laid-out, re-sorted or zoomed. That also means it works from the
+     * keyboard, since the category hit zones already navigate with arrows.
+     */
+    onAnnotate?: (at: {
+      /** The category picked, and its index. */
+      category: string
+      index: number
+      /** The value at that category on the first series. */
+      value: number
+    }) => void
+    /** An existing `spec.annotations` entry was clicked, by index. */
+    onAnnotationRemove?: (index: number) => void
+  }
+  /** What a custom mark is handed. `scales` is null on non-cartesian types. */
+  type ChartRenderContext = {
+    geo: ChartGeometry
+    /** Pixel x at the centre of category `i`. Null when there is no x axis. */
+    xOf: ChartScales['xOf'] | null
+    /** Pixel y for a value. Null when there is no value axis. */
+    yOf: ChartScales['yOf'] | null
+    scales: ChartScales | null
   }
   let {
     spec,
@@ -57,14 +119,22 @@
     toolbar,
     width,
     height,
+    underlay,
+    overlay,
+    annotatable = false,
+    onAnnotate,
+    onAnnotationRemove,
   }: Props = $props()
-  const showToolbar = $derived(toolbar ?? (zoomable || !!onDrill))
+  const showToolbar = $derived(toolbar ?? (zoomable || !!onDrill || annotatable))
+  /** Annotate mode is off until the reader asks for it: it takes over the plot
+   *  click, which is the drill gesture the rest of the time. */
+  let annotating = $state(false)
 
   const fmt = (v: number) =>
     formatValue
       ? formatValue(v)
       : spec.valueFormat
-        ? formatChartValue(v, spec.valueFormat)
+        ? formatChartValue(v, spec.valueFormat, spec)
         : Number.isFinite(v)
           ? v.toLocaleString(undefined, { maximumFractionDigits: 2 })
           : String(v)
@@ -72,9 +142,16 @@
   let hidden = $state(new Set<string>())
   // Isolate: double-clicking a legend chip shows ONLY that series/slice.
   let isolated = $state<string | null>(null)
+  // Series colours read from --sg-chart-1..8. Declared here because the
+  // palette derivation below reads it, and a rune used above its declaration
+  // is an error rather than a hoist. Filled by the theme effect further down.
+  let tokenPalette = $state<string[] | null>(null)
+
   // Hover-dim: hovering a legend chip dims the other series (visual only).
   let dimmed = $state<string | null>(null)
-  const palette = $derived(spec.palette ?? DEFAULT_PALETTE)
+  // An explicit `spec.palette` is the author speaking about THIS chart, so it
+  // outranks the theme's tokens, which in turn outrank the built-in colours.
+  const palette = $derived(spec.palette ?? tokenPalette ?? DEFAULT_PALETTE)
   const uid = `svgc-${Math.random().toString(36).slice(2, 8)}`
 
   const coloredSeries = $derived(
@@ -153,6 +230,9 @@
     return Math.max(0, Math.min(visibleSpec.categories.length - 1, idx))
   }
   function onZoomDown(e: PointerEvent) {
+    // Annotate mode takes the plot pointer over. Without this a click to pin an
+    // annotation also starts a zoom drag, and the reader gets both.
+    if (annotating) return
     if (!zoomable || !isCartesian) return
     const p = svgPoint(e)
     if (!p) return
@@ -188,6 +268,15 @@
     if (zoomable && isZoomed) resetZoom()
   }
 
+  // Candles are cartesian, and the `isCartesian` negative list below already
+  // covers them, so they inherit gridlines, the crosshair, category hit bands,
+  // keyboard nav, drag-zoom and double-click reset with no new wiring.
+  // Declared up here because the brush spec reads it, and a `$derived` used
+  // above its declaration is an error rather than a hoist.
+  const isCandle = $derived(spec.type === 'candlestick' || spec.type === 'ohlc')
+  /** OHLC draws ticks off a vertical; candlestick draws a body and a wick. */
+  const isOhlcBars = $derived(spec.type === 'ohlc')
+
   // ---- Brush state -----------------------------------------------------
   // The brush is a compact second chart showing the FULL data range with
   // a translucent window over the visible slice. Dragging the body pans
@@ -202,7 +291,21 @@
     yAxisTitle: undefined, y2AxisTitle: undefined, xAxisTitle: undefined,
     referenceLines: undefined,
     annotations: undefined,
-    series: coloredSeries.filter((s) => !effectiveHidden.has(s.label)),
+    // The mini-map draws candles as a close-price line: at brush scale a
+    // candle is a couple of pixels wide and reads as noise, while a close line
+    // is the shape a reader actually navigates by.
+    // A box gets the same treatment for the same reason: at brush scale it is
+    // a smear, while the median line is a shape you can navigate by.
+    type: isCandle ? 'line' : spec.type === 'boxplot' ? 'line' : spec.type,
+    series: coloredSeries
+      .filter((s) => !effectiveHidden.has(s.label))
+      .map((s) =>
+        s.ohlc || s.boxes
+          ? { ...s, ohlc: undefined, boxes: undefined, errors: undefined, type: 'line' as const }
+          : s.errors
+            ? { ...s, errors: undefined }
+            : s,
+      ),
   })
   const brushGeo = $derived(brushEligible ? buildChart(brushSpec) : null)
   /** The brush window in fractional [0..1] of the visible data range,
@@ -269,20 +372,12 @@
     }
     const visibleSeries = coloredSeries.filter((s) => !effectiveHidden.has(s.label))
     if (!zoom) return { ...spec, series: visibleSeries }
-    // Slice categories + each series' values to the zoom window so
-    // buildChart re-spreads the visible slice across the full plot.
-    const lo = Math.max(0, zoom.i0)
-    const hi = Math.min(spec.categories.length - 1, zoom.i1)
-    const slice = <T,>(arr: T[]) => arr.slice(lo, hi + 1)
-    return {
-      ...spec,
-      categories: slice(spec.categories),
-      series: visibleSeries.map((s) => ({
-        ...s,
-        values: slice(s.values),
-        rowIds: s.rowIds ? slice(s.rowIds) : undefined,
-      })),
-    }
+    // Narrow to the zoom window so buildChart re-spreads the visible slice
+    // across the full plot. The slicing itself lives in chart.ts: this used to
+    // be done by hand here and only covered categories / values / rowIds, so
+    // the confidence-band envelopes kept their full length and the band
+    // silently vanished as soon as anyone zoomed.
+    return sliceChartWindow({ ...spec, series: visibleSeries }, zoom.i0, zoom.i1)
   })
 
   // Heatmap / calendar cell fills are computed colors (not CSS), so they can't
@@ -290,9 +385,26 @@
   // chartEl) and hand buildChart a light/dark hint so low-value cells render as
   // "cold" rather than glaring white rectangles on a dark grid.
   let isDark = $state(false)
+  // Hand the RESOLVED palette down here rather than relying on per-series
+  // colours alone: buildChart also picks from `spec.palette` for the marks
+  // that have no series of their own (pie slices, treemap cells), and those
+  // should follow the theme tokens too.
   const geo = $derived(
-    buildChart(width || height ? { ...visibleSpec, width, height } : visibleSpec, isDark ? 'dark' : 'light'),
+    buildChart(
+      { ...visibleSpec, palette, ...(width || height ? { width, height } : {}) },
+      isDark ? 'dark' : 'light',
+    ),
   )
+  /** What the `underlay` / `overlay` snippets are handed. Built from the
+   *  laid-out geometry, so a custom mark shares the built-in scale exactly. */
+  const renderScales = $derived(chartScales(geo))
+  const renderCtx = $derived<ChartRenderContext>({
+    geo,
+    scales: renderScales,
+    xOf: renderScales?.xOf ?? null,
+    yOf: renderScales?.yOf ?? null,
+  })
+
   const isCartesian = $derived(
     spec.type !== 'pie' && spec.type !== 'heatmap' &&
     spec.type !== 'funnel' && spec.type !== 'radar' &&
@@ -314,6 +426,95 @@
     (isHorizontal ? geo.plot.h : geo.plot.w) / Math.max(1, visibleSpec.categories.length),
   )
 
+  /**
+   * A chart with more categories than the plot has room for.
+   *
+   * `buildChart` itself scales fine - 100k line points is about 140ms of pure
+   * maths. What does not scale is what the DOM is asked to hold: one `<circle>`
+   * per point, one hit `<rect>` per category whose `aria-label` costs a
+   * `catRows()` call AT RENDER TIME, and one screen-reader table row per
+   * category. That is roughly 300k nodes for a 100k-point series, and the chart
+   * stops responding long before the engine breaks a sweat.
+   *
+   * Below ~4px per category none of that machinery is buying anything anyway:
+   * the dots overlap into a smear that hides the line they are meant to mark,
+   * and a hit rect thinner than the pointer cannot be aimed at. So under the
+   * threshold the marks collapse to the line path, the hit rects collapse to one
+   * surface that computes the index from the cursor, and the table is capped.
+   */
+  const DENSE_SLOT_PX = 4
+  const dense = $derived(
+    isCartesian && !isScatter && !isHorizontal && slot < DENSE_SLOT_PX && visibleSpec.categories.length > 1,
+  )
+
+  /** Rows the screen-reader table will actually render before it is capped. */
+  const SR_ROW_CAP = 1000
+
+  /** Which category the cursor is over, in dense mode. Binary search over the
+   *  first series' point x's, so a non-uniform (time) axis is handled too;
+   *  uniform slot maths when there are no line points to search. */
+  /** Client px -> viewBox px. The svg scales to its container, so the two
+   *  differ whenever the chart is not rendered at its natural size. */
+  function toViewBox(clientX: number, clientY: number, target: Element): { x: number; y: number } | null {
+    const svg = (target as SVGGraphicsElement).ownerSVGElement ?? (target as SVGSVGElement)
+    if (!svg || typeof svg.getBoundingClientRect !== 'function') return null
+    const box = svg.getBoundingClientRect()
+    if (!box.width || !box.height) return null
+    const vb = (svg as SVGSVGElement).viewBox?.baseVal
+    const sx = vb && vb.width ? vb.width / box.width : 1
+    const sy = vb && vb.height ? vb.height / box.height : 1
+    return {
+      x: (clientX - box.left) * sx + (vb ? vb.x : 0),
+      y: (clientY - box.top) * sy + (vb ? vb.y : 0),
+    }
+  }
+
+  function catAtClientX(clientX: number, target: Element): number | null {
+    const vp = toViewBox(clientX, 0, target)
+    if (!vp) return null
+    const x = vp.x
+    const pts = geo.lines[0]?.points
+    const n = visibleSpec.categories.length
+    if (!pts || pts.length !== n) {
+      const i = Math.floor((x - geo.plot.x) / slot)
+      return i >= 0 && i < n ? i : null
+    }
+    let lo = 0
+    let hi = pts.length - 1
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1
+      if (pts[mid]!.x < x) lo = mid + 1
+      else hi = mid
+    }
+    // Land on the nearer of the two neighbours rather than always rounding up.
+    if (lo > 0 && Math.abs(pts[lo - 1]!.x - x) <= Math.abs(pts[lo]!.x - x)) lo -= 1
+    return lo
+  }
+
+  /** Focused category in dense mode, where there is one rect rather than n. */
+  let denseIndex = $state(0)
+  function onDenseKey(e: KeyboardEvent) {
+    const max = visibleSpec.categories.length - 1
+    const step = Math.max(1, Math.floor(max / 10))
+    let next = denseIndex
+    switch (e.key) {
+      case 'ArrowRight': case 'ArrowDown': next = Math.min(max, denseIndex + 1); break
+      case 'ArrowLeft': case 'ArrowUp': next = Math.max(0, denseIndex - 1); break
+      case 'Home': next = 0; break
+      case 'End': next = max; break
+      case 'PageDown': next = Math.min(max, denseIndex + step); break
+      case 'PageUp': next = Math.max(0, denseIndex - step); break
+      case 'Enter': case ' ':
+        e.preventDefault()
+        select(visibleSpec.categories[denseIndex] ?? '', '', 0, denseIndex)
+        return
+      default: return
+    }
+    e.preventDefault()
+    denseIndex = next
+    focusCat(e.currentTarget as Element, next)
+  }
+
   // Opacity for a series when another legend chip is being hovered.
   const dimOf = (seriesLabel: string) => (dimmed && dimmed !== seriesLabel ? 0.18 : 1)
 
@@ -341,6 +542,8 @@
     if (spec.type === 'gauge') return !geo.gauge
     if (spec.type === 'treemap') return geo.treemapCells.length === 0
     if (spec.type === 'sankey') return geo.sankeyNodes.length === 0
+    if (isCandle) return geo.candles.length === 0
+    if (spec.type === 'boxplot') return geo.boxes.length === 0
     return geo.bars.length === 0 && geo.lines.every((l) => l.points.every((p) => !p.defined))
   })
 
@@ -374,11 +577,30 @@
       for (const s of coloredSeries) for (const p of s.points ?? []) rows.push([s.label, fmt(p.x), fmt(p.y), p.r != null ? fmt(p.r) : ''])
       return { cols: ['Series', 'X', 'Y', 'Size'], rows }
     }
+    if (isCandle) {
+      // This IS the accessible version of the chart, so it carries the four
+      // real numbers rather than the closes `values` happens to hold.
+      const rows: string[][] = []
+      for (const s of coloredSeries) {
+        ;(s.ohlc ?? []).forEach((k, i) => {
+          if (!k) return
+          rows.push([spec.categories[i] ?? String(i), s.label, fmt(k.o), fmt(k.h), fmt(k.l), fmt(k.c)])
+        })
+      }
+      return { cols: ['Date', 'Series', 'Open', 'High', 'Low', 'Close'], rows }
+    }
     return {
       cols: ['Category', ...coloredSeries.map((s) => s.label)],
       rows: spec.categories.map((c, i) => [c, ...coloredSeries.map((s) => fmt(s.values[i] ?? 0))]),
     }
   })
+  /** Declared here rather than in the markup: `{@const}` is only legal as the
+   *  immediate child of a block, and the table sits at the template top level.
+   *  Below `srTable` because a `$derived` used above its declaration is an
+   *  error, not a hoist. */
+  const srCapped = $derived(srTable.rows.length > SR_ROW_CAP)
+  const srRows = $derived(srCapped ? srTable.rows.slice(0, SR_ROW_CAP) : srTable.rows)
+
   function truncate(s: string, n = 12): string {
     return s.length > n ? s.slice(0, n - 1) + '…' : s
   }
@@ -405,10 +627,32 @@
     // Perceived luminance (0..255); below the midpoint reads as a dark surface.
     return 0.299 * r + 0.587 * g + 0.114 * b < 128
   }
+  /**
+   * Series colours declared as `--sg-chart-1` .. `--sg-chart-8`.
+   *
+   * The palette used to be a hard-coded array in `chart.ts`, which meant a
+   * theme could restyle every part of a chart except the data - the one part
+   * a brand actually cares about. It stays out of `chart.ts` because that
+   * module is deliberately DOM-free and SSR-safe, so the tokens are read here
+   * and handed down as an ordinary `palette`.
+   *
+   * Partial sets are honoured: declare two tokens and the rest fall back, so a
+   * theme can set a brand primary and secondary without inventing six more.
+   */
   $effect(() => {
     if (!chartEl || typeof window === 'undefined') return
     const el = chartEl
-    const check = () => { isDark = surfaceIsDark(getComputedStyle(el).getPropertyValue('--sg-bg')) }
+    const check = () => {
+      const cs = getComputedStyle(el)
+      isDark = surfaceIsDark(cs.getPropertyValue('--sg-bg'))
+      const next: string[] = []
+      for (let i = 1; i <= 8; i += 1) {
+        const v = cs.getPropertyValue(`--sg-chart-${i}`).trim()
+        next.push(v || DEFAULT_PALETTE[i - 1]!)
+      }
+      const changed = !tokenPalette || next.some((c, i) => c !== tokenPalette![i])
+      if (changed) tokenPalette = next.some((c, i) => c !== DEFAULT_PALETTE[i]) ? next : null
+    }
     check()
     const obs = new MutationObserver(check)
     obs.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme', 'class', 'style'] })
@@ -428,10 +672,51 @@
 
   // Unified tooltip: every visible series' value at one category.
   function catRows(i: number): TipRow[] {
-    return visibleSpec.series
-      .map((s) => ({ label: s.label, color: (s as { color?: string }).color, value: s.values[i] }))
-      .filter((r) => Number.isFinite(r.value))
-      .map((r) => ({ label: r.label, color: r.color, value: fmt(r.value as number) }))
+    const rows: TipRow[] = []
+    for (const s of visibleSpec.series) {
+      const color = (s as { color?: string }).color
+      // A candle carries four numbers, so it gets four rows. Doing it here
+      // rather than in a parallel tooltip path means the crosshair, the
+      // keyboard focus tooltip and the hit rect's aria-label all follow, and a
+      // volume series on the right axis still lists itself underneath.
+      const k = s.ohlc?.[i]
+      if (k) {
+        rows.push({ label: `${s.label} O`, color, value: fmt(k.o) })
+        rows.push({ label: `${s.label} H`, value: fmt(k.h) })
+        rows.push({ label: `${s.label} L`, value: fmt(k.l) })
+        rows.push({ label: `${s.label} C`, value: fmt(k.c) })
+        continue
+      }
+      // A box is a five-number summary, and reading it off the picture is
+      // exactly what a tooltip is for. Same reasoning as the candle above:
+      // one place, so crosshair / keyboard / aria-label all agree.
+      const b = s.boxes?.[i]
+      if (b) {
+        rows.push({ label: `${s.label} max`, color, value: fmt(b.max) })
+        rows.push({ label: `${s.label} Q3`, value: fmt(b.q3) })
+        rows.push({ label: `${s.label} median`, value: fmt(b.median) })
+        rows.push({ label: `${s.label} Q1`, value: fmt(b.q1) })
+        rows.push({ label: `${s.label} min`, value: fmt(b.min) })
+        if (b.outliers?.length) {
+          rows.push({ label: `${s.label} outliers`, value: String(b.outliers.length) })
+        }
+        continue
+      }
+      const v = s.values[i]
+      if (Number.isFinite(v)) {
+        rows.push({ label: s.label, color, value: fmt(v as number) })
+        // An error bar is only worth drawing if you can read what it means.
+        const e = s.errors?.[i]
+        if (e != null) {
+          const lo = typeof e === 'number' ? (v as number) - Math.abs(e) : Math.min(e.lo, e.hi)
+          const hi = typeof e === 'number' ? (v as number) + Math.abs(e) : Math.max(e.lo, e.hi)
+          if (Number.isFinite(lo) && Number.isFinite(hi)) {
+            rows.push({ label: `${s.label} range`, value: `${fmt(lo)} - ${fmt(hi)}` })
+          }
+        }
+      }
+    }
+    return rows
   }
   function hoverCat(clientX: number, clientY: number, i: number) {
     activeCat = i
@@ -473,6 +758,18 @@
   }
 
   function select(category: string, series: string, value: number, catIndex?: number) {
+    // Annotate mode takes over the category gesture rather than adding one of
+    // its own. That is what makes it work from the keyboard: the hit rects
+    // already have a roving tabindex and fire this on Enter, so pinning a note
+    // is Tab, arrow, Enter - with no extra handler and no click-only feature.
+    if (annotating && onAnnotate && catIndex !== undefined) {
+      // A CATEGORY click carries no value - `select(cat, '', 0, i)` passes zero
+      // because a drill only needs the category - so read the real one off the
+      // first series. A click on a specific bar or slice already has one.
+      const picked = series ? value : visibleSpec.series[0]?.values[catIndex]
+      onAnnotate({ category, index: catIndex, value: Number.isFinite(picked) ? (picked as number) : 0 })
+      return
+    }
     // Collect contributing row ids when the spec carries them. For a
     // category click (series === ''), flatten across every series; for a
     // single-series click, return just that series' bucket.
@@ -641,6 +938,19 @@
           Reset zoom
         </button>
       {/if}
+      {#if annotatable}
+        <button
+          type="button"
+          class="sv-grid-chart-tool"
+          class:is-on={annotating}
+          aria-pressed={annotating}
+          onclick={() => (annotating = !annotating)}
+          title={annotating ? 'Click the plot to pin a note, or a marker to remove it' : 'Pin notes on the chart'}
+        >
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 2v6"/><circle cx="12" cy="11" r="3"/><path d="M12 14v8"/></svg>
+          Annotate
+        </button>
+      {/if}
       <button type="button" class="sv-grid-chart-tool" onclick={() => downloadImage('png')} title="Download PNG">PNG</button>
       <button type="button" class="sv-grid-chart-tool" onclick={() => downloadImage('svg')} title="Download SVG">SVG</button>
       <button type="button" class="sv-grid-chart-tool" onclick={copyAsImage} title="Copy chart as image">
@@ -653,7 +963,8 @@
     class="sv-grid-chart-svg"
     class:is-interactive={interactive}
     class:is-clickable={!!onSelect || !!onDrill}
-    class:is-zoomable={zoomable && isCartesian}
+    class:is-zoomable={zoomable && isCartesian && !annotating}
+    class:is-annotating={annotating}
     class:is-dragging={!!dragStart}
     viewBox={`0 0 ${geo.width} ${geo.height}`}
     width="100%"
@@ -759,17 +1070,31 @@
           <path class="sv-grid-chart-area" d={line.areaPath} fill={seriesFill[line.label] ?? line.color} fill-opacity="0.15" stroke="none" />
         {/if}
         <path class="sv-grid-chart-linepath" d={line.path} fill="none" stroke={line.color} stroke-width="2" stroke-linejoin="round" stroke-linecap="round" />
-        {#each line.points as pt, pi (pi)}
-          {#if pt.defined}
-            <circle class="sv-grid-chart-dot" class:is-active={activeCat === pi} cx={pt.x} cy={pt.y} r={activeCat === pi ? 4 : 3} fill={line.color} />
-            {#if dataLabels}
-              <text class="sv-grid-chart-datalabel" x={pt.x} y={pt.y - 7} text-anchor="middle">{fmt(pt.value)}</text>
-            {/if}
+        {#if dense}
+          <!-- Below ~4px a category the dots touch, so they stop marking the
+               points and start hiding the line. Only the hovered one is drawn,
+               which is the one a reader is actually asking about. -->
+          {@const pt = line.points[activeCat ?? -1]}
+          {#if pt?.defined}
+            <circle class="sv-grid-chart-dot is-active" cx={pt.x} cy={pt.y} r="4" fill={line.color} />
           {/if}
-        {/each}
+        {:else}
+          {#each line.points as pt, pi (pi)}
+            {#if pt.defined}
+              <circle class="sv-grid-chart-dot" class:is-active={activeCat === pi} cx={pt.x} cy={pt.y} r={activeCat === pi ? 4 : 3} fill={line.color} />
+              {#if dataLabels}
+                <text class="sv-grid-chart-datalabel" x={pt.x} y={pt.y - 7} text-anchor="middle">{fmt(pt.value)}</text>
+              {/if}
+            {/if}
+          {/each}
+        {/if}
       </g>
     {/each}
 
+    <!-- Custom-series seam, beneath the built-in marks: shaded regions, bands,
+         anything the bars should sit on top of. -->
+    {#if underlay}{@render underlay(renderCtx)}{/if}
+
     {#each geo.bars as bar, bi (bi)}
       <rect class="sv-grid-chart-bar" x={bar.x} y={bar.y} width={bar.w} height={bar.h} rx="1" fill={seriesFill[bar.series] ?? bar.color} style={`opacity:${dimOf(bar.series)}`} />
       {#if dataLabels && isHorizontal && bar.w > 18}
@@ -779,6 +1104,42 @@
       {/if}
     {/each}
 
+    <!-- Candles paint above gridlines and any volume bars, below the reference
+         lines, annotations, crosshair and hit layer. Hollow-up / filled-down
+         rather than two fills: direction then reads from the shape as well as
+         the hue, which is the same reason this chart ships pattern fills. -->
+    {#each geo.candles as k, ki (ki)}
+      {#if isOhlcBars}
+        <line class="sv-grid-chart-ohlc" x1={k.xCenter} y1={k.yHigh} x2={k.xCenter} y2={k.yLow} stroke={k.color} style={`opacity:${dimOf(k.series)}`} />
+        <line class="sv-grid-chart-ohlc" x1={k.x} y1={k.yOpen} x2={k.xCenter} y2={k.yOpen} stroke={k.color} style={`opacity:${dimOf(k.series)}`} />
+        <line class="sv-grid-chart-ohlc" x1={k.xCenter} y1={k.yClose} x2={k.x + k.w} y2={k.yClose} stroke={k.color} style={`opacity:${dimOf(k.series)}`} />
+      {:else}
+        <line class="sv-grid-chart-wick" x1={k.xCenter} y1={k.yHigh} x2={k.xCenter} y2={k.yLow} stroke={k.color} style={`opacity:${dimOf(k.series)}`} />
+        <rect class="sv-grid-chart-candle" x={k.x} y={k.bodyY} width={k.w} height={k.bodyH} fill={k.up ? 'none' : k.color} stroke={k.color} style={`opacity:${dimOf(k.series)}`} />
+      {/if}
+    {/each}
+
+    <!-- Box plots. The median is a heavier rule than the box outline because it
+         is the number people actually read; the whisker caps are drawn at the
+         box width so the shape stays legible when the slot is narrow. -->
+    {#each geo.boxes as b, bi (bi)}
+      <line class="sv-grid-chart-whisker" x1={b.xCenter} y1={b.yMax} x2={b.xCenter} y2={b.yMin} stroke={b.color} style={`opacity:${dimOf(b.series)}`} />
+      <line class="sv-grid-chart-whisker" x1={b.x + b.w * 0.25} y1={b.yMax} x2={b.x + b.w * 0.75} y2={b.yMax} stroke={b.color} style={`opacity:${dimOf(b.series)}`} />
+      <line class="sv-grid-chart-whisker" x1={b.x + b.w * 0.25} y1={b.yMin} x2={b.x + b.w * 0.75} y2={b.yMin} stroke={b.color} style={`opacity:${dimOf(b.series)}`} />
+      <rect class="sv-grid-chart-box" x={b.x} y={b.boxY} width={b.w} height={b.boxH} fill={b.color} fill-opacity="0.25" stroke={b.color} style={`opacity:${dimOf(b.series)}`} />
+      <line class="sv-grid-chart-median" x1={b.x} y1={b.yMedian} x2={b.x + b.w} y2={b.yMedian} stroke={b.color} style={`opacity:${dimOf(b.series)}`} />
+      {#each b.outliers as o, oi (oi)}
+        <circle class="sv-grid-chart-outlier" cx={b.xCenter} cy={o.y} r="2" fill="none" stroke={b.color} style={`opacity:${dimOf(b.series)}`} />
+      {/each}
+    {/each}
+
+    <!-- Error bars, on top of the mark they annotate. -->
+    {#each geo.errorBars as eb, ei (ei)}
+      <line class="sv-grid-chart-errorbar" x1={eb.xCenter} y1={eb.yHi} x2={eb.xCenter} y2={eb.yLo} stroke={eb.color} style={`opacity:${dimOf(eb.series)}`} />
+      <line class="sv-grid-chart-errorbar" x1={eb.xCenter - eb.cap} y1={eb.yHi} x2={eb.xCenter + eb.cap} y2={eb.yHi} stroke={eb.color} style={`opacity:${dimOf(eb.series)}`} />
+      <line class="sv-grid-chart-errorbar" x1={eb.xCenter - eb.cap} y1={eb.yLo} x2={eb.xCenter + eb.cap} y2={eb.yLo} stroke={eb.color} style={`opacity:${dimOf(eb.series)}`} />
+    {/each}
+
     {#each geo.scatterPoints as dot, di (di)}
       <!-- svelte-ignore a11y_no_static_element_interactions a11y_mouse_events_have_key_events -->
       <circle
@@ -811,13 +1172,44 @@
       <path class="sv-grid-chart-overlay" d={ovl.path} fill="none" stroke={ovl.color} stroke-width="2" stroke-dasharray="6 4" stroke-linejoin="round" stroke-linecap="round" />
     {/each}
 
+    <!-- Custom-series seam, above the built-in marks. Deliberately BEFORE the
+         crosshair and the hit layer below, so a custom mark cannot swallow the
+         tooltips, the keyboard navigation or the drill clicks. -->
+    {#if overlay}{@render overlay(renderCtx)}{/if}
+
     <!-- Pinned annotations: small marker + label. Placement nudges the
          label position so it sits clear of the data point. -->
     {#each geo.annotations as ann, ai (ann.label + ai)}
       {@const dx = ann.placement === 'left' ? -8 : ann.placement === 'right' ? 8 : 0}
       {@const dy = ann.placement === 'bottom' ? 14 : ann.placement === 'top' ? -8 : 0}
       {@const anchor = ann.placement === 'left' ? 'end' : ann.placement === 'right' ? 'start' : 'middle'}
-      <circle class="sv-grid-chart-annotation-marker" cx={ann.x} cy={ann.y} r="4" fill={ann.color} stroke="var(--sg-bg, #fff)" stroke-width="1.5" />
+      <!-- svelte-ignore a11y_no_static_element_interactions a11y_click_events_have_key_events -->
+      <circle
+        class="sv-grid-chart-annotation-marker"
+        class:is-removable={annotating && !!onAnnotationRemove}
+        cx={ann.x}
+        cy={ann.y}
+        r={annotating && onAnnotationRemove ? 6 : 4}
+        fill={ann.color}
+        stroke="var(--sg-bg, #fff)"
+        stroke-width="1.5"
+        role={annotating && onAnnotationRemove ? 'button' : undefined}
+        tabindex={annotating && onAnnotationRemove ? 0 : undefined}
+        aria-label={annotating && onAnnotationRemove ? `Remove note: ${ann.label}` : undefined}
+        onclick={(e) => {
+          if (!annotating || !onAnnotationRemove) return
+          // Or the same click also pins a NEW note where this one is.
+          e.stopPropagation()
+          onAnnotationRemove(ai)
+        }}
+        onkeydown={(e) => {
+          if (!annotating || !onAnnotationRemove) return
+          if (e.key !== 'Enter' && e.key !== ' ') return
+          e.preventDefault()
+          e.stopPropagation()
+          onAnnotationRemove(ai)
+        }}
+      />
       <text class="sv-grid-chart-annotation-label" x={ann.x + dx} y={ann.y + dy} text-anchor={anchor} fill={ann.color}>{ann.label}</text>
     {/each}
 
@@ -987,9 +1379,12 @@
       {/each}
       <!-- Track (grey full arc) -->
       <path d={g.trackPath} fill="none" stroke="var(--sg-border, #e2e8f0)" stroke-width="16" stroke-linecap="round" />
-      <!-- Optional colored range bands (a thinner inner arc). -->
+      <!-- Range bands: a thin inner reference ring. Deliberately quieter than
+           the value arc - they say what the scale MEANS, while the value arc
+           is what the dial is actually reading. Butt caps so adjacent bands
+           meet cleanly instead of overlapping into each other's colour. -->
       {#each g.rangePaths as band, bi (bi)}
-        <path d={band.path} fill="none" stroke={band.color} stroke-width="6" stroke-linecap="round" opacity="0.85" />
+        <path d={band.path} fill="none" stroke={band.color} stroke-width="4" stroke-linecap="butt" opacity="0.7" />
       {/each}
       <!-- Value arc, colored by the band the value sits in. -->
       <path d={g.valuePath} fill="none" stroke={g.valueColor ?? 'var(--sg-accent, #2563eb)'} stroke-width="16" stroke-linecap="round" />
@@ -998,8 +1393,11 @@
         <line x1={g.target.x1} y1={g.target.y1} x2={g.target.x2} y2={g.target.y2}
           stroke="var(--sg-fg, #0f172a)" stroke-width="2.5" stroke-linecap="round" />
       {/if}
-      <!-- Pointer needle + center hub. -->
-      <path class="sv-grid-chart-gauge-needle" d={g.needle.path} fill={g.valueColor ?? 'var(--sg-accent, #2563eb)'} />
+      <!-- Pointer needle + center hub. Deliberately NOT the value colour: the
+           needle used to be filled with the same colour as the arc it sits on
+           top of, so on a nearly-full dial it disappeared into it. An
+           instrument pointer reads against the face, whatever the face is. -->
+      <path class="sv-grid-chart-gauge-needle" d={g.needle.path} />
       <circle class="sv-grid-chart-gauge-hub" cx={g.cx} cy={g.cy} r={g.needle.hubR} />
       <circle class="sv-grid-chart-gauge-hub-dot" cx={g.cx} cy={g.cy} r="2.5" />
       <!-- Scale end labels + center readout. -->
@@ -1111,6 +1509,34 @@
            Vertical bands centre on the ACTUAL point x (which differs from
            slot math when xType is 'time'); their widths bisect the gap to
            neighbouring points so a mouse over a dot always selects it. -->
+      {#if dense}
+        <!-- One surface instead of n rects. At this density a per-category
+             rect is thinner than the pointer, and each one costs a catRows()
+             call for its aria-label at render time - so 100k categories meant
+             100k tooltip-row computations before anything was even hovered. -->
+        <!-- svelte-ignore a11y_no_static_element_interactions a11y_mouse_events_have_key_events a11y_no_noninteractive_tabindex -->
+        <rect
+          class="sv-grid-chart-cat-hit"
+          x={geo.plot.x}
+          y={geo.plot.y}
+          width={geo.plot.w}
+          height={geo.plot.h}
+          role={onSelect ? 'button' : 'img'}
+          tabindex={interactive ? 0 : undefined}
+          data-cat-index={denseIndex}
+          data-dense="true"
+          aria-label={`${visibleSpec.categories.length} points, ${visibleSpec.categories[0] ?? ''} to ${visibleSpec.categories[visibleSpec.categories.length - 1] ?? ''}. Arrow keys step through values.`}
+          onmousemove={(e) => {
+            const i = catAtClientX(e.clientX, e.currentTarget)
+            if (i != null) { denseIndex = i; hoverCat(e.clientX, e.clientY, i) }
+          }}
+          onmouseleave={clearActive}
+          onfocus={(e) => focusCat(e.currentTarget, denseIndex)}
+          onblur={clearActive}
+          onclick={() => select(visibleSpec.categories[denseIndex] ?? '', '', 0, denseIndex)}
+          onkeydown={onDenseKey}
+        />
+      {:else}
       {#each visibleSpec.categories as cat, i (cat + i)}
         {@const pts = geo.lines[0]?.points}
         {@const px = pts?.[i]?.x}
@@ -1140,6 +1566,7 @@
           onkeydown={(e) => onCatKey(e, i)}
         />
       {/each}
+      {/if}
     {/if}
 
     {#if dragRect}
@@ -1245,14 +1672,21 @@
     </div>
   {/if}
 
-  <!-- Visually-hidden data table: the same data for assistive technology. -->
+  <!-- Visually-hidden data table: the same data for assistive technology.
+       Capped, and the caption says so. A table with 100k rows is not an
+       accessible version of anything - nobody traverses that with a screen
+       reader, and rendering it was a third of the DOM cost of a large chart.
+       Saying "first 1000 of 100000" is more use than silently truncating, and
+       more honest than pretending the whole set is readable here. -->
   <table id={`${uid}-table`} class="sv-grid-chart-sr-only">
-    <caption>{spec.type} chart data</caption>
+    <caption>
+      {spec.type} chart data{#if srCapped}, first {SR_ROW_CAP} of {srTable.rows.length} rows{/if}
+    </caption>
     <thead>
       <tr>{#each srTable.cols as c (c)}<th>{c}</th>{/each}</tr>
     </thead>
     <tbody>
-      {#each srTable.rows as row, ri (ri)}
+      {#each srRows as row, ri (ri)}
         <tr>{#each row as cell, ci (ci)}<td>{cell}</td>{/each}</tr>
       {/each}
     </tbody>
@@ -1427,6 +1861,10 @@
   }
   /* Pointer needle + hub. */
   .sv-grid-chart-gauge-needle {
+    fill: var(--sg-fg, #0f172a);
+    /* A hairline of the background colour around the needle keeps it legible
+       where it crosses the value arc, which is the same weight and often a
+       similar tone. */
     stroke: var(--sg-bg, #ffffff);
     stroke-width: 0.75;
     stroke-linejoin: round;
@@ -1550,6 +1988,33 @@
   .sv-grid-chart-dot {
     transition: cx 0.3s ease, cy 0.3s ease;
   }
+  .sv-grid-chart-candle {
+    stroke-width: 1;
+    transition: x 0.3s ease, y 0.3s ease, width 0.3s ease, height 0.3s ease;
+  }
+  .sv-grid-chart-wick,
+  .sv-grid-chart-ohlc {
+    stroke-width: 1;
+    shape-rendering: crispEdges;
+  }
+  .sv-grid-chart-box {
+    stroke-width: 1;
+    transition: x 0.3s ease, y 0.3s ease, width 0.3s ease, height 0.3s ease;
+  }
+  .sv-grid-chart-whisker,
+  .sv-grid-chart-errorbar {
+    stroke-width: 1;
+    shape-rendering: crispEdges;
+  }
+  /* The median is the number people read off a box plot, so it gets the
+     weight. Everything else on the mark is 1px. */
+  .sv-grid-chart-median {
+    stroke-width: 2;
+    shape-rendering: crispEdges;
+  }
+  .sv-grid-chart-outlier {
+    stroke-width: 1;
+  }
   .is-clickable .sv-grid-chart-cat-hit,
   .is-clickable .sv-grid-chart-slice {
     cursor: pointer;
@@ -1592,6 +2057,16 @@
     border-color: var(--sg-accent, #2563eb);
   }
 
+  /* Annotate mode: the toggle reads as pressed, the plot as a target, and a
+     marker as something you can click to take away. */
+  .sv-grid-chart-tool.is-on {
+    background: var(--sg-accent, #2563eb);
+    border-color: var(--sg-accent, #2563eb);
+    color: var(--sg-on-accent, #fff);
+  }
+  .sv-grid-chart-svg.is-annotating { cursor: copy; }
+  .sv-grid-chart-annotation-marker.is-removable { cursor: pointer; }
+
   /* Drag-to-zoom: translucent accent rectangle over the plot. */
   .sv-grid-chart-svg.is-zoomable { cursor: crosshair; }
   .sv-grid-chart-svg.is-dragging { cursor: crosshair; user-select: none; }
@@ -1713,4 +2188,59 @@
     display: inline-block;
     box-sizing: border-box;
   }
+
+  /* Enter animation. Marks fade in when they are first created; the position
+     transitions above then handle everything after that, so a chart appears
+     smoothly and moves smoothly rather than popping into place and then
+     animating.
+
+     A fade rather than the wipe you would normally reach for. A wipe needs a
+     clip-path over all the marks, and the marks here are direct children of the
+     <svg> - grouping them is a large edit across every chart type, for a nicer
+     version of something already pleasant. Noted rather than done.
+
+     `both` matters: it holds the from-state before the animation starts, so a
+     mark cannot flash at full opacity for a frame first. It also means that
+     when `animation: none` applies below, the rule stops applying entirely and
+     the mark is simply painted - not stuck invisible. */
+  @keyframes sv-grid-chart-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  .sv-grid-chart-bar,
+  .sv-grid-chart-linepath,
+  .sv-grid-chart-area,
+  .sv-grid-chart-slice,
+  .sv-grid-chart-candle,
+  .sv-grid-chart-box,
+  .sv-grid-chart-funnel-seg,
+  .sv-grid-chart-heatcell,
+  .sv-grid-chart-treemap-cell {
+    animation: sv-grid-chart-in 0.3s ease-out both;
+  }
+
+  /* Reduced motion. Every other animated component in the kit honours this
+     (SvCard, SvCircularProgress, SvCollapsible); the chart never did, so a
+     reader who has asked the OS for less movement still got every bar, dot,
+     candle and box sliding on each re-aggregation - and a chart re-aggregates
+     on every filter keystroke, which is the worst case for it. */
+  @media (prefers-reduced-motion: reduce) {
+    .sv-grid-chart-bar,
+    .sv-grid-chart-dot,
+    .sv-grid-chart-candle,
+    .sv-grid-chart-box {
+      transition: none;
+    }
+    .sv-grid-chart-bar,
+    .sv-grid-chart-linepath,
+    .sv-grid-chart-area,
+    .sv-grid-chart-slice,
+    .sv-grid-chart-candle,
+    .sv-grid-chart-box,
+    .sv-grid-chart-funnel-seg,
+    .sv-grid-chart-heatcell,
+    .sv-grid-chart-treemap-cell {
+      animation: none;
+    }
+  }
 </style>