@carto/ps-react-ui 4.7.1 → 4.9.0

package/src/widgets-v2/provider/widget-provider.test.tsx

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
+import { Provider } from './widget-provider'
+import {
+  clearAllWidgetStores,
+  getWidgetStore,
+  hasWidgetStore,
+  useWidgetId,
+} from '../stores'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+function ChildSpy({ onMount }: { onMount: (id: string) => void }) {
+  const id = useWidgetId()
+  onMount(id)
+  return null
+}
+
+describe('<Provider>', () => {
+  it('creates a store and exposes the id via context', () => {
+    const ids: string[] = []
+    render(
+      <Provider id='p1' data={{ x: 1 }}>
+        <ChildSpy onMount={(i) => ids.push(i)} />
+      </Provider>,
+    )
+    expect(ids).toEqual(['p1'])
+    expect(hasWidgetStore('p1')).toBe(true)
+    const s = getWidgetStore('p1').getState()
+    expect(s.rawData).toEqual({ x: 1 })
+    // Provider is renderer-agnostic — option pipeline state lives in
+    // `<Widget.Echart>`, not on the store.
+    expect(
+      (s as unknown as { rawOptions?: unknown }).rawOptions,
+    ).toBeUndefined()
+  })
+
+  it('removes the store on unmount when keepAlive is false (default)', () => {
+    const { unmount } = render(
+      <Provider id='p2' data={null}>
+        <span />
+      </Provider>,
+    )
+    unmount()
+    expect(hasWidgetStore('p2')).toBe(false)
+  })
+
+  it('preserves the store on unmount when keepAlive is true', () => {
+    const { unmount } = render(
+      <Provider id='p3' data={null} keepAlive>
+        <span />
+      </Provider>,
+    )
+    unmount()
+    expect(hasWidgetStore('p3')).toBe(true)
+  })
+
+  it('reuses an existing keepAlive store on remount and preserves transformStates', () => {
+    const { unmount } = render(
+      <Provider id='p4' data={null} keepAlive>
+        <span />
+      </Provider>,
+    )
+    getWidgetStore('p4').setState({
+      transformStates: { foo: { enabled: false } },
+    })
+    unmount()
+    render(
+      <Provider id='p4' data={null} keepAlive>
+        <span />
+      </Provider>,
+    )
+    expect(getWidgetStore('p4').getState().transformStates.foo).toEqual({
+      enabled: false,
+    })
+  })
+
+  it('syncs data / isLoading / error / formatter prop changes onto the store', () => {
+    const fmt = (n: number): string => `$${n}`
+    const { rerender } = render(
+      <Provider id='p5' data={1} formatter={fmt}>
+        <span />
+      </Provider>,
+    )
+    expect(getWidgetStore('p5').getState().rawData).toBe(1)
+    rerender(
+      <Provider
+        id='p5'
+        data={2}
+        isLoading
+        error={{ message: 'oops' }}
+        formatter={fmt}
+      >
+        <span />
+      </Provider>,
+    )
+    const s = getWidgetStore('p5').getState()
+    expect(s.rawData).toBe(2)
+    expect(s.isLoading).toBe(true)
+    expect(s.error).toEqual({ message: 'oops' })
+    expect(s.formatter).toBe(fmt)
+  })
+
+  it('descendants see the store on first render (sync registration in lazy init)', () => {
+    function Spy() {
+      const id = useWidgetId()
+      // If the store wasn't registered synchronously this would throw.
+      const data = getWidgetStore(id).getState().rawData
+      return <span data-testid='data'>{JSON.stringify(data)}</span>
+    }
+    const { getByTestId } = render(
+      <Provider id='p6' data={{ initial: true }}>
+        <Spy />
+      </Provider>,
+    )
+    expect(getByTestId('data').textContent).toBe('{"initial":true}')
+  })
+})

package/src/widgets-v2/provider/widget-provider.tsx

@@ -0,0 +1,111 @@
+import { useLayoutEffect, useState, type ReactNode } from 'react'
+import {
+  WidgetContext,
+  createWidgetStore,
+  hasWidgetStore,
+  getWidgetStore,
+  registerWidgetStore,
+  setWidgetStoreEntry,
+  unregisterWidgetStore,
+} from '../stores'
+import type { WidgetStoreApi } from '../stores'
+
+export interface ProviderProps {
+  id: string
+  data: unknown
+  isLoading?: boolean
+  isFetching?: boolean
+  error?: unknown
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+  /**
+   * When `true`, the per-widget store survives unmount so transformStates,
+   * search text, fullscreen state, etc. are preserved across remounts.
+   * Consumers using keepAlive must call `deleteWidgetStore(id)` themselves
+   * when the widget is permanently removed — there is no automatic GC.
+   */
+  keepAlive?: boolean
+  children: ReactNode
+}
+
+/**
+ * Renderer-agnostic widget shell. Creates a per-widget Zustand store
+ * keyed by `id`, syncs the consumer props (`data`, `isLoading`, `error`,
+ * `formatter`, …) onto it, and exposes the `id` via `WidgetContext` so
+ * descendants can resolve their store with `useWidgetId()`.
+ *
+ * The Provider deliberately doesn't know about ECharts — there's no
+ * `optionFactory` prop here. ECharts-backed widgets pass their factory
+ * to `<Widget.Echart optionFactory={…}>`, which owns the structural
+ * seed + the data-fusion render step entirely. Non-Echart widgets
+ * (Formula, Spread, Range, Table, Category, Markdown) just don't pass
+ * anything ECharts-shaped.
+ */
+export function Provider({
+  id,
+  data,
+  isLoading,
+  isFetching,
+  error,
+  formatter,
+  labelFormatter,
+  keepAlive = false,
+  children,
+}: ProviderProps) {
+  // Lazy init — reuse an existing keepAlive store, otherwise create one and
+  // synchronously place it in the registry so descendants can call
+  // useWidget(id, ...) on first render. Refcounting + dup-id detection happen
+  // in the mount layout-effect below.
+  const [store] = useState<WidgetStoreApi>(() => {
+    if (hasWidgetStore(id)) return getWidgetStore(id)
+    const created = createWidgetStore(id, {
+      data,
+      isLoading,
+      isFetching,
+      error,
+      formatter,
+      labelFormatter,
+    })
+    setWidgetStoreEntry(id, created)
+    return created
+  })
+
+  // Registration: refcount the mount for dup-id detection; unregister on
+  // unmount or when the id/store/keepAlive triple changes.
+  useLayoutEffect(() => {
+    registerWidgetStore(id, store)
+    return () => {
+      unregisterWidgetStore(id, { keepAlive })
+    }
+  }, [id, store, keepAlive])
+
+  // Per-prop sync. `useLayoutEffect` so kept-alive remounts apply incoming
+  // props before paint (no flash of stale data when reusing a store).
+  // The pipeline middleware bypasses unchanged fields, so unchanged props
+  // are a no-op even though setState is called every effect run.
+  useLayoutEffect(() => {
+    store.setState({ rawData: data })
+  }, [store, data])
+
+  useLayoutEffect(() => {
+    store.setState({
+      isLoading: isLoading ?? false,
+      isFetching: isFetching ?? false,
+      error,
+    })
+  }, [store, isLoading, isFetching, error])
+
+  // Sync the consumer's formatter prop to BOTH `rawFormatter` (kept canonical
+  // for actions that need to restore the absolute view) and `formatter` (the
+  // active value). Actions like RelativeData re-apply their override after
+  // `rawFormatter` changes.
+  useLayoutEffect(() => {
+    store.setState({
+      rawFormatter: formatter,
+      formatter,
+      labelFormatter,
+    })
+  }, [store, formatter, labelFormatter])
+
+  return <WidgetContext.Provider value={id}>{children}</WidgetContext.Provider>
+}

package/src/widgets-v2/range/index.ts

@@ -0,0 +1,4 @@
+export { Range, type RangeProps } from './range'
+export { RangeUI, type RangeUIProps } from './range-ui'
+export { RangeSkeleton, type RangeSkeletonProps } from './skeleton'
+export type { RangeDataItem, RangeWidgetData, RangeItemValue } from './types'

package/src/widgets-v2/range/range-ui.test.tsx

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { RangeUI } from './range-ui'
+
+describe('<RangeUI>', () => {
+  it('renders a two-thumb slider per item', () => {
+    render(<RangeUI items={[{ min: 0, max: 100, value: [20, 80] }]} />)
+    const sliders = screen.getAllByRole('slider')
+    expect(sliders).toHaveLength(2)
+    expect(sliders[0]?.getAttribute('aria-valuenow')).toBe('20')
+    expect(sliders[1]?.getAttribute('aria-valuenow')).toBe('80')
+  })
+
+  it('defaults the value to [min, max] when omitted', () => {
+    render(<RangeUI items={[{ min: 10, max: 90 }]} />)
+    const sliders = screen.getAllByRole('slider')
+    expect(sliders[0]?.getAttribute('aria-valuenow')).toBe('10')
+    expect(sliders[1]?.getAttribute('aria-valuenow')).toBe('90')
+  })
+
+  it('renders editable min/max text inputs below the slider', () => {
+    render(<RangeUI items={[{ min: 0, max: 100, value: [20, 80] }]} />)
+    const min = screen.getByLabelText<HTMLInputElement>('Minimum value')
+    const max = screen.getByLabelText<HTMLInputElement>('Maximum value')
+    expect(min).toBeTruthy()
+    expect(max).toBeTruthy()
+    // The displayed value passes through the formatter (default toString).
+    expect(min.value).toBe('20')
+    expect(max.value).toBe('80')
+  })
+
+  it('runs the formatter through the text inputs', () => {
+    render(
+      <RangeUI
+        items={[{ min: 0, max: 1000, value: [100, 900] }]}
+        formatter={(n) => `$${n}`}
+      />,
+    )
+    const min = screen.getByLabelText<HTMLInputElement>('Minimum value')
+    const max = screen.getByLabelText<HTMLInputElement>('Maximum value')
+    expect(min.value).toBe('$100')
+    expect(max.value).toBe('$900')
+  })
+
+  it('renders a caption below the inputs when `note` is provided', () => {
+    render(
+      <RangeUI
+        items={[{ min: 0, max: 100, value: [25, 75], note: 'Filter window' }]}
+      />,
+    )
+    expect(screen.getByText('Filter window')).toBeTruthy()
+  })
+
+  it('renders multiple sliders stacked', () => {
+    render(
+      <RangeUI
+        items={[
+          { min: 0, max: 100, value: [10, 50], note: 'A' },
+          { min: 0, max: 100, value: [25, 75], note: 'B' },
+          { min: 0, max: 50, value: [10, 30], note: 'C' },
+        ]}
+      />,
+    )
+    expect(screen.getByText('A')).toBeTruthy()
+    expect(screen.getByText('B')).toBeTruthy()
+    expect(screen.getByText('C')).toBeTruthy()
+    // Three two-thumb sliders → 6 thumbs total.
+    expect(screen.getAllByRole('slider')).toHaveLength(6)
+  })
+
+  it('fires onChange with the item index and a clamped [low, high] tuple', () => {
+    const onChange = vi.fn()
+    render(
+      <RangeUI
+        items={[
+          { min: 0, max: 100, value: [10, 90] },
+          { min: 0, max: 100, value: [20, 80] },
+        ]}
+        onChange={onChange}
+      />,
+    )
+    // Drag the second item's lower thumb to 42.
+    const sliders = screen.getAllByRole('slider')
+    fireEvent.change(sliders[2]!, { target: { value: '42' } })
+    expect(onChange).toHaveBeenCalled()
+    const call = onChange.mock.calls[0] as [number, readonly [number, number]]
+    expect(call[0]).toBe(1)
+    expect(Array.isArray(call[1])).toBe(true)
+    expect(call[1]).toHaveLength(2)
+  })
+
+  it('respects per-item disabled on both slider and inputs', () => {
+    render(
+      <RangeUI
+        items={[{ min: 0, max: 100, value: [10, 90], disabled: true }]}
+      />,
+    )
+    const sliders = screen.getAllByRole('slider')
+    expect(sliders[0]?.hasAttribute('disabled')).toBe(true)
+    expect(sliders[1]?.hasAttribute('disabled')).toBe(true)
+    expect(
+      screen.getByLabelText('Minimum value').hasAttribute('disabled'),
+    ).toBe(true)
+    expect(
+      screen.getByLabelText('Maximum value').hasAttribute('disabled'),
+    ).toBe(true)
+  })
+
+  it('commits a typed value on Enter (fires both onChange and onChangeCommitted), clamped to [min, max]', () => {
+    // A text-input edit is both a value change and a final commit, so it
+    // notifies `onChange` AND `onChangeCommitted` — consumers that only wired
+    // `onChange` (the pre-`onChangeCommitted` API) still update.
+    const onChange = vi.fn()
+    const onChangeCommitted = vi.fn()
+    render(
+      <RangeUI
+        items={[{ min: 0, max: 100, value: [10, 90] }]}
+        onChange={onChange}
+        onChangeCommitted={onChangeCommitted}
+      />,
+    )
+    const min = screen.getByLabelText('Minimum value')
+    // Type 150 — should clamp to max (100), then preserve ordering (low <= high).
+    fireEvent.change(min, { target: { value: '150' } })
+    fireEvent.keyDown(min, { key: 'Enter' })
+    expect(onChangeCommitted).toHaveBeenCalled()
+    expect(onChange).toHaveBeenCalled()
+    const last = onChangeCommitted.mock.calls.at(-1) as [
+      number,
+      readonly [number, number],
+    ]
+    expect(last[0]).toBe(0)
+    expect(last[1][0]).toBeLessThanOrEqual(last[1][1])
+    expect(last[1][1]).toBeLessThanOrEqual(100)
+  })
+})

package/src/widgets-v2/range/range-ui.tsx

@@ -0,0 +1,278 @@
+import {
+  useCallback,
+  useState,
+  type FocusEvent,
+  type KeyboardEvent,
+} from 'react'
+import { Box, Slider, TextField, Typography } from '@mui/material'
+import type { RangeDataItem, RangeItemValue } from './types'
+import { styles } from './style'
+
+export interface RangeUIProps {
+  items: readonly RangeDataItem[]
+  /**
+   * Fires on every pointer tick while a thumb is being dragged (mirrors
+   * MUI `<Slider>`'s `onChange`). Use this to update local UI state —
+   * not to persist expensive operations like remote queries.
+   */
+  onChange?: (index: number, value: RangeItemValue) => void
+  /**
+   * Fires once when the user *releases* a slider thumb after dragging,
+   * after an arrow-key adjustment commits, or when the text inputs
+   * blur / Enter. Mirrors MUI `<Slider>`'s `onChangeCommitted`. Use
+   * this for side-effects you want to throttle to "drag end" — e.g.
+   * writing the value to a source filter that triggers refetches.
+   */
+  onChangeCommitted?: (index: number, value: RangeItemValue) => void
+  /** Number formatter for the slider tooltip and the text input display. */
+  formatter?: (value: number) => string
+}
+
+type Bound = 'min' | 'max'
+
+/**
+ * Pure presentational component for the Range widget. Renders one MUI Slider
+ * per item with editable min/max text inputs below — matching the Range v1
+ * UX. Each item is always a two-thumb range; supply `value` to seed the
+ * starting selection, otherwise it defaults to `[min, max]`.
+ */
+export function RangeUI({
+  items,
+  onChange,
+  onChangeCommitted,
+  formatter,
+}: RangeUIProps) {
+  const fmt = formatter ?? ((n: number) => String(n))
+  return (
+    <Box sx={styles.root}>
+      {items.map((item, i) => (
+        // Composite of the row's track bounds — stable across reorders for
+        // any realistic widget configuration. Falls back to a literal +
+        // index when bounds collide (degenerate same-min-same-max rows).
+        <RangeRow
+          key={`range-${item.min}-${item.max}-${i}`}
+          index={i}
+          item={item}
+          fmt={fmt}
+          onChange={onChange}
+          onChangeCommitted={onChangeCommitted}
+        />
+      ))}
+    </Box>
+  )
+}
+
+interface RangeRowProps {
+  index: number
+  item: RangeDataItem
+  fmt: (n: number) => string
+  onChange?: (index: number, value: RangeItemValue) => void
+  onChangeCommitted?: (index: number, value: RangeItemValue) => void
+}
+
+function RangeRow({
+  index,
+  item,
+  fmt,
+  onChange,
+  onChangeCommitted,
+}: RangeRowProps) {
+  const current: readonly [number, number] = item.value ?? [item.min, item.max]
+  const [editing, setEditing] = useState<'' | Bound>('')
+
+  // Clamp inside [min, max] and keep `low <= high`. Pulled out so both the
+  // live `onChange` path and the commit path share the same normalization.
+  const normalize = useCallback(
+    (next: readonly [number, number]): readonly [number, number] => {
+      const [lowRaw, highRaw] = next
+      const low = Math.min(Math.max(lowRaw, item.min), item.max)
+      const high = Math.min(Math.max(highRaw, item.min), item.max)
+      return low <= high ? [low, high] : [high, low]
+    },
+    [item.min, item.max],
+  )
+
+  const commit = useCallback(
+    (next: readonly [number, number]) => {
+      onChange?.(index, normalize(next))
+    },
+    [index, normalize, onChange],
+  )
+
+  const commitFinal = useCallback(
+    (next: readonly [number, number]) => {
+      onChangeCommitted?.(index, normalize(next))
+    },
+    [index, normalize, onChangeCommitted],
+  )
+
+  // A text-input commit (blur / Enter) is both a value change AND a final
+  // commit, so it fires `onChange` *and* `onChangeCommitted`. Firing both
+  // keeps the widget responsive for consumers that only wired `onChange`
+  // (the pre-`onChangeCommitted` API) — without it, typing a value and
+  // pressing Enter would silently no-op for them.
+  const commitText = useCallback(
+    (next: readonly [number, number]) => {
+      const value = normalize(next)
+      onChange?.(index, value)
+      onChangeCommitted?.(index, value)
+    },
+    [index, normalize, onChange, onChangeCommitted],
+  )
+
+  const handleSlider = (_: Event, raw: number | number[]) => {
+    if (!Array.isArray(raw)) return
+    // Hoist defaults out of the destructure: react-compiler can't safely
+    // reorder MemberExpression defaults inside an array pattern.
+    const low = raw[0] ?? item.min
+    const high = raw[1] ?? item.max
+    commit([low, high])
+  }
+
+  const handleSliderCommitted = (
+    _: Event | React.SyntheticEvent,
+    raw: number | number[],
+  ) => {
+    if (!Array.isArray(raw)) return
+    const low = raw[0] ?? item.min
+    const high = raw[1] ?? item.max
+    commitFinal([low, high])
+  }
+
+  return (
+    <Box sx={styles.item}>
+      <Box sx={styles.sliderContainer}>
+        <Slider
+          sx={{
+            ...styles.slider,
+            ...(item.color ? { color: item.color } : null),
+          }}
+          value={[...current]}
+          min={item.min}
+          max={item.max}
+          step={item.step ?? 1}
+          marks={resolveMarks(item.marks)}
+          disabled={item.disabled}
+          valueLabelDisplay='auto'
+          valueLabelFormat={fmt}
+          onChange={handleSlider}
+          onChangeCommitted={handleSliderCommitted}
+        />
+      </Box>
+      <Box sx={styles.inputsRow}>
+        {/* Text-input commits (blur / Enter) are final, but also notify
+            `onChange` — see `commitText` — so consumers that only wired
+            `onChange` still update on a typed value. */}
+        <BoundInput
+          // Bumping the key on a fresh external value resets the local
+          // editing state — matches v1's RangeItem behaviour.
+          key={`min-${current[0]}`}
+          name='min'
+          value={current[0]}
+          item={item}
+          fmt={fmt}
+          editing={editing}
+          setEditing={setEditing}
+          commit={commitText}
+          current={current}
+          ariaLabel='Minimum value'
+        />
+        <BoundInput
+          key={`max-${current[1]}`}
+          name='max'
+          value={current[1]}
+          item={item}
+          fmt={fmt}
+          editing={editing}
+          setEditing={setEditing}
+          commit={commitText}
+          current={current}
+          ariaLabel='Maximum value'
+        />
+      </Box>
+      {item.note ? (
+        <Typography variant='caption' sx={styles.note}>
+          {item.note}
+        </Typography>
+      ) : null}
+    </Box>
+  )
+}
+
+interface BoundInputProps {
+  name: Bound
+  value: number
+  item: RangeDataItem
+  fmt: (n: number) => string
+  editing: '' | Bound
+  setEditing: (next: '' | Bound) => void
+  /**
+   * Called when the user commits a new value (blur / Enter). Text input
+   * edits never produce intermediate "live" values, so the consumer
+   * only needs one callback — the row wires this to `commitFinal`.
+   */
+  commit: (next: readonly [number, number]) => void
+  current: readonly [number, number]
+  ariaLabel: string
+}
+
+function BoundInput({
+  name,
+  value,
+  item,
+  fmt,
+  editing,
+  setEditing,
+  commit,
+  current,
+  ariaLabel,
+}: BoundInputProps) {
+  const [raw, setRaw] = useState<string>(String(value))
+
+  const beginEditing = () => {
+    setEditing(name)
+  }
+  const finishEditingAndCommit = (e: FocusEvent<HTMLInputElement>) => {
+    setEditing('')
+    commitFromText(e.target.value)
+  }
+  const commitOnEnter = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter') {
+      commitFromText((e.target as HTMLInputElement).value)
+      ;(e.target as HTMLInputElement).blur()
+    }
+  }
+
+  function commitFromText(input: string) {
+    const parsed = parseFloat(input)
+    const safe = Number.isFinite(parsed) ? parsed : value
+    const next: readonly [number, number] =
+      name === 'min' ? [safe, current[1]] : [current[0], safe]
+    commit(next)
+  }
+
+  const display = editing === name ? raw : fmt(Number(raw))
+
+  return (
+    <TextField
+      name={name}
+      value={display}
+      onChange={(e) => setRaw(e.target.value)}
+      onFocus={beginEditing}
+      onBlur={finishEditingAndCommit}
+      onKeyDown={commitOnEnter}
+      disabled={item.disabled}
+      size='small'
+      sx={styles.input}
+      inputProps={{ 'aria-label': ariaLabel }}
+    />
+  )
+}
+
+function resolveMarks(
+  marks: RangeDataItem['marks'],
+): boolean | { value: number; label?: string }[] | undefined {
+  if (marks == null) return undefined
+  if (typeof marks === 'boolean') return marks
+  return [...marks]
+}