@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/components/zoom-controls/zoom-controls.test.tsx

@@ -0,0 +1,101 @@
+import { describe, test, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ZoomControlsUI } from './zoom-controls'
+
+describe('ZoomControlsUI', () => {
+  const defaultProps = {
+    zoom: 10,
+    onChange: vi.fn(),
+  }
+
+  test('renders correctly with default props', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    expect(screen.getByLabelText('Increase zoom')).toBeTruthy()
+    expect(screen.getByLabelText('Decrease zoom')).toBeTruthy()
+    expect(screen.getByText('10')).toBeTruthy()
+  })
+
+  test('handles zoom increase correctly', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    fireEvent.click(screen.getByLabelText('Increase zoom'))
+    expect(defaultProps.onChange).toHaveBeenCalledWith(11)
+  })
+
+  test('handles zoom decrease correctly', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    fireEvent.click(screen.getByLabelText('Decrease zoom'))
+    expect(defaultProps.onChange).toHaveBeenCalledWith(9)
+  })
+
+  test('respects min and max zoom limits', () => {
+    const props = {
+      ...defaultProps,
+      zoom: 24,
+      maxZoom: 24,
+      minZoom: 5,
+    }
+
+    const { rerender } = render(<ZoomControlsUI {...props} />)
+
+    fireEvent.click(screen.getByLabelText('Increase zoom'))
+    expect(props.onChange).toHaveBeenCalledWith(24) // Should not exceed maxZoom
+
+    props.zoom = 5
+    rerender(<ZoomControlsUI {...props} />)
+
+    fireEvent.click(screen.getByLabelText('Decrease zoom'))
+    expect(props.onChange).toHaveBeenCalledWith(5) // Should not go below minZoom
+  })
+
+  test('renders reset button when onReset is provided', () => {
+    const props = {
+      ...defaultProps,
+      onReset: vi.fn(),
+    }
+
+    render(<ZoomControlsUI {...props} />)
+
+    const resetButton = screen.getByLabelText('Reset action')
+    expect(resetButton).toBeTruthy()
+
+    fireEvent.click(resetButton)
+    expect(props.onReset).toHaveBeenCalledTimes(1)
+  })
+
+  test('does not render reset button when onReset is not provided', () => {
+    render(<ZoomControlsUI {...defaultProps} />)
+
+    expect(screen.queryByLabelText('Reset action')).toBeNull()
+  })
+
+  test('hides zoom display when showZoom is false', () => {
+    render(<ZoomControlsUI {...defaultProps} showZoom={false} />)
+
+    expect(screen.queryByText('10')).toBeNull()
+  })
+
+  test('shows loading indicator when isLoading is true', () => {
+    render(<ZoomControlsUI {...defaultProps} isLoading={true} />)
+
+    expect(screen.getByRole('progressbar')).toBeTruthy()
+  })
+
+  test('renders in horizontal direction when specified', () => {
+    render(<ZoomControlsUI {...defaultProps} direction='horizontal' />)
+
+    // We can't check styles directly without jest-dom, so we'll skip this assertion
+    expect(screen.getByText('10')).toBeTruthy()
+  })
+
+  test('disables buttons when disabled prop is true', () => {
+    render(<ZoomControlsUI {...defaultProps} disabled={true} />)
+
+    const increaseButton = screen.getByLabelText('Increase zoom')
+    const decreaseButton = screen.getByLabelText('Decrease zoom')
+    expect(increaseButton.hasAttribute('disabled')).toBeTruthy()
+    expect(decreaseButton.hasAttribute('disabled')).toBeTruthy()
+  })
+})

package/src/components/zoom-controls/zoom-controls.tsx

@@ -0,0 +1,114 @@
+import {
+  IconButton,
+  Divider,
+  Box,
+  Typography,
+  CircularProgress,
+  Paper,
+} from '@mui/material'
+import {
+  AddOutlined,
+  RemoveOutlined,
+  CropFreeOutlined,
+} from '@mui/icons-material'
+import { styles } from './styles'
+import type { ZoomControlProps } from './types'
+import { useCallback, type JSX } from 'react'
+
+export function ZoomControlsUI({
+  zoom,
+  disabled,
+  direction = 'vertical',
+  reverse = false,
+  isLoading,
+  maxZoom = 24,
+  minZoom = 0,
+  PaperProps,
+  ResetViewProps = {
+    Icon: CropFreeOutlined,
+  },
+  showZoom = true,
+  onChange,
+  onReset,
+}: ZoomControlProps): JSX.Element {
+  const increaseZoom = useCallback(() => {
+    const newZoom = Math.min(maxZoom, zoom + 1)
+    onChange(newZoom)
+  }, [maxZoom, onChange, zoom])
+
+  const decreaseZoom = useCallback(() => {
+    const newZoom = Math.max(minZoom, zoom - 1)
+    onChange(newZoom)
+  }, [minZoom, onChange, zoom])
+
+  const displayZoom = Math.floor(zoom)
+
+  const dividerOrientation =
+    direction === 'vertical' ? 'horizontal' : 'vertical'
+
+  let flexDirection = direction === 'vertical' ? 'column' : 'row'
+
+  if (reverse) {
+    flexDirection += '-reverse'
+  }
+
+  return (
+    <Paper
+      sx={{
+        ...styles.paper,
+        flexDirection,
+      }}
+      {...PaperProps}
+    >
+      {onReset && (
+        <>
+          <IconButton
+            onClick={onReset}
+            aria-label='Reset action'
+            disabled={disabled}
+          >
+            <ResetViewProps.Icon />
+          </IconButton>
+          <Divider orientation={dividerOrientation} flexItem />
+        </>
+      )}
+      <IconButton
+        onClick={increaseZoom}
+        aria-label='Increase zoom'
+        disabled={disabled}
+      >
+        <AddOutlined />
+      </IconButton>
+      <Divider orientation={dividerOrientation} flexItem />
+      {showZoom && (
+        <>
+          <Box sx={styles.zoom}>
+            <Typography
+              display='block'
+              align='center'
+              color='textSecondary'
+              variant='overline'
+            >
+              {displayZoom}
+            </Typography>
+            {isLoading && (
+              <CircularProgress
+                sx={styles.circularProgress}
+                variant='indeterminate'
+                size={24}
+              />
+            )}
+          </Box>
+          <Divider orientation={dividerOrientation} flexItem />
+        </>
+      )}
+      <IconButton
+        onClick={decreaseZoom}
+        aria-label='Decrease zoom'
+        disabled={disabled}
+      >
+        <RemoveOutlined />
+      </IconButton>
+    </Paper>
+  )
+}

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useDebounce } from './use-debounce'
+export { useWidgetRef } from './use-widget-ref'

package/src/hooks/use-debounce.ts

@@ -0,0 +1,55 @@
+import { useEffect, useRef, useCallback } from 'react'
+
+/**
+ * Custom hook for debouncing a callback function.
+ *
+ * @param callback - The function to debounce
+ * @param delay - The delay in milliseconds (default: 300ms)
+ * @returns A debounced version of the callback
+ *
+ * @example
+ * ```tsx
+ * const debouncedSearch = useDebounce((searchText: string) => {
+ *   // Perform search
+ *   console.log('Searching for:', searchText)
+ * }, 300)
+ *
+ * // Call it anywhere
+ * debouncedSearch('react')
+ * ```
+ */
+export function useDebounce<TArgs extends unknown[], TReturn = void>(
+  callback: (...args: TArgs) => TReturn,
+  delay = 300,
+): (...args: TArgs) => void {
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const callbackRef = useRef(callback)
+
+  // Update callback ref when callback changes
+  useEffect(() => {
+    callbackRef.current = callback
+  }, [callback])
+
+  // Cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+    }
+  }, [])
+
+  const debouncedCallback = useCallback(
+    (...args: TArgs) => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current)
+      }
+      timeoutRef.current = setTimeout(() => {
+        callbackRef.current(...args)
+      }, delay)
+    },
+    [delay],
+  )
+
+  return debouncedCallback
+}

package/src/hooks/use-skeleton.test.tsx

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import { useSkeleton } from './use-skeleton'
+
+describe('useSkeleton', () => {
+  test('should return true if loading', () => {
+    const { result } = renderHook(() => useSkeleton(true))
+
+    expect(result.current).toBe(true)
+  })
+
+  test('should return false if not loading', () => {
+    const { result } = renderHook(() => useSkeleton(false))
+
+    expect(result.current).toBe(false)
+  })
+
+  test('should return false if skeleton was already rendered', () => {
+    const { result, rerender } = renderHook(
+      ({ showSkeleton }) => useSkeleton(showSkeleton),
+      { initialProps: { showSkeleton: true } },
+    )
+
+    expect(result.current).toBe(true)
+
+    rerender({ showSkeleton: false })
+    expect(result.current).toBe(false)
+
+    rerender({ showSkeleton: true })
+    expect(result.current).toBe(false)
+  })
+})

package/src/hooks/use-skeleton.ts

@@ -0,0 +1,19 @@
+import { useState } from 'react'
+
+export function useSkeleton(isLoading: boolean) {
+  // Track render phase: 0=never shown, 1=showing now, 2=already shown
+  const [phase, setPhase] = useState(() => (isLoading ? 1 : 0))
+
+  // Transition from phase 0 to 1 when loading starts
+  if (isLoading && phase === 0) {
+    setPhase(1)
+  }
+
+  // Transition from phase 1 to 2 when loading ends (skeleton was shown, now done)
+  if (!isLoading && phase === 1) {
+    setPhase(2)
+  }
+
+  // Show skeleton only in phase 1 (first time loading)
+  return phase === 1
+}

package/src/hooks/use-widget-ref.ts

@@ -0,0 +1,33 @@
+import { useEffect, useRef } from 'react'
+import { useWidgetStore } from '../widgets/stores/widget-store'
+
+/**
+ * Custom hook for registering a DOM element ref with the widget store.
+ * This allows other parts of the application to access the widget's DOM element.
+ *
+ * @param widgetId - The widget ID to register the ref under
+ * @returns A ref object to attach to the DOM element
+ *
+ * @example
+ * ```tsx
+ * function MyWidget({ id }: { id: string }) {
+ *   const ref = useWidgetRef<HTMLDivElement>(id)
+ *
+ *   return <div ref={ref}>Widget content</div>
+ * }
+ * ```
+ */
+export function useWidgetRef<T extends HTMLElement = HTMLElement>(
+  widgetId: string,
+) {
+  const ref = useRef<T | null>(null)
+  const setWidget = useWidgetStore((store) => store.setWidget)
+
+  useEffect(() => {
+    if (ref.current) {
+      setWidget(widgetId, { refUI: ref })
+    }
+  }, [widgetId, setWidget])
+
+  return ref
+}

package/src/widgets/README.md

@@ -0,0 +1,277 @@
+# Widgets Architecture
+
+> **⚠️ Project-Side Implementation Required**
+>
+> Starting with v4.3.x, widgets should be implemented on the **project side** using the building blocks provided by this library. The library exports UI components, configuration helpers, and state management hooks—you compose them in your project to create complete widgets.
+>
+> **Benefits:**
+>
+> - Full customization tailored to your project's specific needs
+> - Direct integration with your data sources and state management
+> - Independent updates without waiting for library releases
+> - Include only the widget features you actually need
+>
+> **See the internal Storybook for complete implementation examples** of all widget types (Bar, Pie, Histogram, Timeseries, Scatterplot, Formula, etc.).
+
+---
+
+This directory contains the CARTO PS widget system with an optimized architecture for code reuse and maintainability.
+
+## Directory Structure
+
+```
+widgets/
+├── _shared/              # Shared utilities (internal, not exported)
+│   ├── chart-config/     # Chart widget configuration utilities
+│   │   ├── config-factory.ts     # Factory for creating chart widget configs
+│   │   ├── csv-modifiers.ts      # CSV export utilities
+│   │   ├── option-builders.ts    # EChart option builders
+│   │   └── index.ts             # Exports
+│   └── skeleton/         # Shared skeleton styles
+│       ├── styles.ts            # Base skeleton container styles
+│       └── index.ts            # Exports
+├── bar/                  # Bar chart widget
+├── histogram/            # Histogram widget
+├── pie/                  # Pie chart widget
+├── scatterplot/          # Scatterplot widget
+├── timeseries/           # Timeseries/line chart widget
+├── formula/              # Formula/KPI widget
+├── note/                 # Note widget
+├── markdown/             # Markdown renderer
+├── echart/               # Base EChart component
+├── wrapper/              # Widget wrapper with header/actions
+├── actions/              # Download, fullscreen actions
+├── config-loader/        # Config loading system
+├── skeleton-loader/      # Skeleton components
+├── stores/               # Zustand widget state
+├── loader/               # WidgetLoader container
+└── widget/               # Main widget orchestrator
+```
+
+## Shared Utilities (`_shared/`)
+
+The `_shared` directory contains internal utilities used by multiple widgets. These are **not exported** from the package and are only for internal use.
+
+### Chart Config Factory
+
+**File:** `_shared/chart-config/config-factory.ts`
+
+Creates standardized chart widget configurations, eliminating code duplication.
+
+**Example:**
+
+```typescript
+import {
+  createChartWidgetConfig,
+  flattenObjectArrayToCSV,
+} from '../_shared/chart-config'
+
+export const myWidgetConfig = createChartWidgetConfig({
+  type: 'my-widget',
+  getOptions: ({ data, theme }) => ({
+    // EChart configuration
+    legend: buildLegendConfig(hasLegend),
+    // ...
+  }),
+  csvModifier: (data) => flattenObjectArrayToCSV(data),
+})
+```
+
+### CSV Modifiers
+
+**File:** `_shared/chart-config/csv-modifiers.ts`
+
+- `flattenObjectArrayToCSV()` - For widgets with object-based data (bar, pie, histogram, timeseries)
+- `scatterplotDataToCSV()` - For scatterplot with array-based data
+
+### EChart Option Builders
+
+**File:** `_shared/chart-config/option-builders.ts`
+
+- `buildLegendConfig(hasLegend)` - Standard legend configuration
+- `buildGridConfig(hasLegend, theme, additionalConfig?)` - Grid with legend-aware spacing
+- `createTooltipPositioner(theme)` - Tooltip positioning with overflow handling
+
+### Skeleton Styles
+
+**File:** `_shared/skeleton/styles.ts`
+
+- `baseSkeletonStyles.graph.container` - Base container styles for all chart skeletons
+
+## Creating a New Chart Widget
+
+1. **Create widget directory:**
+
+   ```bash
+   mkdir src/widgets/my-widget
+   ```
+
+2. **Create `types.ts`:**
+
+   ```typescript
+   import type { BaseWidgetProps } from '../widget/types'
+   import type { BaseConfig } from '../config-loader'
+   import type {
+     EchartWidgetConfig,
+     EchartWidgetData,
+     EchartWidgetState,
+   } from '../echart'
+
+   export interface MyWidgetProps extends BaseWidgetProps<MyWidgetConfig> {
+     type: 'my-widget'
+     data: MyWidgetData | undefined
+   }
+
+   export type MyWidgetData = EchartWidgetData
+   export type MyWidgetState = EchartWidgetState
+   export type MyWidgetConfig = MyConfig &
+     EchartWidgetConfig & { type: MyWidgetProps['type'] }
+
+   export interface MyConfig extends Omit<BaseConfig, 'data'> {
+     data?: MyWidgetData
+   }
+   ```
+
+3. **Create `config.ts` using shared factory:**
+
+   ```typescript
+   import type { EchartOptionsProps } from '../echart'
+   import type { MyConfig, MyWidgetConfig, MyWidgetData } from './types'
+   import {
+     createChartWidgetConfig,
+     flattenObjectArrayToCSV,
+     buildLegendConfig,
+     buildGridConfig,
+   } from '../_shared/chart-config'
+
+   export const myWidgetConfig = createChartWidgetConfig<
+     MyWidgetData,
+     MyConfig
+   >({
+     type: 'my-widget',
+     getOptions,
+     csvModifier: (data) => flattenObjectArrayToCSV(data),
+   })
+
+   function getOptions({
+     data = [],
+     theme,
+   }: Omit<MyConfig, 'refUI'>): EchartOptionsProps {
+     const hasLegend = (data?.length ?? 0) > 1
+     return {
+       legend: buildLegendConfig(hasLegend),
+       grid: buildGridConfig(hasLegend, theme),
+       // ... widget-specific configuration
+     }
+   }
+   ```
+
+4. **Create `skeleton.tsx` and `style.ts`:**
+
+   ```typescript
+   // style.ts
+   import type { SxProps, Theme } from '@mui/material'
+   import { baseSkeletonStyles } from '../_shared/skeleton'
+
+   export const styles = {
+     skeleton: {
+       graph: baseSkeletonStyles.graph,
+       // Add widget-specific styles here
+     },
+   } satisfies Record<string, SxProps<Theme>>
+   ```
+
+5. **Create `index.ts`:**
+
+   ```typescript
+   export type {
+     MyWidgetProps,
+     MyWidgetData,
+     MyWidgetState,
+     MyWidgetConfig,
+     MyConfig,
+   } from './types'
+   export { myWidgetConfig } from './config'
+   export { MyWidgetSkeleton as Skeleton } from './skeleton'
+   ```
+
+6. **Run build automation:**
+
+   ```bash
+   pnpm generate:exports
+   ```
+
+   This will automatically:
+   - Add the widget to vite.config.ts entry points
+   - Add the widget to package.json exports
+   - Validate all exports
+
+## Build Automation
+
+### Scripts
+
+- `pnpm exports:validate` - Validate all package.json exports have corresponding source files
+
+### How It Works
+
+**package.json is the source of truth!**
+
+The `scripts/generate-widget-config.ts` script:
+
+1. Reads widget exports from `package.json`
+2. Converts export paths to source file paths
+3. Generates vite entry points dynamically
+4. Validates that all exports have corresponding source files
+
+The script uses **Node 22's native TypeScript support** with the `--experimental-strip-types` flag, so no compilation step is needed!
+
+### Adding a New Widget
+
+1. **Create widget folder and files:**
+
+   ```bash
+   mkdir src/widgets/my-widget
+   # Create index.ts, config.ts, types.ts, etc.
+   ```
+
+2. **Add export to package.json:**
+
+   ```json
+   {
+     "exports": {
+       "./widgets/my-widget": {
+         "import": "./dist/widgets/my-widget.js",
+         "types": "./dist/types/widgets/my-widget/index.d.ts"
+       }
+     }
+   }
+   ```
+
+3. **Build:**
+   ```bash
+   pnpm build
+   ```
+
+The vite config automatically reads from package.json and builds all declared exports!
+
+## Code Reduction Achieved
+
+| Widget                | Before     | After     | Reduction |
+| --------------------- | ---------- | --------- | --------- |
+| bar/config.ts         | ~150 lines | ~65 lines | ~57%      |
+| histogram/config.ts   | ~155 lines | ~68 lines | ~56%      |
+| pie/config.ts         | ~160 lines | ~50 lines | ~69%      |
+| scatterplot/config.ts | ~145 lines | ~90 lines | ~38%      |
+| timeseries/config.ts  | ~130 lines | ~70 lines | ~46%      |
+
+**Total:** ~400-500 lines of duplicated code eliminated
+
+## Benefits
+
+✅ **Reduced Duplication** - Shared utilities eliminate repeated code
+✅ **Better Maintainability** - Changes to common patterns update all widgets
+✅ **Automated Builds** - No manual vite/package.json updates needed
+✅ **Consistent Patterns** - All widgets follow the same structure
+✅ **Type Safety** - Full TypeScript support throughout
+✅ **Easy to Extend** - Adding new widgets is straightforward
+✅ **Backwards Compatible** - All external imports remain unchanged

package/src/widgets/_shared/chart-config/config-factory.ts

@@ -0,0 +1,67 @@
+import type { EchartOptionsProps, EchartWidgetData } from '../../echart'
+
+/**
+ * Base configuration interface for chart widgets
+ */
+export interface ChartWidgetBaseConfig<TData = EchartWidgetData> {
+  data?: TData
+}
+
+/**
+ * Parameters for creating a chart widget configuration
+ */
+export interface CreateChartWidgetConfigParams<
+  TData = EchartWidgetData,
+  TConfig extends ChartWidgetBaseConfig<TData> = ChartWidgetBaseConfig<TData>,
+  TType extends string = string,
+> {
+  /** Widget type identifier (e.g., 'bar', 'pie', 'histogram') */
+  type: TType
+  /** Function to get EChart options from config */
+  getOptions: (config: TConfig) => EchartOptionsProps
+}
+
+/**
+ * Return type of the chart widget config function
+ */
+export type ChartWidgetConfigResult<
+  TData = EchartWidgetData,
+  TConfig extends ChartWidgetBaseConfig<TData> = ChartWidgetBaseConfig<TData>,
+  TType extends string = string,
+> = TConfig & {
+  type: TType
+}
+
+/**
+ * Factory function to create a standardized chart widget config function.
+ * This eliminates duplication across chart widgets by providing a common structure.
+ *
+ * @example
+ * ```ts
+ * export const barConfig = createChartWidgetConfig({
+ *   type: 'bar' as const,
+ *   getOptions: ({ data, theme }) => ({
+ *     // EChart configuration
+ *   }),
+ *   csvModifier: (data) => flattenObjectArrayToCSV(data),
+ * })
+ * ```
+ */
+export function createChartWidgetConfig<
+  TData = EchartWidgetData,
+  TConfig extends ChartWidgetBaseConfig<TData> = ChartWidgetBaseConfig<TData>,
+  TType extends string = string,
+>({
+  type,
+  getOptions,
+}: CreateChartWidgetConfigParams<TData, TConfig, TType>): (
+  config: TConfig,
+) => ChartWidgetConfigResult<TData, TConfig, TType> {
+  return function (config: TConfig) {
+    return {
+      ...config,
+      option: getOptions(config),
+      type: type,
+    } as ChartWidgetConfigResult<TData, TConfig, TType>
+  }
+}