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

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

@@ -7,8 +7,11 @@ import { Series } from './components/series'
 import { useWidgetRef } from '../../hooks'
 import { Box } from '@mui/material'
 
+/**
+ * Renders a formula widget displaying one or more KPI values with optional prefixes, suffixes, and series indicators.
+ */
 export function FormulaUI(props: FormulaUIProps) {
-  const ref = useWidgetRef(props.id)
+  const { ref } = useWidgetRef(props.id)
 
   return (
     <Box ref={ref}>

package/src/widgets/histogram/config.ts

@@ -3,25 +3,56 @@ import {
   mergeEchartWidgetConfig,
   type EchartOptionsProps,
 } from '../echart'
-import type {
-  HistogramConfig,
-  HistogramWidgetConfig,
-  HistogramWidgetData,
-} from './types'
+import type { HistogramConfig, HistogramWidgetConfig } from './types'
 import {
-  flattenObjectArrayToCSV,
   buildLegendConfig,
   buildGridConfig,
   createTooltipPositioner,
   createTooltipFormatter,
   niceNum,
-} from '../_shared/chart-config'
+  buildHistogramSeriesLabelConfig,
+} from '../utils/chart-config'
 import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
 import type { ConfigProps } from '../loader/types'
 
+export interface HistogramDownloadConfigProps extends ConfigProps {
+  ticks: number[]
+  labelFormatter?: (value: string | number) => string | number
+}
+
+export function histogramDataToCSV(
+  data: number[][],
+  ticks: number[],
+  labelFormatter?: (value: string | number) => string | number,
+): string[][] {
+  if (!data?.length || data[0]?.length === 0) return []
+
+  const dataLength = data[0]?.length ?? 0
+  const labels = createAxisLabels(dataLength, ticks, labelFormatter)
+  const seriesCount = data.length
+  const isMulti = seriesCount > 1
+
+  const headers = isMulti
+    ? [
+        'Bin',
+        ...Array.from({ length: seriesCount }, (_, i) => `Series ${i + 1}`),
+      ]
+    : ['Bin', 'Value']
+
+  return [
+    headers,
+    ...labels.map((label, i) => [
+      label,
+      ...data.map((series) => String(series[i] ?? 0)),
+    ]),
+  ]
+}
+
 export function histogramDownloadConfig({
   refUI,
-}: ConfigProps): DownloadItem<HistogramWidgetData>[] {
+  ticks,
+  labelFormatter,
+}: HistogramDownloadConfigProps): DownloadItem<number[][]>[] {
   return [
     {
       ...downloadToPNG,
@@ -29,42 +60,87 @@ export function histogramDownloadConfig({
     },
     {
       ...downloadToCSV,
-      modifier: async (data) => {
-        const rows = flattenObjectArrayToCSV(data)
-        return downloadToCSV.modifier(rows)
-      },
+      modifier: async (data) =>
+        downloadToCSV.modifier(histogramDataToCSV(data, ticks, labelFormatter)),
     },
   ]
 }
+
+/**
+ * Creates formatted axis labels from tick boundaries.
+ *
+ * @param dataLength - Number of data points (determines number of labels).
+ * @param ticks - Bin boundaries. If `ticks.length === dataLength + 1`, all
+ *   bins are ranges. If `ticks.length === dataLength`, the last bin is
+ *   open-ended (`+`). A last tick of `Infinity` also produces `+`.
+ * @param labelFormatter - Optional formatter applied to each individual tick
+ *   value when building the bin range label.
+ */
+function createAxisLabels(
+  dataLength: number,
+  ticks: number[],
+  labelFormatter?: (value: string | number) => string | number,
+): string[] {
+  const fmt = (v: number) =>
+    labelFormatter ? String(labelFormatter(v)) : String(v)
+
+  return Array.from({ length: dataLength }, (_, i) => {
+    const low = ticks[i] ?? i
+    const high = ticks[i + 1]
+    return high !== undefined && isFinite(high)
+      ? `${fmt(low)}-${fmt(high)}`
+      : `${fmt(low)}+`
+  })
+}
+
+/**
+ * Generates ECharts configuration for distribution histogram widgets with
+ * adjacent bars (minimal gap) and axis formatting styled with the CARTO theme.
+ *
+ * Accepts raw `number[][]` data and `ticks` boundaries. The ticks and
+ * `labelFormatter` are used to create the x-axis category labels; the raw
+ * numeric data is embedded directly in each series.
+ *
+ * @param props - Histogram configuration including raw data, ticks, and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export function histogramConfig(props: HistogramConfig): HistogramWidgetConfig {
   return {
     type: 'histogram',
     option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
+    labelFormatter: props.labelFormatter,
   }
 }
+
 function getOption({
   data = [],
+  ticks,
   theme,
   formatter,
+  labelFormatter,
 }: HistogramConfig): EchartOptionsProps {
   const hasLegend = (data?.length ?? 0) > 1
+  const dataLength = data[0]?.length ?? 0
+  const axisLabels = createAxisLabels(dataLength, ticks, labelFormatter)
 
   let niceMin = 0
   let niceMax = 1
 
   return {
-    legend: buildLegendConfig(hasLegend),
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
     grid: buildGridConfig(hasLegend, theme),
     xAxis: {
       type: 'category',
+      data: axisLabels,
       axisLine: {
         show: false,
       },
       axisLabel: {
         fontSize: theme.typography.overlineDelicate.fontSize,
         fontFamily: theme.typography.overlineDelicate.fontFamily,
-        showMinLabel: true,
-        showMaxLabel: true,
+        showMinLabel: undefined,
+        showMaxLabel: undefined,
         hideOverlap: true,
         margin: 0,
         padding: [
@@ -126,30 +202,29 @@ function getOption({
     tooltip: {
       position: createTooltipPositioner(theme),
       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 _value = item.value as number
 
         const formattedValue =
           typeof _value === 'number' && formatter
             ? formatter(_value)
-            : (_value ?? '')
+            : String(_value ?? '')
 
         const marker = typeof item.marker === 'string' ? item.marker : ''
         const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
-        const name = item.name ?? ''
+        const name = item.name
 
         return { name, seriesName, marker, value: formattedValue }
       }),
     },
-    series: data.map((_: unknown, index: number) => ({
-      datasetIndex: index,
+    series: data.map((seriesData: number[]) => ({
       type: 'bar',
-      barGap: '1%', // No gap between bars in histogram
-      barCategoryGap: '1%', // No gap between categories in histogram
+      data: seriesData,
+      barGap: '1%',
+      barCategoryGap: '1%',
       emphasis: {
         focus: 'series',
       },
+      ...buildHistogramSeriesLabelConfig(formatter),
     })),
   } as EchartOptionsProps
 }

package/src/widgets/histogram/index.ts

@@ -4,5 +4,10 @@ export type {
   HistogramWidgetData,
   HistogramWidgetState,
 } from './types'
-export { histogramConfig, histogramDownloadConfig } from './config'
+export type { HistogramDownloadConfigProps } from './config'
+export {
+  histogramConfig,
+  histogramDataToCSV,
+  histogramDownloadConfig,
+} from './config'
 export { HistogramSkeleton } from './skeleton'

package/src/widgets/histogram/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/histogram/types.ts

@@ -1,11 +1,11 @@
-import type { EchartWidgetData, EchartWidgetState } from '../echart'
+import type { EchartWidgetState } from '../echart'
 import type {
   EchartWidgetOptionProps,
   EchartWidgetProps,
 } from '../echart/types'
 import type { ConfigProps } from '../loader'
 
-export type HistogramWidgetData = EchartWidgetData
+export type HistogramWidgetData = number[][]
 
 export type HistogramWidgetState = EchartWidgetState
 
@@ -14,4 +14,10 @@ export type HistogramWidgetConfig = EchartWidgetProps & {
 }
 
 export type HistogramConfig = ConfigProps &
-  EchartWidgetOptionProps<HistogramWidgetData>
+  Pick<
+    EchartWidgetOptionProps<unknown>,
+    'theme' | 'formatter' | 'labelFormatter'
+  > & {
+    data?: number[][]
+    ticks: number[]
+  }

package/src/widgets/loader/loader.tsx

@@ -1,22 +1,38 @@
-import { useEffect, useRef, useSyncExternalStore } from 'react'
+import { useEffect, useRef } from 'react'
 import type { WidgetLoaderProps } from './types'
-import { useWidgetStore } from '../stores/widget-store'
+import { useWidgetStore, widgetStoreActions } from '../stores/widget-store'
 import type { WrapperState } from '../wrapper'
 
+/**
+ * Foundation component for all widgets that manages state initialization, synchronization with the widget store, and data transformation pipeline execution.
+ *
+ * @remarks
+ * The WidgetLoader is stateless -- it manages data flow but does not render any UI. Always wrap it with WidgetWrapper for consistent widget appearance.
+ *
+ * @example
+ * ```tsx
+ * <WidgetLoader
+ *   id="sales-chart"
+ *   type="bar"
+ *   data={data}
+ *   isLoading={false}
+ *   isFetching={false}
+ *   config={barConfig({ data })}
+ * >
+ *   <WidgetWrapper id="sales-chart" title="Sales">
+ *     <Echart id="sales-chart" />
+ *   </WidgetWrapper>
+ * </WidgetLoader>
+ * ```
+ */
 export function WidgetLoader<T extends object = Record<string, unknown>>(
   props: WidgetLoaderProps<T>,
 ) {
-  const setWidget = useWidgetStore((state) => state.setWidget)
-  const executeToolPipeline = useWidgetStore(
-    (state) => state.executeToolPipeline,
-  )
-  const executeConfigPipeline = useWidgetStore(
-    (state) => state.executeConfigPipeline,
-  )
-
-  const registeredTools = useSyncExternalStore(
-    useWidgetStore.subscribe,
-    () => useWidgetStore.getState().widgets[props.id]?.registeredTools,
+  // Subscribe only to this widget's registeredTools via Zustand selector.
+  // The selector returns a stable reference when other widgets change,
+  // avoiding unnecessary re-evaluations of Effect 4.
+  const registeredTools = useWidgetStore(
+    (state) => state.widgets[props.id]?.registeredTools,
   )
 
   const dataRef = useRef(props.data)
@@ -28,56 +44,49 @@ export function WidgetLoader<T extends object = Record<string, unknown>>(
     configRef.current = props.config
   })
 
-  // Split into 3 effects for metadata and 1 for data pipeline:
-  // Each property that can be modified independently gets its own effect to avoid
-  // accidentally resetting other properties.
-  //
-  // - Effect 1: Type (can be modified by tools that change visualization type)
-  // - Effect 2: Loading/Error states (change during fetch lifecycle)
-  // - Effect 3: Config (can be modified by tools that change widget configuration)
-  // - Effect 4: Data pipeline execution (transforms data through registered tools)
-  // - Effect 5: Re-execute pipeline when tool state changes
-
-  // Effect 1: Type updates
+  // Effect 1: Metadata — type, loading, and error states in a single setWidget call.
+  // Merged to reduce store updates from 2 to 1 per widget during initialization.
   useEffect(() => {
-    setWidget<WrapperState>(props.id, {
+    widgetStoreActions.setWidget<WrapperState>(props.id, {
       type: props.type,
-    })
-  }, [props.id, props.type, setWidget])
-
-  // Effect 2: Loading and error states
-  useEffect(() => {
-    setWidget<WrapperState>(props.id, {
       isLoading: props.isLoading ?? false,
       isFetching: props.isFetching ?? false,
       error: props.error,
     })
-  }, [props.id, props.isLoading, props.isFetching, props.error, setWidget])
+  }, [props.id, props.type, props.isLoading, props.isFetching, props.error])
 
-  // Effect 3: Config updates — run through config pipeline
+  // Effect 2: Config updates — run through config pipeline
   useEffect(() => {
     if (props.config) {
-      void executeConfigPipeline(props.id, props.config)
+      void widgetStoreActions.executeConfigPipeline(props.id, props.config)
     }
-  }, [props.id, props.config, executeConfigPipeline])
+  }, [props.id, props.config])
 
-  // Effect 4: Execute tool pipeline when props.data changes
+  // Effect 3: Execute tool pipeline when props.data changes
   useEffect(() => {
-    void executeToolPipeline(props.id, props.data)
-  }, [props.id, props.data, executeToolPipeline])
+    void widgetStoreActions.executeToolPipeline(props.id, props.data)
+  }, [props.id, props.data])
 
-  // Effect 5: Re-execute pipelines when registered tools change
+  // Effect 4: Re-execute pipelines when registered tools change.
+  // Uses requestAnimationFrame to coalesce rapid successive registeredTools
+  // changes (e.g., 6 action components each calling registerTool on mount)
+  // into a single pipeline execution instead of 6 pairs.
   useEffect(() => {
     if (!isMountedRef.current) {
       isMountedRef.current = true
       return
     }
 
-    void executeToolPipeline(props.id, dataRef.current)
-    if (configRef.current) {
-      void executeConfigPipeline(props.id, configRef.current)
-    }
-  }, [registeredTools, props.id, executeToolPipeline, executeConfigPipeline])
+    const rafId = requestAnimationFrame(() => {
+      const { executeToolPipeline, executeConfigPipeline } = widgetStoreActions
+      void executeToolPipeline(props.id, dataRef.current)
+      if (configRef.current) {
+        void executeConfigPipeline(props.id, configRef.current)
+      }
+    })
+
+    return () => cancelAnimationFrame(rafId)
+  }, [registeredTools, props.id])
 
   return props.children
 }

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

@@ -1,15 +1,15 @@
 import type { MarkdownUIProps } from './types'
-import { useWidgetStore } from '../stores/widget-store'
 import type { MarkdownWidgetData } from './types'
 import { MarkdownUI } from '.'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 
+/**
+ * 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(
-      (state) =>
-        (state.getWidget(id)?.data as MarkdownWidgetData | undefined)?.content,
-    ),
+  const content = useWidgetSelector(
+    id,
+    (w) => (w?.data as MarkdownWidgetData | undefined)?.content,
   )
 
   if (!content) {