@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,368 +1,108 @@
-import { describe, test, expect, beforeEach } from 'vitest'
+import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { SpreadUI } from './spread-ui'
-import { useWidgetStore } from '../stores/widget-store'
-import type { SpreadWidgetState } from './types'
 
-describe('SpreadUI', () => {
-  beforeEach(() => {
-    useWidgetStore.getState().clearWidgets()
-  })
-
-  test('renders empty container when widget does not exist', () => {
-    const { container } = render(<SpreadUI id='non-existent' />)
-    // Box wrapper is rendered but Row returns null for missing widget
-    expect(container.firstChild?.childNodes.length).toBe(0)
-  })
-
-  test('renders with single spread data item', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 2.1, max: 2.23, suffix: '€' }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('2.1')).toBeTruthy()
-    expect(screen.getByText('-')).toBeTruthy()
-    expect(screen.getByText('2.23')).toBeTruthy()
-    expect(screen.getByText('€')).toBeTruthy()
-  })
-
-  test('renders with multiple spread data items', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [
-        { min: 1.5, max: 2.5, prefix: '$' },
-        { min: 100, max: 200, suffix: '%' },
-        { min: 0, max: 10 },
-      ],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('$')).toBeTruthy()
-    expect(screen.getByText('1.5')).toBeTruthy()
-    expect(screen.getByText('2.5')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('200')).toBeTruthy()
-    expect(screen.getByText('%')).toBeTruthy()
-    expect(screen.getByText('0')).toBeTruthy()
-    expect(screen.getByText('10')).toBeTruthy()
-  })
-
-  test('renders prefix for each item', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [
-        { min: 1, max: 10, prefix: 'Range 1:' },
-        { min: 20, max: 30, prefix: 'Range 2:' },
-      ],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('Range 1:')).toBeTruthy()
-    expect(screen.getByText('Range 2:')).toBeTruthy()
-  })
-
-  test('renders separator between min and max values', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 5, max: 15 }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    // Check for separator "-"
-    const separators = screen.getAllByText('-')
-    expect(separators.length).toBe(1)
-  })
-
-  test('renders in correct order: Prefix, MinValue, Separator, MaxValue, Suffix', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 10, max: 20, prefix: '$', suffix: 'USD' }],
-    })
-
-    const { container } = render(<SpreadUI id='test-spread' />)
-
-    const items = container.querySelectorAll('.MuiTypography-root')
-    expect(items.length).toBe(5)
-    expect(items[0]?.textContent).toBe('$')
-    expect(items[1]?.textContent).toBe('10')
-    expect(items[2]?.textContent).toBe('-')
-    expect(items[3]?.textContent).toBe('20')
-    expect(items[4]?.textContent).toBe('USD')
-  })
-
-  test('handles data without prefix', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 5, max: 15, suffix: 'km' }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('5')).toBeTruthy()
-    expect(screen.getByText('-')).toBeTruthy()
-    expect(screen.getByText('15')).toBeTruthy()
-    expect(screen.getByText('km')).toBeTruthy()
-  })
-
-  test('handles data without suffix', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 5, max: 15, prefix: '$' }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('$')).toBeTruthy()
-    expect(screen.getByText('5')).toBeTruthy()
-    expect(screen.getByText('-')).toBeTruthy()
-    expect(screen.getByText('15')).toBeTruthy()
-  })
-
-  test('handles data with only min and max values', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 5, max: 15 }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('5')).toBeTruthy()
-    expect(screen.getByText('-')).toBeTruthy()
-    expect(screen.getByText('15')).toBeTruthy()
-  })
-
-  test('handles empty data array', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [],
-    })
-
-    const { container } = render(<SpreadUI id='test-spread' />)
-
-    // Row component returns null for empty data, Box wrapper still rendered
-    expect(container.firstChild?.childNodes.length).toBe(0)
-  })
-
-  test('handles undefined data', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-    })
-
-    const { container } = render(<SpreadUI id='test-spread' />)
-
-    // Row component returns null for undefined data, Box wrapper still rendered
-    expect(container.firstChild?.childNodes.length).toBe(0)
-  })
-
-  test('renders with data containing colors', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [
-        { min: 1, max: 10, color: '#FF0000' },
-        { min: 20, max: 30, color: '#00FF00' },
-      ],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('1')).toBeTruthy()
+describe('<SpreadUI>', () => {
+  it('renders a single min/max pair', () => {
+    render(<SpreadUI items={[{ min: 10, max: 100 }]} />)
     expect(screen.getByText('10')).toBeTruthy()
-    expect(screen.getByText('20')).toBeTruthy()
-    expect(screen.getByText('30')).toBeTruthy()
-  })
-
-  test('renders with negative min value', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: -10, max: 5 }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('-10')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
     expect(screen.getByText('-')).toBeTruthy()
-    expect(screen.getByText('5')).toBeTruthy()
-  })
-
-  test('renders with zero values', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 0, max: 0 }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    const zeros = screen.getAllByText('0')
-    expect(zeros.length).toBe(2) // min and max both are 0
   })
 
-  test('renders with decimal values', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 2.1, max: 2.23, suffix: '€' }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('2.1')).toBeTruthy()
-    expect(screen.getByText('2.23')).toBeTruthy()
-    expect(screen.getByText('€')).toBeTruthy()
-  })
-
-  test('renders with large values', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 1000000, max: 2000000, prefix: '$' }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    expect(screen.getByText('$')).toBeTruthy()
-    expect(screen.getByText('1000000')).toBeTruthy()
-    expect(screen.getByText('2000000')).toBeTruthy()
-  })
-
-  test('updates when widget data changes', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 1, max: 10 }],
-    })
-
-    const { rerender } = render(<SpreadUI id='test-spread' />)
+  it('applies the formatter to both bounds', () => {
+    render(
+      <SpreadUI
+        items={[{ min: 1234, max: 9876 }]}
+        formatter={(n) => n.toLocaleString('en-US')}
+      />,
+    )
+    expect(screen.getByText('1,234')).toBeTruthy()
+    expect(screen.getByText('9,876')).toBeTruthy()
+  })
+
+  it('renders prefix and suffix when provided', () => {
+    render(
+      <SpreadUI
+        items={[{ min: 5, max: 95, prefix: 'Range', suffix: 'kWh' }]}
+      />,
+    )
+    expect(screen.getByText('Range')).toBeTruthy()
+    expect(screen.getByText('kWh')).toBeTruthy()
+  })
+
+  it('renders multiple items as separate rows', () => {
+    render(
+      <SpreadUI
+        items={[
+          { min: 0, max: 100, prefix: 'Q1' },
+          { min: 50, max: 200, prefix: 'Q2' },
+          { min: 100, max: 300, prefix: 'Q3' },
+        ]}
+      />,
+    )
+    expect(screen.getByText('Q1')).toBeTruthy()
+    expect(screen.getByText('Q2')).toBeTruthy()
+    expect(screen.getByText('Q3')).toBeTruthy()
+    // One separator dash per item.
+    expect(screen.getAllByText('-')).toHaveLength(3)
+  })
+
+  it('renders nothing visible when items is empty', () => {
+    const { container } = render(<SpreadUI items={[]} />)
+    expect(container.querySelectorAll('h5').length).toBe(0)
+  })
+
+  it('renders a series avatar with the first letter of the name', () => {
+    render(
+      <SpreadUI
+        items={[
+          { min: 1, max: 9, series: { name: 'Revenue', color: '#1E5BB5' } },
+        ]}
+      />,
+    )
+    expect(screen.getByLabelText('Revenue').textContent).toBe('R')
+  })
+
+  it('renders the note when provided', () => {
+    render(<SpreadUI items={[{ min: 1, max: 9, note: 'Last 7 days' }]} />)
+    expect(screen.getByText('Last 7 days')).toBeTruthy()
+  })
+
+  it('omits series / note when fields are absent', () => {
+    const { container } = render(<SpreadUI items={[{ min: 1, max: 2 }]} />)
+    expect(container.querySelector('.MuiAvatar-root')).toBeNull()
+    expect(container.querySelector('p')).toBeNull()
+  })
+
+  it('renders the row in order: Series → Prefix → Min → — → Max → Suffix', () => {
+    const { container } = render(
+      <SpreadUI
+        items={[
+          {
+            min: 10,
+            max: 20,
+            prefix: '$',
+            suffix: 'USD',
+            series: { name: 'Revenue' },
+          },
+        ]}
+      />,
+    )
+    // h5 / h6 / caption typography variants cover prefix, value, separator, suffix.
+    const typographies = Array.from(
+      container.querySelectorAll('.MuiTypography-root'),
+    ).map((el) => el.textContent ?? '')
+    // The Series avatar is not Typography; we look at the inline-row text.
+    expect(typographies).toEqual(['$', '10', '-', '20', 'USD'])
+  })
+
+  it('still renders both bounds when a per-item color is supplied', () => {
+    // Color threading goes through MUI's `sx` so the runtime inline style
+    // isn't populated in JSDOM — we just check that both bounds render
+    // normally with the color prop set.
+    render(<SpreadUI items={[{ min: 1, max: 2, color: 'success.main' }]} />)
     expect(screen.getByText('1')).toBeTruthy()
-    expect(screen.getByText('10')).toBeTruthy()
-
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      data: [{ min: 20, max: 30 }],
-    })
-
-    rerender(<SpreadUI id='test-spread' />)
-    expect(screen.queryByText('1')).toBeNull()
-    expect(screen.queryByText('10')).toBeNull()
-    expect(screen.getByText('20')).toBeTruthy()
-    expect(screen.getByText('30')).toBeTruthy()
-  })
-
-  test('handles widget removal gracefully', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 1, max: 10 }],
-    })
-
-    const { container, rerender } = render(<SpreadUI id='test-spread' />)
-    expect(screen.getByText('1')).toBeTruthy()
-
-    useWidgetStore.getState().removeWidget('test-spread')
-
-    rerender(<SpreadUI id='test-spread' />)
-    // Box wrapper still rendered but Row returns null
-    expect(container.firstChild?.childNodes.length).toBe(0)
-  })
-
-  test('renders multiple rows for multiple data items', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [
-        { min: 1, max: 10, prefix: 'A' },
-        { min: 20, max: 30, prefix: 'B' },
-        { min: 40, max: 50, prefix: 'C' },
-      ],
-    })
-
-    const { container } = render(<SpreadUI id='test-spread' />)
-
-    // Each data item should create a row
-    const rows = container.querySelectorAll('[class*="MuiBox-root"]')
-    expect(rows.length).toBeGreaterThan(0)
-  })
-
-  test('renders with series configuration', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 10, max: 100, suffix: '€' }],
-      series: [{ name: 'Revenue', color: '#FF5733' }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    // Series should display the first letter of the name
-    expect(screen.getByText('R')).toBeTruthy()
-    expect(screen.getByText('10')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('€')).toBeTruthy()
-  })
-
-  test('renders without series when not provided', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 5, max: 25 }],
-    })
-
-    const { container } = render(<SpreadUI id='test-spread' />)
-
-    // Should not have any Avatar elements (series)
-    const avatars = container.querySelectorAll('.MuiAvatar-root')
-    expect(avatars.length).toBe(0)
-  })
-
-  test('renders series with default color when color not provided', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [{ min: 0, max: 50 }],
-      series: [{ name: 'Test' }],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    // Series should display the first letter
-    expect(screen.getByText('T')).toBeTruthy()
-  })
-
-  test('renders with array of series matching data indices', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [
-        { min: 10, max: 100 },
-        { min: 20, max: 200 },
-        { min: 30, max: 300 },
-      ],
-      series: [
-        { name: 'Alpha', color: '#FF0000' },
-        { name: 'Beta', color: '#00FF00' },
-        { name: 'Gamma', color: '#0000FF' },
-      ],
-    })
-
-    render(<SpreadUI id='test-spread' />)
-
-    // Each series should display its first letter
-    expect(screen.getByText('A')).toBeTruthy()
-    expect(screen.getByText('B')).toBeTruthy()
-    expect(screen.getByText('G')).toBeTruthy()
-  })
-
-  test('renders partial series array - only shows series for available indices', () => {
-    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
-      type: 'spread',
-      data: [
-        { min: 10, max: 100 },
-        { min: 20, max: 200 },
-        { min: 30, max: 300 },
-      ],
-      series: [{ name: 'Only First', color: '#FF0000' }],
-    })
-
-    const { container } = render(<SpreadUI id='test-spread' />)
-
-    // Only one series avatar should be rendered
-    const avatars = container.querySelectorAll('.MuiAvatar-root')
-    expect(avatars.length).toBe(1)
-    expect(screen.getByText('O')).toBeTruthy()
+    expect(screen.getByText('2')).toBeTruthy()
   })
 })

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

@@ -1,32 +1,52 @@
-import type { SpreadUIProps } from './types'
-
-import { Separator } from './components/separator'
-import { MinValue } from './components/min-value'
-import { MaxValue } from './components/max-value'
-import { Prefix, Row, Suffix, Series } from '../formula'
-import { useWidgetRef } from '../../hooks'
 import { Box } from '@mui/material'
+import type { Ref } from 'react'
+import { Note, Prefix, Series, Suffix, Value } from '../formula'
+import { styles } from '../formula/style'
+import { Separator } from './separator'
+import type { SpreadDataItem } from './types'
+
+export interface SpreadUIProps {
+  items: readonly SpreadDataItem[]
+  /** Number formatter — applied to each item's `min` and `max`. */
+  formatter?: (value: number) => string
+  /** Forwarded to the root `<Box>` so consumers can capture the DOM (PNG export). */
+  ref?: Ref<HTMLDivElement>
+}
 
 /**
- * Renders a spread widget displaying min-max value pairs with optional prefixes, suffixes, and series indicators.
+ * Pure presentational component for the Spread widget. Each item renders as
+ * a row containing (in order): optional `Series` avatar, a body with
+ * `[prefix] min — max [suffix]` plus optional `Note`. Reuses the Formula
+ * primitives ({@link Series}, {@link Prefix}, {@link Value}, {@link Suffix},
+ * {@link Note}) and the Formula row styles so Spread and Formula stay
+ * visually aligned when used together.
  */
-export function SpreadUI(props: SpreadUIProps) {
-  const { ref } = useWidgetRef(props.id)
-
+export function SpreadUI({ items, formatter, ref }: SpreadUIProps) {
+  const fmt = formatter ?? ((n: number) => String(n))
   return (
-    <Box ref={ref}>
-      <Row id={props.id}>
-        {({ index }) => (
-          <>
-            <Series id={props.id} index={index} />
-            <Prefix id={props.id} index={index} />
-            <MinValue id={props.id} index={index} />
-            <Separator />
-            <MaxValue id={props.id} index={index} />
-            <Suffix id={props.id} index={index} />
-          </>
-        )}
-      </Row>
+    <Box ref={ref} sx={styles.root}>
+      {items.map((item, i) => (
+        // Composite of series name + min/max bounds for stability across
+        // reorders; falls back to the index when bounds happen to collide.
+        <Box
+          key={`spread-${item.series?.name ?? ''}-${item.min}-${item.max}-${i}`}
+          sx={styles.row}
+        >
+          {item.series ? (
+            <Series name={item.series.name} color={item.series.color} />
+          ) : null}
+          <Box sx={styles.body}>
+            <Box sx={styles.valueRow}>
+              {item.prefix ? <Prefix>{item.prefix}</Prefix> : null}
+              <Value color={item.color}>{fmt(item.min)}</Value>
+              <Separator />
+              <Value color={item.color}>{fmt(item.max)}</Value>
+              {item.suffix ? <Suffix>{item.suffix}</Suffix> : null}
+            </Box>
+            {item.note ? <Note>{item.note}</Note> : null}
+          </Box>
+        </Box>
+      ))}
     </Box>
   )
 }

package/src/widgets/spread/types.ts

@@ -1,47 +1,27 @@
-import type { TypographyProps } from '@mui/material'
-import type { ReactNode } from 'react'
-import type { BaseWidgetState, WidgetsStoreProps } from '../stores/types'
-import type { WrapperState } from '../wrapper/types'
-import type { DownloadItem } from '../actions/download/types'
-import type { SeriesConfig } from '../formula/types'
-
-export interface SpreadUIProps {
-  id: WidgetsStoreProps['id']
-}
-
+import type { FormulaSeries } from '../formula'
+
+/**
+ * A single min/max pair rendered by the Spread widget. Mirrors
+ * {@link FormulaDataItem} — same optional `series`, `prefix`, `suffix`,
+ * `color`, and `note` slots — but the value is a range (`min` … `max`)
+ * rather than a single `value`.
+ */
 export interface SpreadDataItem {
   min: number
   max: number
-  prefix?: string | ReactNode
-  suffix?: string | ReactNode
+  prefix?: string
+  suffix?: string
+  /** Override the values' text colour (e.g. `'success.main'`). */
   color?: string
+  /** Optional series indicator — coloured avatar with first letter of `name`. */
+  series?: FormulaSeries
+  /** Optional caption rendered below the values. */
+  note?: string
 }
 
-export interface RowProps {
-  id: WidgetsStoreProps['id']
-  children: ReactNode | ((props: { index: number }) => ReactNode)
-}
-
-export interface ValueProps extends Omit<ItemProps, 'children'> {
-  id: WidgetsStoreProps['id']
-  index?: number
-}
-
-export interface ItemProps {
-  children: ReactNode
-  disabled?: boolean
-  TypographyProps?: TypographyProps
-}
-
-export type SpreadWidgetData = SpreadDataItem[]
-
-export type SpreadWidgetState = BaseWidgetState<
-  WrapperState<SpreadWidgetConfig> & { data: SpreadWidgetData }
->
-
-export interface SpreadWidgetConfig {
-  formatter?: (value: number) => string
-  series?: SeriesConfig[]
-}
-
-export type SpreadDownloadConfig = DownloadItem<SpreadWidgetData>[]
+/**
+ * Spread widget data — an array of `{min, max, …}` pairs rendered
+ * top-to-bottom, one row per entry. Visual structure matches the Formula
+ * widget so the two can sit side-by-side without style drift.
+ */
+export type SpreadWidgetData = readonly SpreadDataItem[]

package/src/{widgets-v2 → widgets}/state/widget-state.tsx

@@ -113,10 +113,20 @@ function ErrorView({ error, labels }: { error: Error; labels: StateLabels }) {
 function EmptyView({ labels }: { labels: StateLabels }) {
   return (
     <Box sx={styles.emptyRoot}>
-      <Typography variant='body2' color='text.primary'>
+      <Typography
+        variant='body2'
+        sx={{
+          color: 'text.primary',
+        }}
+      >
         {labels.emptyTitle}
       </Typography>
-      <Typography variant='caption' color='text.secondary'>
+      <Typography
+        variant='caption'
+        sx={{
+          color: 'text.secondary',
+        }}
+      >
         {labels.emptyDescription}
       </Typography>
     </Box>
@@ -142,7 +152,7 @@ class RenderErrorBoundary extends Component<BoundaryProps, BoundaryState> {
 
   override componentDidCatch(error: Error): void {
     // eslint-disable-next-line no-console
-    console.error('[widgets-v2] Render error in <Widget.State> child:', error)
+    console.error('[widgets] Render error in <Widget.State> child:', error)
   }
 
   override render(): ReactNode {