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

package/src/widgets/range/components/range-item.tsx

@@ -0,0 +1,214 @@
+import { Box, Slider, TextField } from '@mui/material'
+import { useState, useMemo, type FocusEvent, type KeyboardEvent } from 'react'
+import { widgetStoreActions } from '../../stores/widget-store'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
+import type { RangeItemProps, RangeWidgetState } from '../types'
+import { styles } from '../style'
+
+import { defaultFormatter } from '../../utils/formatter'
+
+type EditingState = '' | 'min' | 'max'
+
+/**
+ * Renders a single range slider with editable min/max text inputs, reading its configuration from the widget store.
+ */
+export function RangeItem({ id, index }: RangeItemProps) {
+  const {
+    item,
+    onChange,
+    formatter: _formatter,
+  } = useWidgetSelector(id, (w) => {
+    const rw = w as RangeWidgetState | undefined
+    return {
+      item: rw?.data[index],
+      onChange: rw?.onChange,
+      formatter: rw?.formatter,
+    }
+  })
+  const formatter = _formatter ?? defaultFormatter
+
+  const currentValue = useMemo(
+    () => (item ? (item.value ?? [item.min, item.max]) : [0, 0]),
+    [item],
+  )
+
+  // Local state for input values - track if user is editing
+  const [isEditing, setIsEditing] = useState<EditingState>('')
+
+  if (!item) return null
+
+  const handleSliderChange = (_: Event, newValue: number | number[]) => {
+    if (Array.isArray(newValue)) {
+      const [min, max] = newValue
+      const data =
+        widgetStoreActions.getWidget<RangeWidgetState>(id)?.data ?? []
+
+      data[index] = {
+        ...item,
+        value: newValue,
+      }
+
+      widgetStoreActions.setWidget(id, {
+        data,
+      })
+
+      onChange?.([min!, max!], index)
+    }
+  }
+
+  const handleInputFocus = (e: FocusEvent<HTMLInputElement>) => {
+    setIsEditing(e.target.name as EditingState)
+  }
+
+  const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const { name, value } = event.target
+
+    let newValue: [number, number]
+    if (name === 'min') {
+      newValue = [
+        Math.min(
+          Math.max(item.min, parseFloat(value) || item.min),
+          currentValue[1]!,
+        ),
+        currentValue[1] ?? 0,
+      ]
+    } else {
+      newValue = [
+        currentValue[0] ?? 0,
+        Math.max(
+          Math.min(item.max, parseFloat(value) || item.max),
+          currentValue[0]!,
+        ),
+      ]
+    }
+
+    const data = widgetStoreActions.getWidget<RangeWidgetState>(id)?.data ?? []
+
+    widgetStoreActions.setWidget(id, {
+      data: data.map((d: RangeWidgetState['data'][number], i: number) =>
+        i === index
+          ? {
+              ...d,
+              value: newValue,
+            }
+          : d,
+      ),
+    })
+
+    onChange?.([newValue[0], newValue[1]], index)
+  }
+
+  const handleInputBlur = (e: FocusEvent<HTMLInputElement>) => {
+    setIsEditing('')
+    handleInputChange(e)
+  }
+
+  const handleInputKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'Enter') {
+      handleInputBlur(event as unknown as FocusEvent<HTMLInputElement>)
+      event.currentTarget.blur()
+    }
+  }
+
+  return (
+    <Box sx={styles.rangeItem}>
+      <Box sx={styles.sliderContainer}>
+        <Slider
+          value={currentValue}
+          onChange={handleSliderChange}
+          valueLabelDisplay='auto'
+          valueLabelFormat={formatter}
+          min={item.min}
+          max={item.max}
+          step={item.step}
+          marks={item.marks}
+          disabled={item.disabled}
+          sx={{
+            ...styles.slider,
+            ...(item.color && {
+              color: item.color,
+            }),
+          }}
+        />
+      </Box>
+
+      <Box sx={styles.inputsRow}>
+        <Input
+          key={`min-${currentValue[0]}`}
+          isEditing={isEditing}
+          name='min'
+          value={currentValue[0] ?? 0}
+          formatter={formatter}
+          onFocus={handleInputFocus}
+          onBlur={handleInputBlur}
+          onKeyDown={handleInputKeyDown}
+          disabled={item.disabled}
+          inputProps={{
+            'aria-label': 'Minimum value',
+          }}
+        />
+        <Input
+          key={`max-${currentValue[1]}`}
+          isEditing={isEditing}
+          name='max'
+          value={currentValue[1] ?? 0}
+          formatter={formatter}
+          onFocus={handleInputFocus}
+          onBlur={handleInputBlur}
+          onKeyDown={handleInputKeyDown}
+          disabled={item.disabled}
+          inputProps={{
+            'aria-label': 'Maximum value',
+          }}
+        />
+      </Box>
+    </Box>
+  )
+}
+
+function Input({
+  isEditing,
+  name,
+  disabled,
+  value,
+  formatter,
+  onFocus: onFocus,
+  onBlur: onBlur,
+  onKeyDown: onKeyDown,
+  inputProps,
+}: {
+  isEditing: EditingState
+  name: 'min' | 'max'
+  disabled?: boolean
+  value: number
+  formatter: (value: number) => string
+  onFocus: (e: FocusEvent<HTMLInputElement>) => void
+  onBlur: (e: FocusEvent<HTMLInputElement>) => void
+  onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void
+  inputProps?: React.InputHTMLAttributes<HTMLInputElement>
+}) {
+  const [currentValue, setCurrentValue] = useState<string>(String(value))
+
+  // Compute display values when not editing
+  const displayMinValue = useMemo(
+    () => formatter(Number(currentValue)),
+    [currentValue, formatter],
+  )
+
+  return (
+    <TextField
+      name={name}
+      value={isEditing === name ? currentValue : displayMinValue}
+      onChange={(e) => {
+        setCurrentValue(e.target.value)
+      }}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      onKeyDown={onKeyDown}
+      disabled={disabled}
+      size='small'
+      sx={styles.input}
+      inputProps={inputProps}
+    />
+  )
+}

package/src/widgets/range/config.ts

@@ -0,0 +1,10 @@
+import type { RangeWidgetConfig } from './types'
+
+/**
+ * Returns the default configuration for range (value range with labels) widgets.
+ *
+ * @returns Default range widget config.
+ */
+export function rangeConfig(): RangeWidgetConfig {
+  return {}
+}

package/src/widgets/range/index.ts

@@ -0,0 +1,16 @@
+export { RangeUI } from './range-ui'
+export { RangeSkeleton } from './skeleton'
+export { rangeConfig } from './config'
+export { RangeItem } from './components/range-item'
+
+export type {
+  RangeWidgetState,
+  RangeWidgetConfig,
+  RangeDownloadConfig,
+  RangeUIProps,
+  RangeDataItem,
+  RangeWidgetData,
+  RangeItemProps,
+} from './types'
+
+export { sanitizeRangeDataItem, sanitizeRangeDataItems } from './serializer'

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

@@ -0,0 +1,203 @@
+import { describe, test, expect, beforeEach, vi } from 'vitest'
+import { render, screen, fireEvent } 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()
+  })
+
+  test('returns null when widget does not exist', () => {
+    const { container } = render(<RangeUI id='non-existent' />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  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()
+  })
+
+  test('handles undefined data', () => {
+    useWidgetStore.getState().setWidget<RangeWidgetState>('test-range', {
+      type: 'range',
+    })
+
+    const { container } = render(<RangeUI id='test-range' />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  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')
+  })
+
+  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)
+  })
+
+  test('validates max 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 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)
+  })
+
+  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')
+  })
+
+  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()
+  })
+})

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

@@ -0,0 +1,14 @@
+import type { RangeUIProps } from './types'
+import { Row } from '../formula/components/row'
+import { RangeItem } from './components/range-item'
+
+/**
+ * Renders a range widget with one or more interactive dual-slider controls for selecting value ranges.
+ */
+export function RangeUI(props: RangeUIProps) {
+  return (
+    <Row id={props.id}>
+      {({ index }) => <RangeItem id={props.id} index={index} />}
+    </Row>
+  )
+}

package/src/widgets/range/serializer.test.ts

@@ -0,0 +1,70 @@
+import { describe, test, expect } from 'vitest'
+import { sanitizeRangeDataItem, sanitizeRangeDataItems } from './serializer'
+import type { RangeDataItem } from './types'
+
+describe('sanitizeRangeDataItem', () => {
+  test('preserves all other properties', () => {
+    const item: RangeDataItem = {
+      min: 10,
+      max: 90,
+      value: [20, 80],
+      step: 5,
+      marks: true,
+      disabled: true,
+      color: '#FF0000',
+    }
+
+    const sanitized = sanitizeRangeDataItem(item)
+
+    expect(sanitized.min).toBe(10)
+    expect(sanitized.max).toBe(90)
+    expect(sanitized.value).toEqual([20, 80])
+    expect(sanitized.step).toBe(5)
+    expect(sanitized.marks).toBe(true)
+    expect(sanitized.disabled).toBe(true)
+    expect(sanitized.color).toBe('#FF0000')
+  })
+})
+
+describe('sanitizeRangeDataItems', () => {
+  test('sanitizes array of items', () => {
+    const items: RangeDataItem[] = [{ min: 10, max: 90 }]
+
+    const sanitized = sanitizeRangeDataItems(items)
+
+    expect(sanitized).toHaveLength(1)
+  })
+
+  test('handles undefined input', () => {
+    const sanitized = sanitizeRangeDataItems(undefined)
+
+    expect(sanitized).toBeUndefined()
+  })
+
+  test('handles empty array', () => {
+    const sanitized = sanitizeRangeDataItems([])
+
+    expect(sanitized).toEqual([])
+  })
+
+  test('preserves all item properties', () => {
+    const items: RangeDataItem[] = [
+      {
+        min: 0,
+        max: 100,
+        value: [25, 75],
+        step: 10,
+        marks: [
+          { value: 0, label: '0' },
+          { value: 100, label: '100' },
+        ],
+        disabled: false,
+        color: '#00FF00',
+      },
+    ]
+
+    const sanitized = sanitizeRangeDataItems(items)
+
+    expect(sanitized![0]).toEqual(items[0])
+  })
+})

package/src/widgets/range/serializer.ts

@@ -0,0 +1,27 @@
+import type { RangeDataItem } from './types'
+
+/**
+ * Sanitizes RangeDataItem by converting ReactNode note values to undefined.
+ * This ensures only string values are stored in the widget state.
+ *
+ * @param item - The RangeDataItem to sanitize
+ * @returns A new RangeDataItem with ReactNode note values converted to undefined
+ */
+export function sanitizeRangeDataItem(item: RangeDataItem): RangeDataItem {
+  return {
+    ...item,
+    note: typeof item.note === 'string' ? item.note : undefined,
+  }
+}
+
+/**
+ * Sanitizes an array of RangeDataItems by converting ReactNode note values to undefined.
+ *
+ * @param items - Array of RangeDataItems to sanitize
+ * @returns A new array with sanitized RangeDataItems
+ */
+export function sanitizeRangeDataItems(
+  items: RangeDataItem[] | undefined,
+): RangeDataItem[] | undefined {
+  return items?.map(sanitizeRangeDataItem)
+}

package/src/widgets/range/skeleton.tsx

@@ -0,0 +1,14 @@
+import { Box, Skeleton } from '@mui/material'
+import { styles } from './style'
+
+export function RangeSkeleton() {
+  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>
+  )
+}

package/src/widgets/range/style.ts

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

package/src/widgets/range/types.ts

@@ -0,0 +1,39 @@
+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']
+}
+
+export interface RangeDataItem {
+  min: number
+  max: number
+  value?: number[]
+  step?: number
+  marks?: boolean | { value: number; label?: string }[]
+  disabled?: boolean
+  color?: string
+  note?: string | ReactNode
+}
+
+export interface RangeItemProps {
+  id: WidgetsStoreProps['id']
+  index: number
+}
+
+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
+}
+
+export type RangeDownloadConfig = DownloadItem<RangeWidgetData>[]