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

package/src/widgets-v2/stores/widget-store-registry.ts

@@ -0,0 +1,239 @@
+import type { ECharts } from 'echarts'
+import { useStore, type StoreApi } from 'zustand'
+import { createStore } from 'zustand/vanilla'
+import { devtools } from 'zustand/middleware'
+import { useShallow } from 'zustand/react/shallow'
+import { isDev } from '@carto/ps-utils'
+import { pipelineMiddleware } from './pipeline-middleware'
+import type { WidgetInit, WidgetState, WidgetStoreApi } from './types'
+
+const widgetStores = new Map<string, WidgetStoreApi>()
+
+const widgetMountCounts = new Map<string, number>()
+const warnedDuplicates = new Set<string>()
+
+// Per-widget capture-element registry. Held outside the reactive store so
+// publishing the element doesn't trigger any consumer re-renders — these
+// handles are read imperatively by per-widget download configs at click time
+// only. `Widget.State` writes its success-path content wrapper here on mount
+// (auto-cleared on unmount via callback ref), and `create*DownloadConfig`
+// looks it up to feed `html2canvas` for PNG export.
+const captureEls = new Map<string, HTMLElement>()
+
+// Per-widget live ECharts instance registry. Same imperative-only contract
+// as `captureEls`: published by the `Widget.Echart` bridge on mount /
+// dispose, read at click time by actions that need to dispatch on the live
+// chart (e.g. `ZoomToggle`'s disable handler issuing
+// `setOption({}, { replaceMerge: ['dataZoom'] })` to clear the slider).
+// Held outside the reactive store so publishing never triggers consumer
+// re-renders.
+const echartInstances = new Map<string, ECharts>()
+
+// Per-id subscribers notified whenever `setEchartInstance` writes a new
+// value. Powers `useEchartInstance(id)` (a `useSyncExternalStore` wrapper)
+// so actions like `BrushToggle` can react when the chart becomes available
+// — required for lifecycle effects that need the instance on mount but
+// arrive in the tree before the `Widget.Echart` bridge has run its init
+// `useEffect`.
+type EchartInstanceListener = (chart: ECharts | null) => void
+const echartInstanceSubscribers = new Map<string, Set<EchartInstanceListener>>()
+
+export function getWidgetStore(id: string): WidgetStoreApi {
+  const store = widgetStores.get(id)
+  if (!store) throw new Error(`[widgets-v2] Widget store "${id}" not found.`)
+  return store
+}
+
+export function hasWidgetStore(id: string): boolean {
+  return widgetStores.has(id)
+}
+
+export function deleteWidgetStore(id: string): void {
+  widgetStores.delete(id)
+}
+
+export function resetWidgetStore(id: string): void {
+  const store = widgetStores.get(id)
+  if (store) store.setState({ transformStates: {} })
+}
+
+export function clearAllWidgetStores(): void {
+  widgetStores.clear()
+  widgetMountCounts.clear()
+  warnedDuplicates.clear()
+  captureEls.clear()
+  echartInstances.clear()
+  echartInstanceSubscribers.clear()
+}
+
+/**
+ * Register or clear the capture element for a widget. Pass `null` to clear.
+ * Called by `Widget.State` via a callback ref on its success-path content
+ * wrapper. The element is read by per-widget download configs at click time
+ * to feed `html2canvas` for PNG export.
+ */
+export function setCaptureEl(id: string, el: HTMLElement | null): void {
+  if (el == null) captureEls.delete(id)
+  else captureEls.set(id, el)
+}
+
+/**
+ * Read the currently registered capture element for a widget. Returns `null`
+ * when no `Widget.State` is on its success path (loading / error / empty)
+ * or when the widget hasn't mounted.
+ */
+export function getCaptureEl(id: string): HTMLElement | null {
+  return captureEls.get(id) ?? null
+}
+
+/** @internal — exposed for tests and debugging only. */
+export function clearAllCaptureEls(): void {
+  captureEls.clear()
+}
+
+/**
+ * Register or clear the live ECharts instance for a widget. Pass `null`
+ * to clear. Called by the `Widget.Echart` bridge on mount / dispose.
+ * Read by actions (e.g. `ZoomToggle`'s disable handler) that need to
+ * dispatch on the live chart without going through the pipeline.
+ *
+ * Notifies subscribers registered via {@link subscribeEchartInstance}
+ * after the map mutation, so reactive consumers (the
+ * `useEchartInstance` hook) re-render with the new value.
+ */
+export function setEchartInstance(id: string, chart: ECharts | null): void {
+  if (chart == null) echartInstances.delete(id)
+  else echartInstances.set(id, chart)
+  echartInstanceSubscribers.get(id)?.forEach((fn) => fn(chart))
+}
+
+/**
+ * Read the currently registered ECharts instance for a widget. Returns
+ * `null` when no `Widget.Echart` is mounted, or before the bridge has
+ * created the instance.
+ */
+export function getEchartInstance(id: string): ECharts | null {
+  return echartInstances.get(id) ?? null
+}
+
+/**
+ * Subscribe to changes of the registered ECharts instance for a widget.
+ * The listener is called *after* every {@link setEchartInstance} (with
+ * the new chart, or `null` when cleared). Returns an unsubscribe
+ * function. Used by the `useEchartInstance` hook to drive React effects
+ * that need to react to instance arrival / departure (e.g.
+ * `BrushToggle`'s `'finished'` re-dispatch loop).
+ */
+export function subscribeEchartInstance(
+  id: string,
+  listener: EchartInstanceListener,
+): () => void {
+  let listeners = echartInstanceSubscribers.get(id)
+  if (!listeners) {
+    listeners = new Set()
+    echartInstanceSubscribers.set(id, listeners)
+  }
+  listeners.add(listener)
+  return () => {
+    const set = echartInstanceSubscribers.get(id)
+    if (!set) return
+    set.delete(listener)
+    if (set.size === 0) echartInstanceSubscribers.delete(id)
+  }
+}
+
+/** @internal — exposed for tests and debugging only. */
+export function clearAllEchartInstances(): void {
+  echartInstances.clear()
+  echartInstanceSubscribers.clear()
+}
+
+/** @internal — exposed for tests and debugging only. */
+export function __debugListWidgetStores(): string[] {
+  return Array.from(widgetStores.keys())
+}
+
+/**
+ * Insert or replace a store entry in the registry without refcounting or
+ * duplicate-id detection. Used by Provider's lazy `useState` init so the
+ * store is reachable from `useWidget(id)` calls in children that render
+ * before the Provider's mount effect runs. Refcounting and dev warns happen
+ * in {@link registerWidgetStore} during the mount effect.
+ *
+ * @internal
+ */
+export function setWidgetStoreEntry(id: string, store: WidgetStoreApi): void {
+  widgetStores.set(id, store)
+}
+
+/** @internal — used by Provider; not part of the public API. */
+export function createWidgetStore(
+  id: string,
+  init: WidgetInit,
+): WidgetStoreApi {
+  const builder = pipelineMiddleware<WidgetState>(() => ({
+    rawData: init.data,
+    data: init.data,
+    dataTransforms: [],
+    configTransforms: [],
+    transformStates: {},
+    isLoading: init.isLoading ?? false,
+    isFetching: init.isFetching ?? false,
+    error: init.error,
+    rawFormatter: init.formatter,
+    formatter: init.formatter,
+    labelFormatter: init.labelFormatter,
+  }))
+
+  const store = createStore<WidgetState>()(
+    devtools(builder, { name: `widget-${id}`, enabled: isDev() }),
+  ) as unknown as WidgetStoreApi
+
+  return store
+}
+
+/** @internal — registers a Provider mount and tracks/warns on duplicate ids in dev. */
+export function registerWidgetStore(id: string, store: WidgetStoreApi): void {
+  widgetStores.set(id, store)
+  const count = (widgetMountCounts.get(id) ?? 0) + 1
+  widgetMountCounts.set(id, count)
+  if (count > 1 && isDev() && !warnedDuplicates.has(id)) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[widgets-v2] Duplicate <Widget.Provider id="${id}"> detected. ` +
+        `Multiple providers sharing an id will race on prop sync and corrupt the store. ` +
+        `Use unique ids per widget instance.`,
+    )
+    warnedDuplicates.add(id)
+  }
+}
+
+/** @internal — Provider unmount counterpart; on last unmount removes the refcount entry. */
+export function unregisterWidgetStore(
+  id: string,
+  options: { keepAlive: boolean },
+): void {
+  const count = (widgetMountCounts.get(id) ?? 1) - 1
+  if (count <= 0) {
+    widgetMountCounts.delete(id)
+    if (!options.keepAlive) widgetStores.delete(id)
+  } else {
+    widgetMountCounts.set(id, count)
+  }
+}
+
+export function useWidget<T, S extends WidgetState = WidgetState>(
+  id: string,
+  selector: (state: S) => T,
+): T {
+  const store = getWidgetStore(id) as unknown as StoreApi<S>
+  return useStore(store, selector)
+}
+
+export function useWidgetShallow<T, S extends WidgetState = WidgetState>(
+  id: string,
+  selector: (state: S) => T,
+): T {
+  const store = getWidgetStore(id) as unknown as StoreApi<S>
+  return useStore(store, useShallow(selector))
+}

package/src/widgets-v2/subheader/style.ts

@@ -0,0 +1,12 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'grid',
+    gridTemplateColumns: '1fr auto',
+    alignItems: 'center',
+    gap: 1,
+    minHeight: 32,
+    pb: 1,
+  },
+} satisfies Record<string, SxProps<Theme>>

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

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { Subheader } from './subheader'
+
+describe('<Subheader>', () => {
+  it('renders children inside a Box', () => {
+    const { getByText } = render(
+      <Subheader>
+        <span>left</span>
+        <span>right</span>
+      </Subheader>,
+    )
+    expect(getByText('left')).toBeTruthy()
+    expect(getByText('right')).toBeTruthy()
+  })
+
+  it('merges caller-supplied sx onto the root', () => {
+    const { container } = render(
+      <Subheader sx={{ mt: 4 }}>
+        <span>x</span>
+      </Subheader>,
+    )
+    expect(container.firstChild).not.toBeNull()
+    // Class-based assertions are brittle; settle for "an element renders + a
+    // single child slot exists" — sx forwarding gets exercised at the
+    // import/MUI level so we don't need to inspect emotion-generated class
+    // names.
+    expect(container.querySelectorAll('span').length).toBe(1)
+  })
+})

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

@@ -0,0 +1,16 @@
+import { Box, type SxProps, type Theme } from '@mui/material'
+import type { ReactNode } from 'react'
+import { styles } from './style'
+
+export interface SubheaderProps {
+  sx?: SxProps<Theme>
+  children: ReactNode
+}
+
+/**
+ * Stateless layout: CSS grid `1fr auto`. Children self-place — typically
+ * `<Widget.SelectionSummary />` (left) and `<Widget.Toolbox>` (right).
+ */
+export function Subheader({ sx, children }: SubheaderProps) {
+  return <Box sx={{ ...styles.root, ...sx }}>{children}</Box>
+}

package/src/widgets-v2/table/download.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createTableDownloadConfig } from './download'
+import type { TableColumn, TableWidgetData } from './types'
+
+const columns: TableColumn[] = [
+  { id: 'name', label: 'Name' },
+  { id: 'score', label: 'Score' },
+]
+const data: TableWidgetData = [
+  { id: 1, name: 'Alpha', score: 10 },
+  { id: 2, name: 'Beta', score: 20 },
+]
+
+let csvText = ''
+
+beforeEach(() => {
+  csvText = ''
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock')
+  vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => undefined)
+  const RealBlob = global.Blob
+  vi.stubGlobal(
+    'Blob',
+    class extends RealBlob {
+      constructor(parts: BlobPart[], opts?: BlobPropertyBag) {
+        csvText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
+
+describe('createTableDownloadConfig', () => {
+  it('CSV-only by default', () => {
+    expect(
+      createTableDownloadConfig({
+        filename: 't',
+        getData: () => data,
+        columns,
+      }).map((i) => i.id),
+    ).toEqual(['csv'])
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createTableDownloadConfig({
+      filename: 't',
+      getData: () => data,
+      columns,
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+  })
+
+  it('CSV resolve uses tableDataToCsv with the supplied columns', async () => {
+    const items = createTableDownloadConfig({
+      filename: 't',
+      getData: () => data,
+      columns,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('t.csv')
+    expect(csvText).toBe('Name,Score\nAlpha,10\nBeta,20')
+  })
+
+  it('CSV guards formula-injection cells end-to-end', async () => {
+    const items = createTableDownloadConfig({
+      filename: 't',
+      getData: () => [{ id: 1, name: '=HYPERLINK("x")', score: 1 }],
+      columns,
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toBe('Name,Score\n"\'=HYPERLINK(""x"")",1')
+  })
+
+  it('CSV calls getData() at click time (not at config creation)', async () => {
+    let snapshot: TableWidgetData = data
+    const items = createTableDownloadConfig({
+      filename: 't',
+      getData: () => snapshot,
+      columns,
+    })
+    snapshot = [{ id: 9, name: 'Gamma', score: 99 }]
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toBe('Name,Score\nGamma,99')
+  })
+})

package/src/widgets-v2/table/download.ts

@@ -0,0 +1,43 @@
+import {
+  buildCsvDownloadItem,
+  buildPngDownloadItem,
+  type DownloadItem,
+} from '../actions/download'
+import { tableDataToCsv } from './helpers'
+import type { TableColumn, TableWidgetData } from './types'
+
+/**
+ * Download menu items for the Table widget. Always includes a CSV item
+ * that pulls the latest data from the widget store via `getData()` (so
+ * locked / sorted / filtered state is honored); headers come from
+ * `column.label`, cells from `row[column.id]`. When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export function createTableDownloadConfig(opts: {
+  filename: string
+  getData: () => TableWidgetData
+  columns: readonly TableColumn[]
+  getCaptureEl?: () => HTMLElement | null
+  pngPixelRatio?: number
+  pngBackgroundColor?: string | null
+}): DownloadItem[] {
+  const items: DownloadItem[] = []
+  if (opts.getCaptureEl) {
+    items.push(
+      buildPngDownloadItem({
+        filename: opts.filename,
+        getCaptureEl: opts.getCaptureEl,
+        pixelRatio: opts.pngPixelRatio,
+        backgroundColor: opts.pngBackgroundColor,
+      }),
+    )
+  }
+  items.push(
+    buildCsvDownloadItem({
+      filename: opts.filename,
+      getCsv: () => tableDataToCsv(opts.getData(), opts.columns),
+    }),
+  )
+  return items
+}

package/src/widgets-v2/table/helpers.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect } from 'vitest'
+import {
+  compareValues,
+  deriveVisibleRows,
+  paginateRows,
+  resolveColumns,
+  sortRows,
+  tableDataToCsv,
+} from './helpers'
+import type { TableColumn, TableRow } from './types'
+
+const ROWS: TableRow[] = [
+  { id: 1, name: 'Alpha', score: 12 },
+  { id: 2, name: 'beta', score: 7 },
+  { id: 3, name: 'Gamma', score: 25 },
+  { id: 4, name: null, score: null },
+]
+
+describe('compareValues', () => {
+  it('orders strings via locale compare', () => {
+    expect(compareValues('a', 'b', 'asc')).toBeLessThan(0)
+    expect(compareValues('b', 'a', 'asc')).toBeGreaterThan(0)
+  })
+
+  it('orders numbers numerically', () => {
+    expect(compareValues(1, 10, 'asc')).toBeLessThan(0)
+    expect(compareValues(10, 1, 'asc')).toBeGreaterThan(0)
+  })
+
+  it('flips comparison for desc', () => {
+    expect(compareValues(1, 10, 'desc')).toBeGreaterThan(0)
+  })
+
+  it('sorts null/undefined to the end', () => {
+    expect(compareValues(null, 5, 'asc')).toBeGreaterThan(0)
+    expect(compareValues(5, null, 'asc')).toBeLessThan(0)
+  })
+})
+
+describe('sortRows', () => {
+  it('sorts numeric column ascending and descending', () => {
+    expect(sortRows(ROWS, 'score', 'asc').map((r) => r.id)).toEqual([
+      2, 1, 3, 4,
+    ])
+    expect(sortRows(ROWS, 'score', 'desc').map((r) => r.id)).toEqual([
+      3, 1, 2, 4,
+    ])
+  })
+
+  it('does not mutate the input', () => {
+    const before = [...ROWS]
+    sortRows(ROWS, 'score', 'asc')
+    expect(ROWS).toEqual(before)
+  })
+})
+
+describe('paginateRows', () => {
+  it('returns the requested slice', () => {
+    expect(paginateRows([1, 2, 3, 4, 5], 0, 2)).toEqual([1, 2])
+    expect(paginateRows([1, 2, 3, 4, 5], 1, 2)).toEqual([3, 4])
+    expect(paginateRows([1, 2, 3, 4, 5], 2, 2)).toEqual([5])
+  })
+
+  it('returns empty for out-of-range pages', () => {
+    expect(paginateRows([1, 2, 3], 5, 2)).toEqual([])
+  })
+})
+
+describe('resolveColumns', () => {
+  const cols: TableColumn[] = [
+    { id: 'a', label: 'A' },
+    { id: 'b', label: 'B' },
+    { id: 'c', label: 'C' },
+  ]
+
+  it('returns input unchanged when no order is provided', () => {
+    expect(resolveColumns(cols, undefined)).toBe(cols)
+  })
+
+  it('reorders by id', () => {
+    expect(resolveColumns(cols, ['c', 'a', 'b']).map((c) => c.id)).toEqual([
+      'c',
+      'a',
+      'b',
+    ])
+  })
+
+  it('skips unknown ids and appends columns missing from the order', () => {
+    expect(resolveColumns(cols, ['c', 'unknown']).map((c) => c.id)).toEqual([
+      'c',
+      'a',
+      'b',
+    ])
+  })
+})
+
+describe('deriveVisibleRows', () => {
+  it('paginates without sort when sort columnId is null', () => {
+    const out = deriveVisibleRows(ROWS, {
+      sort: { columnId: null, direction: 'asc' },
+      page: 0,
+      pageSize: 2,
+    })
+    expect(out.visible.map((r) => r.id)).toEqual([1, 2])
+    expect(out.sorted.length).toBe(4)
+  })
+
+  it('sorts then paginates', () => {
+    const out = deriveVisibleRows(ROWS, {
+      sort: { columnId: 'score', direction: 'asc' },
+      page: 0,
+      pageSize: 2,
+    })
+    expect(out.visible.map((r) => r.id)).toEqual([2, 1])
+  })
+})
+
+describe('compareValues — broader types', () => {
+  it('ranks booleans (false < true)', () => {
+    expect(compareValues(false, true, 'asc')).toBeLessThan(0)
+    expect(compareValues(true, false, 'asc')).toBeGreaterThan(0)
+    expect(compareValues(true, true, 'asc')).toBe(0)
+  })
+
+  it('compares objects/arrays via JSON serialization', () => {
+    expect(compareValues({ a: 1 }, { a: 2 }, 'asc')).toBeLessThan(0)
+    expect(compareValues([1, 2], [1, 1], 'desc')).toBeLessThan(0)
+  })
+
+  it('returns 0 when both sides are null/undefined', () => {
+    expect(compareValues(null, undefined, 'asc')).toBe(0)
+    expect(compareValues(undefined, null, 'desc')).toBe(0)
+  })
+
+  it('returns 0 for mismatched primitive types it does not know how to order', () => {
+    // Not a documented contract but the implementation falls through to cmp = 0
+    // when types don't match — guard the fallthrough behavior so future
+    // refactors notice if they change it.
+    expect(compareValues(1, 'a', 'asc')).toBe(0)
+  })
+})
+
+describe('paginateRows — edge cases', () => {
+  it('returns a copy when pageSize is 0 or negative', () => {
+    const rows = [1, 2, 3]
+    const out = paginateRows(rows, 0, 0)
+    expect(out).toEqual(rows)
+    expect(out).not.toBe(rows)
+    expect(paginateRows(rows, 0, -5)).toEqual(rows)
+  })
+})
+
+describe('resolveColumns — edge cases', () => {
+  const cols: TableColumn[] = [
+    { id: 'a', label: 'A' },
+    { id: 'b', label: 'B' },
+  ]
+  it('returns input unchanged when order is empty', () => {
+    expect(resolveColumns(cols, [])).toBe(cols)
+  })
+
+  it('deduplicates repeated ids in the order', () => {
+    expect(resolveColumns(cols, ['a', 'a', 'b']).map((c) => c.id)).toEqual([
+      'a',
+      'b',
+    ])
+  })
+})
+
+describe('tableDataToCsv', () => {
+  const cols: TableColumn[] = [
+    { id: 'name', label: 'Name' },
+    { id: 'score', label: 'Score' },
+  ]
+
+  it('emits header row + cell rows', () => {
+    const csv = tableDataToCsv(ROWS, cols)
+    const lines = csv.split('\n')
+    expect(lines[0]).toBe('Name,Score')
+    expect(lines[1]).toBe('Alpha,12')
+    expect(lines[2]).toBe('beta,7')
+  })
+
+  it('escapes commas, newlines, and quotes', () => {
+    const csv = tableDataToCsv([{ id: 1, name: 'a, b "c"\nd', score: 1 }], cols)
+    expect(csv).toContain('"a, b ""c""\nd",1')
+  })
+
+  it('renders null cells as empty strings', () => {
+    const csv = tableDataToCsv([ROWS[3]!], cols)
+    expect(csv.split('\n')[1]).toBe(',')
+  })
+
+  it('coerces numeric/boolean header labels and skips ReactNode labels', () => {
+    const numericLabel: TableColumn[] = [
+      { id: 'a', label: 7 as unknown as TableColumn['label'] },
+      { id: 'b', label: true as unknown as TableColumn['label'] },
+      // ReactNode (object) labels degrade to empty string by design.
+      { id: 'c', label: { type: 'span' } as unknown as TableColumn['label'] },
+    ]
+    const csv = tableDataToCsv([], numericLabel)
+    expect(csv).toBe('7,true,')
+  })
+
+  it('serialises array and object cell values as JSON', () => {
+    const csv = tableDataToCsv(
+      [{ id: 1, name: ['x', 'y'], score: { z: 1 } }],
+      cols,
+    )
+    // The JSON contains quotes so the cell wraps + escapes.
+    expect(csv).toContain('"[""x"",""y""]"')
+    expect(csv).toContain('"{""z"":1}"')
+  })
+
+  it('guards against formula injection by prefixing leading =,+,-,@', () => {
+    const csv = tableDataToCsv(
+      [
+        { id: 1, name: '=SUM(A1)', score: '+1' },
+        { id: 2, name: '-2', score: '@cmd' },
+      ],
+      cols,
+    )
+    const lines = csv.split('\n')
+    expect(lines[1]).toBe("'=SUM(A1),'+1")
+    expect(lines[2]).toBe("'-2,'@cmd")
+  })
+
+  it('still wraps a formula cell that also contains a comma', () => {
+    const csv = tableDataToCsv([{ id: 1, name: '=A1,B2', score: 1 }], cols)
+    // Prefixed against injection, then quoted for the embedded comma.
+    expect(csv.split('\n')[1]).toBe('"\'=A1,B2",1')
+  })
+})