@carto/ps-react-ui 4.19.0 → 4.20.1

package/dist/zoom-toggle-CA0ifG23.js

@@ -0,0 +1,164 @@
+import { t as e } from "./tooltip-DJUGNZxY.js";
+import "./components-DDt4mOQn.js";
+import { T as t, f as n, n as r } from "./stores-BVFMfgyo.js";
+import { c as i } from "react/compiler-runtime";
+import "react";
+import { IconButton as a, useTheme as o } from "@mui/material";
+import { jsx as s } from "react/jsx-runtime";
+import { ZoomIn as c } from "@mui/icons-material";
+//#region src/widgets-v2/actions/zoom-toggle/transforms.ts
+var l = "image://data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOSIgaGVpZ2h0PSIzNiIgdmlld0JveD0iMCAwIDkgMzYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHg9IjAuNSIgeT0iLTAuNSIgd2lkdGg9IjgiIGhlaWdodD0iMTgiIHJ4PSI0IiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAwIDI3KSIgZmlsbD0id2hpdGUiIHN0cm9rZT0iIzM1OEJFNyIvPgo8cmVjdCB3aWR0aD0iMyIgaGVpZ2h0PSIyIiByeD0iMSIgdHJhbnNmb3JtPSJtYXRyaXgoMSAwIDAgLTEgMyAyMykiIGZpbGw9IiMzNThCRTciLz4KPHJlY3Qgd2lkdGg9IjMiIGhlaWdodD0iMiIgcng9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIC0xIDMgMTkpIiBmaWxsPSIjMzU4QkU3Ii8+CjxyZWN0IHdpZHRoPSIzIiBoZWlnaHQ9IjIiIHJ4PSIxIiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAzIDE1KSIgZmlsbD0iIzM1OEJFNyIvPgo8L3N2Zz4=", u = 32, d = 0;
+function f(e, t = {}) {
+	let n = t.axes ?? ["x"], r = n.includes("x"), i = n.includes("y"), a = {
+		throttle: 0,
+		showDetail: !1,
+		brushSelect: !1,
+		moveHandleSize: 8,
+		handleSize: "100%",
+		...m(e)
+	};
+	return (e) => {
+		if (typeof e != "object" || !e) return e;
+		let t = e, n = [];
+		return r && n.push({
+			type: "inside",
+			xAxisIndex: [0],
+			throttle: 0
+		}), i && n.push({
+			type: "inside",
+			yAxisIndex: [0],
+			throttle: 0
+		}), r && n.push({
+			type: "slider",
+			xAxisIndex: [0],
+			height: u,
+			bottom: d,
+			handleIcon: l,
+			...a
+		}), i && n.push({
+			type: "slider",
+			yAxisIndex: [0],
+			width: u,
+			right: d,
+			...a
+		}), {
+			...t,
+			dataZoom: n
+		};
+	};
+}
+var p = (e) => typeof e != "object" || !e ? e : {
+	...e,
+	dataZoom: [{ type: "inside" }, {
+		type: "slider",
+		height: u,
+		bottom: d
+	}]
+};
+function m(e) {
+	let t = e.palette.secondary?.main ?? "#358BE7";
+	return {
+		fillerColor: "rgba(53, 139, 231, 0.25)",
+		borderColor: "rgba(53, 139, 231, 0.3)",
+		borderWidth: .5,
+		backgroundColor: "transparent",
+		borderRadius: 4,
+		dataBackground: {
+			lineStyle: { opacity: 0 },
+			areaStyle: {
+				opacity: 1,
+				color: t
+			}
+		},
+		selectedDataBackground: {
+			lineStyle: { opacity: 0 },
+			areaStyle: {
+				opacity: 1,
+				color: t
+			}
+		},
+		handleStyle: {
+			color: e.palette.common?.white ?? "#fff",
+			borderColor: "rgba(3, 111, 226, 0.08)",
+			borderWidth: 1,
+			shadowBlur: 3,
+			shadowColor: "rgba(0, 0, 0, 0.1)",
+			shadowOffsetX: 0,
+			shadowOffsetY: 1
+		},
+		textStyle: {
+			color: e.palette.black?.[60] ?? e.palette.text?.primary,
+			fontSize: parseInt(e.typography.overlineDelicate?.fontSize ?? "11"),
+			fontFamily: e.typography.overlineDelicate?.fontFamily ?? e.typography.caption?.fontFamily
+		}
+	};
+}
+var h = {
+	sliderHeight: u,
+	sliderGap: 8,
+	sliderBottomWithLegend: 28
+}, g = {
+	on: "Disable zoom",
+	off: "Enable zoom"
+}, _ = {
+	toggle: {
+		p: .5,
+		"& .MuiSvgIcon-root": { fontSize: 20 }
+	},
+	toggleActive: { background: (e) => e.palette.primary.relatedLight }
+}, v = {
+	id: "zoom-toggle",
+	type: "config",
+	order: 20
+};
+function y(l) {
+	let u = i(31), { initialEnabled: d, labels: p, icon: m, iconProps: h, axes: y } = l, b = d !== void 0 && d, x = m === void 0 ? c : m, S = t(), C = o(), w;
+	u[0] === p ? w = u[1] : (w = {
+		...g,
+		...p
+	}, u[0] = p, u[1] = w);
+	let T = w, E;
+	u[2] === y ? E = u[3] : (E = !y || y.includes("x"), u[2] = y, u[3] = E);
+	let D = E, O;
+	u[4] === y ? O = u[5] : (O = y ? y.includes("y") : !1, u[4] = y, u[5] = O);
+	let k = O, A;
+	if (u[6] !== D || u[7] !== k || u[8] !== C) {
+		let e = [];
+		D && e.push("x"), k && e.push("y"), A = f(C, { axes: e }), u[6] = D, u[7] = k, u[8] = C, u[9] = A;
+	} else A = u[9];
+	let j = A, M;
+	u[10] === b ? M = u[11] : (M = { initialEnabled: b }, u[10] = b, u[11] = M);
+	let { enabled: N, toggle: P } = r(S, v, j, M), F;
+	u[12] !== N || u[13] !== S || u[14] !== P ? (F = () => {
+		N && n(S)?.setOption({}, { replaceMerge: ["dataZoom"] }), P();
+	}, u[12] = N, u[13] = S, u[14] = P, u[15] = F) : F = u[15];
+	let I = F, L = N ? T.on : T.off, R = N ? "active" : void 0, z = N && _.toggleActive, B;
+	u[16] === z ? B = u[17] : (B = {
+		..._.toggle,
+		...z
+	}, u[16] = z, u[17] = B);
+	let V;
+	u[18] !== x || u[19] !== h ? (V = /* @__PURE__ */ s(x, {
+		fontSize: "small",
+		...h
+	}), u[18] = x, u[19] = h, u[20] = V) : V = u[20];
+	let H;
+	u[21] !== N || u[22] !== I || u[23] !== B || u[24] !== V || u[25] !== R || u[26] !== L ? (H = /* @__PURE__ */ s(a, {
+		size: "small",
+		"aria-label": L,
+		"aria-pressed": N,
+		onClick: I,
+		className: R,
+		sx: B,
+		children: V
+	}), u[21] = N, u[22] = I, u[23] = B, u[24] = V, u[25] = R, u[26] = L, u[27] = H) : H = u[27];
+	let U;
+	return u[28] !== H || u[29] !== L ? (U = /* @__PURE__ */ s(e, {
+		title: L,
+		children: H
+	}), u[28] = H, u[29] = L, u[30] = U) : U = u[30], U;
+}
+//#endregion
+export { f as a, p as i, g as n, h as r, y as t };
+
+//# sourceMappingURL=zoom-toggle-CA0ifG23.js.map

package/dist/zoom-toggle-CA0ifG23.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoom-toggle-CA0ifG23.js","names":["Theme","SLIDER_HANDLE_ICON","SLIDER_HEIGHT","SLIDER_BOTTOM","ZoomAxis","CreateAddZoomOptions","axes","createAddZoom","theme","options","option","includeX","includes","includeY","sliderStyles","getZoomSliderStyles","baseSliderProps","throttle","showDetail","brushSelect","moveHandleSize","handleSize","cfg","Record","dataZoom","push","type","xAxisIndex","yAxisIndex","height","bottom","handleIcon","width","right","addZoom","secondary","palette","main","fillerColor","borderColor","borderWidth","backgroundColor","borderRadius","dataBackground","lineStyle","opacity","areaStyle","color","selectedDataBackground","handleStyle","common","white","shadowBlur","shadowColor","shadowOffsetX","shadowOffsetY","textStyle","black","text","primary","fontSize","parseInt","typography","overlineDelicate","fontFamily","caption","ZOOM_LAYOUT","sliderHeight","sliderGap","sliderBottomWithLegend","const","ZoomToggleLabels","on","off","DEFAULT_ZOOM_TOGGLE_LABELS","SxProps","Theme","styles","toggle","p","fontSize","toggleActive","background","theme","palette","primary","relatedLight","Record","useCallback","useMemo","ComponentType","IconButton","useTheme","SvgIconProps","ZoomIn","ZoomInIcon","Tooltip","getEchartInstance","useSingleTransform","useWidgetId","createAddZoom","ZoomAxis","DEFAULT_ZOOM_TOGGLE_LABELS","ZoomToggleLabels","styles","ZOOM_DESCRIPTOR","id","type","const","order","ZoomToggleProps","initialEnabled","labels","Partial","icon","iconProps","axes","ZoomToggle","t0","$","_c","t1","t2","undefined","Icon","theme","t3","_labels","t4","includes","includeX","t5","includeY","t6","resolved","push","transform","t7","enabled","toggle","t8","setOption","replaceMerge","handleToggle","tooltip","on","off","t9","t10","toggleActive","t11","t12","t13","t14"],"sources":["../src/widgets-v2/actions/zoom-toggle/transforms.ts","../src/widgets-v2/actions/zoom-toggle/labels.ts","../src/widgets-v2/actions/zoom-toggle/style.ts","../src/widgets-v2/actions/zoom-toggle/zoom-toggle.tsx"],"sourcesContent":["import type { Theme } from '@mui/material'\n\n/**\n * v1's slider handle — 9×36 SVG with a white pill body, secondary-colored\n * stroke, and three grip lines. Inlined as a data URL so the chart can\n * render it without a network fetch.\n */\nconst SLIDER_HANDLE_ICON =\n  'image://data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOSIgaGVpZ2h0PSIzNiIgdmlld0JveD0iMCAwIDkgMzYiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHg9IjAuNSIgeT0iLTAuNSIgd2lkdGg9IjgiIGhlaWdodD0iMTgiIHJ4PSI0IiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAwIDI3KSIgZmlsbD0id2hpdGUiIHN0cm9rZT0iIzM1OEJFNyIvPgo8cmVjdCB3aWR0aD0iMyIgaGVpZ2h0PSIyIiByeD0iMSIgdHJhbnNmb3JtPSJtYXRyaXgoMSAwIDAgLTEgMyAyMykiIGZpbGw9IiMzNThCRTciLz4KPHJlY3Qgd2lkdGg9IjMiIGhlaWdodD0iMiIgcng9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIC0xIDMgMTkpIiBmaWxsPSIjMzU4QkU3Ii8+CjxyZWN0IHdpZHRoPSIzIiBoZWlnaHQ9IjIiIHJ4PSIxIiB0cmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAzIDE1KSIgZmlsbD0iIzM1OEJFNyIvPgo8L3N2Zz4='\n\nconst SLIDER_HEIGHT = 32\nconst SLIDER_BOTTOM = 0\n\n/** Which chart axis (or axes) zoom applies to. */\nexport type ZoomAxis = 'x' | 'y'\n\nexport interface CreateAddZoomOptions {\n  /**\n   * Axes to enable zoom on. Default `['x']` (matches bar / histogram /\n   * timeseries — horizontal pan/zoom on the category axis). Pass\n   * `['x', 'y']` for a scatterplot-style 2D zoom (mouse-wheel scales both\n   * axes; a horizontal slider sits at the bottom for x-range and a\n   * vertical slider sits on the right for y-range).\n   */\n  axes?: readonly ZoomAxis[]\n}\n\n/**\n * Theme-bound zoom config transform: adds one inside `dataZoom`\n * (mouse-wheel + drag) per axis plus a styled slider per axis with the\n * v1 chrome (blue-tinted filler, secondary-color data preview, white\n * pill handles, CARTO typography). The x-slider is horizontal at the\n * bottom; the y-slider is vertical on the right.\n *\n * Returned function has stable identity for a given theme + axes\n * combination; pair with `useMemo` at the call site.\n *\n * **No `start` / `end`** are emitted: ECharts defaults to `0–100` on the\n * first `setOption` and then keeps the runtime slider state across\n * subsequent merges (no `replaceMerge` for `dataZoom`). Re-running the\n * transform on data/formatter/RelativeData updates therefore preserves the\n * user's dragged range instead of snapping it back.\n */\nexport function createAddZoom(\n  theme: Theme,\n  options: CreateAddZoomOptions = {},\n): (option: unknown) => unknown {\n  const axes = options.axes ?? ['x']\n  const includeX = axes.includes('x')\n  const includeY = axes.includes('y')\n  const sliderStyles = getZoomSliderStyles(theme)\n  const baseSliderProps = {\n    throttle: 0,\n    showDetail: false,\n    brushSelect: false,\n    moveHandleSize: 8,\n    handleSize: '100%',\n    ...sliderStyles,\n  }\n  return (option: unknown): unknown => {\n    if (option == null || typeof option !== 'object') return option\n    const cfg = option as Record<string, unknown>\n    const dataZoom: object[] = []\n    if (includeX) {\n      dataZoom.push({ type: 'inside', xAxisIndex: [0], throttle: 0 })\n    }\n    if (includeY) {\n      dataZoom.push({ type: 'inside', yAxisIndex: [0], throttle: 0 })\n    }\n    if (includeX) {\n      dataZoom.push({\n        type: 'slider',\n        xAxisIndex: [0],\n        height: SLIDER_HEIGHT,\n        bottom: SLIDER_BOTTOM,\n        handleIcon: SLIDER_HANDLE_ICON,\n        ...baseSliderProps,\n      })\n    }\n    if (includeY) {\n      // Vertical slider — `width` is its thickness, `right` pins it to\n      // the right edge. We omit `handleIcon` so ECharts renders its\n      // default vertical handle (the inline SVG is shaped for a\n      // horizontal slider and looks wrong when rotated).\n      dataZoom.push({\n        type: 'slider',\n        yAxisIndex: [0],\n        width: SLIDER_HEIGHT,\n        right: SLIDER_BOTTOM,\n        ...baseSliderProps,\n      })\n    }\n    return { ...cfg, dataZoom }\n  }\n}\n\n/**\n * Back-compat untyped transform — produces the bare `dataZoom` config from\n * the original v2 implementation. Use {@link createAddZoom} when a theme is\n * available so the slider matches the v1 styling.\n *\n * `start` / `end` are intentionally omitted so ECharts preserves the user's\n * runtime range across subsequent `setOption` merges (see {@link createAddZoom}).\n */\nexport const addZoom = (option: unknown): unknown => {\n  if (option == null || typeof option !== 'object') return option\n  const cfg = option as Record<string, unknown>\n  return {\n    ...cfg,\n    dataZoom: [\n      { type: 'inside' },\n      {\n        type: 'slider',\n        height: SLIDER_HEIGHT,\n        bottom: SLIDER_BOTTOM,\n      },\n    ],\n  }\n}\n\n/** Style block matching v1's `getEChartZoomSliderStyles`. */\nfunction getZoomSliderStyles(theme: Theme) {\n  const secondary = theme.palette.secondary?.main ?? '#358BE7'\n  return {\n    fillerColor: 'rgba(53, 139, 231, 0.25)',\n    borderColor: 'rgba(53, 139, 231, 0.3)',\n    borderWidth: 0.5,\n    backgroundColor: 'transparent',\n    borderRadius: 4,\n    dataBackground: {\n      lineStyle: { opacity: 0 },\n      areaStyle: { opacity: 1, color: secondary },\n    },\n    selectedDataBackground: {\n      lineStyle: { opacity: 0 },\n      areaStyle: { opacity: 1, color: secondary },\n    },\n    handleStyle: {\n      color: theme.palette.common?.white ?? '#fff',\n      borderColor: 'rgba(3, 111, 226, 0.08)',\n      borderWidth: 1,\n      shadowBlur: 3,\n      shadowColor: 'rgba(0, 0, 0, 0.1)',\n      shadowOffsetX: 0,\n      shadowOffsetY: 1,\n    },\n    textStyle: {\n      color: theme.palette.black?.[60] ?? theme.palette.text?.primary,\n      fontSize: parseInt(\n        (theme.typography.overlineDelicate?.fontSize as string | undefined) ??\n          '11',\n      ),\n      fontFamily:\n        theme.typography.overlineDelicate?.fontFamily ??\n        theme.typography.caption?.fontFamily,\n    },\n  }\n}\n\n/**\n * Visual layout constants used by the data-fusion mergers (bar, histogram,\n * timeseries) when laying out the slider against the legend / grid.\n */\nexport const ZOOM_LAYOUT = {\n  /** Slider height in px (matches `createAddZoom` output). */\n  sliderHeight: SLIDER_HEIGHT,\n  /** Vertical gap between chart grid and the slider. */\n  sliderGap: 8,\n  /** Slider `bottom` when a legend is shown — sits above the legend row. */\n  sliderBottomWithLegend: 28,\n} as const\n","export interface ZoomToggleLabels {\n  on: string\n  off: string\n}\n\nexport const DEFAULT_ZOOM_TOGGLE_LABELS: ZoomToggleLabels = {\n  on: 'Disable zoom',\n  off: 'Enable zoom',\n}\n","import type { SxProps, Theme } from '@mui/material'\n\nexport const styles = {\n  toggle: {\n    p: 0.5,\n    '& .MuiSvgIcon-root': { fontSize: 20 },\n  },\n  toggleActive: {\n    background: (theme: Theme) => theme.palette.primary.relatedLight,\n  },\n} satisfies Record<string, SxProps<Theme>>\n","import { useCallback, useMemo, type ComponentType } from 'react'\nimport { IconButton, useTheme, type SvgIconProps } from '@mui/material'\nimport { ZoomIn as ZoomInIcon } from '@mui/icons-material'\nimport { Tooltip } from '../../../components'\nimport {\n  getEchartInstance,\n  useSingleTransform,\n  useWidgetId,\n} from '../../stores'\nimport { createAddZoom, type ZoomAxis } from './transforms'\nimport { DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleLabels } from './labels'\nimport { styles } from './style'\n\nconst ZOOM_DESCRIPTOR = {\n  id: 'zoom-toggle',\n  type: 'config' as const,\n  order: 20,\n}\n\nexport interface ZoomToggleProps {\n  initialEnabled?: boolean\n  labels?: Partial<ZoomToggleLabels>\n  icon?: ComponentType<SvgIconProps>\n  iconProps?: SvgIconProps\n  /**\n   * Which axes the zoom controls. Default `['x']` — matches bar /\n   * histogram / timeseries (horizontal pan on the category axis). Pass\n   * `['x', 'y']` for 2D zoom on a scatterplot-style chart (mouse-wheel\n   * scales both axes; horizontal slider at bottom + vertical slider on\n   * the right).\n   */\n  axes?: readonly ZoomAxis[]\n}\n\n/**\n * Toggle a `dataZoom` slider + wheel-zoom on the chart. The transform is\n * theme-bound so the slider gets v1's CARTO chrome (blue-tinted filler,\n * secondary-color preview, white pill handles).\n *\n * `dataZoom` is intentionally NOT in `replaceMergeKeys` — ECharts merges\n * subsequent `setOption` calls so the user's dragged range survives\n * unrelated re-renders (data updates, formatter swaps, RelativeData toggles).\n *\n * On disable the transform is unregistered, but ECharts' merge semantics\n * would otherwise *keep* the live `dataZoom` component visible. To remove\n * the slider immediately we issue a one-shot\n * `setOption({}, { replaceMerge: ['dataZoom'] })` against the live chart\n * instance via {@link getEchartInstance} — this bypasses the pipeline so\n * unrelated transforms aren't disturbed.\n */\nexport function ZoomToggle({\n  initialEnabled = false,\n  labels,\n  icon: Icon = ZoomInIcon,\n  iconProps,\n  axes,\n}: ZoomToggleProps) {\n  const id = useWidgetId()\n  const theme = useTheme()\n  const _labels = { ...DEFAULT_ZOOM_TOGGLE_LABELS, ...labels }\n  // Reduce `axes` to two structural booleans before memoizing so the memo\n  // depends on stable primitive values, not an array reference (callers\n  // typically pass an inline `axes={['x', 'y']}` literal that changes\n  // identity each render). Default — no `axes` prop — is x-axis only,\n  // matching `createAddZoom`'s default.\n  const includeX = axes ? axes.includes('x') : true\n  const includeY = axes ? axes.includes('y') : false\n  const transform = useMemo(() => {\n    const resolved: ZoomAxis[] = []\n    if (includeX) resolved.push('x')\n    if (includeY) resolved.push('y')\n    return createAddZoom(theme, { axes: resolved })\n  }, [theme, includeX, includeY])\n  const { enabled, toggle } = useSingleTransform(\n    id,\n    ZOOM_DESCRIPTOR,\n    transform,\n    { initialEnabled },\n  )\n\n  const handleToggle = useCallback(() => {\n    if (enabled) {\n      // About to disable — clear the dataZoom component on the live\n      // instance so the slider disappears immediately.\n      getEchartInstance(id)?.setOption({}, { replaceMerge: ['dataZoom'] })\n    }\n    toggle()\n  }, [enabled, toggle, id])\n\n  const tooltip = enabled ? _labels.on : _labels.off\n\n  return (\n    <Tooltip title={tooltip}>\n      <IconButton\n        size='small'\n        aria-label={tooltip}\n        aria-pressed={enabled}\n        onClick={handleToggle}\n        className={enabled ? 'active' : undefined}\n        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}\n      >\n        <Icon fontSize='small' {...iconProps} />\n      </IconButton>\n    </Tooltip>\n  )\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carto/ps-react-ui",
-  "version": "4.19.0",
+  "version": "4.20.1",
   "description": "CARTO's Professional Service React Material library",
   "type": "module",
   "devDependencies": {
@@ -12,11 +12,11 @@
     "@mui/icons-material": "5.18.0",
     "@mui/material": "5.18.0",
     "@mui/x-date-pickers": "7.29.4",
-    "echarts": "6.0.0",
+    "echarts": "6.1.0",
     "html2canvas": "1.4.1",
-    "react-dom": "19.2.4",
+    "react-dom": "19.2.8",
     "react-markdown": "10.1.0",
-    "zustand": "5.0.12",
+    "zustand": "5.0.15",
     "@carto/ps-common-types": "1.0.0",
     "@carto/ps-utils": "2.1.0"
   },

package/src/hooks/use-widget-ref.ts

@@ -1,4 +1,5 @@
 import { useEffect, useRef } from 'react'
+import type * as echarts from 'echarts'
 import { widgetStoreActions } from '../widgets/stores/widget-store'
 
 /**

package/src/widgets-v2/index.ts

@@ -175,7 +175,12 @@ export type { MarkdownUIProps, MarkdownWidgetData } from './markdown'
 export type { PieDatum, PieWidgetData } from './pie'
 export type { TimeseriesDatum, TimeseriesWidgetData } from './timeseries'
 export type { ScatterplotDatum, ScatterplotWidgetData } from './scatterplot'
-export type { SpreadUIProps, SpreadDataItem, SpreadWidgetData } from './spread'
+export type {
+  SpreadUIProps,
+  SpreadDataItem,
+  SpreadWidgetData,
+  SpreadVariant,
+} from './spread'
 export type {
   RangeProps,
   RangeUIProps,

package/src/widgets-v2/spread/band.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { getSpreadBand } from './band'
+
+describe('getSpreadBand', () => {
+  it('reads `spread` as a percentage of the centre value by default', () => {
+    expect(getSpreadBand({ value: 1000, spread: 5 })).toEqual({
+      min: 950,
+      max: 1050,
+    })
+  })
+
+  it('reads `spread` as a percentage when asked explicitly', () => {
+    expect(
+      getSpreadBand({ value: 204_113, spread: 5, variant: 'percentage' }),
+    ).toEqual({ min: 193_907.35, max: 214_318.65 })
+  })
+
+  it('reads `spread` as raw units when the caller opts into `absolute`', () => {
+    expect(
+      getSpreadBand({ value: 204_113, spread: 5, variant: 'absolute' }),
+    ).toEqual({ min: 204_108, max: 204_118 })
+  })
+
+  it('collapses to the centre value when `spread` is 0', () => {
+    expect(getSpreadBand({ value: 42, spread: 0 })).toEqual({
+      min: 42,
+      max: 42,
+    })
+  })
+
+  // A percentage of a negative centre value is a negative offset, which would
+  // otherwise invert the band into `min: -180, max: -220`.
+  it('keeps `min <= max` for a negative centre value', () => {
+    expect(getSpreadBand({ value: -200, spread: 10 })).toEqual({
+      min: -220,
+      max: -180,
+    })
+  })
+
+  it('keeps `min <= max` for a negative `spread`', () => {
+    expect(getSpreadBand({ value: 1000, spread: -5 })).toEqual({
+      min: 950,
+      max: 1050,
+    })
+  })
+})

package/src/widgets-v2/spread/band.ts

@@ -0,0 +1,47 @@
+/**
+ * How a `spread` amount is applied to a centre value.
+ *
+ * - `percentage` — `spread` is a whole-number percentage of the centre
+ *   value, so `5` means +/-5%.
+ * - `absolute` — `spread` is a raw offset in the value's own units.
+ */
+export type SpreadVariant = 'percentage' | 'absolute'
+
+export interface GetSpreadBandOptions {
+  /** The centre value the band is drawn around. */
+  value: number
+  /** Half-width of the band, read according to `variant`. */
+  spread: number
+  /** Defaults to `percentage`. */
+  variant?: SpreadVariant
+}
+
+/**
+ * Derives the `min` / `max` band around a centre value, for feeding a
+ * {@link SpreadDataItem} from a single aggregated number (a prediction, a
+ * target) plus a tolerance — rather than from a real column range.
+ *
+ * `spread` is read as a percentage by default, which is what a tolerance
+ * almost always is: an absolute offset is meaningless without knowing the
+ * value's magnitude, and gets visually lost on large values (+/-5 on a
+ * prediction of 204,113 renders as a range indistinguishable from a single
+ * number).
+ *
+ * @example
+ * getSpreadBand({ value: 1000, spread: 5 })
+ * // -> { min: 950, max: 1050 }
+ * getSpreadBand({ value: 1000, spread: 5, variant: 'absolute' })
+ * // -> { min: 995, max: 1005 }
+ */
+export function getSpreadBand({
+  value,
+  spread,
+  variant = 'percentage',
+}: GetSpreadBandOptions): { min: number; max: number } {
+  const offset = variant === 'absolute' ? spread : (spread / 100) * value
+  // Keep `min <= max`: a percentage of a negative centre value (or a negative
+  // `spread`) yields a negative offset, which would invert the band.
+  const width = Math.abs(offset)
+
+  return { min: value - width, max: value + width }
+}

package/src/widgets-v2/spread/index.ts

@@ -3,4 +3,5 @@ export { SpreadUI, type SpreadUIProps } from './spread-ui'
 export { Separator } from './separator'
 export { SpreadSkeleton, type SpreadSkeletonProps } from './skeleton'
 export { createSpreadDownloadConfig } from './download'
+export { getSpreadBand, type SpreadVariant, type GetSpreadBandOptions } from './band'
 export type { SpreadDataItem, SpreadWidgetData } from './types'