@carto/ps-react-ui 4.7.1 → 4.8.0

package/src/widgets-v2/stores/pipeline-middleware.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import {
+  clearAllWidgetStores,
+  createWidgetStore,
+} from './widget-store-registry'
+import type { Transform, WidgetStoreApi } from './types'
+
+const t = (
+  over: Partial<Transform> & { id: string; fn: Transform['fn']; order: number },
+): Transform => ({
+  type: 'data',
+  enabled: true,
+  ...over,
+})
+
+describe('pipeline-middleware', () => {
+  let store: WidgetStoreApi
+
+  beforeEach(() => {
+    store = createWidgetStore('pm-test', { data: 1 })
+  })
+
+  afterEach(() => {
+    clearAllWidgetStores()
+  })
+
+  it('runs the data pipeline when rawData changes', () => {
+    store.setState({
+      dataTransforms: [
+        t({ id: 'd', type: 'data', order: 1, fn: (n) => (n as number) * 2 }),
+      ],
+    })
+    store.setState({ rawData: 5 })
+    expect(store.getState().data).toBe(10)
+  })
+
+  it('skips the pipeline when neither rawData nor dataTransforms change', () => {
+    let runs = 0
+    store.setState({
+      dataTransforms: [
+        t({
+          id: 'd',
+          type: 'data',
+          order: 1,
+          fn: (n) => {
+            runs++
+            return n
+          },
+        }),
+      ],
+    })
+    const baseline = runs
+    store.setState({ isLoading: true })
+    expect(runs).toBe(baseline)
+  })
+
+  it('sets the error field when a transform throws', () => {
+    const bad = t({
+      id: 'bad',
+      type: 'data',
+      order: 1,
+      fn: () => {
+        throw new Error('pipeline-throw')
+      },
+    })
+    store.setState({ dataTransforms: [bad], rawData: 1 })
+    expect(store.getState().error).toBeInstanceOf(Error)
+    expect((store.getState().error as Error).message).toBe('pipeline-throw')
+  })
+
+  it('clears a stale error once a clean pipeline run completes', () => {
+    // First run throws and stamps `error` into state.
+    const bad = t({
+      id: 'bad',
+      type: 'data',
+      order: 1,
+      fn: () => {
+        throw new Error('one-shot-throw')
+      },
+    })
+    store.setState({ dataTransforms: [bad], rawData: 1 })
+    expect(store.getState().error).toBeInstanceOf(Error)
+    // Next pipeline run completes cleanly — the prior error must be cleared.
+    const ok = t({
+      id: 'ok',
+      type: 'data',
+      order: 1,
+      fn: (n) => n,
+    })
+    store.setState({ dataTransforms: [ok], rawData: 2 })
+    expect(store.getState().error).toBeUndefined()
+  })
+
+  it('preserves a consumer-set error when a clean pipeline runs (e.g. action mount adds dataTransforms)', () => {
+    // Regression: an action like StackToggle mounts and registers a
+    // dataTransforms entry; that triggers a pipeline run with no throw.
+    // The consumer-supplied error (Provider's `error` prop) must survive.
+    const consumerError = new Error('fetch failed')
+    store.setState({ error: consumerError })
+    // Action mount: a new dataTransforms array reference flows in.
+    store.setState({
+      dataTransforms: [
+        t({
+          id: 'noop',
+          type: 'data',
+          order: 1,
+          fn: (n) => n,
+        }),
+      ],
+    })
+    expect(store.getState().error).toBe(consumerError)
+  })
+
+  it('clears a consumer-set error when the consumer explicitly writes a new one mid-pipeline-run', () => {
+    const initial = new Error('first')
+    const next = new Error('second')
+    store.setState({ error: initial })
+    // Consumer writes `error` AND triggers the pipeline in the same call.
+    store.setState({
+      error: next,
+      rawData: 99,
+    })
+    expect(store.getState().error).toBe(next)
+  })
+
+  it('preserves the first error when multiple transforms throw', () => {
+    const a = t({
+      id: 'a',
+      type: 'data',
+      order: 1,
+      fn: () => {
+        throw new Error('first')
+      },
+    })
+    const b = t({
+      id: 'b',
+      type: 'data',
+      order: 2,
+      fn: () => {
+        throw new Error('second')
+      },
+    })
+    store.setState({ dataTransforms: [a, b], rawData: 1 })
+    expect((store.getState().error as Error).message).toBe('first')
+  })
+
+  it('passes incoming non-pipeline updates through unchanged', () => {
+    store.setState({ isFetching: true, isLoading: true })
+    expect(store.getState().isFetching).toBe(true)
+    expect(store.getState().isLoading).toBe(true)
+  })
+
+  it('runs the data pipeline when dataTransforms reference changes', () => {
+    const id1 = t({
+      id: 'a',
+      type: 'data',
+      order: 1,
+      fn: (n) => (n as number) + 1,
+    })
+    store.setState({ dataTransforms: [id1] })
+    expect(store.getState().data).toBe(2)
+    const id2 = t({
+      id: 'a',
+      type: 'data',
+      order: 1,
+      fn: (n) => (n as number) + 100,
+    })
+    store.setState({ dataTransforms: [id2] })
+    expect(store.getState().data).toBe(101)
+  })
+
+  it('one set call → one render — atomic raw + derived', () => {
+    let renders = 0
+    const unsub = store.subscribe(() => {
+      renders++
+    })
+    store.setState({
+      rawData: 5,
+      dataTransforms: [
+        t({ id: 'd', type: 'data', order: 1, fn: (n) => (n as number) * 2 }),
+      ],
+    })
+    expect(renders).toBe(1)
+    expect(store.getState().data).toBe(10)
+    unsub()
+  })
+})

package/src/widgets-v2/stores/pipeline-middleware.ts

@@ -0,0 +1,91 @@
+import type { StateCreator, StoreApi, StoreMutatorIdentifier } from 'zustand'
+import type { Transform, WidgetState } from './types'
+import { applyTransforms } from './transforms'
+
+type PipelineMiddleware = <
+  T extends WidgetState,
+  Mps extends [StoreMutatorIdentifier, unknown][] = [],
+  Mcs extends [StoreMutatorIdentifier, unknown][] = [],
+>(
+  config: StateCreator<T, Mps, Mcs>,
+) => StateCreator<T, Mps, Mcs>
+
+type SetFn<T> = StoreApi<T>['setState']
+
+// Per-store flag: true iff the current `state.error` was authored by the
+// pipeline (a transform threw) rather than by the consumer (Provider's
+// `error` prop or a direct setState). Lets the middleware clear stale
+// pipeline errors on a subsequent clean run without clobbering errors a
+// consumer set out-of-band.
+const pipelineOwnedError = new WeakSet<StoreApi<WidgetState>>()
+
+export const pipelineMiddleware: PipelineMiddleware = ((config) =>
+  (set, get, api) => {
+    const origSetState = api.setState as SetFn<WidgetState>
+    const typedApi = api as StoreApi<WidgetState>
+
+    const wrap = (delegate: SetFn<WidgetState>): SetFn<WidgetState> =>
+      ((partial, replace) => {
+        const current = (api.getState as () => WidgetState)()
+        const incoming =
+          typeof partial === 'function'
+            ? (partial as (s: WidgetState) => Partial<WidgetState>)(current)
+            : (partial as Partial<WidgetState>)
+
+        const has = (key: keyof WidgetState) =>
+          Object.prototype.hasOwnProperty.call(incoming, key)
+
+        const rawDataChanged =
+          has('rawData') && !Object.is(incoming.rawData, current.rawData)
+        const dataXfChanged =
+          has('dataTransforms') &&
+          incoming.dataTransforms !== current.dataTransforms
+
+        if (!rawDataChanged && !dataXfChanged) {
+          // Consumer-authored writes that don't trigger the pipeline. If the
+          // consumer is explicitly touching `error`, the next pipeline run is
+          // no longer responsible for it — drop the pipeline-owned marker.
+          if (has('error')) pipelineOwnedError.delete(typedApi)
+          return delegate(incoming, replace as false)
+        }
+
+        const augmented: Partial<WidgetState> = { ...incoming }
+        let firstError: unknown = undefined
+        const onError = (_id: string, err: Error) => {
+          if (firstError === undefined) firstError = err
+        }
+
+        const nextRaw = rawDataChanged ? incoming.rawData : current.rawData
+        const nextXf: readonly Transform[] = dataXfChanged
+          ? incoming.dataTransforms!
+          : current.dataTransforms
+        augmented.data = applyTransforms(nextRaw, nextXf, onError)
+
+        // Reconcile `error` based on who authored the previous value:
+        //   - pipeline throw → stamp the new error, mark pipeline-owned.
+        //   - clean run AND previous error was pipeline-owned → clear it.
+        //   - clean run AND previous error was consumer-set → leave it.
+        // Consumer-authored `error` in `incoming` also wins over the marker
+        // (and resets the marker via the early-return branch above).
+        if (firstError !== undefined) {
+          augmented.error = firstError
+          pipelineOwnedError.add(typedApi)
+        } else if (pipelineOwnedError.has(typedApi) && !has('error')) {
+          augmented.error = undefined
+          pipelineOwnedError.delete(typedApi)
+        } else if (has('error')) {
+          // Consumer set error in the same call that ran the pipeline — honor
+          // their write and surrender ownership.
+          pipelineOwnedError.delete(typedApi)
+        }
+
+        return delegate(augmented, replace as false)
+      }) as SetFn<WidgetState>
+
+    // Wrap both the public setState (used by store.setState() callers) and
+    // the inner set passed into the state creator (used by actions inside config).
+    api.setState = wrap(origSetState) as typeof api.setState
+    const wrappedInnerSet = wrap(set as SetFn<WidgetState>)
+
+    return config(wrappedInnerSet as typeof set, get, api)
+  }) as PipelineMiddleware

package/src/widgets-v2/stores/transforms.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest'
+import { applyTransforms, upsertTransform, removeTransform } from './transforms'
+import type { Transform } from './types'
+
+const t = (
+  over: Partial<Transform> & { id: string; fn: Transform['fn']; order: number },
+): Transform => ({
+  type: 'data',
+  enabled: true,
+  ...over,
+})
+
+describe('applyTransforms', () => {
+  it('returns input when transforms array is empty', () => {
+    expect(applyTransforms({ a: 1 }, [])).toEqual({ a: 1 })
+  })
+
+  it('applies a single enabled transform', () => {
+    const out = applyTransforms(2, [
+      t({ id: 'x2', order: 1, fn: (n) => (n as number) * 2 }),
+    ])
+    expect(out).toBe(4)
+  })
+
+  it('chains transforms in order', () => {
+    const xs = [
+      t({ id: 'a', order: 1, fn: (n) => (n as number) + 1 }),
+      t({ id: 'b', order: 2, fn: (n) => (n as number) * 10 }),
+    ]
+    expect(applyTransforms(1, xs)).toBe(20)
+  })
+
+  it('skips disabled transforms', () => {
+    const xs = [
+      t({ id: 'a', order: 1, fn: (n) => (n as number) + 1 }),
+      t({ id: 'b', order: 2, fn: (n) => (n as number) * 10, enabled: false }),
+    ]
+    expect(applyTransforms(1, xs)).toBe(2)
+  })
+
+  it('respects disables map: enabled transform disables another', () => {
+    const xs = [
+      t({ id: 'a', order: 1, fn: (n) => (n as number) + 1, disables: ['b'] }),
+      t({ id: 'b', order: 2, fn: (n) => (n as number) * 10 }),
+    ]
+    expect(applyTransforms(1, xs)).toBe(2)
+  })
+
+  it('does not apply disables when the disabling transform itself is disabled', () => {
+    const xs = [
+      t({
+        id: 'a',
+        order: 1,
+        fn: (n) => (n as number) + 1,
+        disables: ['b'],
+        enabled: false,
+      }),
+      t({ id: 'b', order: 2, fn: (n) => (n as number) * 10 }),
+    ]
+    expect(applyTransforms(1, xs)).toBe(10)
+  })
+
+  it('captures the first error and continues with remaining transforms', () => {
+    const errors: { id: string; msg: string }[] = []
+    const xs = [
+      t({
+        id: 'bad',
+        order: 1,
+        fn: () => {
+          throw new Error('boom')
+        },
+      }),
+      t({ id: 'good', order: 2, fn: (n) => (n as number) * 2 }),
+    ]
+    const out = applyTransforms(3, xs, (id, err) =>
+      errors.push({ id, msg: err.message }),
+    )
+    expect(out).toBe(6)
+    expect(errors).toEqual([{ id: 'bad', msg: 'boom' }])
+  })
+
+  it('wraps non-Error throws as Error', () => {
+    const errors: Error[] = []
+    applyTransforms(
+      1,
+      [
+        t({
+          id: 'x',
+          order: 1,
+          fn: () => {
+            // eslint-disable-next-line @typescript-eslint/only-throw-error -- exercising non-Error wrap
+            throw 'string-throw'
+          },
+        }),
+      ],
+      (_id, err) => errors.push(err),
+    )
+    expect(errors[0]).toBeInstanceOf(Error)
+    expect(errors[0]?.message).toBe('string-throw')
+  })
+})
+
+describe('upsertTransform', () => {
+  it('inserts new transforms in ascending order', () => {
+    const a = t({ id: 'a', order: 10, fn: (n) => n })
+    const b = t({ id: 'b', order: 5, fn: (n) => n })
+    const c = t({ id: 'c', order: 20, fn: (n) => n })
+    const out = upsertTransform(upsertTransform(upsertTransform([], a), b), c)
+    expect(out.map((x) => x.id)).toEqual(['b', 'a', 'c'])
+  })
+
+  it('returns the same array reference when transform is identical', () => {
+    const fn = (n: unknown) => n
+    const a = t({ id: 'a', order: 1, fn })
+    const arr = upsertTransform([], a)
+    const next = upsertTransform(arr, t({ id: 'a', order: 1, fn }))
+    expect(next).toBe(arr)
+  })
+
+  it('replaces an existing transform when fn changes', () => {
+    const a1 = t({ id: 'a', order: 1, fn: (n) => n })
+    const a2 = t({ id: 'a', order: 1, fn: (n) => (n as number) + 1 })
+    const arr = upsertTransform([], a1)
+    const next = upsertTransform(arr, a2)
+    expect(next).not.toBe(arr)
+    expect(next.find((x) => x.id === 'a')?.fn).toBe(a2.fn)
+  })
+
+  it('reorders when order changes', () => {
+    const a = t({ id: 'a', order: 10, fn: (n) => n })
+    const b = t({ id: 'b', order: 20, fn: (n) => n })
+    const arr = [a, b]
+    const next = upsertTransform(arr, t({ id: 'a', order: 30, fn: a.fn }))
+    expect(next.map((x) => x.id)).toEqual(['b', 'a'])
+  })
+
+  it('treats different disables as a structural change', () => {
+    const a1 = t({ id: 'a', order: 1, fn: (n) => n, disables: ['b'] })
+    const a2 = t({ id: 'a', order: 1, fn: a1.fn, disables: ['c'] })
+    const arr = upsertTransform([], a1)
+    const next = upsertTransform(arr, a2)
+    expect(next).not.toBe(arr)
+    expect(next.find((x) => x.id === 'a')?.disables).toEqual(['c'])
+  })
+})
+
+describe('removeTransform', () => {
+  it('removes a transform by id', () => {
+    const arr = [
+      t({ id: 'a', order: 1, fn: (n) => n }),
+      t({ id: 'b', order: 2, fn: (n) => n }),
+    ]
+    const next = removeTransform(arr, 'a')
+    expect(next.map((x) => x.id)).toEqual(['b'])
+  })
+
+  it('returns the same array reference when id is absent', () => {
+    const arr = [t({ id: 'a', order: 1, fn: (n) => n })]
+    const next = removeTransform(arr, 'missing')
+    expect(next).toBe(arr)
+  })
+})

package/src/widgets-v2/stores/transforms.ts

@@ -0,0 +1,70 @@
+import type { Transform } from './types'
+
+export function applyTransforms(
+  input: unknown,
+  transforms: readonly Transform[],
+  onError?: (id: string, error: Error) => void,
+): unknown {
+  const disabledIds = new Set<string>()
+  for (const t of transforms) {
+    if (t.enabled && t.disables?.length) {
+      for (const id of t.disables) disabledIds.add(id)
+    }
+  }
+  let acc: unknown = input
+  for (const t of transforms) {
+    if (!t.enabled) continue
+    if (disabledIds.has(t.id)) continue
+    try {
+      acc = t.fn(acc)
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e))
+      // eslint-disable-next-line no-console
+      console.warn(`[widgets-v2] Transform "${t.id}" failed:`, err)
+      onError?.(t.id, err)
+    }
+  }
+  return acc
+}
+
+export function upsertTransform(
+  transforms: readonly Transform[],
+  next: Transform,
+): readonly Transform[] {
+  const existing = transforms.find((t) => t.id === next.id)
+  if (
+    existing?.order === next.order &&
+    existing?.enabled === next.enabled &&
+    existing?.fn === next.fn &&
+    existing?.type === next.type &&
+    sameStringArray(existing?.disables, next.disables) &&
+    sameStringArray(existing?.replaceMergeKeys, next.replaceMergeKeys)
+  ) {
+    return transforms
+  }
+  const filtered = transforms.filter((t) => t.id !== next.id)
+  const idx = filtered.findIndex((t) => t.order > next.order)
+  const out = filtered.slice()
+  out.splice(idx === -1 ? out.length : idx, 0, next)
+  return out
+}
+
+export function removeTransform(
+  transforms: readonly Transform[],
+  id: string,
+): readonly Transform[] {
+  if (!transforms.some((t) => t.id === id)) return transforms
+  return transforms.filter((t) => t.id !== id)
+}
+
+function sameStringArray(
+  a?: readonly string[],
+  b?: readonly string[],
+): boolean {
+  if (a === b) return true
+  if (!a) return !b?.length
+  if (!b) return !a.length
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
+  return true
+}

package/src/widgets-v2/stores/types.ts

@@ -0,0 +1,64 @@
+import type { StoreApi } from 'zustand'
+
+export type TransformType = 'data' | 'config'
+
+export interface TransformDescriptor {
+  id: string
+  type: TransformType
+  order: number
+  disables?: string[]
+  replaceMergeKeys?: string[]
+}
+
+export type TransformFn = (input: unknown) => unknown
+
+export interface Transform extends TransformDescriptor {
+  fn: TransformFn
+  enabled: boolean
+}
+
+export interface TransformPair {
+  descriptor: TransformDescriptor
+  fn: TransformFn
+}
+
+export interface WidgetState {
+  rawData: unknown
+  data: unknown
+
+  dataTransforms: readonly Transform[]
+  configTransforms: readonly Transform[]
+
+  transformStates: Record<string, { enabled: boolean; [k: string]: unknown }>
+
+  isLoading: boolean
+  isFetching: boolean
+  error: unknown
+
+  /**
+   * Original formatter as supplied by the consumer (Provider's `formatter`
+   * prop). Always live-synced — never overridden by actions. Actions that need
+   * to display a different formatter (e.g. {@link RelativeData}'s percent
+   * formatter) should write to {@link WidgetState.formatter} and read this
+   * field when restoring the absolute view.
+   */
+  rawFormatter?: (value: number) => string
+  /**
+   * Active formatter — what consumer code (tooltips, axis labels, legends,
+   * etc.) reads. Defaults to {@link WidgetState.rawFormatter}; actions may
+   * override it temporarily and restore it from `rawFormatter` later.
+   */
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
+
+export interface WidgetInit {
+  data: unknown
+  isLoading?: boolean
+  isFetching?: boolean
+  error?: unknown
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
+
+export type WidgetStoreApi = StoreApi<WidgetState>

package/src/widgets-v2/stores/use-echart-instance.test.tsx

@@ -0,0 +1,91 @@
+import { useEffect } from 'react'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { act, render } from '@testing-library/react'
+import type { ECharts } from 'echarts'
+import { useEchartInstance } from './use-echart-instance'
+import {
+  clearAllWidgetStores,
+  setEchartInstance,
+} from './widget-store-registry'
+
+const captured: { value: ECharts | null; renders: number } = {
+  value: null,
+  renders: 0,
+}
+
+function Probe({ id }: { id: string }) {
+  const chart = useEchartInstance(id)
+  // Capture in an effect so the React Compiler doesn't flag the
+  // outside-component mutations during render.
+  useEffect(() => {
+    captured.value = chart
+    captured.renders += 1
+  })
+  return null
+}
+
+beforeEach(() => {
+  clearAllWidgetStores()
+  captured.value = null
+  captured.renders = 0
+})
+afterEach(() => clearAllWidgetStores())
+
+function makeChart(): ECharts {
+  return {} as unknown as ECharts
+}
+
+describe('useEchartInstance', () => {
+  it('returns null when no instance is registered', () => {
+    render(<Probe id='h1' />)
+    expect(captured.value).toBeNull()
+  })
+
+  it('re-renders the consumer when the instance arrives', () => {
+    render(<Probe id='h2' />)
+    const initialRenders = captured.renders
+    const chart = makeChart()
+    act(() => setEchartInstance('h2', chart))
+    expect(captured.value).toBe(chart)
+    expect(captured.renders).toBeGreaterThan(initialRenders)
+  })
+
+  it('re-renders again when the instance changes', () => {
+    render(<Probe id='h3' />)
+    const a = makeChart()
+    const b = makeChart()
+    act(() => setEchartInstance('h3', a))
+    expect(captured.value).toBe(a)
+    act(() => setEchartInstance('h3', b))
+    expect(captured.value).toBe(b)
+  })
+
+  it('re-renders with null when the instance is cleared', () => {
+    render(<Probe id='h4' />)
+    act(() => setEchartInstance('h4', makeChart()))
+    expect(captured.value).not.toBeNull()
+    act(() => setEchartInstance('h4', null))
+    expect(captured.value).toBeNull()
+  })
+
+  it('isolates ids', () => {
+    const latest: { a: ECharts | null; b: ECharts | null } = {
+      a: null,
+      b: null,
+    }
+    function ProbeMulti() {
+      const a = useEchartInstance('h5-a')
+      const b = useEchartInstance('h5-b')
+      useEffect(() => {
+        latest.a = a
+        latest.b = b
+      })
+      return null
+    }
+    render(<ProbeMulti />)
+    const aChart = makeChart()
+    act(() => setEchartInstance('h5-a', aChart))
+    expect(latest.a).toBe(aChart)
+    expect(latest.b).toBeNull()
+  })
+})

package/src/widgets-v2/stores/use-echart-instance.ts

@@ -0,0 +1,29 @@
+import { useSyncExternalStore } from 'react'
+import type { ECharts } from 'echarts'
+import {
+  getEchartInstance,
+  subscribeEchartInstance,
+} from './widget-store-registry'
+
+const SSR_SNAPSHOT = (): ECharts | null => null
+
+/**
+ * Reactive read of the live ECharts instance for a widget. Returns
+ * `null` before the `Widget.Echart` bridge has mounted (or after it's
+ * disposed); the consumer re-renders when the instance arrives /
+ * departs / changes.
+ *
+ * Wraps {@link subscribeEchartInstance} via `useSyncExternalStore`, so
+ * actions can use it inside an effect's deps array to react to chart
+ * lifecycle events without polling. Required for actions like
+ * `BrushToggle` whose effect needs to dispatch `takeGlobalCursor` the
+ * moment the chart exists, then re-dispatch on every `'finished'`
+ * event.
+ */
+export function useEchartInstance(id: string): ECharts | null {
+  return useSyncExternalStore(
+    (cb) => subscribeEchartInstance(id, cb),
+    () => getEchartInstance(id),
+    SSR_SNAPSHOT,
+  )
+}