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

package/src/widgets/category/components/category-rows.test.tsx

@@ -0,0 +1,213 @@
+/**
+ * Tests for CategoryRowSingle and CategoryRowMulti — both files share the
+ * same conditional-render branches (onClick presence, labelFormatter
+ * presence, selected default).
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { render, fireEvent } from '@testing-library/react'
+import { ThemeProvider, createTheme } from '@mui/material/styles'
+import { CategoryRowSingle } from './category-row-single'
+import { CategoryRowMulti } from './category-row-multi'
+
+const theme = createTheme({})
+function renderWithTheme(ui: React.ReactElement) {
+  return render(<ThemeProvider theme={theme}>{ui}</ThemeProvider>)
+}
+
+const formatter = (v: number) => `${v}`
+
+describe('CategoryRowSingle', () => {
+  it('renders the name and formatted value', () => {
+    const { getByText } = renderWithTheme(
+      <CategoryRowSingle
+        name='Category A'
+        value={42}
+        maxValue={100}
+        color='#f00'
+        formatter={formatter}
+      />,
+    )
+    expect(getByText('Category A')).toBeDefined()
+    expect(getByText('42')).toBeDefined()
+  })
+
+  it('applies labelFormatter when provided', () => {
+    const { getByText } = renderWithTheme(
+      <CategoryRowSingle
+        name='raw'
+        value={10}
+        maxValue={100}
+        color='#f00'
+        formatter={formatter}
+        labelFormatter={(s) => `[${s}]`}
+      />,
+    )
+    expect(getByText('[raw]')).toBeDefined()
+  })
+
+  it('invokes onClick with the row name when clicked', () => {
+    const onClick = vi.fn()
+    const { getByText } = renderWithTheme(
+      <CategoryRowSingle
+        name='X'
+        value={1}
+        maxValue={10}
+        color='#f00'
+        formatter={formatter}
+        onClick={onClick}
+      />,
+    )
+    fireEvent.click(getByText('X'))
+    expect(onClick).toHaveBeenCalledWith({ name: 'X' })
+  })
+
+  it('renders without onClick (handleClick=undefined branch)', () => {
+    expect(() =>
+      renderWithTheme(
+        <CategoryRowSingle
+          name='Y'
+          value={1}
+          maxValue={10}
+          color='#f00'
+          formatter={formatter}
+        />,
+      ),
+    ).not.toThrow()
+  })
+
+  it('respects selected=false', () => {
+    expect(() =>
+      renderWithTheme(
+        <CategoryRowSingle
+          name='Z'
+          value={1}
+          maxValue={10}
+          color='#f00'
+          formatter={formatter}
+          selected={false}
+        />,
+      ),
+    ).not.toThrow()
+  })
+})
+
+describe('CategoryRowMulti', () => {
+  it('renders the name and one bar per value', () => {
+    const { getByText, getAllByText } = renderWithTheme(
+      <CategoryRowMulti
+        name='Multi A'
+        values={[1, 2, 3]}
+        maxValue={10}
+        colors={['#f00', '#0f0', '#00f']}
+        formatter={formatter}
+      />,
+    )
+    expect(getByText('Multi A')).toBeDefined()
+    expect(getAllByText('1')).toHaveLength(1)
+    expect(getAllByText('2')).toHaveLength(1)
+    expect(getAllByText('3')).toHaveLength(1)
+  })
+
+  it('applies labelFormatter when provided', () => {
+    const { getByText } = renderWithTheme(
+      <CategoryRowMulti
+        name='raw'
+        values={[1]}
+        maxValue={10}
+        colors={['#f00']}
+        formatter={formatter}
+        labelFormatter={(s) => `<${s}>`}
+      />,
+    )
+    expect(getByText('<raw>')).toBeDefined()
+  })
+
+  it('invokes onClick with the row name when clicked', () => {
+    const onClick = vi.fn()
+    const { getByText } = renderWithTheme(
+      <CategoryRowMulti
+        name='ClickRow'
+        values={[1, 2]}
+        maxValue={10}
+        colors={['#f00', '#0f0']}
+        formatter={formatter}
+        onClick={onClick}
+      />,
+    )
+    fireEvent.click(getByText('ClickRow'))
+    expect(onClick).toHaveBeenCalledWith({ name: 'ClickRow' })
+  })
+
+  it('renders without onClick', () => {
+    expect(() =>
+      renderWithTheme(
+        <CategoryRowMulti
+          name='N'
+          values={[1, 2]}
+          maxValue={10}
+          colors={['#f00', '#0f0']}
+          formatter={formatter}
+        />,
+      ),
+    ).not.toThrow()
+  })
+
+  it('cycles colors when values.length exceeds colors.length (modulo branch)', () => {
+    // 4 values, 2 colors → uses modulo to cycle (colors[index % colors.length])
+    expect(() =>
+      renderWithTheme(
+        <CategoryRowMulti
+          name='Cycle'
+          values={[1, 2, 3, 4]}
+          maxValue={10}
+          colors={['#f00', '#0f0']}
+          formatter={formatter}
+        />,
+      ),
+    ).not.toThrow()
+  })
+
+  it('handles colors[i % colors.length] being undefined (?? "" fallback)', () => {
+    // Empty colors array → colors[0 % 0] === undefined → falls back to ''
+    expect(() =>
+      renderWithTheme(
+        <CategoryRowMulti
+          name='Empty'
+          values={[1, 2]}
+          maxValue={10}
+          colors={[]}
+          formatter={formatter}
+        />,
+      ),
+    ).not.toThrow()
+  })
+
+  it('respects selected=false', () => {
+    expect(() =>
+      renderWithTheme(
+        <CategoryRowMulti
+          name='Sel'
+          values={[1]}
+          maxValue={10}
+          colors={['#f00']}
+          formatter={formatter}
+          selected={false}
+        />,
+      ),
+    ).not.toThrow()
+  })
+
+  it('renders an empty bar container when values is empty', () => {
+    expect(() =>
+      renderWithTheme(
+        <CategoryRowMulti
+          name='Z'
+          values={[]}
+          maxValue={10}
+          colors={['#f00']}
+          formatter={formatter}
+        />,
+      ),
+    ).not.toThrow()
+  })
+})

package/src/widgets/category/config.ts

@@ -10,6 +10,12 @@ interface CategoryDownloadConfigProps extends ConfigProps {
   series?: CategorySeriesConfig[]
 }
 
+/**
+ * Creates download configuration for category widgets, supporting PNG (screenshot) and CSV (data) exports. CSV output groups values by category across multiple series.
+ *
+ * @param props - Configuration with `refUI` reference and optional `series` for CSV column headers.
+ * @returns Array of download items for use with the Download action.
+ */
 export function categoryDownloadConfig({
   refUI,
   series,
@@ -66,6 +72,11 @@ export function categoryDownloadConfig({
   ]
 }
 
+/**
+ * Returns the default configuration for category list widgets, including empty series and a default `maxItems` of 10.
+ *
+ * @returns Default category widget config.
+ */
 export function categoryConfig(): CategoryWidgetConfig {
   return {
     series: [],

package/src/widgets/category/index.ts

@@ -2,21 +2,20 @@ export { CategoryUI } from './category-ui'
 export { CategorySkeleton } from './skeleton'
 export { categoryConfig, categoryDownloadConfig } from './config'
 
-export {
-  CategoryBar,
-  CategoryRowSingle,
-  CategoryRowMulti,
-  CategoryLegend,
-  CategoryRowOther,
-} from './components'
+export { CategoryBar } from './components/category-bar'
+export type { CategoryBarProps } from './components/category-bar'
 
-export type {
-  CategoryBarProps,
-  CategoryRowSingleProps,
-  CategoryRowMultiProps,
-  CategoryLegendProps,
-  CategoryRowOtherProps,
-} from './components'
+export { CategoryRowSingle } from './components/category-row-single'
+export type { CategoryRowSingleProps } from './components/category-row-single'
+
+export { CategoryRowMulti } from './components/category-row-multi'
+export type { CategoryRowMultiProps } from './components/category-row-multi'
+
+export { CategoryRowOther } from './components/category-row-other'
+export type { CategoryRowOtherProps } from './components/category-row-other'
+
+export { CategoryLegend } from './components/category-legend'
+export type { CategoryLegendProps } from './components/category-legend'
 
 export type {
   CategoryUIProps,

package/src/widgets/category/style.ts

@@ -5,6 +5,7 @@ export const styles = {
     display: 'flex',
     flexDirection: 'column',
     position: 'relative',
+    width: '100%',
   },
   list: {
     display: 'flex',

package/src/widgets/category/types.ts

@@ -29,6 +29,7 @@ export type CategoryWidgetState = BaseWidgetState<
 
 export interface CategoryWidgetConfig {
   formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
   series?: CategorySeriesConfig[]
   maxItems?: number
   labels?: CategoryLabels

package/src/widgets/echart/echart-ui.test.tsx

@@ -3,6 +3,7 @@ import { render } from '@testing-library/react'
 import { EchartUI } from './echart-ui'
 import type { EChartsOption } from 'echarts'
 import * as echarts from 'echarts'
+import { resetSharedResizeObserver } from './shared-resize-observer'
 
 // Mock echarts module
 vi.mock('echarts', () => {
@@ -36,6 +37,7 @@ describe('EchartUI', () => {
     disconnect: ReturnType<typeof vi.fn>
     unobserve: ReturnType<typeof vi.fn>
   }
+  let resizeObserverCallback: ResizeObserverCallback | undefined
 
   const defaultProps = {
     id: 'test-echart',
@@ -73,6 +75,9 @@ describe('EchartUI', () => {
       mockChart as unknown as echarts.ECharts,
     )
 
+    // Reset the shared observer so each test gets a fresh one using the mock
+    resetSharedResizeObserver()
+
     // Mock ResizeObserver
     mockResizeObserver = {
       observe: vi.fn(),
@@ -80,7 +85,12 @@ describe('EchartUI', () => {
       unobserve: vi.fn(),
     }
 
+    resizeObserverCallback = undefined
+
     global.ResizeObserver = class {
+      constructor(callback: ResizeObserverCallback) {
+        resizeObserverCallback = callback
+      }
       observe = mockResizeObserver.observe
       disconnect = mockResizeObserver.disconnect
       unobserve = mockResizeObserver.unobserve
@@ -245,32 +255,26 @@ describe('EchartUI', () => {
     )
   })
 
-  test('disconnects ResizeObserver on unmount', () => {
+  test('unobserves element from shared ResizeObserver on unmount', () => {
     const { unmount } = render(
       <EchartUI {...defaultProps} option={basicOption} />,
     )
 
     unmount()
 
-    expect(mockResizeObserver.disconnect).toHaveBeenCalled()
+    // The shared observer calls unobserve() for the specific element, not disconnect()
+    expect(mockResizeObserver.unobserve).toHaveBeenCalled()
   })
 
   test('calls resize on chart when ResizeObserver triggers', () => {
-    let resizeCallback: ResizeObserverCallback
-
-    global.ResizeObserver = class {
-      constructor(callback: ResizeObserverCallback) {
-        resizeCallback = callback
-      }
-      observe = mockResizeObserver.observe
-      disconnect = mockResizeObserver.disconnect
-      unobserve = mockResizeObserver.unobserve
-    } as unknown as typeof ResizeObserver
-
     render(<EchartUI {...defaultProps} option={basicOption} />)
 
-    // Trigger resize callback
-    resizeCallback!([], mockResizeObserver as unknown as ResizeObserver)
+    // Trigger the shared observer's callback with a mock entry targeting the chart element
+    const chartElement = document.getElementById(defaultProps.id)!
+    const entries: ResizeObserverEntry[] = [
+      { target: chartElement } as unknown as ResizeObserverEntry,
+    ]
+    resizeObserverCallback!(entries, {} as ResizeObserver)
 
     expect(mockChart.resize).toHaveBeenCalled()
   })
@@ -517,6 +521,6 @@ describe('EchartUI', () => {
     unmount()
 
     expect(mockChart.dispose).toHaveBeenCalled()
-    expect(mockResizeObserver.disconnect).toHaveBeenCalled()
+    expect(mockResizeObserver.unobserve).toHaveBeenCalled()
   })
 })

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

@@ -2,13 +2,21 @@ import { useEffect, useRef, useImperativeHandle } from 'react'
 import * as echarts from 'echarts'
 import type { EchartUIProps } from './types'
 import { useWidgetRef } from '../../hooks'
+import { observeResize } from './shared-resize-observer'
 
+/**
+ * Presentational component that initializes and manages an Apache ECharts instance.
+ *
+ * @remarks
+ * Handles chart lifecycle (init, dispose), option updates, resize observation, and event listener management.
+ * Uses SVG renderer with a default height of 304px.
+ */
 export function EchartUI(props: EchartUIProps) {
   const { id, ref, init, option, className, style, onEvents } = props
 
-  const chartRef = useWidgetRef<HTMLDivElement>(id)
+  const { ref: chartRef, instance: chartInstanceRef } =
+    useWidgetRef<HTMLDivElement>(id)
   const chartInstance = useRef<echarts.ECharts>(null)
-  const resizeObserverRef = useRef<ResizeObserver | null>(null)
 
   useImperativeHandle(ref, () => chartInstance.current!, [])
 
@@ -20,12 +28,14 @@ export function EchartUI(props: EchartUIProps) {
       height: 304,
       ...init,
     })
+    chartInstanceRef.current = chartInstance.current
     // Cleanup function
     return () => {
       chartInstance.current?.dispose()
       chartInstance.current = null
+      chartInstanceRef.current = null
     }
-  }, [chartRef, init])
+  }, [chartInstanceRef, chartRef, init])
 
   // Update chart when options change
   useEffect(() => {
@@ -35,19 +45,13 @@ export function EchartUI(props: EchartUIProps) {
     })
   }, [option])
 
-  // Handle resize using ResizeObserver
+  // Handle resize using shared ResizeObserver (single instance for all charts)
   useEffect(() => {
-    const handleResize = () => {
-      chartInstance.current?.resize()
-    }
-
-    resizeObserverRef.current = new ResizeObserver(handleResize)
-    resizeObserverRef.current.observe(chartRef.current!)
+    if (!chartRef.current) return
 
-    return () => {
-      resizeObserverRef.current?.disconnect()
-      resizeObserverRef.current = null
-    }
+    return observeResize(chartRef.current, () => {
+      chartInstance.current?.resize()
+    })
   }, [chartRef])
 
   useEffect(() => {

package/src/widgets/echart/echart.tsx

@@ -5,36 +5,28 @@ import type {
   EchartOptionsProps,
 } from './types'
 import { EchartUI } from './echart-ui'
-import { useWidgetStore } from '../stores/widget-store'
-import { useShallow } from 'zustand/shallow'
+import { useWidgetSelector } from '../stores/use-widget-selector'
 import { useMemo } from 'react'
 
+/**
+ * Stateful EChart widget component that reads data and options from the widget store and renders an ECharts chart.
+ *
+ * @remarks
+ * Transforms widget data into ECharts dataset format and delegates rendering to {@link EchartUI}.
+ */
 export function Echart(props: EchartProps) {
-  const id = useWidgetStore(
-    (state) => state.getWidget<EchartWidgetState>(props.id)?.id,
-  )
-
-  const data = useWidgetStore(
-    useShallow(
-      (state) =>
-        state.getWidget<EchartWidgetState>(props.id)?.data as
-          | EchartWidgetData
-          | undefined,
-    ),
-  )
-
-  const widgetOption = useWidgetStore(
-    useShallow((state) => state.getWidget<EchartWidgetState>(props.id)?.option),
-  )
-
-  const onEvents = useWidgetStore(
-    useShallow(
-      (state) => state.getWidget<EchartWidgetState>(props.id)?.onEvents,
-    ),
-  )
-
-  const init = useWidgetStore(
-    (state) => state.getWidget<EchartWidgetState>(props.id)?.init,
+  // Single consolidated subscription instead of 5 separate ones.
+  const { id, data, widgetOption, onEvents, init } = useWidgetSelector(
+    props.id,
+    (w) => ({
+      id: w?.id,
+      data: (w as EchartWidgetState | undefined)?.data as
+        | EchartWidgetData
+        | undefined,
+      widgetOption: (w as EchartWidgetState | undefined)?.option,
+      onEvents: (w as EchartWidgetState | undefined)?.onEvents,
+      init: (w as EchartWidgetState | undefined)?.init,
+    }),
   )
 
   // Memoize dataset transformation to avoid re-computing on every render

package/src/widgets/echart/options.ts

@@ -1,5 +1,12 @@
 import type { EchartOptionsProps, EchartWidgetOptionProps } from './types'
 
+/**
+ * Returns the shared base ECharts options used across all EChart-based widgets (bar, pie, histogram, etc.).
+ *
+ * @remarks
+ * Configures grid spacing, tooltip styling, legend, axis pointer, and the default color palette
+ * derived from the MUI theme.
+ */
 export function getCommonOptions({
   theme,
 }: EchartWidgetOptionProps<unknown>): EchartOptionsProps {
@@ -16,10 +23,7 @@ export function getCommonOptions({
     },
     tooltip: {
       axisPointer: {
-        type: 'shadow',
-        shadowStyle: {
-          color: 'rgba(44,48,50, 0.08)',
-        },
+        type: 'line',
       },
       backgroundColor: theme.palette.grey[900],
       borderWidth: 0,

package/src/widgets/echart/shared-resize-observer.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared ResizeObserver singleton for all ECharts instances.
+ *
+ * Instead of creating 100+ individual ResizeObserver instances (one per chart),
+ * this module provides a single shared observer that efficiently handles resize
+ * callbacks for all registered elements.
+ */
+
+type ResizeCallback = () => void
+
+const callbacks = new Map<Element, ResizeCallback>()
+
+let observer: ResizeObserver | null = null
+
+function getObserver(): ResizeObserver {
+  observer ??= new ResizeObserver((entries) => {
+    for (const entry of entries) {
+      const callback = callbacks.get(entry.target)
+      callback?.()
+    }
+  })
+  return observer
+}
+
+export function observeResize(
+  element: Element,
+  callback: ResizeCallback,
+): () => void {
+  callbacks.set(element, callback)
+  getObserver().observe(element)
+
+  return () => {
+    callbacks.delete(element)
+    getObserver().unobserve(element)
+  }
+}
+
+/** Reset the shared observer (for testing only). */
+export function resetSharedResizeObserver(): void {
+  if (observer) {
+    observer.disconnect()
+    observer = null
+  }
+  callbacks.clear()
+}

package/src/widgets/echart/types.ts

@@ -1,7 +1,7 @@
 import type { EChartsOption } from 'echarts'
 import type * as echarts from 'echarts'
 import type { BaseWidgetState } from '../stores/types'
-import type { Ref } from 'react'
+import type { Ref, RefObject } from 'react'
 import { theme as CartoTheme } from '@carto/meridian-ds/theme'
 
 export type EchartOptionsProps = EChartsOption
@@ -26,16 +26,20 @@ export type EchartWidgetState = BaseWidgetState<{
   option: EchartUIProps['option']
   onEvents?: EchartUIProps['onEvents']
   init?: EchartUIProps['init']
+  instance?: RefObject<echarts.ECharts | null>
 }>
 
 export interface EchartWidgetOptionProps<D> {
   data?: D
   theme: typeof CartoTheme
   formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
 }
 
 export interface EchartWidgetProps {
   type: string
   option: EchartUIProps['option']
   onEvents?: EchartUIProps['onEvents']
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
 }