@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/widgets-v2/echart/echart.test.tsx

@@ -1,229 +0,0 @@
-import { useEffect } from 'react'
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { act, render } from '@testing-library/react'
-import type * as echarts from 'echarts'
-import { Provider } from '../provider/widget-provider'
-import { Echart } from './echart'
-import type { OptionFactory } from './echart'
-import {
-  clearAllWidgetStores,
-  getEchartInstance,
-  getWidgetStore,
-} from '../stores'
-
-// Capture the option that EchartUI receives, since we don't render real ECharts in tests.
-const captured: {
-  option: echarts.EChartsOption | null
-  replaceMerge: readonly string[] | null
-  setOptions: number
-} = {
-  option: null,
-  replaceMerge: null,
-  setOptions: 0,
-}
-
-vi.mock('./echart-ui', () => ({
-  EchartUI: ({
-    option,
-    replaceMerge,
-    onInstance,
-  }: {
-    option: echarts.EChartsOption
-    replaceMerge: readonly string[]
-    onInstance?: (chart: echarts.ECharts | null) => void
-  }) => {
-    captured.option = option
-    captured.replaceMerge = replaceMerge
-    captured.setOptions++
-    // Mimic the real bridge: publish a fake instance on mount, clear on
-    // unmount. Cast through unknown so the test doesn't depend on the full
-    // ECharts surface.
-    useEffect(() => {
-      const fake = { __mock: true } as unknown as echarts.ECharts
-      onInstance?.(fake)
-      return () => onInstance?.(null)
-    }, [onInstance])
-    return null
-  },
-  DEFAULT_INIT_OPTS: { renderer: 'svg' },
-}))
-
-beforeEach(() => {
-  clearAllWidgetStores()
-  captured.option = null
-  captured.replaceMerge = null
-  captured.setOptions = 0
-})
-afterEach(() => clearAllWidgetStores())
-
-// Helper: build an OptionFactory whose structural branch returns `structural`
-// and whose merge branch passes the post-config-transforms option through
-// `mergeData(option, data, ctx)`.
-const makeFactory = (
-  structural: echarts.EChartsOption,
-  mergeData: (
-    option: echarts.EChartsOption,
-    data: unknown,
-  ) => echarts.EChartsOption,
-): OptionFactory => {
-  return (option, data) => {
-    if (option == null) return structural
-    return mergeData(option, data)
-  }
-}
-
-describe('<Echart> bridge — owns the option factory directly', () => {
-  it('forwards the structural option to EchartUI synchronously on first render', () => {
-    const factory = makeFactory(
-      { xAxis: { type: 'category' } } as echarts.EChartsOption,
-      // Merge branch: return the option as-is so the structural option
-      // flows through to ECharts unchanged.
-      (option) => option,
-    )
-    render(
-      <Provider id='e1' data={[]}>
-        <Echart optionFactory={factory} />
-      </Provider>,
-    )
-    expect(captured.option).toEqual({ xAxis: { type: 'category' } })
-    // No `rawOptions` on the store — the option pipeline is Echart-local now.
-    expect(
-      (getWidgetStore('e1').getState() as unknown as { rawOptions?: unknown })
-        .rawOptions,
-    ).toBeUndefined()
-  })
-
-  it('fuses state.data into the option via the factory merge branch (dataset)', () => {
-    const factory = makeFactory(
-      { xAxis: { type: 'category' } } as echarts.EChartsOption,
-      (option, data) =>
-        ({
-          ...option,
-          dataset: Array.isArray(data)
-            ? (data as { name: string; value: number }[][]).map((source) => ({
-                source,
-              }))
-            : [],
-        }) as echarts.EChartsOption,
-    )
-    render(
-      <Provider id='e2' data={[[{ name: 'A', value: 1 }]]}>
-        <Echart optionFactory={factory} />
-      </Provider>,
-    )
-    const captured2 = captured.option as { dataset: { source: unknown }[] }
-    expect(captured2.dataset).toHaveLength(1)
-    expect(captured2.dataset[0]?.source).toEqual([{ name: 'A', value: 1 }])
-  })
-
-  it('updates the option when a data transform changes state.data (no re-init)', () => {
-    interface Row {
-      name: string
-      value: number
-    }
-    const factory = makeFactory(
-      { xAxis: { type: 'category' } } as echarts.EChartsOption,
-      (option, data) =>
-        ({
-          ...option,
-          // Mark each dataset with the record count so changes are observable.
-          dataset: Array.isArray(data)
-            ? (data as Row[][]).map((s) => ({
-                source: s,
-                id: `len:${s.length}`,
-              }))
-            : [],
-        }) as echarts.EChartsOption,
-    )
-    render(
-      <Provider
-        id='e3'
-        data={[
-          [
-            { name: 'A', value: 1 },
-            { name: 'B', value: 2 },
-            { name: 'C', value: 3 },
-          ],
-        ]}
-      >
-        <Echart optionFactory={factory} />
-      </Provider>,
-    )
-
-    // Before transform: 3 records.
-    let dataset = (captured.option as { dataset: { id: string }[] }).dataset
-    expect(dataset[0]?.id).toBe('len:3')
-
-    // Register a data transform that filters out half the records.
-    act(() => {
-      getWidgetStore('e3').setState({
-        dataTransforms: [
-          {
-            id: 'cut',
-            type: 'data',
-            order: 1,
-            enabled: true,
-            fn: (input) => {
-              const arr = input as { name: string; value: number }[][]
-              return arr.map((s) => s.slice(0, 1))
-            },
-          },
-        ],
-      })
-    })
-
-    // Bridge should have re-rendered with post-pipeline data: 1 record.
-    dataset = (captured.option as { dataset: { id: string }[] }).dataset
-    expect(dataset[0]?.id).toBe('len:1')
-  })
-
-  it('applies configTransforms to the rendered option and forwards replaceMerge', () => {
-    const factory = makeFactory(
-      { xAxis: { type: 'category' } } as echarts.EChartsOption,
-      (option) => option,
-    )
-    render(
-      <Provider id='e-cfg' data={[]}>
-        <Echart optionFactory={factory} />
-      </Provider>,
-    )
-
-    // Before transform: untouched structural; replaceMerge is the default.
-    expect(captured.option).toEqual({ xAxis: { type: 'category' } })
-    expect(captured.replaceMerge).toEqual(['toolbox'])
-
-    // Register a config transform that stamps a field onto the option and
-    // contributes a `replaceMergeKeys` entry.
-    act(() => {
-      getWidgetStore('e-cfg').setState({
-        configTransforms: [
-          {
-            id: 'stamp',
-            type: 'config',
-            order: 1,
-            enabled: true,
-            replaceMergeKeys: ['stamp'],
-            fn: (o) => ({ ...(o as object), stamp: true }),
-          },
-        ],
-      })
-    })
-
-    // After transform: option carries the mutation, replaceMerge is
-    // deduped+sorted with the default and the transform's keys.
-    expect((captured.option as { stamp?: boolean }).stamp).toBe(true)
-    expect(captured.replaceMerge).toEqual(['stamp', 'toolbox'])
-  })
-
-  it('publishes the live ECharts instance to the per-id registry on mount and clears on unmount', () => {
-    const factory = makeFactory({} as echarts.EChartsOption, (option) => option)
-    const { unmount } = render(
-      <Provider id='e-instance' data={[]}>
-        <Echart optionFactory={factory} />
-      </Provider>,
-    )
-    expect(getEchartInstance('e-instance')).not.toBeNull()
-    unmount()
-    expect(getEchartInstance('e-instance')).toBeNull()
-  })
-})

package/src/widgets-v2/echart/echart.tsx

@@ -1,209 +0,0 @@
-import { useCallback, useMemo } from 'react'
-import type { SxProps, Theme } from '@mui/material'
-import type * as echarts from 'echarts'
-import {
-  applyTransforms,
-  setEchartInstance,
-  useWidgetId,
-  useWidgetShallow,
-  type Transform,
-} from '../stores'
-import { EchartUI, type EchartsEventHandler } from './echart-ui'
-
-/**
- * Default ECharts `replaceMerge` keys for every widget. `dataZoom` and
- * `brush` are omitted so ZoomToggle / BrushToggle's user-driven runtime
- * state (slider range, brushed areas in `multiple` mode) survives unrelated
- * re-renders. `series` and `dataset` are also omitted: EchartUI fingerprints
- * them per-render and adds them to `replaceMerge` only when their shape
- * actually changes, keeping ECharts' per-series runtime state alive when
- * only callback-style fields differ.
- *
- * Lives in this module (not the generic store) because it's an ECharts
- * concept. Module-private — callers should not need it.
- */
-const DEFAULT_REPLACE_MERGE: readonly string[] = ['toolbox']
-
-/**
- * Reactive context passed to every {@link OptionFactory} call so the
- * factory can rebuild render-time pieces (axis label / tooltip formatters)
- * from the live store. Drives RelativeData / consumer-formatter changes
- * through to the chart without rebuilding the structural option.
- */
-export interface OptionFactoryContext {
-  formatter?: (value: number) => string
-  labelFormatter?: (value: string | number) => string | number
-}
-
-/**
- * The per-widget option factory — a single callable that owns BOTH phases
- * of option construction:
- *
- * - **Structural phase** — when `option == null`, return the theme-aware
- *   structural option (tooltip / legend / color palette / series
- *   template, optionally merged with a consumer-supplied `optionsOverride`).
- *   No data is read. `<Widget.Echart>` calls the factory with
- *   `(undefined, undefined)` synchronously during render to derive the
- *   structural base; `configTransforms` (Stack/Zoom/Brush) then mutate it
- *   in the same render pass.
- * - **Merge phase** — when `option` is defined, fuse `data` into the
- *   post-configTransforms option at fusion time. `<Widget.Echart>` calls
- *   the factory with `(transformed, data, ctx)` on every render.
- *
- * The two phases share a closure (the factory creator captures `theme`,
- * `formatter`, `labelFormatter`, `seriesNames`, `selection`, `optionsOverride`,
- * …), so structural and merge agree on the same widget configuration.
- *
- * The third arg `ctx` carries the **live** store-side formatters at the
- * call site — distinct from the closure-time formatters because actions
- * like RelativeData can install a percent formatter on the store after
- * the factory was constructed. The merge phase reads from `ctx`; the
- * structural phase typically uses the closure-time values.
- */
-export type OptionFactory = (
-  option: echarts.EChartsOption | undefined,
-  data: unknown,
-  ctx?: OptionFactoryContext,
-) => echarts.EChartsOption
-
-export interface EchartProps {
-  /**
-   * The per-widget {@link OptionFactory}. Required — `<Widget.Echart>`
-   * derives the structural option from it (so configTransforms have a base
-   * to mutate) and fuses `state.data` into the post-pipeline option at
-   * render time. Wrap the factory creator in `useMemo` so its identity is
-   * stable across renders.
-   */
-  optionFactory: OptionFactory
-  onEvents?: Record<string, EchartsEventHandler>
-  init?: echarts.EChartsInitOpts
-  className?: string
-  /**
-   * Styles for the chart container — this is where its height comes from.
-   * `min-height` defaults to the card height (304px) and `flex: 1` lets the
-   * chart fill a taller parent; override either here, e.g.
-   * `sx={{ minHeight: 400 }}` for a taller card.
-   */
-  sx?: SxProps<Theme>
-}
-
-interface EchartSlice {
-  data: unknown
-  configTransforms: readonly Transform[]
-  formatter?: (value: number) => string
-  labelFormatter?: (value: string | number) => string | number
-}
-
-const echartSelector = (s: {
-  data: unknown
-  configTransforms: readonly Transform[]
-  formatter?: (value: number) => string
-  labelFormatter?: (value: string | number) => string | number
-}): EchartSlice => ({
-  data: s.data,
-  configTransforms: s.configTransforms,
-  formatter: s.formatter,
-  labelFormatter: s.labelFormatter,
-})
-
-/**
- * Stateful Echart bridge — owns the entire ECharts coupling. The whole
- * option pipeline lives here, not in the store:
- *
- * 1. **Structural** — `optionFactory(undefined, undefined)` produces the
- *    theme-aware base. Memoized on the factory identity, so the consumer's
- *    `useMemo` ID gates the rebuild.
- * 2. **Transformed** — `applyTransforms(structural, configTransforms)`
- *    applies any registered configTransforms (Stack/Zoom/Brush) over the
- *    structural base. Memoized on `[structural, configTransforms]`.
- * 3. **`replaceMerge`** — derived from the enabled configTransforms'
- *    `replaceMergeKeys`, deduped and sorted, seeded with
- *    {@link DEFAULT_REPLACE_MERGE}. Memoized on `[configTransforms]` so
- *    ECharts sees a stable array reference across non-transform changes.
- * 4. **Merge** — `optionFactory(transformed, data, ctx)` fuses post-
- *    pipeline data into the option. Reactive `ctx` carries the live store
- *    formatters so RelativeData's percent formatter flows through without
- *    a structural rebuild.
- *
- * The `<Widget.Provider>` doesn't know about the factory at all: it stays
- * a renderer-agnostic shell. The `ProviderProps` surface has no ECharts
- * coupling, so non-Echart widgets don't transitively import the type.
- */
-export function Echart({
-  optionFactory,
-  onEvents,
-  init,
-  className,
-  sx,
-}: EchartProps) {
-  const id = useWidgetId()
-  const slice = useWidgetShallow(id, echartSelector)
-
-  // Publish the live ECharts instance to the per-id registry so actions
-  // (e.g. `ZoomToggle`'s disable handler) can reach it imperatively. The
-  // callback identity is stable across renders (only `id` is in deps), so
-  // EchartUI's init effect doesn't see a fresh `onInstance` and re-init.
-  const onInstance = useCallback(
-    (chart: echarts.ECharts | null) => setEchartInstance(id, chart),
-    [id],
-  )
-
-  // Destructure so React Compiler sees specific deps instead of inferring
-  // the whole `slice` object. `useWidgetShallow` already shallow-compares
-  // the slice, so per-field deps drive each memo exactly when its inputs
-  // change.
-  const {
-    data: sliceData,
-    configTransforms,
-    formatter: sliceFormatter,
-    labelFormatter: sliceLabelFormatter,
-  } = slice
-
-  const structural = useMemo(
-    () => optionFactory(undefined, undefined),
-    [optionFactory],
-  )
-
-  const transformed = useMemo(
-    () =>
-      applyTransforms(structural, configTransforms) as echarts.EChartsOption,
-    [structural, configTransforms],
-  )
-
-  const replaceMerge = useMemo(() => {
-    const keys = new Set<string>(DEFAULT_REPLACE_MERGE)
-    for (const xf of configTransforms) {
-      if (xf.enabled && xf.replaceMergeKeys?.length) {
-        for (const k of xf.replaceMergeKeys) keys.add(k)
-      }
-    }
-    return Array.from(keys).sort()
-  }, [configTransforms])
-
-  const option = useMemo(
-    () =>
-      optionFactory(transformed, sliceData, {
-        formatter: sliceFormatter,
-        labelFormatter: sliceLabelFormatter,
-      }),
-    [
-      optionFactory,
-      transformed,
-      sliceData,
-      sliceFormatter,
-      sliceLabelFormatter,
-    ],
-  )
-
-  return (
-    <EchartUI
-      option={option}
-      replaceMerge={replaceMerge}
-      onEvents={onEvents}
-      init={init}
-      onInstance={onInstance}
-      className={className}
-      sx={sx}
-    />
-  )
-}

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

@@ -1,22 +0,0 @@
-export {
-  EchartUI,
-  DEFAULT_INIT_OPTS,
-  type EchartUIProps,
-  type EchartsEventHandler,
-} from './echart-ui'
-export {
-  Echart,
-  type EchartProps,
-  type OptionFactory,
-  type OptionFactoryContext,
-} from './echart'
-export {
-  useChartSelection,
-  type SelectionKey,
-  type UseChartSelectionOptions,
-  type ChartSelectionWiring,
-} from './use-chart-selection'
-export {
-  observeResize,
-  __resetSharedResizeObserver,
-} from './shared-resize-observer'

package/src/widgets-v2/echart/shared-resize-observer.ts

@@ -1,56 +0,0 @@
-type ResizeCallback = () => void
-
-const callbacks = new Map<Element, ResizeCallback>()
-let observer: ResizeObserver | null = null
-
-/**
- * Returns the singleton ResizeObserver, lazily constructing it on first use.
- * Returns `null` when `ResizeObserver` is not available in the global scope
- * (SSR, very old browsers, or tests that intentionally remove it).
- */
-function getObserver(): ResizeObserver | null {
-  if (typeof ResizeObserver === 'undefined') return null
-  observer ??= new ResizeObserver((entries) => {
-    for (const entry of entries) {
-      const callback = callbacks.get(entry.target)
-      callback?.()
-    }
-  })
-  return observer
-}
-
-const NOOP_CLEANUP = (): void => undefined
-
-export function observeResize(
-  element: Element,
-  callback: ResizeCallback,
-): () => void {
-  const ro = getObserver()
-  // Gracefully degrade when no ResizeObserver is available — consumers
-  // still see one initial measure() pass via their own effect; we just
-  // skip the subsequent resize-driven re-measures.
-  if (!ro) return NOOP_CLEANUP
-  callbacks.set(element, callback)
-  ro.observe(element)
-  return () => {
-    callbacks.delete(element)
-    if (observer) {
-      observer.unobserve(element)
-      // Disconnect the singleton once the last subscriber leaves so the
-      // observer doesn't outlive its consumers in SSR teardown / micro-
-      // frontend unmount scenarios. A subsequent observeResize() will
-      // lazily re-create it via getObserver().
-      if (callbacks.size === 0) {
-        observer.disconnect()
-        observer = null
-      }
-    }
-  }
-}
-
-/** @internal — for tests only. */
-export function __resetSharedResizeObserver(): void {
-  if (observer) observer.disconnect()
-  callbacks.clear()
-  observer = null
-}

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

@@ -1,91 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { render, screen } from '@testing-library/react'
-import { FormulaUI } from './formula-ui'
-
-describe('<FormulaUI>', () => {
-  it('renders a single KPI value', () => {
-    render(<FormulaUI items={[{ value: 1234 }]} />)
-    expect(screen.getByText('1234')).toBeTruthy()
-  })
-
-  it('applies a formatter to the value', () => {
-    render(
-      <FormulaUI
-        items={[{ value: 1234 }]}
-        formatter={(n) => `$${n.toLocaleString('en-US')}`}
-      />,
-    )
-    expect(screen.getByText('$1,234')).toBeTruthy()
-  })
-
-  it('renders prefix and suffix when provided', () => {
-    render(<FormulaUI items={[{ value: 99, prefix: 'USD', suffix: '/mo' }]} />)
-    expect(screen.getByText('USD')).toBeTruthy()
-    expect(screen.getByText('99')).toBeTruthy()
-    expect(screen.getByText('/mo')).toBeTruthy()
-  })
-
-  it('renders multiple items side-by-side', () => {
-    render(
-      <FormulaUI
-        items={[
-          { value: 100, suffix: 'rev' },
-          { value: 25, suffix: 'cogs' },
-          { value: 75, suffix: 'gp' },
-        ]}
-      />,
-    )
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('25')).toBeTruthy()
-    expect(screen.getByText('75')).toBeTruthy()
-  })
-
-  it('renders nothing visible when items is empty', () => {
-    const { container } = render(<FormulaUI items={[]} />)
-    // Root <Box> exists, but it has no item children.
-    expect(container.querySelectorAll('[role]').length).toBe(0)
-  })
-
-  it('renders a series avatar with the first letter of the name', () => {
-    render(
-      <FormulaUI
-        items={[{ value: 1, series: { name: 'Revenue', color: '#1E5BB5' } }]}
-      />,
-    )
-    expect(screen.getByLabelText('Revenue').textContent).toBe('R')
-  })
-
-  it('renders the note when provided', () => {
-    render(<FormulaUI items={[{ value: 1, note: 'Last 7 days' }]} />)
-    expect(screen.getByText('Last 7 days')).toBeTruthy()
-  })
-
-  it('renders a delta chip with severity-based styling', () => {
-    const { container } = render(
-      <FormulaUI items={[{ value: 1, delta: { value: -0.123 } }]} />,
-    )
-    // MUI's `severity='error'` → `MuiChip-colorError` class.
-    expect(container.querySelector('.MuiChip-colorError')).toBeTruthy()
-  })
-
-  it('uses the explicit delta label when provided', () => {
-    render(
-      <FormulaUI
-        items={[
-          {
-            value: 1,
-            delta: { value: 0.05, label: 'better than yesterday' },
-          },
-        ]}
-      />,
-    )
-    expect(screen.getByText('better than yesterday')).toBeTruthy()
-  })
-
-  it('omits avatar / note / delta when fields are absent', () => {
-    const { container } = render(<FormulaUI items={[{ value: 42 }]} />)
-    expect(container.querySelector('[role="img"]')).toBeNull()
-    expect(container.querySelector('.MuiChip-root')).toBeNull()
-    expect(container.querySelector('p')).toBeNull()
-  })
-})

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

@@ -1,66 +0,0 @@
-import { Box } from '@mui/material'
-import type { Ref } from 'react'
-import type { FormulaDataItem } from './types'
-import { Delta } from './delta'
-import { Note } from './note'
-import { Prefix } from './prefix'
-import { Series } from './series'
-import { Suffix } from './suffix'
-import { Value } from './value'
-import { styles } from './style'
-
-export interface FormulaUIProps {
-  items: readonly FormulaDataItem[]
-  /** Number formatter — applied to each item's `value`. */
-  formatter?: (value: number) => string
-  /** Forwarded to the root `<Box>` so consumers can capture the DOM (PNG export). */
-  ref?: Ref<HTMLDivElement>
-}
-
-/**
- * Pure presentational component for the Formula widget. Each item renders as
- * a row containing (in order): optional `Series` avatar, a body with
- * `[prefix] value [suffix]` plus optional `Note`, and an optional `Delta`
- * chip pushed to the right edge.
- *
- * For fully custom layouts, compose {@link Series}, {@link Prefix},
- * {@link Value}, {@link Suffix}, {@link Note}, and {@link Delta} directly
- * instead of passing `items`.
- */
-export function FormulaUI({ items, formatter, ref }: FormulaUIProps) {
-  return (
-    <Box ref={ref} sx={styles.root}>
-      {items.map((item, i) => (
-        // Series name is the closest stable id; fall back to the literal
-        // value (numeric KPIs rarely repeat with the same prefix/suffix).
-        <Box
-          key={`formula-${item.series?.name ?? `${item.prefix ?? ''}${item.value}${item.suffix ?? ''}`}-${i}`}
-          sx={styles.row}
-        >
-          {item.series ? (
-            <Series name={item.series.name} color={item.series.color} />
-          ) : null}
-          <Box sx={styles.body}>
-            <Box sx={styles.valueRow}>
-              {item.prefix ? <Prefix>{item.prefix}</Prefix> : null}
-              <Value color={item.color}>
-                {formatter ? formatter(item.value) : String(item.value)}
-              </Value>
-              {item.suffix ? <Suffix>{item.suffix}</Suffix> : null}
-            </Box>
-            {item.note ? <Note>{item.note}</Note> : null}
-          </Box>
-          {item.delta ? (
-            <Box sx={styles.delta}>
-              <Delta
-                value={item.delta.value}
-                label={item.delta.label}
-                severity={item.delta.severity}
-              />
-            </Box>
-          ) : null}
-        </Box>
-      ))}
-    </Box>
-  )
-}

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

@@ -1,17 +0,0 @@
-export { Formula } from './formula'
-export { FormulaUI, type FormulaUIProps } from './formula-ui'
-export { Prefix, type PrefixProps } from './prefix'
-export { Suffix, type SuffixProps } from './suffix'
-export { Value, type ValueProps } from './value'
-export { Series, type SeriesProps } from './series'
-export { Note, type NoteProps } from './note'
-export { Delta, type DeltaProps } from './delta'
-export { FormulaSkeleton, type FormulaSkeletonProps } from './skeleton'
-export { createFormulaDownloadConfig } from './download'
-export type {
-  FormulaDataItem,
-  FormulaWidgetData,
-  FormulaSeries,
-  FormulaDelta,
-  DeltaSeverity,
-} from './types'