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

package/src/widgets/scatterplot/config.ts

@@ -0,0 +1,136 @@
+import {
+  getCommonOptions,
+  mergeEchartWidgetConfig,
+  type EchartOptionsProps,
+} from '../echart'
+import type {
+  ScatterplotConfig,
+  ScatterplotWidgetConfig,
+  ScatterplotWidgetData,
+} from './types'
+import {
+  scatterplotDataToCSV,
+  buildLegendConfig,
+  createTooltipFormatter,
+  createChartDownloadConfig,
+  applyYAxisFormatter,
+  applyXAxisFormatter,
+  buildSeriesLabelConfig,
+} from '../utils/chart-config'
+
+export const scatterplotDownloadConfig =
+  createChartDownloadConfig<ScatterplotWidgetData>(scatterplotDataToCSV)
+
+/**
+ * Generates ECharts configuration for X-Y scatter plot widgets with value axes, legend support, and CARTO qualitative color palette.
+ *
+ * @param props - Scatterplot configuration including data points and theme.
+ * @returns Widget config with ECharts option object.
+ */
+export function scatterplotConfig(
+  props: ScatterplotConfig,
+): ScatterplotWidgetConfig {
+  return {
+    type: 'scatterplot',
+    option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
+    labelFormatter: props.labelFormatter,
+  }
+}
+
+function getOption({
+  data = [],
+  theme,
+  formatter,
+  labelFormatter,
+}: ScatterplotConfig): EchartOptionsProps {
+  const hasLegend = data.length > 1
+
+  const xAxis = {
+    type: 'value' as const,
+    axisLine: { show: false },
+    axisTick: { show: false },
+    axisLabel: {
+      fontSize: theme.typography.overlineDelicate.fontSize,
+      fontFamily: theme.typography.overlineDelicate.fontFamily,
+      showMinLabel: true,
+      showMaxLabel: true,
+      hideOverlap: true,
+      padding: [
+        parseInt(theme.spacing(0.5)),
+        parseInt(theme.spacing(0.5)),
+        0,
+        parseInt(theme.spacing(0.5)),
+      ],
+      color: theme.palette.black[60],
+    },
+    splitLine: {
+      show: true,
+      lineStyle: { color: theme.palette.black[4] },
+    },
+  }
+
+  const yAxis = {
+    type: 'value' as const,
+    axisLabel: {
+      fontSize: theme.typography.overlineDelicate.fontSize,
+      fontFamily: theme.typography.overlineDelicate.fontFamily,
+      inside: false,
+      padding: [
+        0,
+        0,
+        parseInt(theme.spacing(1.25)),
+        parseInt(theme.spacing(3.25)),
+      ],
+      margin: 0,
+      show: true,
+      showMaxLabel: true,
+      showMinLabel: false,
+      align: 'right',
+      verticalAlign: 'bottom',
+    },
+    axisLine: { show: false },
+    axisTick: { show: false },
+    splitLine: {
+      show: true,
+      lineStyle: { color: theme.palette.black[4] },
+    },
+  }
+
+  return {
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
+    grid: {
+      ...(!hasLegend && { bottom: parseInt(theme.spacing(1)) }),
+      ...(hasLegend && { bottom: parseInt(theme.spacing(10)) }),
+    },
+    xAxis: applyXAxisFormatter(xAxis, labelFormatter),
+    yAxis: applyYAxisFormatter(yAxis, formatter),
+    tooltip: {
+      trigger: 'item',
+      // position: createTooltipPositioner(theme),
+      formatter: createTooltipFormatter((item) => {
+        const value = item.value as Record<string, string | number>
+        const index = item.encode?.y?.at(0)
+        const _value = value[index ?? '']
+
+        const formattedValue =
+          typeof _value === 'number' && formatter
+            ? formatter(_value)
+            : (_value ?? '')
+        const marker = typeof item.marker === 'string' ? item.marker : ''
+        const name = labelFormatter
+          ? String(labelFormatter(item.seriesName ?? ''))
+          : (item.seriesName ?? '')
+
+        return { name, seriesName: '', marker, value: formattedValue }
+      }),
+    },
+    color: Object.values(theme.palette.qualitative.bold),
+    series: data.map((_: unknown, index: number) => ({
+      datasetIndex: index,
+      type: 'scatter',
+      symbolSize: 8,
+      ...buildSeriesLabelConfig(formatter),
+    })),
+  } as EchartOptionsProps
+}

package/src/widgets/scatterplot/index.ts

@@ -0,0 +1,8 @@
+export type {
+  ScatterplotWidgetData,
+  ScatterplotWidgetState,
+  ScatterplotWidgetConfig,
+  ScatterplotConfig,
+} from './types'
+export { scatterplotConfig, scatterplotDownloadConfig } from './config'
+export { ScatterplotSkeleton } from './skeleton'

package/src/widgets/scatterplot/skeleton.tsx

@@ -0,0 +1,59 @@
+import { Box, Skeleton } from '@mui/material'
+import { styles } from './style'
+
+const SCATTER_POINTS = [
+  { left: '20%', top: '62%' },
+  { left: '26%', top: '70%' },
+  { left: '29%', top: '73%' },
+  { left: '38%', top: '63%' },
+  { left: '41%', top: '68%' },
+  { left: '47%', top: '62%' },
+  { left: '53%', top: '49%' },
+  { left: '56%', top: '55%' },
+  { left: '65%', top: '37%' },
+  { left: '68%', top: '43%' },
+  { left: '77%', top: '59%' },
+  { left: '25%', top: '30%' },
+  { left: '60%', top: '70%' },
+  { left: '10%', top: '55%' },
+  { left: '40%', top: '40%' },
+]
+
+export function ScatterplotSkeleton() {
+  return (
+    <Box sx={styles.skeleton.graph.container}>
+      {SCATTER_POINTS.map((point, index) => (
+        <Skeleton
+          key={`skeleton-point-${index}`}
+          variant='circular'
+          width={12}
+          height={12}
+          sx={{
+            position: 'absolute',
+            top: point.top,
+            left: point.left,
+            transform: 'translate(-50%, -50%)',
+          }}
+        />
+      ))}
+      {/* Legend */}
+      <Box sx={styles.skeleton.legend}>
+        {Array(2)
+          .fill(0)
+          .map((_, i) => (
+            <Box
+              key={`skeleton-${i}`}
+              sx={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: ({ spacing }) => spacing(1.5),
+              }}
+            >
+              <Skeleton variant='circular' width={8} height={8} />
+              <Skeleton width={48} height={8} />
+            </Box>
+          ))}
+      </Box>
+    </Box>
+  )
+}

package/src/widgets/scatterplot/style.ts

@@ -0,0 +1,21 @@
+import type { SxProps, Theme } from '@mui/material'
+import { baseSkeletonStyles } from '../utils/skeleton'
+
+export const styles = {
+  skeleton: {
+    graph: {
+      container: {
+        ...baseSkeletonStyles.graph.container,
+        position: 'relative',
+      },
+    },
+    legend: {
+      display: 'flex',
+      alignItems: 'center',
+      gap: ({ spacing }) => spacing(2),
+      height: ({ spacing }) => spacing(5),
+      position: 'absolute',
+      bottom: 0,
+    },
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/scatterplot/types.ts

@@ -0,0 +1,17 @@
+import type { EchartWidgetState } from '../echart'
+import type {
+  EchartWidgetOptionProps,
+  EchartWidgetProps,
+} from '../echart/types'
+import type { ConfigProps } from '../loader'
+
+export type ScatterplotWidgetData = [number, number][][]
+
+export type ScatterplotWidgetState = EchartWidgetState
+
+export type ScatterplotWidgetConfig = EchartWidgetProps & {
+  type: 'scatterplot'
+}
+
+export type ScatterplotConfig = ConfigProps &
+  EchartWidgetOptionProps<ScatterplotWidgetData>

package/src/widgets/selection-summary/index.ts

@@ -0,0 +1,6 @@
+export { WidgetSelectionSummary } from './selection-summary'
+
+export type {
+  WidgetSelectionSummaryProps,
+  SelectionSummaryLabels,
+} from './types'

package/src/widgets/selection-summary/selection-summary.tsx

@@ -0,0 +1,57 @@
+/* Selection Summary Component */
+
+import { Box, Button, Typography } from '@mui/material'
+import type {
+  WidgetSelectionSummaryProps,
+  SelectionSummaryLabels,
+} from './types'
+import { styles } from './style'
+
+const DEFAULT_SELECTION_LABELS: SelectionSummaryLabels = {
+  allSelected: 'All selected',
+  selections: (count: number) => `${count} selected`,
+  clear: 'Clear',
+}
+
+/**
+ * Displays the count of selected items with an optional clear button. Commonly used with the LockSelection action to show selection state in widgets.
+ *
+ * @example
+ * ```tsx
+ * <WidgetSelectionSummary
+ *   selections={selectedItems.length}
+ *   onClear={() => setSelectedItems([])}
+ * />
+ * ```
+ */
+export function WidgetSelectionSummary({
+  selections,
+  onClear,
+  labels,
+}: WidgetSelectionSummaryProps) {
+  const allSelectedLabel =
+    labels?.allSelected ?? DEFAULT_SELECTION_LABELS.allSelected
+
+  const selectionsLabel =
+    labels?.selections ?? DEFAULT_SELECTION_LABELS.selections
+
+  const clearLabel = labels?.clear ?? DEFAULT_SELECTION_LABELS.clear
+
+  const displayLabel =
+    selections > 0 ? selectionsLabel(selections) : allSelectedLabel
+
+  const showClearButton = selections > 0 && onClear
+
+  return (
+    <Box sx={styles.root}>
+      <Typography variant='caption' color='textSecondary' fontWeight={500}>
+        {displayLabel}
+      </Typography>
+      {showClearButton && (
+        <Button size='small' variant='text' onClick={onClear}>
+          {clearLabel}
+        </Button>
+      )}
+    </Box>
+  )
+}

package/src/widgets/selection-summary/style.ts

@@ -0,0 +1,10 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    alignItems: 'center',
+    flex: '0 0 auto',
+    gap: ({ spacing }) => spacing(0.5),
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/selection-summary/types.ts

@@ -0,0 +1,14 @@
+export interface WidgetSelectionSummaryProps {
+  selections: number
+  onClear?: () => void
+  labels?: Partial<SelectionSummaryLabels>
+}
+
+export interface SelectionSummaryLabels {
+  /** Label for "All selected" state */
+  allSelected: string
+  /** Label for number of selections */
+  selections: (count: number) => string
+  /** Label for clear button */
+  clear: string
+}

package/src/widgets/skeleton-loader/index.ts

@@ -0,0 +1,2 @@
+export { SkeletonLoader } from './skeleton-loader'
+export type { SkeletonLoaderProps } from './types'

package/src/widgets/skeleton-loader/skeleton-loader.test.tsx

@@ -0,0 +1,139 @@
+import { render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, test } from 'vitest'
+import { SkeletonLoader } from './skeleton-loader'
+import { useWidgetStore } from '../stores/widget-store'
+
+// Mock Skeleton component
+function MockSkeleton() {
+  return <div aria-label='Loading skeleton'>Loading...</div>
+}
+
+describe('SkeletonLoader', () => {
+  const widgetId = 'test-skeleton-widget'
+
+  beforeEach(() => {
+    useWidgetStore.getState().clearWidgets()
+  })
+
+  describe('when isLoading is true', () => {
+    test('renders skeleton component', () => {
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: true })
+
+      render(
+        <SkeletonLoader id={widgetId} Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.getByLabelText('Loading skeleton')).toBeTruthy()
+      expect(screen.queryByText('Content')).toBeNull()
+    })
+
+    test('returns null when Skeleton prop is null', () => {
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: true })
+
+      const { container } = render(
+        <SkeletonLoader id={widgetId} Skeleton={null}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(container.firstChild).toBeNull()
+    })
+  })
+
+  describe('when isLoading is false', () => {
+    test('renders children', () => {
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: false })
+
+      render(
+        <SkeletonLoader id={widgetId} Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.getByText('Content')).toBeTruthy()
+      expect(screen.queryByLabelText('Loading skeleton')).toBeNull()
+    })
+  })
+
+  describe('when isLoading is undefined', () => {
+    test('renders children', () => {
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: undefined })
+
+      render(
+        <SkeletonLoader id={widgetId} Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.getByText('Content')).toBeTruthy()
+      expect(screen.queryByLabelText('Loading skeleton')).toBeNull()
+    })
+  })
+
+  describe('when widget does not exist in store', () => {
+    test('renders children (isLoading is undefined)', () => {
+      render(
+        <SkeletonLoader id='non-existent-widget' Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.getByText('Content')).toBeTruthy()
+      expect(screen.queryByLabelText('Loading skeleton')).toBeNull()
+    })
+  })
+
+  describe('reactivity to store changes', () => {
+    test('updates from skeleton to content when isLoading becomes false', () => {
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: true })
+
+      const { rerender } = render(
+        <SkeletonLoader id={widgetId} Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.getByLabelText('Loading skeleton')).toBeTruthy()
+
+      // Update store with isLoading false
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: false })
+
+      // Force rerender to pick up store changes
+      rerender(
+        <SkeletonLoader id={widgetId} Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.queryByLabelText('Loading skeleton')).toBeNull()
+      expect(screen.getByText('Content')).toBeTruthy()
+    })
+
+    test('updates from content to skeleton when isLoading becomes true', () => {
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: false })
+
+      const { rerender } = render(
+        <SkeletonLoader id={widgetId} Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.getByText('Content')).toBeTruthy()
+
+      // Update store to isLoading true
+      useWidgetStore.getState().setWidget(widgetId, { isLoading: true })
+
+      // Force rerender to pick up store changes
+      rerender(
+        <SkeletonLoader id={widgetId} Skeleton={MockSkeleton}>
+          <div>Content</div>
+        </SkeletonLoader>,
+      )
+
+      expect(screen.getByLabelText('Loading skeleton')).toBeTruthy()
+      expect(screen.queryByText('Content')).toBeNull()
+    })
+  })
+})

package/src/widgets/skeleton-loader/skeleton-loader.tsx

@@ -0,0 +1,35 @@
+import type { SkeletonLoaderProps } from './types'
+import { useWidgetSelector } from '../stores/use-widget-selector'
+import { Suspense } from 'react'
+
+/**
+ * Displays a skeleton loading placeholder while widget data is loading. Subscribes to widget loading state in the store and renders the provided Skeleton component or children accordingly.
+ *
+ * @example
+ * ```tsx
+ * <SkeletonLoader id="sales-chart" Skeleton={BarSkeleton}>
+ *   <Bar id="sales-chart" />
+ * </SkeletonLoader>
+ * ```
+ */
+export function SkeletonLoader({
+  id,
+  children,
+  Skeleton,
+}: SkeletonLoaderProps) {
+  const isLoading = useWidgetSelector(id, (w) => w?.isLoading)
+
+  if (isLoading) {
+    if (!Skeleton) {
+      return null
+    }
+
+    return (
+      <Suspense fallback={null}>
+        <Skeleton />
+      </Suspense>
+    )
+  }
+
+  return children
+}

package/src/widgets/skeleton-loader/types.ts

@@ -0,0 +1,8 @@
+import type { ElementType, ReactNode } from 'react'
+import type { WidgetState } from '../stores/types'
+
+export interface SkeletonLoaderProps {
+  id: WidgetState['id']
+  Skeleton: ElementType | null
+  children: ReactNode
+}

package/src/widgets/spread/components/max-value.tsx

@@ -0,0 +1,29 @@
+import { type SpreadWidgetState, type ValueProps } from '../types'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
+import { Item } from '../../formula/components/item'
+import { defaultFormatter } from '../../utils/formatter'
+
+/**
+ * Displays the formatted maximum value for a spread widget data item.
+ */
+export function MaxValue({ id, index = 0, ...props }: ValueProps) {
+  const {
+    max,
+    color,
+    formatter: _formatter,
+  } = useWidgetSelector(id, (w) => {
+    const sw = w as SpreadWidgetState | undefined
+    return {
+      max: sw?.data[index]?.max,
+      color: sw?.data[index]?.color,
+      formatter: sw?.formatter,
+    }
+  })
+  const formatter = _formatter ?? defaultFormatter
+
+  return (
+    <Item TypographyProps={{ color }} {...props}>
+      {formatter(max ?? 0)}
+    </Item>
+  )
+}

package/src/widgets/spread/components/min-value.tsx

@@ -0,0 +1,29 @@
+import { type SpreadWidgetState, type ValueProps } from '../types'
+import { useWidgetSelector } from '../../stores/use-widget-selector'
+import { Item } from '../../formula/components/item'
+import { defaultFormatter } from '../../utils/formatter'
+
+/**
+ * Displays the formatted minimum value for a spread widget data item.
+ */
+export function MinValue({ id, index = 0, ...props }: ValueProps) {
+  const {
+    min,
+    color,
+    formatter: _formatter,
+  } = useWidgetSelector(id, (w) => {
+    const sw = w as SpreadWidgetState | undefined
+    return {
+      min: sw?.data[index]?.min,
+      color: sw?.data[index]?.color,
+      formatter: sw?.formatter,
+    }
+  })
+  const formatter = _formatter ?? defaultFormatter
+
+  return (
+    <Item TypographyProps={{ color }} {...props}>
+      {formatter(min ?? 0)}
+    </Item>
+  )
+}

package/src/widgets/spread/components/separator.tsx

@@ -0,0 +1,9 @@
+import { Item } from '../../formula/components/item'
+import type { ItemProps } from '../../formula/types'
+
+/**
+ * Renders a dash separator between the min and max values in a spread widget.
+ */
+export function Separator(props: Omit<ItemProps, 'children'>) {
+  return <Item {...props}>-</Item>
+}

package/src/widgets/spread/config.ts

@@ -0,0 +1,39 @@
+import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
+import type { ConfigProps } from '../loader/types'
+import type { SpreadWidgetConfig, SpreadWidgetData } from './types'
+
+/**
+ * Creates download configuration for spread widgets, supporting PNG (screenshot) and CSV (min/max data) exports.
+ *
+ * @param props - Configuration with `refUI` reference for PNG export.
+ * @returns Array of download items for use with the Download action.
+ */
+export function spreadDownloadConfig({
+  refUI,
+}: ConfigProps): DownloadItem<SpreadWidgetData>[] {
+  return [
+    {
+      ...downloadToPNG,
+      modifier: () => downloadToPNG.modifier(refUI),
+    },
+    {
+      ...downloadToCSV,
+      modifier: async (data) => {
+        const rows = data.map((item) => [item.min, item.max])
+
+        return downloadToCSV.modifier([['Min', 'Max'], ...rows])
+      },
+    },
+  ]
+}
+
+/**
+ * Returns the default configuration for spread (min/max value range) widgets.
+ *
+ * @returns Default spread widget config with empty series.
+ */
+export function spreadConfig(): SpreadWidgetConfig {
+  return {
+    series: [],
+  }
+}

package/src/widgets/spread/index.ts

@@ -0,0 +1,23 @@
+export { SpreadUI } from './spread-ui'
+export { SpreadSkeleton } from './skeleton'
+export { spreadConfig, spreadDownloadConfig } from './config'
+export { MinValue } from './components/min-value'
+export { MaxValue } from './components/max-value'
+export { Separator } from './components/separator'
+
+// Re-export formula components for convenience
+export { Item, Row, Prefix, Suffix, Series } from '../formula'
+
+export type {
+  RowProps,
+  ValueProps,
+  SpreadWidgetState,
+  SpreadWidgetConfig,
+  SpreadWidgetData,
+  SpreadDownloadConfig,
+  ItemProps,
+  SpreadDataItem,
+  SpreadUIProps,
+} from './types'
+
+export type { SeriesConfig } from '../formula/types'

package/src/widgets/spread/skeleton.tsx

@@ -0,0 +1,10 @@
+import { Box, Skeleton } from '@mui/material'
+import { styles } from './style'
+
+export function SpreadSkeleton() {
+  return (
+    <Box sx={styles.row} aria-label='Spread skeleton'>
+      <Skeleton width={120} height={32} />
+    </Box>
+  )
+}