@carto/ps-react-ui 4.7.1 → 4.9.0

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

@@ -0,0 +1,179 @@
+import { useCallback, useMemo } from 'react'
+import {
+  getWidgetStore,
+  useWidget,
+  useWidgetId,
+  useWidgetShallow,
+} from '../stores'
+import { TableUI, type TableUIProps } from './table-ui'
+import {
+  DEFAULT_TABLE_PAGE_SIZE,
+  type TableColumn,
+  type TableRow,
+  type TableSortState,
+  type TableWidgetState,
+} from './types'
+import { deriveVisibleRows, resolveColumns } from './helpers'
+
+export interface TableProps<T extends TableRow = TableRow> extends Pick<
+  TableUIProps<T>,
+  | 'pageSizeOptions'
+  | 'selectable'
+  | 'labels'
+  | 'emptyContent'
+  | 'size'
+  | 'keyColumn'
+> {
+  /**
+   * Column definitions. Order can be overridden by ChangeColumn via the
+   * `columnOrder` field on the extended widget state.
+   */
+  columns: readonly TableColumn[]
+  /**
+   * When set, render only the first `visibleColumns` entries **after**
+   * applying the user's `columnOrder` from the store. Useful for showing
+   * a compact projection while letting consumers (e.g. `Widget.ChangeColumn`)
+   * see the full column list. When omitted, every column renders.
+   */
+  visibleColumns?: number
+  /** Initial page size (only on first mount; afterwards lives on the store). */
+  initialPageSize?: number
+  /** Selected row ids (destination-owned). */
+  selection?: readonly (string | number)[]
+  onSelectionChange?: (next: readonly (string | number)[]) => void
+  onRowClick?: (row: T) => void
+  onRowHover?: (row: T | null) => void
+  /**
+   * When `true`, the bridge stops sorting and paginating locally and
+   * renders `data` as-is — the consumer is then responsible for
+   * refetching the slice that matches the active `page` / `pageSize` /
+   * `sort` from the outbound callbacks below. `total` is required in
+   * this mode (the server already knows the full row count; the
+   * widget can't infer it from a partial page).
+   */
+  remote?: boolean
+  /**
+   * Server-reported total row count. Required when `remote === true`;
+   * ignored in local mode (where the bridge derives total from the
+   * sorted result of `deriveVisibleRows`).
+   */
+  total?: number
+  /** Fires after the store-level sort write so the consumer can refetch. */
+  onSortChange?: (next: TableSortState) => void
+  /** Fires after the store-level page write so the consumer can refetch. */
+  onPageChange?: (page: number) => void
+  /** Fires after the store-level pageSize write so the consumer can refetch. */
+  onPageSizeChange?: (pageSize: number) => void
+}
+
+/**
+ * Bridge component — reads the widget store's `data`, applies sort + pagination
+ * locally, and feeds `<TableUI />`. Sort, page, and pageSize live on the
+ * extended widget state ({@link TableWidgetState}).
+ */
+export function Table<T extends TableRow = TableRow>({
+  columns,
+  visibleColumns,
+  initialPageSize = DEFAULT_TABLE_PAGE_SIZE,
+  selection,
+  onSelectionChange,
+  onRowClick,
+  onRowHover,
+  remote = false,
+  total: remoteTotal,
+  onSortChange,
+  onPageChange,
+  onPageSizeChange,
+  ...uiProps
+}: TableProps<T>) {
+  const id = useWidgetId()
+  const data = useWidget(id, (s) => s.data as readonly T[] | undefined)
+  const ui = useWidgetShallow<
+    {
+      sort: TableSortState | undefined
+      page: number
+      pageSize: number
+      columnOrder: readonly string[] | undefined
+    },
+    TableWidgetState
+  >(id, (s) => ({
+    sort: s.sort,
+    page: s.page ?? 0,
+    pageSize: s.pageSize ?? initialPageSize,
+    columnOrder: s.columnOrder,
+  }))
+
+  const orderedColumns = useMemo(() => {
+    const reordered = resolveColumns(columns, ui.columnOrder)
+    return visibleColumns == null
+      ? reordered
+      : reordered.slice(0, visibleColumns)
+  }, [columns, ui.columnOrder, visibleColumns])
+
+  // In remote mode the consumer already paginated / sorted server-side,
+  // so pass `data` and `total` straight through. Local mode keeps the
+  // bridge-driven sort + slice via `deriveVisibleRows`.
+  const { rows, totalRows } = useMemo(() => {
+    if (remote) {
+      return {
+        rows: data ?? [],
+        totalRows: remoteTotal ?? 0,
+      }
+    }
+    const { sorted, visible } = deriveVisibleRows(data ?? [], {
+      sort: ui.sort,
+      page: ui.page,
+      pageSize: ui.pageSize,
+    })
+    return { rows: visible, totalRows: sorted.length }
+  }, [remote, data, remoteTotal, ui.sort, ui.page, ui.pageSize])
+
+  const handleSortChange = useCallback(
+    (next: TableSortState) => {
+      getWidgetStore(id).setState({
+        sort: next,
+        page: 0,
+      } as Partial<TableWidgetState>)
+      onSortChange?.(next)
+    },
+    [id, onSortChange],
+  )
+
+  const handlePageChange = useCallback(
+    (page: number) => {
+      getWidgetStore(id).setState({ page } as Partial<TableWidgetState>)
+      onPageChange?.(page)
+    },
+    [id, onPageChange],
+  )
+
+  const handlePageSizeChange = useCallback(
+    (pageSize: number) => {
+      getWidgetStore(id).setState({
+        pageSize,
+        page: 0,
+      } as Partial<TableWidgetState>)
+      onPageSizeChange?.(pageSize)
+    },
+    [id, onPageSizeChange],
+  )
+
+  return (
+    <TableUI
+      {...uiProps}
+      columns={orderedColumns}
+      rows={rows}
+      total={totalRows}
+      page={ui.page}
+      pageSize={ui.pageSize}
+      sort={ui.sort}
+      selection={selection}
+      onSortChange={handleSortChange}
+      onPageChange={handlePageChange}
+      onPageSizeChange={handlePageSizeChange}
+      onSelectionChange={onSelectionChange}
+      onRowClick={onRowClick}
+      onRowHover={onRowHover}
+    />
+  )
+}

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

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react'
+import type { WidgetState } from '../stores'
+
+/**
+ * Single row of tabular data.
+ *
+ * The default row-identity column is `id`. Consumers that don't have a
+ * literal `id` field can point `<Table>` / `<TableUI>` at a different
+ * column via the `keyColumn` prop; the library reads `row[keyColumn]`
+ * for selection lookup, React keys, and aria labels.
+ */
+export interface TableRow extends Record<string, unknown> {
+  /**
+   * Default row identity. Required when no `keyColumn` is configured.
+   * Omit when wiring `keyColumn` to a different column.
+   */
+  id?: string | number
+}
+
+export type TableWidgetData = readonly TableRow[]
+
+export type TableSortDirection = 'asc' | 'desc'
+
+export interface TableSortState {
+  columnId: string | null
+  direction: TableSortDirection
+}
+
+export interface TableColumn {
+  /** Unique column identifier; matches the field name on each row. */
+  id: string
+  /** Header label. */
+  label: ReactNode
+  align?: 'left' | 'center' | 'right'
+  width?: number | string
+  sortable?: boolean
+  /** Custom cell renderer. Falls back to a string-cast of the raw value. */
+  formatter?: (value: unknown, row: TableRow) => ReactNode
+}
+
+/**
+ * State extension carrying Table-specific UI state on the per-widget store.
+ * Per R12: widget-specific UI state lives in widget-specific extensions of
+ * `WidgetState`, not on the base type.
+ */
+export interface TableWidgetState extends WidgetState {
+  /** Optional reordered column list driven by ChangeColumn. Falls back to props. */
+  columnOrder?: readonly string[]
+  sort?: TableSortState
+  page: number
+  pageSize: number
+}
+
+export const DEFAULT_TABLE_PAGE_SIZE = 10
+export const DEFAULT_TABLE_PAGE_SIZE_OPTIONS = [10, 25, 50, 100] as const

package/src/widgets-v2/test-utils.ts

@@ -0,0 +1,107 @@
+/**
+ * Shared test helpers for widgets-v2 unit tests.
+ *
+ * Keep this file small: only utilities used by 3+ tests live here. One-off
+ * mocks remain inline in their test files to stay legible.
+ *
+ * NOTE: this file is intentionally `.ts` (not `.tsx`) so consumers must
+ * pass JSX in from their own `.tsx` test files. Keeping the module
+ * JSX-free avoids polluting non-React tests with a React dependency.
+ */
+import { vi } from 'vitest'
+import type { ECharts, EChartsOption } from 'echarts'
+import { getWidgetStore, type WidgetState, type WidgetStoreApi } from './stores'
+
+// ─── ECharts instance mock ────────────────────────────────────────────────
+
+export interface MockChartHandlers {
+  finished?: () => void
+  rendered?: () => void
+  click?: (params: unknown) => void
+  globalcursortaken?: (params: unknown) => void
+  datazoom?: (params: unknown) => void
+  brushselected?: (params: unknown) => void
+  brushend?: (params: unknown) => void
+  [key: string]: ((params?: unknown) => void) | undefined
+}
+
+export interface MockChart {
+  dispatchAction: ReturnType<typeof vi.fn>
+  setOption: ReturnType<typeof vi.fn>
+  getOption: ReturnType<typeof vi.fn>
+  resize: ReturnType<typeof vi.fn>
+  clear: ReturnType<typeof vi.fn>
+  dispose: ReturnType<typeof vi.fn>
+  isDisposed: ReturnType<typeof vi.fn>
+  getWidth: ReturnType<typeof vi.fn>
+  getHeight: ReturnType<typeof vi.fn>
+  getDom: ReturnType<typeof vi.fn>
+  on: (event: string, callback: (params?: unknown) => void) => void
+  off: (event: string, callback?: (params?: unknown) => void) => void
+  __handlers: MockChartHandlers
+  __emit: (event: keyof MockChartHandlers, params?: unknown) => void
+}
+
+/**
+ * Returns a duck-typed `ECharts` instance suitable for tests. The instance
+ * captures `on()` handlers in `__handlers` so tests can `__emit('finished')`
+ * directly, and all imperative methods (`dispatchAction`, `setOption`,
+ * `resize`, …) are `vi.fn()` spies.
+ */
+export function createMockChart(): MockChart {
+  const handlers: MockChartHandlers = {}
+  const chart: MockChart = {
+    dispatchAction: vi.fn(),
+    setOption: vi.fn(),
+    getOption: vi.fn(() => ({})),
+    resize: vi.fn(),
+    clear: vi.fn(),
+    dispose: vi.fn(),
+    isDisposed: vi.fn(() => false),
+    getWidth: vi.fn(() => 400),
+    getHeight: vi.fn(() => 300),
+    getDom: vi.fn(() => document.createElement('div')),
+    on: (event, callback) => {
+      handlers[event] = callback as MockChartHandlers[string]
+    },
+    off: (event) => {
+      handlers[event] = undefined
+    },
+    __handlers: handlers,
+    __emit: (event, params) => {
+      handlers[event as string]?.(params)
+    },
+  }
+  return chart
+}
+
+/** Convenience cast for tests that need an `ECharts`-typed reference. */
+export const asEcharts = (chart: MockChart): ECharts =>
+  chart as unknown as ECharts
+
+// ─── Option factory helpers ────────────────────────────────────────────────
+
+/**
+ * Returns a `vi.fn()` option factory. The factory takes the standard
+ * `(option, data, ctx)` signature and returns the supplied `output` unchanged.
+ * Useful when the test only cares about how the bridge wires the factory in.
+ */
+export function createMockOptionFactory(output: EChartsOption = {}) {
+  return vi.fn(() => output)
+}
+
+// ─── Store accessor ────────────────────────────────────────────────────────
+
+/**
+ * Typed re-export of `getWidgetStore(id).getState()` — the verbose form
+ * shows up dozens of times across the suite. Tests that need the store
+ * api itself (`setState`, `subscribe`) still call `getWidgetStore(id)`.
+ */
+export function getState(id: string): WidgetState {
+  return getWidgetStore(id).getState()
+}
+
+/** Typed re-export of `getWidgetStore(id)` for tests that need the api. */
+export function getStore(id: string): WidgetStoreApi {
+  return getWidgetStore(id)
+}

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

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createTimeseriesDownloadConfig } from './download'
+import type { TimeseriesWidgetData } from './types'
+
+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('createTimeseriesDownloadConfig', () => {
+  it('CSV-only by default', () => {
+    expect(
+      createTimeseriesDownloadConfig({
+        filename: 't',
+        getData: () => [[{ name: '2024-01-01', value: 1 }]],
+      }).map((i) => i.id),
+    ).toEqual(['csv'])
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createTimeseriesDownloadConfig({
+      filename: 't',
+      getData: () => [],
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+  })
+
+  it('emits ISO strings for Date keys and aligns rows across series', async () => {
+    const d1 = new Date('2024-01-01T00:00:00.000Z')
+    const d2 = new Date('2024-01-02T00:00:00.000Z')
+    const data: TimeseriesWidgetData = [
+      [
+        { name: d1, value: 1 },
+        { name: d2, value: 2 },
+      ],
+      [{ name: d2, value: 20 }],
+    ]
+    const items = createTimeseriesDownloadConfig({
+      filename: 't',
+      getData: () => data,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('t.csv')
+    expect(csvText).toBe(
+      'time,series_1,series_2\n' +
+        '2024-01-01T00:00:00.000Z,1,\n' +
+        '2024-01-02T00:00:00.000Z,2,20',
+    )
+  })
+
+  it('emits ISO strings for numeric ms-since-epoch keys', async () => {
+    const ts = Date.UTC(2024, 0, 1)
+    const data: TimeseriesWidgetData = [[{ name: ts, value: 7 }]]
+    const items = createTimeseriesDownloadConfig({
+      filename: 't',
+      getData: () => data,
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toContain('2024-01-01T00:00:00.000Z,7')
+  })
+
+  it('passes string time keys through verbatim', async () => {
+    const data: TimeseriesWidgetData = [[{ name: '2024-Q1', value: 1 }]]
+    const items = createTimeseriesDownloadConfig({
+      filename: 't',
+      getData: () => data,
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText).toContain('2024-Q1,1')
+  })
+
+  it('uses supplied seriesNames in the header', async () => {
+    const items = createTimeseriesDownloadConfig({
+      filename: 't',
+      getData: () => [[{ name: '2024', value: 1 }]],
+      seriesNames: ['revenue'],
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText.split('\n')[0]).toBe('time,revenue')
+  })
+})

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

@@ -0,0 +1,86 @@
+import {
+  buildPngDownloadItem,
+  downloadToCSV,
+  type DownloadItem,
+} from '../actions/download'
+import type { TimeseriesWidgetData } from './types'
+
+/**
+ * Download menu items for the Timeseries widget. Always includes a CSV
+ * item with `time, series_1, series_2, …` columns (one row per unique time
+ * across all series; ISO-8601 strings for `Date`/numeric times). When
+ * `getCaptureEl` is supplied, prepends a PNG item that rasterises the
+ * captured element via `html2canvas`.
+ */
+export function createTimeseriesDownloadConfig(args: {
+  filename: string
+  getData: () => TimeseriesWidgetData
+  seriesNames?: readonly string[]
+  getCaptureEl?: () => HTMLElement | null
+  pngPixelRatio?: number
+  pngBackgroundColor?: string | null
+}): DownloadItem[] {
+  const items: DownloadItem[] = []
+  if (args.getCaptureEl) {
+    items.push(
+      buildPngDownloadItem({
+        filename: args.filename,
+        getCaptureEl: args.getCaptureEl,
+        pixelRatio: args.pngPixelRatio,
+        backgroundColor: args.pngBackgroundColor,
+      }),
+    )
+  }
+  items.push({
+    id: 'csv',
+    label: 'Download as CSV',
+    resolve: () => {
+      const data = args.getData()
+      const seriesCount = data.length
+
+      // Collect every unique time, preserving insertion order.
+      const timeKeys: (Date | number | string)[] = []
+      const seenKeys = new Set<string>()
+      for (const series of data) {
+        for (const point of series) {
+          const key = String(point.name)
+          if (!seenKeys.has(key)) {
+            seenKeys.add(key)
+            timeKeys.push(point.name)
+          }
+        }
+      }
+
+      // Build a quick lookup per series for O(rows × series) emit.
+      const lookups = data.map(
+        (series) => new Map(series.map((p) => [String(p.name), p.value])),
+      )
+
+      const header: unknown[] = ['time']
+      for (let i = 0; i < seriesCount; i++) {
+        header.push(args.seriesNames?.[i] ?? `series_${i + 1}`)
+      }
+      const rows: unknown[][] = [header]
+      for (const key of timeKeys) {
+        const row: unknown[] = [formatTime(key)]
+        const lookupKey = String(key)
+        for (const lookup of lookups) row.push(lookup.get(lookupKey) ?? '')
+        rows.push(row)
+      }
+
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  return items
+}
+
+function formatTime(v: Date | number | string): string {
+  if (v instanceof Date) return v.toISOString()
+  if (typeof v === 'number') return new Date(v).toISOString()
+  return v
+}

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

@@ -0,0 +1,10 @@
+export { timeseriesOptions, createTimeseriesOptionFactory } from './options'
+export { TimeseriesSkeleton } from './skeleton'
+export { createTimeseriesDownloadConfig } from './download'
+export type {
+  TimeseriesDatum,
+  TimeseriesWidgetData,
+  TimeseriesOptionsInput,
+  TimeseriesOptionFactoryInput,
+  TimeseriesEChartsOption,
+} from './types'