@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,84 +0,0 @@
-import { Box, Skeleton } from '@mui/material'
-import type { SxProps, Theme } from '@mui/material'
-
-const styles = {
-  container: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    flexDirection: 'column',
-    gap: ({ spacing }) => spacing(1),
-    height: ({ spacing }) => spacing(38),
-  },
-  grid: {
-    position: 'relative',
-    flex: '1 1 auto',
-    width: '100%',
-  },
-  legend: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: ({ spacing }) => spacing(2),
-    height: ({ spacing }) => spacing(5),
-  },
-  legendItem: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: ({ spacing }) => spacing(1.5),
-  },
-} satisfies Record<string, SxProps<Theme>>
-
-// `sx` callback that needs runtime args — extracted at module scope so the
-// `styles` object can satisfy `Record<string, SxProps<Theme>>` cleanly
-// (function `sx`-with-args isn't assignable to plain `SxProps<Theme>`).
-const dotSx = (top: string, left: string, size: number): SxProps<Theme> => ({
-  position: 'absolute',
-  top,
-  left,
-  width: size,
-  height: size,
-  borderRadius: '50%',
-})
-
-export interface ScatterplotSkeletonProps {
-  /** Number of dots to render. */
-  count?: number
-}
-
-/**
- * Loading state for the Scatterplot widget. Mirrors a scatter chart's
- * silhouette — a deterministic spread of small circular dots in the plot
- * area plus a legend stub — so the skeleton reads as "a scatter chart"
- * rather than a generic list. Matches bar/histogram/pie skeleton structure
- * (grid stub + legend stub in a flex column).
- */
-export function ScatterplotSkeleton({ count = 24 }: ScatterplotSkeletonProps) {
-  // Deterministic pseudo-scatter positions so the skeleton doesn't flicker.
-  const dots = Array.from({ length: count }, (_, i) => {
-    const top = 10 + ((i * 37) % 80)
-    const left = 5 + ((i * 53) % 90)
-    const size = 8 + ((i * 7) % 6)
-    return { top: `${top}%`, left: `${left}%`, size }
-  })
-  return (
-    <Box sx={styles.container}>
-      <Box sx={styles.grid}>
-        {dots.map((d, i) => (
-          <Skeleton
-            key={`dot-${i}`}
-            variant='circular'
-            sx={dotSx(d.top, d.left, d.size)}
-          />
-        ))}
-      </Box>
-      <Box sx={styles.legend}>
-        {[0, 1].map((i) => (
-          <Box key={`legend-${i}`} sx={styles.legendItem}>
-            <Skeleton variant='circular' width={8} height={8} />
-            <Skeleton width={48} height={8} />
-          </Box>
-        ))}
-      </Box>
-    </Box>
-  )
-}

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

@@ -1,59 +0,0 @@
-import type { Theme } from '@mui/material'
-import type { EChartsOption } from 'echarts'
-import type { WidgetSeries } from '../types'
-
-/** 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 (`series`, `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
-  /**
-   * Per-series metadata — drives the legend, `series[i].name`, and
-   * (when `color` is set) a per-series colour override on the points.
-   */
-  series?: readonly WidgetSeries[]
-  /** 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/selection-summary.tsx

@@ -1,82 +0,0 @@
-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 `undefined` or `0` the component renders nothing (no data). */
-  total?: number
-  /** Clear callback. The Clear control is shown only when `count > 0` and `onClear` is provided. */
-  onClear?: () => void
-  labels?: Partial<SelectionSummaryLabels>
-  icon?: ComponentType<SvgIconProps>
-  iconProps?: SvgIconProps
-}
-
-/**
- * Renders a `selected / total` count.
- *
- * Render rules:
- *   - `!total` (undefined or 0) → render nothing (no data to summarize).
- *   - `count === 0` → display `total / total` (everything is implicitly in
- *     scope); no Clear button.
- *   - `count > 0` → display `count / total` + Clear (when `onClear` is given).
- *
- * The count is two-tone by default (selected number bold/`text.primary`,
- * ` / total` in `text.secondary`). Pass `labels.summary` to render a custom
- * node instead — it receives the already-resolved displayed number (which
- * equals `total` when nothing is selected).
- */
-export function SelectionSummary({
-  count,
-  total,
-  onClear,
-  labels,
-  icon: Icon,
-  iconProps,
-}: SelectionSummaryProps) {
-  if (!total) return null
-  const _labels = { ...DEFAULT_SELECTION_SUMMARY_LABELS, ...labels }
-  const shown = count === 0 ? total : count
-
-  return (
-    <Box sx={styles.root}>
-      {Icon ? <Icon fontSize='small' {...iconProps} /> : null}
-      <Box
-        component='span'
-        sx={styles.count}
-        aria-label={`${shown} / ${total}`}
-      >
-        {_labels.summary ? (
-          _labels.summary(shown, total)
-        ) : (
-          <>
-            <Typography component='span' variant='caption' sx={styles.selected}>
-              {shown}
-            </Typography>
-            <Typography
-              component='span'
-              variant='caption'
-              sx={styles.separator}
-            >
-              /
-            </Typography>
-            <Typography component='span' variant='caption' sx={styles.total}>
-              {total}
-            </Typography>
-          </>
-        )}
-      </Box>
-      {count > 0 && onClear && (
-        <Button size='small' variant='text' onClick={onClear}>
-          {_labels.clear}
-        </Button>
-      )}
-    </Box>
-  )
-}

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

@@ -1,38 +0,0 @@
-import type { SxProps, Theme } from '@mui/material'
-
-export const styles = {
-  root: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: 0.5,
-    minHeight: 24,
-  },
-  label: {
-    color: 'text.secondary',
-  },
-  count: {
-    display: 'inline-flex',
-    alignItems: 'baseline',
-    gap: 0.5,
-  },
-  selected: {
-    color: 'text.primary',
-    fontWeight: 600,
-  },
-  separator: {
-    color: 'text.secondary',
-  },
-  total: {
-    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/index.ts

@@ -1,11 +0,0 @@
-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 {
-  getSpreadBand,
-  type SpreadVariant,
-  type GetSpreadBandOptions,
-} from './band'
-export type { SpreadDataItem, SpreadWidgetData } from './types'

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

@@ -1,38 +0,0 @@
-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

@@ -1,108 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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/types.ts

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

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

@@ -1,49 +0,0 @@
-export type {
-  TransformType,
-  TransformDescriptor,
-  TransformFn,
-  Transform,
-  TransformPair,
-  WidgetState,
-  WidgetInit,
-  WidgetStoreApi,
-} from './types'
-
-export { applyTransforms, upsertTransform, removeTransform } from './transforms'
-
-export { pipelineMiddleware } from './pipeline-middleware'
-
-export { WidgetContext, useWidgetId } from './widget-context'
-
-export {
-  getWidgetStore,
-  hasWidgetStore,
-  deleteWidgetStore,
-  resetWidgetStore,
-  clearAllWidgetStores,
-  registerWidgetStore,
-  unregisterWidgetStore,
-  setWidgetStoreEntry,
-  createWidgetStore,
-  useWidget,
-  useWidgetShallow,
-  setCaptureEl,
-  getCaptureEl,
-  clearAllCaptureEls,
-  setEchartInstance,
-  getEchartInstance,
-  subscribeEchartInstance,
-  clearAllEchartInstances,
-  __debugListWidgetStores,
-} from './widget-store-registry'
-
-export { useEchartInstance } from './use-echart-instance'
-
-export {
-  useTransform,
-  useSingleTransform,
-  type UseTransformOptions,
-  type TransformControls,
-} from './use-transform'
-
-export { useTransformEnabled } from './use-transform-enabled'

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

@@ -1,64 +0,0 @@
-import type { StoreApi } from 'zustand'
-
-export type TransformType = 'data' | 'config'
-
-export interface TransformDescriptor {
-  id: string
-  type: TransformType
-  order: number
-  disables?: string[]
-  replaceMergeKeys?: string[]
-}
-
-export type TransformFn = (input: unknown) => unknown
-
-export interface Transform extends TransformDescriptor {
-  fn: TransformFn
-  enabled: boolean
-}
-
-export interface TransformPair {
-  descriptor: TransformDescriptor
-  fn: TransformFn
-}
-
-export interface WidgetState {
-  rawData: unknown
-  data: unknown
-
-  dataTransforms: readonly Transform[]
-  configTransforms: readonly Transform[]
-
-  transformStates: Record<string, { enabled: boolean; [k: string]: unknown }>
-
-  isLoading: boolean
-  isFetching: boolean
-  error: unknown
-
-  /**
-   * Original formatter as supplied by the consumer (Provider's `formatter`
-   * prop). Always live-synced — never overridden by actions. Actions that need
-   * to display a different formatter (e.g. {@link RelativeData}'s percent
-   * formatter) should write to {@link WidgetState.formatter} and read this
-   * field when restoring the absolute view.
-   */
-  rawFormatter?: (value: number) => string
-  /**
-   * Active formatter — what consumer code (tooltips, axis labels, legends,
-   * etc.) reads. Defaults to {@link WidgetState.rawFormatter}; actions may
-   * override it temporarily and restore it from `rawFormatter` later.
-   */
-  formatter?: (value: number) => string
-  labelFormatter?: (value: string | number) => string | number
-}
-
-export interface WidgetInit {
-  data: unknown
-  isLoading?: boolean
-  isFetching?: boolean
-  error?: unknown
-  formatter?: (value: number) => string
-  labelFormatter?: (value: string | number) => string | number
-}
-
-export type WidgetStoreApi = StoreApi<WidgetState>

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

@@ -1,12 +0,0 @@
-import type { SxProps, Theme } from '@mui/material'
-
-export const styles = {
-  root: {
-    display: 'grid',
-    gridTemplateColumns: '1fr auto',
-    alignItems: 'center',
-    gap: 1,
-    minHeight: 32,
-    pb: 1,
-  },
-} satisfies Record<string, SxProps<Theme>>

package/src/widgets-v2/subheader/subheader.test.tsx

@@ -1,30 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { render } from '@testing-library/react'
-import { Subheader } from './subheader'
-
-describe('<Subheader>', () => {
-  it('renders children inside a Box', () => {
-    const { getByText } = render(
-      <Subheader>
-        <span>left</span>
-        <span>right</span>
-      </Subheader>,
-    )
-    expect(getByText('left')).toBeTruthy()
-    expect(getByText('right')).toBeTruthy()
-  })
-
-  it('merges caller-supplied sx onto the root', () => {
-    const { container } = render(
-      <Subheader sx={{ mt: 4 }}>
-        <span>x</span>
-      </Subheader>,
-    )
-    expect(container.firstChild).not.toBeNull()
-    // Class-based assertions are brittle; settle for "an element renders + a
-    // single child slot exists" — sx forwarding gets exercised at the
-    // import/MUI level so we don't need to inspect emotion-generated class
-    // names.
-    expect(container.querySelectorAll('span').length).toBe(1)
-  })
-})

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

@@ -1,16 +0,0 @@
-import { Box, type SxProps, type Theme } from '@mui/material'
-import type { ReactNode } from 'react'
-import { styles } from './style'
-
-export interface SubheaderProps {
-  sx?: SxProps<Theme>
-  children: ReactNode
-}
-
-/**
- * Stateless layout: CSS grid `1fr auto`. Children self-place — typically
- * `<Widget.SelectionSummary />` (left) and `<Widget.Toolbox>` (right).
- */
-export function Subheader({ sx, children }: SubheaderProps) {
-  return <Box sx={{ ...styles.root, ...sx }}>{children}</Box>
-}