@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

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

@@ -0,0 +1,28 @@
+/**
+ * `LockSelection` filter for Table. Data is a FLAT `TableRow[]` (unlike every
+ * other widget's `X[][]` series shape) and row identity comes from
+ * `row[keyColumn]` (default `'id'`), not `name` — so `filterByLockedItems`
+ * doesn't apply here (its outer `.map` treats each row as a "series", and a
+ * plain row object isn't an array, so it would silently pass everything
+ * through unfiltered). Falls back to the row's index when the identity
+ * column is nullish, mirroring `TableUI`'s own `resolveRowId`.
+ *
+ * `keyColumn` arrives as `LockSelection`'s `filterKey`, so pass this by
+ * reference: `filterFn={filterTableByLockedRows} filterKey={keyColumn}`.
+ * Don't close over it — `filterFn`'s identity is not a pipeline dependency,
+ * so a captured key changes without re-running anything.
+ */
+export function filterTableByLockedRows(
+  input: unknown,
+  lockedItems: readonly (string | number)[],
+  keyColumn: string | number = 'id',
+): unknown {
+  if (lockedItems.length === 0) return input
+  if (!Array.isArray(input)) return input
+  const locked = new Set<string | number>(lockedItems)
+  return input.filter((row: unknown, index: number): boolean => {
+    if (row == null || typeof row !== 'object') return false
+    const id = (row as Record<string, unknown>)[keyColumn] ?? index
+    return (typeof id === 'string' || typeof id === 'number') && locked.has(id)
+  })
+}

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,82 @@
+import {
+  buildCsvDownloadItem,
+  buildPngDownloadItem,
+  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(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        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)
+        }
+
+        return rows
+      },
+    }),
+  )
+  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,11 @@
+export { timeseriesOptions, createTimeseriesOptionFactory } from './options'
+export { TimeseriesSkeleton } from './skeleton'
+export { createTimeseriesDownloadConfig } from './download'
+export { filterTimeseriesByLockedItems } from './transforms'
+export type {
+  TimeseriesDatum,
+  TimeseriesWidgetData,
+  TimeseriesOptionsInput,
+  TimeseriesOptionFactoryInput,
+  TimeseriesEChartsOption,
+} from './types'