basalt-ui 1.15.0 → 1.16.0

package/src/charts/primitives/XZoneRects.tsx

@@ -13,6 +13,50 @@ export type XZoneSpec = {
   /** Right edge — a domain key produced by the kind's `getX`. Omit for "end of the plot area". */
   to?: string
   fill: string
+  /**
+   * `'center'` (default, unchanged behaviour) resolves a present bound to `xScale(key)` — the
+   * point's own center, so a band reads "from this sample to that sample" rather than
+   * edge-to-edge. `'edge'` resolves a present `from` to `xScale(from) - step/2` and a present `to`
+   * to `xScale(to) + step/2` (`step` read from `xScale.step()`), so the band covers both terminal
+   * slots in full — a two-key band widens by exactly one step, and `from === to` renders one step
+   * wide instead of being skipped as degenerate. An omitted `from`/`to` still resolves to the plot
+   * edge (`xScale.range()[0]`/`[1]`) in both modes, unshifted — omission means "the plot's own
+   * edge", not "the first/last sample's edge". A resolved `'edge'` bound is clamped into the plot
+   * range so a band anchored at the first or last sample cannot paint outside the plot area.
+   */
+  align?: 'center' | 'edge'
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Resolves one zone bound (`from` or `to`) to a pixel x. `edgeSign` is `-1` for `from` (subtract
+ * half a step) and `+1` for `to` (add half a step) — only consulted in `'edge'` mode.
+ */
+function resolveBound({
+  key,
+  omittedEdge,
+  xScale,
+  align,
+  edgeSign,
+  rangeMin,
+  rangeMax,
+}: {
+  key: string | undefined
+  omittedEdge: number
+  xScale: PointScale
+  align: 'center' | 'edge'
+  edgeSign: -1 | 1
+  rangeMin: number
+  rangeMax: number
+}): number | undefined {
+  if (key === undefined) return omittedEdge
+  const center = xScale(key)
+  if (center === undefined) return undefined
+  if (align === 'center') return center
+  return clamp(center + edgeSign * (xScale.step() / 2), rangeMin, rangeMax)
 }
 
 /**
@@ -20,18 +64,20 @@ export type XZoneSpec = {
  * <rect> per zone, spanning y=[0, height] and x=[scale(from), scale(to)]. The x analog of
  * `ZoneRects`, for a `scalePoint` x-axis instead of a `scaleLinear` y-axis.
  *
- * An omitted `from` resolves to `0` (start of the plot area); an omitted `to` resolves to
- * `xScale.range()[1]` (the plot's right edge). A present key resolves to `xScale(key)` — the
- * POINT CENTER, so a band reads as "from this sample to that sample", not edge-to-edge.
+ * Bound resolution depends on `XZoneSpec.align` (see its JSDoc for the full `'center'`/`'edge'`
+ * contract) — default `'center'` resolves a present key to the point's own center; `'edge'`
+ * widens by half a step at each present bound so the band covers the terminal slots in full.
  *
  * A key that is not in the scale's domain skips that band entirely (renders nothing for it) —
- * it is NEVER clamped to a plot edge. Clamping would silently paint a band across the whole
- * chart for a typo'd or stale key, which is the exact class of quiet lie the repo's "nothing to
- * draw is two different states" doctrine rejects: an unknown key must read as "not drawn", not
- * as "the whole plot".
+ * it is NEVER clamped to a plot edge, in either mode. Clamping an unknown key would silently
+ * paint a band across the whole chart for a typo'd or stale key, which is the exact class of
+ * quiet lie the repo's "nothing to draw is two different states" doctrine rejects: an unknown key
+ * must read as "not drawn", not as "the whole plot".
  *
  * A degenerate resolved range (right edge <= left edge, e.g. an inverted `from`/`to` pair) is
- * also skipped — no negative-width rect.
+ * also skipped — no negative-width rect. In `'center'` mode `from === to` is degenerate (skipped,
+ * today's behaviour); in `'edge'` mode it is NOT — the half-step widening on each side always
+ * produces a positive-width, one-step-wide rect.
  */
 export function XZoneRects({
   zones,
@@ -47,8 +93,27 @@ export function XZoneRects({
     <>
       {zones.map((z, i) => {
         const [rangeStart, rangeEnd] = xScale.range() as [number, number]
-        const xFrom = z.from === undefined ? rangeStart : xScale(z.from)
-        const xTo = z.to === undefined ? rangeEnd : xScale(z.to)
+        const rangeMin = Math.min(rangeStart, rangeEnd)
+        const rangeMax = Math.max(rangeStart, rangeEnd)
+        const align = z.align ?? 'center'
+        const xFrom = resolveBound({
+          key: z.from,
+          omittedEdge: rangeStart,
+          xScale,
+          align,
+          edgeSign: -1,
+          rangeMin,
+          rangeMax,
+        })
+        const xTo = resolveBound({
+          key: z.to,
+          omittedEdge: rangeEnd,
+          xScale,
+          align,
+          edgeSign: 1,
+          rangeMin,
+          rangeMax,
+        })
         if (xFrom === undefined || xTo === undefined) return null
         if (xTo <= xFrom) return null
         return (

package/src/charts/series.test.ts

@@ -58,4 +58,55 @@ describe('deriveTooltipRows', () => {
     )
     expect(rows[0]?.value).toBe('42%')
   })
+
+  test('formatValue receives the hovered datum alongside the value', () => {
+    type Set = { v: number; reps: number }
+    const rows = deriveTooltipRows(
+      [
+        {
+          key: 'set',
+          label: 'Set',
+          color: '#000',
+          mark: 'bar' as const,
+          getValue: (d: Set) => d.v,
+          formatValue: (v: number, d: Set) => `${v} kg (${d.reps} reps)`,
+        },
+      ],
+      { v: 97.5, reps: 3 },
+      fmt,
+    )
+    expect(rows[0]?.value).toBe('97.5 kg (3 reps)')
+  })
+
+  test('the fallback formatter (single-arg) still works once formatValue is 2-arg typed', () => {
+    const rows = deriveTooltipRows([{ ...base, key: 'a', label: 'A' }], { v: 5 }, fmt)
+    expect(rows[0]?.value).toBe('5')
+  })
+})
+
+describe('strokeOpacity — a mark property, not a tooltip property', () => {
+  test('reaches the derived legend entry', () => {
+    const [entry] = deriveLegend([{ ...baseSeries, strokeOpacity: 0.4 }])
+    expect(entry?.strokeOpacity).toBe(0.4)
+  })
+
+  test('is absent from the legend entry when unset', () => {
+    const [entry] = deriveLegend([baseSeries])
+    expect(entry).not.toHaveProperty('strokeOpacity')
+  })
+
+  test('never reaches TooltipRowData — the row is a 12px value chip, not a dimmed mark', () => {
+    const rows = deriveTooltipRows(
+      [
+        {
+          ...baseSeries,
+          strokeOpacity: 0.4,
+          getValue: () => 10,
+        },
+      ],
+      {},
+      (v) => String(v),
+    )
+    expect(rows[0]).not.toHaveProperty('strokeOpacity')
+  })
 })

package/src/charts/series.ts

@@ -60,6 +60,14 @@ export type SeriesStyle = {
   strokeWidth?: number
   /** bar/area: the swatch honors this so it cannot lie. */
   fillOpacity?: number
+  /**
+   * A MARK property — dims the plotted stroke, e.g. a faint moving-average companion line. The
+   * legend swatch honors it too (parity with `fillOpacity`, which it already honors — a swatch
+   * that lies is the thing the derived-legend rule exists to prevent). The TOOLTIP ROW swatch and
+   * the CROSSHAIR DOT deliberately do NOT honor it: those are 12px value-readout chips where a
+   * sub-1 opacity reads as a rendering bug, not as data.
+   */
+  strokeOpacity?: number
   /** Which y-axis this series is measured against. Default 'left'. `'right'` is what makes a
    * chart dual-axis — `CartesianChart` reads it for the crosshair dots and the tooltip. */
   axis?: 'left' | 'right'
@@ -84,8 +92,10 @@ export type SeriesStyle = {
 export type ChartSeries<T> = SeriesStyle & {
   /** null = line gap + skipped tooltip row. */
   getValue: (d: T) => number | null
-  /** Per-series override of the shared tooltip/value formatter. */
-  formatValue?: (v: number) => string
+  /** Per-series override of the shared tooltip/value formatter. Receives the hovered datum
+   * alongside the value so a row can read fields beyond the plotted number (e.g. `97.5 kg (92.5 ×
+   * 3)`). */
+  formatValue?: (v: number, d: T) => string
   /** PR star / status dot. Return null for no marker at that point. */
   getMarker?: (d: T) => { color?: string; r?: number } | null
 }
@@ -112,6 +122,7 @@ function legendEntryFor(s: SeriesStyle): LegendEntry {
     dashed: s.dash === 'dashed',
     ...(s.strokeWidth !== undefined && { strokeWidth: s.strokeWidth }),
     ...(s.fillOpacity !== undefined && { fillOpacity: s.fillOpacity }),
+    ...(s.strokeOpacity !== undefined && { strokeOpacity: s.strokeOpacity }),
     ...(s.role !== undefined && { role: s.role }),
     ...(s.note !== undefined && { note: s.note }),
   }
@@ -165,12 +176,12 @@ export function deriveTooltipRows<T>(
     if (s.tooltip === false) continue
     const value = s.getValue(datum)
     if (value === null) continue
-    const format = s.formatValue ?? fallbackFormat
+    const format: (v: number, d: T) => string = s.formatValue ?? fallbackFormat
     rows.push({
       key: s.key,
       label: s.label,
       color: s.color,
-      value: format(value),
+      value: format(value, datum),
       shape: shapeFor(s.mark),
       dashed: s.dash === 'dashed',
       ...(s.strokeWidth !== undefined && { strokeWidth: s.strokeWidth }),