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

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

@@ -0,0 +1,368 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { SpreadUI } from './spread-ui'
+import { useWidgetStore } from '../stores/widget-store'
+import type { SpreadWidgetState } from './types'
+
+describe('SpreadUI', () => {
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  test('renders empty container when widget does not exist', () => {
+    const { container } = render(<SpreadUI id='non-existent' />)
+    // Box wrapper is rendered but Row returns null for missing widget
+    expect(container.firstChild?.childNodes.length).toBe(0)
+  })
+
+  test('renders with single spread data item', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 2.1, max: 2.23, suffix: '€' }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('2.1')).toBeTruthy()
+    expect(screen.getByText('-')).toBeTruthy()
+    expect(screen.getByText('2.23')).toBeTruthy()
+    expect(screen.getByText('€')).toBeTruthy()
+  })
+
+  test('renders with multiple spread data items', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [
+        { min: 1.5, max: 2.5, prefix: '$' },
+        { min: 100, max: 200, suffix: '%' },
+        { min: 0, max: 10 },
+      ],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('$')).toBeTruthy()
+    expect(screen.getByText('1.5')).toBeTruthy()
+    expect(screen.getByText('2.5')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+    expect(screen.getByText('200')).toBeTruthy()
+    expect(screen.getByText('%')).toBeTruthy()
+    expect(screen.getByText('0')).toBeTruthy()
+    expect(screen.getByText('10')).toBeTruthy()
+  })
+
+  test('renders prefix for each item', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [
+        { min: 1, max: 10, prefix: 'Range 1:' },
+        { min: 20, max: 30, prefix: 'Range 2:' },
+      ],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('Range 1:')).toBeTruthy()
+    expect(screen.getByText('Range 2:')).toBeTruthy()
+  })
+
+  test('renders separator between min and max values', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 5, max: 15 }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    // Check for separator "-"
+    const separators = screen.getAllByText('-')
+    expect(separators.length).toBe(1)
+  })
+
+  test('renders in correct order: Prefix, MinValue, Separator, MaxValue, Suffix', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 10, max: 20, prefix: '$', suffix: 'USD' }],
+    })
+
+    const { container } = render(<SpreadUI id='test-spread' />)
+
+    const items = container.querySelectorAll('.MuiTypography-root')
+    expect(items.length).toBe(5)
+    expect(items[0]?.textContent).toBe('$')
+    expect(items[1]?.textContent).toBe('10')
+    expect(items[2]?.textContent).toBe('-')
+    expect(items[3]?.textContent).toBe('20')
+    expect(items[4]?.textContent).toBe('USD')
+  })
+
+  test('handles data without prefix', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 5, max: 15, suffix: 'km' }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('5')).toBeTruthy()
+    expect(screen.getByText('-')).toBeTruthy()
+    expect(screen.getByText('15')).toBeTruthy()
+    expect(screen.getByText('km')).toBeTruthy()
+  })
+
+  test('handles data without suffix', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 5, max: 15, prefix: '$' }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('$')).toBeTruthy()
+    expect(screen.getByText('5')).toBeTruthy()
+    expect(screen.getByText('-')).toBeTruthy()
+    expect(screen.getByText('15')).toBeTruthy()
+  })
+
+  test('handles data with only min and max values', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 5, max: 15 }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('5')).toBeTruthy()
+    expect(screen.getByText('-')).toBeTruthy()
+    expect(screen.getByText('15')).toBeTruthy()
+  })
+
+  test('handles empty data array', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [],
+    })
+
+    const { container } = render(<SpreadUI id='test-spread' />)
+
+    // Row component returns null for empty data, Box wrapper still rendered
+    expect(container.firstChild?.childNodes.length).toBe(0)
+  })
+
+  test('handles undefined data', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+    })
+
+    const { container } = render(<SpreadUI id='test-spread' />)
+
+    // Row component returns null for undefined data, Box wrapper still rendered
+    expect(container.firstChild?.childNodes.length).toBe(0)
+  })
+
+  test('renders with data containing colors', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [
+        { min: 1, max: 10, color: '#FF0000' },
+        { min: 20, max: 30, color: '#00FF00' },
+      ],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('1')).toBeTruthy()
+    expect(screen.getByText('10')).toBeTruthy()
+    expect(screen.getByText('20')).toBeTruthy()
+    expect(screen.getByText('30')).toBeTruthy()
+  })
+
+  test('renders with negative min value', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: -10, max: 5 }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('-10')).toBeTruthy()
+    expect(screen.getByText('-')).toBeTruthy()
+    expect(screen.getByText('5')).toBeTruthy()
+  })
+
+  test('renders with zero values', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 0, max: 0 }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    const zeros = screen.getAllByText('0')
+    expect(zeros.length).toBe(2) // min and max both are 0
+  })
+
+  test('renders with decimal values', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 2.1, max: 2.23, suffix: '€' }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('2.1')).toBeTruthy()
+    expect(screen.getByText('2.23')).toBeTruthy()
+    expect(screen.getByText('€')).toBeTruthy()
+  })
+
+  test('renders with large values', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 1000000, max: 2000000, prefix: '$' }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    expect(screen.getByText('$')).toBeTruthy()
+    expect(screen.getByText('1000000')).toBeTruthy()
+    expect(screen.getByText('2000000')).toBeTruthy()
+  })
+
+  test('updates when widget data changes', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 1, max: 10 }],
+    })
+
+    const { rerender } = render(<SpreadUI id='test-spread' />)
+    expect(screen.getByText('1')).toBeTruthy()
+    expect(screen.getByText('10')).toBeTruthy()
+
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      data: [{ min: 20, max: 30 }],
+    })
+
+    rerender(<SpreadUI id='test-spread' />)
+    expect(screen.queryByText('1')).toBeNull()
+    expect(screen.queryByText('10')).toBeNull()
+    expect(screen.getByText('20')).toBeTruthy()
+    expect(screen.getByText('30')).toBeTruthy()
+  })
+
+  test('handles widget removal gracefully', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 1, max: 10 }],
+    })
+
+    const { container, rerender } = render(<SpreadUI id='test-spread' />)
+    expect(screen.getByText('1')).toBeTruthy()
+
+    useWidgetStore.getState().removeWidget('test-spread')
+
+    rerender(<SpreadUI id='test-spread' />)
+    // Box wrapper still rendered but Row returns null
+    expect(container.firstChild?.childNodes.length).toBe(0)
+  })
+
+  test('renders multiple rows for multiple data items', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [
+        { min: 1, max: 10, prefix: 'A' },
+        { min: 20, max: 30, prefix: 'B' },
+        { min: 40, max: 50, prefix: 'C' },
+      ],
+    })
+
+    const { container } = render(<SpreadUI id='test-spread' />)
+
+    // Each data item should create a row
+    const rows = container.querySelectorAll('[class*="MuiBox-root"]')
+    expect(rows.length).toBeGreaterThan(0)
+  })
+
+  test('renders with series configuration', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 10, max: 100, suffix: '€' }],
+      series: [{ name: 'Revenue', color: '#FF5733' }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    // Series should display the first letter of the name
+    expect(screen.getByText('R')).toBeTruthy()
+    expect(screen.getByText('10')).toBeTruthy()
+    expect(screen.getByText('100')).toBeTruthy()
+    expect(screen.getByText('€')).toBeTruthy()
+  })
+
+  test('renders without series when not provided', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 5, max: 25 }],
+    })
+
+    const { container } = render(<SpreadUI id='test-spread' />)
+
+    // Should not have any Avatar elements (series)
+    const avatars = container.querySelectorAll('.MuiAvatar-root')
+    expect(avatars.length).toBe(0)
+  })
+
+  test('renders series with default color when color not provided', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [{ min: 0, max: 50 }],
+      series: [{ name: 'Test' }],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    // Series should display the first letter
+    expect(screen.getByText('T')).toBeTruthy()
+  })
+
+  test('renders with array of series matching data indices', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [
+        { min: 10, max: 100 },
+        { min: 20, max: 200 },
+        { min: 30, max: 300 },
+      ],
+      series: [
+        { name: 'Alpha', color: '#FF0000' },
+        { name: 'Beta', color: '#00FF00' },
+        { name: 'Gamma', color: '#0000FF' },
+      ],
+    })
+
+    render(<SpreadUI id='test-spread' />)
+
+    // Each series should display its first letter
+    expect(screen.getByText('A')).toBeTruthy()
+    expect(screen.getByText('B')).toBeTruthy()
+    expect(screen.getByText('G')).toBeTruthy()
+  })
+
+  test('renders partial series array - only shows series for available indices', () => {
+    useWidgetStore.getState().setWidget<SpreadWidgetState>('test-spread', {
+      type: 'spread',
+      data: [
+        { min: 10, max: 100 },
+        { min: 20, max: 200 },
+        { min: 30, max: 300 },
+      ],
+      series: [{ name: 'Only First', color: '#FF0000' }],
+    })
+
+    const { container } = render(<SpreadUI id='test-spread' />)
+
+    // Only one series avatar should be rendered
+    const avatars = container.querySelectorAll('.MuiAvatar-root')
+    expect(avatars.length).toBe(1)
+    expect(screen.getByText('O')).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,32 @@
+import type { SpreadUIProps } from './types'
+
+import { Separator } from './components/separator'
+import { MinValue } from './components/min-value'
+import { MaxValue } from './components/max-value'
+import { Prefix, Row, Suffix, Series } from '../formula'
+import { useWidgetRef } from '../../hooks'
+import { Box } from '@mui/material'
+
+/**
+ * Renders a spread widget displaying min-max value pairs with optional prefixes, suffixes, and series indicators.
+ */
+export function SpreadUI(props: SpreadUIProps) {
+  const { ref } = useWidgetRef(props.id)
+
+  return (
+    <Box ref={ref}>
+      <Row id={props.id}>
+        {({ index }) => (
+          <>
+            <Series id={props.id} index={index} />
+            <Prefix id={props.id} index={index} />
+            <MinValue id={props.id} index={index} />
+            <Separator />
+            <MaxValue id={props.id} index={index} />
+            <Suffix id={props.id} index={index} />
+          </>
+        )}
+      </Row>
+    </Box>
+  )
+}

package/src/widgets/spread/style.ts

@@ -0,0 +1,22 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: (theme: Theme) => theme.spacing(2),
+  },
+  item: {
+    '&[data-disabled="true"]': {
+      color: (theme: Theme) => theme.palette.text.disabled,
+    },
+  },
+  row: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: (theme: Theme) => theme.spacing(0.25),
+    '& + &': {
+      marginTop: (theme: Theme) => theme.spacing(1),
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/spread/types.ts

@@ -0,0 +1,47 @@
+import type { TypographyProps } from '@mui/material'
+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'
+import type { SeriesConfig } from '../formula/types'
+
+export interface SpreadUIProps {
+  id: WidgetsStoreProps['id']
+}
+
+export interface SpreadDataItem {
+  min: number
+  max: number
+  prefix?: string | ReactNode
+  suffix?: string | ReactNode
+  color?: string
+}
+
+export interface RowProps {
+  id: WidgetsStoreProps['id']
+  children: ReactNode | ((props: { index: number }) => ReactNode)
+}
+
+export interface ValueProps extends Omit<ItemProps, 'children'> {
+  id: WidgetsStoreProps['id']
+  index?: number
+}
+
+export interface ItemProps {
+  children: ReactNode
+  disabled?: boolean
+  TypographyProps?: TypographyProps
+}
+
+export type SpreadWidgetData = SpreadDataItem[]
+
+export type SpreadWidgetState = BaseWidgetState<
+  WrapperState<SpreadWidgetConfig> & { data: SpreadWidgetData }
+>
+
+export interface SpreadWidgetConfig {
+  formatter?: (value: number) => string
+  series?: SeriesConfig[]
+}
+
+export type SpreadDownloadConfig = DownloadItem<SpreadWidgetData>[]

package/src/widgets/stores/index.ts

@@ -0,0 +1,13 @@
+export { useWidgetStore, widgetStoreActions } from './widget-store'
+export { useWidgetSelector } from './use-widget-selector'
+export type {
+  BaseWidgetState,
+  ToolRegistration,
+  ToolTransformFunction,
+  ToolType,
+  WidgetsStoreProps,
+  WidgetState,
+  WidgetStore,
+  WidgetStoreActions,
+  WidgetStoreState,
+} from './types'

package/src/widgets/stores/types.ts

@@ -0,0 +1,203 @@
+import type { RefObject } from 'react'
+
+/**
+ * Tool type determines which pipeline a tool participates in.
+ * - 'data': transforms widget data (default)
+ * - 'config': transforms widget config/option
+ */
+export type ToolType = 'data' | 'config'
+
+export interface WidgetsStoreProps {
+  /** Unique identifier for the widget */
+  id: string
+  /** Type of widget */
+  type: string
+  /** Widget data - flexible to accommodate different widget types */
+  data: unknown
+  /** Original pre-pipeline data. Used by NoData to distinguish
+   *  "no data from API" from "pipeline tools filtered everything out".
+   *  Set automatically by executeToolPipeline — not a component prop. */
+  sourceData?: unknown
+  /** Loading state */
+  isLoading: boolean
+  /** Fetching state (e.g., for async data) */
+  isFetching: boolean
+  /** Error message if any */
+  error?: {
+    title?: string
+    message?: string
+  }
+  /** Whether widget is visible */
+  visible?: boolean
+  /** Reference to the widget ui instance */
+  refUI?: RefObject<HTMLElement | null>
+  /** Registered tools for the widget's transformation pipeline */
+  registeredTools?: ToolRegistration[]
+  /** Formatter function for widget values */
+  formatter?: (value: number) => string
+  /** Formatter function for widget label/category values */
+  labelFormatter?: (value: string | number) => string | number
+  /** Locale for number formatting (e.g., 'en-US', 'es-ES', 'fr-FR') */
+  locale?: string
+}
+
+/**
+ * Tool transformation function type
+ * Can be synchronous or asynchronous to support remote operations
+ */
+export type ToolTransformFunction = (data: unknown) => unknown
+
+/**
+ * Tool registration for widget pipeline
+ *
+ * @example Basic tool registration
+ * ```typescript
+ * registerTool(widgetId, {
+ *   id: 'searcher',
+ *   order: 10,
+ *   enabled: true,
+ *   fn: (data) => filterData(data),
+ * })
+ * ```
+ *
+ * @example Tool with dependencies
+ * ```typescript
+ * registerTool(widgetId, {
+ *   id: 'lock-selection',
+ *   order: 20,
+ *   enabled: true,
+ *   fn: (data) => lockData(data),
+ *   disables: ['searcher', 'relative-data'], // Disable these when active
+ * })
+ * ```
+ *
+ * Dependency Management:
+ * - Multiple tools can disable the same target (reference counting)
+ * - Target is only re-enabled when ALL disabling tools are inactive
+ * - Original enabled state is preserved and restored
+ * - Circular dependencies are detected and throw errors
+ */
+export interface ToolRegistration {
+  /** Unique tool identifier (e.g., 'searcher', 'relative-data') */
+  id: string
+  /** Execution priority - lower numbers execute first */
+  order: number
+  /** Transformation function */
+  fn: ToolTransformFunction
+  /** Whether tool is currently enabled */
+  enabled: boolean
+  /** 'data' (default) transforms data, 'config' transforms widget config/option */
+  type?: ToolType
+  /**
+   * Array of tool IDs to disable when this tool is active.
+   * During pipeline execution, if this tool is enabled, any tools listed
+   * in this array will be excluded from the pipeline.
+   *
+   * @example
+   * ```typescript
+   * disables: ['searcher', 'relative-data']
+   * ```
+   */
+  disables?: string[]
+}
+
+/**
+ * Base widget state interface
+ */
+export type BaseWidgetState<T> = WidgetsStoreProps & T
+
+/**
+ * Union type for all widget states
+ */
+export type WidgetState = BaseWidgetState<unknown>
+
+/**
+ * Widget store state with tool registration
+ */
+export interface WidgetStoreState {
+  /** Map of widget id to widget state */
+  widgets: Record<string, WidgetState>
+}
+
+/**
+ * Widget store actions
+ */
+export interface WidgetStoreActions {
+  /**
+   * Add or update a widget in the store
+   * @param id - Widget ID
+   * @param widget - Widget state properties to merge (accepts any object structure)
+   * @template T - Type of the widget state for type-safe access
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  setWidget: <T = any>(id: WidgetState['id'], widget: Partial<T>) => void
+
+  /**
+   * Remove a widget from the store
+   * @param id - Widget ID to remove
+   */
+  removeWidget: (id: WidgetState['id']) => void
+
+  /**
+   * Clear all widgets
+   */
+  clearWidgets: () => void
+
+  /**
+   * Get widget by ID
+   * @param id - Widget ID
+   * @returns Widget state or undefined if not found
+   */
+  getWidget: <T extends WidgetState = WidgetState>(
+    id: WidgetState['id'],
+  ) => T | undefined
+
+  /**
+   * Register a tool with the widget's transformation pipeline
+   * @param widgetId - Widget ID
+   * @param tool - Tool registration object
+   */
+  registerTool: (widgetId: string, tool: ToolRegistration) => void
+
+  /**
+   * Unregister a tool from the widget's transformation pipeline
+   * @param widgetId - Widget ID
+   * @param toolId - Tool ID to remove
+   */
+  unregisterTool: (widgetId: string, toolId: string) => void
+
+  /**
+   * Set tool enabled state
+   * @param widgetId - Widget ID
+   * @param toolId - Tool ID
+   * @param enabled - Whether tool should be enabled
+   */
+  setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) => void
+
+  /**
+   * Trigger pipeline re-execution by bumping the registeredTools reference.
+   * @param widgetId - Widget ID
+   */
+  triggerToolPipeline: (widgetId: string) => void
+
+  /**
+   * Execute the tool transformation pipeline
+   * Supports both synchronous and asynchronous tools
+   * @param widgetId - Widget ID
+   * @param sourceData - Original data to transform
+   */
+  executeToolPipeline: (widgetId: string, sourceData: unknown) => Promise<void>
+
+  /**
+   * Execute the config transformation pipeline
+   * Applies config-type tools to the base config, then sets the result on the widget
+   * @param widgetId - Widget ID
+   * @param baseConfig - Base config to transform
+   */
+  executeConfigPipeline: (widgetId: string, baseConfig: object) => Promise<void>
+}
+
+/**
+ * Complete widget store interface
+ */
+export type WidgetStore = WidgetStoreState & WidgetStoreActions