@carto/ps-react-ui 4.7.1 → 4.8.0

package/src/widgets-v2/scatterplot/types.ts

@@ -0,0 +1,55 @@
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+
+/** A single point — `[x, y]` tuple. */
+export type ScatterplotDatum = readonly [number, number]
+
+/** Scatterplot widget data — array of series, each a list of `[x, y]` tuples. */
+export type ScatterplotWidgetData = readonly (readonly ScatterplotDatum[])[]
+
+/** Inputs to the structural-only {@link scatterplotOptions} builder. */
+export interface ScatterplotOptionsInput {
+  theme: Theme
+  /** Optional formatter for x-axis values. */
+  xFormatter?: (value: number) => string
+  /** Optional formatter for y-axis values. */
+  yFormatter?: (value: number) => string
+}
+
+/**
+ * Combined inputs for the scatterplot option factory creator. Carries
+ * everything the widget needs across BOTH phases — the structural-build
+ * (`theme`, `xFormatter`, `yFormatter`, `optionsOverride`) AND the data
+ * merge (`seriesNames`, `symbolSize`, `selection`).
+ */
+export interface ScatterplotOptionFactoryInput {
+  theme: Theme
+  /**
+   * Optional x-axis value formatter. Drives the structural x-axis
+   * label and the reactive tooltip path: when RelativeData overrides
+   * `state.formatter` (the y formatter) the merger rebuilds the tooltip
+   * and reads `xFormatter` to render coordinates correctly. xFormatter
+   * itself isn't relativized — x stays raw.
+   */
+  xFormatter?: (value: number) => string
+  /** Optional formatter for y-axis values (structural baseline). */
+  yFormatter?: (value: number) => string
+  /** Series names — drives the legend and `series[i].name`. */
+  seriesNames?: readonly string[]
+  /** Symbol size in px (default `8`). */
+  symbolSize?: number
+  /**
+   * Selected point keys, one per `${seriesIndex}:${dataIndex}` pair. Points
+   * not in this list render dimmed (`itemStyle.opacity: 0.15`). `null`/empty
+   * means no selection.
+   */
+  selection?: readonly string[] | null
+  /**
+   * Consumer-supplied partial option merged into the structural option at
+   * structural-build time. Lets stories override pieces of the theme-aware
+   * base without forking the structural builder.
+   */
+  optionsOverride?: Partial<EChartsOption>
+}
+
+export type ScatterplotEChartsOption = EChartsOption

package/src/widgets-v2/selection-summary/labels.ts

@@ -0,0 +1,11 @@
+export interface SelectionSummaryLabels {
+  allSelected: string
+  selections: (count: number) => string
+  clear: string
+}
+
+export const DEFAULT_SELECTION_SUMMARY_LABELS: SelectionSummaryLabels = {
+  allSelected: 'All selected',
+  selections: (count) => `${count} selected`,
+  clear: 'Clear',
+}

package/src/widgets-v2/selection-summary/selection-summary.test.tsx

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import StarIcon from '@mui/icons-material/Star'
+import { SelectionSummary } from './selection-summary'
+
+describe('<SelectionSummary>', () => {
+  it('renders nothing when total === 0 (no data to summarize)', () => {
+    const { container } = render(<SelectionSummary count={0} total={0} />)
+    expect(container.textContent).toBe('')
+  })
+
+  it('renders the "All selected" label when count === 0 and total > 0 (R34)', () => {
+    render(<SelectionSummary count={0} total={10} />)
+    expect(screen.getByText('All selected')).toBeTruthy()
+  })
+
+  it('renders the count + Clear link when count > 0', () => {
+    const onClear = vi.fn()
+    render(<SelectionSummary count={3} total={10} onClear={onClear} />)
+    expect(screen.getByText(/3/)).toBeTruthy()
+    fireEvent.click(screen.getByText('Clear'))
+    expect(onClear).toHaveBeenCalledTimes(1)
+  })
+
+  it('hides the Clear link when no onClear is provided', () => {
+    render(<SelectionSummary count={3} total={10} />)
+    expect(screen.queryByText('Clear')).toBeNull()
+  })
+
+  it('honors custom labels for empty + populated + clear', () => {
+    render(
+      <SelectionSummary
+        count={3}
+        total={10}
+        labels={{
+          allSelected: 'Showing all',
+          selections: (n) => `${n} pinned`,
+          clear: 'Reset',
+        }}
+        onClear={() => undefined}
+      />,
+    )
+    expect(screen.getByText('3 pinned')).toBeTruthy()
+    expect(screen.getByText('Reset')).toBeTruthy()
+  })
+
+  it('renders the custom icon component when provided in the empty state', () => {
+    const { container } = render(
+      <SelectionSummary count={0} total={10} icon={StarIcon} />,
+    )
+    expect(container.querySelector('[data-testid="StarIcon"]')).toBeTruthy()
+  })
+})

package/src/widgets-v2/selection-summary/selection-summary.tsx

@@ -0,0 +1,62 @@
+import { Box, Button, Typography, type SvgIconProps } from '@mui/material'
+import type { ComponentType } from 'react'
+import {
+  DEFAULT_SELECTION_SUMMARY_LABELS,
+  type SelectionSummaryLabels,
+} from './labels'
+import { styles } from './style'
+
+export interface SelectionSummaryProps {
+  /** Number of currently selected items. */
+  count: number
+  /** Optional total — when 0 the component renders nothing (no data to summarize). */
+  total?: number
+  /** Clear callback. Shown only when count > 0. */
+  onClear?: () => void
+  labels?: Partial<SelectionSummaryLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+}
+
+/**
+ * Render rules:
+ *   - `total === 0` → render nothing.
+ *   - `count === 0` → render `labels.allSelected` (matches v1 default),
+ *     prefixed with the optional `icon` glyph when provided.
+ *   - `count > 0`   → render `labels.selections(count)` + Clear (when `onClear`).
+ */
+export function SelectionSummary({
+  count,
+  total,
+  onClear,
+  labels,
+  icon: Icon,
+  iconProps,
+}: SelectionSummaryProps) {
+  if (total === 0) return null
+  const _labels = { ...DEFAULT_SELECTION_SUMMARY_LABELS, ...labels }
+
+  if (count === 0) {
+    return (
+      <Box sx={styles.root}>
+        {Icon ? <Icon fontSize='small' {...iconProps} /> : null}
+        <Typography variant='caption' sx={styles.label}>
+          {_labels.allSelected}
+        </Typography>
+      </Box>
+    )
+  }
+
+  return (
+    <Box sx={styles.root}>
+      <Typography variant='caption' sx={styles.label}>
+        {_labels.selections(count)}
+      </Typography>
+      {onClear && (
+        <Button size='small' variant='text' onClick={onClear}>
+          {_labels.clear}
+        </Button>
+      )}
+    </Box>
+  )
+}

package/src/widgets-v2/selection-summary/style.ts

@@ -0,0 +1,23 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.5,
+    minHeight: 24,
+  },
+  label: {
+    color: 'text.secondary',
+  },
+  clear: {
+    color: 'primary.main',
+    cursor: 'pointer',
+    fontWeight: 500,
+    '&:hover': { textDecoration: 'underline' },
+  },
+  icon: {
+    fontSize: 16,
+    color: 'text.secondary',
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/spread/download.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createSpreadDownloadConfig } from './download'
+import type { SpreadWidgetData } from './types'
+
+const data: SpreadWidgetData = [
+  {
+    min: 1,
+    max: 9,
+    prefix: '$',
+    suffix: 'k',
+    note: 'q1',
+    series: { name: 'Revenue' },
+  },
+  { min: 0, max: 10 },
+]
+
+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('createSpreadDownloadConfig', () => {
+  it('CSV-only by default', () => {
+    expect(
+      createSpreadDownloadConfig({ filename: 's', getData: () => data }).map(
+        (i) => i.id,
+      ),
+    ).toEqual(['csv'])
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createSpreadDownloadConfig({
+      filename: 's',
+      getData: () => data,
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+  })
+
+  it('CSV resolve emits one row per item with optional fields blanked', async () => {
+    const items = createSpreadDownloadConfig({
+      filename: 's',
+      getData: () => data,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('s.csv')
+    expect(csvText).toBe(
+      'series,prefix,min,max,suffix,note\nRevenue,$,1,9,k,q1\n,,0,10,,',
+    )
+  })
+})

package/src/widgets-v2/spread/download.ts

@@ -0,0 +1,59 @@
+import {
+  buildPngDownloadItem,
+  downloadToCSV,
+  type DownloadItem,
+} from '../actions/download'
+import type { SpreadWidgetData } from './types'
+
+/**
+ * Download menu items for the Spread widget. Always includes a CSV item
+ * with `series, prefix, min, max, suffix, note` columns (one row per
+ * entry). When `getCaptureEl` is supplied, prepends a PNG item that
+ * rasterises the captured element via `html2canvas`.
+ */
+export function createSpreadDownloadConfig(args: {
+  filename: string
+  getData: () => SpreadWidgetData
+  getCaptureEl?: () => HTMLElement | null
+  pngPixelRatio?: number
+  pngBackgroundColor?: string | null
+}): 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: 'Download as CSV',
+    resolve: () => {
+      const data = args.getData()
+      const rows: unknown[][] = [
+        ['series', 'prefix', 'min', 'max', 'suffix', 'note'],
+      ]
+      for (const item of data) {
+        rows.push([
+          item.series?.name ?? '',
+          item.prefix ?? '',
+          item.min,
+          item.max,
+          item.suffix ?? '',
+          item.note ?? '',
+        ])
+      }
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  return items
+}

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

@@ -0,0 +1,6 @@
+export { Spread } from './spread'
+export { SpreadUI, type SpreadUIProps } from './spread-ui'
+export { Separator } from './separator'
+export { SpreadSkeleton, type SpreadSkeletonProps } from './skeleton'
+export { createSpreadDownloadConfig } from './download'
+export type { SpreadDataItem, SpreadWidgetData } from './types'

package/src/widgets-v2/spread/separator.tsx

@@ -0,0 +1,11 @@
+import { Value } from '../formula'
+
+/**
+ * Em-dash separator placed between a Spread row's `min` and `max` values.
+ * Built from the Formula {@link Value} primitive so typography (h5/600,
+ * baseline alignment) matches the numbers around it. Renders with
+ * `text.secondary` so it visually recedes between the two bounds.
+ */
+export function Separator() {
+  return <Value color='inherit'>-</Value>
+}

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

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { SpreadSkeleton } from './skeleton'
+
+describe('<SpreadSkeleton>', () => {
+  it('renders the default skeleton', () => {
+    const { container } = render(<SpreadSkeleton />)
+    expect(container.firstChild).not.toBeNull()
+  })
+
+  it('renders the requested number of rows', () => {
+    const { container } = render(<SpreadSkeleton count={2} />)
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThan(1)
+  })
+})

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

@@ -0,0 +1,38 @@
+import { Box, Skeleton } from '@mui/material'
+import type { SxProps, Theme } from '@mui/material'
+
+const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+    py: 1,
+  },
+  row: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 1.5,
+  },
+  block: { width: 200, height: 32 },
+} satisfies Record<string, SxProps<Theme>>
+
+export interface SpreadSkeletonProps {
+  count?: number
+}
+
+/**
+ * Loading placeholder for the Spread widget. Renders `count` rows, each
+ * sized for the `min — max` pair so the layout doesn't jump once data
+ * resolves. Mirrors the row-per-item structure of {@link SpreadUI}.
+ */
+export function SpreadSkeleton({ count = 1 }: SpreadSkeletonProps) {
+  return (
+    <Box sx={styles.root}>
+      {Array.from({ length: count }).map((_, i) => (
+        <Box key={`row-${i}`} sx={styles.row}>
+          <Skeleton variant='rectangular' sx={styles.block} />
+        </Box>
+      ))}
+    </Box>
+  )
+}

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

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { SpreadUI } from './spread-ui'
+
+describe('<SpreadUI>', () => {
+  it('renders a single min/max pair', () => {
+    render(<SpreadUI items={[{ min: 10, max: 100 }]} />)
+    expect(screen.getByText('10')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+    expect(screen.getByText('-')).toBeTruthy()
+  })
+
+  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('2')).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,52 @@
+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>
+}
+
+/**
+ * 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({ items, formatter, ref }: SpreadUIProps) {
+  const fmt = formatter ?? ((n: number) => String(n))
+  return (
+    <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-v2/spread/spread.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import { Spread } from './spread'
+import { Provider } from '../provider/widget-provider'
+import type { SpreadWidgetData } from './types'
+
+vi.mock('./spread-ui', () => ({
+  SpreadUI: ({
+    items,
+    formatter,
+  }: {
+    items: SpreadWidgetData
+    formatter?: (value: number) => string
+  }) => (
+    <div data-testid='spread-ui' data-count={items.length}>
+      {items
+        .map(
+          (it) =>
+            `${formatter ? formatter(it.min) : it.min}—${formatter ? formatter(it.max) : it.max}`,
+        )
+        .join('|')}
+    </div>
+  ),
+}))
+
+describe('<Spread> bridge', () => {
+  it('forwards data + formatter to SpreadUI', () => {
+    const data: SpreadWidgetData = [
+      { min: 1, max: 9 },
+      { min: 0, max: 10 },
+    ]
+    const { getByTestId } = render(
+      <Provider id='sp-1' data={data} formatter={(n) => `${n}k`}>
+        <Spread />
+      </Provider>,
+    )
+    const ui = getByTestId('spread-ui')
+    expect(ui.dataset.count).toBe('2')
+    expect(ui.textContent).toBe('1k—9k|0k—10k')
+  })
+
+  it('renders zero items when data is null', () => {
+    const { getByTestId } = render(
+      <Provider id='sp-2' data={null}>
+        <Spread />
+      </Provider>,
+    )
+    expect(getByTestId('spread-ui').dataset.count).toBe('0')
+  })
+})

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

@@ -0,0 +1,31 @@
+import { useWidgetId, useWidgetShallow } from '../stores'
+import { SpreadUI } from './spread-ui'
+import type { SpreadWidgetData } from './types'
+
+interface SpreadSlice {
+  data: SpreadWidgetData
+  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: SpreadWidgetData = Object.freeze([]) as SpreadWidgetData
+
+const spreadSelector = (s: {
+  data: unknown
+  formatter?: (value: number) => string
+}): SpreadSlice => ({
+  data: (s.data ?? EMPTY_DATA) as SpreadWidgetData,
+  formatter: s.formatter,
+})
+
+/**
+ * Stateful Spread bridge — reads `data` (post-pipeline) and `formatter` from
+ * the per-widget store and forwards them to the pure {@link SpreadUI}.
+ */
+export function Spread() {
+  const id = useWidgetId()
+  const slice = useWidgetShallow(id, spreadSelector)
+  return <SpreadUI items={slice.data} formatter={slice.formatter} />
+}

package/src/widgets-v2/spread/types.ts

@@ -0,0 +1,27 @@
+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
+  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
+}
+
+/**
+ * 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[]