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

package/src/widgets/echart/utils.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest'
+import type { Theme } from '@mui/material'
+
+import {
+  mergeEchartWidgetConfig,
+  getEChartZoomConfig,
+  getEChartBrushConfig,
+  getEChartStackConfig,
+} from './utils'
+
+const theme = {
+  spacing: (n: number) => `${n * 8}`,
+  palette: {
+    common: { white: '#ffffff' },
+    secondary: { main: '#3366ff' },
+    black: { 60: 'rgba(0,0,0,0.6)' },
+  },
+  typography: {
+    overlineDelicate: { fontSize: '11', fontFamily: 'Inter, sans-serif' },
+  },
+} as unknown as Theme
+
+describe('mergeEchartWidgetConfig', () => {
+  it('returns a deep-merged base + override when no custom merger is provided', () => {
+    const a = { title: { text: 'A' }, tooltip: { trigger: 'axis' } } as never
+    const b = { title: { subtext: 'sub' } } as never
+    const merged = mergeEchartWidgetConfig(a, b) as unknown as {
+      title: { text: string; subtext: string }
+    }
+    expect(merged.title.text).toBe('A')
+    expect(merged.title.subtext).toBe('sub')
+  })
+
+  it('handles both inputs being undefined (defaults to {})', () => {
+    const merged = mergeEchartWidgetConfig(undefined, undefined)
+    expect(merged).toEqual({})
+  })
+
+  it('replaces `color` arrays rather than concatenating', () => {
+    const merged = mergeEchartWidgetConfig(
+      { color: ['#ff0000', '#00ff00'] },
+      { color: ['#0000ff'] },
+    )
+    expect(merged.color).toEqual(['#0000ff'])
+  })
+
+  it('composes `axisLabel` formatter functions so base formatter can suppress', () => {
+    const base = {
+      xAxis: {
+        axisLabel: {
+          formatter: (v: unknown) => (v === 0 ? '' : `BASE-${String(v)}`),
+        },
+      },
+    }
+    const override = {
+      xAxis: {
+        axisLabel: {
+          formatter: (v: unknown) => `OVR-${String(v)}`,
+        },
+      },
+    }
+    const merged = mergeEchartWidgetConfig(base, override)
+    const fmt = (
+      merged.xAxis as { axisLabel: { formatter: (v: unknown) => unknown } }
+    ).axisLabel.formatter
+    expect(fmt(0)).toBe('') // base returned '' → suppressed
+    expect(fmt(5)).toBe('OVR-5') // base non-empty → fall through to override
+  })
+
+  it('merges plain object axisLabel keys when no formatter present', () => {
+    const merged = mergeEchartWidgetConfig(
+      { xAxis: { axisLabel: { color: 'red' } } },
+      { xAxis: { axisLabel: { fontSize: 12 } } },
+    )
+    const al = (merged.xAxis as { axisLabel: Record<string, unknown> })
+      .axisLabel
+    expect(al.color).toBe('red')
+    expect(al.fontSize).toBe(12)
+  })
+
+  it('merges `series` element-by-element rather than concatenating', () => {
+    const a = {
+      series: [
+        { name: 'a1', data: [1, 2] },
+        { name: 'a2', data: [3] },
+      ],
+    } as never
+    const b = { series: [{ barWidth: '60%' }] } as never
+    const merged = mergeEchartWidgetConfig(a, b) as unknown as {
+      series: { name?: string; barWidth?: string; data?: number[] }[]
+    }
+    const s = merged.series
+    expect(s).toHaveLength(2)
+    expect(s[0]!.name).toBe('a1')
+    expect(s[0]!.barWidth).toBe('60%')
+    expect(s[1]!.name).toBe('a2')
+  })
+
+  it('handles series merge when one side has no series array (defaults to length 0)', () => {
+    const merged = mergeEchartWidgetConfig(
+      { series: [{ name: 'only' }] },
+      { series: [] },
+    )
+    const s = merged.series as { name?: string }[]
+    expect(s).toHaveLength(1)
+    expect(s[0]!.name).toBe('only')
+  })
+
+  it('delegates to a custom merger when provided and it returns a function', () => {
+    const merged = mergeEchartWidgetConfig(
+      { title: { text: 'A' } },
+      { title: { text: 'B' } },
+      (key) =>
+        key === 'title'
+          ? (_a: unknown, b: unknown) => ({ ...(b as object), custom: true })
+          : undefined,
+    )
+    expect((merged.title as { text: string; custom: boolean }).text).toBe('B')
+    expect((merged.title as { text: string; custom: boolean }).custom).toBe(
+      true,
+    )
+  })
+
+  it('falls through to default merger when custom merger returns undefined for the key', () => {
+    const merged = mergeEchartWidgetConfig(
+      { color: ['#a'] },
+      { color: ['#b'] },
+      () => undefined,
+    )
+    expect(merged.color).toEqual(['#b'])
+  })
+})
+
+describe('getEChartZoomConfig', () => {
+  it('returns a default config (inside + xSlider) with no args', () => {
+    const cfg = getEChartZoomConfig()
+    expect(cfg.dataZoom).toBeDefined()
+    // inside + xSlider both true → 2 entries
+    expect(cfg.dataZoom.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('honours an explicit range start/end', () => {
+    const cfg = getEChartZoomConfig({ start: 25, end: 75 })
+    const insideCfg = cfg.dataZoom.find(
+      (z) => (z as { type: string }).type === 'inside',
+    ) as { start: number; end: number }
+    expect(insideCfg.start).toBe(25)
+    expect(insideCfg.end).toBe(75)
+  })
+
+  it('emits a vertical inside zoom when ySlider=true and inside=true', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: true, ySlider: true },
+    )
+    const verticalInside = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; orientation?: string }).type === 'inside' &&
+        (z as { orientation?: string }).orientation === 'vertical',
+    )
+    expect(verticalInside).toBeDefined()
+  })
+
+  it('omits the inside entry when inside=false', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: false, xSlider: true },
+    )
+    const insideEntries = cfg.dataZoom.filter(
+      (z) => (z as { type: string }).type === 'inside',
+    )
+    expect(insideEntries).toHaveLength(0)
+  })
+
+  it('omits the xSlider entry when xSlider=false', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: false, xSlider: false, ySlider: false },
+    )
+    expect(cfg.dataZoom).toHaveLength(0)
+  })
+
+  it('includes a yAxis slider when ySlider=true', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { inside: false, xSlider: false, ySlider: true },
+    )
+    const yAxisSlider = cfg.dataZoom.find((z) => {
+      const c = z as { type: string; yAxisIndex?: number[] }
+      return c.type === 'slider' && Array.isArray(c.yAxisIndex)
+    })
+    expect(yAxisSlider).toBeDefined()
+  })
+
+  it('respects bottomOffset for the xAxis slider', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { bottomOffset: 16 },
+    )
+    const xSlider = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; bottom?: number }).type === 'slider' &&
+        (z as { bottom?: number }).bottom === 16,
+    )
+    expect(xSlider).toBeDefined()
+  })
+
+  it('threads through xAxisLabelFormatter to the xSlider config', () => {
+    const fmt = (v: number) => `lbl-${v}`
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { xAxisLabelFormatter: fmt },
+    )
+    const xSlider = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; xAxisIndex?: number[] }).type === 'slider' &&
+        Array.isArray((z as { xAxisIndex?: number[] }).xAxisIndex),
+    ) as { labelFormatter: typeof fmt }
+    expect(xSlider.labelFormatter).toBe(fmt)
+  })
+
+  it('hides sliders when showSliders=false (`show` field is false)', () => {
+    const cfg = getEChartZoomConfig(
+      { start: 0, end: 100 },
+      { showSliders: false },
+    )
+    const xSlider = cfg.dataZoom.find(
+      (z) => (z as { type: string }).type === 'slider',
+    ) as { show: boolean }
+    expect(xSlider.show).toBe(false)
+  })
+
+  it('falls back to default spacing strings when theme.spacing is missing', () => {
+    const cfg = getEChartZoomConfig(undefined, undefined, undefined)
+    expect(cfg.dataZoom).toBeDefined()
+  })
+
+  it('applies theme-derived slider styles when a theme is provided', () => {
+    const cfg = getEChartZoomConfig({ start: 0, end: 100 }, undefined, theme)
+    const xSlider = cfg.dataZoom.find(
+      (z) =>
+        (z as { type: string; xAxisIndex?: number[] }).type === 'slider' &&
+        Array.isArray((z as { xAxisIndex?: number[] }).xAxisIndex),
+    ) as unknown as { fillerColor: string }
+    expect(xSlider.fillerColor).toBeDefined()
+  })
+})
+
+describe('getEChartBrushConfig', () => {
+  it('returns a default brush config when called with no args', () => {
+    const cfg = getEChartBrushConfig()
+    expect(cfg.brush.brushType).toBe('lineX')
+    expect(cfg.brush.brushMode).toBe('single')
+    expect(cfg.brush.xAxisIndex).toBe(0)
+  })
+
+  it('respects explicit brushType, brushMode, and xAxisIndex', () => {
+    const cfg = getEChartBrushConfig({
+      brushType: 'polygon',
+      brushMode: 'multiple',
+      xAxisIndex: 2,
+    })
+    expect(cfg.brush.brushType).toBe('polygon')
+    expect(cfg.brush.brushMode).toBe('multiple')
+    expect(cfg.brush.xAxisIndex).toBe(2)
+  })
+})
+
+describe('getEChartStackConfig', () => {
+  it('uses the default stack group when no arg passed', () => {
+    expect(getEChartStackConfig().stack).toBe('stacked')
+  })
+
+  it('respects an explicit stack group name', () => {
+    expect(getEChartStackConfig('foo').stack).toBe('foo')
+  })
+})

package/src/widgets/echart/utils.ts

@@ -3,31 +3,86 @@ import type { EchartOptionsProps } from './types'
 import type { Theme } from '@mui/material'
 import { DEFAULT_STACK_GROUP } from './const'
 
+/**
+ * Deep-merges two ECharts option objects with smart handling for `color`, `axisLabel`, and `series` keys.
+ *
+ * @param optionA - Base ECharts options.
+ * @param optionB - Override ECharts options to merge on top.
+ * @param customMergeFn - Optional function returning a custom merge strategy per key.
+ * @returns The merged ECharts options object.
+ *
+ * @remarks
+ * - `color` arrays are replaced entirely (not concatenated).
+ * - `axisLabel` formatters are composed so the base formatter can suppress values by returning `''`.
+ * - `series` arrays are merged element-by-element rather than concatenated.
+ *
+ * @example
+ * ```tsx
+ * const option = mergeEchartWidgetConfig(props.option, {
+ *   series: [{ barWidth: '60%', itemStyle: { borderRadius: [4, 4, 0, 0] } }],
+ *   tooltip: { trigger: 'axis' },
+ * })
+ * ```
+ */
 export function mergeEchartWidgetConfig<T extends EchartOptionsProps>(
-  ...options: [T | undefined, T | undefined]
+  optionA: T | undefined,
+  optionB: T | undefined,
+  customMergeFn?: (
+    key: string,
+  ) => ((a: unknown, b: unknown) => unknown) | undefined,
 ): T {
-  return deepmerge(options[0] ?? {}, options[1] ?? {}, {
+  return deepmerge(optionA ?? {}, optionB ?? {}, {
     customMerge: (key) => {
+      const externalMerge = customMergeFn?.(key)
+      if (externalMerge) return externalMerge
+
       if (key === 'color') {
         return (_, b: T['color']) => b
       }
+      if (key === 'axisLabel') {
+        return (
+          a: Record<string, unknown> | undefined,
+          b: Record<string, unknown> | undefined,
+        ) => {
+          const merged = { ...a, ...b }
+          if (
+            typeof a?.formatter === 'function' &&
+            typeof b?.formatter === 'function'
+          ) {
+            const baseFormatter = a.formatter as (value: unknown) => unknown
+            const customFormatter = b.formatter as (value: unknown) => unknown
+            merged.formatter = (value: unknown) => {
+              const baseResult = baseFormatter(value)
+              if (baseResult === '') return ''
+              return customFormatter(value)
+            }
+          }
+          return merged
+        }
+      }
       if (key === 'series') {
         return (a: T['series'][], b: T['series'][]) => {
-          if (!a.length) return a // If there is no series in a, return a as is
-
-          const mergedSeries = b?.map((bItem, index) => {
+          const maxLength = Math.max(a?.length ?? 0, b?.length ?? 0)
+          return Array.from({ length: maxLength }, (_, index) => {
             const aItem = a?.[index] ?? {}
+            const bItem = b?.[index] ?? {}
             return deepmerge(aItem, bItem as object)
           })
-          return mergedSeries
         }
       }
     },
   }) as T
 }
 
+/**
+ * Generates ECharts `dataZoom` configuration for interactive zoom and pan on chart axes.
+ *
+ * @param range - Initial visible range as `{ start, end }` percentages (0-100). Defaults to full range.
+ * @param options - Zoom behavior options including axis sliders, inside zoom, and formatter.
+ * @param theme - Optional MUI theme for styled slider handles and backgrounds.
+ * @returns An object containing the `dataZoom` array configuration.
+ */
 export function getEChartZoomConfig(
-  zoom: boolean,
   { start, end }: { start: number; end: number } = { start: 0, end: 100 },
   {
     inside = true,
@@ -46,6 +101,7 @@ export function getEChartZoomConfig(
   },
   theme?: Theme,
 ) {
+  const zoom = true
   const sliderStyles = theme ? getEChartZoomSliderStyles(theme) : {}
 
   return {
@@ -152,20 +208,37 @@ function getEChartZoomSliderStyles(theme: Theme) {
   } as const
 }
 
-export function getEChartBrushConfig(brush: boolean) {
-  return brush
-    ? {
-        brush: {
-          brushType: 'rect',
-          brushMode: 'single',
-        },
-      }
-    : {}
+/**
+ * Generates ECharts `brush` configuration for interactive data selection on charts.
+ *
+ * @param options - Brush options including type, mode, and target axis index.
+ * @returns An object containing the `brush` configuration.
+ */
+export function getEChartBrushConfig(
+  { brushType = 'lineX', brushMode = 'single', xAxisIndex = 0 } = {} as {
+    brushType?: string
+    brushMode?: string
+    xAxisIndex?: number
+    throttleType?: string
+    throttleDelay?: number
+  },
+) {
+  return {
+    brush: {
+      toolbox: ['lineX', 'clear'],
+      brushType,
+      brushMode,
+      xAxisIndex,
+    },
+  }
 }
 
-export function getEChartStackConfig(
-  stack: boolean,
-  stackGroup: string = DEFAULT_STACK_GROUP,
-) {
-  return { stack: stack ? stackGroup : undefined }
+/**
+ * Returns an ECharts `stack` configuration to group series into a stacked layout.
+ *
+ * @param stackGroup - The stack group identifier. Defaults to the library's default group.
+ * @returns An object with the `stack` property set to the group name.
+ */
+export function getEChartStackConfig(stackGroup: string = DEFAULT_STACK_GROUP) {
+  return { stack: stackGroup }
 }

package/src/widgets/error/error.tsx

@@ -1,21 +1,29 @@
 import { Alert, AlertTitle } from '@mui/material'
-import { useWidgetStore } from '../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 import type { WidgetErrorProps } from './types'
 
+/**
+ * Displays an error alert when a widget encounters an error during data loading. Reads error state from the widget store and hides errors during loading/fetching to prevent flashing.
+ *
+ * @example
+ * ```tsx
+ * <WidgetError id="my-widget">
+ *   <WidgetContent />
+ * </WidgetError>
+ * ```
+ */
 export function WidgetError({
   id,
   children,
   title: titleProp,
   description,
 }: WidgetErrorProps) {
-  const isLoading = useWidgetStore(
-    useShallow((state) => state.widgets[id]?.isLoading),
-  )
-  const isFetching = useWidgetStore(
-    useShallow((state) => state.widgets[id]?.isFetching),
-  )
-  const error = useWidgetStore(useShallow((state) => state.widgets[id]?.error))
+  // Single consolidated subscription instead of 3 separate ones.
+  const { isLoading, isFetching, error } = useWidgetSelector(id, (w) => ({
+    isLoading: w?.isLoading,
+    isFetching: w?.isFetching,
+    error: w?.error,
+  }))
 
   // Don't show error during loading/fetching states
   if (isLoading || isFetching) {

package/src/widgets/formula/components/item.tsx

@@ -2,6 +2,9 @@ import { Typography } from '@mui/material'
 import type { ItemProps } from '../types'
 import { styles } from '../style'
 
+/**
+ * Base typography wrapper used by formula sub-components (Value, Prefix, Suffix) to render styled text.
+ */
 export function Item(props: ItemProps) {
   return (
     <Typography

package/src/widgets/formula/components/prefix.tsx

@@ -1,13 +1,14 @@
 import { type FormulaWidgetState, type ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from './item'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
+/**
+ * Renders the prefix content (e.g., currency symbol) before a formula value, if defined in the data item.
+ */
 export function Prefix({ id, index = 0, ...props }: ValueProps) {
-  const prefix = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.data?.[index]?.prefix,
-    ),
+  const prefix = useWidgetSelector(
+    id,
+    (w) => (w as FormulaWidgetState | undefined)?.data?.[index]?.prefix,
   )
 
   if (!prefix) {

package/src/widgets/formula/components/row.tsx

@@ -1,12 +1,15 @@
 import { Box } from '@mui/material'
 import { styles } from '../style'
 import type { FormulaWidgetState, RowProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
+/**
+ * Iterates over the widget's data items and renders a row for each one using render props.
+ */
 export function Row(props: RowProps) {
-  const data = useWidgetStore(
-    useShallow((state) => state.getWidget<FormulaWidgetState>(props.id)?.data),
+  const data = useWidgetSelector(
+    props.id,
+    (w) => (w as FormulaWidgetState | undefined)?.data,
   )
 
   return data?.map((_, index) => {

package/src/widgets/formula/components/series.tsx

@@ -1,13 +1,14 @@
 import { Avatar } from '@mui/material'
 import type { FormulaWidgetState, ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
+/**
+ * Renders a colored avatar badge showing the first letter of the series name for multi-value formula widgets.
+ */
 export function Series({ id, index = 0 }: Pick<ValueProps, 'id' | 'index'>) {
-  const serie = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.series?.[index],
-    ),
+  const serie = useWidgetSelector(
+    id,
+    (w) => (w as FormulaWidgetState | undefined)?.series?.[index],
   )
   if (!serie) {
     return null

package/src/widgets/formula/components/suffix.tsx

@@ -1,14 +1,15 @@
 import { type FormulaWidgetState, type ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from './item'
 import type { Theme } from '@mui/material'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
+/**
+ * Renders the suffix content (e.g., unit label) after a formula value, if defined in the data item.
+ */
 export function Suffix({ id, index = 0, ...props }: ValueProps) {
-  const suffix = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.data?.[index]?.suffix,
-    ),
+  const suffix = useWidgetSelector(
+    id,
+    (w) => (w as FormulaWidgetState | undefined)?.data?.[index]?.suffix,
   )
 
   if (!suffix) {

package/src/widgets/formula/components/value.tsx

@@ -1,25 +1,20 @@
 import { type FormulaWidgetState, type ValueProps } from '../types'
-import { useWidgetStore } from '../../stores/widget-store'
 import { Item } from './item'
-import { useShallow } from 'zustand/shallow'
-
-const defaultFormatter = (value: number) => value.toString()
+import { defaultFormatter } from '../../utils/formatter'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
 
+/**
+ * Displays the formatted numeric value for a formula widget data item, applying the widget's formatter and color.
+ */
 export function Value({ id, index = 0, ...props }: ValueProps) {
-  const value = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.data?.[index]?.value,
-    ),
-  )
-  const color = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<FormulaWidgetState>(id)?.data?.[index]?.color,
-    ),
-  )
-  const formatter =
-    useWidgetStore(
-      useShallow((state) => state.getWidget<FormulaWidgetState>(id)?.formatter),
-    ) ?? defaultFormatter
+  const { value, color, formatter } = useWidgetSelector(id, (w) => {
+    const widget = w as FormulaWidgetState | undefined
+    return {
+      value: widget?.data?.[index]?.value,
+      color: widget?.data?.[index]?.color,
+      formatter: widget?.formatter ?? defaultFormatter,
+    }
+  })
 
   return (
     <Item TypographyProps={{ color }} {...props}>

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

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { createRef } from 'react'
+import { formulaConfig, formulaDownloadConfig } from './config'
+
+describe('formulaConfig', () => {
+  it('returns an empty series array', () => {
+    const cfg = formulaConfig()
+    expect(cfg.series).toEqual([])
+  })
+})
+
+describe('formulaDownloadConfig', () => {
+  it('returns a two-item download config (PNG + CSV)', () => {
+    const refUI = createRef<HTMLDivElement>()
+    const cfg = formulaDownloadConfig({ refUI })
+    expect(cfg).toHaveLength(2)
+  })
+
+  it('CSV modifier maps numeric values out of data items', async () => {
+    const refUI = createRef<HTMLDivElement>()
+    const cfg = formulaDownloadConfig({ refUI })
+    const csvItem = cfg[1]!
+    // Spy-style: the underlying downloadToCSV.modifier is the only thing that
+    // actually returns. We just confirm `modifier` runs without throwing for
+    // both populated and empty inputs — that exercises the `?? []` branch.
+    await expect(
+      csvItem.modifier([{ value: 1 }, { value: 2 }]),
+    ).resolves.not.toThrow()
+    await expect(
+      csvItem.modifier(
+        undefined as unknown as Parameters<
+          NonNullable<typeof csvItem.modifier>
+        >[0],
+      ),
+    ).resolves.not.toThrow()
+  })
+})

package/src/widgets/formula/config.ts

@@ -2,6 +2,12 @@ import { downloadToCSV, downloadToPNG } from '../actions'
 import type { ConfigProps } from '../loader/types'
 import type { FormulaDownloadConfig, FormulaWidgetConfig } from './types'
 
+/**
+ * Creates download configuration for formula widgets, supporting PNG (screenshot) and CSV (data) exports.
+ *
+ * @param props - Configuration with `refUI` reference for PNG export.
+ * @returns Array of download items for use with the Download action.
+ */
 export function formulaDownloadConfig({
   refUI,
 }: ConfigProps): FormulaDownloadConfig {
@@ -20,6 +26,11 @@ export function formulaDownloadConfig({
   ]
 }
 
+/**
+ * Returns the default configuration for formula (single or multiple numeric value) widgets.
+ *
+ * @returns Default formula widget config with empty series.
+ */
 export function formulaConfig(): FormulaWidgetConfig {
   return {
     series: [],