@carto/ps-react-ui 6.3.0 → 6.5.0

package/src/widgets/histogram/options.ts

@@ -12,6 +12,7 @@ import {
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { spacingPx } from '../utils/spacing-px'
 import { createItemColorResolver } from '../utils/item-color'
 import { getHistogramBinValue } from './bins'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
@@ -22,6 +23,7 @@ import type {
   HistogramBin,
   HistogramWidgetData,
 } from './types'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a histogram widget — axes,
@@ -55,9 +57,9 @@ export function histogramOptions({
 
   return {
     grid: {
-      left: parseInt(theme.spacing(1)),
-      top: parseInt(theme.spacing(3)),
-      right: parseInt(theme.spacing(1)),
+      left: spacingPx(theme, 1),
+      top: spacingPx(theme, 3),
+      right: spacingPx(theme, 1),
       // Default: no legend. Merger bumps this when there are >1 series.
       ...buildGridConfig(false, theme),
       containLabel: true,
@@ -66,7 +68,7 @@ export function histogramOptions({
       trigger: 'axis',
       backgroundColor: theme.palette.grey[900],
       borderWidth: 0,
-      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      padding: [spacingPx(theme, 1), spacingPx(theme, 1)],
       textStyle: {
         color: theme.palette.common.white,
         fontSize: 11,
@@ -97,7 +99,7 @@ export function histogramOptions({
       axisTick: { show: false },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        padding: [spacingPx(theme, 0.5), 0, 0, 0],
         margin: 0,
         // `interval: 0` makes every bin label a candidate so `hideOverlap`
         // can pack the maximum number that physically fit. The category-axis
@@ -125,7 +127,7 @@ export function histogramOptions({
       },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        margin: parseInt(theme.spacing(1)),
+        margin: spacingPx(theme, 1),
         show: true,
         showMaxLabel: true,
         showMinLabel: true,
@@ -216,6 +218,7 @@ export function createHistogramOptionFactory(
       typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
         ? option.yAxis
         : {}
+    const fixedY = fixedAxisBounds(baseYAxis)
     const baseGrid =
       typeof option.grid === 'object' && !Array.isArray(option.grid)
         ? option.grid
@@ -354,12 +357,14 @@ export function createHistogramOptionFactory(
       ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
       yAxis: {
         ...baseYAxis,
+        // A config transform (RelativeData's `'total'` scale) may pin the
+        // ends; each applies only on the side the data reaches.
         min: (extent: { min: number }) => {
-          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          niceMin = extent.min < 0 ? (fixedY.min ?? niceNum(extent.min)) : 0
           return niceMin
         },
         max: (extent: { min: number; max: number }) => {
-          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          niceMax = extent.max <= 0 ? 1 : (fixedY.max ?? niceNum(extent.max))
           return niceMax
         },
         axisLabel: {

package/src/widgets/index.ts

@@ -155,6 +155,7 @@ export type {
   ZoomToggleProps,
   BrushToggleProps,
   RelativeDataProps,
+  RelativeScale,
   DownloadProps,
   DownloadItem,
   DownloadContext,

package/src/widgets/markdown/style.ts

@@ -1,7 +1,47 @@
 import type { SxProps, Theme } from '@mui/material'
+import type { CSSObject } from '@mui/material/styles'
+
+/**
+ * Browser defaults that rendered Markdown relies on, restated with `revert`
+ * so a CSS reset in the app (Tailwind's preflight, for one) cannot strip
+ * them: list bullets and indent, link underline, blockquote margins, inline
+ * images, monospace fonts, `pre` margins, `sub`/`sup` placement. `revert`
+ * rolls back to the browser's own value, so pages without a reset render
+ * exactly as before.
+ *
+ * Wrapped in `:where()` so any element rule a consumer sets on top wins.
+ */
+export const markdownElementDefaults = {
+  '& :where(ul, ol)': {
+    listStyle: 'revert',
+    margin: 'revert',
+    padding: 'revert',
+  },
+  '& :where(a)': { textDecoration: 'revert' },
+  '& :where(blockquote)': { margin: 'revert' },
+  '& :where(code, kbd, samp)': { fontFamily: 'revert' },
+  '& :where(img)': {
+    display: 'revert',
+    verticalAlign: 'revert',
+    maxWidth: 'revert',
+    height: 'revert',
+  },
+  '& :where(pre)': {
+    margin: 'revert',
+    fontFamily: 'revert',
+    fontSize: 'revert',
+  },
+  '& :where(sub, sup)': {
+    fontSize: 'revert',
+    lineHeight: 'revert',
+    position: 'revert',
+    verticalAlign: 'revert',
+  },
+} satisfies CSSObject
 
 export const styles = {
   root: {
+    ...markdownElementDefaults,
     color: 'text.primary',
     '& a': { color: 'primary.main' },
     '& code': {

package/src/widgets/note/widget-note.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
 import { Box, Link, Typography } from '@mui/material'
 import type { Components } from 'react-markdown'
 import { MarkdownContent } from '../markdown/markdown-content'
+import { markdownElementDefaults } from '../markdown/style'
 import { observeResize } from '../echart/shared-resize-observer'
 import { DEFAULT_NOTE_LABELS, type NoteLabels } from './labels'
 import { styles } from './style'
@@ -107,7 +108,9 @@ function NoteBase({ lineClamp = 3, labels, children }: NoteProps) {
 function NoteMarkdown({ content, lineClamp = 3, labels }: NoteMarkdownProps) {
   return (
     <NoteShell lineClamp={lineClamp} labels={labels} dependency={content}>
-      <MarkdownContent content={content} components={NOTE_COMPONENTS} />
+      <Box sx={markdownElementDefaults}>
+        <MarkdownContent content={content} components={NOTE_COMPONENTS} />
+      </Box>
     </NoteShell>
   )
 }

package/src/widgets/pie/options.ts

@@ -12,6 +12,7 @@ import {
 } from '../utils/option-builders'
 import type { OptionFactory, OptionFactoryContext } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { spacingPx } from '../utils/spacing-px'
 import { createItemColorResolver } from '../utils/item-color'
 import type { WidgetSeries } from '../types'
 import type {
@@ -67,7 +68,7 @@ export function pieOptions({
       trigger: 'item',
       backgroundColor: theme.palette.grey[900],
       borderWidth: 0,
-      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      padding: [spacingPx(theme, 1), spacingPx(theme, 1)],
       textStyle: {
         color: theme.palette.common.white,
         fontSize: 11,
@@ -466,7 +467,7 @@ function buildMultiSeriesBarFusion(
     grid: {
       ...baseGrid,
       ...buildGridConfig(true, theme),
-      right: parseInt(theme.spacing(4)),
+      right: spacingPx(theme, 4),
       containLabel: true,
     },
     // Drop pie-specific structural keys that shouldn't render in the
@@ -511,7 +512,7 @@ function buildMultiSeriesBarFusion(
       axisLabel: {
         fontSize: theme.typography.overlineDelicate?.fontSize,
         fontFamily: theme.typography.overlineDelicate?.fontFamily,
-        margin: parseInt(theme.spacing(1)),
+        margin: spacingPx(theme, 1),
         showMaxLabel: true,
         showMinLabel: true,
         formatter: (value: number) => {
@@ -526,7 +527,7 @@ function buildMultiSeriesBarFusion(
       axisLine: { show: false },
       axisTick: { show: false },
       axisLabel: {
-        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        padding: [spacingPx(theme, 0.5), 0, 0, 0],
         ...(labelFormatter && {
           formatter: (value: string | number) => String(labelFormatter(value)),
         }),

package/src/widgets/scatterplot/options.test.ts

@@ -213,6 +213,18 @@ describe('createScatterplotOptionFactory', () => {
     expect(out.yAxis.min).toBe(0)
   })
 
+  it("pins the y ends a config transform set (RelativeData 'total')", () => {
+    const merge = createScatterplotOptionFactory({ theme })
+    const out = merge({ yAxis: { min: -100, max: 100 } }, [
+      [
+        [1, 47],
+        [2, 3],
+      ],
+    ]) as { yAxis: { min: number; max: number } }
+    expect(out.yAxis.max).toBe(100)
+    expect(out.yAxis.min).toBe(0)
+  })
+
   it('always emits itemStyle.color as a callback (passthrough when no selection)', () => {
     const merge = createScatterplotOptionFactory({ theme })
     const out = merge({}, [[[1, 2]]]) as {

package/src/widgets/scatterplot/options.ts

@@ -12,6 +12,7 @@ import {
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { spacingPx } from '../utils/spacing-px'
 import { createItemColorResolver } from '../utils/item-color'
 import { getScatterplotXY } from './points'
 import type {
@@ -21,6 +22,7 @@ import type {
   ScatterplotItem,
   ScatterplotWidgetData,
 } from './types'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a scatterplot widget — both
@@ -44,9 +46,9 @@ export function scatterplotOptions({
 }: ScatterplotOptionsInput): ScatterplotEChartsOption {
   return {
     grid: {
-      left: parseInt(theme.spacing(1)),
-      top: parseInt(theme.spacing(3)),
-      right: parseInt(theme.spacing(1)),
+      left: spacingPx(theme, 1),
+      top: spacingPx(theme, 3),
+      right: spacingPx(theme, 1),
       // Default: no legend. Merger bumps `bottom` when there are >1 series.
       ...buildGridConfig(false, theme),
       containLabel: true,
@@ -57,7 +59,7 @@ export function scatterplotOptions({
       trigger: 'item',
       backgroundColor: theme.palette.grey[900],
       borderWidth: 0,
-      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      padding: [spacingPx(theme, 1), spacingPx(theme, 1)],
       textStyle: {
         color: theme.palette.common.white,
         fontSize: 11,
@@ -85,7 +87,7 @@ export function scatterplotOptions({
       axisTick: { show: false },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        margin: parseInt(theme.spacing(1)),
+        margin: spacingPx(theme, 1),
         hideOverlap: true,
         showMinLabel: true,
         showMaxLabel: true,
@@ -102,7 +104,7 @@ export function scatterplotOptions({
       axisTick: { show: false },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        margin: parseInt(theme.spacing(1)),
+        margin: spacingPx(theme, 1),
         hideOverlap: true,
         showMinLabel: true,
         showMaxLabel: true,
@@ -189,8 +191,12 @@ export function createScatterplotOptionFactory(
 
     const reactiveFormatter = ctx?.formatter
 
-    const { niceMinX, niceMaxX, niceMinY, niceMaxY } =
-      computeScatterBounds(seriesArr)
+    const { niceMinX, niceMaxX, niceMinY, niceMaxY } = computeScatterBounds(
+      seriesArr,
+      // A config transform (RelativeData's `'total'` scale) may pin the
+      // y ends; each applies only on the side the data reaches.
+      fixedAxisBounds(baseYAxis),
+    )
 
     // Dim non-selected points via `series.itemStyle.color`. The selection
     // key is `${seriesIndex}:${dataIndex}`; we read those off the params
@@ -410,6 +416,7 @@ function buildScatterTooltipFormatter(
 
 function computeScatterBounds(
   seriesArr: ScatterplotWidgetData<ScatterplotItem>,
+  fixedY: { min?: number; max?: number } = {},
 ): {
   niceMinX: number
   niceMaxX: number
@@ -439,8 +446,16 @@ function computeScatterBounds(
   // negative mins, and floor max=0 to 1 so the chart always has range.
   // Scatter can have free coordinates so we apply this per-axis.
   const niceMaxX = Number.isFinite(maxX) ? (maxX <= 0 ? 1 : niceNum(maxX)) : 1
-  const niceMaxY = Number.isFinite(maxY) ? (maxY <= 0 ? 1 : niceNum(maxY)) : 1
+  const niceMaxY = Number.isFinite(maxY)
+    ? maxY <= 0
+      ? 1
+      : (fixedY.max ?? niceNum(maxY))
+    : 1
   const niceMinX = Number.isFinite(minX) ? (minX < 0 ? niceNum(minX) : 0) : 0
-  const niceMinY = Number.isFinite(minY) ? (minY < 0 ? niceNum(minY) : 0) : 0
+  const niceMinY = Number.isFinite(minY)
+    ? minY < 0
+      ? (fixedY.min ?? niceNum(minY))
+      : 0
+    : 0
   return { niceMinX, niceMaxX, niceMinY, niceMaxY }
 }

package/src/widgets/timeseries/options.ts

@@ -12,6 +12,7 @@ import {
 import { ZOOM_LAYOUT } from '../actions/zoom-toggle'
 import type { OptionFactory } from '../echart'
 import { mergeOptions, resolveThemeColor } from '../utils'
+import { spacingPx } from '../utils/spacing-px'
 import { createItemColorResolver } from '../utils/item-color'
 import { positionDataZoomForLegend } from '../utils/data-zoom-layout'
 import type {
@@ -20,6 +21,7 @@ import type {
   TimeseriesOptionsInput,
   TimeseriesWidgetData,
 } from './types'
+import { fixedAxisBounds } from '../actions/relative-data/scale'
 
 /**
  * Builds the **structural** ECharts option for a timeseries widget —
@@ -52,9 +54,9 @@ export function timeseriesOptions({
 
   return {
     grid: {
-      left: parseInt(theme.spacing(1)),
-      top: parseInt(theme.spacing(3)),
-      right: parseInt(theme.spacing(1)),
+      left: spacingPx(theme, 1),
+      top: spacingPx(theme, 3),
+      right: spacingPx(theme, 1),
       // Default: no legend. Merger bumps this when there are >1 series.
       ...buildGridConfig(false, theme),
       containLabel: true,
@@ -63,7 +65,7 @@ export function timeseriesOptions({
       trigger: 'axis',
       backgroundColor: theme.palette.grey[900],
       borderWidth: 0,
-      padding: [parseInt(theme.spacing(1)), parseInt(theme.spacing(1))],
+      padding: [spacingPx(theme, 1), spacingPx(theme, 1)],
       textStyle: {
         color: theme.palette.common.white,
         fontSize: 11,
@@ -92,7 +94,7 @@ export function timeseriesOptions({
       axisTick: { show: false },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        padding: [parseInt(theme.spacing(0.5)), 0, 0, 0],
+        padding: [spacingPx(theme, 0.5), 0, 0, 0],
         margin: 0,
         hideOverlap: true,
         ...(labelFormatter && {
@@ -118,7 +120,7 @@ export function timeseriesOptions({
       },
       axisLabel: {
         ...buildAxisLabelStyle(theme),
-        margin: parseInt(theme.spacing(1)),
+        margin: spacingPx(theme, 1),
         show: true,
         showMaxLabel: true,
         showMinLabel: true,
@@ -188,6 +190,7 @@ export function createTimeseriesOptionFactory(
       typeof option.yAxis === 'object' && !Array.isArray(option.yAxis)
         ? option.yAxis
         : {}
+    const fixedY = fixedAxisBounds(baseYAxis)
     const baseGrid =
       typeof option.grid === 'object' && !Array.isArray(option.grid)
         ? option.grid
@@ -302,12 +305,14 @@ export function createTimeseriesOptionFactory(
       ...(dataZoomLayout ? { dataZoom: dataZoomLayout } : {}),
       yAxis: {
         ...baseYAxis,
+        // A config transform (RelativeData's `'total'` scale) may pin the
+        // ends; each applies only on the side the data reaches.
         min: (extent: { min: number }) => {
-          niceMin = extent.min < 0 ? niceNum(extent.min) : 0
+          niceMin = extent.min < 0 ? (fixedY.min ?? niceNum(extent.min)) : 0
           return niceMin
         },
         max: (extent: { min: number; max: number }) => {
-          niceMax = extent.max <= 0 ? 1 : niceNum(extent.max)
+          niceMax = extent.max <= 0 ? 1 : (fixedY.max ?? niceNum(extent.max))
           return niceMax
         },
         axisLabel: {

package/src/widgets/utils/css-variables-theme.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import { createCartoTheme } from '../../theme/create-carto-theme'
+import { barOptions } from '../bar/options'
+import { histogramOptions } from '../histogram/options'
+import { pieOptions } from '../pie/options'
+import { scatterplotOptions } from '../scatterplot/options'
+import { timeseriesOptions } from '../timeseries/options'
+
+const theme = createCartoTheme()
+
+function nanPaths(value: unknown, path = '$'): string[] {
+  if (typeof value === 'number') return Number.isNaN(value) ? [path] : []
+  if (Array.isArray(value))
+    return value.flatMap((v, i) => nanPaths(v, `${path}[${i}]`))
+  if (value && typeof value === 'object')
+    return Object.entries(value).flatMap(([k, v]) =>
+      nanPaths(v, `${path}.${k}`),
+    )
+  return []
+}
+
+describe('ECharts options with a cssVariables theme', () => {
+  it.each([
+    ['bar', () => barOptions({ theme })],
+    ['histogram', () => histogramOptions({ theme })],
+    ['pie', () => pieOptions({ theme })],
+    ['scatterplot', () => scatterplotOptions({ theme })],
+    ['timeseries', () => timeseriesOptions({ theme })],
+  ])('%s has no NaN in its options', (_name, build) => {
+    expect(nanPaths(build())).toEqual([])
+  })
+})

package/src/widgets/utils/option-builders.ts

@@ -4,6 +4,7 @@ import type {
   CallbackDataParams,
   TopLevelFormatterParams,
 } from 'echarts/types/dist/shared'
+import { spacingPx } from './spacing-px'
 
 /**
  * Shared EChart configuration builders for chart widgets
@@ -61,8 +62,8 @@ export function buildLegendConfig({
  */
 export function buildGridConfig(hasLegend: boolean, theme: Theme) {
   return {
-    ...(!hasLegend && { bottom: parseInt(theme.spacing(3)) }),
-    ...(hasLegend && { bottom: parseInt(theme.spacing(7)) }),
+    ...(!hasLegend && { bottom: spacingPx(theme, 3) }),
+    ...(hasLegend && { bottom: spacingPx(theme, 7) }),
   }
 }
 
@@ -106,10 +107,7 @@ export function createTooltipPositioner(theme: Theme) {
     _rect: unknown,
     size: { contentSize: [number, number]; viewSize: [number, number] },
   ) {
-    const position = { top: parseInt(theme.spacing(0.5)) } as Record<
-      string,
-      number
-    >
+    const position = { top: spacingPx(theme, 0.5) } as Record<string, number>
 
     // Position tooltip left or right based on available space
     if (size.contentSize[0] < size.viewSize[0] - point[0]) {

package/src/widgets/utils/spacing-px.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { createTheme, responsiveFontSizes, type Theme } from '@mui/material'
+import {
+  cartoThemeOptions,
+  theme as cartoTheme,
+} from '@carto/meridian-ds/theme'
+import { createCartoTheme } from '../../theme/create-carto-theme'
+import { spacingPx } from './spacing-px'
+
+const FACTORS = [0.5, 1, 3, 4, 7]
+
+describe('spacingPx', () => {
+  it('matches the previous parseInt(theme.spacing(n)) for the current CARTO theme', () => {
+    const theme = createTheme(cartoTheme)
+    for (const factor of FACTORS) {
+      expect(spacingPx(theme, factor)).toBe(parseInt(theme.spacing(factor)))
+    }
+  })
+
+  it('resolves numbers for a CARTO theme with cssVariables', () => {
+    const theme = responsiveFontSizes(
+      createTheme({ ...cartoThemeOptions, cssVariables: true }),
+    )
+    expect(theme.spacing(1)).toContain('var(')
+    expect(FACTORS.map((f) => spacingPx(theme, f))).toEqual([4, 8, 24, 32, 56])
+  })
+
+  it('falls back to 8px per unit for a plain MUI theme with cssVariables', () => {
+    const theme = createTheme({ cssVariables: true }) as unknown as Theme
+    expect(FACTORS.map((f) => spacingPx(theme, f))).toEqual([4, 8, 24, 32, 56])
+  })
+
+  it('honours a numeric spacing override on createCartoTheme', () => {
+    const theme = createCartoTheme({ spacing: 4 })
+    expect(FACTORS.map((f) => spacingPx(theme, f))).toEqual([2, 4, 12, 16, 28])
+  })
+
+  it('honours a function spacing override under cssVariables', () => {
+    const theme = createCartoTheme({ spacing: (f: number) => f * 6 })
+    expect(spacingPx(theme, 1)).toBe(6)
+  })
+})

package/src/widgets/utils/spacing-px.ts

@@ -0,0 +1,24 @@
+import type { Theme } from '@mui/material'
+
+/**
+ * Theme spacing as a pixel number, for APIs that need numbers (ECharts).
+ *
+ * `theme.spacing(n)` returns `"8px"` for a regular theme but
+ * `"var(--mui-spacing, 8px)"` / `"calc(...)"` once the theme uses
+ * `cssVariables`, which does not parse. Resolution order:
+ * 1. `parseFloat` of `theme.spacing(factor)` (regular themes);
+ * 2. the px unit MUI writes into `theme.spacing(1)` (`var(--mui-spacing, Npx)`),
+ *    which honours a `spacing` override such as `createCartoTheme({ spacing: 4 })`;
+ * 3. meridian's numeric `spacingValue`, or MUI's default 8px.
+ */
+export function spacingPx(theme: Theme, factor: number): number {
+  const parsed = parseFloat(theme.spacing(factor))
+  if (Number.isFinite(parsed)) return parsed
+  // `spacing(1)` is `var(--mui-spacing, Npx)`; larger factors are
+  // `calc(f * var(--mui-spacing, Npx))`, so read the unit from the former.
+  const fallback = /,\s*(-?[\d.]+)px\)\s*$/.exec(theme.spacing(1))
+  const px = fallback ? Number(fallback[1]) : NaN
+  if (Number.isFinite(px)) return px * factor
+  const unit = (theme.spacingValue as number | undefined) ?? 8
+  return unit * factor
+}