@carto/ps-react-ui 5.0.0-widgets.9 → 5.0.0

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,
+  )
+}

package/src/widgets-v2/stores/use-transform-enabled.test.tsx

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { act, render } from '@testing-library/react'
+import { Provider } from '../provider/widget-provider'
+import { clearAllWidgetStores, getWidgetStore } from './widget-store-registry'
+import { useTransformEnabled } from './use-transform-enabled'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+function Probe({
+  id,
+  transformId,
+  onValue,
+}: {
+  id: string
+  transformId: string
+  onValue: (v: boolean) => void
+}) {
+  const enabled = useTransformEnabled(id, transformId)
+  onValue(enabled)
+  return null
+}
+
+describe('useTransformEnabled', () => {
+  it('returns false when the transform has not been registered', () => {
+    const calls: boolean[] = []
+    render(
+      <Provider id='ute-1' data={null}>
+        <Probe
+          id='ute-1'
+          transformId='searcher'
+          onValue={(v) => calls.push(v)}
+        />
+      </Provider>,
+    )
+    expect(calls[calls.length - 1]).toBe(false)
+  })
+
+  it('returns true when `transformStates.<id>.enabled` is true; updates reactively', () => {
+    const calls: boolean[] = []
+    render(
+      <Provider id='ute-2' data={null}>
+        <Probe
+          id='ute-2'
+          transformId='searcher'
+          onValue={(v) => calls.push(v)}
+        />
+      </Provider>,
+    )
+    // Initial — no transform registered.
+    expect(calls[calls.length - 1]).toBe(false)
+
+    // Simulate SearcherToggle enabling itself.
+    act(() => {
+      const store = getWidgetStore('ute-2')
+      store.setState({
+        transformStates: {
+          ...store.getState().transformStates,
+          searcher: { enabled: true },
+        },
+      })
+    })
+    expect(calls[calls.length - 1]).toBe(true)
+
+    // Disable.
+    act(() => {
+      const store = getWidgetStore('ute-2')
+      store.setState({
+        transformStates: {
+          ...store.getState().transformStates,
+          searcher: { enabled: false },
+        },
+      })
+    })
+    expect(calls[calls.length - 1]).toBe(false)
+  })
+
+  it('returns false when `enabled` is a non-true truthy value (strict boolean check)', () => {
+    // Defensive: the helper uses `=== true`, so non-boolean truthy values
+    // shouldn't accidentally activate features. Guards against future
+    // store-shape drift.
+    const calls: boolean[] = []
+    render(
+      <Provider id='ute-3' data={null}>
+        <Probe
+          id='ute-3'
+          transformId='searcher'
+          onValue={(v) => calls.push(v)}
+        />
+      </Provider>,
+    )
+    act(() => {
+      const store = getWidgetStore('ute-3')
+      store.setState({
+        transformStates: {
+          ...store.getState().transformStates,
+          // @ts-expect-error — intentional shape violation for the boundary test.
+          searcher: { enabled: 'yes' },
+        },
+      })
+    })
+    expect(calls[calls.length - 1]).toBe(false)
+  })
+
+  it('returns false for an unknown transform id while others are enabled', () => {
+    const calls: boolean[] = []
+    render(
+      <Provider id='ute-4' data={null}>
+        <Probe
+          id='ute-4'
+          transformId='not-a-real-transform'
+          onValue={(v) => calls.push(v)}
+        />
+      </Provider>,
+    )
+    act(() => {
+      const store = getWidgetStore('ute-4')
+      store.setState({
+        transformStates: {
+          ...store.getState().transformStates,
+          searcher: { enabled: true },
+        },
+      })
+    })
+    expect(calls[calls.length - 1]).toBe(false)
+  })
+})

package/src/widgets-v2/stores/use-transform-enabled.ts

@@ -0,0 +1,25 @@
+import { useWidgetShallow } from './widget-store-registry'
+import type { WidgetState } from './types'
+
+/**
+ * Reactive read of a single transform's `enabled` flag from the
+ * per-widget store. Returns `false` if the transform hasn't been
+ * registered yet (i.e., the action component hasn't mounted) — safe
+ * default for "the feature is off".
+ *
+ * Used by widget composers that want to react to an action's on/off
+ * cycle without having the widget primitive import the action. For
+ * example, the `CategoryWidget` storybook composer wires the
+ * SearcherToggle's open state into `<Widget.Category searcherOpen=…>`
+ * so the library primitive stays renderer-agnostic.
+ *
+ * Magic-string `transformId` is intentional — it lives at the composer
+ * layer where the action is already imported by JSX, so the string
+ * appears alongside the same name in the toolbox.
+ */
+export function useTransformEnabled(id: string, transformId: string): boolean {
+  return useWidgetShallow(
+    id,
+    (s: WidgetState) => s.transformStates?.[transformId]?.enabled === true,
+  )
+}

package/src/widgets-v2/stores/use-transform.test.tsx

@@ -0,0 +1,262 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { act, render } from '@testing-library/react'
+import {
+  clearAllWidgetStores,
+  createWidgetStore,
+  registerWidgetStore,
+  getWidgetStore,
+} from './widget-store-registry'
+import {
+  useSingleTransform,
+  useTransform,
+  type TransformControls,
+} from './use-transform'
+import { applyTransforms } from './transforms'
+import type { TransformDescriptor, TransformFn } from './types'
+
+function setup(id = 'wt-test') {
+  const store = createWidgetStore(id, { data: 1 })
+  registerWidgetStore(id, store)
+  return store
+}
+
+const captureRef: { current: TransformControls | null } = { current: null }
+const onControls = (c: TransformControls): void => {
+  captureRef.current = c
+}
+const getCaptured = (): TransformControls | null => captureRef.current
+
+function Single({
+  id,
+  descriptor,
+  fn,
+  initialEnabled,
+}: {
+  id: string
+  descriptor: TransformDescriptor
+  fn: TransformFn
+  initialEnabled?: boolean
+}) {
+  const controls = useSingleTransform(id, descriptor, fn, { initialEnabled })
+  onControls(controls)
+  return null
+}
+
+function Multi({
+  id,
+  pairs,
+  initialEnabled,
+}: {
+  id: string
+  pairs: readonly { descriptor: TransformDescriptor; fn: TransformFn }[]
+  initialEnabled?: boolean
+}) {
+  const controls = useTransform(id, pairs, { initialEnabled })
+  onControls(controls)
+  return null
+}
+
+beforeEach(() => {
+  clearAllWidgetStores()
+  captureRef.current = null
+})
+
+afterEach(() => {
+  clearAllWidgetStores()
+})
+
+describe('useSingleTransform', () => {
+  it('registers the transform on mount with enabled=true by default', () => {
+    setup()
+    render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'a', type: 'data', order: 1 }}
+        fn={(n) => (n as number) * 2}
+      />,
+    )
+    expect(captureRef.current?.enabled).toBe(true)
+    expect(
+      getWidgetStore('wt-test')
+        .getState()
+        .dataTransforms.map((t) => t.id),
+    ).toEqual(['a'])
+    expect(getWidgetStore('wt-test').getState().data).toBe(2)
+  })
+
+  it('respects initialEnabled=false', () => {
+    setup()
+    render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'a', type: 'data', order: 1 }}
+        fn={(n) => (n as number) * 2}
+        initialEnabled={false}
+      />,
+    )
+    expect(captureRef.current?.enabled).toBe(false)
+    expect(getWidgetStore('wt-test').getState().data).toBe(1)
+  })
+
+  it('toggle flips enabled and re-runs the pipeline', () => {
+    setup()
+    render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'a', type: 'data', order: 1 }}
+        fn={(n) => (n as number) * 2}
+      />,
+    )
+    act(() => captureRef.current?.toggle())
+    expect(captureRef.current?.enabled).toBe(false)
+    expect(getWidgetStore('wt-test').getState().data).toBe(1)
+    act(() => captureRef.current?.toggle())
+    expect(captureRef.current?.enabled).toBe(true)
+    expect(getWidgetStore('wt-test').getState().data).toBe(2)
+  })
+
+  it('persists enabled to transformStates', () => {
+    setup()
+    render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'a', type: 'data', order: 1 }}
+        fn={(n) => n}
+      />,
+    )
+    act(() => captureRef.current?.setEnabled(false))
+    expect(
+      getWidgetStore('wt-test').getState().transformStates.a,
+    ).toMatchObject({ enabled: false })
+  })
+
+  it('rehydrates enabled from transformStates on remount', () => {
+    setup()
+    const { unmount } = render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'a', type: 'data', order: 1 }}
+        fn={(n) => n}
+        initialEnabled={true}
+      />,
+    )
+    act(() => captureRef.current?.setEnabled(false))
+    unmount()
+    captureRef.current = null
+    render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'a', type: 'data', order: 1 }}
+        fn={(n) => n}
+        initialEnabled={true}
+      />,
+    )
+    expect(getCaptured()?.enabled).toBe(false)
+  })
+
+  it('cleanup removes the transform on unmount', () => {
+    setup()
+    const { unmount } = render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'a', type: 'data', order: 1 }}
+        fn={(n) => n}
+      />,
+    )
+    expect(getWidgetStore('wt-test').getState().dataTransforms).toHaveLength(1)
+    unmount()
+    expect(getWidgetStore('wt-test').getState().dataTransforms).toHaveLength(0)
+  })
+
+  it('updates the registered fn when fn identity changes across renders', () => {
+    setup()
+    function Wrap({ multiplier }: { multiplier: number }) {
+      return (
+        <Single
+          id='wt-test'
+          descriptor={{ id: 'a', type: 'data', order: 1 }}
+          fn={(n) => (n as number) * multiplier}
+        />
+      )
+    }
+    const { rerender } = render(<Wrap multiplier={2} />)
+    expect(getWidgetStore('wt-test').getState().data).toBe(2)
+    rerender(<Wrap multiplier={5} />)
+    expect(getWidgetStore('wt-test').getState().data).toBe(5)
+  })
+
+  it('config-type descriptor registers into configTransforms', () => {
+    setup()
+    render(
+      <Single
+        id='wt-test'
+        descriptor={{ id: 'c', type: 'config', order: 1 }}
+        fn={(o) => ({ ...(o as object), x: 1 })}
+      />,
+    )
+    const cfgTransforms = getWidgetStore('wt-test').getState().configTransforms
+    expect(cfgTransforms.map((t) => t.id)).toEqual(['c'])
+    expect(applyTransforms({}, cfgTransforms)).toEqual({ x: 1 })
+  })
+})
+
+describe('useTransform (multi)', () => {
+  it('registers paired data + config transforms with shared enabled', () => {
+    setup()
+    render(
+      <Multi
+        id='wt-test'
+        pairs={[
+          {
+            descriptor: { id: 'rd-data', type: 'data', order: 1 },
+            fn: (n) => (n as number) + 10,
+          },
+          {
+            descriptor: { id: 'rd-config', type: 'config', order: 1 },
+            fn: (o) => ({ ...(o as object), tag: 'rel' }),
+          },
+        ]}
+      />,
+    )
+    const s = getWidgetStore('wt-test').getState()
+    expect(s.dataTransforms.map((t) => t.id)).toEqual(['rd-data'])
+    expect(s.configTransforms.map((t) => t.id)).toEqual(['rd-config'])
+    expect(s.data).toBe(11)
+    expect(applyTransforms({}, s.configTransforms)).toEqual({ tag: 'rel' })
+  })
+
+  it('toggle affects every paired transform together', () => {
+    setup()
+    render(
+      <Multi
+        id='wt-test'
+        pairs={[
+          {
+            descriptor: { id: 'rd-data', type: 'data', order: 1 },
+            fn: (n) => (n as number) + 10,
+          },
+          {
+            descriptor: { id: 'rd-config', type: 'config', order: 1 },
+            fn: (o) => ({ ...(o as object), tag: 'rel' }),
+          },
+        ]}
+      />,
+    )
+    act(() => captureRef.current?.toggle())
+    const s = getWidgetStore('wt-test').getState()
+    expect(s.dataTransforms.every((t) => !t.enabled)).toBe(true)
+    expect(s.configTransforms.every((t) => !t.enabled)).toBe(true)
+    expect(s.data).toBe(1)
+    // All config transforms disabled — applying them to {} leaves it untouched.
+    expect(applyTransforms({}, s.configTransforms)).toEqual({})
+  })
+
+  it('throws when no pair is provided', () => {
+    setup()
+    function NoPairs() {
+      useTransform('wt-test', [])
+      return null
+    }
+    expect(() => render(<NoPairs />)).toThrow(/at least one pair/)
+  })
+})