@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,62 +0,0 @@
-import type { Theme } from '@mui/material'
-import type { EChartsOption } from 'echarts'
-import type { WidgetSeries } from '../types'
-
-/** A single slice of a pie series. */
-export interface PieDatum {
-  name: string | number
-  value: number
-}
-
-/** Pie widget data — one slice array per series (rendered as side-by-side donuts). */
-export type PieWidgetData = readonly (readonly PieDatum[])[]
-
-/** Inputs to the structural-only {@link pieOptions} builder. */
-export interface PieOptionsInput {
-  theme: Theme
-  /** Numeric value formatter — drives the tooltip value and center label. */
-  formatter?: (value: number) => string
-  /** Optional slice-name formatter — also forwarded to the legend. */
-  labelFormatter?: (value: string | number) => string | number
-}
-
-/**
- * Combined inputs for the pie option factory creator. Carries everything
- * the widget needs across BOTH phases — the structural-build (`theme`,
- * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
- * (`series`, `radius`, `selection`). The merger emits different
- * chart shapes by series count: single → donut, multi → horizontal-bar
- * fallback (mirrors v1 pie); both branches read `theme` for styling.
- */
-export interface PieOptionFactoryInput {
-  theme: Theme
-  formatter?: (value: number) => string
-  labelFormatter?: (value: string | number) => string | number
-  /**
-   * Per-series metadata — drives the legend, `series[i].name`, and (in
-   * the multi-series bar fallback) per-series colour overrides.
-   * Single-series donuts always use the per-slice palette regardless of
-   * any `series[0].color`, since the donut palette is keyed by data
-   * index, not series index.
-   */
-  series?: readonly WidgetSeries[]
-  /**
-   * Inner/outer radius (percent). Default `['58%', '74%']` produces a
-   * donut sized to leave room for the wrappable bottom legend. Set
-   * inner to `'0%'` for a solid pie.
-   */
-  radius?: readonly [string, string]
-  /**
-   * Selected slice names. Slices not in this list render dimmed
-   * (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
-   */
-  selection?: readonly (string | number)[] | 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 PieEChartsOption = EChartsOption

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

@@ -1,4 +0,0 @@
-export { Range, type RangeProps } from './range'
-export { RangeUI, type RangeUIProps } from './range-ui'
-export { RangeSkeleton, type RangeSkeletonProps } from './skeleton'
-export type { RangeDataItem, RangeWidgetData, RangeItemValue } from './types'

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

@@ -1,136 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-import { fireEvent, render, screen } from '@testing-library/react'
-import { RangeUI } from './range-ui'
-
-describe('<RangeUI>', () => {
-  it('renders a two-thumb slider per item', () => {
-    render(<RangeUI items={[{ min: 0, max: 100, value: [20, 80] }]} />)
-    const sliders = screen.getAllByRole('slider')
-    expect(sliders).toHaveLength(2)
-    expect(sliders[0]?.getAttribute('aria-valuenow')).toBe('20')
-    expect(sliders[1]?.getAttribute('aria-valuenow')).toBe('80')
-  })
-
-  it('defaults the value to [min, max] when omitted', () => {
-    render(<RangeUI items={[{ min: 10, max: 90 }]} />)
-    const sliders = screen.getAllByRole('slider')
-    expect(sliders[0]?.getAttribute('aria-valuenow')).toBe('10')
-    expect(sliders[1]?.getAttribute('aria-valuenow')).toBe('90')
-  })
-
-  it('renders editable min/max text inputs below the slider', () => {
-    render(<RangeUI items={[{ min: 0, max: 100, value: [20, 80] }]} />)
-    const min = screen.getByLabelText<HTMLInputElement>('Minimum value')
-    const max = screen.getByLabelText<HTMLInputElement>('Maximum value')
-    expect(min).toBeTruthy()
-    expect(max).toBeTruthy()
-    // The displayed value passes through the formatter (default toString).
-    expect(min.value).toBe('20')
-    expect(max.value).toBe('80')
-  })
-
-  it('runs the formatter through the text inputs', () => {
-    render(
-      <RangeUI
-        items={[{ min: 0, max: 1000, value: [100, 900] }]}
-        formatter={(n) => `$${n}`}
-      />,
-    )
-    const min = screen.getByLabelText<HTMLInputElement>('Minimum value')
-    const max = screen.getByLabelText<HTMLInputElement>('Maximum value')
-    expect(min.value).toBe('$100')
-    expect(max.value).toBe('$900')
-  })
-
-  it('renders a caption below the inputs when `note` is provided', () => {
-    render(
-      <RangeUI
-        items={[{ min: 0, max: 100, value: [25, 75], note: 'Filter window' }]}
-      />,
-    )
-    expect(screen.getByText('Filter window')).toBeTruthy()
-  })
-
-  it('renders multiple sliders stacked', () => {
-    render(
-      <RangeUI
-        items={[
-          { min: 0, max: 100, value: [10, 50], note: 'A' },
-          { min: 0, max: 100, value: [25, 75], note: 'B' },
-          { min: 0, max: 50, value: [10, 30], note: 'C' },
-        ]}
-      />,
-    )
-    expect(screen.getByText('A')).toBeTruthy()
-    expect(screen.getByText('B')).toBeTruthy()
-    expect(screen.getByText('C')).toBeTruthy()
-    // Three two-thumb sliders → 6 thumbs total.
-    expect(screen.getAllByRole('slider')).toHaveLength(6)
-  })
-
-  it('fires onChange with the item index and a clamped [low, high] tuple', () => {
-    const onChange = vi.fn()
-    render(
-      <RangeUI
-        items={[
-          { min: 0, max: 100, value: [10, 90] },
-          { min: 0, max: 100, value: [20, 80] },
-        ]}
-        onChange={onChange}
-      />,
-    )
-    // Drag the second item's lower thumb to 42.
-    const sliders = screen.getAllByRole('slider')
-    fireEvent.change(sliders[2]!, { target: { value: '42' } })
-    expect(onChange).toHaveBeenCalled()
-    const call = onChange.mock.calls[0] as [number, readonly [number, number]]
-    expect(call[0]).toBe(1)
-    expect(Array.isArray(call[1])).toBe(true)
-    expect(call[1]).toHaveLength(2)
-  })
-
-  it('respects per-item disabled on both slider and inputs', () => {
-    render(
-      <RangeUI
-        items={[{ min: 0, max: 100, value: [10, 90], disabled: true }]}
-      />,
-    )
-    const sliders = screen.getAllByRole('slider')
-    expect(sliders[0]?.hasAttribute('disabled')).toBe(true)
-    expect(sliders[1]?.hasAttribute('disabled')).toBe(true)
-    expect(
-      screen.getByLabelText('Minimum value').hasAttribute('disabled'),
-    ).toBe(true)
-    expect(
-      screen.getByLabelText('Maximum value').hasAttribute('disabled'),
-    ).toBe(true)
-  })
-
-  it('commits a typed value on Enter (fires both onChange and onChangeCommitted), clamped to [min, max]', () => {
-    // A text-input edit is both a value change and a final commit, so it
-    // notifies `onChange` AND `onChangeCommitted` — consumers that only wired
-    // `onChange` (the pre-`onChangeCommitted` API) still update.
-    const onChange = vi.fn()
-    const onChangeCommitted = vi.fn()
-    render(
-      <RangeUI
-        items={[{ min: 0, max: 100, value: [10, 90] }]}
-        onChange={onChange}
-        onChangeCommitted={onChangeCommitted}
-      />,
-    )
-    const min = screen.getByLabelText('Minimum value')
-    // Type 150 — should clamp to max (100), then preserve ordering (low <= high).
-    fireEvent.change(min, { target: { value: '150' } })
-    fireEvent.keyDown(min, { key: 'Enter' })
-    expect(onChangeCommitted).toHaveBeenCalled()
-    expect(onChange).toHaveBeenCalled()
-    const last = onChangeCommitted.mock.calls.at(-1) as [
-      number,
-      readonly [number, number],
-    ]
-    expect(last[0]).toBe(0)
-    expect(last[1][0]).toBeLessThanOrEqual(last[1][1])
-    expect(last[1][1]).toBeLessThanOrEqual(100)
-  })
-})

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

@@ -1,278 +0,0 @@
-import {
-  useCallback,
-  useState,
-  type FocusEvent,
-  type KeyboardEvent,
-} from 'react'
-import { Box, Slider, TextField, Typography } from '@mui/material'
-import type { RangeDataItem, RangeItemValue } from './types'
-import { styles } from './style'
-
-export interface RangeUIProps {
-  items: readonly RangeDataItem[]
-  /**
-   * Fires on every pointer tick while a thumb is being dragged (mirrors
-   * MUI `<Slider>`'s `onChange`). Use this to update local UI state —
-   * not to persist expensive operations like remote queries.
-   */
-  onChange?: (index: number, value: RangeItemValue) => void
-  /**
-   * Fires once when the user *releases* a slider thumb after dragging,
-   * after an arrow-key adjustment commits, or when the text inputs
-   * blur / Enter. Mirrors MUI `<Slider>`'s `onChangeCommitted`. Use
-   * this for side-effects you want to throttle to "drag end" — e.g.
-   * writing the value to a source filter that triggers refetches.
-   */
-  onChangeCommitted?: (index: number, value: RangeItemValue) => void
-  /** Number formatter for the slider tooltip and the text input display. */
-  formatter?: (value: number) => string
-}
-
-type Bound = 'min' | 'max'
-
-/**
- * Pure presentational component for the Range widget. Renders one MUI Slider
- * per item with editable min/max text inputs below — matching the Range v1
- * UX. Each item is always a two-thumb range; supply `value` to seed the
- * starting selection, otherwise it defaults to `[min, max]`.
- */
-export function RangeUI({
-  items,
-  onChange,
-  onChangeCommitted,
-  formatter,
-}: RangeUIProps) {
-  const fmt = formatter ?? ((n: number) => String(n))
-  return (
-    <Box sx={styles.root}>
-      {items.map((item, i) => (
-        // Composite of the row's track bounds — stable across reorders for
-        // any realistic widget configuration. Falls back to a literal +
-        // index when bounds collide (degenerate same-min-same-max rows).
-        <RangeRow
-          key={`range-${item.min}-${item.max}-${i}`}
-          index={i}
-          item={item}
-          fmt={fmt}
-          onChange={onChange}
-          onChangeCommitted={onChangeCommitted}
-        />
-      ))}
-    </Box>
-  )
-}
-
-interface RangeRowProps {
-  index: number
-  item: RangeDataItem
-  fmt: (n: number) => string
-  onChange?: (index: number, value: RangeItemValue) => void
-  onChangeCommitted?: (index: number, value: RangeItemValue) => void
-}
-
-function RangeRow({
-  index,
-  item,
-  fmt,
-  onChange,
-  onChangeCommitted,
-}: RangeRowProps) {
-  const current: readonly [number, number] = item.value ?? [item.min, item.max]
-  const [editing, setEditing] = useState<'' | Bound>('')
-
-  // Clamp inside [min, max] and keep `low <= high`. Pulled out so both the
-  // live `onChange` path and the commit path share the same normalization.
-  const normalize = useCallback(
-    (next: readonly [number, number]): readonly [number, number] => {
-      const [lowRaw, highRaw] = next
-      const low = Math.min(Math.max(lowRaw, item.min), item.max)
-      const high = Math.min(Math.max(highRaw, item.min), item.max)
-      return low <= high ? [low, high] : [high, low]
-    },
-    [item.min, item.max],
-  )
-
-  const commit = useCallback(
-    (next: readonly [number, number]) => {
-      onChange?.(index, normalize(next))
-    },
-    [index, normalize, onChange],
-  )
-
-  const commitFinal = useCallback(
-    (next: readonly [number, number]) => {
-      onChangeCommitted?.(index, normalize(next))
-    },
-    [index, normalize, onChangeCommitted],
-  )
-
-  // A text-input commit (blur / Enter) is both a value change AND a final
-  // commit, so it fires `onChange` *and* `onChangeCommitted`. Firing both
-  // keeps the widget responsive for consumers that only wired `onChange`
-  // (the pre-`onChangeCommitted` API) — without it, typing a value and
-  // pressing Enter would silently no-op for them.
-  const commitText = useCallback(
-    (next: readonly [number, number]) => {
-      const value = normalize(next)
-      onChange?.(index, value)
-      onChangeCommitted?.(index, value)
-    },
-    [index, normalize, onChange, onChangeCommitted],
-  )
-
-  const handleSlider = (_: Event, raw: number | number[]) => {
-    if (!Array.isArray(raw)) return
-    // Hoist defaults out of the destructure: react-compiler can't safely
-    // reorder MemberExpression defaults inside an array pattern.
-    const low = raw[0] ?? item.min
-    const high = raw[1] ?? item.max
-    commit([low, high])
-  }
-
-  const handleSliderCommitted = (
-    _: Event | React.SyntheticEvent,
-    raw: number | number[],
-  ) => {
-    if (!Array.isArray(raw)) return
-    const low = raw[0] ?? item.min
-    const high = raw[1] ?? item.max
-    commitFinal([low, high])
-  }
-
-  return (
-    <Box sx={styles.item}>
-      <Box sx={styles.sliderContainer}>
-        <Slider
-          sx={{
-            ...styles.slider,
-            ...(item.color ? { color: item.color } : null),
-          }}
-          value={[...current]}
-          min={item.min}
-          max={item.max}
-          step={item.step ?? 1}
-          marks={resolveMarks(item.marks)}
-          disabled={item.disabled}
-          valueLabelDisplay='auto'
-          valueLabelFormat={fmt}
-          onChange={handleSlider}
-          onChangeCommitted={handleSliderCommitted}
-        />
-      </Box>
-      <Box sx={styles.inputsRow}>
-        {/* Text-input commits (blur / Enter) are final, but also notify
-            `onChange` — see `commitText` — so consumers that only wired
-            `onChange` still update on a typed value. */}
-        <BoundInput
-          // Bumping the key on a fresh external value resets the local
-          // editing state — matches v1's RangeItem behaviour.
-          key={`min-${current[0]}`}
-          name='min'
-          value={current[0]}
-          item={item}
-          fmt={fmt}
-          editing={editing}
-          setEditing={setEditing}
-          commit={commitText}
-          current={current}
-          ariaLabel='Minimum value'
-        />
-        <BoundInput
-          key={`max-${current[1]}`}
-          name='max'
-          value={current[1]}
-          item={item}
-          fmt={fmt}
-          editing={editing}
-          setEditing={setEditing}
-          commit={commitText}
-          current={current}
-          ariaLabel='Maximum value'
-        />
-      </Box>
-      {item.note ? (
-        <Typography variant='caption' sx={styles.note}>
-          {item.note}
-        </Typography>
-      ) : null}
-    </Box>
-  )
-}
-
-interface BoundInputProps {
-  name: Bound
-  value: number
-  item: RangeDataItem
-  fmt: (n: number) => string
-  editing: '' | Bound
-  setEditing: (next: '' | Bound) => void
-  /**
-   * Called when the user commits a new value (blur / Enter). Text input
-   * edits never produce intermediate "live" values, so the consumer
-   * only needs one callback — the row wires this to `commitFinal`.
-   */
-  commit: (next: readonly [number, number]) => void
-  current: readonly [number, number]
-  ariaLabel: string
-}
-
-function BoundInput({
-  name,
-  value,
-  item,
-  fmt,
-  editing,
-  setEditing,
-  commit,
-  current,
-  ariaLabel,
-}: BoundInputProps) {
-  const [raw, setRaw] = useState<string>(String(value))
-
-  const beginEditing = () => {
-    setEditing(name)
-  }
-  const finishEditingAndCommit = (e: FocusEvent<HTMLInputElement>) => {
-    setEditing('')
-    commitFromText(e.target.value)
-  }
-  const commitOnEnter = (e: KeyboardEvent<HTMLInputElement>) => {
-    if (e.key === 'Enter') {
-      commitFromText((e.target as HTMLInputElement).value)
-      ;(e.target as HTMLInputElement).blur()
-    }
-  }
-
-  function commitFromText(input: string) {
-    const parsed = parseFloat(input)
-    const safe = Number.isFinite(parsed) ? parsed : value
-    const next: readonly [number, number] =
-      name === 'min' ? [safe, current[1]] : [current[0], safe]
-    commit(next)
-  }
-
-  const display = editing === name ? raw : fmt(Number(raw))
-
-  return (
-    <TextField
-      name={name}
-      value={display}
-      onChange={(e) => setRaw(e.target.value)}
-      onFocus={beginEditing}
-      onBlur={finishEditingAndCommit}
-      onKeyDown={commitOnEnter}
-      disabled={item.disabled}
-      size='small'
-      sx={styles.input}
-      inputProps={{ 'aria-label': ariaLabel }}
-    />
-  )
-}
-
-function resolveMarks(
-  marks: RangeDataItem['marks'],
-): boolean | { value: number; label?: string }[] | undefined {
-  if (marks == null) return undefined
-  if (typeof marks === 'boolean') return marks
-  return [...marks]
-}

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

@@ -1,47 +0,0 @@
-import { Box, Skeleton } from '@mui/material'
-import type { SxProps, Theme } from '@mui/material'
-
-const styles = {
-  root: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 3,
-    py: 1,
-  },
-  item: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 1.5,
-  },
-  track: { height: 32 },
-  inputsRow: {
-    display: 'flex',
-    gap: 2,
-  },
-  input: { flex: 1, height: 40 },
-} satisfies Record<string, SxProps<Theme>>
-
-export interface RangeSkeletonProps {
-  count?: number
-}
-
-/**
- * Loading placeholder for the Range widget. Renders `count` rows, each
- * matching the slider-then-inputs layout of {@link RangeUI} so the layout
- * doesn't jump when data resolves.
- */
-export function RangeSkeleton({ count = 1 }: RangeSkeletonProps) {
-  return (
-    <Box sx={styles.root}>
-      {Array.from({ length: count }).map((_, i) => (
-        <Box key={`item-${i}`} sx={styles.item}>
-          <Skeleton variant='rectangular' sx={styles.track} />
-          <Box sx={styles.inputsRow}>
-            <Skeleton variant='rectangular' sx={styles.input} />
-            <Skeleton variant='rectangular' sx={styles.input} />
-          </Box>
-        </Box>
-      ))}
-    </Box>
-  )
-}

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

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

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

@@ -1,37 +0,0 @@
-import type { ReactNode } from 'react'
-
-/**
- * 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
-  /**
-   * 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
-  /**
-   * 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
-  /** Optional caption rendered below the inputs row. */
-  note?: ReactNode
-}
-
-/** Range widget data — one or more two-thumb entries rendered stacked. */
-export type RangeWidgetData = readonly RangeDataItem[]
-
-/** The shape `onChange` reports — always a `[low, high]` tuple. */
-export type RangeItemValue = readonly [number, number]

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

@@ -1,51 +0,0 @@
-import {
-  buildCsvDownloadItem,
-  buildPngDownloadItem,
-  type DownloadContext,
-  type DownloadItem,
-} 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 supplied, prepends a PNG item that rasterises the
- * captured element via `html2canvas`.
- */
-export function createScatterplotDownloadConfig(args: {
-  filename: string
-  getData: (ctx: DownloadContext) => ScatterplotWidgetData
-  seriesNames?: readonly string[]
-  getCaptureEl?: (ctx: DownloadContext) => 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(
-    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
-      },
-    }),
-  )
-  return items
-}

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

@@ -1,14 +0,0 @@
-export { scatterplotOptions, createScatterplotOptionFactory } from './options'
-export { ScatterplotSkeleton, type ScatterplotSkeletonProps } from './skeleton'
-export { createScatterplotDownloadConfig } from './download'
-export {
-  toRelativeScatterplotData,
-  filterScatterplotByLockedPoints,
-} from './transforms'
-export type {
-  ScatterplotDatum,
-  ScatterplotWidgetData,
-  ScatterplotOptionsInput,
-  ScatterplotOptionFactoryInput,
-  ScatterplotEChartsOption,
-} from './types'