basalt-ui 2.2.0 → 2.4.0

package/src/charts/types.ts

@@ -24,35 +24,57 @@ export type ChartSeries<T> = {
    * series whose `getValue` is always `null` is a legend-only entry (a zone or reference key). */
   getValue: (d: T) => number | null
   /** The legend swatch shape. Default: the kind's own mark (`line` in `Lines`, `bar` in `Bars`). */
-  mark?: 'line' | 'bar' | 'area'
+  mark?: 'line' | 'bar' | 'area' | undefined
   /** Default `'solid'`; `'dashed'` is `VX.dashArray` on the line, the legend and the tooltip. */
-  dash?: 'solid' | 'dashed'
+  dash?: 'solid' | 'dashed' | undefined
   /** Interpolation between points. Default `'monotone'`. A piecewise-constant quantity (a price
    * tier, a config value) is a step: a smoothed curve draws values that never existed. */
-  curve?: CurveName
-  strokeWidth?: number
+  curve?: CurveName | undefined
+  strokeWidth?: number | undefined
+  /**
+   * What a `null` value does to the line (and its `area`). `'break'` (default) leaves a gap;
+   * `'connect'` draws through the series' non-null points only, skipping the null rows, so a series
+   * that is null on most shared x values (one lift in a wide table) is one continuous line. Points,
+   * markers, the cursor and the tooltip still read real values: a null row has no tooltip row.
+   */
+  gaps?: 'break' | 'connect' | undefined
   /** Dims the plotted stroke (a faint companion line). Strokes only. */
-  strokeOpacity?: number
+  strokeOpacity?: number | undefined
   /** Bars and areas. */
-  fillOpacity?: number
-  /** `Lines`: a soft gradient fill under the line — `true` in the series color, or a color ref. */
-  area?: boolean | string
+  fillOpacity?: number | undefined
+  /** `Lines`: a soft gradient fill under the line — `true` in the series color, a color ref, or
+   * `'zones'`: a vertical gradient coloured by the chart's `zones` on this series' axis, hard stops
+   * at the zone boundaries (no zone in reach: the series color). Linear axes only. */
+  area?: boolean | 'zones' | (string & {}) | undefined
   /** Which y axis the series is measured against. `'right'` needs the chart's `y2`. */
-  axis?: 'left' | 'right'
+  axis?: 'left' | 'right' | undefined
   /** Legend grouping: series → overlay → reference. Default `'series'`. */
-  role?: 'series' | 'overlay' | 'reference'
+  role?: 'series' | 'overlay' | 'reference' | undefined
   /** `false` keeps it out of the legend (a companion line folded under `parent`). Default `true`. */
-  legend?: boolean
+  legend?: boolean | undefined
   /** `false` draws and legends it but never lists it as a tooltip row. Default `true`. */
-  tooltip?: boolean
+  tooltip?: boolean | undefined
   /** A companion (an MA line) names its parent, so a legend toggle and hover keep the pair. */
-  parent?: string
+  parent?: string | undefined
   /** A short qualifier after the label in the legend and the tooltip row, in muted text. */
-  note?: string
+  note?: string | undefined
   /** Per-series tooltip value format; receives the datum so a row can read more than the value. */
-  formatValue?: (v: number, d: T) => string
+  formatValue?: ((v: number, d: T) => string) | undefined
+  /**
+   * A cursor dot for a series whose mark the consumer draws itself (`marks`, so `getValue` stays
+   * `null`): the y of the dot at each datum, `null` for none. The dot shows while the cursor is on
+   * that datum's x and takes the series color. A series drawn from `plot.rows` already has one.
+   */
+  cursorValue?: ((d: T) => number | null) | undefined
   /** A marker at a point (a PR star, a status dot); `null` for none. */
-  getMarker?: (d: T) => { color?: string; r?: number; fillOpacity?: number; ring?: boolean } | null
+  getMarker?:
+    | ((d: T) => {
+        color?: string | undefined
+        r?: number | undefined
+        fillOpacity?: number | undefined
+        ring?: boolean | undefined
+      } | null)
+    | undefined
 }
 
 /** One y axis. */
@@ -66,23 +88,33 @@ export type AxisConfig<T> = {
     | readonly [number, number]
     | 'auto'
     | ((data: readonly T[], visible: readonly ChartSeries<T>[]) => readonly [number, number])
+    | undefined
   /** When `'auto'`: the raw upper bound is at least this; padding applies after. */
-  autoMaxFloor?: number
+  autoMaxFloor?: number | undefined
   /** When `'auto'`: the lower bound is at most this. Default `0` (a zero baseline); `Infinity` pads
    * down from the data minimum instead. Ignored on a log axis. */
-  autoMinCeil?: number
+  autoMinCeil?: number | undefined
   /** When `'auto'`: padding multiplier away from the data. Default `1.1`. */
-  autoPad?: number
+  autoPad?: number | undefined
   /** A tick count, or the exact tick values. Default: one per ~48px of plot height, ≤ 5. */
-  ticks?: number | readonly number[]
+  ticks?: number | readonly number[] | undefined
   /** Tick and tooltip formatter. Default: compact numbers (`12.5k`). */
-  format?: (v: number) => string
+  format?: ((v: number) => string) | undefined
   /** Horizontal grid rules. Default: on for `y`, off for `y2`. */
-  grid?: boolean
+  grid?: boolean | undefined
   /** Round the domain outward to nice ticks. Default `false` (a fixed domain stays fixed). */
-  nice?: boolean
+  nice?: boolean | undefined
   /** Default `'linear'`. A log axis floors at the smallest positive visible value. */
-  scale?: 'linear' | 'log'
+  scale?: 'linear' | 'log' | undefined
+}
+
+/** A rule along a band's boundary, painted with the band. A bound at the plot edge draws none. */
+export type ZoneEdge<S extends string> = {
+  side: S | 'both'
+  color: string
+  dashed?: boolean | undefined
+  /** Default `1`. */
+  width?: number | undefined
 }
 
 /** A horizontal band on one y axis. `±Infinity` reaches the plot edge. */
@@ -90,7 +122,10 @@ export type ZoneSpec = {
   from: number
   to: number
   fill: string
-  axisSide?: 'left' | 'right'
+  axisSide?: 'left' | 'right' | undefined
+  /** A rule on the band's visual `top` (the larger bound) and/or `bottom` (the smaller), whichever
+   * of `from`/`to` that is. */
+  edge?: ZoneEdge<'top' | 'bottom'> | undefined
 }
 
 /**
@@ -99,18 +134,27 @@ export type ZoneSpec = {
  * from one hour to another, both hours included).
  */
 export type XZoneSpec<X extends ChartX = ChartX> = {
-  from?: X
-  to?: X
+  from?: X | undefined
+  to?: X | undefined
   fill: string
-  align?: 'center' | 'edge'
+  align?: 'center' | 'edge' | undefined
+  /** A rule on the band's `start` (`from`) and/or `end` (`to`) boundary; an omitted bound has none. */
+  edge?: ZoneEdge<'start' | 'end'> | undefined
 }
 
 /** A horizontal reference line — annotation only, no domain role beyond staying inside the plot. */
 export type RefLine = {
   value: number
   color: string
-  dashed?: boolean
-  axis?: 'left' | 'right'
+  dashed?: boolean | undefined
+  axis?: 'left' | 'right' | undefined
+  /**
+   * Names the line in the legend (its color, dashed as `dashed`; a toggle hides the line), so a
+   * threshold needs no always-`null` series. `mark` is the swatch shape. Default `'line'`. The
+   * toggle state is keyed by the line's index in `refLines`: reordering the array while a line is
+   * toggled off moves the "off" to whichever line now sits at that index.
+   */
+  legend?: { label: string; mark?: 'line' | 'bar' | undefined } | undefined
 }
 
 /** A fill between the line and a value, on one side of it, tracking the line. */
@@ -128,50 +172,54 @@ export type ChartTooltipRow = {
   label: string
   value: string
   /** The row swatch; omitted, the row has none. */
-  color?: string
+  color?: string | undefined
+  /** The swatch shape; `'dashed'` for a reference or dashed series. Default `'solid'`. */
+  swatch?: 'solid' | 'dashed' | undefined
 }
 
 export type ChartTooltipConfig<T, X extends ChartX = ChartX> = {
   /** The tooltip title. Default: the x value through `formatX`'s long form (a date reads
    * `Mon Sep 1 2026`). */
-  formatHeader?: (x: X, d: T) => string
+  formatHeader?: ((x: X, d: T) => string) | undefined
   /** Rows after the per-series rows (a total, a zone badge, a context line). `visible`/`hidden` are
    * the legend's split, so a row never names a series the plot no longer draws. */
-  rows?: (
-    d: T,
-    ctx: { visible: readonly ChartSeries<T>[]; hidden: readonly ChartSeries<T>[] },
-  ) => readonly ChartTooltipRow[]
+  rows?:
+    | ((
+        d: T,
+        ctx: { visible: readonly ChartSeries<T>[]; hidden: readonly ChartSeries<T>[] },
+      ) => readonly ChartTooltipRow[])
+    | undefined
   /** Show this chart's tooltip while it FOLLOWS a sibling's cursor. Default `false`: only the chart
    * under the pointer or keyboard focus shows a tooltip and a live region. */
-  onFollow?: boolean
+  onFollow?: boolean | undefined
 }
 
 export type ChartLegendConfig = {
   /** Default `'bottom'`. `'header'` draws the legend at the top of the chart body, spaced as the
    * enclosing `ChartCard`'s header legend row (in the chart's own markup, so it is in the server
    * HTML and the header never grows); outside a card it is `'top'`. */
-  placement?: 'top' | 'bottom' | 'header'
+  placement?: 'top' | 'bottom' | 'header' | undefined
   /** Visually separate roles: series | overlay | reference. */
-  groups?: boolean
+  groups?: boolean | undefined
   /** Clicking an entry hides that series. Default: on whenever there are two or more entries. */
-  toggle?: boolean
+  toggle?: boolean | undefined
 }
 
 /** A height per container class, `base` below `regular`. A plain number is fixed. */
 export type ResponsiveChartHeight = {
   base: number
-  regular?: number
-  wide?: number
+  regular?: number | undefined
+  wide?: number | undefined
 }
 
 /** The three "nothing to draw" states, pending → error → empty. */
 export type ChartState = {
-  pending?: boolean
+  pending?: boolean | undefined
   /** Truthy = the query failed; an `Error`'s message is the label. */
   error?: unknown
   /** `true`, or the empty label itself. The label is the one way to say WHY (`'No runs match the
    * filter'` vs `'No runs yet'`): § 9 fixes the state shape, so there is no reason field. */
-  empty?: boolean | string
+  empty?: boolean | string | undefined
 }
 
 /** A row of `plot.rows(key)`: one per datum, `y: null` kept as a gap. */
@@ -215,27 +263,27 @@ export type CartesianChartProps<T, X extends ChartX = ChartX> = BasaltProps & {
   series: readonly ChartSeries<T>[]
   /** The plot's marks. Draw `plot.rows(key)` / `plot.visible`, never `series` directly. */
   marks: (plot: PlotContext<T, X>) => ChartMarks
-  y?: AxisConfig<T>
+  y?: AxisConfig<T> | undefined
   /** A right axis; series with `axis: 'right'` and marks bound to `plot.y2` read it. */
-  y2?: AxisConfig<T>
+  y2?: AxisConfig<T> | undefined
   /** A tick count, or the exact x tick values. Default: by container class. */
-  xTicks?: number | readonly X[]
+  xTicks?: number | readonly X[] | undefined
   /** Tick label for an x value. Default: `DD.MM` for dates, compact numbers, strings verbatim. */
-  formatX?: (x: X) => string
-  zones?: readonly ZoneSpec[]
-  xZones?: readonly XZoneSpec<X>[]
-  refLines?: readonly RefLine[]
+  formatX?: ((x: X) => string) | undefined
+  zones?: readonly ZoneSpec[] | undefined
+  xZones?: readonly XZoneSpec<X>[] | undefined
+  refLines?: readonly RefLine[] | undefined
   /** `false` hides the legend. */
-  legend?: ChartLegendConfig | false
+  legend?: ChartLegendConfig | false | undefined
   /** Default: the height law (measured width × class ratio, 160–420px, ≤ 45vh on touch). */
-  height?: number | ResponsiveChartHeight
-  state?: ChartState
+  height?: number | ResponsiveChartHeight | undefined
+  state?: ChartState | undefined
   /** Joins a named cursor group instead of the page-shared default. */
-  cursorGroup?: string
+  cursorGroup?: string | undefined
   /** Default `'nearest'`. `'leading'` for a series keyed by a bucket's leading edge (a weekly
    * value keyed by its Monday). */
-  cursorResolution?: CursorResolution
-  tooltip?: ChartTooltipConfig<T, X> | false
+  cursorResolution?: CursorResolution | undefined
+  tooltip?: ChartTooltipConfig<T, X> | false | undefined
 }
 
 /** The x channel of a `plot.rows()` row, as an accessor (a field name does not type-check against a

package/src/state/fields.ts

@@ -279,6 +279,24 @@ type NumberHandleExtras<F> = F extends { kind: 'number' }
       readonly step?: undefined
     }
 
+/**
+ * `createLocalStore`'s `use()` read options. `fallback` is a CALL-SITE default for a value that
+ * arrives as a prop (a leader, a latest date): it applies only while the field is unset (nothing
+ * stored), is applied in render AFTER the store read, and is never persisted — `clear()` unsets
+ * back to it. `handle.fallback` and `isDefault` still report the definition's.
+ *
+ * An object fallback (range, multi) must be memoised by the caller: the value returned while unset
+ * IS that object, so a fresh literal per render changes identity every render.
+ */
+export type FieldReadOptions<F extends AnyField> = { fallback?: FieldValue<F> }
+
+/** A `createLocalStore` field: the shared handle, plus `use({ fallback })`. */
+export type LocalFieldHandle<F extends AnyField> = FieldHandle<F> & {
+  use(
+    read?: FieldReadOptions<F>,
+  ): readonly [FieldValue<F>, (next: FieldValue<F>, opts?: FieldSetOptions) => void]
+}
+
 /**
  * The binding every basalt control takes instead of `value`/`onChange` (C2). One field, both lanes,
  * one resolution law. Handed out by `createSearchStore().field.<name>` /
@@ -771,7 +789,7 @@ type StoreRecord = Record<string, unknown>
 export type FieldWrite = (next: unknown, opts?: FieldSetOptions) => void
 
 /** One field's `use()`, untyped. @internal — see `FieldCodec`. */
-export type FieldUse = () => readonly [unknown, FieldWrite]
+export type FieldUse = (read?: FieldReadOptions<AnyField>) => readonly [unknown, FieldWrite]
 
 /** One named field plus its codec, in declaration order. @internal — see `FieldCodec`. */
 export type StoreEntry = { readonly name: string; readonly codec: FieldCodec }
@@ -798,7 +816,12 @@ export type StoreCore = {
   setLabels(map: Record<string, Record<string, string> | undefined>): void
   optionsFor(entry: StoreEntry): readonly FieldOption[]
   /** The resolution law, once: URL ⊳ localStorage ⊳ fallback. `search: null` skips the URL lane. */
-  resolve(entry: StoreEntry, search: StoreRecord | null, record: StoreRecord): unknown
+  resolve(
+    entry: StoreEntry,
+    search: StoreRecord | null,
+    record: StoreRecord,
+    fallback?: unknown,
+  ): unknown
   writeField(setRecord: (next: StoreRecord) => void, name: string, value: unknown): void
   /**
    * The IN-MEMORY lane's `use()` for one field — a field with neither the URL nor the mirror.
@@ -841,14 +864,19 @@ function assignDefined(into: StoreRecord, from: StoreRecord): void {
  * The resolution law, in one place: URL ⊳ localStorage ⊳ fallback (C4). `search: null` skips the
  * URL lane — what the local lane and `linkSearch` pass.
  */
-function resolveField(entry: StoreEntry, search: StoreRecord | null, record: StoreRecord): unknown {
+function resolveField(
+  entry: StoreEntry,
+  search: StoreRecord | null,
+  record: StoreRecord,
+  fallback?: unknown,
+): unknown {
   const fromUrl = search === null ? null : entry.codec.fromSearch(search)
   if (fromUrl !== null) return fromUrl
   if (entry.codec.lane.persist) {
     const stored = entry.codec.decode(record[entry.name])
     if (stored !== null) return stored
   }
-  return entry.codec.fallback
+  return fallback === undefined ? entry.codec.fallback : fallback
 }
 
 /**
@@ -865,7 +893,7 @@ function resolveField(entry: StoreEntry, search: StoreRecord | null, record: Sto
 function createMemoryLane(): {
   subscribe: (cb: () => void) => () => void
   getVersion: () => number
-  resolve: (entry: StoreEntry) => unknown
+  resolve: (entry: StoreEntry, fallback?: unknown) => unknown
   write: (name: string, value: unknown) => void
   remove: (name: string) => void
   clear: () => void
@@ -889,9 +917,10 @@ function createMemoryLane(): {
     getVersion: () => version,
     // `undefined` is the only "never written" marker the lane needs: no field kind has `undefined`
     // as a legal value, so it can never collide with a written one.
-    resolve: (entry) => {
+    resolve: (entry, fallback) => {
       const stored = values.get(entry.name)
-      return stored === undefined ? entry.codec.fallback : stored
+      if (stored !== undefined) return stored
+      return fallback === undefined ? entry.codec.fallback : fallback
     },
     write: (name, value) => {
       values.set(name, value)
@@ -1036,11 +1065,14 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
     },
     readRecord,
     memoryUse(entry) {
-      return () => {
+      return (read) => {
         // Subscribing to the VERSION (never to the value) is what re-renders every other mount of
         // this field when one of them writes, with no snapshot-stability trap.
         useSyncExternalStore(memory.subscribe, memory.getVersion, memory.getVersion)
-        return [memory.resolve(entry), (next: unknown) => memory.write(entry.name, next)] as const
+        return [
+          memory.resolve(entry, read?.fallback),
+          (next: unknown) => memory.write(entry.name, next),
+        ] as const
       }
     },
     readMemoryValue: (entry) => memory.resolve(entry),
@@ -1074,7 +1106,7 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
 
 /** `Pick<SearchStore<S>, 'field' | 'readStored' | 'labels'>` — the same handles, no router. */
 export type LocalStore<S extends Record<string, AnyField>> = {
-  readonly field: { [K in keyof S]: FieldHandle<S[K]> }
+  readonly field: { [K in keyof S]: LocalFieldHandle<S[K]> }
   readStored: () => Partial<StoredValues<S>>
   /**
    * Option labels for enum / multi / range fields — the same chainable contract
@@ -1116,20 +1148,24 @@ export function createLocalStore<const S extends Record<string, AnyField>>(o: {
 }): LocalStore<S> {
   const core = createStoreCore({ key: o.key, fields: o.fields, version: o.version })
 
-  const persistedUse = (entry: StoreEntry) => (): readonly [unknown, (next: unknown) => void] => {
-    const [record, setRecord] = core.usePersistedRecord()
-    return [
-      core.resolve(entry, null, record),
-      (next: unknown) => core.writeField(setRecord, entry.name, next),
-    ] as const
-  }
+  const persistedUse =
+    (entry: StoreEntry): FieldUse =>
+    (read) => {
+      const [record, setRecord] = core.usePersistedRecord()
+      return [
+        // The call-site fallback is applied here, in render, after the store read — never inside
+        // the snapshot — so React's out-of-render snapshot reads cannot disagree with it.
+        core.resolve(entry, null, record, read?.fallback),
+        (next: unknown) => core.writeField(setRecord, entry.name, next),
+      ] as const
+    }
 
-  const field = {} as { [K in keyof S]: FieldHandle<S[K]> }
+  const field = {} as { [K in keyof S]: LocalFieldHandle<S[K]> }
   for (const entry of core.entries) {
     const persisted = entry.codec.lane.persist
     const use = persisted ? persistedUse(entry) : core.memoryUse(entry)
     const clear = persisted ? () => core.clearField(entry.name) : () => core.clearMemory(entry.name)
-    field[entry.name as keyof S] = core.handle(entry, use, clear) as unknown as FieldHandle<
+    field[entry.name as keyof S] = core.handle(entry, use, clear) as unknown as LocalFieldHandle<
       S[keyof S]
     >
   }