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

package/src/widgets/formula/types.ts

@@ -0,0 +1,50 @@
+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'
+
+export interface FormulaUIProps {
+  id: WidgetsStoreProps['id']
+}
+
+export interface DataItem {
+  value: 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 FormulaWidgetData = DataItem[]
+
+export interface SeriesConfig {
+  name: string
+  color?: string
+}
+
+export type FormulaWidgetState = BaseWidgetState<
+  WrapperState<FormulaWidgetConfig> & { data: FormulaWidgetData }
+>
+
+export interface FormulaWidgetConfig {
+  formatter?: (value: number) => string
+  series?: SeriesConfig[]
+}
+
+export type FormulaDownloadConfig = DownloadItem<FormulaWidgetData>[]

package/src/widgets/histogram/config.ts

@@ -0,0 +1,230 @@
+import {
+  getCommonOptions,
+  mergeEchartWidgetConfig,
+  type EchartOptionsProps,
+} from '../echart'
+import type { HistogramConfig, HistogramWidgetConfig } from './types'
+import {
+  buildLegendConfig,
+  buildGridConfig,
+  createTooltipPositioner,
+  createTooltipFormatter,
+  niceNum,
+  buildHistogramSeriesLabelConfig,
+} from '../utils/chart-config'
+import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
+import type { ConfigProps } from '../loader/types'
+
+export interface HistogramDownloadConfigProps extends ConfigProps {
+  ticks: number[]
+  labelFormatter?: (value: string | number) => string | number
+}
+
+export function histogramDataToCSV(
+  data: number[][],
+  ticks: number[],
+  labelFormatter?: (value: string | number) => string | number,
+): string[][] {
+  if (!data?.length || data[0]?.length === 0) return []
+
+  const dataLength = data[0]?.length ?? 0
+  const labels = createAxisLabels(dataLength, ticks, labelFormatter)
+  const seriesCount = data.length
+  const isMulti = seriesCount > 1
+
+  const headers = isMulti
+    ? [
+        'Bin',
+        ...Array.from({ length: seriesCount }, (_, i) => `Series ${i + 1}`),
+      ]
+    : ['Bin', 'Value']
+
+  return [
+    headers,
+    ...labels.map((label, i) => [
+      label,
+      ...data.map((series) => String(series[i] ?? 0)),
+    ]),
+  ]
+}
+
+export function histogramDownloadConfig({
+  refUI,
+  ticks,
+  labelFormatter,
+}: HistogramDownloadConfigProps): DownloadItem<number[][]>[] {
+  return [
+    {
+      ...downloadToPNG,
+      modifier: () => downloadToPNG.modifier(refUI),
+    },
+    {
+      ...downloadToCSV,
+      modifier: async (data) =>
+        downloadToCSV.modifier(histogramDataToCSV(data, ticks, labelFormatter)),
+    },
+  ]
+}
+
+/**
+ * Creates formatted axis labels from tick boundaries.
+ *
+ * @param dataLength - Number of data points (determines number of labels).
+ * @param ticks - Bin boundaries. If `ticks.length === dataLength + 1`, all
+ *   bins are ranges. If `ticks.length === dataLength`, the last bin is
+ *   open-ended (`+`). A last tick of `Infinity` also produces `+`.
+ * @param labelFormatter - Optional formatter applied to each individual tick
+ *   value when building the bin range label.
+ */
+function createAxisLabels(
+  dataLength: number,
+  ticks: number[],
+  labelFormatter?: (value: string | number) => string | number,
+): string[] {
+  const fmt = (v: number) =>
+    labelFormatter ? String(labelFormatter(v)) : String(v)
+
+  return Array.from({ length: dataLength }, (_, i) => {
+    const low = ticks[i] ?? i
+    const high = ticks[i + 1]
+    return high !== undefined && isFinite(high)
+      ? `${fmt(low)}-${fmt(high)}`
+      : `${fmt(low)}+`
+  })
+}
+
+/**
+ * Generates ECharts configuration for distribution histogram widgets with
+ * adjacent bars (minimal gap) and axis formatting styled with the CARTO theme.
+ *
+ * Accepts raw `number[][]` data and `ticks` boundaries. The ticks and
+ * `labelFormatter` are used to create the x-axis category labels; the raw
+ * numeric data is embedded directly in each series.
+ *
+ * @param props - Histogram configuration including raw data, ticks, and theme.
+ * @returns Widget config with ECharts option object.
+ */
+export function histogramConfig(props: HistogramConfig): HistogramWidgetConfig {
+  return {
+    type: 'histogram',
+    option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+    formatter: props.formatter,
+    labelFormatter: props.labelFormatter,
+  }
+}
+
+function getOption({
+  data = [],
+  ticks,
+  theme,
+  formatter,
+  labelFormatter,
+}: HistogramConfig): EchartOptionsProps {
+  const hasLegend = (data?.length ?? 0) > 1
+  const dataLength = data[0]?.length ?? 0
+  const axisLabels = createAxisLabels(dataLength, ticks, labelFormatter)
+
+  let niceMin = 0
+  let niceMax = 1
+
+  return {
+    legend: buildLegendConfig({ hasLegend, labelFormatter }),
+    grid: buildGridConfig(hasLegend, theme),
+    xAxis: {
+      type: 'category',
+      data: axisLabels,
+      axisLine: {
+        show: false,
+      },
+      axisLabel: {
+        fontSize: theme.typography.overlineDelicate.fontSize,
+        fontFamily: theme.typography.overlineDelicate.fontFamily,
+        showMinLabel: undefined,
+        showMaxLabel: undefined,
+        hideOverlap: true,
+        margin: 0,
+        padding: [
+          parseInt(theme.spacing(0.5)),
+          parseInt(theme.spacing(0.5)),
+          0,
+          parseInt(theme.spacing(0.5)),
+        ],
+        color: theme.palette.black[60],
+      },
+      axisTick: {
+        show: false,
+      },
+      splitLine: {
+        show: true,
+        lineStyle: {
+          color: theme.palette.black[4],
+        },
+      },
+    },
+    yAxis: {
+      type: 'value' as const,
+      min: (extent: { min: number }) => {
+        niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+        return niceMin
+      },
+      max: (extent: { min: number; max: number }) => {
+        niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+        return niceMax
+      },
+      splitNumber: 1,
+      axisLabel: {
+        fontSize: theme.typography.overlineDelicate.fontSize,
+        fontFamily: theme.typography.overlineDelicate.fontFamily,
+        margin: parseInt(theme.spacing(1)),
+        show: true,
+        showMaxLabel: true,
+        showMinLabel: true,
+        verticalAlign: 'bottom' as const,
+        formatter: (value: number) => {
+          if (value !== niceMax && value !== niceMin) return ''
+          if (value === 0) return ''
+          return formatter ? formatter(value) : String(value)
+        },
+      },
+      axisLine: {
+        show: false,
+      },
+      axisTick: {
+        show: false,
+      },
+      splitLine: {
+        show: true,
+        lineStyle: {
+          color: theme.palette.black[4],
+        },
+      },
+    },
+    tooltip: {
+      position: createTooltipPositioner(theme),
+      formatter: createTooltipFormatter((item) => {
+        const _value = item.value as number
+
+        const formattedValue =
+          typeof _value === 'number' && formatter
+            ? formatter(_value)
+            : String(_value ?? '')
+
+        const marker = typeof item.marker === 'string' ? item.marker : ''
+        const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
+        const name = item.name
+
+        return { name, seriesName, marker, value: formattedValue }
+      }),
+    },
+    series: data.map((seriesData: number[]) => ({
+      type: 'bar',
+      data: seriesData,
+      barGap: '1%',
+      barCategoryGap: '1%',
+      emphasis: {
+        focus: 'series',
+      },
+      ...buildHistogramSeriesLabelConfig(formatter),
+    })),
+  } as EchartOptionsProps
+}

package/src/widgets/histogram/index.ts

@@ -0,0 +1,13 @@
+export type {
+  HistogramConfig,
+  HistogramWidgetConfig,
+  HistogramWidgetData,
+  HistogramWidgetState,
+} from './types'
+export type { HistogramDownloadConfigProps } from './config'
+export {
+  histogramConfig,
+  histogramDataToCSV,
+  histogramDownloadConfig,
+} from './config'
+export { HistogramSkeleton } from './skeleton'

package/src/widgets/histogram/skeleton.tsx

@@ -0,0 +1,52 @@
+import { Box, Skeleton } from '@mui/material'
+import { styles } from './style'
+
+export function HistogramSkeleton() {
+  return (
+    <Box sx={styles.skeleton.graph.container}>
+      <Box
+        sx={{
+          display: 'flex',
+          alignItems: 'flex-end',
+          justifyContent: 'space-between',
+          gap: ({ spacing }) => spacing(0.5),
+          height: ({ spacing }) => spacing(30),
+          width: '100%',
+        }}
+      >
+        {Array(8)
+          .fill(0)
+          .map((_, i) => {
+            // Create varying heights for histogram bars
+            const heights = [60, 80, 95, 85, 70, 55, 40, 30]
+            const height = `${heights[i]}%`
+            return (
+              <Skeleton
+                key={`skeleton-bar-${i}`}
+                variant='rectangular'
+                sx={{
+                  flex: 1,
+                  height,
+                }}
+              />
+            )
+          })}
+      </Box>
+      <Box
+        sx={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          width: '100%',
+          mt: ({ spacing }) => spacing(1),
+        }}
+      >
+        {Array(4)
+          .fill(0)
+          .map((_, i) => (
+            <Skeleton key={`skeleton-label-${i}`} width={32} height={8} />
+          ))}
+      </Box>
+    </Box>
+  )
+}

package/src/widgets/histogram/style.ts

@@ -0,0 +1,8 @@
+import type { SxProps, Theme } from '@mui/material'
+import { baseSkeletonStyles } from '../utils/skeleton'
+
+export const styles = {
+  skeleton: {
+    graph: baseSkeletonStyles.graph,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/histogram/types.ts

@@ -0,0 +1,23 @@
+import type { EchartWidgetState } from '../echart'
+import type {
+  EchartWidgetOptionProps,
+  EchartWidgetProps,
+} from '../echart/types'
+import type { ConfigProps } from '../loader'
+
+export type HistogramWidgetData = number[][]
+
+export type HistogramWidgetState = EchartWidgetState
+
+export type HistogramWidgetConfig = EchartWidgetProps & {
+  type: 'histogram'
+}
+
+export type HistogramConfig = ConfigProps &
+  Pick<
+    EchartWidgetOptionProps<unknown>,
+    'theme' | 'formatter' | 'labelFormatter'
+  > & {
+    data?: number[][]
+    ticks: number[]
+  }

package/src/widgets/loader/index.ts

@@ -0,0 +1,4 @@
+export { WidgetLoader } from './loader'
+export { mergeWidgetConfig, resolveConfig, type ConfigOrFn } from './utils'
+
+export type { WidgetLoaderProps, ConfigProps } from './types'

package/src/widgets/loader/loader.tsx

@@ -0,0 +1,92 @@
+import { useEffect, useRef } from 'react'
+import type { WidgetLoaderProps } from './types'
+import { useWidgetStore, widgetStoreActions } from '../stores/widget-store'
+import type { WrapperState } from '../wrapper'
+
+/**
+ * Foundation component for all widgets that manages state initialization, synchronization with the widget store, and data transformation pipeline execution.
+ *
+ * @remarks
+ * The WidgetLoader is stateless -- it manages data flow but does not render any UI. Always wrap it with WidgetWrapper for consistent widget appearance.
+ *
+ * @example
+ * ```tsx
+ * <WidgetLoader
+ *   id="sales-chart"
+ *   type="bar"
+ *   data={data}
+ *   isLoading={false}
+ *   isFetching={false}
+ *   config={barConfig({ data })}
+ * >
+ *   <WidgetWrapper id="sales-chart" title="Sales">
+ *     <Echart id="sales-chart" />
+ *   </WidgetWrapper>
+ * </WidgetLoader>
+ * ```
+ */
+export function WidgetLoader<T extends object = Record<string, unknown>>(
+  props: WidgetLoaderProps<T>,
+) {
+  // Subscribe only to this widget's registeredTools via Zustand selector.
+  // The selector returns a stable reference when other widgets change,
+  // avoiding unnecessary re-evaluations of Effect 4.
+  const registeredTools = useWidgetStore(
+    (state) => state.widgets[props.id]?.registeredTools,
+  )
+
+  const dataRef = useRef(props.data)
+  const configRef = useRef(props.config)
+  const isMountedRef = useRef(false)
+
+  useEffect(() => {
+    dataRef.current = props.data
+    configRef.current = props.config
+  })
+
+  // Effect 1: Metadata — type, loading, and error states in a single setWidget call.
+  // Merged to reduce store updates from 2 to 1 per widget during initialization.
+  useEffect(() => {
+    widgetStoreActions.setWidget<WrapperState>(props.id, {
+      type: props.type,
+      isLoading: props.isLoading ?? false,
+      isFetching: props.isFetching ?? false,
+      error: props.error,
+    })
+  }, [props.id, props.type, props.isLoading, props.isFetching, props.error])
+
+  // Effect 2: Config updates — run through config pipeline
+  useEffect(() => {
+    if (props.config) {
+      void widgetStoreActions.executeConfigPipeline(props.id, props.config)
+    }
+  }, [props.id, props.config])
+
+  // Effect 3: Execute tool pipeline when props.data changes
+  useEffect(() => {
+    void widgetStoreActions.executeToolPipeline(props.id, props.data)
+  }, [props.id, props.data])
+
+  // Effect 4: Re-execute pipelines when registered tools change.
+  // Uses requestAnimationFrame to coalesce rapid successive registeredTools
+  // changes (e.g., 6 action components each calling registerTool on mount)
+  // into a single pipeline execution instead of 6 pairs.
+  useEffect(() => {
+    if (!isMountedRef.current) {
+      isMountedRef.current = true
+      return
+    }
+
+    const rafId = requestAnimationFrame(() => {
+      const { executeToolPipeline, executeConfigPipeline } = widgetStoreActions
+      void executeToolPipeline(props.id, dataRef.current)
+      if (configRef.current) {
+        void executeConfigPipeline(props.id, configRef.current)
+      }
+    })
+
+    return () => cancelAnimationFrame(rafId)
+  }, [registeredTools, props.id])
+
+  return props.children
+}

package/src/widgets/loader/types.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react'
+import type { WidgetsStoreProps, WidgetState } from '../stores/types'
+
+export interface WidgetLoaderProps<
+  T extends object = Record<string, unknown>,
+> extends WidgetsStoreProps {
+  children: ReactNode
+  config?: T
+}
+
+export interface ConfigProps {
+  refUI?: WidgetState['refUI']
+}

package/src/widgets/loader/utils.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest'
+import { resolveConfig, mergeWidgetConfig } from './utils'
+
+describe('resolveConfig', () => {
+  interface TestConfig {
+    max: number
+    items: number
+    label?: string
+  }
+
+  type TestData = { value: number }[]
+
+  const baseConfig: TestConfig = {
+    max: 100,
+    items: 10,
+    label: 'default',
+  }
+
+  const testData: TestData = [{ value: 50 }, { value: 75 }]
+
+  it('should return undefined when config is undefined', () => {
+    const result = resolveConfig(undefined, baseConfig, testData)
+    expect(result).toBeUndefined()
+  })
+
+  it('should return the object config unchanged when config is an object', () => {
+    const objectConfig = { max: 200, items: 20 }
+    const result = resolveConfig(objectConfig, baseConfig, testData)
+    expect(result).toEqual(objectConfig)
+  })
+
+  it('should call function config with baseConfig and data when config is a function', () => {
+    const fnConfig = (base: TestConfig, data: TestData) => ({
+      max: base.max * 2,
+      items: data.length,
+    })
+
+    const result = resolveConfig(fnConfig, baseConfig, testData)
+    expect(result).toEqual({ max: 200, items: 2 })
+  })
+
+  it('should allow function config to access baseConfig properties', () => {
+    const fnConfig = (base: TestConfig) => ({
+      label: `Modified: ${base.label}`,
+    })
+
+    const result = resolveConfig(fnConfig, baseConfig, testData)
+    expect(result).toEqual({ label: 'Modified: default' })
+  })
+
+  it('should allow function config to compute values from data', () => {
+    const fnConfig = (_base: TestConfig, data: TestData) => ({
+      max: Math.max(...data.map((d) => d.value)),
+    })
+
+    const result = resolveConfig(fnConfig, baseConfig, testData)
+    expect(result).toEqual({ max: 75 })
+  })
+
+  it('should return partial config from function', () => {
+    const fnConfig = () => ({ items: 5 })
+
+    const result = resolveConfig(fnConfig, baseConfig, testData)
+    expect(result).toEqual({ items: 5 })
+    // Ensure it's partial - doesn't include all base properties
+    expect(result).not.toHaveProperty('max')
+    expect(result).not.toHaveProperty('label')
+  })
+})
+
+describe('mergeWidgetConfig', () => {
+  interface TestConfig {
+    max: number
+    items: number
+    label?: string
+    series?: { name: string }[]
+  }
+
+  it('should merge two partial configs', () => {
+    const base: Partial<TestConfig> = { max: 100, items: 10 }
+    const override: Partial<TestConfig> = { max: 200 }
+
+    const result = mergeWidgetConfig<TestConfig>(base, override)
+    expect(result).toEqual({ max: 200, items: 10 })
+  })
+
+  it('should handle undefined base config', () => {
+    const override: Partial<TestConfig> = { max: 200 }
+
+    const result = mergeWidgetConfig<TestConfig>(undefined, override)
+    expect(result).toEqual({ max: 200 })
+  })
+
+  it('should handle undefined override config', () => {
+    const base: Partial<TestConfig> = { max: 100 }
+
+    const result = mergeWidgetConfig<TestConfig>(base, undefined)
+    expect(result).toEqual({ max: 100 })
+  })
+
+  it('should replace arrays instead of merging them', () => {
+    const base: Partial<TestConfig> = {
+      series: [{ name: 'Series 1' }, { name: 'Series 2' }],
+    }
+    const override: Partial<TestConfig> = {
+      series: [{ name: 'New Series' }],
+    }
+
+    const result = mergeWidgetConfig<TestConfig>(base, override)
+    expect(result.series).toEqual([{ name: 'New Series' }])
+  })
+})

package/src/widgets/loader/utils.ts

@@ -0,0 +1,57 @@
+import deepmerge from 'deepmerge'
+
+/**
+ * Config can be either an object or a function that receives baseConfig and data
+ * and returns a partial config to be merged with the base.
+ */
+export type ConfigOrFn<TConfig, TData = unknown> =
+  Partial<TConfig> | ((baseConfig: TConfig, data: TData) => Partial<TConfig>)
+
+/**
+ * Resolves a widget config that may be either a partial object or a function receiving the computed base config and data. If it is a function, calls it with `baseConfig` and `data`; otherwise returns the value as-is.
+ *
+ * @param config - The config object or function to resolve.
+ * @param baseConfig - The computed base configuration.
+ * @param data - The widget data.
+ * @returns Resolved partial config, or undefined.
+ *
+ * @example
+ * ```tsx
+ * const resolved = resolveConfig(
+ *   (base, data) => ({ maxItems: base.maxItems + 5 }),
+ *   baseConfig,
+ *   widgetData,
+ * )
+ * ```
+ */
+export function resolveConfig<TConfig, TData>(
+  config: ConfigOrFn<TConfig, TData> | undefined,
+  baseConfig: TConfig,
+  data: TData,
+): Partial<TConfig> | undefined {
+  if (typeof config === 'function') {
+    return config(baseConfig, data)
+  }
+  return config
+}
+
+/**
+ * Deep-merges two partial widget config objects using `deepmerge`, with arrays replaced rather than concatenated.
+ *
+ * @param options - A tuple of two partial configs to merge (base and override).
+ * @returns The merged config object.
+ *
+ * @example
+ * ```tsx
+ * const finalConfig = mergeWidgetConfig(baseConfig, resolvedConfig)
+ * ```
+ */
+export function mergeWidgetConfig<T>(
+  ...options: [Partial<T> | undefined, Partial<T> | undefined]
+): T {
+  return deepmerge(options[0] ?? {}, options[1] ?? {}, {
+    arrayMerge(_, source) {
+      return source as T[keyof T][]
+    },
+  })
+}

package/src/widgets/markdown/config.ts

@@ -0,0 +1,28 @@
+import { downloadToCSV, type DownloadItem } from '../actions'
+import type { MarkdownWidgetConfig, MarkdownWidgetData } from './types'
+
+/**
+ * Creates download configuration for markdown widgets, supporting CSV export of text content. Does not require `refUI` since it only exports text.
+ *
+ * @returns Array of download items for use with the Download action.
+ */
+export function markdownDownloadConfig(): DownloadItem<MarkdownWidgetData>[] {
+  return [
+    {
+      ...downloadToCSV,
+      modifier: async (data) => {
+        const content = data?.content ?? ''
+        return downloadToCSV.modifier([['Content'], [content]])
+      },
+    },
+  ]
+}
+
+/**
+ * Returns the default configuration for markdown content display widgets.
+ *
+ * @returns Default markdown widget config (empty object).
+ */
+export function markdownConfig(): MarkdownWidgetConfig {
+  return {}
+}