@carto/ps-react-ui 4.7.1 → 4.8.0

package/src/widgets-v2/formula/download.test.tsx

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createFormulaDownloadConfig } from './download'
+import type { FormulaWidgetData } from './types'
+
+let csvText = ''
+
+beforeEach(() => {
+  csvText = ''
+  vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock')
+  vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => undefined)
+  const RealBlob = global.Blob
+  vi.stubGlobal(
+    'Blob',
+    class extends RealBlob {
+      constructor(parts: BlobPart[], opts?: BlobPropertyBag) {
+        csvText = typeof parts[0] === 'string' ? parts[0] : ''
+        super(parts, opts)
+      }
+    },
+  )
+})
+
+describe('createFormulaDownloadConfig', () => {
+  it('CSV-only by default', () => {
+    const items = createFormulaDownloadConfig({
+      filename: 'f',
+      getData: () => [{ value: 1 }],
+    })
+    expect(items.map((i) => i.id)).toEqual(['csv'])
+    expect(items[0]?.label).toBe('CSV')
+    expect(items[0]?.icon).toBeTruthy()
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createFormulaDownloadConfig({
+      filename: 'f',
+      getData: () => [],
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+  })
+
+  it('CSV resolve serialises all optional fields, defaulting blanks', async () => {
+    const data: FormulaWidgetData = [
+      {
+        value: 42,
+        prefix: '$',
+        suffix: 'k',
+        note: 'q1',
+        series: { name: 'Rev' },
+        delta: { value: 12 },
+      },
+      { value: 10 },
+    ]
+    const items = createFormulaDownloadConfig({
+      filename: 'f',
+      getData: () => data,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('f.csv')
+    expect(csvText).toBe(
+      'series,prefix,value,suffix,note,delta\nRev,$,42,k,q1,12\n,,10,,,',
+    )
+  })
+})

package/src/widgets-v2/formula/download.tsx

@@ -0,0 +1,69 @@
+import {
+  CSVIcon,
+  buildPngDownloadItem,
+  downloadToCSV,
+  type DownloadItem,
+} from '../actions/download'
+import type { FormulaWidgetData } from './types'
+
+export interface FormulaDownloadConfigArgs {
+  filename: string
+  getData: () => FormulaWidgetData
+  /**
+   * Optional getter for the widget's capture element (registered by
+   * `Widget.State`). When provided, a PNG item is prepended.
+   */
+  getCaptureEl?: () => HTMLElement | null
+  pngPixelRatio?: number
+  pngBackgroundColor?: string | null
+}
+
+/**
+ * Builds download items for the Formula widget. Always includes a CSV item
+ * with one row per KPI (`prefix`, `value`, `suffix`, `note`, `delta`).
+ * When `getCaptureEl` is supplied, prepends a PNG item that rasterises the
+ * captured element via `html2canvas`.
+ */
+export function createFormulaDownloadConfig(
+  args: FormulaDownloadConfigArgs,
+): DownloadItem[] {
+  const items: DownloadItem[] = []
+  if (args.getCaptureEl) {
+    items.push(
+      buildPngDownloadItem({
+        filename: args.filename,
+        getCaptureEl: args.getCaptureEl,
+        pixelRatio: args.pngPixelRatio,
+        backgroundColor: args.pngBackgroundColor,
+      }),
+    )
+  }
+  items.push({
+    id: 'csv',
+    label: 'CSV',
+    icon: <CSVIcon fontSize='small' />,
+    resolve: () => {
+      const data = args.getData()
+      const rows: unknown[][] = [
+        ['series', 'prefix', 'value', 'suffix', 'note', 'delta'],
+      ]
+      for (const d of data) {
+        rows.push([
+          d.series?.name ?? '',
+          d.prefix ?? '',
+          d.value,
+          d.suffix ?? '',
+          d.note ?? '',
+          d.delta?.value ?? '',
+        ])
+      }
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  return items
+}

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

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { FormulaUI } from './formula-ui'
+
+describe('<FormulaUI>', () => {
+  it('renders a single KPI value', () => {
+    render(<FormulaUI items={[{ value: 1234 }]} />)
+    expect(screen.getByText('1234')).toBeTruthy()
+  })
+
+  it('applies a formatter to the value', () => {
+    render(
+      <FormulaUI
+        items={[{ value: 1234 }]}
+        formatter={(n) => `$${n.toLocaleString('en-US')}`}
+      />,
+    )
+    expect(screen.getByText('$1,234')).toBeTruthy()
+  })
+
+  it('renders prefix and suffix when provided', () => {
+    render(<FormulaUI items={[{ value: 99, prefix: 'USD', suffix: '/mo' }]} />)
+    expect(screen.getByText('USD')).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()
+    expect(screen.getByText('25')).toBeTruthy()
+    expect(screen.getByText('75')).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)
+  })
+
+  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')
+  })
+
+  it('renders the note when provided', () => {
+    render(<FormulaUI items={[{ value: 1, note: 'Last 7 days' }]} />)
+    expect(screen.getByText('Last 7 days')).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()
+  })
+
+  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()
+  })
+
+  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-v2/formula/formula-ui.tsx

@@ -0,0 +1,66 @@
+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>
+}
+
+/**
+ * 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({ items, formatter, ref }: FormulaUIProps) {
+  return (
+    <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-v2/formula/formula.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import { Formula } from './formula'
+import { Provider } from '../provider/widget-provider'
+import type { FormulaWidgetData } from './types'
+
+vi.mock('./formula-ui', () => ({
+  FormulaUI: ({
+    items,
+    formatter,
+  }: {
+    items: FormulaWidgetData
+    formatter?: (value: number) => string
+  }) => (
+    <div data-testid='formula-ui' data-count={items.length}>
+      {items
+        .map(
+          (it) =>
+            `${it.prefix ?? ''}${formatter ? formatter(it.value) : it.value}${it.suffix ?? ''}`,
+        )
+        .join('|')}
+    </div>
+  ),
+}))
+
+describe('<Formula> bridge', () => {
+  it('forwards data + formatter from the store to FormulaUI', () => {
+    const data: FormulaWidgetData = [
+      { value: 12, prefix: '$' },
+      { value: 34, suffix: '%' },
+    ]
+    const { getByTestId } = render(
+      <Provider id='f-1' data={data} formatter={(n) => `[${n.toFixed(1)}]`}>
+        <Formula />
+      </Provider>,
+    )
+    const ui = getByTestId('formula-ui')
+    expect(ui.dataset.count).toBe('2')
+    expect(ui.textContent).toBe('$[12.0]|[34.0]%')
+  })
+
+  it('falls back to an empty items array when data is null', () => {
+    const { getByTestId } = render(
+      <Provider id='f-2' data={null}>
+        <Formula />
+      </Provider>,
+    )
+    expect(getByTestId('formula-ui').dataset.count).toBe('0')
+  })
+})

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

@@ -0,0 +1,34 @@
+import { useWidgetId, useWidgetShallow } from '../stores'
+import { FormulaUI } from './formula-ui'
+import type { FormulaWidgetData } from './types'
+
+interface FormulaSlice {
+  data: FormulaWidgetData
+  formatter?: (value: number) => string
+}
+
+// Stable empty-data sentinel — keeps the slice's `data` reference stable
+// when the underlying store value is null/undefined so the shallow-equality
+// gate in `useWidgetShallow` doesn't re-render every commit.
+const EMPTY_DATA: FormulaWidgetData = Object.freeze([]) as FormulaWidgetData
+
+const formulaSelector = (s: {
+  data: unknown
+  formatter?: (value: number) => string
+}): FormulaSlice => ({
+  data: (s.data ?? EMPTY_DATA) as FormulaWidgetData,
+  formatter: s.formatter,
+})
+
+/**
+ * Stateful Formula bridge — reads `data` (post-pipeline) and `formatter` from
+ * the per-widget store and forwards them to the pure {@link FormulaUI}. Sits
+ * inside `<Widget.Provider>`. Demonstrates that the composition shell
+ * (Provider, Wrapper, State) doesn't care whether the rendered child is
+ * ECharts (Bar) or a custom DOM tree (Formula).
+ */
+export function Formula() {
+  const id = useWidgetId()
+  const slice = useWidgetShallow(id, formulaSelector)
+  return <FormulaUI items={slice.data} formatter={slice.formatter} />
+}

package/src/widgets-v2/formula/index.ts

@@ -0,0 +1,17 @@
+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 {
+  FormulaDataItem,
+  FormulaWidgetData,
+  FormulaSeries,
+  FormulaDelta,
+  DeltaSeverity,
+} from './types'

package/src/widgets-v2/formula/note.tsx

@@ -0,0 +1,25 @@
+import { Typography, type TypographyProps } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export interface NoteProps {
+  children: ReactNode
+  TypographyProps?: TypographyProps
+}
+
+/**
+ * Small subdued caption rendered below a Formula value. Use for short
+ * descriptive text (e.g. "Last 7 days", "Excludes refunds").
+ */
+export function Note({ children, TypographyProps }: NoteProps) {
+  return (
+    <Typography
+      variant='caption'
+      component='p'
+      color='text.secondary'
+      sx={{ m: 0 }}
+      {...TypographyProps}
+    >
+      {children}
+    </Typography>
+  )
+}

package/src/widgets-v2/formula/prefix.tsx

@@ -0,0 +1,25 @@
+import { Typography, type TypographyProps } from '@mui/material'
+import type { ReactNode } from 'react'
+
+export interface PrefixProps {
+  children: ReactNode
+  TypographyProps?: TypographyProps
+}
+
+/**
+ * Prefix slot for a Formula KPI — large, bold, muted (`text.secondary`).
+ * Composable building block for custom formula layouts; the canonical
+ * {@link FormulaUI} renders one of these per item when `prefix` is set.
+ */
+export function Prefix({ children, TypographyProps }: PrefixProps) {
+  return (
+    <Typography
+      variant='h5'
+      component='span'
+      sx={{ fontWeight: 600, color: 'text.secondary', lineHeight: 1 }}
+      {...TypographyProps}
+    >
+      {children}
+    </Typography>
+  )
+}

package/src/widgets-v2/formula/series.tsx

@@ -0,0 +1,67 @@
+import { Avatar, type AvatarProps, type Theme } from '@mui/material'
+
+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
+  /** Diameter in px. Default `24`. */
+  size?: number
+  AvatarProps?: AvatarProps
+}
+
+/**
+ * Series indicator — circular avatar showing the first letter of `name`.
+ * Background colour is `color` (consumer-supplied) or a neutral disabled
+ * colour, with text colour computed for contrast against it.
+ */
+export function Series({
+  name,
+  color,
+  size = 24,
+  AvatarProps: avatarProps,
+}: SeriesProps) {
+  const letter = name.charAt(0).toUpperCase()
+  return (
+    <Avatar
+      aria-label={name}
+      sx={{
+        width: size,
+        height: size,
+        fontSize: size * 0.5,
+        fontWeight: 600,
+        bgcolor: color ?? 'action.disabledBackground',
+        color: color
+          ? (theme: Theme) =>
+              theme.palette.getContrastText(toCssColor(theme, color))
+          : 'text.primary',
+      }}
+      {...avatarProps}
+    >
+      {letter}
+    </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
+}

package/src/widgets-v2/formula/skeleton.test.tsx

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { FormulaSkeleton } from './skeleton'
+
+describe('<FormulaSkeleton>', () => {
+  it('renders the default single-row skeleton', () => {
+    const { container } = render(<FormulaSkeleton />)
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThan(0)
+  })
+
+  it('renders multiple rows when count > 1', () => {
+    const { container } = render(<FormulaSkeleton count={3} />)
+    expect(container.firstChild).not.toBeNull()
+    // Per-row Skeletons must scale with count.
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThan(1)
+  })
+})

package/src/widgets-v2/formula/skeleton.tsx

@@ -0,0 +1,27 @@
+import { Box, Skeleton } from '@mui/material'
+import type { SxProps, Theme } from '@mui/material'
+
+const styles = {
+  root: {
+    display: 'flex',
+    gap: 3,
+    alignItems: 'baseline',
+    minHeight: 64,
+    py: 1,
+  },
+  block: { width: 120, height: 36 },
+} satisfies Record<string, SxProps<Theme>>
+
+export interface FormulaSkeletonProps {
+  count?: number
+}
+
+export function FormulaSkeleton({ count = 1 }: FormulaSkeletonProps) {
+  return (
+    <Box sx={styles.root}>
+      {Array.from({ length: count }).map((_, i) => (
+        <Skeleton key={`row-${i}`} variant='rectangular' sx={styles.block} />
+      ))}
+    </Box>
+  )
+}

package/src/widgets-v2/formula/style.ts

@@ -0,0 +1,31 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+    alignItems: 'stretch',
+  },
+  row: {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: 1.5,
+  },
+  body: {
+    flex: 1,
+    minWidth: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 0.25,
+  },
+  valueRow: {
+    display: 'inline-flex',
+    alignItems: 'baseline',
+    gap: 0.25,
+  },
+  delta: {
+    alignSelf: 'center',
+    flexShrink: 0,
+  },
+} satisfies Record<string, SxProps<Theme>>