@carto/ps-react-ui 4.4.0-chat-ui.5 → 4.4.0-chat-ui.7

package/src/widgets/table/hooks/use-pagination.ts

@@ -1,8 +1,8 @@
 import { useCallback, useMemo } from 'react'
 import type { TableRow, TableWidgetState } from '../types'
 import { paginateData } from '../helpers'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import {
   DEFAULT_PAGE,
   DEFAULT_ROWS_PER_PAGE,
@@ -37,58 +37,42 @@ export interface UsePaginationResult<T> {
 }
 
 /**
- * Hook for managing table pagination
- * Supports both local (client-side) and remote (server-side) pagination
- * State is persisted in the widget store for the given widgetId
+ * Hook for managing table pagination with support for both local (client-side) and remote (server-side) modes.
+ * State is persisted in the widget store for the given widget ID.
+ *
+ * @param widgetId - The widget ID to persist pagination state under.
+ * @param data - The full data array (used for local pagination and total count fallback).
+ * @returns Pagination state and navigation helpers.
+ *
+ * @example
+ * ```tsx
+ * const { page, setPage, paginatedData, totalPages } = usePagination(widgetId, data)
+ * ```
  */
 export function usePagination<T extends TableRow>(
   widgetId: string,
   data: T[],
 ): UsePaginationResult<T> {
-  // Get store actions and state
-  const setWidget = useWidgetStore((state) => state.setWidget)
-  const getWidget = useWidgetStore((state) => state.getWidget)
-  const paginationEnabled = useWidgetStore(
-    useShallow(
-      (state) =>
-        !!(state.widgets[widgetId] as TableWidgetState | undefined)?.pagination,
-    ),
-  )
-  const page = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.page ?? DEFAULT_PAGE,
-    ),
-  )
-  const rowsPerPage = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE,
-    ),
-  )
-  const rowsPerPageOptions = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.rowsPerPageOptions ?? DEFAULT_ROWS_PER_PAGE_OPTIONS,
-    ),
-  )
-  const total = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.pagination
-          ?.total ?? data.length,
-    ),
-  )
-
-  const mode = useWidgetStore(
-    useShallow((state) => {
-      const widget = state.widgets[widgetId] as TableWidgetState | undefined
-      return widget?.mode
-    }),
-  )
+  // Get store state
+  const {
+    paginationEnabled,
+    page,
+    rowsPerPage,
+    rowsPerPageOptions,
+    total,
+    mode,
+  } = useWidgetSelector(widgetId, (w) => {
+    const widget = w as TableWidgetState | undefined
+    return {
+      paginationEnabled: !!widget?.pagination,
+      page: widget?.pagination?.page ?? DEFAULT_PAGE,
+      rowsPerPage: widget?.pagination?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE,
+      rowsPerPageOptions:
+        widget?.pagination?.rowsPerPageOptions ?? DEFAULT_ROWS_PER_PAGE_OPTIONS,
+      total: widget?.pagination?.total ?? data.length,
+      mode: widget?.mode,
+    }
+  })
 
   // Calculate max page
   const maxPage = Math.max(0, Math.ceil(total / (rowsPerPage ?? 1)) - 1)
@@ -97,7 +81,7 @@ export function usePagination<T extends TableRow>(
   const setPage = useCallback(
     (newPage: number) => {
       // Read current state directly from store to avoid stale closures
-      const widget = getWidget<TableWidgetState>(widgetId)
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
       const currentTotal = widget?.pagination?.total ?? data.length
       const currentRowsPerPage =
         widget?.pagination?.rowsPerPage ?? DEFAULT_ROWS_PER_PAGE
@@ -107,21 +91,21 @@ export function usePagination<T extends TableRow>(
       )
       const boundedPage = Math.max(0, Math.min(newPage, currentMaxPage))
 
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         pagination: {
           ...widget?.pagination,
           page: boundedPage,
         },
       })
     },
-    [data.length, getWidget, setWidget, widgetId],
+    [data.length, widgetId],
   )
 
   // Set rows per page and reset to first page
   const setRowsPerPage = useCallback(
     (newRowsPerPage: number) => {
-      const widget = getWidget<TableWidgetState>(widgetId)
-      setWidget<TableWidgetState>(widgetId, {
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         pagination: {
           ...widget?.pagination,
           rowsPerPage: newRowsPerPage,
@@ -129,7 +113,7 @@ export function usePagination<T extends TableRow>(
         },
       })
     },
-    [getWidget, setWidget, widgetId],
+    [widgetId],
   )
 
   // Navigation helpers

package/src/widgets/table/hooks/use-selection.ts

@@ -1,7 +1,7 @@
 import { useCallback, useMemo } from 'react'
 import type { TableRow, TableWidgetState } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
 export interface UseSelectionOptions {
   /** Callback when selection changes */
@@ -30,8 +30,17 @@ export interface UseSelectionResult {
 }
 
 /**
- * Hook for managing table row selection
- * Selection persists across pagination and is stored in the widget store
+ * Hook for managing table row selection with persistence across pagination.
+ * Selection state is stored in the widget store for the given widget ID.
+ *
+ * @param widgetId - The widget ID to persist selection state under.
+ * @param options - Optional configuration including an `onSelectionChange` callback.
+ * @returns Selection state and control functions (toggle, select, deselect, clear).
+ *
+ * @example
+ * ```tsx
+ * const { selectedIds, isAllSelected, handleSelectRow, clearSelection } = useSelection(widgetId)
+ * ```
  */
 export function useSelection(
   widgetId: string,
@@ -39,14 +48,10 @@ export function useSelection(
 ): UseSelectionResult {
   const { onSelectionChange } = options ?? {}
 
-  // Get store actions and state
-  const setWidget = useWidgetStore((state) => state.setWidget)
-  const getWidget = useWidgetStore((state) => state.getWidget)
-  const selected = useWidgetStore(
-    useShallow((state) => {
-      const widget = state.widgets[widgetId] as TableWidgetState | undefined
-      return widget?.selected
-    }),
+  // Get store state
+  const selected = useWidgetSelector(
+    widgetId,
+    (w) => (w as TableWidgetState | undefined)?.selected,
   )
 
   // Use store values with fallback to empty array
@@ -82,14 +87,14 @@ export function useSelection(
   // Toggle selection of a single row
   const toggleRow = useCallback(
     (id: string | number) => {
-      const widget = getWidget<TableWidgetState>(widgetId)
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
       const currentSelected = widget?.selected ?? []
 
       const newSelected = currentSelected.includes(id)
         ? currentSelected.filter((s) => s !== id)
         : [...currentSelected, id]
 
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         selected: newSelected,
       })
 
@@ -97,13 +102,13 @@ export function useSelection(
         onSelectionChange(newSelected)
       }
     },
-    [getWidget, setWidget, widgetId, onSelectionChange],
+    [widgetId, onSelectionChange],
   )
 
   // Toggle selection of all provided rows
   const toggleAll = useCallback(
     (rows: TableRow[]) => {
-      const widget = getWidget<TableWidgetState>(widgetId)
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
       const currentSelected = widget?.selected ?? []
 
       const rowIds = rows.map((row) => row.id)
@@ -113,7 +118,7 @@ export function useSelection(
         ? currentSelected.filter((id) => !rowIds.includes(id))
         : [...new Set([...currentSelected, ...rowIds])]
 
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         selected: newSelected,
       })
 
@@ -121,18 +126,18 @@ export function useSelection(
         onSelectionChange(newSelected)
       }
     },
-    [getWidget, setWidget, widgetId, onSelectionChange],
+    [widgetId, onSelectionChange],
   )
 
   // Select specific rows
   const selectRows = useCallback(
     (ids: (string | number)[]) => {
-      const widget = getWidget<TableWidgetState>(widgetId)
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
       const currentSelected = widget?.selected ?? []
 
       const newSelected = [...new Set([...currentSelected, ...ids])]
 
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         selected: newSelected,
       })
 
@@ -140,18 +145,18 @@ export function useSelection(
         onSelectionChange(newSelected)
       }
     },
-    [getWidget, setWidget, widgetId, onSelectionChange],
+    [widgetId, onSelectionChange],
   )
 
   // Deselect specific rows
   const deselectRows = useCallback(
     (ids: (string | number)[]) => {
-      const widget = getWidget<TableWidgetState>(widgetId)
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
       const currentSelected = widget?.selected ?? []
 
       const newSelected = currentSelected.filter((id) => !ids.includes(id))
 
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         selected: newSelected,
       })
 
@@ -159,21 +164,21 @@ export function useSelection(
         onSelectionChange(newSelected)
       }
     },
-    [getWidget, setWidget, widgetId, onSelectionChange],
+    [widgetId, onSelectionChange],
   )
 
   // Clear all selections
   const clearSelection = useCallback(() => {
     const newSelected: (string | number)[] = []
 
-    setWidget<TableWidgetState>(widgetId, {
+    widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
       selected: newSelected,
     })
 
     if (onSelectionChange) {
       onSelectionChange(newSelected)
     }
-  }, [setWidget, widgetId, onSelectionChange])
+  }, [widgetId, onSelectionChange])
 
   return {
     selectedIds,

package/src/widgets/table/hooks/use-sort.ts

@@ -6,8 +6,8 @@ import type {
   TableWidgetState,
 } from '../types'
 import { sortData } from '../helpers'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 import { DEFAULT_COLUMN_ID, DEFAULT_DIRECTION } from '../config'
 
 export interface UseSortResult<T> extends SortState {
@@ -27,50 +27,41 @@ export interface UseSortResult<T> extends SortState {
 }
 
 /**
- * Hook for managing table sorting
- * Supports both local (client-side) and remote (server-side) sorting
- * State is persisted in the widget store for the given widgetId
+ * Hook for managing table sorting with support for both local (client-side) and remote (server-side) modes.
+ * State is persisted in the widget store for the given widget ID.
+ *
+ * @param widgetId - The widget ID to persist sort state under.
+ * @param data - The data array to sort (for local mode).
+ * @returns Sort state, sorted data, and sort control functions.
+ *
+ * @example
+ * ```tsx
+ * const { sortedData, sortField, sortDirection, handleSort } = useSort(widgetId, data)
+ * ```
  */
 export function useSort<T extends TableRow>(
   widgetId: string,
   data: T[],
 ): UseSortResult<T> {
-  // Get store actions and state
-  const setWidget = useWidgetStore((state) => state.setWidget)
-  const getWidget = useWidgetStore((state) => state.getWidget)
-  const sortEnabled = useWidgetStore(
-    useShallow(
-      (state) =>
-        !!(state.widgets[widgetId] as TableWidgetState | undefined)?.sort,
-    ),
-  )
-  const columnId = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.sort
-          ?.columnId ?? DEFAULT_COLUMN_ID,
-    ),
-  )
-  const direction = useWidgetStore(
-    useShallow(
-      (state) =>
-        (state.widgets[widgetId] as TableWidgetState | undefined)?.sort
-          ?.direction ?? DEFAULT_DIRECTION,
-    ),
-  )
-
-  const mode = useWidgetStore(
-    useShallow((state) => {
-      const widget = state.widgets[widgetId] as TableWidgetState | undefined
-      return widget?.mode
-    }),
+  // Get store state
+  const { sortEnabled, columnId, direction, mode } = useWidgetSelector(
+    widgetId,
+    (w) => {
+      const widget = w as TableWidgetState | undefined
+      return {
+        sortEnabled: !!widget?.sort,
+        columnId: widget?.sort?.columnId ?? DEFAULT_COLUMN_ID,
+        direction: widget?.sort?.direction ?? DEFAULT_DIRECTION,
+        mode: widget?.mode,
+      }
+    },
   )
 
   // Toggle sort on a column
   const toggleSort = useCallback(
     (toggleColumnId: string) => {
       // Read current state directly from store to avoid stale closures
-      const widget = getWidget<TableWidgetState>(widgetId)
+      const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
       const currentColumnId = widget?.sort?.columnId ?? DEFAULT_COLUMN_ID
       const currentDirection = widget?.sort?.direction ?? DEFAULT_DIRECTION
 
@@ -81,42 +72,42 @@ export function useSort<T extends TableRow>(
         newDirection = currentDirection === 'asc' ? 'desc' : 'asc'
       }
 
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         sort: {
           columnId: toggleColumnId,
           direction: newDirection,
         },
       })
     },
-    [getWidget, setWidget, widgetId],
+    [widgetId],
   )
 
   // Set sort state directly
   const setSort = useCallback(
     (newColumnId: string | null, newDirection: SortDirection) => {
-      setWidget<TableWidgetState>(widgetId, {
+      widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
         sort: {
           columnId: newColumnId,
           direction: newDirection,
         },
       })
     },
-    [setWidget, widgetId],
+    [widgetId],
   )
 
   // Clear sort
   const clearSort = useCallback(() => {
-    const widget = getWidget<TableWidgetState>(widgetId)
+    const widget = widgetStoreActions.getWidget<TableWidgetState>(widgetId)
     if (!widget?.sort) return
 
-    setWidget<TableWidgetState>(widgetId, {
+    widgetStoreActions.setWidget<TableWidgetState>(widgetId, {
       sort: {
         ...widget.sort,
         columnId: null,
         direction: 'asc',
       },
     })
-  }, [setWidget, getWidget, widgetId])
+  }, [widgetId])
 
   // Sorted data for local mode
   const sortedData = useMemo(() => {

package/src/widgets/table/index.ts

@@ -8,7 +8,9 @@ export { PaginationActions } from './components/pagination-actions'
 export { Table } from './table-ui'
 
 // Hooks
-export { usePagination, useSort, useSelection } from './hooks'
+export { usePagination } from './hooks/use-pagination'
+export { useSort } from './hooks/use-sort'
+export { useSelection } from './hooks/use-selection'
 
 // Config
 export { tableConfig, tableDownloadConfig } from './config'
@@ -45,9 +47,9 @@ export type {
   PaginationActionsProps,
 } from './types'
 
+export type { UsePaginationResult } from './hooks/use-pagination'
+export type { UseSortResult } from './hooks/use-sort'
 export type {
-  UsePaginationResult,
-  UseSortResult,
   UseSelectionOptions,
   UseSelectionResult,
-} from './hooks'
+} from './hooks/use-selection'

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

@@ -58,7 +58,7 @@ export { Table }
  * Integrates with widget store and provides ref registration using custom hook
  */
 function TableContainer(props: TableUIProps) {
-  const ref = useWidgetRef<HTMLDivElement>(props.id)
+  const { ref } = useWidgetRef<HTMLDivElement>(props.id)
 
   return <MuiTableContainer ref={ref}>{props.children}</MuiTableContainer>
 }

package/src/widgets/table/types.ts

@@ -84,7 +84,7 @@ export interface TableWidgetConfig {
   /** Enable row selection with checkboxes */
   selectable?: boolean
   /** Currently selected row IDs */
-  selected: (string | number)[]
+  selected?: (string | number)[]
   /** Pagination and sort mode: local (client-side) or remote (server-side) */
   mode: Mode
   /** Pagination configuration */

package/src/widgets/timeseries/config.ts

@@ -13,35 +13,29 @@ import {
   buildLegendConfig,
   buildGridConfig,
   createTooltipFormatter,
+  createChartDownloadConfig,
   applyYAxisFormatter,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
+  applyXAxisFormatter,
+  buildSeriesLabelConfig,
+} from '../utils/chart-config'
 
-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 const timeseriesDownloadConfig =
+  createChartDownloadConfig<TimeseriesWidgetData>(flattenObjectArrayToCSV)
 
+/**
+ * Generates ECharts configuration for line and area chart widgets over time, with smooth curves, rotated axis labels, and CARTO qualitative color palette.
+ *
+ * @param props - Timeseries configuration including data and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export function timeseriesConfig(
   props: TimeseriesConfig,
 ): TimeseriesWidgetConfig {
   return {
     type: 'timeseries',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
+    labelFormatter: props.labelFormatter,
   }
 }
 
@@ -49,6 +43,7 @@ function getOption({
   data = [],
   theme,
   formatter,
+  labelFormatter,
 }: TimeseriesConfig): EchartOptionsProps {
   const hasLegend = (data?.length ?? 0) > 1
 
@@ -82,7 +77,7 @@ function getOption({
   }
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
     grid: {
       ...buildGridConfig(hasLegend, theme),
       outerBounds: {
@@ -91,18 +86,21 @@ function getOption({
         top: parseInt(theme.spacing(2)),
       },
     },
-    xAxis: {
-      type: 'category',
-      axisTick: {
-        alignWithLabel: true,
-      },
-      axisLabel: {
-        show: true,
-        showMaxLabel: true,
-        showMinLabel: true,
-        rotate: 45,
+    xAxis: applyXAxisFormatter(
+      {
+        type: 'category',
+        axisTick: {
+          alignWithLabel: true,
+        },
+        axisLabel: {
+          show: true,
+          showMaxLabel: true,
+          showMinLabel: true,
+          rotate: 45,
+        },
       },
-    },
+      labelFormatter,
+    ),
     yAxis: applyYAxisFormatter(yAxis, formatter),
     tooltip: {
       formatter: createTooltipFormatter((item) => {
@@ -117,7 +115,9 @@ function getOption({
 
         const marker = typeof item.marker === 'string' ? item.marker : ''
         const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
-        const name = item.name ?? ''
+        const name = labelFormatter
+          ? String(labelFormatter(item.name ?? ''))
+          : (item.name ?? '')
 
         return { name, seriesName, marker, value: formattedValue }
       }),
@@ -130,6 +130,7 @@ function getOption({
       emphasis: {
         focus: 'series',
       },
+      ...buildSeriesLabelConfig(formatter),
     })),
   } as EchartOptionsProps
 }

package/src/widgets/timeseries/style.ts

@@ -1,5 +1,5 @@
 import type { SxProps, Theme } from '@mui/material'
-import { baseSkeletonStyles } from '../_shared/skeleton'
+import { baseSkeletonStyles } from '../utils/skeleton'
 
 export const styles = {
   skeleton: {

package/src/widgets/utils/chart-config/download-config.ts

@@ -0,0 +1,22 @@
+import { downloadToCSV, downloadToPNG, type DownloadItem } from '../../actions'
+import type { ConfigProps } from '../../loader/types'
+
+export function createChartDownloadConfig<TData>(
+  csvModifier: (data: TData) => string[][],
+) {
+  return function ({ refUI }: ConfigProps): DownloadItem<TData>[] {
+    return [
+      {
+        ...downloadToPNG,
+        modifier: () => downloadToPNG.modifier(refUI),
+      },
+      {
+        ...downloadToCSV,
+        modifier: async (data) => {
+          const rows = csvModifier(data)
+          return downloadToCSV.modifier(rows)
+        },
+      },
+    ]
+  }
+}

package/src/widgets/{_shared → utils}/chart-config/index.ts

@@ -2,6 +2,8 @@
  * Shared utilities for chart widget configuration
  */
 
+export { defaultFormatter, defaultLabelFormatter } from '../formatter'
+
 export { createChartWidgetConfig } from './config-factory'
 export type {
   ChartWidgetBaseConfig,
@@ -19,4 +21,8 @@ export {
   applyXAxisFormatter,
   applyYAxisFormatter,
   niceNum,
+  buildSeriesLabelConfig,
+  buildHistogramSeriesLabelConfig,
 } from './option-builders'
+
+export { createChartDownloadConfig } from './download-config'