@carto/ps-react-ui 4.7.1 → 4.9.0

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

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