@carto/ps-react-ui 4.4.1 → 4.4.3

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,28 @@ 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,
+    labelFormatter: props.labelFormatter,
   }
 }
 
@@ -42,26 +37,94 @@ function getOption({
   data = [],
   theme,
   formatter,
+  labelFormatter,
 }: PieConfig): EchartOptionsProps {
   const multiSeries = (data?.length ?? 0) > 1
 
   if (multiSeries) {
+    let niceMin = 0
+    let niceMax = 1
+
     return {
+      legend: buildLegendConfig({ hasLegend: true, labelFormatter }),
+      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],
+          ...(labelFormatter && {
+            formatter: (value: string | number) =>
+              String(labelFormatter(value)),
+          }),
+        },
       },
-      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 = labelFormatter
+            ? String(labelFormatter(item.name ?? ''))
+            : (item.name ?? '')
+
+          return { name, seriesName, marker, value: formattedValue }
+        }),
       },
       series: data.map((_: unknown, index: number) => ({
         datasetIndex: index,
@@ -77,7 +140,7 @@ function getOption({
   const hasLegend = true
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
     grid: {
       ...buildGridConfig(hasLegend, theme),
       left: 0,
@@ -109,7 +172,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,
@@ -148,7 +213,9 @@ function getOption({
               ? formatter(value)
               : (value ?? '')
 
-          const nameFormatted = name
+          const nameFormatted = labelFormatter
+            ? String(labelFormatter(name ?? ''))
+            : (name ?? '')
 
           return `{c|${formattedValue}}\n\n{b|${nameFormatted}}`
         },

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,28 @@ import {
   scatterplotDataToCSV,
   buildLegendConfig,
   createTooltipFormatter,
+  createChartDownloadConfig,
   applyYAxisFormatter,
-} from '../_shared/chart-config'
-import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
-import type { ConfigProps } from '../loader/types'
+  applyXAxisFormatter,
+} 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,
+    labelFormatter: props.labelFormatter,
   }
 }
 
@@ -48,6 +41,7 @@ function getOption({
   data = [],
   theme,
   formatter,
+  labelFormatter,
 }: ScatterplotConfig): EchartOptionsProps {
   const hasLegend = data.length > 1
 
@@ -103,12 +97,12 @@ function getOption({
   }
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
     grid: {
       ...(!hasLegend && { bottom: parseInt(theme.spacing(1)) }),
       ...(hasLegend && { bottom: parseInt(theme.spacing(10)) }),
     },
-    xAxis,
+    xAxis: applyXAxisFormatter(xAxis, labelFormatter),
     yAxis: applyYAxisFormatter(yAxis, formatter),
     tooltip: {
       trigger: 'item',
@@ -123,7 +117,9 @@ function getOption({
             ? formatter(_value)
             : (_value ?? '')
         const marker = typeof item.marker === 'string' ? item.marker : ''
-        const name = item.seriesName ?? ''
+        const name = labelFormatter
+          ? String(labelFormatter(item.seriesName ?? ''))
+          : (item.seriesName ?? '')
 
         return { name, seriesName: '', marker, value: formattedValue }
       }),

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/stores/types.ts

@@ -31,6 +31,8 @@ export interface WidgetsStoreProps {
   registeredTools?: ToolRegistration[]
   /** Formatter function for widget values */
   formatter?: (value: number) => string
+  /** Formatter function for widget label/category values */
+  labelFormatter?: (value: string | number) => string | number
   /** Locale for number formatting (e.g., 'en-US', 'es-ES', 'fr-FR') */
   locale?: string
 }

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,