basalt-ui 2.4.0 → 2.6.0

package/src/charts/panel.tsx

@@ -83,12 +83,15 @@ export const paneY = (opts: {
   format: (v: number) => string
   ticks: number
   cls: ContainerClass
+  /** The whole chart's height ({@link chartHeightOf}). */
+  height: number
 }): StoredChartSpec['scales'][string] => ({
   scale: opts.scale,
   ...yGuide({
     cfg: { ticks: opts.ticks },
     axis: { domain: opts.domain, format: opts.format },
     cls: opts.cls,
+    height: opts.height,
     side: 'left',
     grid: true,
   }),
@@ -102,11 +105,23 @@ export const paneX = <X extends ChartX>(opts: {
   model: XScaleModel<X>
   format: (v: ChartValue) => string
   cls: ContainerClass
+  /** The whole chart's height ({@link chartHeightOf}). */
+  height: number
 }): StoredChartSpec['scales'][string] => ({
   scale: opts.scale,
-  ...xGuide({ model: opts.model, xTicks: undefined, format: opts.format, cls: opts.cls }),
+  ...xGuide({
+    model: opts.model,
+    xTicks: undefined,
+    format: opts.format,
+    cls: opts.cls,
+    height: opts.height,
+  }),
 })
 
+/** The whole chart's height from one pane's: a pane gets `share` of the height less the gap. */
+export const chartHeightOf = (paneHeight: number, share: number, gap: number): number =>
+  paneHeight > 0 && share > 0 ? paneHeight / share + gap : 0
+
 /** One row per datum for a series: a `null` or non-finite value is kept as a gap. */
 export function rowsOf<T, X extends ChartX>(
   data: readonly T[],

package/src/index.ts

@@ -12,7 +12,7 @@ export {
   type BasaltRouter,
   type BasaltRouterContext,
 } from './provider/create-router'
-export type { BasaltEvent } from './telemetry'
+export type { BasaltEvent, ChatTurnEnd, ChatTurnTrace, Telemetry, TraceHeaders } from './telemetry'
 export {
   defineNav,
   navGroup,

package/src/provider/index.tsx

@@ -36,7 +36,13 @@ import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import { PageTitle } from '../shell/page-title'
 import { SizeClassHintContext } from '../shell/use-size-class'
 import type { SizeClass } from '../shell/use-size-class'
-import { TelemetryContext, bindRouterTelemetry, createEmitter, errorName, now } from '../telemetry'
+import {
+  TelemetryContext,
+  bindRouterTelemetry,
+  createLiveEmitter,
+  errorName,
+  now,
+} from '../telemetry'
 import type { Telemetry } from '../telemetry'
 import type { BasaltDevDockTool } from '../dev-dock'
 import type { BasaltRouter, BasaltRouterContext } from './create-router'
@@ -426,7 +432,7 @@ export function BasaltProvider({
   useEffect(() => {
     sinkRef.current = telemetry
   })
-  const emit = useMemo(() => createEmitter((event) => sinkRef.current?.(event)), [])
+  const emit = useMemo(() => createLiveEmitter(() => sinkRef.current), [])
   useWindowErrors(emit)
   useRegistryHotkeys()
   // `overlays.confirm` is an imperative call; this tells it a `ModalsProvider` is live.

package/src/state/fields.ts

@@ -217,6 +217,14 @@ export type FieldSetOptions = {
 /** One option of an enum / multi / range field, labelled through `store.labels()`. */
 export type FieldOption = { value: string; label: string }
 
+/** The one label law: a declared label, else the value itself. */
+function labelledOptions(
+  values: readonly string[],
+  labels: Readonly<Record<string, string | undefined>> | undefined,
+): readonly FieldOption[] {
+  return values.map((value) => ({ value, label: labels?.[value] ?? value }))
+}
+
 /** `toWindow` exists on a range handle and nowhere else — it is not an optional convenience. */
 type RangeHandleExtras<F> = F extends {
   kind: 'range'
@@ -279,22 +287,14 @@ 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 })`. */
+/** A `createLocalStore` field: the shared handle plus `withFallback`. */
 export type LocalFieldHandle<F extends AnyField> = FieldHandle<F> & {
-  use(
-    read?: FieldReadOptions<F>,
-  ): readonly [FieldValue<F>, (next: FieldValue<F>, opts?: FieldSetOptions) => void]
+  /**
+   * The same field with a call-site unset value (a prop-derived leader), for `use()` and any
+   * control as `field=`. Rule: `basalt-state`. Stable per fallback: a primitive is cached for the
+   * LAST value only, an object (range, multi) by identity — memoise objects at the caller.
+   */
+  withFallback(fallback: FieldValue<F>): FieldHandle<F>
 }
 
 /**
@@ -789,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 = (read?: FieldReadOptions<AnyField>) => readonly [unknown, FieldWrite]
+export type FieldUse = (read?: { fallback?: unknown }) => readonly [unknown, FieldWrite]
 
 /** One named field plus its codec, in declaration order. @internal — see `FieldCodec`. */
 export type StoreEntry = { readonly name: string; readonly codec: FieldCodec }
@@ -986,8 +986,7 @@ export function createStoreCore(o: StoreCoreOptions): StoreCore {
   const readRecord = (): StoreRecord => toRecord(readPersistedValue(o.key, version))
 
   const optionsFor = (entry: StoreEntry): readonly FieldOption[] => {
-    const map = labels.get(entry.name)
-    return entry.codec.optionValues.map((value) => ({ value, label: map?.[value] ?? value }))
+    return labelledOptions(entry.codec.optionValues, labels.get(entry.name))
   }
 
   const clearField = (name: string): void => {
@@ -1165,9 +1164,39 @@ export function createLocalStore<const S extends Record<string, AnyField>>(o: {
     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 LocalFieldHandle<
-      S[keyof S]
-    >
+    // Two handles over one field: the public one carries `withFallback`, a derived one is built
+    // on the bare one, so `derived.withFallback` is undefined at runtime as well as in the type.
+    const bare = core.handle(entry, use, clear)
+    // Object.create, never a spread: `options` and `fallback` are live getters, and a spread would
+    // freeze them at derivation. Only what the call-site fallback changes is shadowed.
+    const derive = (fallback: FieldValue<AnyField>): FieldHandle<AnyField> => {
+      const useDerived = () => use({ fallback })
+      return Object.create(bare, {
+        use: { value: useDerived, enumerable: true },
+        fallback: { get: () => fallback, enumerable: true },
+        isDefault: { value: (v: unknown) => entry.codec.equals(v, fallback), enumerable: true },
+      }) as FieldHandle<AnyField>
+    }
+    // Objects by identity (weak); a primitive only for the last value, so a high-cardinality
+    // fallback (a latest date, an id) cannot grow the cache. A function is never cached.
+    const byIdentity = new WeakMap<object, FieldHandle<AnyField>>()
+    let last: { value: FieldValue<AnyField>; handle: FieldHandle<AnyField> } | undefined
+    const withFallback = (fallback: FieldValue<AnyField>): FieldHandle<AnyField> => {
+      if (typeof fallback === 'function') return derive(fallback)
+      if (typeof fallback === 'object') {
+        const cached = byIdentity.get(fallback)
+        if (cached !== undefined) return cached
+        const handle = derive(fallback)
+        byIdentity.set(fallback, handle)
+        return handle
+      }
+      if (last !== undefined && Object.is(last.value, fallback)) return last.handle
+      last = { value: fallback, handle: derive(fallback) }
+      return last.handle
+    }
+    field[entry.name as keyof S] = Object.assign(core.handle(entry, use, clear), {
+      withFallback,
+    }) as unknown as LocalFieldHandle<S[keyof S]>
   }
 
   const store: LocalStore<S> = {
@@ -1181,3 +1210,65 @@ export function createLocalStore<const S extends Record<string, AnyField>>(o: {
 
   return store
 }
+
+// ── externalField — a handle over a value another store owns ──────────────────────────────────
+
+/**
+ * The non-hook surface of a store basalt does not own — what zustand's `store.getState` /
+ * `store.setState` / `store.subscribe` already are, and what `useSyncExternalStore` wants.
+ */
+export type ExternalStore<T> = {
+  get: () => T
+  set: (next: T) => void
+  subscribe: (onChange: () => void) => () => void
+}
+
+/**
+ * A closed-enum field whose value lives in a store basalt does not own (a zustand slice, a context)
+ * — the bridge for a runtime mode that is neither page view state (URL) nor a preference
+ * (localStorage), so no `createSearchStore` / `createLocalStore` field may hold it without forking
+ * the truth. Returns the SAME `FieldHandle` those stores hand out, so `ViewTabs`, `SelectFilter`
+ * and `EnumFilter` bind to it as `field=` with no `value`/`onChange`.
+ *
+ * There is no lane: the handle reads and writes ONLY through `store`, which is taken at
+ * DEFINITION so a write never depends on a render — `clear()` calls `store.set(fallback)` directly
+ * (a foreign store has no "unset"), mounted or not, however many controls bind the handle. Labels
+ * are declared here like every other field's. The setter ignores `FieldSetOptions`: `patch` merges
+ * into a URL navigate and a lane-less write has none, the same contract the local lane documents.
+ *
+ * @example
+ * const timerMode = externalField({
+ *   values: ['rest', 'interval'],
+ *   fallback: 'rest',
+ *   labels: { rest: 'Rest Timer', interval: 'Interval Timer' },
+ *   store: {
+ *     get: () => useTimerStore.getState().mode,
+ *     set: (mode) => useTimerStore.getState().setMode(mode),
+ *     subscribe: useTimerStore.subscribe,
+ *   },
+ * })
+ * // <WidgetHeader actions={<ViewTabs field={timerMode} label="Timer mode" />} />
+ */
+export function externalField<const T extends string>(o: {
+  values: readonly T[]
+  fallback: NoInfer<T>
+  /** Option labels, keyed by value; an unlabelled value shows as itself. */
+  labels?: Partial<Record<T, string>>
+  store: ExternalStore<T>
+}): FieldHandle<EnumField<T>> {
+  const { values, fallback, store } = o
+  if (!values.includes(fallback)) {
+    throw new Error(
+      `basalt-ui: externalField fallback '${fallback}' is not one of its values (${values.join(', ')}).`,
+    )
+  }
+  const setter = (next: T): void => store.set(next)
+  return {
+    kind: 'enum',
+    fallback,
+    options: labelledOptions(values, o.labels),
+    use: () => [useSyncExternalStore(store.subscribe, store.get, store.get), setter] as const,
+    clear: () => store.set(fallback),
+    isDefault: (v) => v === fallback,
+  }
+}

package/src/state.ts

@@ -5,6 +5,7 @@
  * - `createPersistedState` — the versioned localStorage primitive every basalt module persists through.
  * - `field.*`, `FieldHandle`, `EnumField`, `RangeWindow` and `createLocalStore` — the store field
  *   vocabulary and the router-free store.
+ * - `externalField` — a `FieldHandle` over a value another store owns (a zustand slice).
  * - `createSearchStore` — the URL-backed store (the store half of 1.x `./router-tanstack`).
  *
  * Internal consumers import the wider field types from `./state/fields`.
@@ -14,6 +15,7 @@ export { createPersistedState } from './state/persisted'
 
 export {
   field,
+  externalField,
   createLocalStore,
   type EnumField,
   type FieldHandle,

package/src/telemetry.ts

@@ -65,7 +65,61 @@ export type BasaltEvent =
   | Ok<'chat.turn', ChatAttrs>
   | Err<'chat.turn', ChatAttrs, Span>
 
-export type Telemetry = (event: BasaltEvent) => void
+/** W3C trace-context request headers a sink contributes to one chat turn's request. */
+export type TraceHeaders = {
+  readonly traceparent: string
+  readonly tracestate?: string | undefined
+}
+
+/**
+ * How a traced chat turn ended: its `chat.turn` event fired (`settled`/`failed`), or `stopped` — a
+ * `stop()`, an unmount or a newer run taking the thread over — which emits no event. The one
+ * lifecycle vocabulary of the run records too.
+ */
+export type ChatTurnEnd = 'settled' | 'failed' | 'stopped'
+
+/** The turn a sink is asked to trace. */
+type ChatTurnInit = { readonly threadId: string; readonly messageId: string }
+
+/**
+ * What a sink returns from `startChatTurn`. `settle` runs once, synchronously, right after the
+ * turn's `chat.turn` event (`settled`/`failed`), or when the turn is cut short (`stopped`) — the
+ * point to end a span opened in `startChatTurn`. It runs even when `headers` is absent or
+ * malformed (dropped, the request goes out untraced), so the span never leaks.
+ */
+export type ChatTurnTrace = {
+  readonly headers?: TraceHeaders | undefined
+  readonly settle?: ((end: ChatTurnEnd) => void) | undefined
+}
+
+/**
+ * The event sink. It may carry one optional hook, `startChatTurn`, called when a new chat turn
+ * begins (not on a resume): open your span there and return its `traceparent` (and `tracestate`)
+ * and `aiSdkTransport` sends them with that turn's request to the chat endpoint — never anywhere
+ * else. A sink without the hook, or no sink, changes nothing on the wire. basalt has no OTel
+ * dependency; the hook is where the consumer's SDK does the work.
+ *
+ * @example
+ * export const telemetry: Telemetry = Object.assign(onEvent, {
+ *   startChatTurn({ threadId }) {
+ *     const span = tracer.startSpan('chat.turn', {
+ *       attributes: { 'basalt.chat.thread_id': threadId },
+ *     })
+ *     const carrier: Record<string, string> = {}
+ *     propagation.inject(trace.setSpan(context.active(), span), carrier)
+ *     return {
+ *       headers: { traceparent: carrier.traceparent ?? '', tracestate: carrier.tracestate },
+ *       settle(end) {
+ *         if (end === 'failed') span.setStatus({ code: SpanStatusCode.ERROR })
+ *         span.end()
+ *       },
+ *     }
+ *   },
+ * })
+ */
+export type Telemetry = ((event: BasaltEvent) => void) & {
+  readonly startChatTurn?: ((turn: ChatTurnInit) => ChatTurnTrace | undefined) | undefined
+}
 
 export const now = (): number => performance.timeOrigin + performance.now()
 
@@ -73,18 +127,27 @@ export const now = (): number => performance.timeOrigin + performance.now()
 export const errorName = (error: unknown): string => (error instanceof Error ? error.name : 'Error')
 
 /**
- * Wrap a sink so it is called synchronously and a throwing sink never breaks a render. No sink, no
- * events.
+ * The wrapped emitter over a sink read at call time (a ref), so a swapped sink is never stale. It is
+ * called synchronously and a throwing sink never breaks a render; no sink, no events. Its
+ * `startChatTurn` forwards the sink's hook; the hook's consumer validates the headers.
  */
-export function createEmitter(sink: Telemetry | undefined): Telemetry {
-  if (sink === undefined) return noop
-  return (event) => {
+export function createLiveEmitter(read: () => Telemetry | undefined): Telemetry {
+  const emit = (event: BasaltEvent): void => {
     try {
-      sink(event)
+      read()?.(event)
     } catch {
       // a throwing sink must never break the app (§ 7 delivery rules)
     }
   }
+  return Object.assign(emit, {
+    startChatTurn(turn: ChatTurnInit): ChatTurnTrace | undefined {
+      try {
+        return read()?.startChatTurn?.(turn)
+      } catch {
+        return undefined
+      }
+    },
+  })
 }
 
 function noop(): void {}