@carto/ps-react-ui 4.4.1 → 4.4.2

package/src/widgets/loader/utils.ts

@@ -9,9 +9,21 @@ export type ConfigOrFn<TConfig, TData = unknown> =
   | ((baseConfig: TConfig, data: TData) => Partial<TConfig>)
 
 /**
- * Resolves a config that may be either an object or a function.
- * If it's a function, calls it with baseConfig and data.
- * If it's an object (or undefined), returns it as-is.
+ * Resolves a widget config that may be either a partial object or a function receiving the computed base config and data. If it is a function, calls it with `baseConfig` and `data`; otherwise returns the value as-is.
+ *
+ * @param config - The config object or function to resolve.
+ * @param baseConfig - The computed base configuration.
+ * @param data - The widget data.
+ * @returns Resolved partial config, or undefined.
+ *
+ * @example
+ * ```tsx
+ * const resolved = resolveConfig(
+ *   (base, data) => ({ maxItems: base.maxItems + 5 }),
+ *   baseConfig,
+ *   widgetData,
+ * )
+ * ```
  */
 export function resolveConfig<TConfig, TData>(
   config: ConfigOrFn<TConfig, TData> | undefined,
@@ -24,6 +36,17 @@ export function resolveConfig<TConfig, TData>(
   return config
 }
 
+/**
+ * Deep-merges two partial widget config objects using `deepmerge`, with arrays replaced rather than concatenated.
+ *
+ * @param options - A tuple of two partial configs to merge (base and override).
+ * @returns The merged config object.
+ *
+ * @example
+ * ```tsx
+ * const finalConfig = mergeWidgetConfig(baseConfig, resolvedConfig)
+ * ```
+ */
 export function mergeWidgetConfig<T>(
   ...options: [Partial<T> | undefined, Partial<T> | undefined]
 ): T {

package/src/widgets/markdown/config.ts

@@ -1,6 +1,11 @@
 import { downloadToCSV, type DownloadItem } from '../actions'
 import type { MarkdownWidgetConfig, MarkdownWidgetData } from './types'
 
+/**
+ * Creates download configuration for markdown widgets, supporting CSV export of text content. Does not require `refUI` since it only exports text.
+ *
+ * @returns Array of download items for use with the Download action.
+ */
 export function markdownDownloadConfig(): DownloadItem<MarkdownWidgetData>[] {
   return [
     {
@@ -13,6 +18,11 @@ export function markdownDownloadConfig(): DownloadItem<MarkdownWidgetData>[] {
   ]
 }
 
+/**
+ * Returns the default configuration for markdown content display widgets.
+ *
+ * @returns Default markdown widget config (empty object).
+ */
 export function markdownConfig(): MarkdownWidgetConfig {
   return {}
 }

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

@@ -38,6 +38,13 @@ const COMPONENTS: Components = {
   li: ({ children }) => <ListItem sx={styles.li}>{children}</ListItem>,
 }
 
+/**
+ * Presentational component that renders a Markdown string as MUI-styled HTML using react-markdown.
+ *
+ * @remarks
+ * Maps Markdown elements (headings, paragraphs, links, lists) to MUI Typography and Link components.
+ * Custom component overrides can be passed via the `overrides` prop.
+ */
 export function MarkdownUI({ children, overrides }: MarkdownComponentProps) {
   return (
     <ReactMarkdown

package/src/widgets/markdown/markdown.tsx

@@ -4,6 +4,9 @@ import type { MarkdownWidgetData } from './types'
 import { MarkdownUI } from '.'
 import { useShallow } from 'zustand/shallow'
 
+/**
+ * Stateful markdown widget component that reads content from the widget store and renders it as formatted rich text.
+ */
 export function Markdown({ id }: MarkdownUIProps) {
   const content = useWidgetStore(
     useShallow(

package/src/widgets/note/note.tsx

@@ -37,6 +37,16 @@ const COMPONENTS: Components = {
   li: DEFAULT_P,
 }
 
+/**
+ * Displays text content with markdown support and automatic show more/less functionality for long content. Automatically detects content exceeding 3 lines and shows an expand/collapse button.
+ *
+ * @example
+ * ```tsx
+ * <WidgetNote>
+ *   {"**Important:** This data is from Q4 2024."}
+ * </WidgetNote>
+ * ```
+ */
 export function WidgetNote({
   children,
   labels = DEFAULT_LABELS,

package/src/widgets/pie/config.ts

@@ -8,33 +8,27 @@ import {
   buildGridConfig,
   buildLegendConfig,
   flattenObjectArrayToCSV,
+  createTooltipPositioner,
   createTooltipFormatter,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
-
-export function pieDownloadConfig({
-  refUI,
-}: ConfigProps): DownloadItem<PieWidgetData>[] {
-  return [
-    {
-      ...downloadToPNG,
-      modifier: () => downloadToPNG.modifier(refUI),
-    },
-    {
-      ...downloadToCSV,
-      modifier: async (data) => {
-        const rows = flattenObjectArrayToCSV(data)
-        return downloadToCSV.modifier(rows)
-      },
-    },
-  ]
-}
+  createChartDownloadConfig,
+  niceNum,
+} from '../utils/chart-config'
 
+export const pieDownloadConfig = createChartDownloadConfig<PieWidgetData>(
+  flattenObjectArrayToCSV,
+)
+
+/**
+ * Generates ECharts configuration for pie and donut chart widgets. Falls back to a horizontal bar layout when multiple data series are provided.
+ *
+ * @param props - Pie chart configuration including data and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export function pieConfig(props: PieConfig): PieWidgetConfig {
   return {
     type: 'pie',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
   }
 }
 
@@ -46,22 +40,83 @@ function getOption({
   const multiSeries = (data?.length ?? 0) > 1
 
   if (multiSeries) {
+    let niceMin = 0
+    let niceMax = 1
+
     return {
+      legend: buildLegendConfig(true),
+      grid: {
+        ...buildGridConfig(true, theme),
+        right: parseInt(theme.spacing(4)),
+      },
       xAxis: {
         type: 'value',
-        show: true,
+        min: (extent: { min: number }) => {
+          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          return niceMin
+        },
+        max: (extent: { min: number; max: number }) => {
+          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          return niceMax
+        },
+        axisLabel: {
+          fontSize: theme.typography.overlineDelicate.fontSize,
+          fontFamily: theme.typography.overlineDelicate.fontFamily,
+          margin: parseInt(theme.spacing(1)),
+          show: true,
+          showMaxLabel: true,
+          showMinLabel: true,
+          verticalAlign: 'bottom' as const,
+          inside: true,
+          formatter: (value: number) => {
+            if (value !== niceMax && value !== niceMin) return ''
+            if (value === 0) return ''
+            return formatter ? formatter(value) : String(value)
+          },
+        },
+        axisLine: {
+          show: false,
+        },
+        axisTick: {
+          show: false,
+        },
+        splitLine: {
+          show: true,
+          lineStyle: {
+            color: theme.palette.black[4],
+          },
+        },
       },
       yAxis: {
         type: 'category',
-        show: true,
-      },
-      legend: {
-        show: true,
-        bottom: 0,
+        axisLine: {
+          show: false,
+        },
+        axisTick: {
+          show: false,
+        },
+        axisLabel: {
+          padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        },
       },
-      grid: {
-        bottom: parseInt(theme.spacing(4)),
-        right: parseInt(theme.spacing(4)),
+      tooltip: {
+        position: createTooltipPositioner(theme),
+        formatter: createTooltipFormatter((item) => {
+          const value = item.value as Record<string, string | number>
+          const index = item.dimensionNames?.[item.encode?.x?.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 }
+        }),
       },
       series: data.map((_: unknown, index: number) => ({
         datasetIndex: index,

package/src/widgets/pie/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/range/components/range-item.tsx

@@ -5,10 +5,13 @@ import type { RangeItemProps, RangeWidgetState } from '../types'
 import { styles } from '../style'
 import { useShallow } from 'zustand/shallow'
 
-type EditingState = '' | 'min' | 'max'
+import { defaultFormatter } from '../../utils/formatter'
 
-const defaultFormatter = (value: number) => value.toString()
+type EditingState = '' | 'min' | 'max'
 
+/**
+ * Renders a single range slider with editable min/max text inputs, reading its configuration from the widget store.
+ */
 export function RangeItem({ id, index }: RangeItemProps) {
   const item = useWidgetStore(
     useShallow((state) => state.getWidget<RangeWidgetState>(id)?.data[index]),

package/src/widgets/range/config.ts

@@ -1,5 +1,10 @@
 import type { RangeWidgetConfig } from './types'
 
+/**
+ * Returns the default configuration for range (value range with labels) widgets.
+ *
+ * @returns Default range widget config.
+ */
 export function rangeConfig(): RangeWidgetConfig {
   return {}
 }

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

@@ -2,6 +2,9 @@ import type { RangeUIProps } from './types'
 import { Row } from '../formula/components/row'
 import { RangeItem } from './components/range-item'
 
+/**
+ * Renders a range widget with one or more interactive dual-slider controls for selecting value ranges.
+ */
 export function RangeUI(props: RangeUIProps) {
   return (
     <Row id={props.id}>

package/src/widgets/scatterplot/config.ts

@@ -12,35 +12,26 @@ import {
   scatterplotDataToCSV,
   buildLegendConfig,
   createTooltipFormatter,
+  createChartDownloadConfig,
   applyYAxisFormatter,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
+} from '../utils/chart-config'
 
-export function scatterplotDownloadConfig({
-  refUI,
-}: ConfigProps): DownloadItem<ScatterplotWidgetData>[] {
-  return [
-    {
-      ...downloadToPNG,
-      modifier: () => downloadToPNG.modifier(refUI),
-    },
-    {
-      ...downloadToCSV,
-      modifier: async (data) => {
-        const rows = scatterplotDataToCSV(data)
-        return downloadToCSV.modifier(rows)
-      },
-    },
-  ]
-}
+export const scatterplotDownloadConfig =
+  createChartDownloadConfig<ScatterplotWidgetData>(scatterplotDataToCSV)
 
+/**
+ * Generates ECharts configuration for X-Y scatter plot widgets with value axes, legend support, and CARTO qualitative color palette.
+ *
+ * @param props - Scatterplot configuration including data points and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export function scatterplotConfig(
   props: ScatterplotConfig,
 ): ScatterplotWidgetConfig {
   return {
     type: 'scatterplot',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
   }
 }
 

package/src/widgets/scatterplot/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/selection-summary/selection-summary.tsx

@@ -13,6 +13,17 @@ const DEFAULT_SELECTION_LABELS: SelectionSummaryLabels = {
   clear: 'Clear',
 }
 
+/**
+ * Displays the count of selected items with an optional clear button. Commonly used with the LockSelection action to show selection state in widgets.
+ *
+ * @example
+ * ```tsx
+ * <WidgetSelectionSummary
+ *   selections={selectedItems.length}
+ *   onClear={() => setSelectedItems([])}
+ * />
+ * ```
+ */
 export function WidgetSelectionSummary({
   selections,
   onClear,

package/src/widgets/skeleton-loader/skeleton-loader.tsx

@@ -3,6 +3,16 @@ import { useWidgetStore } from '../stores/widget-store'
 import { Suspense } from 'react'
 import { useShallow } from 'zustand/shallow'
 
+/**
+ * Displays a skeleton loading placeholder while widget data is loading. Subscribes to widget loading state in the store and renders the provided Skeleton component or children accordingly.
+ *
+ * @example
+ * ```tsx
+ * <SkeletonLoader id="sales-chart" Skeleton={BarSkeleton}>
+ *   <Bar id="sales-chart" />
+ * </SkeletonLoader>
+ * ```
+ */
 export function SkeletonLoader({
   id,
   children,

package/src/widgets/spread/components/max-value.tsx

@@ -2,9 +2,11 @@ import { type SpreadWidgetState, type ValueProps } from '../types'
 import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from '../../formula/components/item'
 import { useShallow } from 'zustand/shallow'
+import { defaultFormatter } from '../../utils/formatter'
 
-const defaultFormatter = (value: number) => value.toString()
-
+/**
+ * Displays the formatted maximum value for a spread widget data item.
+ */
 export function MaxValue({ id, index = 0, ...props }: ValueProps) {
   const max = useWidgetStore(
     useShallow(

package/src/widgets/spread/components/min-value.tsx

@@ -2,9 +2,11 @@ import { type SpreadWidgetState, type ValueProps } from '../types'
 import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from '../../formula/components/item'
 import { useShallow } from 'zustand/shallow'
+import { defaultFormatter } from '../../utils/formatter'
 
-const defaultFormatter = (value: number) => value.toString()
-
+/**
+ * Displays the formatted minimum value for a spread widget data item.
+ */
 export function MinValue({ id, index = 0, ...props }: ValueProps) {
   const min = useWidgetStore(
     useShallow(

package/src/widgets/spread/components/separator.tsx

@@ -1,6 +1,9 @@
 import { Item } from '../../formula/components/item'
 import type { ItemProps } from '../../formula/types'
 
+/**
+ * Renders a dash separator between the min and max values in a spread widget.
+ */
 export function Separator(props: Omit<ItemProps, 'children'>) {
   return <Item {...props}>-</Item>
 }

package/src/widgets/spread/config.ts

@@ -2,6 +2,12 @@ import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
 import type { ConfigProps } from '../loader/types'
 import type { SpreadWidgetConfig, SpreadWidgetData } from './types'
 
+/**
+ * Creates download configuration for spread widgets, supporting PNG (screenshot) and CSV (min/max data) exports.
+ *
+ * @param props - Configuration with `refUI` reference for PNG export.
+ * @returns Array of download items for use with the Download action.
+ */
 export function spreadDownloadConfig({
   refUI,
 }: ConfigProps): DownloadItem<SpreadWidgetData>[] {
@@ -21,6 +27,11 @@ export function spreadDownloadConfig({
   ]
 }
 
+/**
+ * Returns the default configuration for spread (min/max value range) widgets.
+ *
+ * @returns Default spread widget config with empty series.
+ */
 export function spreadConfig(): SpreadWidgetConfig {
   return {
     series: [],

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

@@ -7,6 +7,9 @@ import { Prefix, Row, Suffix, Series } from '../formula'
 import { useWidgetRef } from '../../hooks'
 import { Box } from '@mui/material'
 
+/**
+ * Renders a spread widget displaying min-max value pairs with optional prefixes, suffixes, and series indicators.
+ */
 export function SpreadUI(props: SpreadUIProps) {
   const { ref } = useWidgetRef(props.id)
 

package/src/widgets/subheader/subheader.tsx

@@ -2,6 +2,17 @@ import { Box } from '@mui/material'
 import { styles } from './style'
 import type { WidgetSubHeaderProps } from './types'
 
+/**
+ * Flexible two-slot layout for displaying supplementary widget information such as totals, timestamps, or controls. Uses flexbox with space-between justification.
+ *
+ * @example
+ * ```tsx
+ * <WidgetSubHeader
+ *   slotLeft={<Typography variant="caption">Total: 1,234</Typography>}
+ *   slotRight={<Typography variant="caption">Updated: 2m ago</Typography>}
+ * />
+ * ```
+ */
 export function WidgetSubHeader({
   slotLeft,
   slotRight,

package/src/widgets/table/config.ts

@@ -17,8 +17,10 @@ export const DEFAULT_COLUMN_ID = null
 export const DEFAULT_DIRECTION: SortDirection = 'asc'
 
 /**
- * Default table download configuration
- * Supports PNG export (screenshot) and CSV export (data)
+ * Creates download configuration for table widgets, supporting PNG (screenshot) and CSV (data) exports. CSV output uses column keys as headers and filters out `id` fields.
+ *
+ * @param props - Configuration with `refUI` reference for PNG export.
+ * @returns Array of download items for use with the Download action.
  */
 export function tableDownloadConfig({
   refUI,
@@ -59,7 +61,10 @@ export function tableDownloadConfig({
 }
 
 /**
- * Default table widget configuration
+ * Returns the default configuration for table widgets with pagination and sorting, including column definitions and local data mode.
+ *
+ * @param columns - Array of column definitions for the table.
+ * @returns Default table widget config.
  */
 export function tableConfig(columns: TableColumn[] = []): TableWidgetConfig {
   return {

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

@@ -37,9 +37,17 @@ 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,

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

@@ -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,

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

@@ -27,9 +27,17 @@ 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,

package/src/widgets/timeseries/config.ts

@@ -13,35 +13,26 @@ import {
   buildLegendConfig,
   buildGridConfig,
   createTooltipFormatter,
+  createChartDownloadConfig,
   applyYAxisFormatter,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
+} 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,
   }
 }
 

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)
+        },
+      },
+    ]
+  }
+}