basalt-ui 2.3.0 → 2.4.0

package/src/charts/panel.tsx

@@ -21,7 +21,7 @@ import { useCallback } from 'react'
 import type { ReactElement } from 'react'
 import { ChartShell } from './CartesianChart'
 import type { ChartShellProps, ShellContext } from './CartesianChart'
-import { defaultFormatX, utcHeaderDate, visibleSeries, xGuide, yGuide } from './compile'
+import { defaultFormatX, engineRow, utcHeaderDate, visibleSeries, xGuide, yGuide } from './compile'
 import type { CartesianDefinition } from './compile'
 import { cursorBinding, sourceOnlyFocus } from './cursor'
 import type { XScaleModel } from './scales'
@@ -205,7 +205,7 @@ function panelDefinition<T, X extends ChartX>(
               const { x, d } = sourceOf<T>(primary, owned)
               const extra: readonly ChartTooltipRow[] =
                 tooltip?.rows?.(d, { visible, hidden: hiddenSeries }) ?? []
-              return { title: header(x, d), rows: [...plan.rows(d), ...extra] }
+              return { title: header(x, d), rows: [...plan.rows(d), ...extra.map(engineRow)] }
             },
           },
   }

package/src/charts/types.ts

@@ -31,6 +31,13 @@ export type ChartSeries<T> = {
    * tier, a config value) is a step: a smoothed curve draws values that never existed. */
   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 | undefined
   /** Bars and areas. */
@@ -53,6 +60,12 @@ export type ChartSeries<T> = {
   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) | 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) => {
@@ -95,12 +108,24 @@ export type AxisConfig<T> = {
   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. */
 export type ZoneSpec = {
   from: number
   to: number
   fill: string
   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
 }
 
 /**
@@ -113,6 +138,8 @@ export type XZoneSpec<X extends ChartX = ChartX> = {
   to?: X | undefined
   fill: string
   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. */
@@ -121,6 +148,13 @@ export type RefLine = {
   color: string
   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. */
@@ -138,7 +172,9 @@ 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> = {

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]
     >
   }