@carto/ps-react-ui 4.3.3 → 4.3.5

package/src/widgets/echart/types.ts

@@ -0,0 +1,45 @@
+import type { EChartsOption } from 'echarts'
+import type * as echarts from 'echarts'
+import type { BaseWidgetState } from '../stores/types'
+import type { Ref } from 'react'
+import { theme as CartoTheme } from '@carto/meridian-ds/theme'
+
+export type EchartOptionsProps = EChartsOption
+export type EchartReplaceMerge = string[]
+
+export interface EchartUIProps {
+  id: string
+  option: EchartOptionsProps
+  className?: string
+  init?: echarts.EChartsInitOpts
+  replaceMerge?: EchartReplaceMerge
+  style?: React.CSSProperties
+  ref?: Ref<echarts.ECharts>
+  onEvents?: Record<string, Parameters<echarts.ECharts['on']>[2]>
+}
+
+export interface EchartProps {
+  id: EchartUIProps['id']
+}
+
+export type EchartWidgetData = Record<string, string | number>[][]
+
+export type EchartWidgetState = BaseWidgetState<{
+  option: EchartUIProps['option']
+  onEvents?: EchartUIProps['onEvents']
+  init?: EchartUIProps['init']
+  replaceMerge?: EchartReplaceMerge
+}>
+
+export interface EchartWidgetOptionProps<D> {
+  data?: D
+  theme: typeof CartoTheme
+  formatter?: (value: number) => string
+}
+
+export interface EchartWidgetProps {
+  type: string
+  option: EchartUIProps['option']
+  onEvents?: EchartUIProps['onEvents']
+  replaceMerge?: EchartReplaceMerge
+}

package/src/widgets/echart/utils.ts

@@ -0,0 +1,169 @@
+import deepmerge from 'deepmerge'
+import type { EchartOptionsProps } from './types'
+import type { Theme } from '@mui/material'
+import { DEFAULT_STACK_GROUP } from './const'
+
+export function mergeEchartWidgetConfig<T extends EchartOptionsProps>(
+  ...options: [T | undefined, T | undefined]
+): T {
+  return deepmerge(options[0] ?? {}, options[1] ?? {}, {
+    customMerge: (key) => {
+      if (key === 'color') {
+        return (_, b: T['color']) => b
+      }
+      if (key === 'series') {
+        return (a: T['series'][], b: T['series'][]) => {
+          if (!a.length) return a // If there is no series in a, return a as is
+
+          const mergedSeries = b?.map((bItem, index) => {
+            const aItem = a?.[index] ?? {}
+            return deepmerge(aItem, bItem as object)
+          })
+          return mergedSeries
+        }
+      }
+    },
+  }) as T
+}
+
+export function getEChartZoomConfig(
+  zoom: boolean,
+  { start, end }: { start: number; end: number } = { start: 0, end: 100 },
+  {
+    inside = true,
+    xSlider = true,
+    ySlider = false,
+    showSliders = true,
+    xAxisLabelFormatter,
+  } = {} as {
+    inside?: boolean
+    xSlider?: boolean
+    ySlider?: boolean
+    showSliders?: boolean
+    xAxisLabelFormatter?: (value: number) => string
+  },
+  theme?: Theme,
+) {
+  const sliderStyles = theme ? getEChartZoomSliderStyles(theme) : {}
+
+  return {
+    dataZoom: [
+      inside && {
+        throttle: 0,
+        type: 'inside',
+        xAxisIndex: xSlider ? [0] : [],
+        yAxisIndex: ySlider ? [0] : [],
+        show: zoom,
+        zoomLock: !zoom,
+        start,
+        end,
+      },
+      inside &&
+        ySlider && {
+          throttle: 0,
+          type: 'inside',
+          show: zoom,
+          zoomLock: !zoom,
+          start,
+          end,
+          orientation: 'vertical',
+        },
+      xSlider && {
+        throttle: 0,
+        type: 'slider',
+        xAxisIndex: [0],
+        bottom: 0,
+        height: parseInt(theme?.spacing?.(4) ?? '32'),
+        show: zoom && showSliders,
+        zoomLock: !zoom,
+        start,
+        end,
+        labelFormatter: xAxisLabelFormatter,
+        showDetail: false,
+        ...sliderStyles,
+        brushSelect: false,
+        moveHandleSize: 8,
+        handleSize: '100%',
+        handleIcon:
+          'image://data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOSIgaGVpZ2h0PSIzNiIgdmlld0JveD0iMCAwIDkgMzYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHg9IjAuNSIgeT0iLTAuNSIgd2lkdGg9IjgiIGhlaWdodD0iMTgiIHJ4PSI0IiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAwIDI3KSIgZmlsbD0id2hpdGUiIHN0cm9rZT0iIzM1OEJFNyIvPgo8cmVjdCB3aWR0aD0iMyIgaGVpZ2h0PSIyIiByeD0iMSIgdHJhbnNmb3JtPSJtYXRyaXgoMSAwIDAgLTEgMyAyMykiIGZpbGw9IiMzNThCRTciLz4KPHJlY3Qgd2lkdGg9IjMiIGhlaWdodD0iMiIgcng9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIC0xIDMgMTkpIiBmaWxsPSIjMzU4QkU3Ii8+CjxyZWN0IHdpZHRoPSIzIiBoZWlnaHQ9IjIiIHJ4PSIxIiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAzIDE1KSIgZmlsbD0iIzM1OEJFNyIvPgo8L3N2Zz4=',
+      },
+      ySlider && {
+        throttle: 0,
+        type: 'slider',
+        left: parseInt(theme?.spacing?.(6) ?? '48'),
+        width: parseInt(theme?.spacing?.(4) ?? '32'),
+        yAxisIndex: [0],
+        show: zoom && showSliders,
+        zoomLock: !zoom,
+        start,
+        end,
+        ...sliderStyles,
+        brushSelect: false,
+        moveHandleSize: 8,
+        handleSize: '100%',
+        handleIcon:
+          'image://data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzYiIGhlaWdodD0iOSIgdmlld0JveD0iMCAwIDM2IDkiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHg9IjAuNSIgeT0iMC41IiB3aWR0aD0iOCIgaGVpZ2h0PSIxOCIgcng9IjQiIHRyYW5zZm9ybT0icm90YXRlKC05MCAwLjUgMC41KSIgZmlsbD0id2hpdGUiIHN0cm9rZT0iIzM1OEJFNyIvPgo8cmVjdCB3aWR0aD0iMyIgaGVpZ2h0PSIyIiByeD0iMSIgdHJhbnNmb3JtPSJyb3RhdGUoLTkwIDEzIDYpIiBmaWxsPSIjMzU4QkU3Ii8+CjxyZWN0IHdpZHRoPSIzIiBoZWlnaHQ9IjIiIHJ4PSIxIiB0cmFuc2Zvcm09InJvdGF0ZSgtOTAgMTcgNikiIGZpbGw9IiMzNThCRTciLz4KPHJlY3Qgd2lkdGg9IjMiIGhlaWdodD0iMiIgcng9IjEiIHRyYW5zZm9ybT0icm90YXRlKC05MCAyMSA2KSIgZmlsbD0iIzM1OEJFNyIvPgo8L3N2Zz4=',
+      },
+    ].filter((d) => !!d),
+  }
+}
+
+function getEChartZoomSliderStyles(theme: Theme) {
+  return {
+    fillerColor: 'rgba(53, 139, 231, 0.25)',
+    borderColor: 'rgba(53, 139, 231, 0.3)',
+    borderWidth: 0.5,
+    backgroundColor: 'transparent',
+    borderRadius: 4,
+    dataBackground: {
+      lineStyle: {
+        opacity: 0,
+      },
+      areaStyle: {
+        opacity: 1,
+        color: theme.palette.secondary.main,
+      },
+    },
+    selectedDataBackground: {
+      lineStyle: {
+        opacity: 0,
+      },
+      areaStyle: {
+        opacity: 1,
+        color: theme.palette.secondary.main,
+      },
+    },
+    handleStyle: {
+      color: theme.palette.common.white,
+      borderColor: 'rgba(3, 111, 226, 0.08)',
+      borderWidth: 1,
+      shadowBlur: 3,
+      shadowColor: 'rgba(0, 0, 0, 0.1)',
+      shadowOffsetX: 0,
+      shadowOffsetY: 1,
+    },
+    textStyle: {
+      color: theme.palette.black[60],
+      fontSize: parseInt(theme.typography.overlineDelicate.fontSize as string),
+      fontFamily: theme.typography.overlineDelicate.fontFamily,
+    },
+  } as const
+}
+
+export function getEChartBrushConfig(brush: boolean) {
+  return brush
+    ? {
+        brush: {
+          brushType: 'rect',
+          brushMode: 'single',
+        },
+      }
+    : {}
+}
+
+export function getEChartStackConfig(
+  stack: boolean,
+  stackGroup: string = DEFAULT_STACK_GROUP,
+) {
+  return { stack: stack ? stackGroup : undefined }
+}

package/src/widgets/error/error.test.tsx

@@ -0,0 +1,331 @@
+import { render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, test } from 'vitest'
+import { WidgetError } from './error'
+import { useWidgetStore } from '../stores/widget-store'
+
+describe('WidgetError', () => {
+  const widgetId = 'test-error-widget'
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  describe('when error exists', () => {
+    test('renders Error UI with default title and message when error is empty object', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: {},
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Error')).toBeTruthy()
+      expect(
+        screen.getByText(
+          'An error occurred while loading the widget. Please try again.',
+        ),
+      ).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders custom title with default message', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: { title: 'Database Connection Failed' },
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Database Connection Failed')).toBeTruthy()
+      expect(
+        screen.getByText(
+          'An error occurred while loading the widget. Please try again.',
+        ),
+      ).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders default title with custom message', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: { message: 'The server returned a 500 error.' },
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Error')).toBeTruthy()
+      expect(screen.getByText('The server returned a 500 error.')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('renders both custom title and message', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: {
+          title: 'Network Error',
+          message:
+            'Unable to connect to the API. Check your internet connection.',
+        },
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Network Error')).toBeTruthy()
+      expect(
+        screen.getByText(
+          'Unable to connect to the API. Check your internet connection.',
+        ),
+      ).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('uses defaults when title and message are empty strings', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: {
+          title: 'Error',
+          message:
+            'An error occurred while loading the widget. Please try again.',
+        },
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Error')).toBeTruthy()
+      expect(
+        screen.getByText(
+          'An error occurred while loading the widget. Please try again.',
+        ),
+      ).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+  })
+
+  describe('when no error exists', () => {
+    test('renders children when error is undefined', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: undefined,
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('Error')).toBeNull()
+    })
+
+    test('renders children when widget has no error property', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('Error')).toBeNull()
+    })
+  })
+
+  describe('loading states', () => {
+    test('renders children when isLoading is true, even with error', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: true,
+        isFetching: false,
+        error: { title: 'Some error' },
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('Error')).toBeNull()
+    })
+
+    test('renders children when isFetching is true, even with error', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: true,
+        error: { title: 'Some error' },
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('Error')).toBeNull()
+    })
+
+    test('renders children when both isLoading and isFetching are true, even with error', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: true,
+        isFetching: true,
+        error: { title: 'Some error' },
+      })
+
+      render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('Error')).toBeNull()
+    })
+  })
+
+  describe('reactivity', () => {
+    test('updates when error appears', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: undefined,
+      })
+
+      const { rerender } = render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+
+      // Add error
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: { title: 'Failed to load' },
+      })
+
+      rerender(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Failed to load')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+    })
+
+    test('updates when error clears', () => {
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: { title: 'Failed to load' },
+      })
+
+      const { rerender } = render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Failed to load')).toBeTruthy()
+
+      // Clear error
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: undefined,
+      })
+
+      rerender(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('Failed to load')).toBeNull()
+    })
+
+    test('transitions from loading to error to success', () => {
+      // Start loading
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: true,
+        isFetching: false,
+        error: undefined,
+      })
+
+      const { rerender } = render(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+
+      // Error occurs
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: { title: 'Network error' },
+      })
+
+      rerender(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Network error')).toBeTruthy()
+      expect(screen.queryByText('Widget Content')).toBeNull()
+
+      // Error clears on retry
+      useWidgetStore.getState().setWidget(widgetId, {
+        isLoading: false,
+        isFetching: false,
+        error: undefined,
+      })
+
+      rerender(
+        <WidgetError id={widgetId}>
+          <div>Widget Content</div>
+        </WidgetError>,
+      )
+
+      expect(screen.getByText('Widget Content')).toBeTruthy()
+      expect(screen.queryByText('Network error')).toBeNull()
+    })
+  })
+})

package/src/widgets/error/error.tsx

@@ -0,0 +1,40 @@
+import { Alert, AlertTitle } from '@mui/material'
+import { useWidgetStore } from '../stores/widget-store'
+import { useShallow } from 'zustand/shallow'
+import type { WidgetErrorProps } from './types'
+
+export function WidgetError({ id, children }: WidgetErrorProps) {
+  const widget = useWidgetStore(
+    useShallow((state) => {
+      const w = state.widgets[id]
+      return {
+        isLoading: w?.isLoading,
+        isFetching: w?.isFetching,
+        error: w?.error,
+      }
+    }),
+  )
+
+  // Don't show error during loading/fetching states
+  if (widget?.isLoading || widget?.isFetching) {
+    return children
+  }
+
+  // Show error UI if error exists
+  if (widget?.error) {
+    const errorTitle = widget.error.title ?? 'Error'
+    const errorMessage =
+      widget.error.message ??
+      'An error occurred while loading the widget. Please try again.'
+
+    return (
+      <Alert severity='error'>
+        <AlertTitle>{errorTitle}</AlertTitle>
+        {errorMessage}
+      </Alert>
+    )
+  }
+
+  // No error, render children
+  return children
+}

package/src/widgets/error/index.ts

@@ -0,0 +1,2 @@
+export { WidgetError } from './error'
+export type { WidgetErrorProps } from './types'

package/src/widgets/error/types.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react'
+import type { WidgetState } from '../stores/types'
+
+export interface WidgetErrorProps {
+  /**
+   * Widget ID to fetch error state from store
+   */
+  id: WidgetState['id']
+
+  /**
+   * Children to render when no error exists
+   */
+  children: ReactNode
+}