@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/widgets/echart/echart.tsx

@@ -1,66 +1,209 @@
-import type {
-  EchartProps,
-  EchartWidgetState,
-  EchartWidgetData,
-  EchartOptionsProps,
-} from './types'
-import { EchartUI } from './echart-ui'
-import { useWidgetSelector } from '../stores/use-widget-selector'
-import { useMemo } from 'react'
+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'
 
 /**
- * Stateful EChart widget component that reads data and options from the widget store and renders an ECharts chart.
+ * 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.
  *
- * @remarks
- * Transforms widget data into ECharts dataset format and delegates rendering to {@link EchartUI}.
+ * Lives in this module (not the generic store) because it's an ECharts
+ * concept. Module-private — callers should not need it.
  */
-export function Echart(props: EchartProps) {
-  // Single consolidated subscription instead of 5 separate ones.
-  const { id, data, widgetOption, onEvents, init } = useWidgetSelector(
-    props.id,
-    (w) => ({
-      id: w?.id,
-      data: (w as EchartWidgetState | undefined)?.data as
-        EchartWidgetData | undefined,
-      widgetOption: (w as EchartWidgetState | undefined)?.option,
-      onEvents: (w as EchartWidgetState | undefined)?.onEvents,
-      init: (w as EchartWidgetState | undefined)?.init,
-    }),
-  )
+const DEFAULT_REPLACE_MERGE: readonly string[] = ['toolbox']
 
-  // Memoize dataset transformation to avoid re-computing on every render
-  const dataset = useMemo(() => buildDataset(data), [data])
+/**
+ * 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
+}
 
-  const option = useMemo<EchartOptionsProps>(
-    () => ({
-      ...widgetOption,
-      ...(dataset && { dataset }),
-    }),
-    [widgetOption, dataset],
-  )
+/**
+ * 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
 
-  if (!id) {
-    return null
-  }
+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>
+}
 
-  return (
-    <EchartUI id={props.id} option={option} onEvents={onEvents} init={init} />
-  )
+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,
+})
+
 /**
- * Builds the dataset configuration from widget data
- * @param data - The widget data array
- * @returns The dataset configuration for ECharts
+ * 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.
  */
-function buildDataset(
-  data: EchartWidgetData | undefined,
-): EchartOptionsProps['dataset'] {
-  if (!data || data.length === 0) {
-    return undefined
-  }
+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],
+  )
 
-  return data.map((d) => ({
-    source: d,
-  }))
+  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/echart/index.ts

@@ -1,16 +1,22 @@
-export { Echart } from './echart'
-export { EchartUI } from './echart-ui'
-export type {
-  EchartProps,
-  EchartOptionsProps,
-  EchartUIProps,
-  EchartWidgetData,
-  EchartWidgetState,
-} from './types'
-export { getCommonOptions } from './options'
 export {
-  mergeEchartWidgetConfig,
-  getEChartBrushConfig,
-  getEChartStackConfig,
-  getEChartZoomConfig,
-} from './utils'
+  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/echart/shared-resize-observer.ts

@@ -1,18 +1,15 @@
-/**
- * Shared ResizeObserver singleton for all ECharts instances.
- *
- * Instead of creating 100+ individual ResizeObserver instances (one per chart),
- * this module provides a single shared observer that efficiently handles resize
- * callbacks for all registered elements.
- */
-
 type ResizeCallback = () => void
 
 const callbacks = new Map<Element, ResizeCallback>()
-
 let observer: ResizeObserver | null = null
 
-function getObserver(): ResizeObserver {
+/**
+ * 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)
@@ -22,24 +19,38 @@ function getObserver(): ResizeObserver {
   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)
-  getObserver().observe(element)
-
+  ro.observe(element)
   return () => {
     callbacks.delete(element)
-    getObserver().unobserve(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
+      }
+    }
   }
 }
 
-/** Reset the shared observer (for testing only). */
-export function resetSharedResizeObserver(): void {
-  if (observer) {
-    observer.disconnect()
-    observer = null
-  }
+/** @internal — for tests only. */
+export function __resetSharedResizeObserver(): void {
+  if (observer) observer.disconnect()
   callbacks.clear()
+  observer = null
 }

package/src/{widgets-v2 → widgets}/echart/style.ts

@@ -15,9 +15,9 @@ export const styles = {
     minHeight: 304,
     // ECharts puts its tooltip inside this box at `z-index: 9999999`. With
     // no stacking context of its own, that number competes page-wide and
-    // beats MUI's modal layer — under `FullScreen.Slot` the card's chart
-    // mirrors the dialog's tooltip (echarts.connect) and it painted over
-    // the dialog. Isolating keeps the tooltip above its own chart only.
+    // beats MUI's modal and popover layers, so a tooltip left showing
+    // paints over any dialog or menu opened above the chart. Isolating
+    // keeps the tooltip above its own chart only.
     isolation: 'isolate',
   },
 } satisfies Record<string, SxProps<Theme>>

package/src/{widgets-v2 → widgets}/formula/download.tsx

@@ -1,44 +1,24 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
-  type DownloadContext,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } from '../actions/download'
 import type { FormulaWidgetData } from './types'
 
-export interface FormulaDownloadConfigArgs {
-  filename: string
-  getData: (ctx: DownloadContext) => FormulaWidgetData
-  /**
-   * Optional getter for the widget's capture element (registered by
-   * `Widget.State`). When provided, a PNG item is prepended.
-   */
-  getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null
-  pngPixelRatio?: number
-  pngBackgroundColor?: string | null
-}
+export type FormulaDownloadConfigArgs = WidgetDownloadArgs<FormulaWidgetData>
 
 /**
  * Builds download items for the Formula widget. Always includes a CSV item
- * with one row per KPI (`prefix`, `value`, `suffix`, `note`, `delta`).
- * When `getCaptureEl` is supplied, prepends a PNG item that rasterises the
- * captured element via `html2canvas`.
+ * with one row per KPI (`prefix`, `value`, `suffix`, `note`, `delta`). When
+ * `getCaptureEl` is given, prepends a PNG item that rasterises the captured
+ * element via `html2canvas`.
  */
 export function createFormulaDownloadConfig(
   args: FormulaDownloadConfigArgs,
 ): DownloadItem[] {
-  const items: DownloadItem[] = []
-  if (args.getCaptureEl) {
-    items.push(
-      buildPngDownloadItem({
-        filename: args.filename,
-        getCaptureEl: args.getCaptureEl,
-        pixelRatio: args.pngPixelRatio,
-        backgroundColor: args.pngBackgroundColor,
-      }),
-    )
-  }
-  items.push(
+  return withPngItem(
+    args,
     buildCsvDownloadItem({
       filename: args.filename,
       getRows: (ctx) => {
@@ -60,5 +40,4 @@ export function createFormulaDownloadConfig(
       },
     }),
   )
-  return items
 }