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

package/src/widgets/stores/widget-store.ts

@@ -1,5 +1,10 @@
 import { create } from 'zustand'
-import type { WidgetState, WidgetStore, ToolRegistration } from './types'
+import type {
+  WidgetState,
+  WidgetStore,
+  ToolRegistration,
+  WidgetStoreActions,
+} from './types'
 
 // Track active pipeline executions for cancellation
 const activePipelines = new Map<string, number>()
@@ -8,38 +13,39 @@ const activeConfigPipelines = new Map<string, number>()
 /**
  * Zustand store for managing widget state across the application.
  *
- * This store provides centralized state management for all widget UI components
+ * Provides centralized state management for all widget UI components, including
+ * data/config transformation pipelines via registered tools.
  *
- * @example
- * ```tsx
- * // Import the store
- * import { useWidgetStore } from '@carto/ps-react-ui/widgets'
- *
- * // Use in a component
- * function MyWidget() {
- *   const setWidget = useWidgetStore((state) => state.setWidget)
- *   const widget = useWidgetStore((state) => state.widgets['my-widget'])
+ * **Performance optimizations:**
+ * - `registerTool` skips the store update when structural properties (order, enabled,
+ *   type, disables) haven't changed — only `fn` is updated via direct mutation,
+ *   avoiding a new `registeredTools` array reference and WidgetLoader pipeline cascades.
+ * - `setToolEnabled` skips the store update when the enabled state is already the
+ *   requested value.
+ * - `executeToolPipeline` / `executeConfigPipeline` skip the final `set()` when
+ *   the transformed data/config is referentially identical to what's already in the store.
+ * - Both pipelines support cancellation — newer executions for the same widget
+ *   automatically cancel in-progress ones.
  *
- *   useEffect(() => {
- *     setWidget({
- *       id: 'my-widget',
- *       type: 'formula',
- *       title: 'Total Sales',
- *       isLoading: false,
- *       visible: true,
- *       data: { value: 1000, prefix: '$' }
- *     })
- *   }, [setWidget])
+ * @example Reading widget state (prefer useWidgetSelector for performance)
+ * ```tsx
+ * import { useWidgetSelector } from '@carto/ps-react-ui/widgets'
  *
- *   return <div>{widget?.data?.value}</div>
+ * function MyWidget({ id }: { id: string }) {
+ *   const { title, data } = useWidgetSelector(id, (w) => ({
+ *     title: w?.title,
+ *     data: w?.data,
+ *   }))
+ *   return <div>{title}: {JSON.stringify(data)}</div>
  * }
  * ```
  *
- * @example
+ * @example Writing widget state
  * ```tsx
- * // Get widgets by type
- * const getWidgetsByType = useWidgetStore((state) => state.getWidgetsByType)
- * const formulaWidgets = getWidgetsByType('formula')
+ * import { widgetStoreActions } from '@carto/ps-react-ui/widgets'
+ *
+ * const { setWidget } = widgetStoreActions
+ * setWidget('my-widget', { type: 'formula', isLoading: false, data: { value: 1000 } })
  * ```
  */
 export const useWidgetStore = create<WidgetStore>()((set, get) => ({
@@ -47,21 +53,23 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
   widgets: {},
 
   // Actions
-  setWidget: (id, widget) =>
+
+  /** Merges partial state into the widget entry. Creates the widget if it doesn't exist. */
+  setWidget: (id, widget) => {
     set((state) => {
-      const current =
-        state.widgets[id] ?? ({} as WidgetStore['widgets'][string])
+      const prev = state.widgets[id] ?? ({} as WidgetStore['widgets'][string])
       return {
         widgets: {
           ...state.widgets,
           [id]: {
-            ...current,
+            ...prev,
             ...widget,
             id,
           },
         },
       }
-    }),
+    })
+  },
 
   removeWidget: (id) =>
     set((state) => {
@@ -81,10 +89,36 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
     return get().widgets[id] as T | undefined
   },
 
-  registerTool: (widgetId: string, tool: ToolRegistration) =>
+  /**
+   * Registers a transformation tool for a widget's data or config pipeline.
+   *
+   * **No-op optimization:** When a tool with the same `id` already exists and its
+   * structural properties (`order`, `enabled`, `type`, `disables`) are unchanged,
+   * only `fn` is updated via direct mutation — no store update is triggered. This
+   * allows action components to include all reactive dependencies in their
+   * `useEffect` arrays without causing WidgetLoader pipeline cascades.
+   */
+  registerTool: (widgetId: string, tool: ToolRegistration) => {
+    const current = get().widgets[widgetId]
+    const existingTool = current?.registeredTools?.find(
+      (t: ToolRegistration) => t.id === tool.id,
+    )
+
+    // No-op: structural properties unchanged — update fn via direct mutation.
+    // Safe because fn is only consumed imperatively during pipeline execution.
+    if (
+      existingTool?.order === tool.order &&
+      existingTool.enabled === tool.enabled &&
+      existingTool.type === tool.type &&
+      existingTool.disables === tool.disables
+    ) {
+      existingTool.fn = tool.fn
+      return
+    }
+
     set((state) => {
-      const current = state.widgets[widgetId] ?? ({} as WidgetState)
-      const registeredTools = current.registeredTools ?? []
+      const widget = state.widgets[widgetId] ?? ({} as WidgetState)
+      const registeredTools = widget.registeredTools ?? []
 
       // Remove existing tool with same id if present
       const filteredTools = registeredTools.filter(
@@ -95,13 +129,14 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
         widgets: {
           ...state.widgets,
           [widgetId]: {
-            ...current,
+            ...widget,
             id: widgetId,
             registeredTools: [...filteredTools, tool],
           },
         },
       }
-    }),
+    })
+  },
 
   unregisterTool: (widgetId: string, toolId: string) =>
     set((state) => {
@@ -124,42 +159,47 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
       }
     }),
 
-  updateToolConfig: (
-    widgetId: string,
-    toolId: string,
-    config: Record<string, unknown>,
-  ) =>
+  /**
+   * Triggers pipeline re-execution by creating a new `registeredTools` reference.
+   * This is a lightweight operation that only bumps the array reference without
+   * modifying any tool.
+   */
+  triggerToolPipeline: (widgetId: string) =>
     set((state) => {
-      const current = state.widgets[widgetId]
-      if (!current) return state
-
-      const registeredTools = current.registeredTools ?? []
-      const updatedTools = registeredTools.map((tool: ToolRegistration) =>
-        tool.id === toolId
-          ? {
-              ...tool,
-              config: { ...tool.config, ...config },
-            }
-          : tool,
-      )
+      const widget = state.widgets[widgetId]
+      if (!widget) return state
 
       return {
         widgets: {
           ...state.widgets,
           [widgetId]: {
-            ...current,
-            registeredTools: updatedTools,
+            ...widget,
+            registeredTools: [...(widget.registeredTools ?? [])],
           },
         },
       }
     }),
 
-  setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) =>
+  /**
+   * Updates a tool's enabled state.
+   *
+   * **No-op optimization:** Skips the store update if the tool already has the
+   * requested enabled value.
+   */
+  setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) => {
+    const current = get().widgets[widgetId]
+    if (current) {
+      const tool = current.registeredTools?.find(
+        (t: ToolRegistration) => t.id === toolId,
+      )
+      if (tool?.enabled === enabled) return
+    }
+
     set((state) => {
-      const current = state.widgets[widgetId]
-      if (!current) return state
+      const widget = state.widgets[widgetId]
+      if (!widget) return state
 
-      const registeredTools = current.registeredTools ?? []
+      const registeredTools = widget.registeredTools ?? []
       const updatedTools = registeredTools.map((tool: ToolRegistration) =>
         tool.id === toolId ? { ...tool, enabled } : tool,
       )
@@ -168,13 +208,26 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
         widgets: {
           ...state.widgets,
           [widgetId]: {
-            ...current,
+            ...widget,
             registeredTools: updatedTools,
           },
         },
       }
-    }),
+    })
+  },
 
+  /**
+   * Executes the data transformation pipeline for a widget.
+   *
+   * Filters to enabled data-type tools (respecting `disables`), sorts by `order`,
+   * and chains their `fn` calls. Supports async tools.
+   *
+   * **Cancellation:** Newer executions for the same widget automatically cancel
+   * in-progress ones via a version counter.
+   *
+   * **No-op optimization:** Skips the final `set()` if the transformed data is
+   * referentially identical (`Object.is`) to what's already in the store.
+   */
   executeToolPipeline: async (widgetId: string, sourceData: unknown) => {
     const widget = get().widgets[widgetId]
     if (!widget) return
@@ -213,7 +266,7 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
 
       try {
         // Call tool function (may return Promise or direct value)
-        transformedData = await tool.fn(transformedData, tool.config)
+        transformedData = await tool.fn(transformedData)
       } catch (error) {
         // eslint-disable-next-line no-console
         console.error(`Tool ${tool.id} failed for widget ${widgetId}:`, error)
@@ -221,6 +274,19 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
       }
     }
 
+    // Skip store update if neither data nor sourceData changed
+    const widgetAfter = get().widgets[widgetId]
+    if (
+      widgetAfter &&
+      Object.is(widgetAfter.data, transformedData) &&
+      Object.is(widgetAfter.sourceData, sourceData)
+    ) {
+      if (activePipelines.get(widgetId) === currentExecution) {
+        activePipelines.delete(widgetId)
+      }
+      return
+    }
+
     // Single store update with final transformed data
     set((state) => {
       const currentWidget = state.widgets[widgetId]
@@ -231,6 +297,7 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
           ...state.widgets,
           [widgetId]: {
             ...currentWidget,
+            sourceData,
             data: transformedData,
           },
         },
@@ -243,6 +310,18 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
     }
   },
 
+  /**
+   * Executes the config transformation pipeline for a widget.
+   *
+   * Filters to enabled config-type tools (respecting `disables`), sorts by `order`,
+   * and chains their `fn` calls. The transformed config is spread into the widget state.
+   *
+   * **Cancellation:** Newer executions for the same widget automatically cancel
+   * in-progress ones via a version counter.
+   *
+   * **No-op optimization:** Skips the final `set()` when the config object is unchanged
+   * and all its properties already match what's in the store.
+   */
   executeConfigPipeline: async (widgetId: string, baseConfig: object) => {
     const widget = get().widgets[widgetId]
     if (!widget) return
@@ -277,7 +356,7 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
       }
 
       try {
-        transformedConfig = await tool.fn(transformedConfig, tool.config)
+        transformedConfig = await tool.fn(transformedConfig)
       } catch (error) {
         // eslint-disable-next-line no-console
         console.error(
@@ -287,7 +366,50 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
       }
     }
 
-    // Set the transformed config into the widget
+    // Build a patch that only includes properties the pipeline should set.
+    // A property is applied when:
+    //   1. A config tool explicitly changed it (transformedConfig[k] !== baseConfig[k])
+    //   2. First pipeline run for this widget (no _lastConfig yet)
+    //   3. The widget value still matches what the pipeline last set — meaning the
+    //      user hasn't modified it via setWidget, so it's safe to overwrite.
+    // A property is SKIPPED when the widget value differs from _lastConfig,
+    // meaning the user (or a hook) changed it since the last pipeline run.
+    const base = baseConfig as Record<string, unknown>
+    const result = transformedConfig as Record<string, unknown>
+    const widgetNow = get().widgets[widgetId] as unknown as Record<
+      string,
+      unknown
+    >
+    const lastConfig = widgetNow?._lastConfig as
+      | Record<string, unknown>
+      | undefined
+
+    const patch: Record<string, unknown> = {}
+    for (const key of Object.keys(result)) {
+      const toolChanged = !Object.is(result[key], base[key])
+      const isFirstRun = !lastConfig || !(key in lastConfig)
+      const userUnmodified =
+        !isFirstRun && Object.is(widgetNow[key], lastConfig[key])
+
+      if (toolChanged || isFirstRun || userUnmodified) {
+        patch[key] = result[key]
+      }
+    }
+
+    // Skip store update if every patch value already matches the widget
+    const hasChanges = Object.keys(patch).some(
+      (k) => !Object.is(widgetNow?.[k], patch[k]),
+    )
+    const configRefChanged = !Object.is(transformedConfig, lastConfig)
+
+    if (!hasChanges && !configRefChanged) {
+      if (activeConfigPipelines.get(widgetId) === currentExecution) {
+        activeConfigPipelines.delete(widgetId)
+      }
+      return
+    }
+
+    // Apply the patch and store the pipeline output for next run's comparison
     set((state) => {
       const currentWidget = state.widgets[widgetId]
       if (!currentWidget) return state
@@ -297,7 +419,8 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
           ...state.widgets,
           [widgetId]: {
             ...currentWidget,
-            ...(transformedConfig as Record<string, unknown>),
+            ...patch,
+            _lastConfig: transformedConfig,
           },
         },
       }
@@ -308,3 +431,55 @@ export const useWidgetStore = create<WidgetStore>()((set, get) => ({
     }
   },
 }))
+
+/**
+ * Stable references to store actions, accessible without creating a subscription.
+ *
+ * Use this instead of `useWidgetStore((state) => state.setWidget)` to avoid
+ * unnecessary subscriber evaluations. Actions are stable functions that never
+ * change, so subscribing to them wastes cycles on every store update.
+ *
+ * @example
+ * ```tsx
+ * import { widgetStoreActions } from '@carto/ps-react-ui/widgets'
+ *
+ * const { setWidget, registerTool } = widgetStoreActions
+ *
+ * useEffect(() => {
+ *   registerTool(id, { id: 'my-tool', order: 10, enabled: true, fn: (d) => d })
+ *   return () => widgetStoreActions.unregisterTool(id, 'my-tool')
+ * }, [id])
+ * ```
+ */
+export const widgetStoreActions: WidgetStoreActions = {
+  get setWidget() {
+    return useWidgetStore.getState().setWidget
+  },
+  get removeWidget() {
+    return useWidgetStore.getState().removeWidget
+  },
+  get clearWidgets() {
+    return useWidgetStore.getState().clearWidgets
+  },
+  get getWidget() {
+    return useWidgetStore.getState().getWidget
+  },
+  get registerTool() {
+    return useWidgetStore.getState().registerTool
+  },
+  get unregisterTool() {
+    return useWidgetStore.getState().unregisterTool
+  },
+  get setToolEnabled() {
+    return useWidgetStore.getState().setToolEnabled
+  },
+  get triggerToolPipeline() {
+    return useWidgetStore.getState().triggerToolPipeline
+  },
+  get executeToolPipeline() {
+    return useWidgetStore.getState().executeToolPipeline
+  },
+  get executeConfigPipeline() {
+    return useWidgetStore.getState().executeConfigPipeline
+  },
+} as WidgetStoreActions

package/src/widgets/subheader/subheader.tsx

@@ -2,15 +2,34 @@ 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,
   sx,
 }: WidgetSubHeaderProps) {
   return (
-    <Box sx={{ ...styles.root, ...sx }}>
-      {slotLeft && <Box sx={styles.slotLeft}>{slotLeft}</Box>}
-      <Box sx={styles.slotRight}>{slotRight}</Box>
+    <Box sx={{ ...styles.root, ...sx }} className='widget-subheader'>
+      {slotLeft && (
+        <Box sx={styles.slotLeft} className='widget-subheader-slot-left'>
+          {slotLeft}
+        </Box>
+      )}
+      {slotRight && (
+        <Box sx={styles.slotRight} className='widget-subheader-slot-right'>
+          {slotRight}
+        </Box>
+      )}
     </Box>
   )
 }

package/src/widgets/table/config.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import { createRef } from 'react'
+import { tableConfig, tableDownloadConfig } from './config'
+
+describe('tableConfig', () => {
+  it('returns config with the provided columns', () => {
+    const columns = [
+      { id: 'name', label: 'Name' },
+      { id: 'age', label: 'Age' },
+    ] satisfies Parameters<typeof tableConfig>[0]
+    const cfg = tableConfig(columns)
+    expect(cfg.columns).toBe(columns)
+    expect(cfg.mode).toBe('local')
+    expect(cfg.selectable).toBe(false)
+  })
+
+  it('defaults to empty columns when no argument passed', () => {
+    const cfg = tableConfig()
+    expect(cfg.columns).toEqual([])
+  })
+})
+
+describe('tableDownloadConfig', () => {
+  const refUI = createRef<HTMLDivElement>()
+
+  it('returns a two-item download config (PNG + CSV)', () => {
+    const cfg = tableDownloadConfig({ refUI })
+    expect(cfg).toHaveLength(2)
+  })
+
+  it('CSV modifier handles populated row data with mixed value types', async () => {
+    const cfg = tableDownloadConfig({ refUI })
+    const csvItem = cfg[1]!
+    const rows = [
+      { id: '1', name: 'A', value: 10, meta: { tag: 'x' } },
+      { id: '2', name: 'B', value: null, meta: { tag: 'y' } },
+      { id: '3', name: 'C', value: undefined, meta: undefined },
+    ] as unknown as Parameters<NonNullable<typeof csvItem.modifier>>[0]
+    await expect(csvItem.modifier(rows)).resolves.not.toThrow()
+  })
+
+  it('CSV modifier short-circuits when data is empty', async () => {
+    const cfg = tableDownloadConfig({ refUI })
+    const csvItem = cfg[1]!
+    await expect(csvItem.modifier([])).resolves.not.toThrow()
+    await expect(
+      csvItem.modifier(
+        undefined as unknown as Parameters<
+          NonNullable<typeof csvItem.modifier>
+        >[0],
+      ),
+    ).resolves.not.toThrow()
+  })
+
+  it('CSV modifier handles first-row being undefined (edge case)', async () => {
+    const cfg = tableDownloadConfig({ refUI })
+    const csvItem = cfg[1]!
+    // Pass an array containing a falsy first item — should not throw.
+    await expect(
+      csvItem.modifier([undefined] as unknown as Parameters<
+        NonNullable<typeof csvItem.modifier>
+      >[0]),
+    ).resolves.not.toThrow()
+  })
+})

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,13 +61,15 @@ 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 {
     columns,
     selectable: false,
-    selected: [],
     mode: DEFAULT_MODE,
   }
 }