@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/widgets/range/style.ts

@@ -1,25 +1,32 @@
 import type { SxProps, Theme } from '@mui/material'
 
-export const styles: Record<string, SxProps<Theme>> = {
+export const styles = {
   root: {
     display: 'flex',
     flexDirection: 'column',
-    gap: (theme: Theme) => theme.spacing(2),
+    gap: 3,
+    py: 1,
   },
-  rangeItem: {
+  item: {
     display: 'flex',
     flexDirection: 'column',
-    gap: (theme: Theme) => theme.spacing(1.5),
+    gap: 1.5,
   },
   sliderContainer: {
     display: 'flex',
     flexDirection: 'column',
-    gap: (theme: Theme) => theme.spacing(1),
-    px: (theme: Theme) => theme.spacing(1),
+    gap: 1,
+    px: 1,
+  },
+  slider: {
+    width: '100%',
+    '&.Mui-disabled': {
+      color: (theme: Theme) => theme.palette.text.disabled,
+    },
   },
   inputsRow: {
     display: 'flex',
-    gap: (theme: Theme) => theme.spacing(2),
+    gap: 2,
     alignItems: 'center',
   },
   input: {
@@ -28,10 +35,7 @@ export const styles: Record<string, SxProps<Theme>> = {
       textAlign: 'center',
     },
   },
-  slider: {
-    width: '100%',
-    '&.Mui-disabled': {
-      color: (theme: Theme) => theme.palette.text.disabled,
-    },
+  note: {
+    color: 'text.secondary',
   },
 } satisfies Record<string, SxProps<Theme>>

package/src/widgets/range/types.ts

@@ -1,39 +1,37 @@
 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'
-
-export interface RangeUIProps {
-  id: WidgetsStoreProps['id']
-}
 
+/**
+ * A single two-thumb range entry. Renders as an MUI `<Slider>` with editable
+ * `min` / `max` text inputs below, mirroring the Range v1 widget UX.
+ */
 export interface RangeDataItem {
+  /** Lower bound of the slider track. */
   min: number
+  /** Upper bound of the slider track. */
   max: number
-  value?: number[]
+  /**
+   * Current selected range `[low, high]`. When omitted, defaults to
+   * `[min, max]` — i.e. the full track. The consumer owns this value and
+   * updates it in response to `onChange`.
+   */
+  value?: readonly [number, number]
+  /** Step granularity (default `1`). */
   step?: number
-  marks?: boolean | { value: number; label?: string }[]
+  /**
+   * Tick marks. Pass `true` to enable MUI's auto-marks (one per `step`); pass
+   * an array for explicit marks; omit for no marks.
+   */
+  marks?: boolean | readonly { value: number; label?: string }[]
+  /** Disable user interaction for this row (slider + inputs). */
   disabled?: boolean
+  /** Override the slider's track / thumb colour (any CSS / MUI palette path). */
   color?: string
-  note?: string | ReactNode
-}
-
-export interface RangeItemProps {
-  id: WidgetsStoreProps['id']
-  index: number
+  /** Optional caption rendered below the inputs row. */
+  note?: ReactNode
 }
 
-export type RangeWidgetData = RangeDataItem[]
-
-export type RangeWidgetState = BaseWidgetState<
-  WrapperState<RangeWidgetConfig>
-> & {
-  data: RangeWidgetData
-}
-
-export interface RangeWidgetConfig {
-  formatter?: (value: number) => string
-  onChange?: (value: number[], index: number) => void
-}
+/** Range widget data — one or more two-thumb entries rendered stacked. */
+export type RangeWidgetData = readonly RangeDataItem[]
 
-export type RangeDownloadConfig = DownloadItem<RangeWidgetData>[]
+/** The shape `onChange` reports — always a `[low, high]` tuple. */
+export type RangeItemValue = readonly [number, number]

package/src/widgets/scatterplot/download.ts

@@ -0,0 +1,37 @@
+import {
+  buildCsvDownloadItem,
+  withPngItem,
+  type DownloadItem,
+  type WidgetDownloadArgs,
+} from '../actions/download'
+import type { ScatterplotWidgetData } from './types'
+
+/**
+ * Download menu items for the Scatterplot widget. Always includes a CSV item
+ * with `series, x, y` columns (one row per point). When `getCaptureEl` is
+ * given, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export function createScatterplotDownloadConfig(
+  args: WidgetDownloadArgs<ScatterplotWidgetData> & {
+    seriesNames?: readonly string[]
+  },
+): DownloadItem[] {
+  return withPngItem(
+    args,
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
+        const rows: unknown[][] = [['series', 'x', 'y']]
+        for (const [i, series] of data.entries()) {
+          const seriesName = args.seriesNames?.[i] ?? `series_${i + 1}`
+          for (const [x, y] of series) {
+            rows.push([seriesName, x, y])
+          }
+        }
+        return rows
+      },
+    }),
+  )
+}

package/src/widgets/scatterplot/index.ts

@@ -1,8 +1,14 @@
+export { scatterplotOptions, createScatterplotOptionFactory } from './options'
+export { ScatterplotSkeleton, type ScatterplotSkeletonProps } from './skeleton'
+export { createScatterplotDownloadConfig } from './download'
+export {
+  toRelativeScatterplotData,
+  filterScatterplotByLockedPoints,
+} from './transforms'
 export type {
+  ScatterplotDatum,
   ScatterplotWidgetData,
-  ScatterplotWidgetState,
-  ScatterplotWidgetConfig,
-  ScatterplotConfig,
+  ScatterplotOptionsInput,
+  ScatterplotOptionFactoryInput,
+  ScatterplotEChartsOption,
 } from './types'
-export { scatterplotConfig, scatterplotDownloadConfig } from './config'
-export { ScatterplotSkeleton } from './skeleton'

package/src/{widgets-v2 → widgets}/scatterplot/options.ts

@@ -8,7 +8,7 @@ import {
   createTooltipFormatter,
   createTooltipPositioner,
   niceNum,
-} from '../../widgets/utils/chart-config'
+} from '../utils/option-builders'
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'

package/src/widgets/scatterplot/skeleton.tsx

@@ -1,58 +1,83 @@
 import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import type { SxProps, Theme } from '@mui/material'
 
-const SCATTER_POINTS = [
-  { left: '20%', top: '62%' },
-  { left: '26%', top: '70%' },
-  { left: '29%', top: '73%' },
-  { left: '38%', top: '63%' },
-  { left: '41%', top: '68%' },
-  { left: '47%', top: '62%' },
-  { left: '53%', top: '49%' },
-  { left: '56%', top: '55%' },
-  { left: '65%', top: '37%' },
-  { left: '68%', top: '43%' },
-  { left: '77%', top: '59%' },
-  { left: '25%', top: '30%' },
-  { left: '60%', top: '70%' },
-  { left: '10%', top: '55%' },
-  { left: '40%', top: '40%' },
-]
+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>>
 
-export function ScatterplotSkeleton() {
+// `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.skeleton.graph.container}>
-      {SCATTER_POINTS.map((point, index) => (
-        <Skeleton
-          key={`skeleton-point-${index}`}
-          variant='circular'
-          width={12}
-          height={12}
-          sx={{
-            position: 'absolute',
-            top: point.top,
-            left: point.left,
-            transform: 'translate(-50%, -50%)',
-          }}
-        />
-      ))}
-      {/* Legend */}
-      <Box sx={styles.skeleton.legend}>
-        {Array(2)
-          .fill(0)
-          .map((_, i) => (
-            <Box
-              key={`skeleton-${i}`}
-              sx={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: ({ spacing }) => spacing(1.5),
-              }}
-            >
-              <Skeleton variant='circular' width={8} height={8} />
-              <Skeleton width={48} height={8} />
-            </Box>
-          ))}
+    <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/scatterplot/types.ts

@@ -1,17 +1,59 @@
-import type { EchartWidgetState } from '../echart'
-import type {
-  EchartWidgetOptionProps,
-  EchartWidgetProps,
-} from '../echart/types'
-import type { ConfigProps } from '../loader'
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+import type { WidgetSeries } from '../types'
 
-export type ScatterplotWidgetData = [number, number][][]
+/** A single point — `[x, y]` tuple. */
+export type ScatterplotDatum = readonly [number, number]
 
-export type ScatterplotWidgetState = EchartWidgetState
+/** Scatterplot widget data — array of series, each a list of `[x, y]` tuples. */
+export type ScatterplotWidgetData = readonly (readonly ScatterplotDatum[])[]
 
-export type ScatterplotWidgetConfig = EchartWidgetProps & {
-  type: 'scatterplot'
+/** 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
 }
 
-export type ScatterplotConfig = ConfigProps &
-  EchartWidgetOptionProps<ScatterplotWidgetData>
+/**
+ * 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/selection-summary/selection-summary.tsx

@@ -1,55 +1,80 @@
-/* Selection Summary Component */
-
-import { Box, Button, Typography } from '@mui/material'
-import type {
-  WidgetSelectionSummaryProps,
-  SelectionSummaryLabels,
-} from './types'
+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'
 
-const DEFAULT_SELECTION_LABELS: SelectionSummaryLabels = {
-  allSelected: 'All selected',
-  selections: (count: number) => `${count} selected`,
-  clear: 'Clear',
+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
 }
 
 /**
- * Displays the count of selected items with an optional clear button. Commonly used with the LockSelection action to show selection state in widgets.
+ * 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).
  *
- * @example
- * ```tsx
- * <WidgetSelectionSummary
- *   selections={selectedItems.length}
- *   onClear={() => setSelectedItems([])}
- * />
- * ```
+ * 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 WidgetSelectionSummary({
-  selections,
+export function SelectionSummary({
+  count,
+  total,
   onClear,
   labels,
-}: WidgetSelectionSummaryProps) {
-  const allSelectedLabel =
-    labels?.allSelected ?? DEFAULT_SELECTION_LABELS.allSelected
-
-  const selectionsLabel =
-    labels?.selections ?? DEFAULT_SELECTION_LABELS.selections
-
-  const clearLabel = labels?.clear ?? DEFAULT_SELECTION_LABELS.clear
-
-  const displayLabel =
-    selections > 0 ? selectionsLabel(selections) : allSelectedLabel
-
-  const showClearButton = selections > 0 && onClear
+  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}>
-      <Typography variant='caption' color='textSecondary' fontWeight={500}>
-        {displayLabel}
-      </Typography>
-      {showClearButton && (
+      {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}>
-          {clearLabel}
+          {_labels.clear}
         </Button>
       )}
     </Box>

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

@@ -4,7 +4,35 @@ export const styles = {
   root: {
     display: 'flex',
     alignItems: 'center',
-    flex: '0 0 auto',
-    gap: ({ spacing }) => spacing(0.5),
+    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/spread/download.ts

@@ -0,0 +1,41 @@
+import {
+  buildCsvDownloadItem,
+  withPngItem,
+  type DownloadItem,
+  type WidgetDownloadArgs,
+} 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 given, prepends a PNG item that rasterises the captured
+ * element via `html2canvas`.
+ */
+export function createSpreadDownloadConfig(
+  args: WidgetDownloadArgs<SpreadWidgetData>,
+): DownloadItem[] {
+  return withPngItem(
+    args,
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: (ctx) => {
+        const data = args.getData(ctx)
+        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 ?? '',
+          ])
+        }
+        return rows
+      },
+    }),
+  )
+}

package/src/widgets/spread/index.ts

@@ -1,23 +1,11 @@
-export { SpreadUI } from './spread-ui'
-export { SpreadSkeleton } from './skeleton'
-export { spreadConfig, spreadDownloadConfig } from './config'
-export { MinValue } from './components/min-value'
-export { MaxValue } from './components/max-value'
-export { Separator } from './components/separator'
-
-// Re-export formula components for convenience
-export { Item, Row, Prefix, Suffix, Series } from '../formula'
-
-export type {
-  RowProps,
-  ValueProps,
-  SpreadWidgetState,
-  SpreadWidgetConfig,
-  SpreadWidgetData,
-  SpreadDownloadConfig,
-  ItemProps,
-  SpreadDataItem,
-  SpreadUIProps,
-} from './types'
-
-export type { SeriesConfig } from '../formula/types'
+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'