@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

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

@@ -0,0 +1,278 @@
+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/range.test.tsx

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { Provider } from '../provider/widget-provider'
+import { clearAllWidgetStores } from '../stores'
+import { Range } from './range'
+import type { RangeWidgetData } from './types'
+
+beforeEach(() => clearAllWidgetStores())
+afterEach(() => clearAllWidgetStores())
+
+describe('<Range> bridge', () => {
+  it('renders two-thumb sliders for each row', () => {
+    const data: RangeWidgetData = [
+      { min: 0, max: 100, value: [25, 75] },
+      { min: 0, max: 50, value: [10, 40] },
+    ]
+    render(
+      <Provider id='rng-1' data={data}>
+        <Range />
+      </Provider>,
+    )
+    // Two items × two thumbs each = 4.
+    expect(screen.getAllByRole('slider').length).toBe(4)
+  })
+
+  it('defaults a row without `value` to [min, max]', () => {
+    const data: RangeWidgetData = [{ min: 10, max: 90 }]
+    render(
+      <Provider id='rng-2' data={data}>
+        <Range />
+      </Provider>,
+    )
+    const sliders = screen.getAllByRole('slider')
+    expect(sliders[0]?.getAttribute('aria-valuenow')).toBe('10')
+    expect(sliders[1]?.getAttribute('aria-valuenow')).toBe('90')
+  })
+
+  it('fires onChange with item index and the new tuple', () => {
+    const onChange = vi.fn()
+    const data: RangeWidgetData = [{ min: 0, max: 100, value: [25, 75] }]
+    render(
+      <Provider id='rng-3' data={data}>
+        <Range onChange={onChange} />
+      </Provider>,
+    )
+    const sliders = screen.getAllByRole('slider')
+    fireEvent.change(sliders[0]!, { target: { value: '60' } })
+    expect(onChange).toHaveBeenCalled()
+    const call = onChange.mock.calls[0] as [number, readonly [number, number]]
+    expect(call[0]).toBe(0)
+    expect(Array.isArray(call[1])).toBe(true)
+    expect(call[1]).toHaveLength(2)
+  })
+
+  it('honours per-item disabled', () => {
+    const data: RangeWidgetData = [
+      { min: 0, max: 100, value: [25, 75], disabled: true },
+    ]
+    render(
+      <Provider id='rng-4' data={data}>
+        <Range />
+      </Provider>,
+    )
+    const sliders = screen.getAllByRole('slider')
+    expect((sliders[0] as HTMLInputElement).disabled).toBe(true)
+    expect((sliders[1] as HTMLInputElement).disabled).toBe(true)
+  })
+})

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

@@ -0,0 +1,52 @@
+import { useWidgetId, useWidgetShallow } from '../stores'
+import { RangeUI } from './range-ui'
+import type { RangeItemValue, RangeWidgetData } from './types'
+
+interface RangeSlice {
+  data: RangeWidgetData
+  formatter?: (value: number) => string
+}
+
+const rangeSelector = (s: {
+  data: unknown
+  formatter?: (value: number) => string
+}): RangeSlice => ({
+  data: (s.data ?? []) as RangeWidgetData,
+  formatter: s.formatter,
+})
+
+export interface RangeProps {
+  /**
+   * Fires on every pointer tick while a thumb is being dragged. Use this
+   * for cheap UI updates (local state, optimistic display).
+   */
+  onChange?: (index: number, value: RangeItemValue) => void
+  /**
+   * Fires once when the user *releases* a slider thumb (or when the text
+   * inputs blur / Enter, or when an arrow-key adjustment settles). Use
+   * this for expensive side-effects you want throttled to drag end —
+   * e.g. writing the value to a source filter that refetches widgets.
+   */
+  onChangeCommitted?: (index: number, value: RangeItemValue) => void
+}
+
+/**
+ * Stateful Range bridge — reads `data` (post-pipeline) and `formatter` from
+ * the per-widget store and forwards them to the pure {@link RangeUI}. Per
+ * the destination-owned principle, value changes flow back through
+ * `onChange` (per-tick) and `onChangeCommitted` (drag end) — the consumer
+ * is expected to update the data prop on `<Provider>`. Use `disabled` on
+ * individual `RangeDataItem`s to disable specific rows.
+ */
+export function Range({ onChange, onChangeCommitted }: RangeProps) {
+  const id = useWidgetId()
+  const slice = useWidgetShallow(id, rangeSelector)
+  return (
+    <RangeUI
+      items={slice.data}
+      formatter={slice.formatter}
+      onChange={onChange}
+      onChangeCommitted={onChangeCommitted}
+    />
+  )
+}

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

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { RangeSkeleton } from './skeleton'
+
+describe('<RangeSkeleton>', () => {
+  it('renders without crashing', () => {
+    const { container } = render(<RangeSkeleton />)
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThan(0)
+  })
+
+  it('scales with count', () => {
+    const { container } = render(<RangeSkeleton count={2} />)
+    expect(container.firstChild).not.toBeNull()
+  })
+})

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

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

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

@@ -0,0 +1,37 @@
+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.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createScatterplotDownloadConfig } from './download'
+import type { ScatterplotWidgetData } from './types'
+
+const data: ScatterplotWidgetData = [
+  [
+    [1, 10],
+    [2, 20],
+  ],
+  [[3, 30]],
+]
+
+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('createScatterplotDownloadConfig', () => {
+  it('CSV-only by default', () => {
+    expect(
+      createScatterplotDownloadConfig({
+        filename: 's',
+        getData: () => data,
+      }).map((i) => i.id),
+    ).toEqual(['csv'])
+  })
+
+  it('prepends PNG when getCaptureEl is provided', () => {
+    const items = createScatterplotDownloadConfig({
+      filename: 's',
+      getData: () => data,
+      getCaptureEl: () => document.createElement('div'),
+    })
+    expect(items.map((i) => i.id)).toEqual(['png', 'csv'])
+  })
+
+  it('CSV resolve writes series × point rows with default names', async () => {
+    const items = createScatterplotDownloadConfig({
+      filename: 's',
+      getData: () => data,
+    })
+    const handle = await items.find((i) => i.id === 'csv')!.resolve()
+    expect(handle.filename).toBe('s.csv')
+    expect(csvText).toBe(
+      'series,x,y\nseries_1,1,10\nseries_1,2,20\nseries_2,3,30',
+    )
+  })
+
+  it('CSV honours supplied seriesNames', async () => {
+    const items = createScatterplotDownloadConfig({
+      filename: 's',
+      getData: () => data,
+      seriesNames: ['A', 'B'],
+    })
+    await items.find((i) => i.id === 'csv')!.resolve()
+    expect(csvText.split('\n')[1]).toBe('A,1,10')
+  })
+})

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

@@ -0,0 +1,50 @@
+import {
+  buildCsvDownloadItem,
+  buildPngDownloadItem,
+  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: () => ScatterplotWidgetData
+  seriesNames?: readonly string[]
+  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(
+    buildCsvDownloadItem({
+      filename: args.filename,
+      getRows: () => {
+        const data = args.getData()
+        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

@@ -0,0 +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,
+  ScatterplotOptionsInput,
+  ScatterplotOptionFactoryInput,
+  ScatterplotEChartsOption,
+} from './types'