@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/widgets/table/types.ts

@@ -1,223 +1,55 @@
-import type { ReactNode, Ref } from 'react'
-import type { TableProps as MuiTableProps } from '@mui/material'
-import type { BaseWidgetState, WidgetsStoreProps } from '../stores/types'
-import type { WrapperState } from '../wrapper/types'
-import type { DownloadItem } from '../actions/download/types'
+import type { ReactNode } from 'react'
+import type { WidgetState } from '../stores'
 
 /**
- * Table UI component props
- */
-export interface TableUIProps {
-  id: WidgetsStoreProps['id']
-  children?: ReactNode
-}
-
-/**
- * Table column definition
- */
-export interface TableColumn {
-  /** Unique column identifier, matches key in row data */
-  id: string
-  /** Column header label */
-  label: string | ReactNode
-  /** Text alignment */
-  align?: 'left' | 'center' | 'right'
-  /** Column width (number for px, string for CSS value) */
-  width?: number | string
-  /** Enable sorting for this column */
-  sortable?: boolean
-  /** Custom cell value formatter */
-  formatter?: (value: unknown, row: TableRow) => ReactNode
-}
-
-/**
- * Table row data - extends Record for flexible data
+ * 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> {
-  /** Unique row identifier */
-  id: string | number
+  /**
+   * Default row identity. Required when no `keyColumn` is configured.
+   * Omit when wiring `keyColumn` to a different column.
+   */
+  id?: string | number
 }
 
-/**
- * Table widget data type - array of row records
- */
-export type TableWidgetData = TableRow[]
+export type TableWidgetData = readonly TableRow[]
 
-/**
- * Pagination state
- */
-export interface TablePaginationState {
-  /** Current page (0-indexed) */
-  page: number
-  /** Rows per page */
-  rowsPerPage: number
-  /** Total number of rows (for remote pagination) */
-  total: number
-}
-
-/**
- * Sort direction
- */
-export type SortDirection = 'asc' | 'desc'
+export type TableSortDirection = 'asc' | 'desc'
 
-/**
- * Sort state for single-column sorting
- */
-export interface SortState {
-  /** Column ID being sorted */
+export interface TableSortState {
   columnId: string | null
-  /** Sort direction */
-  direction: SortDirection
-}
-
-/**
- * Pagination and sort mode
- */
-export type Mode = 'local' | 'remote'
-
-/**
- * Table widget configuration
- */
-export interface TableWidgetConfig {
-  /** Column definitions */
-  columns?: TableColumn[]
-  /** Enable row selection with checkboxes */
-  selectable?: boolean
-  /** Currently selected row IDs */
-  selected?: (string | number)[]
-  /** Pagination and sort mode: local (client-side) or remote (server-side) */
-  mode: Mode
-  /** Pagination configuration */
-  pagination?: {
-    /** Current page (0-indexed) */
-    page?: number
-    /** Available rows per page options */
-    rowsPerPageOptions?: number[]
-    /** Default rows per page */
-    rowsPerPage?: number
-    /** Total rows for remote pagination */
-    total?: number
-  }
-  /** Sort configuration */
-  sort?: {
-    /** Default sort column */
-    columnId: string | null
-    /** Default sort direction */
-    direction?: SortDirection
-  }
-  /** Callback when a row is clicked */
-  onRowClick?: (row: TableRow) => void
-  /** Callback when hovering over a row (null when leaving table) */
-  onRowHover?: (row: TableRow | null) => void
-  /** Callback when selection changes */
-  onSelectionChange?: (selected: (string | number)[]) => void
-  /** Callback when page changes (for remote pagination) */
-  onPageChange?: (page: number, rowsPerPage: number) => void
-  /** Callback when sort changes (for remote sorting) */
-  onSortChange?: (columnId: string, direction: SortDirection) => void
+  direction: TableSortDirection
 }
 
-/**
- * Table widget state - includes both configuration and runtime state
- */
-export type TableWidgetState = BaseWidgetState<
-  WrapperState<
-    TableWidgetConfig & {
-      // pagination?: {
-      //   page?: number
-      // }
-    }
-  > & {
-    data: TableWidgetData
-  }
->
-
-/**
- * Table download configuration
- */
-export type TableDownloadConfig = DownloadItem<TableWidgetData>[]
-
-/**
- * Props for the base Table component
- */
-export interface TableProps extends MuiTableProps {
-  /** Table element ref */
-  ref?: Ref<HTMLTableElement>
-}
-
-/**
- * Props for CellHeader component
- */
-export interface CellHeaderProps {
-  /** Column definition */
-  column: TableColumn
-  /** Current sort state */
-  sortState?: SortState
-  /** Callback when sort is triggered */
-  onSort?: (columnId: string) => void
-  /** Whether this is a select-all checkbox header */
-  isSelectAll?: boolean
-  /** Whether all rows are selected */
-  isAllSelected?: boolean
-  /** Whether some rows are selected (indeterminate state) */
-  isIndeterminate?: boolean
-  /** Callback for select-all toggle */
-  onSelectAll?: () => void
-}
-
-/**
- * Props for Row component
- */
-export interface RowProps {
-  /** Row data */
-  row: TableRow
-  /** Column definitions */
-  columns: TableColumn[]
-  /** Whether row is selected */
-  isSelected?: boolean
-  /** Whether selection is enabled */
-  selectable?: boolean
-  /** Callback when row is clicked */
-  onClick?: (row: TableRow) => void
-  /** Callback when row selection is toggled */
-  onSelect?: (row: TableRow) => void
-  /** Callback when mouse enters row */
-  onMouseEnter?: (row: TableRow) => void
-  /** Callback when mouse leaves row */
-  onMouseLeave?: () => void
+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
 }
 
 /**
- * Props for Pagination component
+ * 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 PaginationProps {
-  /** Current page (0-indexed) */
+export interface TableWidgetState extends WidgetState {
+  /** Optional reordered column list driven by ChangeColumn. Falls back to props. */
+  columnOrder?: readonly string[]
+  sort?: TableSortState
   page: number
-  /** Rows per page */
-  rowsPerPage: number
-  /** Total row count */
-  total: number
-  /** Available rows per page options */
-  rowsPerPageOptions?: number[]
-  /** Callback when page changes */
-  onPageChange: (page: number) => void
-  /** Callback when rows per page changes */
-  onRowsPerPageChange: (rowsPerPage: number) => void
+  pageSize: number
 }
 
-/**
- * Props for PaginationActions component
- */
-export interface PaginationActionsProps {
-  /** Current page (0-indexed) */
-  page: number
-  /** Total row count */
-  count: number
-  /** Rows per page */
-  rowsPerPage: number
-  /** Callback when page changes */
-  onPageChange: (
-    event: React.MouseEvent<HTMLButtonElement> | null,
-    newPage: number,
-  ) => void
-}
+export const DEFAULT_TABLE_PAGE_SIZE = 10
+export const DEFAULT_TABLE_PAGE_SIZE_OPTIONS = [10, 25, 50, 100] as const

package/src/{widgets-v2 → widgets}/test-utils.ts

@@ -1,5 +1,5 @@
 /**
- * Shared test helpers for widgets-v2 unit tests.
+ * Shared test helpers for widgets 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.

package/src/{widgets-v2 → widgets}/timeseries/download.ts

@@ -1,38 +1,25 @@
 import {
   buildCsvDownloadItem,
-  buildPngDownloadItem,
-  type DownloadContext,
+  withPngItem,
   type DownloadItem,
+  type WidgetDownloadArgs,
 } 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`.
+ * 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 given, prepends a PNG item that rasterises the captured
+ * element via `html2canvas`.
  */
-export function createTimeseriesDownloadConfig(args: {
-  filename: string
-  getData: (ctx: DownloadContext) => TimeseriesWidgetData
-  seriesNames?: readonly string[]
-  getCaptureEl?: (ctx: DownloadContext) => 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(
+export function createTimeseriesDownloadConfig(
+  args: WidgetDownloadArgs<TimeseriesWidgetData> & {
+    seriesNames?: readonly string[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    args,
     buildCsvDownloadItem({
       filename: args.filename,
       getRows: (ctx) => {
@@ -73,7 +60,6 @@ export function createTimeseriesDownloadConfig(args: {
       },
     }),
   )
-  return items
 }
 
 function formatTime(v: Date | number | string): string {

package/src/widgets/timeseries/index.ts

@@ -1,8 +1,11 @@
+export { timeseriesOptions, createTimeseriesOptionFactory } from './options'
+export { TimeseriesSkeleton } from './skeleton'
+export { createTimeseriesDownloadConfig } from './download'
+export { filterTimeseriesByLockedItems } from './transforms'
 export type {
+  TimeseriesDatum,
   TimeseriesWidgetData,
-  TimeseriesWidgetState,
-  TimeseriesWidgetConfig,
-  TimeseriesConfig,
+  TimeseriesOptionsInput,
+  TimeseriesOptionFactoryInput,
+  TimeseriesEChartsOption,
 } from './types'
-export { timeseriesConfig, timeseriesDownloadConfig } from './config'
-export { TimeseriesSkeleton } from './skeleton'

package/src/{widgets-v2 → widgets}/timeseries/options.ts

@@ -8,7 +8,7 @@ import {
   createTooltipFormatter,
   createTooltipPositioner,
   niceNum,
-} from '../../widgets/utils/chart-config'
+} from '../utils/option-builders'
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'

package/src/widgets/timeseries/skeleton.tsx

@@ -1,54 +1,75 @@
 import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import type { SxProps, Theme } from '@mui/material'
 
+const styles = {
+  container: {
+    display: 'flex',
+    flexDirection: 'column',
+    justifyContent: 'space-between',
+    gap: ({ spacing }) => spacing(1),
+    height: ({ spacing }) => spacing(38),
+  },
+  graph: {
+    position: 'relative',
+    flex: '1 1 auto',
+    width: '100%',
+  },
+  segmentA: {
+    position: 'absolute',
+    left: 0,
+    right: '70%',
+    top: '60%',
+    height: 4,
+  },
+  segmentB: {
+    position: 'absolute',
+    left: '25%',
+    right: '40%',
+    top: '35%',
+    height: 4,
+  },
+  segmentC: {
+    position: 'absolute',
+    left: '55%',
+    right: 0,
+    top: '50%',
+    height: 4,
+  },
+  legend: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(2),
+    height: ({ spacing }) => spacing(5),
+  },
+  legendItem: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1.5),
+  },
+} satisfies Record<string, SxProps<Theme>>
+
+/**
+ * Loading state for the Timeseries widget. Mirrors a line chart's
+ * silhouette — three thin horizontal segments at staggered offsets to
+ * suggest a moving line, plus a 2-dot legend stub. Sibling-consistent
+ * with Bar / Histogram / Scatter skeletons (column-flex container with
+ * legend strip below).
+ */
 export function TimeseriesSkeleton() {
   return (
-    <Box sx={styles.skeleton.graph.container}>
-      {/* Timeseries bar */}
-      <Box sx={styles.skeleton.graph.grid}>
-        <Skeleton
-          sx={styles.skeleton.histogram.item}
-          variant='rectangular'
-          height='20%'
-        />
-        <Skeleton
-          sx={styles.skeleton.histogram.item}
-          variant='rectangular'
-          height='40%'
-        />
-        <Skeleton
-          sx={styles.skeleton.histogram.item}
-          variant='rectangular'
-          height='60%'
-        />
-        <Skeleton
-          sx={styles.skeleton.histogram.item}
-          variant='rectangular'
-          height='20%'
-        />
-        <Skeleton
-          sx={styles.skeleton.histogram.item}
-          variant='rectangular'
-          height='80%'
-        />
+    <Box sx={styles.container}>
+      <Box sx={styles.graph}>
+        <Skeleton variant='rectangular' sx={styles.segmentA} />
+        <Skeleton variant='rectangular' sx={styles.segmentB} />
+        <Skeleton variant='rectangular' sx={styles.segmentC} />
       </Box>
-      {/* Legend */}
-      <Box sx={styles.skeleton.legend}>
-        {Array(2)
-          .fill(0)
-          .map((_, i) => (
-            <Box
-              key={`skeleton-${i}`}
-              sx={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: ({ spacing }) => spacing(1.5),
-              }}
-            >
-              <Skeleton variant='circular' width={8} height={8} />
-              <Skeleton width={48} height={8} />
-            </Box>
-          ))}
+      <Box sx={styles.legend}>
+        {[0, 1].map((i) => (
+          <Box key={`legend-${i}`} sx={styles.legendItem}>
+            <Skeleton variant='circular' width={8} height={8} />
+            <Skeleton width={48} height={8} />
+          </Box>
+        ))}
       </Box>
     </Box>
   )

package/src/widgets/timeseries/types.ts

@@ -1,17 +1,65 @@
-import type { EchartWidgetData, EchartWidgetState } from '../echart'
-import type {
-  EchartWidgetOptionProps,
-  EchartWidgetProps,
-} from '../echart/types'
-import type { ConfigProps } from '../loader'
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
 
-export type TimeseriesWidgetData = EchartWidgetData
+/**
+ * A single point on a time series. `name` is the time coordinate — accepts a
+ * Date object, a number (ms-since-epoch), or an ISO-8601 string. ECharts'
+ * time axis parses any of these.
+ */
+export interface TimeseriesDatum {
+  name: Date | number | string
+  value: number
+}
+
+/** Timeseries widget data — one array of points per series. */
+export type TimeseriesWidgetData = readonly (readonly TimeseriesDatum[])[]
 
-export type TimeseriesWidgetState = EchartWidgetState
+/** Inputs to the structural-only {@link timeseriesOptions} builder. */
+export interface TimeseriesOptionsInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  /** Optional formatter for the time-axis tick labels. Receives a JS Date. */
+  labelFormatter?: (value: Date) => string
+}
 
-export type TimeseriesWidgetConfig = EchartWidgetProps & {
-  type: 'timeseries'
+/**
+ * Combined inputs for the timeseries option factory creator. Carries
+ * everything the widget needs across BOTH phases — the structural-build
+ * (`theme`, `formatter`, `labelFormatter`, `optionsOverride`) AND the
+ * data merge (`series`, `smooth`, `area`, `selection`).
+ */
+export interface TimeseriesOptionFactoryInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  /**
+   * Time-axis label formatter (also used in the tooltip name). Receives
+   * a JS Date — applied both at structural-build time (x-axis ticks) and
+   * at fusion time (tooltip name) so the date-aware labeling survives
+   * RelativeData's reactive formatter swaps.
+   */
+  labelFormatter?: (value: Date) => string
+  /**
+   * Per-series metadata — drives the legend, `series[i].name`, and
+   * (when `color` is set) per-series line + marker colour overrides.
+   */
+  series?: readonly WidgetSeries[]
+  /** Smooth lines (default `true`). */
+  smooth?: boolean
+  /** Filled area below each line (default `false`). */
+  area?: boolean
+  /**
+   * Selected point keys (matched against `TimeseriesDatum.name`; `Date`
+   * names are normalized to ms-since-epoch). Points not in this list render
+   * dimmed (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
+   */
+  selection?: readonly (string | number)[] | null
+  /**
+   * Consumer-supplied partial option merged into the structural option at
+   * structural-build time. Lets stories override pieces of the theme-aware
+   * base without forking the structural builder.
+   */
+  optionsOverride?: Partial<EChartsOption>
 }
 
-export type TimeseriesConfig = ConfigProps &
-  EchartWidgetOptionProps<TimeseriesWidgetData>
+export type TimeseriesEChartsOption = EChartsOption

package/src/{widgets-v2 → widgets}/types.ts

@@ -1,3 +1,5 @@
+import type { PaletteColor } from '../components/types'
+
 /**
  * Canonical cross-widget series metadata.
  *
@@ -11,15 +13,15 @@
  * (`FormulaSeries`, `CategorySeriesConfig`) are kept as type aliases of
  * `WidgetSeries` — see `formula/types.ts` and `category/types.ts`.
  *
- * Colours accept MUI theme paths (e.g. `'primary.main'`) as well as raw
- * CSS strings (`'#ff0000'`, `'rgb(…)'`). The echart-based widgets
- * resolve them through `resolveThemeColor` (see
- * `widgets-v2/utils/resolve-theme-color.ts`); Category and Formula/Spread
- * resolve them implicitly via MUI's `sx` prop.
+ * Colours are {@link PaletteColor}: a theme path (`'primary.main'`) or a raw
+ * CSS string (`'#ff0000'`). Formula and Spread hand them to `sx`, which
+ * resolves paths itself; the echart widgets and Category paint outside `sx`
+ * and go through `resolveThemeColor` (see
+ * `widgets/utils/resolve-theme-color.ts`).
  */
 export interface WidgetSeries {
   /** Display name — drives legend, tooltip, and avatar glyphs. */
   name: string
   /** Optional colour override. MUI theme path or raw CSS string. */
-  color?: string
+  color?: PaletteColor
 }

package/src/widgets/utils/index.ts

@@ -1,26 +1,3 @@
-// Formatter
-export { defaultFormatter, defaultLabelFormatter } from './formatter'
-
-// Chart configuration
-export { createChartWidgetConfig } from './chart-config'
-export type {
-  ChartWidgetBaseConfig,
-  CreateChartWidgetConfigParams,
-} from './chart-config'
-export { flattenObjectArrayToCSV, scatterplotDataToCSV } from './chart-config'
-export {
-  buildLegendConfig,
-  buildGridConfig,
-  createTooltipPositioner,
-  createAxisLabelFormatter,
-  createTooltipFormatter,
-  applyXAxisFormatter,
-  applyYAxisFormatter,
-  niceNum,
-} from './chart-config'
-
-// Skeleton styles
-export { baseSkeletonStyles } from './skeleton'
-
-// Download config factory
-export { createChartDownloadConfig } from './chart-config'
+export { mergeOptions } from './merge-options'
+export { positionDataZoomForLegend } from './data-zoom-layout'
+export { resolveThemeColor } from './resolve-theme-color'

package/src/widgets/wrapper/index.ts

@@ -1,16 +1,14 @@
-// Subcomponents for advanced stories
-export { Actions } from './components/actions'
-export { Options } from './components/options'
-export { Title } from './components/title'
-
-export { WidgetWrapper } from './wrapper'
-export { WrapperUI } from './wrapper-ui'
-
-export type {
-  WrapperActionsProps,
-  WrapperOption,
-  WrapperOptionsProps,
-  WrapperProps,
-  WrapperState,
-  WrapperUIProps,
-} from './types'
+export { Wrapper, type WrapperProps } from './widget-wrapper'
+export {
+  Actions,
+  Options,
+  type ActionsProps,
+  type OptionsProps,
+} from './widget-actions'
+export {
+  Content,
+  Footer,
+  type ContentProps,
+  type FooterProps,
+} from './widget-content'
+export { DEFAULT_WRAPPER_LABELS, type WrapperLabels } from './labels'