@carto/ps-react-ui 4.3.3 → 4.3.5

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,143 @@
+import {
+  getCommonOptions,
+  mergeEchartWidgetConfig,
+  type EchartOptionsProps,
+} from '../echart'
+import type {
+  HistogramConfig,
+  HistogramWidgetConfig,
+  HistogramWidgetData,
+} from './types'
+import {
+  flattenObjectArrayToCSV,
+  buildLegendConfig,
+  buildGridConfig,
+  createTooltipPositioner,
+  createTooltipFormatter,
+  applyYAxisFormatter,
+} from '../_shared/chart-config'
+import { downloadToCSV, downloadToPNG, type DownloadItem } from '../actions'
+import type { ConfigProps } from '../loader/types'
+
+export function histogramDownloadConfig({
+  refUI,
+}: ConfigProps): DownloadItem<HistogramWidgetData>[] {
+  return [
+    {
+      ...downloadToPNG,
+      modifier: () => downloadToPNG.modifier(refUI),
+    },
+    {
+      ...downloadToCSV,
+      modifier: async (data) => {
+        const rows = flattenObjectArrayToCSV(data)
+        return downloadToCSV.modifier(rows)
+      },
+    },
+  ]
+}
+export function histogramConfig(props: HistogramConfig): HistogramWidgetConfig {
+  return {
+    type: 'histogram',
+    option: mergeEchartWidgetConfig(getCommonOptions(props), getOption(props)),
+  }
+}
+function getOption({
+  data = [],
+  theme,
+  formatter,
+}: HistogramConfig): EchartOptionsProps {
+  const hasLegend = (data?.length ?? 0) > 1
+
+  const yAxis = {
+    type: 'value' as const,
+    showMaxLabel: true,
+    showMinLabel: true,
+    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,
+    },
+    axisLine: {
+      show: false,
+    },
+    axisTick: {
+      show: false,
+    },
+    splitLine: {
+      show: true,
+      lineStyle: {
+        color: theme.palette.black[4],
+      },
+    },
+  }
+
+  return {
+    legend: buildLegendConfig(hasLegend),
+    grid: buildGridConfig(hasLegend, theme),
+    xAxis: {
+      type: 'category',
+      axisLine: {
+        show: false,
+      },
+      axisLabel: {
+        fontSize: theme.typography.overlineDelicate.fontSize,
+        fontFamily: theme.typography.overlineDelicate.fontFamily,
+        showMinLabel: true,
+        showMaxLabel: true,
+        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: applyYAxisFormatter(yAxis, formatter),
+    tooltip: {
+      position: createTooltipPositioner(theme),
+      formatter: createTooltipFormatter((item) => {
+        const value = item.value as Record<string, string | number>
+        const index = item.dimensionNames?.[item.encode?.y?.at(0) ?? 1]
+        const _value = value[index ?? '']
+
+        const formattedValue =
+          typeof _value === 'number' && formatter
+            ? formatter(_value)
+            : (_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((_: unknown, index: number) => ({
+      datasetIndex: index,
+      type: 'bar',
+      barGap: '1%', // No gap between bars in histogram
+      barCategoryGap: '1%', // No gap between categories in histogram
+      emphasis: {
+        focus: 'series',
+      },
+    })),
+  } as EchartOptionsProps
+}

package/src/widgets/histogram/index.ts

@@ -0,0 +1,8 @@
+export type {
+  HistogramConfig,
+  HistogramWidgetConfig,
+  HistogramWidgetData,
+  HistogramWidgetState,
+} from './types'
+export { histogramConfig, 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={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={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 '../_shared/skeleton'
+
+export const styles = {
+  skeleton: {
+    graph: baseSkeletonStyles.graph,
+  },
+} satisfies Record<string, SxProps<Theme>>

package/src/widgets/histogram/types.ts

@@ -0,0 +1,17 @@
+import type { EchartWidgetData, EchartWidgetState } from '../echart'
+import type {
+  EchartWidgetOptionProps,
+  EchartWidgetProps,
+} from '../echart/types'
+import type { ConfigProps } from '../loader'
+
+export type HistogramWidgetData = EchartWidgetData
+
+export type HistogramWidgetState = EchartWidgetState
+
+export type HistogramWidgetConfig = EchartWidgetProps & {
+  type: 'histogram'
+}
+
+export type HistogramConfig = ConfigProps &
+  EchartWidgetOptionProps<HistogramWidgetData>

package/src/widgets/index.ts

@@ -0,0 +1,25 @@
+// Widget store
+export { useWidgetStore } from './stores/widget-store'
+export type {
+  BaseWidgetState,
+  WidgetsStoreProps,
+  WidgetState,
+  WidgetStore,
+  WidgetStoreActions,
+  WidgetStoreState,
+} from './stores/types'
+
+// Hooks
+export { useWidgetRef } from '../hooks/use-widget-ref'
+
+// NoData
+export { WidgetNoData } from './no-data'
+export type { WidgetNoDataProps } from './no-data'
+
+// Error
+export { WidgetError } from './error'
+export type { WidgetErrorProps } from './error'
+
+// Note
+export { WidgetNote } from './note'
+export type { WidgetNoteProps } from './note'

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,70 @@
+import { useEffect } from 'react'
+import type { WidgetLoaderProps } from './types'
+import { useWidgetStore } from '../stores/widget-store'
+import type { WrapperState } from '../wrapper'
+
+export function WidgetLoader<T>(props: WidgetLoaderProps<T>) {
+  const setWidget = useWidgetStore((state) => state.setWidget)
+  const executeToolPipeline = useWidgetStore(
+    (state) => state.executeToolPipeline,
+  )
+
+  // Split into 3 effects for metadata and 1 for data pipeline:
+  // Each property that can be modified independently gets its own effect to avoid
+  // accidentally resetting other properties.
+  //
+  // - Effect 1: Type (can be modified by tools that change visualization type)
+  // - Effect 2: Loading/Error states (change during fetch lifecycle)
+  // - Effect 3: Config (can be modified by tools that change widget configuration)
+  // - Effect 4: Data pipeline execution (transforms data through registered tools)
+  // - Effect 5: Re-execute pipeline when tool state changes
+
+  // Effect 1: Type updates
+  useEffect(() => {
+    setWidget<WrapperState>(props.id, {
+      type: props.type,
+    })
+  }, [props.id, props.type, setWidget])
+
+  // Effect 2: Loading and error states
+  useEffect(() => {
+    setWidget<WrapperState>(props.id, {
+      isLoading: props.isLoading ?? false,
+      isFetching: props.isFetching ?? false,
+      error: props.error,
+    })
+  }, [props.id, props.isLoading, props.isFetching, props.error, setWidget])
+
+  // Effect 3: Config updates
+  useEffect(() => {
+    if (props.config) {
+      setWidget<WrapperState>(props.id, {
+        ...props.config,
+      })
+    }
+  }, [props.id, props.config, setWidget])
+
+  // Effect 4: Execute tool pipeline when props.data changes
+  useEffect(() => {
+    void executeToolPipeline(props.id, props.data)
+  }, [props.id, props.data, executeToolPipeline])
+
+  // Effect 5: Re-execute pipeline when tool state changes (enabled/config)
+  useEffect(() => {
+    let prevTools = useWidgetStore.getState().widgets[props.id]?.registeredTools
+
+    const unsubscribe = useWidgetStore.subscribe((state) => {
+      const currentTools = state.widgets[props.id]?.registeredTools
+
+      // Only re-execute if tools array changed
+      if (currentTools !== prevTools) {
+        prevTools = currentTools
+        void executeToolPipeline(props.id, props.data)
+      }
+    })
+
+    return unsubscribe
+  }, [props.id, props.data, executeToolPipeline])
+
+  return props.children
+}

package/src/widgets/loader/types.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react'
+import type { WidgetsStoreProps, WidgetState } from '../stores/types'
+
+export interface WidgetLoaderProps<T> 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,35 @@
+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 config that may be either an object or a function.
+ * If it's a function, calls it with baseConfig and data.
+ * If it's an object (or undefined), returns it as-is.
+ */
+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
+}
+
+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,18 @@
+import { downloadToCSV, type DownloadItem } from '../actions'
+import type { MarkdownWidgetConfig, MarkdownWidgetData } from './types'
+
+export function markdownDownloadConfig(): DownloadItem<MarkdownWidgetData>[] {
+  return [
+    {
+      ...downloadToCSV,
+      modifier: async (data) => {
+        const content = data?.content ?? ''
+        return downloadToCSV.modifier([['Content'], [content]])
+      },
+    },
+  ]
+}
+
+export function markdownConfig(): MarkdownWidgetConfig {
+  return {}
+}

package/src/widgets/markdown/index.ts

@@ -0,0 +1,14 @@
+export { Markdown } from './markdown'
+export { MarkdownUI } from './markdown-ui'
+export { MarkdownSkeleton } from './skeleton'
+export { markdownConfig, markdownDownloadConfig } from './config'
+
+export type {
+  MarkdownComponentProps,
+  MarkdownUIProps,
+  MarkdownWidgetData,
+  MarkdownWidgetState,
+  MarkdownWidgetConfig,
+  MarkdownDownloadConfig,
+  MarkdownDataItem,
+} from './types'