@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/table/types.ts

@@ -0,0 +1,223 @@
+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'
+
+/**
+ * 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) => ReactNode
+}
+
+/**
+ * Table row data - extends Record for flexible data
+ */
+export interface TableRow extends Record<string, unknown> {
+  /** Unique row identifier */
+  id: string | number
+}
+
+/**
+ * Table widget data type - array of row records
+ */
+export type TableWidgetData = 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'
+
+/**
+ * Sort state for single-column sorting
+ */
+export interface SortState {
+  /** Column ID being sorted */
+  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
+}
+
+/**
+ * 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
+}
+
+/**
+ * Props for Pagination component
+ */
+export interface PaginationProps {
+  /** Current page (0-indexed) */
+  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
+}
+
+/**
+ * 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
+}

package/src/widgets/timeseries/config.ts

@@ -0,0 +1,135 @@
+import {
+  getCommonOptions,
+  mergeEchartWidgetConfig,
+  type EchartOptionsProps,
+} from '../echart'
+import type {
+  TimeseriesConfig,
+  TimeseriesWidgetConfig,
+  TimeseriesWidgetData,
+} from './types'
+import {
+  flattenObjectArrayToCSV,
+  buildLegendConfig,
+  buildGridConfig,
+  createTooltipFormatter,
+  applyYAxisFormatter,
+} from '../_shared/chart-config'
+import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
+import type { ConfigProps } from '../loader/types'
+
+export function timeseriesDownloadConfig({
+  refUI,
+}: ConfigProps): DownloadItem<TimeseriesWidgetData>[] {
+  return [
+    {
+      ...downloadToPNG,
+      modifier: () => downloadToPNG.modifier(refUI),
+    },
+    {
+      ...downloadToCSV,
+      modifier: async (data) => {
+        const rows = flattenObjectArrayToCSV(data)
+        return downloadToCSV.modifier(rows)
+      },
+    },
+  ]
+}
+
+export function timeseriesConfig(
+  props: TimeseriesConfig,
+): TimeseriesWidgetConfig {
+  return {
+    type: 'timeseries',
+    option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+  }
+}
+
+function getOption({
+  data = [],
+  theme,
+  formatter,
+}: TimeseriesConfig): EchartOptionsProps {
+  const hasLegend = (data?.length ?? 0) > 1
+
+  const yAxis = {
+    type: 'value' as const,
+    axisLabel: {
+      margin: 0,
+      padding: [
+        0,
+        parseInt(theme.spacing(0.75)),
+        parseInt(theme.spacing(1.25)),
+        -parseInt(theme.spacing(1)),
+      ],
+      show: true,
+      showMaxLabel: true,
+      showMinLabel: false,
+      verticalAlign: 'bottom' as const,
+    },
+    axisLine: {
+      show: false,
+    },
+    axisTick: {
+      show: false,
+    },
+    splitLine: {
+      show: true,
+      lineStyle: {
+        color: theme.palette.black[4],
+      },
+    },
+  }
+
+  return {
+    legend: buildLegendConfig(hasLegend),
+    grid: {
+      ...buildGridConfig(hasLegend, theme),
+      outerBounds: {
+        left: parseInt(theme.spacing(3)),
+        right: parseInt(theme.spacing(1)),
+        top: parseInt(theme.spacing(2)),
+      },
+    },
+    xAxis: {
+      type: 'category',
+      axisTick: {
+        alignWithLabel: true,
+      },
+      axisLabel: {
+        show: true,
+        showMaxLabel: true,
+        showMinLabel: true,
+        rotate: 45,
+      },
+    },
+    yAxis: applyYAxisFormatter(yAxis, formatter),
+    tooltip: {
+      formatter: createTooltipFormatter((item) => {
+        const value = item.value as Record<string, string | number>
+        const index = item.dimensionNames?.[item.encode?.y?.at(0) ?? 1]
+        const _value = value[index ?? '']
+
+        const formattedValue =
+          typeof _value === 'number' && formatter
+            ? formatter(_value)
+            : (_value ?? '')
+
+        const marker = typeof item.marker === 'string' ? item.marker : ''
+        const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
+        const name = item.name ?? ''
+
+        return { name, seriesName, marker, value: formattedValue }
+      }),
+    },
+    color: Object.values(theme.palette.qualitative.bold),
+    series: data.map((_: unknown, index: number) => ({
+      datasetIndex: index,
+      type: 'line',
+      smooth: true,
+      emphasis: {
+        focus: 'series',
+      },
+    })),
+  } as EchartOptionsProps
+}

package/src/widgets/timeseries/index.ts

@@ -0,0 +1,8 @@
+export type {
+  TimeseriesWidgetData,
+  TimeseriesWidgetState,
+  TimeseriesWidgetConfig,
+  TimeseriesConfig,
+} from './types'
+export { timeseriesConfig, timeseriesDownloadConfig } from './config'
+export { TimeseriesSkeleton } from './skeleton'

package/src/widgets/timeseries/skeleton.tsx

@@ -0,0 +1,55 @@
+import { Box, Skeleton } from '@mui/material'
+import { styles } from './style'
+
+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>
+      {/* Legend */}
+      <Box sx={styles.skeleton.legend}>
+        {Array(2)
+          .fill(0)
+          .map((_, i) => (
+            <Box
+              key={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>
+    </Box>
+  )
+}

package/src/widgets/timeseries/style.ts

@@ -0,0 +1,36 @@
+import type { SxProps, Theme } from '@mui/material'
+import { baseSkeletonStyles } from '../_shared/skeleton'
+
+export const styles = {
+  skeleton: {
+    graph: {
+      container: {
+        ...baseSkeletonStyles.graph.container,
+        position: 'relative',
+      },
+      grid: {
+        display: 'flex',
+        justifyContent: 'space-between',
+        flex: '1 1 auto',
+        alignItems: 'flex-end',
+        width: '100%',
+      },
+    },
+    histogram: {
+      item: {
+        flex: 1,
+        maxWidth: ({ spacing }) => spacing(8),
+
+        '& + &': {
+          marginLeft: '1px',
+        },
+      },
+    },
+    legend: {
+      display: 'flex',
+      alignItems: 'center',
+      gap: ({ spacing }) => spacing(2),
+      height: ({ spacing }) => spacing(5),
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/timeseries/types.ts

@@ -0,0 +1,17 @@
+import type { EchartWidgetData, EchartWidgetState } from '../echart'
+import type {
+  EchartWidgetOptionProps,
+  EchartWidgetProps,
+} from '../echart/types'
+import type { ConfigProps } from '../loader'
+
+export type TimeseriesWidgetData = EchartWidgetData
+
+export type TimeseriesWidgetState = EchartWidgetState
+
+export type TimeseriesWidgetConfig = EchartWidgetProps & {
+  type: 'timeseries'
+}
+
+export type TimeseriesConfig = ConfigProps &
+  EchartWidgetOptionProps<TimeseriesWidgetData>

package/src/widgets/toolbar-actions/index.ts

@@ -0,0 +1,6 @@
+export type {
+  ToolbarAction,
+  ToolbarActionsLabels,
+  ToolbarActionsProps,
+} from './types'
+export { ToolbarActions } from './toolbar-actions'

package/src/widgets/toolbar-actions/styles.ts

@@ -0,0 +1,38 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    alignItems: 'center',
+    width: 'fit-content',
+    overflow: 'hidden',
+    borderRadius: ({ spacing }) => spacing(0.5),
+    gap: ({ spacing }) => spacing(0.25),
+  },
+  preview: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(0.25),
+  },
+  actionsContainer: {
+    position: 'absolute',
+    display: 'flex',
+    alignItems: 'center',
+    backgroundColor: ({ palette }) => palette.background.default,
+    padding: ({ spacing }) => spacing(0.25),
+    gap: ({ spacing }) => spacing(0.25),
+  },
+  iconButton: {
+    width: ({ spacing }) => spacing(4),
+    height: ({ spacing }) => spacing(4),
+    borderRadius: 0,
+    '.MuiTouchRipple-ripple .MuiTouchRipple-child': {
+      borderRadius: 0,
+    },
+  },
+  triggerButton: {
+    '&[data-active="true"]': {
+      backgroundColor: ({ palette }) => palette.primary.relatedLight,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>