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

package/src/widgets/utils/chart-config/option-builders.test.ts

@@ -0,0 +1,332 @@
+import { describe, it, expect } from 'vitest'
+import type { CallbackDataParams } from 'echarts/types/dist/shared'
+import type { Theme } from '@mui/material'
+import {
+  niceNum,
+  buildSeriesLabelConfig,
+  buildHistogramSeriesLabelConfig,
+  buildLegendConfig,
+  buildGridConfig,
+  createTooltipPositioner,
+  createAxisLabelFormatter,
+  applyXAxisFormatter,
+  applyYAxisFormatter,
+  createTooltipFormatter,
+} from './option-builders'
+
+const fakeTheme = {
+  spacing: (n: number) => String(n * 8),
+} as unknown as Theme
+
+describe('niceNum', () => {
+  it('should return 0 for 0', () => {
+    expect(niceNum(0)).toBe(0)
+  })
+
+  it('should return the same negative value for negative numbers', () => {
+    expect(niceNum(-5)).toBe(-5)
+  })
+
+  it('should round 547 to 600', () => {
+    expect(niceNum(547)).toBe(600)
+  })
+
+  it('should keep 200 as 200', () => {
+    expect(niceNum(200)).toBe(200)
+  })
+
+  it('should round 1200 to 2000', () => {
+    expect(niceNum(1200)).toBe(2000)
+  })
+
+  it('should round 18 to 20', () => {
+    expect(niceNum(18)).toBe(20)
+  })
+
+  it('should keep 5 as 5', () => {
+    expect(niceNum(5)).toBe(5)
+  })
+
+  it('should round 350 to 400', () => {
+    expect(niceNum(350)).toBe(400)
+  })
+
+  it('should keep 1 as 1', () => {
+    expect(niceNum(1)).toBe(1)
+  })
+})
+
+describe('buildSeriesLabelConfig', () => {
+  it('should return empty object when no formatter provided', () => {
+    expect(buildSeriesLabelConfig()).toEqual({})
+    expect(buildSeriesLabelConfig(undefined)).toEqual({})
+  })
+
+  it('should return label config with formatter when formatter provided', () => {
+    const formatter = (v: number) => `$${v}`
+    const result = buildSeriesLabelConfig(formatter)
+    expect(result).toHaveProperty('label')
+    expect((result as { label: { formatter: unknown } }).label).toHaveProperty(
+      'formatter',
+    )
+  })
+
+  it('should format value from dataset params using y encode key', () => {
+    const formatter = (v: number) => `$${v}`
+    const result = buildSeriesLabelConfig(formatter, 'y')
+    const label = (
+      result as {
+        label: { formatter: (p: Partial<CallbackDataParams>) => string }
+      }
+    ).label
+    const params = {
+      encode: { y: [1] },
+      dimensionNames: ['category', 'amount'],
+      value: { category: 'A', amount: 42 },
+    }
+    expect(label.formatter(params as unknown as CallbackDataParams)).toBe('$42')
+  })
+
+  it('should format value from dataset params using x encode key', () => {
+    const formatter = (v: number) => `${v}%`
+    const result = buildSeriesLabelConfig(formatter, 'x')
+    const label = (
+      result as {
+        label: { formatter: (p: Partial<CallbackDataParams>) => string }
+      }
+    ).label
+    const params = {
+      encode: { x: [1] },
+      dimensionNames: ['name', 'value'],
+      value: { name: 'Foo', value: 75 },
+    }
+    expect(label.formatter(params as unknown as CallbackDataParams)).toBe('75%')
+  })
+
+  it('should return empty string when encode index is undefined', () => {
+    const formatter = (v: number) => `$${v}`
+    const result = buildSeriesLabelConfig(formatter, 'y')
+    const label = (
+      result as {
+        label: { formatter: (p: Partial<CallbackDataParams>) => string }
+      }
+    ).label
+    const params = {
+      encode: {},
+      dimensionNames: ['category', 'amount'],
+      value: { category: 'A', amount: 42 },
+    }
+    expect(label.formatter(params as unknown as CallbackDataParams)).toBe('')
+  })
+})
+
+describe('buildHistogramSeriesLabelConfig', () => {
+  it('should return empty object when no formatter provided', () => {
+    expect(buildHistogramSeriesLabelConfig()).toEqual({})
+    expect(buildHistogramSeriesLabelConfig(undefined)).toEqual({})
+  })
+
+  it('should format raw numeric value', () => {
+    const formatter = (v: number) => `${v} units`
+    const result = buildHistogramSeriesLabelConfig(formatter)
+    const label = (
+      result as {
+        label: { formatter: (p: Partial<CallbackDataParams>) => string }
+      }
+    ).label
+    const params = { value: 100 }
+    expect(label.formatter(params as unknown as CallbackDataParams)).toBe(
+      '100 units',
+    )
+  })
+
+  it('should stringify non-numeric values', () => {
+    const formatter = (v: number) => `${v} units`
+    const result = buildHistogramSeriesLabelConfig(formatter)
+    const label = (
+      result as {
+        label: { formatter: (p: Partial<CallbackDataParams>) => string }
+      }
+    ).label
+    const params = { value: 'text' }
+    expect(label.formatter(params as unknown as CallbackDataParams)).toBe(
+      'text',
+    )
+  })
+})
+
+describe('buildLegendConfig', () => {
+  it('returns config with show=true when hasLegend=true', () => {
+    const cfg = buildLegendConfig({ hasLegend: true })
+    expect(cfg.show).toBe(true)
+    expect(cfg.icon).toBe('circle')
+  })
+
+  it('returns config with show=false when hasLegend=false', () => {
+    const cfg = buildLegendConfig({ hasLegend: false })
+    expect(cfg.show).toBe(false)
+  })
+
+  it('does not set formatter when no labelFormatter provided', () => {
+    const cfg = buildLegendConfig({ hasLegend: true })
+    expect(cfg.formatter).toBeUndefined()
+  })
+
+  it('sets a wrapper formatter when labelFormatter is provided', () => {
+    const cfg = buildLegendConfig({
+      hasLegend: true,
+      labelFormatter: (v) => `[${v}]`,
+    })
+    expect(typeof cfg.formatter).toBe('function')
+    const fmt = cfg.formatter as (name: string) => string
+    expect(fmt('hello')).toBe('[hello]')
+  })
+})
+
+describe('buildGridConfig', () => {
+  it('uses smaller bottom spacing when no legend', () => {
+    const cfg = buildGridConfig(false, fakeTheme)
+    expect(cfg.bottom).toBe(24) // 3 * 8
+  })
+
+  it('uses larger bottom spacing when legend present', () => {
+    const cfg = buildGridConfig(true, fakeTheme)
+    expect(cfg.bottom).toBe(56) // 7 * 8
+  })
+})
+
+describe('createTooltipPositioner', () => {
+  it('returns a positioner that places tooltip on the left when there is room', () => {
+    const positioner = createTooltipPositioner(fakeTheme)
+    const position = positioner([100, 50], null, null, null, {
+      contentSize: [50, 30],
+      viewSize: [400, 200],
+    })
+    expect(position.left).toBe(100)
+    expect(position.right).toBeUndefined()
+    expect(position.top).toBeDefined()
+  })
+
+  it('returns a positioner that places tooltip on the right when there is no room', () => {
+    const positioner = createTooltipPositioner(fakeTheme)
+    const position = positioner([380, 50], null, null, null, {
+      contentSize: [100, 30],
+      viewSize: [400, 200],
+    })
+    expect(position.right).toBe(20) // 400 - 380
+    expect(position.left).toBeUndefined()
+  })
+})
+
+describe('createAxisLabelFormatter', () => {
+  it('returns undefined when no formatter passed', () => {
+    expect(createAxisLabelFormatter(undefined)).toBeUndefined()
+  })
+
+  it('returns a wrapper function that calls the formatter', () => {
+    const fn = createAxisLabelFormatter((v) => `$${v}`)
+    expect(fn?.(5)).toBe('$5')
+  })
+})
+
+describe('applyXAxisFormatter', () => {
+  it('attaches a stringifying formatter when both xAxis is object and formatter provided', () => {
+    const result = applyXAxisFormatter({ type: 'value' }, (v) => Number(v) + 1)
+    const r = result as { axisLabel: { formatter: (v: unknown) => string } }
+    expect(r.axisLabel.formatter(2)).toBe('3')
+  })
+
+  it('returns undefined formatter when no formatter provided', () => {
+    const result = applyXAxisFormatter({ type: 'value' }, undefined)
+    const r = result as { axisLabel: { formatter: unknown } }
+    expect(r.axisLabel.formatter).toBeUndefined()
+  })
+
+  it('preserves existing axisLabel object keys', () => {
+    const result = applyXAxisFormatter(
+      { type: 'value', axisLabel: { color: 'red' } },
+      undefined,
+    )
+    const r = result as { axisLabel: { color: string; formatter: unknown } }
+    expect(r.axisLabel.color).toBe('red')
+  })
+
+  it('handles xAxis being an array (skips object-only path)', () => {
+    const result = applyXAxisFormatter([{ type: 'value' }], (v) => v)
+    // formatter should not be attached when xAxis is an array
+    const r = result as { axisLabel: { formatter: unknown } }
+    expect(r.axisLabel.formatter).toBeUndefined()
+  })
+})
+
+describe('applyYAxisFormatter', () => {
+  it('applies formatter when yAxis is an object with type=value', () => {
+    const result = applyYAxisFormatter({ type: 'value' }, (v) => `$${v}`)
+    const r = result as { axisLabel: { formatter: (v: number) => string } }
+    expect(r.axisLabel.formatter(5)).toBe('$5')
+  })
+
+  it('does not apply formatter when yAxis is not type=value', () => {
+    const result = applyYAxisFormatter({ type: 'category' }, (v) => `$${v}`)
+    const r = result as { axisLabel: { formatter: unknown } }
+    expect(r.axisLabel.formatter).toBeUndefined()
+  })
+
+  it('handles yAxis being an array (skips object-only path)', () => {
+    const result = applyYAxisFormatter([{ type: 'value' }], (v) => `$${v}`)
+    const r = result as { axisLabel: { formatter: unknown } }
+    expect(r.axisLabel.formatter).toBeUndefined()
+  })
+
+  it('handles missing axisLabel gracefully', () => {
+    const result = applyYAxisFormatter({ type: 'value' }, undefined)
+    const r = result as { axisLabel: object }
+    expect(r.axisLabel).toBeDefined()
+  })
+})
+
+describe('createTooltipFormatter', () => {
+  it('returns html for a single-item (object) trigger', () => {
+    const fmt = createTooltipFormatter((item) => ({
+      name: 'A',
+      seriesName: 'series',
+      marker: '●',
+      value: (item.value as number) ?? 0,
+    }))
+    const params = { value: 42 } as unknown as CallbackDataParams
+    const html = fmt(params)
+    expect(html).toContain('series')
+    expect(html).toContain('42')
+  })
+
+  it('handles multi-item (array) trigger', () => {
+    const fmt = createTooltipFormatter((item) => ({
+      name: String(item.name ?? ''),
+      seriesName: String(item.seriesName ?? ''),
+      marker: '●',
+      value: (item.value as number) ?? 0,
+    }))
+    const params = [
+      { name: 'X', seriesName: 's1', value: 1 },
+      { name: 'X', seriesName: 's2', value: 2 },
+    ] as unknown as CallbackDataParams[]
+    const html = fmt(params)
+    expect(html).toContain('s1')
+    expect(html).toContain('s2')
+  })
+
+  it('omits the header div when name is empty and there is only one item', () => {
+    const fmt = createTooltipFormatter(() => ({
+      name: '',
+      seriesName: '',
+      marker: '●',
+      value: 1,
+    }))
+    const params = { value: 1 } as unknown as CallbackDataParams
+    const html = fmt(params)
+    // no name → no top label div should be present
+    expect(html).not.toContain(
+      'color:#FFFFFF;font-weight:400;line-height:1; margin-bottom: 10px',
+    )
+  })
+})

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

@@ -3,7 +3,7 @@ import type { LegendComponentOption } from 'echarts'
 import type {
   CallbackDataParams,
   TopLevelFormatterParams,
-} from 'node_modules/echarts/types/dist/shared'
+} from 'echarts/types/dist/shared'
 
 /**
  * Shared EChart configuration builders for chart widgets
@@ -26,10 +26,18 @@ export function niceNum(value: number): number {
 /**
  * Builds standard legend configuration for chart widgets
  *
- * @param hasLegend - Whether to show the legend
+ * @param params - Legend configuration parameters
+ * @param params.hasLegend - Whether to show the legend
+ * @param params.labelFormatter - Optional formatter for legend item names
  * @returns Legend configuration object
  */
-export function buildLegendConfig(hasLegend: boolean): LegendComponentOption {
+export function buildLegendConfig({
+  hasLegend,
+  labelFormatter,
+}: {
+  hasLegend: boolean
+  labelFormatter?: (value: string | number) => string | number
+}): LegendComponentOption {
   return {
     show: hasLegend,
     icon: 'circle' as const,
@@ -37,6 +45,9 @@ export function buildLegendConfig(hasLegend: boolean): LegendComponentOption {
     bottom: 0,
     orient: 'horizontal',
     type: 'scroll',
+    ...(labelFormatter && {
+      formatter: (name: string) => String(labelFormatter(name)),
+    }),
   }
 }
 
@@ -101,25 +112,24 @@ export function createAxisLabelFormatter(
 }
 
 /**
- * Applies formatter to xAxis configuration
- * Only applies to single axis objects (not arrays) with type 'value'
+ * Applies labelFormatter to xAxis configuration
+ * Applies to any xAxis regardless of axis type (category, value, etc.)
  *
  * @param xAxis - Existing xAxis configuration
- * @param formatter - Optional formatter function from widget config
- * @returns Updated xAxis configuration or undefined if no changes needed
+ * @param labelFormatter - Optional labelFormatter function from widget config
+ * @returns Updated xAxis configuration
  */
 export function applyXAxisFormatter(
   xAxis: unknown,
-  formatter?: (value: number) => string,
+  formatter?: (value: string | number) => string | number,
 ) {
-  let axisFormatter = createAxisLabelFormatter(formatter)
-
   const xAxisIsObject = xAxis && !Array.isArray(xAxis)
   const xAxisTyped = xAxis as { type?: string; axisLabel?: unknown }
 
-  if (!xAxisIsObject || xAxisTyped.type !== 'value') {
-    axisFormatter = undefined
-  }
+  const axisFormatter =
+    formatter && xAxisIsObject
+      ? (value: string | number) => String(formatter(value))
+      : undefined
 
   return {
     ...xAxisTyped,
@@ -215,3 +225,59 @@ export function createTooltipFormatter(
     return tooltip(name, formattedValues.join(''))
   }
 }
+
+/**
+ * Builds a series `label` config that applies formatter to the data value
+ * extracted from a dataset row using ECharts encode/dimensionNames.
+ *
+ * Does not set `show` — labels remain hidden by default per ECharts defaults.
+ *
+ * @param formatter - Optional numeric value formatter
+ * @param encodeKey - The encode dimension key to extract ('y' for vertical charts, 'x' for horizontal)
+ */
+export function buildSeriesLabelConfig(
+  formatter?: (value: number) => string,
+  encodeKey = 'y',
+): { label: { formatter: (params: CallbackDataParams) => string } } | object {
+  if (!formatter) return {}
+
+  return {
+    label: {
+      formatter: (params: CallbackDataParams) => {
+        const encodeIndex = params.encode?.[encodeKey]?.[0]
+        if (encodeIndex === undefined) return ''
+        const dimName = params.dimensionNames?.[encodeIndex]
+        const row = params.value as Record<string, string | number>
+        const value = dimName ? row[dimName] : undefined
+        return typeof value === 'number'
+          ? formatter(value)
+          : String(value ?? '')
+      },
+    },
+  }
+}
+
+/**
+ * Builds a series `label` config that applies formatter to a raw numeric value.
+ * Used by histogram where series data is number[] (not datasets).
+ *
+ * Does not set `show` — labels remain hidden by default per ECharts defaults.
+ *
+ * @param formatter - Optional numeric value formatter
+ */
+export function buildHistogramSeriesLabelConfig(
+  formatter?: (value: number) => string,
+): { label: { formatter: (params: CallbackDataParams) => string } } | object {
+  if (!formatter) return {}
+
+  return {
+    label: {
+      formatter: (params: CallbackDataParams) => {
+        const value = params.value as number
+        return typeof value === 'number'
+          ? formatter(value)
+          : String(value ?? '')
+      },
+    },
+  }
+}

package/src/widgets/utils/formatter.ts

@@ -0,0 +1,2 @@
+export const defaultFormatter = (value: number) => String(value)
+export const defaultLabelFormatter = (value: string | number) => value

package/src/widgets/utils/index.ts

@@ -0,0 +1,26 @@
+// Formatter
+export { defaultFormatter, defaultLabelFormatter } from './formatter'
+
+// Chart configuration
+export { createChartWidgetConfig } from './chart-config'
+export type {
+  ChartWidgetBaseConfig,
+  CreateChartWidgetConfigParams,
+} from './chart-config'
+export { flattenObjectArrayToCSV, scatterplotDataToCSV } from './chart-config'
+export {
+  buildLegendConfig,
+  buildGridConfig,
+  createTooltipPositioner,
+  createAxisLabelFormatter,
+  createTooltipFormatter,
+  applyXAxisFormatter,
+  applyYAxisFormatter,
+  niceNum,
+} from './chart-config'
+
+// Skeleton styles
+export { baseSkeletonStyles } from './skeleton'
+
+// Download config factory
+export { createChartDownloadConfig } from './chart-config'

package/src/widgets/wrapper/components/actions.tsx

@@ -4,6 +4,9 @@ import { styles } from '../styles'
 
 const EMPTY_ACTIONS: NonNullable<WrapperActionsProps['actions']> = []
 
+/**
+ * Renders action buttons in the widget wrapper header. Each action click event is stopped from propagating to the accordion.
+ */
 export function Actions({ actions = EMPTY_ACTIONS }: WrapperActionsProps) {
   return (
     <Box sx={styles.actions} className='widget-wrapper-actions'>

package/src/widgets/wrapper/components/options.tsx

@@ -12,6 +12,9 @@ import { styles } from '../styles'
 
 const EMPTY_OPTIONS: NonNullable<WrapperOptionsProps['options']> = []
 
+/**
+ * Renders a dropdown options menu in the widget wrapper header, triggered by a vertical ellipsis icon button.
+ */
 export function Options({
   labels,
   options = EMPTY_OPTIONS,

package/src/widgets/wrapper/components/title.tsx

@@ -4,6 +4,9 @@ import { SmartTooltip } from '../../../components'
 import type { ReactNode } from 'react'
 import type { WrapperOptionsProps } from '../types'
 
+/**
+ * Renders the widget title text inside the wrapper header with smart tooltip support for truncated titles.
+ */
 export function Title({
   label,
   children,

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

@@ -9,12 +9,25 @@ import { Title } from './components/title'
 import type { WrapperState, WrapperUIProps } from './types'
 import { Options } from './components/options'
 import { Actions } from './components/actions'
-import { useWidgetStore } from '../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 
 const EMPTY_ACTIONS: NonNullable<WrapperUIProps['actions']> = []
 const EMPTY_OPTIONS: NonNullable<WrapperUIProps['options']> = []
 
+/**
+ * Presentational wrapper component that renders the widget accordion UI with title, actions, options menu, and loading indicator. For uncontrolled usage without automatic widget store synchronization, use this instead of WidgetWrapper.
+ *
+ * @example
+ * ```tsx
+ * <WrapperUI
+ *   id="my-widget"
+ *   actions={[<Download key="download" id="my-widget" />]}
+ *   onChangeCollapsed={(e, collapsed) => console.log(collapsed)}
+ * >
+ *   <div>Content</div>
+ * </WrapperUI>
+ * ```
+ */
 export function WrapperUI({
   children,
   id,
@@ -24,17 +37,17 @@ export function WrapperUI({
   options = EMPTY_OPTIONS,
   onChangeCollapsed,
 }: WrapperUIProps) {
-  const title = useWidgetStore(
-    useShallow((state) => state.getWidget<WrapperState>(id)?.title),
-  )
-  const collapsed = useWidgetStore(
-    useShallow((state) => state.getWidget<WrapperState>(id)?.collapsed),
-  )
-  const disabled = useWidgetStore(
-    useShallow((state) => state.getWidget<WrapperState>(id)?.disabled),
-  )
-  const isFetching = useWidgetStore(
-    useShallow((state) => state.getWidget<WrapperState>(id)?.isFetching),
+  // Single consolidated subscription instead of 4 separate ones.
+  const { title, collapsed, disabled, isFetching } = useWidgetSelector(
+    id,
+    (w) => {
+      return {
+        title: (w as WrapperState | undefined)?.title,
+        collapsed: (w as WrapperState | undefined)?.collapsed,
+        disabled: (w as WrapperState | undefined)?.disabled,
+        isFetching: w?.isFetching,
+      }
+    },
   )
 
   return (

package/src/widgets/wrapper/wrapper.tsx

@@ -1,8 +1,22 @@
 import type { WrapperProps, WrapperState } from './types'
 import { WrapperUI } from './wrapper-ui'
-import { useWidgetStore } from '../stores/widget-store'
+import { widgetStoreActions } from '../stores/widget-store'
 import { useLayoutEffect } from 'react'
 
+/**
+ * Container component providing a collapsible header with title, action buttons, and options menu for widgets. Syncs collapse, disabled, and title state with the widget store.
+ *
+ * @example
+ * ```tsx
+ * <WidgetWrapper
+ *   id="my-widget"
+ *   title="Sales Overview"
+ *   actions={[<Download key="download" id="my-widget" items={downloads} />]}
+ * >
+ *   {children}
+ * </WidgetWrapper>
+ * ```
+ */
 export function WidgetWrapper({
   id,
   title,
@@ -15,22 +29,20 @@ export function WidgetWrapper({
   children,
   onChangeCollapsed,
 }: WrapperProps) {
-  const setWidget = useWidgetStore((state) => state.setWidget)
-
   useLayoutEffect(() => {
-    setWidget<WrapperState>(id, {
+    widgetStoreActions.setWidget<WrapperState>(id, {
       collapsed: defaultCollapsed,
       disabled,
       title,
     })
-  }, [defaultCollapsed, disabled, title, id, setWidget])
+  }, [defaultCollapsed, disabled, title, id])
 
   const handleChangeCollapsed = (
     event: React.SyntheticEvent<Element, Event>,
     expanded: boolean,
   ) => {
     onChangeCollapsed?.(event, expanded)
-    setWidget<WrapperState>(id, { collapsed: !expanded })
+    widgetStoreActions.setWidget<WrapperState>(id, { collapsed: !expanded })
   }
 
   return (