@carto/ps-react-ui 4.7.1 → 4.9.0

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,54 @@
+import {
+  buildPngDownloadItem,
+  downloadToCSV,
+  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({
+    id: 'csv',
+    label: 'Download as CSV',
+    resolve: () => {
+      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])
+        }
+      }
+      const handle = downloadToCSV(rows)
+      return Promise.resolve({
+        url: handle.url,
+        filename: `${args.filename}.csv`,
+        revoke: handle.revoke,
+      })
+    },
+  })
+  return items
+}

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

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