@carto/ps-react-ui 4.7.1 → 4.8.0

package/src/widgets-v2/timeseries/options.ts

@@ -0,0 +1,341 @@
+import type { EChartsOption } from 'echarts'
+import * as echarts from 'echarts'
+import type { CallbackDataParams } from 'echarts/types/dist/shared'
+import {
+  buildGridConfig,
+  buildLegendConfig,
+  createTooltipFormatter,
+  createTooltipPositioner,
+  niceNum,
+} from '../../widgets/utils/chart-config'
+import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
+import type { OptionFactory } from '../echart'
+import { mergeOptions } from '../utils'
+import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
+import type {
+  TimeseriesEChartsOption,
+  TimeseriesOptionFactoryInput,
+  TimeseriesOptionsInput,
+  TimeseriesWidgetData,
+} from './types'
+
+/**
+ * Builds the **structural** ECharts option for a timeseries widget —
+ * time x-axis, value y-axis, themed tooltip, themed legend, CARTO color
+ * palette. Mirrors {@link import('../bar/options').barOptions} so all
+ * four ECharts widgets share v1 look-and-feel.
+ *
+ * Intentional deviations from bar (timeseries-specific):
+ *   - **X-axis is `type: 'time'`** (not 'category'). ECharts handles
+ *     uneven sample spacing and zoom-level-aware label formatting.
+ *     `labelFormatter` is wrapped so the consumer sees a `Date`, not
+ *     a numeric timestamp.
+ *   - **Tooltip body reads `{ name, value }` rows**, same as bar, but
+ *     the `name` may arrive as `Date | number | string`. The
+ *     `labelFormatter` receives a `Date` regardless.
+ *
+ * Intentionally data-agnostic: no series, no dataset, no `legend.show`
+ * (those depend on data and are added by the option factory's merge
+ * phase via {@link createTimeseriesOptionFactory}).
+ */
+export function timeseriesOptions({
+  theme,
+  formatter,
+  labelFormatter,
+}: TimeseriesOptionsInput): TimeseriesEChartsOption {
+  // Closure shared between yAxis min/max callbacks and the label formatter,
+  // so only the rounded extents are labelled (matches v1 + bar).
+  let niceMin = 0
+  let niceMax = 1
+
+  return {
+    grid: {
+      left: parseInt(theme.spacing(1)),
+      top: parseInt(theme.spacing(3)),
+      right: parseInt(theme.spacing(1)),
+      // Default: no legend. Merger bumps this when there are >1 series.
+      ...buildGridConfig(false, theme),
+      containLabel: true,
+    },
+    tooltip: {
+      trigger: 'axis',
+      backgroundColor: theme.palette.grey[900],
+      borderWidth: 0,
+      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      textStyle: {
+        color: theme.palette.common.white,
+        fontSize: 11,
+        fontFamily: theme.typography.caption.fontFamily,
+      },
+      axisPointer: { type: 'line' },
+      position: createTooltipPositioner(theme),
+      formatter: buildTimeseriesTooltipFormatter(formatter, labelFormatter),
+    },
+    // Legend styling baked here; `show` is toggled by the merger based on
+    // series count.
+    legend: {
+      ...buildLegendConfig({ hasLegend: false }),
+    },
+    axisPointer: { lineStyle: { color: theme.palette.grey[400] } },
+    color: [
+      theme.palette.secondary.main,
+      ...Object.values(
+        (theme.palette as { qualitative?: { bold?: Record<string, string> } })
+          .qualitative?.bold ?? {},
+      ),
+    ],
+    xAxis: {
+      type: 'time',
+      axisLine: { show: false },
+      axisTick: { show: false },
+      axisLabel: {
+        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        margin: 0,
+        hideOverlap: true,
+        ...(labelFormatter && {
+          formatter: (value: number) => labelFormatter(new Date(value)),
+        }),
+      },
+    },
+    yAxis: {
+      type: 'value',
+      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
+      },
+      axisLine: { show: false },
+      axisTick: { show: false },
+      splitLine: {
+        show: true,
+        lineStyle: { color: theme.palette.black?.[4] ?? theme.palette.divider },
+      },
+      axisLabel: {
+        fontSize: theme.typography.overlineDelicate?.fontSize,
+        fontFamily: theme.typography.overlineDelicate?.fontFamily,
+        margin: parseInt(theme.spacing(1)),
+        show: true,
+        showMaxLabel: true,
+        showMinLabel: true,
+        verticalAlign: 'bottom',
+        inside: true,
+        formatter: (value: number) => {
+          if (value !== niceMax && value !== niceMin) return ''
+          if (value === 0) return ''
+          return formatter ? formatter(value) : String(value)
+        },
+      },
+    },
+  } as TimeseriesEChartsOption
+}
+
+/**
+ * Returns the timeseries widget's {@link OptionFactory} — one closure
+ * that owns BOTH phases of option construction:
+ *
+ *   - **Structural phase** (`option == null`) — builds the theme-aware
+ *     structural option via {@link timeseriesOptions}, optionally merging
+ *     the consumer-supplied `optionsOverride`. Called once by Provider to
+ *     seed `rawOptions` in the store.
+ *   - **Merge phase** (`option != null`) — fuses post-pipeline `state.data`
+ *     (`TimeseriesWidgetData`) into the option via the dataset API: one
+ *     dataset per series, each series referencing its dataset by index,
+ *     encoded by `name` (x — time) and `value` (y). Mirrors {@link import('../bar/options').createBarOptionFactory}:
+ *     series-template merge for `addStack`, reactive formatters from
+ *     `ctx`, `niceNum`-rounded y-axis bounds at fusion time, and
+ *     `positionDataZoomForLegend` layout for ZoomToggle sliders.
+ */
+export function createTimeseriesOptionFactory(
+  options: TimeseriesOptionFactoryInput,
+): OptionFactory {
+  const { theme, formatter, labelFormatter, optionsOverride } = options
+  const seriesNames = options.seriesNames
+  const smooth = options.smooth ?? true
+  const area = options.area ?? false
+  const selection = options.selection
+  const selectionSet =
+    selection && selection.length > 0
+      ? new Set<string | number>(selection)
+      : null
+  // `name` may be Date | number | string. Normalize to the same type the
+  // selection is keyed on (Date → ms) so Set lookups match.
+  const normalizeName = (n: Date | number | string): string | number =>
+    n instanceof Date ? n.getTime() : n
+  return (option, data, ctx) => {
+    if (option == null) {
+      const structural = timeseriesOptions({ theme, formatter, labelFormatter })
+      return optionsOverride
+        ? (mergeOptions(
+            structural as unknown as Record<string, unknown>,
+            optionsOverride as Partial<Record<string, unknown>>,
+          ) as EChartsOption)
+        : structural
+    }
+
+    const seriesArr = Array.isArray(data) ? (data as TimeseriesWidgetData) : []
+    if (seriesArr.length === 0) {
+      return { ...option, dataset: [], series: [] }
+    }
+    const hasLegend = seriesArr.length > 1
+    const seriesTemplates = Array.isArray(option.series) ? option.series : []
+    const broadcastTemplate = seriesTemplates[0] ?? {}
+    const baseYAxis =
+      typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
+        ? option.yAxis
+        : {}
+    const baseGrid =
+      typeof option.grid === 'object' && !Array.isArray(option.grid)
+        ? option.grid
+        : {}
+    const baseTooltip =
+      typeof option.tooltip === 'object' && !Array.isArray(option.tooltip)
+        ? option.tooltip
+        : {}
+    const baseLegend =
+      typeof option.legend === 'object' && !Array.isArray(option.legend)
+        ? option.legend
+        : {}
+
+    // Reactive (live store) formatter from ctx — distinct from the
+    // closure-time `formatter` captured for the structural-build branch
+    // above. RelativeData can install a percent formatter on the store
+    // after the factory was constructed; the merge phase reads `ctx` to
+    // pick that up. `labelFormatter` (Date → string) is structural-only —
+    // not relativizable — so the merge branch reads the closure-time value.
+    const liveFormatter = ctx?.formatter
+
+    const { niceMinVal, niceMaxVal } = computeTimeseriesNiceBounds(seriesArr)
+
+    // Zoom slider layout: when ZoomToggle has installed `dataZoom`, push the
+    // slider above the legend (if any) and reserve room in the grid below.
+    const dataZoomLayout = positionDataZoomForLegend(option.dataZoom, hasLegend)
+    const fallbackBottom =
+      typeof baseGrid.bottom === 'number' ? baseGrid.bottom : 24
+    const baseBottom = hasLegend ? 56 : fallbackBottom
+    const gridBottom = dataZoomLayout
+      ? baseBottom + ZOOM_LAYOUT.sliderHeight + ZOOM_LAYOUT.sliderGap
+      : baseBottom
+
+    // Dim non-selected points via `series.itemStyle.color`. Per-row
+    // `itemStyle` on dataset object-rows is silently ignored when
+    // `series.encode` is in play.
+    //
+    // We *always* emit `itemStyle.color` (a passthrough when nothing is
+    // selected), not conditionally — dropping the key between renders
+    // would let ECharts' default merge keep the previous callback alive
+    // and points would stay dimmed forever after an external clear.
+    // Always emitting lets normal merge swap the callback in place, no
+    // `replaceMerge` and no entry-animation flash on selection on/off.
+    const dimItemStyle = {
+      color: (params: CallbackDataParams) => {
+        const datum = params.value as
+          | { name?: Date | number | string }
+          | undefined
+        const raw = datum?.name
+        const base = params.color as string
+        if (!selectionSet || raw == null) return base
+        return selectionSet.has(normalizeName(raw))
+          ? base
+          : echarts.color.modifyAlpha(base, 0.15)
+      },
+    }
+
+    return {
+      ...option,
+      dataset: seriesArr.map((s) => ({ source: s as readonly object[] })),
+      series: seriesArr.map((_, i) => {
+        const template =
+          (seriesTemplates[i] as object | undefined) ??
+          (broadcastTemplate as object)
+        return {
+          ...(typeof template === 'object' ? template : {}),
+          type: 'line' as const,
+          datasetIndex: i,
+          name: seriesNames?.[i] ?? `Series ${i + 1}`,
+          encode: { x: 'name', y: 'value' },
+          smooth,
+          // When a selection is active, surface markers so the per-point
+          // color callback has something to dim — a continuous line would
+          // hide the visual selection feedback.
+          showSymbol: selectionSet != null,
+          ...(area ? { areaStyle: {} } : {}),
+          emphasis: { focus: 'series' },
+          itemStyle: dimItemStyle,
+        }
+      }),
+      legend: { ...baseLegend, show: hasLegend },
+      grid: { ...baseGrid, bottom: gridBottom },
+      ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
+      yAxis: {
+        ...baseYAxis,
+        min: niceMinVal,
+        max: niceMaxVal,
+        axisLabel: {
+          ...((baseYAxis as { axisLabel?: object }).axisLabel ?? {}),
+          formatter: (value: number) => {
+            if (value !== niceMaxVal && value !== niceMinVal) return ''
+            if (value === 0) return ''
+            return liveFormatter ? liveFormatter(value) : String(value)
+          },
+        },
+      } as EChartsOption['yAxis'],
+      tooltip: {
+        ...baseTooltip,
+        formatter: buildTimeseriesTooltipFormatter(
+          liveFormatter,
+          labelFormatter,
+        ),
+      },
+    } as EChartsOption
+  }
+}
+
+/**
+ * Tooltip formatter for the timeseries `{ name, value }` row shape.
+ * `name` arrives as `Date | number | string` (the time-axis stores the
+ * raw value the consumer supplied). The consumer's `labelFormatter`
+ * expects a `Date`, so we coerce non-Date values via `new Date(...)`
+ * before invoking it.
+ */
+function buildTimeseriesTooltipFormatter(
+  formatter: ((value: number) => string) | undefined,
+  labelFormatter: ((value: Date) => string) | undefined,
+) {
+  return createTooltipFormatter((item) => {
+    const row = item.value as
+      | { name?: Date | number | string; value?: number }
+      | undefined
+    const raw = row?.value
+    const formattedValue =
+      typeof raw === 'number' && formatter ? formatter(raw) : (raw ?? '')
+    const marker = typeof item.marker === 'string' ? item.marker : ''
+    const seriesName = item.seriesName ? `${item.seriesName}: ` : ''
+    const rawName = row?.name ?? item.name
+    const name =
+      labelFormatter && rawName != null
+        ? labelFormatter(rawName instanceof Date ? rawName : new Date(rawName))
+        : (rawName ?? '')
+    return { name: String(name), seriesName, marker, value: formattedValue }
+  })
+}
+
+function computeTimeseriesNiceBounds(seriesArr: TimeseriesWidgetData): {
+  niceMinVal: number
+  niceMaxVal: number
+} {
+  let min = 0
+  let max = -Infinity
+  for (const series of seriesArr) {
+    for (const d of series) {
+      if (typeof d?.value !== 'number' || !Number.isFinite(d.value)) continue
+      if (d.value < min) min = d.value
+      if (d.value > max) max = d.value
+    }
+  }
+  const niceMinVal = min < 0 ? niceNum(min) : 0
+  const niceMaxVal = max <= 0 ? 1 : niceNum(max)
+  return { niceMinVal, niceMaxVal }
+}

package/src/widgets-v2/timeseries/skeleton.test.tsx

@@ -0,0 +1,13 @@
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { TimeseriesSkeleton } from './skeleton'
+
+describe('<TimeseriesSkeleton>', () => {
+  it('renders without crashing', () => {
+    const { container } = render(<TimeseriesSkeleton />)
+    expect(container.firstChild).not.toBeNull()
+    expect(
+      container.querySelectorAll('.MuiSkeleton-root').length,
+    ).toBeGreaterThan(0)
+  })
+})

package/src/widgets-v2/timeseries/skeleton.tsx

@@ -0,0 +1,76 @@
+import { Box, Skeleton } from '@mui/material'
+import type { SxProps, Theme } from '@mui/material'
+
+const styles = {
+  container: {
+    display: 'flex',
+    flexDirection: 'column',
+    justifyContent: 'space-between',
+    gap: ({ spacing }) => spacing(1),
+    height: ({ spacing }) => spacing(38),
+  },
+  graph: {
+    position: 'relative',
+    flex: '1 1 auto',
+    width: '100%',
+  },
+  segmentA: {
+    position: 'absolute',
+    left: 0,
+    right: '70%',
+    top: '60%',
+    height: 4,
+  },
+  segmentB: {
+    position: 'absolute',
+    left: '25%',
+    right: '40%',
+    top: '35%',
+    height: 4,
+  },
+  segmentC: {
+    position: 'absolute',
+    left: '55%',
+    right: 0,
+    top: '50%',
+    height: 4,
+  },
+  legend: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(2),
+    height: ({ spacing }) => spacing(5),
+  },
+  legendItem: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: ({ spacing }) => spacing(1.5),
+  },
+} satisfies Record<string, SxProps<Theme>>
+
+/**
+ * Loading state for the Timeseries widget. Mirrors a line chart's
+ * silhouette — three thin horizontal segments at staggered offsets to
+ * suggest a moving line, plus a 2-dot legend stub. Sibling-consistent
+ * with Bar / Histogram / Scatter skeletons (column-flex container with
+ * legend strip below).
+ */
+export function TimeseriesSkeleton() {
+  return (
+    <Box sx={styles.container}>
+      <Box sx={styles.graph}>
+        <Skeleton variant='rectangular' sx={styles.segmentA} />
+        <Skeleton variant='rectangular' sx={styles.segmentB} />
+        <Skeleton variant='rectangular' sx={styles.segmentC} />
+      </Box>
+      <Box sx={styles.legend}>
+        {[0, 1].map((i) => (
+          <Box key={`legend-${i}`} sx={styles.legendItem}>
+            <Skeleton variant='circular' width={8} height={8} />
+            <Skeleton width={48} height={8} />
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  )
+}

package/src/widgets-v2/timeseries/types.ts

@@ -0,0 +1,61 @@
+import type { Theme } from '@mui/material'
+import type { EChartsOption } from 'echarts'
+
+/**
+ * A single point on a time series. `name` is the time coordinate — accepts a
+ * Date object, a number (ms-since-epoch), or an ISO-8601 string. ECharts'
+ * time axis parses any of these.
+ */
+export interface TimeseriesDatum {
+  name: Date | number | string
+  value: number
+}
+
+/** Timeseries widget data — one array of points per series. */
+export type TimeseriesWidgetData = readonly (readonly TimeseriesDatum[])[]
+
+/** Inputs to the structural-only {@link timeseriesOptions} builder. */
+export interface TimeseriesOptionsInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  /** Optional formatter for the time-axis tick labels. Receives a JS Date. */
+  labelFormatter?: (value: Date) => string
+}
+
+/**
+ * Combined inputs for the timeseries option factory creator. Carries
+ * everything the widget needs across BOTH phases — the structural-build
+ * (`theme`, `formatter`, `labelFormatter`, `optionsOverride`) AND the
+ * data merge (`seriesNames`, `smooth`, `area`, `selection`).
+ */
+export interface TimeseriesOptionFactoryInput {
+  theme: Theme
+  formatter?: (value: number) => string
+  /**
+   * Time-axis label formatter (also used in the tooltip name). Receives
+   * a JS Date — applied both at structural-build time (x-axis ticks) and
+   * at fusion time (tooltip name) so the date-aware labeling survives
+   * RelativeData's reactive formatter swaps.
+   */
+  labelFormatter?: (value: Date) => string
+  /** Series names — drives the legend and `series[i].name`. */
+  seriesNames?: readonly string[]
+  /** Smooth lines (default `true`). */
+  smooth?: boolean
+  /** Filled area below each line (default `false`). */
+  area?: boolean
+  /**
+   * Selected point keys (matched against `TimeseriesDatum.name`; `Date`
+   * names are normalized to ms-since-epoch). Points not in this list render
+   * dimmed (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
+   */
+  selection?: readonly (string | number)[] | null
+  /**
+   * Consumer-supplied partial option merged into the structural option at
+   * structural-build time. Lets stories override pieces of the theme-aware
+   * base without forking the structural builder.
+   */
+  optionsOverride?: Partial<EChartsOption>
+}
+
+export type TimeseriesEChartsOption = EChartsOption

package/src/widgets-v2/toolbox/labels.ts

@@ -0,0 +1,9 @@
+export interface ToolboxLabels {
+  trigger: string
+  close: string
+}
+
+export const DEFAULT_TOOLBOX_LABELS: ToolboxLabels = {
+  trigger: 'More actions',
+  close: 'Close',
+}

package/src/widgets-v2/toolbox/style.ts

@@ -0,0 +1,33 @@
+import type { SxProps, Theme } from '@mui/material'
+
+export const styles = {
+  root: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.25,
+    width: 'fit-content',
+    borderRadius: 0.5,
+    gridColumn: 2,
+    height: 'fit-content',
+  },
+  preview: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.25,
+  },
+  triggerActive: {
+    bgcolor: 'primary.relatedLight',
+  },
+  paper: {
+    // Positioning is handled by Popper; only visual styles here.
+    display: 'flex',
+    alignItems: 'center',
+    gap: 0.25,
+    px: 0.25,
+    py: 0.25,
+    mx: 0.25,
+    mt: `0 !important`, // Popper's placement adds a margin-top to offset from the trigger; we want to override that.
+    bgcolor: 'background.paper',
+    borderRadius: 0.5,
+  },
+} satisfies Record<string, SxProps<Theme>>