@carto/ps-react-ui 5.3.0 → 6.1.0

package/src/widgets/histogram/config.ts

@@ -1,230 +0,0 @@
-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/style.ts

@@ -1,8 +0,0 @@
-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/loader/index.ts

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

package/src/widgets/loader/loader.tsx

@@ -1,92 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,112 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,28 +0,0 @@
-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 {}
-}

package/src/widgets/no-data/index.ts

@@ -1,2 +0,0 @@
-export { WidgetNoData } from './no-data'
-export type { WidgetNoDataProps } from './types'