basalt-ui 1.26.0 → 1.27.0

package/src/state/persisted.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `createPersistedState` — the in-tab notification contract.
+ *
+ * The versioned envelope and the cross-tab path are exercised through every store that persists
+ * (`fields.test.tsx`, `search-store.test.ts`); what only shows up here is TWO instances over ONE
+ * key, which is ordinary rather than exotic: a page's store and a widget's own state legitimately
+ * name the same key. Per-instance listener sets made a write through one invisible to the other in
+ * the SAME tab — while the cross-tab path worked, which is what made it read as a caching bug.
+ */
+import { beforeEach, describe, expect, test } from 'bun:test'
+import { act, renderHook } from '@testing-library/react'
+import { createPersistedState, readPersistedValue } from './persisted'
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+describe('createPersistedState — one key, two instances', () => {
+  test('a write through A re-renders a hook on B with the new value', () => {
+    const useA = createPersistedState({ key: 'shared-draft', version: 1, initial: 'a' })
+    const useB = createPersistedState({ key: 'shared-draft', version: 1, initial: 'a' })
+
+    const a = renderHook(() => useA())
+    const b = renderHook(() => useB())
+    expect(b.result.current[0]).toBe('a')
+
+    act(() => {
+      a.result.current[1]('written-through-A')
+    })
+
+    expect(b.result.current[0]).toBe('written-through-A')
+    expect(a.result.current[0]).toBe('written-through-A')
+    expect(readPersistedValue('shared-draft', 1)).toBe('written-through-A')
+  })
+
+  test('the notification is per KEY — a second key is not woken', () => {
+    const useShared = createPersistedState({ key: 'k-one', version: 1, initial: 0 })
+    const useOther = createPersistedState({ key: 'k-two', version: 1, initial: 0 })
+
+    let otherRenders = 0
+    const shared = renderHook(() => useShared())
+    renderHook(() => {
+      otherRenders += 1
+      return useOther()
+    })
+    const before = otherRenders
+
+    act(() => {
+      shared.result.current[1](7)
+    })
+
+    expect(shared.result.current[0]).toBe(7)
+    expect(otherRenders).toBe(before)
+  })
+
+  test('unmounting one instance leaves the other subscribed', () => {
+    const useA = createPersistedState({ key: 'shared-unmount', version: 1, initial: 'a' })
+    const useB = createPersistedState({ key: 'shared-unmount', version: 1, initial: 'a' })
+
+    const a = renderHook(() => useA())
+    const b = renderHook(() => useB())
+    a.unmount()
+
+    const c = renderHook(() => useA())
+    act(() => {
+      c.result.current[1]('later')
+    })
+
+    expect(b.result.current[0]).toBe('later')
+  })
+
+  test('an object value stays referentially stable between writes (the snapshot cache)', () => {
+    const useDraft = createPersistedState<{ title: string }>({
+      key: 'shared-object',
+      version: 1,
+      initial: { title: '' },
+    })
+
+    const { result } = renderHook(() => useDraft())
+    const first = result.current[0]
+    act(() => {
+      result.current[1]({ title: 'one' })
+    })
+    const written = result.current[0]
+
+    expect(first).not.toBe(written)
+    expect(written).toEqual({ title: 'one' })
+    // Same raw string → same parsed reference, which is what keeps useSyncExternalStore quiet.
+    expect(renderHook(() => useDraft()).result.current[0]).toBe(written)
+  })
+})

package/src/state/persisted.ts

@@ -32,6 +32,42 @@ export type PersistedStateOptions<T> = {
   readonly schema?: StandardSchemaV1<unknown, T>
 }
 
+/**
+ * Every subscriber for ONE storage key, shared by every `createPersistedState` instance over that
+ * key — plus the single `storage` event listener the key needs.
+ *
+ * Module-level rather than per-instance because two instances of the same key are ordinary, not a
+ * mistake: a page's `createSearchStore` and a widget's `createPersistedState` legitimately name the
+ * same key, and a consumer re-exporting a store from two modules ends up there by accident. With
+ * per-instance listener sets a write through one instance updated localStorage and notified only
+ * its own hooks, so the other instance's components kept rendering the stale value until something
+ * else re-rendered them — in the SAME tab, while the cross-tab path (the `storage` event) worked.
+ *
+ * The map is keyed by the NAMESPACED key and holds no window reference; a channel is created on
+ * first subscribe, which only happens in the browser (`subscribe` is never passed on the server).
+ */
+type KeyChannel = {
+  readonly listeners: Set<() => void>
+  handler: ((e: StorageEvent) => void) | null
+}
+
+const channels = new Map<string, KeyChannel>()
+
+/** Wake every hook on a key, whichever instance holds it. */
+function notify(storageKey: string): void {
+  const channel = channels.get(storageKey)
+  if (channel === undefined) return
+  for (const listener of channel.listeners) listener()
+}
+
+function channelFor(storageKey: string): KeyChannel {
+  const existing = channels.get(storageKey)
+  if (existing !== undefined) return existing
+  const created: KeyChannel = { listeners: new Set(), handler: null }
+  channels.set(storageKey, created)
+  return created
+}
+
 /** The envelope stored in localStorage: `{ v: number, value: unknown }`. */
 type Envelope = { v: number; value: unknown }
 
@@ -73,16 +109,19 @@ function parseStorage<T>(raw: string | null, opts: PersistedStateOptions<T>): T
   }
 }
 
-function writeStorage<T>(opts: PersistedStateOptions<T>, next: T): void {
-  const storageKey = `basalt:${opts.key}`
+function writeEnvelope(storageKey: string, version: number, value: unknown): void {
   try {
-    const envelope: Envelope = { v: opts.version, value: next }
+    const envelope: Envelope = { v: version, value }
     window.localStorage.setItem(storageKey, JSON.stringify(envelope))
   } catch {
     // Silently fail (storage full, private browsing, etc.)
   }
 }
 
+function writeStorage<T>(opts: PersistedStateOptions<T>, next: T): void {
+  writeEnvelope(`basalt:${opts.key}`, opts.version, next)
+}
+
 /**
  * Versioned, Standard-Schema-validated localStorage state via useSyncExternalStore (no zustand).
  * SSR-safe (getServerSnapshot returns `initial`). Cross-tab via the storage event.
@@ -100,32 +139,25 @@ export function createPersistedState<T>(
 ): () => readonly [T, (next: T) => void] {
   const storageKey = `basalt:${opts.key}`
 
-  // One Set of subscriber callbacks — mirrors notifications/store.ts single-listener-to-Set pattern.
-  const listeners = new Set<() => void>()
-
-  // ONE module-scoped 'storage' event listener per key, registered lazily on first subscriber.
-  // Removed when the last subscriber unsubscribes (cleanup semantics preserved).
-  let storageHandler: ((e: StorageEvent) => void) | null = null
-
   const subscribe = (cb: () => void): (() => void) => {
-    listeners.add(cb)
-
-    // Attach the shared window listener on the first subscriber.
-    if (storageHandler === null) {
-      storageHandler = (e: StorageEvent): void => {
-        if (e.key === storageKey) {
-          for (const listener of listeners) listener()
-        }
+    // The subscriber set is the KEY's, not this instance's — see `KeyChannel`.
+    const channel = channelFor(storageKey)
+    channel.listeners.add(cb)
+
+    // ONE 'storage' event listener per key, registered lazily on the first subscriber and removed
+    // when the last one leaves (cleanup semantics preserved).
+    if (channel.handler === null) {
+      channel.handler = (e: StorageEvent): void => {
+        if (e.key === storageKey) notify(storageKey)
       }
-      window.addEventListener('storage', storageHandler)
+      window.addEventListener('storage', channel.handler)
     }
 
     return () => {
-      listeners.delete(cb)
-      // Detach the shared window listener when the last subscriber unsubscribes.
-      if (listeners.size === 0 && storageHandler !== null) {
-        window.removeEventListener('storage', storageHandler)
-        storageHandler = null
+      channel.listeners.delete(cb)
+      if (channel.listeners.size === 0 && channel.handler !== null) {
+        window.removeEventListener('storage', channel.handler)
+        channel.handler = null
       }
     }
   }
@@ -158,8 +190,9 @@ export function createPersistedState<T>(
 
   const setState = (next: T): void => {
     writeStorage(opts, next)
-    // Notify in-tab listeners (the 'storage' event only fires in OTHER tabs)
-    for (const cb of listeners) cb()
+    // Notify every in-tab listener on this KEY — the 'storage' event fires in OTHER tabs only, and
+    // a second instance of the same key has its own hooks to wake.
+    notify(storageKey)
   }
 
   // Detect SSR once at creation time — the environment doesn't change between renders.
@@ -209,3 +242,20 @@ export function readPersistedValue(key: string, version?: number): unknown | nul
     return null
   }
 }
+
+/**
+ * Write a value under the namespaced key `basalt:<key>` in the same versioned envelope
+ * `createPersistedState` writes, and wake every hook on that key — the write half of
+ * `readPersistedValue`, and plain in the same way: no React required.
+ *
+ * The one call site is a store field's `clear()`, which has to DELETE its key from the store's
+ * record from an event handler, where the hook's setter is not in reach. Not exported from the
+ * `basalt-ui/state` barrel: the two store factories are the API, this is their seam.
+ *
+ * @internal
+ */
+export function writePersistedValue(key: string, version: number, value: unknown): void {
+  const storageKey = `basalt:${key}`
+  writeEnvelope(storageKey, version, value)
+  notify(storageKey)
+}

package/src/state.ts

@@ -30,6 +30,10 @@ export {
   type RangeValue,
   type RangeParams,
   type RangePresets,
+  type RangeWindow,
+  type RangeWindows,
+  type FieldFallback,
+  type FieldSetOptions,
   type EnumField,
   type MultiField,
   type RangeField,
@@ -47,6 +51,8 @@ export {
   type StoreEntry,
   type StoreCoreOptions,
   type StoreCore,
+  type FieldUse,
+  type FieldWrite,
   resolveFieldCodec,
   createStoreCore,
 } from './state/fields'

package/src/surfaces.ts

@@ -553,8 +553,9 @@ export const SURFACES = {
     // The text lane of law C1 — the plugin's `control-outside-home` seen through a 12-line host-tag
     // window, since a regex scan has no ancestry. Same law, same wave, same promotion.
     guardKinds: ['raw-selection-control'],
-    // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter` ships `error` — "inside a
-    // slot" is structural; the other three are grace entries in `PLUGIN_RULE_GRACE` until 1.27.0.
+    // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter`, `control-size-literal` and
+    // `responsive-twin` all ship `error`; `control-outside-home` is the one grace entry left in
+    // `PLUGIN_RULE_GRACE`, re-dated to 1.28.0 against the wave-7 measurement (see its `why`).
     // The budget rules live on `.` with `PageBar` itself.
     pluginRules: [
       'hand-rolled-filter',
@@ -571,7 +572,7 @@ export const SURFACES = {
       'C12 — one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy',
     ],
     description:
-      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
+      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
     optionalPeers: [],
     forbiddenImports: [],
   },

package/src/widget-header/widget-header.module.css

@@ -199,6 +199,21 @@
   color: var(--vx-ink);
 }
 
+/*
+ * The unit beside the hero value. Mono like the number it qualifies (so `412 TSS` sits on one
+ * baseline grid), `--vx-text-sm` and `--vx-muted` so it never competes with the numeral — the whole
+ * point is that a unit is the SMALL half of the pair. `flex-shrink: 0`: the value is the row's
+ * shrinkable half (see `.value`), and a unit that ellipsized to `TS…` would state nothing.
+ */
+.unit {
+  flex-shrink: 0;
+  align-self: baseline;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-sm);
+  font-weight: 500;
+  color: var(--vx-muted);
+}
+
 /* The C1/C5 home for header actions — always pinned right, regardless of what else is present. */
 .actions {
   display: inline-flex;

package/src/widget-header/widget-header.module.css.d.ts

@@ -11,6 +11,7 @@ declare const classes: {
   readonly count: string
   readonly metrics: string
   readonly value: string
+  readonly unit: string
   readonly actions: string
   readonly subtitle: string
   readonly sparkline: string

package/src/widget-header/widget-header.tsx

@@ -51,10 +51,40 @@ export type WidgetHeaderProps = {
   /** Pre-formatted metric value (mono, hero size). Renders on its own row with `delta`, directly
    * under the title row — never inline with the title. */
   value?: string
+  /**
+   * The value's unit, rendered immediately after it on the hero row: muted, mono, `--vx-text-sm`.
+   *
+   * It exists because `value` is a pre-formatted `string` and a KPI's unit is not part of the
+   * number: `412` and `TSS` are two facts at two weights, and jamming them into one string paints
+   * the unit at the hero's 24px — which reads as a second numeral. `subtitle` was the only place a
+   * unit could go before this, and a unit on its own line under the value is a different claim (the
+   * BASIS: `7-day rolling`), so cards using both had to pick one.
+   *
+   * Never a substitute for the number's own formatting: a thousands separator, a currency symbol or
+   * a `%` belong in `value`, where they are part of how the numeral reads.
+   */
+  unit?: string
   /** Signed delta rendered via `DeltaBadge`, on the same hero-metric row as `value`. */
   delta?: number
   /** Comparison timeframe forwarded to `DeltaBadge` (e.g. `MoM`). */
   deltaPeriod?: string
+  /**
+   * Formats `delta` into the chip's label — forwarded to `DeltaBadge`'s `format`. Defaults to
+   * `${Math.abs(delta).toFixed(1)}%`.
+   *
+   * It exists because not every delta is a percentage: a pace card's trend is `0:12 /km` and a
+   * throughput card's is `0.3 km/h`, and the default printed both as a percent — a wrong unit on a
+   * KPI, which is worse than no chip. A FUNCTION rather than a label string, so the number stays the
+   * number: `delta` still drives the tone and the glyph, and there is exactly one place the sign is
+   * decided.
+   *
+   * The value arrives SIGNED, so a formatter that wants to print the sign itself (`−0:12 /km`) can —
+   * pair it with `deltaGlyph={false}` so the ▼ does not say the same thing twice.
+   */
+  deltaFormat?: (delta: number) => string
+  /** Render `DeltaBadge`'s ▲/▼ glyph. Defaults to `true`; a zero delta never shows one. Pass
+   * `false` when `deltaFormat` prints the sign itself. */
+  deltaGlyph?: boolean
   /** Trend visual slot, rendered below the metric row. Carries `data-placement="right"` so a
    * wave-3 composer's `bleed` layout can select it. */
   sparkline?: ReactNode
@@ -127,8 +157,11 @@ export function WidgetHeader({
   subtitle,
   info,
   value,
+  unit,
   delta,
   deltaPeriod,
+  deltaFormat,
+  deltaGlyph,
   sparkline,
   count,
   actions,
@@ -154,7 +187,19 @@ export function WidgetHeader({
       {(value !== undefined || delta !== undefined) && (
         <div className={classes.metrics}>
           {value !== undefined && <span className={classes.value}>{value}</span>}
-          {delta !== undefined && <DeltaBadge value={delta} period={deltaPeriod} />}
+          {/* Gated on `value`, not on itself: a unit with nothing to qualify is a stray word, and a
+              card that lost its number must not keep printing `TSS` beside the empty space. */}
+          {value !== undefined && unit !== undefined && (
+            <span className={classes.unit}>{unit}</span>
+          )}
+          {delta !== undefined && (
+            <DeltaBadge
+              value={delta}
+              period={deltaPeriod}
+              {...(deltaFormat !== undefined && { format: deltaFormat })}
+              {...(deltaGlyph !== undefined && { withGlyph: deltaGlyph })}
+            />
+          )}
         </div>
       )}
       {subtitle !== undefined && <span className={classes.subtitle}>{subtitle}</span>}