@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,399 +1,91 @@
-import { describe, test, expect, beforeEach } from 'vitest'
+import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { FormulaUI } from './formula-ui'
-import { useWidgetStore } from '../stores/widget-store'
-import type { FormulaWidgetState } from './types'
 
-describe('FormulaUI', () => {
-  beforeEach(() => {
-    useWidgetStore.getState().clearWidgets()
+describe('<FormulaUI>', () => {
+  it('renders a single KPI value', () => {
+    render(<FormulaUI items={[{ value: 1234 }]} />)
+    expect(screen.getByText('1234')).toBeTruthy()
   })
 
-  test('renders empty container when widget does not exist', () => {
-    const { container } = render(<FormulaUI id='non-existent' />)
-    // Box wrapper is rendered but Row returns null for missing widget
-    expect(container.firstChild?.childNodes.length).toBe(0)
+  it('applies a formatter to the value', () => {
+    render(
+      <FormulaUI
+        items={[{ value: 1234 }]}
+        formatter={(n) => `$${n.toLocaleString('en-US')}`}
+      />,
+    )
+    expect(screen.getByText('$1,234')).toBeTruthy()
   })
 
-  test('renders with single data item', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100, prefix: '$', suffix: 'USD' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('$')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('USD')).toBeTruthy()
-  })
-
-  test('renders with multiple data items', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, prefix: '$' },
-        { value: 200, suffix: '%' },
-        { value: 300 },
-      ],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('$')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('200')).toBeTruthy()
-    expect(screen.getByText('%')).toBeTruthy()
-    expect(screen.getByText('300')).toBeTruthy()
-  })
-
-  test('renders Prefix component for each item', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, prefix: 'Item 1:' },
-        { value: 200, prefix: 'Item 2:' },
-      ],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('Item 1:')).toBeTruthy()
-    expect(screen.getByText('Item 2:')).toBeTruthy()
-  })
-
-  test('renders Value component for each item', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100 }, { value: 200 }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('200')).toBeTruthy()
-  })
-
-  test('renders Suffix component for each item', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, suffix: 'units' },
-        { value: 200, suffix: 'items' },
-      ],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('units')).toBeTruthy()
-    expect(screen.getByText('items')).toBeTruthy()
-  })
-
-  test('renders in correct order: Prefix, Value, Suffix', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100, prefix: '$', suffix: 'USD' }],
-    })
-
-    const { container } = render(<FormulaUI id='test-formula' />)
-
-    const items = container.querySelectorAll('.MuiTypography-root')
-    expect(items.length).toBe(3)
-    expect(items[0]?.textContent).toBe('$')
-    expect(items[1]?.textContent).toBe('100')
-    expect(items[2]?.textContent).toBe('USD')
-  })
-
-  test('handles data without prefix', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100, suffix: 'USD' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.queryByText('$')).toBeNull()
-    expect(screen.getByText('100')).toBeTruthy()
+  it('renders prefix and suffix when provided', () => {
+    render(<FormulaUI items={[{ value: 99, prefix: 'USD', suffix: '/mo' }]} />)
     expect(screen.getByText('USD')).toBeTruthy()
-  })
-
-  test('handles data without suffix', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100, prefix: '$' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('$')).toBeTruthy()
+    expect(screen.getByText('99')).toBeTruthy()
+    expect(screen.getByText('/mo')).toBeTruthy()
+  })
+
+  it('renders multiple items side-by-side', () => {
+    render(
+      <FormulaUI
+        items={[
+          { value: 100, suffix: 'rev' },
+          { value: 25, suffix: 'cogs' },
+          { value: 75, suffix: 'gp' },
+        ]}
+      />,
+    )
     expect(screen.getByText('100')).toBeTruthy()
-    // Suffix should not be rendered
-    const items = screen.queryAllByText('USD')
-    expect(items.length).toBe(0)
+    expect(screen.getByText('25')).toBeTruthy()
+    expect(screen.getByText('75')).toBeTruthy()
   })
 
-  test('handles data with only value', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100 }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('100')).toBeTruthy()
+  it('renders nothing visible when items is empty', () => {
+    const { container } = render(<FormulaUI items={[]} />)
+    // Root <Box> exists, but it has no item children.
+    expect(container.querySelectorAll('[role]').length).toBe(0)
   })
 
-  test('handles empty data array', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [],
-    })
-
-    const { container } = render(<FormulaUI id='test-formula' />)
-
-    // Row component returns null for empty data, Box wrapper still rendered
-    expect(container.firstChild?.childNodes.length).toBe(0)
+  it('renders a series avatar with the first letter of the name', () => {
+    render(
+      <FormulaUI
+        items={[{ value: 1, series: { name: 'Revenue', color: '#1E5BB5' } }]}
+      />,
+    )
+    expect(screen.getByLabelText('Revenue').textContent).toBe('R')
   })
 
-  test('handles undefined data', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-    })
-
-    const { container } = render(<FormulaUI id='test-formula' />)
-
-    // Row component returns null for undefined data, Box wrapper still rendered
-    expect(container.firstChild?.childNodes.length).toBe(0)
+  it('renders the note when provided', () => {
+    render(<FormulaUI items={[{ value: 1, note: 'Last 7 days' }]} />)
+    expect(screen.getByText('Last 7 days')).toBeTruthy()
   })
 
-  test('passes correct index to child components', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, prefix: 'First' },
-        { value: 200, prefix: 'Second' },
-        { value: 300, prefix: 'Third' },
-      ],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('First')).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('Second')).toBeTruthy()
-    expect(screen.getByText('200')).toBeTruthy()
-    expect(screen.getByText('Third')).toBeTruthy()
-    expect(screen.getByText('300')).toBeTruthy()
+  it('renders a delta chip with severity-based styling', () => {
+    const { container } = render(
+      <FormulaUI items={[{ value: 1, delta: { value: -0.123 } }]} />,
+    )
+    // MUI's `severity='error'` → `MuiChip-colorError` class.
+    expect(container.querySelector('.MuiChip-colorError')).toBeTruthy()
   })
 
-  test('renders with data containing colors', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, color: '#FF0000' },
-        { value: 200, color: '#00FF00' },
-      ],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('200')).toBeTruthy()
+  it('uses the explicit delta label when provided', () => {
+    render(
+      <FormulaUI
+        items={[
+          {
+            value: 1,
+            delta: { value: 0.05, label: 'better than yesterday' },
+          },
+        ]}
+      />,
+    )
+    expect(screen.getByText('better than yesterday')).toBeTruthy()
   })
 
-  test('renders with negative values', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: -100, prefix: '-' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('-')).toBeTruthy()
-    expect(screen.getByText('-100')).toBeTruthy()
-  })
-
-  test('renders with zero value', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 0 }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('0')).toBeTruthy()
-  })
-
-  test('renders with decimal values', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 123.456, suffix: 'km' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('123.456')).toBeTruthy()
-    expect(screen.getByText('km')).toBeTruthy()
-  })
-
-  test('renders with large values', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 1000000000, prefix: '$' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('$')).toBeTruthy()
-    expect(screen.getByText('1000000000')).toBeTruthy()
-  })
-
-  test('updates when widget data changes', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100 }],
-    })
-
-    const { rerender } = render(<FormulaUI id='test-formula' />)
-    expect(screen.getByText('100')).toBeTruthy()
-
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      data: [{ value: 200 }],
-    })
-
-    rerender(<FormulaUI id='test-formula' />)
-    expect(screen.queryByText('100')).toBeNull()
-    expect(screen.getByText('200')).toBeTruthy()
-  })
-
-  test('handles widget removal gracefully', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100 }],
-    })
-
-    const { container, rerender } = render(<FormulaUI id='test-formula' />)
-    expect(screen.getByText('100')).toBeTruthy()
-
-    useWidgetStore.getState().removeWidget('test-formula')
-
-    rerender(<FormulaUI id='test-formula' />)
-    // Box wrapper still rendered but Row returns null
-    expect(container.firstChild?.childNodes.length).toBe(0)
-  })
-
-  test('renders with empty string prefix', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100, prefix: '' }],
-    })
-
-    const { container } = render(<FormulaUI id='test-formula' />)
-
-    // Empty prefix should not render
-    expect(container.firstChild).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-  })
-
-  test('renders with empty string suffix', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100, suffix: '' }],
-    })
-
-    const { container } = render(<FormulaUI id='test-formula' />)
-
-    // Empty suffix should not render
-    expect(container.firstChild).toBeTruthy()
-    expect(screen.getByText('100')).toBeTruthy()
-  })
-
-  test('renders multiple rows for multiple data items', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, prefix: 'A' },
-        { value: 200, prefix: 'B' },
-        { value: 300, prefix: 'C' },
-      ],
-    })
-
-    const { container } = render(<FormulaUI id='test-formula' />)
-
-    // Each data item should create a row
-    const rows = container.querySelectorAll('[class*="MuiBox-root"]')
-    expect(rows.length).toBeGreaterThan(0)
-  })
-
-  test('renders with single series in array', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100, suffix: 'units' }],
-      series: [{ name: 'Category A' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('C')).toBeTruthy() // Avatar shows first letter
-    expect(screen.getByText('100')).toBeTruthy()
-  })
-
-  test('renders with series and custom color', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [{ value: 100 }],
-      series: [{ name: 'Sales', color: '#FF0000' }],
-    })
-
-    const { container } = render(<FormulaUI id='test-formula' />)
-
-    const avatar = container.querySelector('.MuiAvatar-root')
-    expect(avatar).toBeTruthy()
-    expect(screen.getByText('S')).toBeTruthy() // First letter of 'Sales'
-  })
-
-  test('renders with array of series matching data indices', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, suffix: 'units' },
-        { value: 200, suffix: 'items' },
-        { value: 300, suffix: 'pieces' },
-      ],
-      series: [
-        { name: 'Alpha', color: '#FF0000' },
-        { name: 'Beta', color: '#00FF00' },
-        { name: 'Gamma', color: '#0000FF' },
-      ],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    expect(screen.getByText('A')).toBeTruthy() // Alpha
-    expect(screen.getByText('B')).toBeTruthy() // Beta
-    expect(screen.getByText('G')).toBeTruthy() // Gamma
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('200')).toBeTruthy()
-    expect(screen.getByText('300')).toBeTruthy()
-  })
-
-  test('renders partial series array - only shows series for available indices', () => {
-    useWidgetStore.getState().setWidget<FormulaWidgetState>('test-formula', {
-      type: 'formula',
-      data: [
-        { value: 100, suffix: 'units' },
-        { value: 200, suffix: 'items' },
-        { value: 300, suffix: 'pieces' },
-      ],
-      series: [{ name: 'Only First', color: '#FF0000' }],
-    })
-
-    render(<FormulaUI id='test-formula' />)
-
-    // Only first row should have series avatar
-    expect(screen.getByText('O')).toBeTruthy() // Only First
-    expect(screen.getByText('100')).toBeTruthy()
-    expect(screen.getByText('200')).toBeTruthy()
-    expect(screen.getByText('300')).toBeTruthy()
+  it('omits avatar / note / delta when fields are absent', () => {
+    const { container } = render(<FormulaUI items={[{ value: 42 }]} />)
+    expect(container.querySelector('[role="img"]')).toBeNull()
+    expect(container.querySelector('.MuiChip-root')).toBeNull()
+    expect(container.querySelector('p')).toBeNull()
   })
 })

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

@@ -1,30 +1,66 @@
-import type { FormulaUIProps } from './types'
-import { Row } from './components/row'
-import { Value } from './components/value'
-import { Prefix } from './components/prefix'
-import { Suffix } from './components/suffix'
-import { Series } from './components/series'
-import { useWidgetRef } from '../../hooks'
 import { Box } from '@mui/material'
+import type { Ref } from 'react'
+import type { FormulaDataItem } from './types'
+import { Delta } from './delta'
+import { Note } from './note'
+import { Prefix } from './prefix'
+import { Series } from './series'
+import { Suffix } from './suffix'
+import { Value } from './value'
+import { styles } from './style'
+
+export interface FormulaUIProps {
+  items: readonly FormulaDataItem[]
+  /** Number formatter — applied to each item's `value`. */
+  formatter?: (value: number) => string
+  /** Forwarded to the root `<Box>` so consumers can capture the DOM (PNG export). */
+  ref?: Ref<HTMLDivElement>
+}
 
 /**
- * Renders a formula widget displaying one or more KPI values with optional prefixes, suffixes, and series indicators.
+ * Pure presentational component for the Formula widget. Each item renders as
+ * a row containing (in order): optional `Series` avatar, a body with
+ * `[prefix] value [suffix]` plus optional `Note`, and an optional `Delta`
+ * chip pushed to the right edge.
+ *
+ * For fully custom layouts, compose {@link Series}, {@link Prefix},
+ * {@link Value}, {@link Suffix}, {@link Note}, and {@link Delta} directly
+ * instead of passing `items`.
  */
-export function FormulaUI(props: FormulaUIProps) {
-  const { ref } = useWidgetRef(props.id)
-
+export function FormulaUI({ items, formatter, ref }: FormulaUIProps) {
   return (
-    <Box ref={ref}>
-      <Row id={props.id}>
-        {({ index }) => (
-          <>
-            <Series id={props.id} index={index} />
-            <Prefix id={props.id} index={index} />
-            <Value id={props.id} index={index} />
-            <Suffix id={props.id} index={index} />
-          </>
-        )}
-      </Row>
+    <Box ref={ref} sx={styles.root}>
+      {items.map((item, i) => (
+        // Series name is the closest stable id; fall back to the literal
+        // value (numeric KPIs rarely repeat with the same prefix/suffix).
+        <Box
+          key={`formula-${item.series?.name ?? `${item.prefix ?? ''}${item.value}${item.suffix ?? ''}`}-${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}>
+                {formatter ? formatter(item.value) : String(item.value)}
+              </Value>
+              {item.suffix ? <Suffix>{item.suffix}</Suffix> : null}
+            </Box>
+            {item.note ? <Note>{item.note}</Note> : null}
+          </Box>
+          {item.delta ? (
+            <Box sx={styles.delta}>
+              <Delta
+                value={item.delta.value}
+                label={item.delta.label}
+                severity={item.delta.severity}
+              />
+            </Box>
+          ) : null}
+        </Box>
+      ))}
     </Box>
   )
 }

package/src/widgets/formula/index.ts

@@ -1,24 +1,17 @@
-export { Item } from './components/item'
-export { Value } from './components/value'
-export { Prefix } from './components/prefix'
-export { Suffix } from './components/suffix'
-export { Series } from './components/series'
-export { Row } from './components/row'
-
-export { formulaConfig, formulaDownloadConfig } from './config'
-export { FormulaUI } from './formula-ui'
-export { FormulaSkeleton } from './skeleton'
-export { sanitizeDataItem, sanitizeDataItems } from './serializer'
-
+export { Formula } from './formula'
+export { FormulaUI, type FormulaUIProps } from './formula-ui'
+export { Prefix, type PrefixProps } from './prefix'
+export { Suffix, type SuffixProps } from './suffix'
+export { Value, type ValueProps } from './value'
+export { Series, type SeriesProps } from './series'
+export { Note, type NoteProps } from './note'
+export { Delta, type DeltaProps } from './delta'
+export { FormulaSkeleton, type FormulaSkeletonProps } from './skeleton'
+export { createFormulaDownloadConfig } from './download'
 export type {
-  DataItem,
-  FormulaDownloadConfig,
-  FormulaUIProps,
-  FormulaWidgetConfig,
+  FormulaDataItem,
   FormulaWidgetData,
-  FormulaWidgetState,
-  ItemProps,
-  RowProps,
-  SeriesConfig,
-  ValueProps,
+  FormulaSeries,
+  FormulaDelta,
+  DeltaSeverity,
 } from './types'

package/src/{widgets-v2 → widgets}/formula/note.tsx

@@ -1,5 +1,6 @@
 import { Typography, type TypographyProps } from '@mui/material'
 import type { ReactNode } from 'react'
+import { mergeSx } from '../../components/lasso-tool/styles'
 
 export interface NoteProps {
   children: ReactNode
@@ -15,9 +16,14 @@ export function Note({ children, TypographyProps }: NoteProps) {
     <Typography
       variant='caption'
       component='p'
-      color='text.secondary'
-      sx={{ m: 0 }}
       {...TypographyProps}
+      sx={mergeSx(
+        {
+          color: 'text.secondary',
+          m: 0,
+        },
+        TypographyProps?.sx,
+      )}
     >
       {children}
     </Typography>

package/src/{widgets-v2 → widgets}/formula/series.tsx

@@ -1,10 +1,12 @@
 import { Avatar, type AvatarProps, type Theme } from '@mui/material'
+import type { PaletteColor } from '../../components/types'
+import { resolveThemeColor } from '../utils'
 
 export interface SeriesProps {
   /** Used for the avatar's first-letter glyph and as accessible label. */
   name: string
   /** Avatar background colour (any MUI palette path or CSS colour). */
-  color?: string
+  color?: PaletteColor
   /** Diameter in px. Default `24`. */
   size?: number
   AvatarProps?: AvatarProps
@@ -31,9 +33,13 @@ export function Series({
         fontSize: size * 0.5,
         fontWeight: 600,
         bgcolor: color ?? 'action.disabledBackground',
+        // `getContrastText` needs a concrete colour, so the palette path is
+        // resolved here even though `bgcolor` above takes it as it comes.
         color: color
           ? (theme: Theme) =>
-              theme.palette.getContrastText(toCssColor(theme, color))
+              theme.palette.getContrastText(
+                resolveThemeColor(theme, color) ?? color,
+              )
           : 'text.primary',
       }}
       {...avatarProps}
@@ -42,26 +48,3 @@ export function Series({
     </Avatar>
   )
 }
-
-/**
- * Resolve a palette path (e.g. `"primary.main"`) to a hex/rgb string so that
- * `getContrastText` — which doesn't accept dotted paths — produces a sensible
- * text colour. Non-palette strings (raw `#hex`, `rgb(...)`) pass through.
- */
-function toCssColor(theme: Theme, value: string): string {
-  if (!value.includes('.')) return value
-  const parts = value.split('.')
-  let cur: unknown = theme.palette
-  for (const p of parts) {
-    if (
-      cur &&
-      typeof cur === 'object' &&
-      p in (cur as Record<string, unknown>)
-    ) {
-      cur = (cur as Record<string, unknown>)[p]
-    } else {
-      return value
-    }
-  }
-  return typeof cur === 'string' ? cur : value
-}