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

package/src/widgets-v2/pie/skeleton.tsx

@@ -0,0 +1,94 @@
+import { Box, Skeleton } from '@mui/material'
+import type { SxProps, Theme } from '@mui/material'
+
+const OUTER_SIZE = 160
+const HOLE_SIZE = 96
+
+const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: 200,
+    py: 1,
+    gap: ({ spacing }) => spacing(2),
+  },
+  donut: {
+    position: 'relative',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  ring: {
+    width: OUTER_SIZE,
+    height: OUTER_SIZE,
+  },
+  hole: {
+    position: 'absolute',
+    zIndex: 1,
+    width: HOLE_SIZE,
+    height: HOLE_SIZE,
+    borderRadius: '50%',
+    bgcolor: 'background.paper',
+  },
+  label: {
+    position: 'absolute',
+    zIndex: 2,
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: ({ spacing }) => spacing(0.5),
+  },
+  legend: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(2),
+  },
+  legendItem: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1.5),
+  },
+} satisfies Record<string, SxProps<Theme>>
+
+export interface PieSkeletonProps {
+  count?: number
+}
+
+/**
+ * Loading state for the Pie widget. Mirrors the donut silhouette — a ring
+ * (gray circle with a background-coloured hole punched out), a stacked
+ * value/name stub in the centre, and a centered legend stub below — so the
+ * skeleton reads as "a donut chart" rather than a solid disc.
+ *
+ * Single donut only: multi-series pie loads as a horizontal bar chart, so
+ * rendering one ring stays honest regardless of `count`.
+ */
+export function PieSkeleton({ count }: PieSkeletonProps) {
+  // `count` is accepted for API compatibility but intentionally unused: the
+  // skeleton always renders a single donut, since multi-series pie loads as a
+  // horizontal bar chart rather than multiple donuts.
+  void count
+  return (
+    <Box sx={styles.root}>
+      <Box sx={styles.donut}>
+        <Skeleton variant='circular' sx={styles.ring} />
+        <Box sx={styles.hole} />
+        <Box sx={styles.label}>
+          <Skeleton width={56} height={18} />
+          <Skeleton width={36} height={8} />
+        </Box>
+      </Box>
+      <Box sx={styles.legend}>
+        {[0, 1].map((i) => (
+          <Box key={`legend-${i}`} sx={styles.legendItem}>
+            <Skeleton variant='circular' width={8} height={8} />
+            <Skeleton width={48} height={8} />
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  )
+}

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

@@ -0,0 +1,62 @@
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
+
+/** A single slice of a pie series. */
+export interface PieDatum {
+  name: string | number
+  value: number
+}
+
+/** Pie widget data — one slice array per series (rendered as side-by-side donuts). */
+export type PieWidgetData = readonly (readonly PieDatum[])[]
+
+/** Inputs to the structural-only {@link pieOptions} builder. */
+export interface PieOptionsInput {
+  theme: Theme
+  /** Numeric value formatter — drives the tooltip value and center label. */
+  formatter?: (value: number) => string
+  /** Optional slice-name formatter — also forwarded to the legend. */
+  labelFormatter?: (value: string | number) => string | number
+}
+
+/**
+ * Combined inputs for the pie option factory creator. Carries everything
+ * the widget needs across BOTH phases — the structural-build (`theme`,
+ * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
+ * (`series`, `radius`, `selection`). The merger emits different
+ * chart shapes by series count: single → donut, multi → horizontal-bar
+ * fallback (mirrors v1 pie); both branches read `theme` for styling.
+ */
+export interface PieOptionFactoryInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and (in
+   * the multi-series bar fallback) per-series colour overrides.
+   * Single-series donuts always use the per-slice palette regardless of
+   * any `series[0].color`, since the donut palette is keyed by data
+   * index, not series index.
+   */
+  series?: readonly WidgetSeries[]
+  /**
+   * Inner/outer radius (percent). Default `['58%', '74%']` produces a
+   * donut sized to leave room for the wrappable bottom legend. Set
+   * inner to `'0%'` for a solid pie.
+   */
+  radius?: readonly [string, string]
+  /**
+   * Selected slice names. Slices not in this list render dimmed
+   * (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
+   */
+  selection?: readonly (string | number)[] | null
+  /**
+   * Consumer-supplied partial option merged into the structural option at
+   * structural-build time. Lets stories override pieces of the theme-aware
+   * base without forking the structural builder.
+   */
+  optionsOverride?: Partial<EChartsOption>
+}
+
+export type PieEChartsOption = EChartsOption

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