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

package/src/widgets-v2/echart/edge-label-clamp.ts

@@ -0,0 +1,217 @@
+import * as echarts from 'echarts'
+import type { ECharts, EChartsOption } from 'echarts'
+
+/**
+ * Render-time clamp that stops the first/last **category x-axis** labels from
+ * clipping at the chart edges — *only when they actually overflow*.
+ *
+ * ECharts centers each category label on its tick; the first/last ticks sit at
+ * the plot boundary, so a wide edge label spills past the chart and is cut off.
+ * `grid.containLabel` does not contain this horizontal overflow and the v6
+ * `outerBounds` shrink is unreliable, so we measure at render time and anchor
+ * the overflowing edge label inward (`alignMinLabel: 'left'` /
+ * `alignMaxLabel: 'right'`). Labels that fit stay centered.
+ *
+ * Lives in the generic bridge because the verdict needs the laid-out chart
+ * (`convertToPixel`, `getWidth`); everything else is read from the `option`.
+ * Auto-targets bar + histogram (category x-axis); pie's horizontal-bar fallback
+ * (category *y*-axis), scatterplot (value) and timeseries (time) are skipped.
+ */
+
+export interface EdgeAlignment {
+  alignMinLabel: 'left' | null
+  alignMaxLabel: 'right' | null
+}
+
+export const CENTERED: EdgeAlignment = {
+  alignMinLabel: null,
+  alignMaxLabel: null,
+}
+
+// Small cushion biasing toward anchoring when borderline: clipping is worse
+// than a hair of off-centering, and the measured width can differ slightly
+// from the final render (mainly when the web font isn't loaded yet at measure
+// time). Kept to 1px — a wider margin anchored labels that only just clear the
+// edge, and an anchored edge label can then be dropped by the axis
+// `hideOverlap`, leaving a gap. 1px guards measurement error without that.
+const SAFETY_MARGIN_PX = 1
+
+/**
+ * Pure overflow decision. Inputs are anchor-independent (tick centers and text
+ * width don't depend on the label's current `text-anchor`), so feeding the
+ * result back via `setOption` doesn't change them — the next pass yields the
+ * same verdict, keeping the clamp loop-stable.
+ */
+export function decideEdgeAlignment(args: {
+  firstLabel: string
+  lastLabel: string
+  font: string
+  firstTickX: number
+  lastTickX: number
+  width: number
+}): EdgeAlignment {
+  const halfFirst =
+    echarts.format.getTextRect(args.firstLabel, args.font).width / 2
+  const halfLast =
+    echarts.format.getTextRect(args.lastLabel, args.font).width / 2
+  return {
+    alignMinLabel:
+      halfFirst + SAFETY_MARGIN_PX > args.firstTickX ? 'left' : null,
+    alignMaxLabel:
+      halfLast + SAFETY_MARGIN_PX > args.width - args.lastTickX
+        ? 'right'
+        : null,
+  }
+}
+
+interface AxisLabel {
+  formatter?: (value: string | number) => string | number
+  fontSize?: number | string
+  fontFamily?: string
+  fontWeight?: number | string
+}
+
+interface CategoryXAxis {
+  type?: string
+  axisLabel?: AxisLabel
+}
+
+interface SeriesLike {
+  encode?: { x?: string | number }
+  datasetIndex?: number
+}
+
+type Cell = string | number | null | undefined
+
+function firstOf<T>(value: T | T[] | undefined): T | undefined {
+  if (Array.isArray(value)) return value[0]
+  return value
+}
+
+function firstXAxis(option: EChartsOption): CategoryXAxis | undefined {
+  const axis = firstOf(
+    option.xAxis as CategoryXAxis | CategoryXAxis[] | undefined,
+  )
+  return axis && typeof axis === 'object' ? axis : undefined
+}
+
+function hasDataZoom(option: EChartsOption): boolean {
+  const dz = option.dataZoom
+  return Array.isArray(dz) ? dz.length > 0 : dz != null
+}
+
+function cellToText(value: Cell, fmt: AxisLabel['formatter']): string {
+  if (typeof fmt === 'function') return String(fmt(value ?? ''))
+  return value == null ? '' : String(value)
+}
+
+/**
+ * Extracts the displayed first/last category strings and the label font from
+ * the option, reading categories generically via `series[0].encode.x` into the
+ * referenced dataset (`'name'` for bar, `0` for histogram). Returns `null` when
+ * the option isn't a measurable category x-axis (fewer than 2 categories, no
+ * dataset, etc.).
+ */
+export function resolveEdgeLabels(option: EChartsOption): {
+  firstLabel: string
+  lastLabel: string
+  font: string
+  count: number
+} | null {
+  const xAxis = firstXAxis(option)
+  if (!xAxis) return null
+  if (xAxis.type !== 'category') return null
+
+  const series0 = firstOf(
+    option.series as SeriesLike | SeriesLike[] | undefined,
+  )
+  const encodeX = series0?.encode?.x
+  if (encodeX == null) return null
+
+  const datasetIndex = series0?.datasetIndex ?? 0
+  const allDatasets = option.dataset as
+    { source?: unknown } | { source?: unknown }[] | undefined
+  const dataset = Array.isArray(allDatasets)
+    ? allDatasets[datasetIndex]
+    : allDatasets
+  const source = dataset?.source
+  if (!Array.isArray(source) || source.length < 2) return null
+
+  const rows = source as Record<string | number, Cell>[]
+  const fmt = xAxis.axisLabel?.formatter
+  const axisLabel = xAxis.axisLabel ?? {}
+  const size =
+    typeof axisLabel.fontSize === 'number'
+      ? `${axisLabel.fontSize}px`
+      : (axisLabel.fontSize ?? '12px')
+  const family = axisLabel.fontFamily ?? 'sans-serif'
+  const weight = axisLabel.fontWeight != null ? `${axisLabel.fontWeight} ` : ''
+
+  return {
+    firstLabel: cellToText(rows[0]?.[encodeX], fmt),
+    lastLabel: cellToText(rows[rows.length - 1]?.[encodeX], fmt),
+    font: `${weight}${size} ${family}`,
+    count: source.length,
+  }
+}
+
+/**
+ * Measures the rendered chart and, when the edge labels would clip, applies
+ * `alignMinLabel`/`alignMaxLabel` (or clears them) via an imperative merge
+ * `setOption`. Returns the alignment now in effect so the caller can keep a
+ * `prev` ref and skip redundant `setOption`s. Should be invoked from the
+ * chart's `finished` event (layout is settled, so `convertToPixel` is valid).
+ */
+export function clampEdgeLabels(
+  chart: ECharts,
+  option: EChartsOption,
+  prev: EdgeAlignment,
+): EdgeAlignment {
+  const next = computeAlignment(chart, option)
+  if (
+    next.alignMinLabel === prev.alignMinLabel &&
+    next.alignMaxLabel === prev.alignMaxLabel
+  ) {
+    return prev
+  }
+  chart.setOption({ xAxis: { axisLabel: { ...next } } } as EChartsOption, {
+    lazyUpdate: true,
+  })
+  return next
+}
+
+function computeAlignment(
+  chart: ECharts,
+  option: EChartsOption,
+): EdgeAlignment {
+  // Under dataZoom, convertToPixel on the absolute first/last index returns
+  // off-plot pixels, so the overflow math is invalid — reset to centered.
+  if (hasDataZoom(option)) return CENTERED
+
+  const labels = resolveEdgeLabels(option)
+  if (!labels) return CENTERED
+
+  const firstTickX = chart.convertToPixel({ xAxisIndex: 0 }, 0)
+  const lastTickX = chart.convertToPixel({ xAxisIndex: 0 }, labels.count - 1)
+  const width = chart.getWidth()
+  // Layout not measurable yet (defensive — `finished` normally fires after
+  // layout). Fall back to centered; a later `finished` re-measures.
+  if (
+    typeof firstTickX !== 'number' ||
+    typeof lastTickX !== 'number' ||
+    !Number.isFinite(firstTickX) ||
+    !Number.isFinite(lastTickX) ||
+    !width
+  ) {
+    return CENTERED
+  }
+
+  return decideEdgeAlignment({
+    firstLabel: labels.firstLabel,
+    lastLabel: labels.lastLabel,
+    font: labels.font,
+    firstTickX,
+    lastTickX,
+    width,
+  })
+}

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

@@ -0,0 +1,22 @@
+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.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import {
+  __resetSharedResizeObserver,
+  observeResize,
+} from './shared-resize-observer'
+
+// Track every ResizeObserver instance created in the test run so we can
+// assert on construction / disconnect lifecycle. The shared module is a
+// singleton — between tests we reset both its state and the mock.
+const instances: {
+  observe: ReturnType<typeof vi.fn>
+  unobserve: ReturnType<typeof vi.fn>
+  disconnect: ReturnType<typeof vi.fn>
+}[] = []
+
+class MockResizeObserver {
+  observe = vi.fn()
+  unobserve = vi.fn()
+  disconnect = vi.fn()
+  constructor() {
+    instances.push(this)
+  }
+}
+
+beforeEach(() => {
+  __resetSharedResizeObserver()
+  instances.length = 0
+  vi.stubGlobal('ResizeObserver', MockResizeObserver)
+})
+
+afterEach(() => {
+  __resetSharedResizeObserver()
+  vi.unstubAllGlobals()
+})
+
+describe('observeResize', () => {
+  it('lazily creates a single observer for the first subscriber', () => {
+    const el = document.createElement('div')
+    observeResize(el, () => undefined)
+    expect(instances).toHaveLength(1)
+    expect(instances[0]?.observe).toHaveBeenCalledWith(el)
+  })
+
+  it('reuses the singleton observer for additional subscribers', () => {
+    const a = document.createElement('div')
+    const b = document.createElement('div')
+    observeResize(a, () => undefined)
+    observeResize(b, () => undefined)
+    expect(instances).toHaveLength(1)
+    expect(instances[0]?.observe).toHaveBeenCalledTimes(2)
+  })
+
+  it('unobserves on unsubscribe but keeps the observer while other subscribers remain', () => {
+    const a = document.createElement('div')
+    const b = document.createElement('div')
+    const stopA = observeResize(a, () => undefined)
+    observeResize(b, () => undefined)
+    stopA()
+    expect(instances[0]?.unobserve).toHaveBeenCalledWith(a)
+    expect(instances[0]?.disconnect).not.toHaveBeenCalled()
+  })
+
+  it('disconnects the observer once the last subscriber leaves', () => {
+    const a = document.createElement('div')
+    const stop = observeResize(a, () => undefined)
+    stop()
+    expect(instances[0]?.disconnect).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns a no-op cleanup when ResizeObserver is unavailable', () => {
+    vi.stubGlobal('ResizeObserver', undefined)
+    const el = document.createElement('div')
+    const cb = vi.fn()
+    const stop = observeResize(el, cb)
+    // No constructor calls — no instances tracked.
+    expect(instances).toHaveLength(0)
+    // Cleanup is safe to call.
+    expect(() => stop()).not.toThrow()
+  })
+
+  it('re-instantiates the observer when a new subscriber arrives after disconnect', () => {
+    const a = document.createElement('div')
+    const b = document.createElement('div')
+    observeResize(a, () => undefined)()
+    expect(instances).toHaveLength(1)
+    expect(instances[0]?.disconnect).toHaveBeenCalledTimes(1)
+    observeResize(b, () => undefined)
+    expect(instances).toHaveLength(2)
+    expect(instances[1]?.observe).toHaveBeenCalledWith(b)
+  })
+})

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

@@ -0,0 +1,56 @@
+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/echart/style.ts

@@ -0,0 +1,17 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    width: '100%',
+    // `flex: 1` lets the chart fill a parent that has a definite height —
+    // the fullscreen dialog. Inline it has none (Widget.Content is an
+    // auto-height flex column), so flex-basis resolves to the content box,
+    // which is empty until ECharts measures it: at `min-height: 0` the
+    // container is 0px tall, ECharts draws nothing and the widget renders
+    // blank. 304 is not a new magic number — it's the height `init.height`
+    // used to pin, kept so cards look exactly as before. Override per widget
+    // with `<Widget.Echart sx={{ minHeight }} />`.
+    flex: 1,
+    minHeight: 304,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/echart/use-chart-selection.test.tsx

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { useChartSelection } from './use-chart-selection'
+
+describe('useChartSelection', () => {
+  it('clicking an item toggles it into and out of the selection', () => {
+    const onSelectionChange = vi.fn()
+    const { result, rerender } = renderHook(
+      ({ selection }: { selection: readonly string[] }) =>
+        useChartSelection<string>({
+          selection,
+          onSelectionChange,
+          keyFromClick: (p) => (p as { name?: string }).name ?? null,
+          keysFromBrush: () => [],
+        }),
+      { initialProps: { selection: [] as readonly string[] } },
+    )
+
+    act(() => {
+      result.current.onEvents.click?.({ name: 'A' })
+    })
+    expect(onSelectionChange).toHaveBeenLastCalledWith(['A'])
+
+    rerender({ selection: ['A'] })
+    act(() => {
+      result.current.onEvents.click?.({ name: 'A' })
+    })
+    expect(onSelectionChange).toHaveBeenLastCalledWith([])
+  })
+
+  it('emits the brushed selection only on brushEnd (brushSelected just caches)', () => {
+    const onSelectionChange = vi.fn()
+    const { result } = renderHook(() =>
+      useChartSelection<number>({
+        selection: [99],
+        onSelectionChange,
+        keyFromClick: () => null,
+        keysFromBrush: (selected) => selected.flatMap((s) => s.dataIndex),
+      }),
+    )
+
+    // Mid-drag updates fire brushSelected — these should NOT call back.
+    act(() => {
+      result.current.onEvents.brushSelected?.({
+        batch: [{ selected: [{ seriesIndex: 0, dataIndex: [3] }] }],
+      })
+      result.current.onEvents.brushSelected?.({
+        batch: [{ selected: [{ seriesIndex: 0, dataIndex: [3, 7] }] }],
+      })
+      result.current.onEvents.brushSelected?.({
+        batch: [{ selected: [{ seriesIndex: 0, dataIndex: [3, 7, 11] }] }],
+      })
+    })
+    expect(onSelectionChange).not.toHaveBeenCalled()
+
+    // Releasing the brush fires brushEnd — that's when we commit.
+    act(() => {
+      result.current.onEvents.brushEnd?.({})
+    })
+    expect(onSelectionChange).toHaveBeenCalledTimes(1)
+    expect(onSelectionChange).toHaveBeenLastCalledWith([3, 7, 11])
+  })
+
+  it('collapses undefined/null/an explicit empty list to null, since no merger treats them differently', () => {
+    const { result, rerender } = renderHook(
+      ({ selection }: { selection?: readonly string[] }) =>
+        useChartSelection<string>({
+          selection,
+          onSelectionChange: () => undefined,
+          keyFromClick: () => null,
+          keysFromBrush: () => [],
+        }),
+      {
+        initialProps: { selection: undefined } as {
+          selection?: readonly string[]
+        },
+      },
+    )
+    expect(result.current.selection).toBeNull()
+    rerender({ selection: [] })
+    expect(result.current.selection).toBeNull()
+    rerender({ selection: ['A'] })
+    expect(result.current.selection).toEqual(['A'])
+    rerender({ selection: undefined })
+    expect(result.current.selection).toBeNull()
+  })
+
+  it('is a no-op when `onSelectionChange` is missing', () => {
+    const { result } = renderHook(() =>
+      useChartSelection<string>({
+        selection: [],
+        keyFromClick: (p) => (p as { name?: string }).name ?? null,
+        keysFromBrush: () => ['x'],
+      }),
+    )
+    // Neither call should throw — handler short-circuits without a callback.
+    expect(() => result.current.onEvents.click?.({ name: 'A' })).not.toThrow()
+    expect(() =>
+      result.current.onEvents.brushSelected?.({
+        batch: [{ selected: [{ seriesIndex: 0, dataIndex: [0] }] }],
+      }),
+    ).not.toThrow()
+  })
+
+  it('skips clicks where keyFromClick returns null (e.g. axis-label clicks)', () => {
+    const onSelectionChange = vi.fn()
+    const { result } = renderHook(() =>
+      useChartSelection<string>({
+        selection: [],
+        onSelectionChange,
+        keyFromClick: () => null,
+        keysFromBrush: () => [],
+      }),
+    )
+    act(() => {
+      result.current.onEvents.click?.({ name: 'A' })
+    })
+    expect(onSelectionChange).not.toHaveBeenCalled()
+  })
+})

package/src/widgets-v2/echart/use-chart-selection.ts

@@ -0,0 +1,121 @@
+import { useCallback, useMemo, useRef } from 'react'
+import type { CallbackDataParams } from 'echarts/types/dist/shared'
+import type { EchartsEventHandler } from './echart-ui'
+
+export type SelectionKey = string | number
+
+export interface UseChartSelectionOptions<K extends SelectionKey> {
+  /**
+   * Controlled selection. `undefined`/`null`/an explicit `[]` all mean "no
+   * selection interaction" — every current merger already treats an empty
+   * selection as "nothing excluded," so this hook collapses all three to
+   * `null` rather than promising per-merger `[]` semantics it doesn't
+   * implement.
+   */
+  selection?: readonly K[]
+  /** Receives the next selection. When omitted the wiring is a no-op. */
+  onSelectionChange?: (next: readonly K[]) => void
+  /**
+   * Pull a selection key out of an ECharts `click` event. Return `null` to
+   * skip (e.g. a click on empty plot area). For Bar/Pie/Timeseries this is
+   * usually `(p) => p.name`; for Histogram/Scatterplot it's the dataIndex.
+   */
+  keyFromClick: (params: CallbackDataParams) => K | null
+  /**
+   * Map a `brushSelected` payload's `selected[*]` entries (each carrying a
+   * `seriesIndex` + `dataIndex[]`) into the full set of selection keys for
+   * the brushed area. Called once per brush event.
+   */
+  keysFromBrush: (
+    selected: readonly { seriesIndex: number; dataIndex: number[] }[],
+  ) => K[]
+}
+
+export interface ChartSelectionWiring<K extends SelectionKey> {
+  /**
+   * Pass straight to `<Widget.Echart onEvents={…}>`. Wires `click` and
+   * `brushSelected` so the user's interactions reach `onSelectionChange`.
+   */
+  onEvents: Record<string, EchartsEventHandler>
+  /**
+   * The current selection — `null` for "no selection interaction"
+   * (`undefined`/`null`/an explicit `[]`), or a non-empty array meaning
+   * "render only these as fully opaque, dim the rest".
+   */
+  selection: readonly K[] | null
+}
+
+/**
+ * Translate ECharts' click + brush events into a consumer-owned selection
+ * with the expected dashboard semantics:
+ *
+ *   - **Click toggles** — clicking an item adds it to the selection if
+ *     absent, removes it if present.
+ *   - **Brush replaces** — finishing a brush stroke overwrites the selection
+ *     with whatever the brush covered (drag-to-empty clears).
+ *
+ * Wire the returned `onEvents` into `<Widget.Echart>` and feed
+ * `wiring.selection` to the widget's option factory so the merger can dim
+ * non-selected rows at fusion time.
+ */
+export function useChartSelection<K extends SelectionKey>({
+  selection,
+  onSelectionChange,
+  keyFromClick,
+  keysFromBrush,
+}: UseChartSelectionOptions<K>): ChartSelectionWiring<K> {
+  const handleClick = useCallback(
+    (event: unknown) => {
+      if (!onSelectionChange) return
+      const params = event as CallbackDataParams
+      const key = keyFromClick(params)
+      if (key == null) return
+      const current = selection ?? []
+      const idx = current.indexOf(key)
+      const next =
+        idx === -1
+          ? [...current, key]
+          : [...current.slice(0, idx), ...current.slice(idx + 1)]
+      onSelectionChange(next)
+    },
+    [selection, onSelectionChange, keyFromClick],
+  )
+
+  // ECharts fires `brushSelected` on every pointer-move while the user is
+  // drawing a brush, but we only want to push to `onSelectionChange` once
+  // the gesture ends. Cache the latest `brushSelected` payload here, then
+  // commit on `brushEnd`.
+  const latestBrushedRef = useRef<
+    readonly { seriesIndex: number; dataIndex: number[] }[]
+  >([])
+
+  const handleBrushSelected = useCallback((event: unknown) => {
+    const params = event as {
+      batch?: {
+        selected?: { seriesIndex: number; dataIndex: number[] }[]
+      }[]
+    }
+    latestBrushedRef.current = params.batch?.[0]?.selected ?? []
+  }, [])
+
+  const handleBrushEnd = useCallback(() => {
+    if (!onSelectionChange) return
+    onSelectionChange(keysFromBrush(latestBrushedRef.current))
+  }, [onSelectionChange, keysFromBrush])
+
+  const onEvents = useMemo<Record<string, EchartsEventHandler>>(
+    () => ({
+      click: handleClick,
+      brushSelected: handleBrushSelected,
+      brushEnd: handleBrushEnd,
+    }),
+    [handleClick, handleBrushSelected, handleBrushEnd],
+  )
+
+  const wiringSelection = useMemo(
+    () => (selection && selection.length > 0 ? selection : null),
+    [selection],
+  )
+
+  return { onEvents, selection: wiringSelection }
+}