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

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

@@ -0,0 +1,158 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type Dispatch,
+  type SetStateAction,
+} from 'react'
+import { useStore } from 'zustand'
+import { getWidgetStore } from './widget-store-registry'
+import { removeTransform, upsertTransform } from './transforms'
+import type {
+  Transform,
+  TransformDescriptor,
+  TransformFn,
+  TransformPair,
+  WidgetState,
+} from './types'
+
+export interface UseTransformOptions {
+  initialEnabled?: boolean
+}
+
+export interface TransformControls {
+  enabled: boolean
+  setEnabled: Dispatch<SetStateAction<boolean>>
+  toggle: () => void
+}
+
+type RegistrationKey = 'dataTransforms' | 'configTransforms'
+
+interface Registration {
+  key: RegistrationKey
+  id: string
+}
+
+export function useTransform(
+  id: string,
+  pairs: readonly TransformPair[],
+  options?: UseTransformOptions,
+): TransformControls {
+  if (pairs.length === 0) {
+    throw new Error('[widgets-v2] useTransform requires at least one pair.')
+  }
+
+  const store = getWidgetStore(id)
+  const primaryId = pairs[0]!.descriptor.id
+  const initialEnabled = options?.initialEnabled ?? true
+
+  // Read `enabled` reactively from the store. Multiple mounts of the same
+  // descriptor (e.g., Toolbox renders ZoomToggle both in the inline preview
+  // and inside its overflow Paper) stay in sync because they share the
+  // `transformStates[primaryId].enabled` slot.
+  const persisted = useStore(
+    store,
+    (s) => s.transformStates[primaryId]?.enabled,
+  )
+  const enabled = typeof persisted === 'boolean' ? persisted : initialEnabled
+
+  // Seed the store's `transformStates[primaryId].enabled` on first mount so
+  // subsequent reads (and a rehydration after `keepAlive` remounts) have a
+  // canonical value to read from. Idempotent: skip when already set.
+  useEffect(() => {
+    if (typeof persisted === 'boolean') return
+    store.setState((s: WidgetState) => ({
+      transformStates: {
+        ...s.transformStates,
+        [primaryId]: {
+          ...s.transformStates[primaryId],
+          enabled: initialEnabled,
+        },
+      },
+    }))
+  }, [store, primaryId, persisted, initialEnabled])
+
+  const setEnabled = useCallback<Dispatch<SetStateAction<boolean>>>(
+    (next) => {
+      store.setState((s: WidgetState) => {
+        const current = s.transformStates[primaryId]?.enabled ?? initialEnabled
+        const value =
+          typeof next === 'function'
+            ? (next as (v: boolean) => boolean)(current)
+            : next
+        if (value === current) return {}
+        return {
+          transformStates: {
+            ...s.transformStates,
+            [primaryId]: {
+              ...s.transformStates[primaryId],
+              enabled: value,
+            },
+          },
+        }
+      })
+    },
+    [store, primaryId, initialEnabled],
+  )
+
+  // Track the latest registrations so the unmount cleanup knows what to remove.
+  // Updated inside the register effect (post-render), never during render.
+  const registeredRef = useRef<Registration[]>([])
+
+  // Register / re-register when `pairs` reference or `enabled` changes.
+  // upsertTransform is identity-stable: re-registering with an unchanged
+  // descriptor + fn returns the same array reference, and the middleware
+  // bypasses the pipeline for unchanged refs. Consumers should memoize
+  // `pairs` (useSingleTransform does this internally; multi-pair consumers
+  // should wrap the pairs array in useMemo).
+  useEffect(() => {
+    const next: Registration[] = []
+    for (const { descriptor, fn } of pairs) {
+      const key: RegistrationKey =
+        descriptor.type === 'data' ? 'dataTransforms' : 'configTransforms'
+      const transform: Transform = { ...descriptor, fn, enabled }
+      store.setState(
+        (s: WidgetState) =>
+          ({
+            [key]: upsertTransform(s[key], transform),
+          }) as Partial<WidgetState>,
+      )
+      next.push({ key, id: descriptor.id })
+    }
+    registeredRef.current = next
+  }, [store, pairs, enabled])
+
+  // Unmount cleanup — remove every currently-registered descriptor. Reads from
+  // the ref so we always remove the latest registrations, not a stale snapshot.
+  useEffect(() => {
+    return () => {
+      for (const { key, id: descriptorId } of registeredRef.current) {
+        store.setState(
+          (s: WidgetState) =>
+            ({
+              [key]: removeTransform(s[key], descriptorId),
+            }) as Partial<WidgetState>,
+        )
+      }
+      registeredRef.current = []
+    }
+  }, [store])
+
+  const toggle = useCallback(() => setEnabled((v) => !v), [setEnabled])
+
+  return { enabled, setEnabled, toggle }
+}
+
+export function useSingleTransform(
+  id: string,
+  descriptor: TransformDescriptor,
+  fn: TransformFn,
+  options?: UseTransformOptions,
+): TransformControls {
+  const pairs = useMemo<readonly TransformPair[]>(
+    () => [{ descriptor, fn }],
+    [descriptor, fn],
+  )
+  return useTransform(id, pairs, options)
+}

package/src/widgets-v2/stores/widget-context.test.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import { WidgetContext, useWidgetId } from './widget-context'
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = (): void => {}
+
+function Probe({ onId }: { onId: (id: string) => void }) {
+  onId(useWidgetId())
+  return null
+}
+
+describe('useWidgetId', () => {
+  it('throws a clear error when called outside a WidgetContext', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(noop)
+    expect(() => render(<Probe onId={noop} />)).toThrow(
+      /useWidgetId\(\) must be called inside <Widget\.Provider>/,
+    )
+    spy.mockRestore()
+  })
+
+  it('returns the id from the surrounding context', () => {
+    let captured = ''
+    render(
+      <WidgetContext.Provider value='test-id'>
+        <Probe onId={(id) => (captured = id)} />
+      </WidgetContext.Provider>,
+    )
+    expect(captured).toBe('test-id')
+  })
+
+  it('isolates ids across sibling Providers', () => {
+    const ids: string[] = []
+    render(
+      <>
+        <WidgetContext.Provider value='a'>
+          <Probe onId={(id) => ids.push(id)} />
+        </WidgetContext.Provider>
+        <WidgetContext.Provider value='b'>
+          <Probe onId={(id) => ids.push(id)} />
+        </WidgetContext.Provider>
+      </>,
+    )
+    expect(ids).toEqual(['a', 'b'])
+  })
+
+  it('inner Provider value shadows outer', () => {
+    let captured = ''
+    render(
+      <WidgetContext.Provider value='outer'>
+        <WidgetContext.Provider value='inner'>
+          <Probe onId={(id) => (captured = id)} />
+        </WidgetContext.Provider>
+      </WidgetContext.Provider>,
+    )
+    expect(captured).toBe('inner')
+  })
+})

package/src/widgets-v2/stores/widget-context.ts

@@ -0,0 +1,15 @@
+import { createContext, useContext } from 'react'
+
+export const WidgetContext = createContext<string | null>(null)
+
+export function useWidgetId(): string {
+  const id = useContext(WidgetContext)
+  if (id == null) {
+    throw new Error(
+      'useWidgetId() must be called inside <Widget.Provider>. ' +
+        'If you are calling from outside the Provider tree, use the hooks ' +
+        '(useWidget, useWidgetShallow, useTransform) directly with an explicit id.',
+    )
+  }
+  return id
+}

package/src/widgets-v2/stores/widget-store-registry.test.ts

@@ -0,0 +1,292 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = (): void => {}
+
+import {
+  __debugListWidgetStores,
+  clearAllCaptureEls,
+  clearAllEchartInstances,
+  clearAllWidgetStores,
+  createWidgetStore,
+  deleteWidgetStore,
+  getCaptureEl,
+  getEchartInstance,
+  getWidgetStore,
+  hasWidgetStore,
+  registerWidgetStore,
+  resetWidgetStore,
+  setCaptureEl,
+  setEchartInstance,
+  subscribeEchartInstance,
+  unregisterWidgetStore,
+} from './widget-store-registry'
+import type { ECharts } from 'echarts'
+
+describe('widget-store-registry', () => {
+  beforeEach(() => clearAllWidgetStores())
+  afterEach(() => clearAllWidgetStores())
+
+  it('register + get round-trip', () => {
+    const s = createWidgetStore('w1', { data: 1 })
+    registerWidgetStore('w1', s)
+    expect(getWidgetStore('w1')).toBe(s)
+    expect(hasWidgetStore('w1')).toBe(true)
+  })
+
+  it('getWidgetStore throws for unknown id', () => {
+    expect(() => getWidgetStore('missing')).toThrow(
+      /Widget store "missing" not found/,
+    )
+  })
+
+  it('isolates state across stores', () => {
+    const a = createWidgetStore('a', { data: 1 })
+    const b = createWidgetStore('b', { data: 2 })
+    registerWidgetStore('a', a)
+    registerWidgetStore('b', b)
+    a.setState({ rawData: 10 })
+    expect(b.getState().rawData).toBe(2)
+  })
+
+  it('deleteWidgetStore removes the store from the registry', () => {
+    const s = createWidgetStore('w', { data: 1 })
+    registerWidgetStore('w', s)
+    deleteWidgetStore('w')
+    expect(hasWidgetStore('w')).toBe(false)
+  })
+
+  it('resetWidgetStore clears transformStates and keeps the store', () => {
+    const s = createWidgetStore('w', { data: 1 })
+    registerWidgetStore('w', s)
+    s.setState({ transformStates: { foo: { enabled: true } } })
+    resetWidgetStore('w')
+    expect(s.getState().transformStates).toEqual({})
+    expect(hasWidgetStore('w')).toBe(true)
+  })
+
+  it('clearAllWidgetStores empties everything', () => {
+    registerWidgetStore('a', createWidgetStore('a', { data: 1 }))
+    registerWidgetStore('b', createWidgetStore('b', { data: 2 }))
+    clearAllWidgetStores()
+    expect(__debugListWidgetStores()).toEqual([])
+  })
+
+  it('unregisterWidgetStore drops the store on last unmount when keepAlive is false', () => {
+    registerWidgetStore('w', createWidgetStore('w', { data: 1 }))
+    unregisterWidgetStore('w', { keepAlive: false })
+    expect(hasWidgetStore('w')).toBe(false)
+  })
+
+  it('unregisterWidgetStore preserves the store when keepAlive is true', () => {
+    registerWidgetStore('w', createWidgetStore('w', { data: 1 }))
+    unregisterWidgetStore('w', { keepAlive: true })
+    expect(hasWidgetStore('w')).toBe(true)
+  })
+
+  it('refcounts overlapping registers — store stays until both unregister', () => {
+    const s = createWidgetStore('w', { data: 1 })
+    registerWidgetStore('w', s)
+    registerWidgetStore('w', s)
+    unregisterWidgetStore('w', { keepAlive: false })
+    expect(hasWidgetStore('w')).toBe(true)
+    unregisterWidgetStore('w', { keepAlive: false })
+    expect(hasWidgetStore('w')).toBe(false)
+  })
+
+  it('warns once on duplicate concurrent registration with the same id', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(noop)
+    const s = createWidgetStore('dup', { data: 1 })
+    registerWidgetStore('dup', s)
+    registerWidgetStore('dup', s)
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(warn.mock.calls[0]?.[0]).toMatch(
+      /Duplicate <Widget.Provider id="dup">/,
+    )
+    warn.mockRestore()
+  })
+
+  it('does not warn again on subsequent re-registrations after the first warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(noop)
+    const s = createWidgetStore('dup', { data: 1 })
+    registerWidgetStore('dup', s)
+    registerWidgetStore('dup', s)
+    registerWidgetStore('dup', s)
+    expect(warn).toHaveBeenCalledTimes(1)
+    warn.mockRestore()
+  })
+
+  it('createWidgetStore seeds rawData/data from init.data', () => {
+    const s = createWidgetStore('w', { data: { x: 1 } })
+    expect(s.getState().rawData).toEqual({ x: 1 })
+    expect(s.getState().data).toEqual({ x: 1 })
+  })
+
+  it('createWidgetStore seeds isLoading/isFetching defaults to false', () => {
+    const s = createWidgetStore('w', { data: 1 })
+    expect(s.getState().isLoading).toBe(false)
+    expect(s.getState().isFetching).toBe(false)
+  })
+
+  it('createWidgetStore preserves init.error', () => {
+    const err = { title: 'oops' }
+    const s = createWidgetStore('w', { data: 1, error: err })
+    expect(s.getState().error).toBe(err)
+  })
+
+  it('__debugListWidgetStores reflects registered ids', () => {
+    registerWidgetStore('a', createWidgetStore('a', { data: 1 }))
+    registerWidgetStore('b', createWidgetStore('b', { data: 1 }))
+    expect(__debugListWidgetStores().sort()).toEqual(['a', 'b'])
+  })
+
+  describe('capture-el registry', () => {
+    it('returns null for unregistered ids', () => {
+      expect(getCaptureEl('missing')).toBeNull()
+    })
+
+    it('round-trips a set value', () => {
+      const el = document.createElement('div')
+      setCaptureEl('w1', el)
+      expect(getCaptureEl('w1')).toBe(el)
+    })
+
+    it('clears when set to null', () => {
+      const el = document.createElement('div')
+      setCaptureEl('w1', el)
+      setCaptureEl('w1', null)
+      expect(getCaptureEl('w1')).toBeNull()
+    })
+
+    it('isolates ids', () => {
+      const a = document.createElement('div')
+      const b = document.createElement('section')
+      setCaptureEl('a', a)
+      setCaptureEl('b', b)
+      expect(getCaptureEl('a')).toBe(a)
+      expect(getCaptureEl('b')).toBe(b)
+    })
+
+    it('clearAllWidgetStores wipes the capture-el map too', () => {
+      setCaptureEl('w', document.createElement('div'))
+      clearAllWidgetStores()
+      expect(getCaptureEl('w')).toBeNull()
+    })
+
+    it('clearAllCaptureEls wipes only the capture-el map', () => {
+      registerWidgetStore('w', createWidgetStore('w', { data: 1 }))
+      setCaptureEl('w', document.createElement('div'))
+      clearAllCaptureEls()
+      expect(getCaptureEl('w')).toBeNull()
+      expect(hasWidgetStore('w')).toBe(true)
+    })
+  })
+
+  describe('echart-instance registry', () => {
+    function makeChart(): ECharts {
+      // Minimal stand-in — only the methods used by registry tests need to
+      // exist. Cast through unknown to keep the signature opaque.
+      return {} as unknown as ECharts
+    }
+
+    it('returns null for unregistered ids', () => {
+      expect(getEchartInstance('missing')).toBeNull()
+    })
+
+    it('round-trips a set value', () => {
+      const chart = makeChart()
+      setEchartInstance('w1', chart)
+      expect(getEchartInstance('w1')).toBe(chart)
+    })
+
+    it('clears when set to null', () => {
+      setEchartInstance('w1', makeChart())
+      setEchartInstance('w1', null)
+      expect(getEchartInstance('w1')).toBeNull()
+    })
+
+    it('isolates ids', () => {
+      const a = makeChart()
+      const b = makeChart()
+      setEchartInstance('a', a)
+      setEchartInstance('b', b)
+      expect(getEchartInstance('a')).toBe(a)
+      expect(getEchartInstance('b')).toBe(b)
+    })
+
+    it('clearAllWidgetStores wipes the echart-instance map too', () => {
+      setEchartInstance('w', makeChart())
+      clearAllWidgetStores()
+      expect(getEchartInstance('w')).toBeNull()
+    })
+
+    it('clearAllEchartInstances wipes only the echart-instance map', () => {
+      registerWidgetStore('w', createWidgetStore('w', { data: 1 }))
+      setEchartInstance('w', makeChart())
+      clearAllEchartInstances()
+      expect(getEchartInstance('w')).toBeNull()
+      expect(hasWidgetStore('w')).toBe(true)
+    })
+  })
+
+  describe('subscribeEchartInstance', () => {
+    function makeChart(): ECharts {
+      return {} as unknown as ECharts
+    }
+
+    it('fires the listener whenever setEchartInstance writes a new value', () => {
+      const seen: (ECharts | null)[] = []
+      const off = subscribeEchartInstance('s1', (chart) => seen.push(chart))
+      const a = makeChart()
+      const b = makeChart()
+      setEchartInstance('s1', a)
+      setEchartInstance('s1', b)
+      setEchartInstance('s1', null)
+      expect(seen).toEqual([a, b, null])
+      off()
+    })
+
+    it('the returned unsubscribe stops the listener', () => {
+      const fn = vi.fn()
+      const off = subscribeEchartInstance('s2', fn)
+      setEchartInstance('s2', makeChart())
+      off()
+      setEchartInstance('s2', makeChart())
+      expect(fn).toHaveBeenCalledTimes(1)
+    })
+
+    it('multiple listeners per id all fire', () => {
+      const a = vi.fn()
+      const b = vi.fn()
+      subscribeEchartInstance('s3', a)
+      subscribeEchartInstance('s3', b)
+      setEchartInstance('s3', makeChart())
+      expect(a).toHaveBeenCalledTimes(1)
+      expect(b).toHaveBeenCalledTimes(1)
+    })
+
+    it('listeners are isolated by id', () => {
+      const a = vi.fn()
+      const b = vi.fn()
+      subscribeEchartInstance('s4', a)
+      subscribeEchartInstance('s5', b)
+      setEchartInstance('s4', makeChart())
+      expect(a).toHaveBeenCalledTimes(1)
+      expect(b).not.toHaveBeenCalled()
+    })
+
+    it('clearAllEchartInstances and clearAllWidgetStores clear subscribers too', () => {
+      const fn = vi.fn()
+      subscribeEchartInstance('s6', fn)
+      clearAllEchartInstances()
+      setEchartInstance('s6', makeChart())
+      expect(fn).not.toHaveBeenCalled()
+
+      const fn2 = vi.fn()
+      subscribeEchartInstance('s7', fn2)
+      clearAllWidgetStores()
+      setEchartInstance('s7', makeChart())
+      expect(fn2).not.toHaveBeenCalled()
+    })
+  })
+})