@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,203 +1,136 @@
-import { describe, test, expect, beforeEach, vi } from 'vitest'
-import { render, screen, fireEvent } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
 import { RangeUI } from './range-ui'
-import { useWidgetStore } from '../stores/widget-store'
-import type { RangeWidgetState } from './types'
 
-describe('RangeUI', () => {
-  beforeEach(() => {
-    useWidgetStore.getState().clearWidgets()
+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')
   })
 
-  test('returns null when widget does not exist', () => {
-    const { container } = render(<RangeUI id='non-existent' />)
-    expect(container.firstChild).toBeNull()
+  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')
   })
 
-  test('renders with single range item', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100, value: [20, 80] }],
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const inputs = screen.getAllByRole('textbox')
-    expect(inputs).toHaveLength(2)
-    expect((inputs[0] as HTMLInputElement).value).toBe('20')
-    expect((inputs[1] as HTMLInputElement).value).toBe('80')
-  })
-
-  test('renders with multiple range items', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [
-        { min: 0, max: 100, value: [20, 80] },
-        { min: 0, max: 50, value: [10, 40] },
-      ],
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const inputs = screen.getAllByRole('textbox')
-    expect(inputs).toHaveLength(4)
-    expect((inputs[0] as HTMLInputElement).value).toBe('20')
-    expect((inputs[1] as HTMLInputElement).value).toBe('80')
-    expect((inputs[2] as HTMLInputElement).value).toBe('10')
-    expect((inputs[3] as HTMLInputElement).value).toBe('40')
-  })
-
-  test('uses formatter when provided', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100, value: [20, 80] }],
-      formatter: (val: number) => `$${val}`,
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const inputs = screen.getAllByRole('textbox')
-    expect((inputs[0] as HTMLInputElement).value).toBe('$20')
-    expect((inputs[1] as HTMLInputElement).value).toBe('$80')
-  })
-
-  test('handles onChange callback', () => {
-    const onChange = vi.fn()
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100, value: [20, 80] }],
-      onChange,
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const minInput = screen.getAllByRole('textbox')[0]
-    fireEvent.change(minInput!, { target: { value: '30' } })
-    fireEvent.blur(minInput!)
-
-    expect(onChange).toHaveBeenCalledWith([30, 80], 0)
-  })
-
-  test('renders disabled state', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100, disabled: true }],
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const inputs = screen.getAllByRole('textbox')
-    expect((inputs[0] as HTMLInputElement).disabled).toBe(true)
-    expect((inputs[1] as HTMLInputElement).disabled).toBe(true)
-  })
-
-  test('handles empty data array', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [],
-    })
-
-    const { container } = render(<RangeUI id='test-range' />)
-    expect(container.firstChild).toBeNull()
+  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')
   })
 
-  test('handles undefined data', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-    })
-
-    const { container } = render(<RangeUI id='test-range' />)
-    expect(container.firstChild).toBeNull()
+  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')
   })
 
-  test('uses default min/max when value is not provided', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 10, max: 90 }],
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const inputs = screen.getAllByRole('textbox')
-    expect((inputs[0] as HTMLInputElement).value).toBe('10')
-    expect((inputs[1] as HTMLInputElement).value).toBe('90')
+  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()
   })
 
-  test('validates min input on blur', () => {
-    const onChange = vi.fn()
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100, value: [20, 80] }],
-      onChange,
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const minInput = screen.getAllByRole('textbox')[0]
-
-    // Try to set min higher than max
-    fireEvent.change(minInput!, { target: { value: '90' } })
-    fireEvent.blur(minInput!)
-
-    // Should clamp to max value
-    expect(onChange).toHaveBeenCalledWith([80, 80], 0)
+  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)
   })
 
-  test('validates max input on blur', () => {
+  it('fires onChange with the item index and a clamped [low, high] tuple', () => {
     const onChange = vi.fn()
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100, value: [20, 80] }],
-      onChange,
-    })
-
-    render(<RangeUI id='test-range' />)
-
-    const maxInput = screen.getAllByRole('textbox')[1]
-
-    // Try to set max lower than min
-    fireEvent.change(maxInput!, { target: { value: '10' } })
-    fireEvent.blur(maxInput!)
-
-    // Should clamp to min value
-    expect(onChange).toHaveBeenCalledWith([20, 20], 0)
+    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)
   })
 
-  test('updates when widget data changes', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100, value: [20, 80] }],
-    })
-
-    const { rerender } = render(<RangeUI id='test-range' />)
-
-    let inputs = screen.getAllByRole('textbox')
-    expect((inputs[0] as HTMLInputElement).value).toBe('20')
-    expect((inputs[1] as HTMLInputElement).value).toBe('80')
-
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      data: [{ min: 0, max: 100, value: [30, 70] }],
-    })
-
-    rerender(<RangeUI id='test-range' />)
-
-    inputs = screen.getAllByRole('textbox')
-    expect((inputs[0] as HTMLInputElement).value).toBe('30')
-    expect((inputs[1] as HTMLInputElement).value).toBe('70')
+  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)
   })
 
-  test('handles widget removal gracefully', () => {
-    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
-      type: 'range',
-      data: [{ min: 0, max: 100 }],
-    })
-
-    const { container, rerender } = render(<RangeUI id='test-range' />)
-    expect(container.firstChild).toBeTruthy()
-
-    useWidgetStore.getState().removeWidget('test-range')
-
-    rerender(<RangeUI id='test-range' />)
-    expect(container.firstChild).toBeNull()
+  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/range/range-ui.tsx

@@ -1,14 +1,280 @@
-import type { RangeUIProps } from './types'
-import { Row } from '../formula/components/row'
-import { RangeItem } from './components/range-item'
+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'
 
 /**
- * Renders a range widget with one or more interactive dual-slider controls for selecting value ranges.
+ * 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(props: RangeUIProps) {
+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 (
-    <Row id={props.id}>
-      {({ index }) => <RangeItem id={props.id} index={index} />}
-    </Row>
+    <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}
+      slotProps={{
+        htmlInput: { '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/range/skeleton.tsx

@@ -1,14 +1,47 @@
 import { Box, Skeleton } from '@mui/material'
-import { styles } from './style'
+import type { SxProps, Theme } from '@mui/material'
 
-export function RangeSkeleton() {
+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.rangeItem} aria-label='Range skeleton'>
-      <Skeleton width='100%' height={32} />
-      <Box sx={styles.inputsRow}>
-        <Skeleton width='100%' height={40} />
-        <Skeleton width='100%' height={40} />
-      </Box>
+    <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>
   )
 }