@carto/ps-react-ui 5.0.0 → 6.0.0

package/dist/types/widgets/markdown/markdown.d.ts

@@ -1,5 +1,6 @@
-import { MarkdownUIProps } from './types.js';
 /**
- * Stateful markdown widget component that reads content from the widget store and renders it as formatted rich text.
+ * Stateful Markdown bridge — reads `data.content` (post-pipeline) from the
+ * per-widget store and forwards it to the pure {@link MarkdownUI}. Sits
+ * inside `<Widget.Provider>`.
  */
-export declare function Markdown({ id }: MarkdownUIProps): import('react').JSX.Element | null;
+export declare function Markdown(): import('react').JSX.Element;

package/dist/types/widgets/markdown/skeleton.d.ts

@@ -1 +1,4 @@
-export declare function MarkdownSkeleton(): import('react').JSX.Element;
+export interface MarkdownSkeletonProps {
+    lines?: number;
+}
+export declare function MarkdownSkeleton({ lines }: MarkdownSkeletonProps): import('react').JSX.Element;

package/dist/types/widgets/markdown/style.d.ts

@@ -1,2 +1,61 @@
-import { SxProps, Theme } from '@mui/material';
-export declare const styles: Record<string, SxProps<Theme>>;
+export declare const styles: {
+    root: {
+        color: "text.primary";
+        '& a': {
+            color: "primary.main";
+        };
+        '& code': {
+            bgcolor: "action.hover";
+            px: number;
+            borderRadius: number;
+            fontFamily: "monospace";
+            fontSize: string;
+        };
+        '& pre': {
+            bgcolor: "action.hover";
+            p: number;
+            borderRadius: number;
+            overflowX: "auto";
+        };
+        '& blockquote': {
+            borderLeft: string;
+            borderColor: "divider";
+            pl: number;
+            ml: number;
+            color: "text.secondary";
+            fontStyle: "italic";
+        };
+        '& ul, & ol': {
+            pl: number;
+            my: number;
+        };
+        '& li': {
+            my: number;
+        };
+        '& hr': {
+            border: "none";
+            borderTop: string;
+            borderColor: "divider";
+            my: number;
+        };
+        '& table': {
+            borderCollapse: "collapse";
+            width: string;
+        };
+        '& th, & td': {
+            border: "1px solid";
+            borderColor: "divider";
+            px: number;
+            py: number;
+            textAlign: "left";
+        };
+    };
+    paragraph: {
+        my: number;
+    };
+    heading: {
+        mt: number;
+        mb: number;
+        fontWeight: number;
+    };
+};

package/dist/types/widgets/markdown/types.d.ts

@@ -1,18 +1,4 @@
-import { BaseWidgetState, WidgetsStoreProps } from '../stores/types.js';
-import { WrapperState } from '../wrapper/types.js';
-import { DownloadItem } from '../actions/download/types.js';
-import { Components } from 'react-markdown';
-export interface MarkdownComponentProps {
-    children: string;
-    overrides?: Components;
-}
-export interface MarkdownUIProps {
-    id: WidgetsStoreProps['id'];
-}
-export interface MarkdownDataItem {
+/** Markdown widget data — a single markdown source string. */
+export interface MarkdownWidgetData {
     content: string;
 }
-export type MarkdownWidgetData = MarkdownDataItem;
-export type MarkdownWidgetState = BaseWidgetState<WrapperState<MarkdownWidgetConfig>>;
-export type MarkdownWidgetConfig = Record<string, unknown>;
-export type MarkdownDownloadConfig = DownloadItem<MarkdownWidgetData>[];

package/dist/types/widgets/note/style.d.ts

@@ -1,28 +1,26 @@
-import { Theme } from '@mui/material';
 export declare const styles: {
     root: {
-        typography: string;
-        color: (theme: Theme) => string;
-        marginBlockStart: ({ spacing }: Theme) => string;
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+    };
+    text: {
+        color: "text.secondary";
+        overflow: "hidden";
+        overflowWrap: "anywhere";
     };
     clamped: {
         display: "-webkit-box";
-        WebkitLineClamp: number;
         WebkitBoxOrient: "vertical";
-        overflow: "hidden";
-    };
-    expanded: {
-        display: "block";
+        WebkitLineClamp: number;
     };
-    linkButton: {
-        padding: number;
-        minWidth: string;
-        textTransform: "none";
-        typography: string;
+    toggle: {
+        alignSelf: "flex-start";
+        color: "primary.main";
         fontWeight: number;
-        textDecoration: string;
+        cursor: "pointer";
         '&:hover': {
-            backgroundColor: "transparent";
+            textDecoration: string;
         };
     };
 };

package/dist/types/widgets/pie/index.d.ts

@@ -1,3 +1,4 @@
-export type { PieWidgetData, PieWidgetState, PieWidgetConfig, PieConfig, } from './types.js';
-export { pieConfig, pieDownloadConfig } from './config.js';
-export { PieSkeleton } from './skeleton.js';
+export { pieOptions, createPieOptionFactory } from './options.js';
+export { PieSkeleton, type PieSkeletonProps } from './skeleton.js';
+export { createPieDownloadConfig } from './download.js';
+export type { PieDatum, PieWidgetData, PieOptionsInput, PieOptionFactoryInput, PieEChartsOption, } from './types.js';

package/dist/types/widgets/pie/skeleton.d.ts

@@ -1 +1,13 @@
-export declare function PieSkeleton(): import('react').JSX.Element;
+export interface PieSkeletonProps {
+    count?: number;
+}
+/**
+ * Loading state for the Pie widget. Mirrors the donut silhouette — a ring
+ * (gray circle with a background-coloured hole punched out), a stacked
+ * value/name stub in the centre, and a centered legend stub below — so the
+ * skeleton reads as "a donut chart" rather than a solid disc.
+ *
+ * Single donut only: multi-series pie loads as a horizontal bar chart, so
+ * rendering one ring stays honest regardless of `count`.
+ */
+export declare function PieSkeleton({ count }: PieSkeletonProps): import('react').JSX.Element;

package/dist/types/widgets/pie/types.d.ts

@@ -1,9 +1,57 @@
-import { EchartWidgetData, EchartWidgetState } from '../echart/index.js';
-import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types.js';
-import { ConfigProps } from '../loader/index.js';
-export type PieWidgetData = EchartWidgetData;
-export type PieWidgetState = EchartWidgetState;
-export type PieWidgetConfig = EchartWidgetProps & {
-    type: 'pie';
-};
-export type PieConfig = ConfigProps & EchartWidgetOptionProps<PieWidgetData>;
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types.js';
+/** A single slice of a pie series. */
+export interface PieDatum {
+    name: string | number;
+    value: number;
+}
+/** Pie widget data — one slice array per series (rendered as side-by-side donuts). */
+export type PieWidgetData = readonly (readonly PieDatum[])[];
+/** Inputs to the structural-only {@link pieOptions} builder. */
+export interface PieOptionsInput {
+    theme: Theme;
+    /** Numeric value formatter — drives the tooltip value and center label. */
+    formatter?: (value: number) => string;
+    /** Optional slice-name formatter — also forwarded to the legend. */
+    labelFormatter?: (value: string | number) => string | number;
+}
+/**
+ * Combined inputs for the pie option factory creator. Carries everything
+ * the widget needs across BOTH phases — the structural-build (`theme`,
+ * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
+ * (`series`, `radius`, `selection`). The merger emits different
+ * chart shapes by series count: single → donut, multi → horizontal-bar
+ * fallback (mirrors v1 pie); both branches read `theme` for styling.
+ */
+export interface PieOptionFactoryInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+    /**
+     * Per-series metadata — drives the legend, `series[i].name`, and (in
+     * the multi-series bar fallback) per-series colour overrides.
+     * Single-series donuts always use the per-slice palette regardless of
+     * any `series[0].color`, since the donut palette is keyed by data
+     * index, not series index.
+     */
+    series?: readonly WidgetSeries[];
+    /**
+     * Inner/outer radius (percent). Default `['58%', '74%']` produces a
+     * donut sized to leave room for the wrappable bottom legend. Set
+     * inner to `'0%'` for a solid pie.
+     */
+    radius?: readonly [string, string];
+    /**
+     * Selected slice names. Slices 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 PieEChartsOption = EChartsOption;

package/dist/types/widgets/range/index.d.ts

@@ -1,6 +1,4 @@
-export { RangeUI } from './range-ui.js';
-export { RangeSkeleton } from './skeleton.js';
-export { rangeConfig } from './config.js';
-export { RangeItem } from './components/range-item.js';
-export type { RangeWidgetState, RangeWidgetConfig, RangeDownloadConfig, RangeUIProps, RangeDataItem, RangeWidgetData, RangeItemProps, } from './types.js';
-export { sanitizeRangeDataItem, sanitizeRangeDataItems } from './serializer.js';
+export { Range, type RangeProps } from './range.js';
+export { RangeUI, type RangeUIProps } from './range-ui.js';
+export { RangeSkeleton, type RangeSkeletonProps } from './skeleton.js';
+export type { RangeDataItem, RangeWidgetData, RangeItemValue } from './types.js';

package/dist/types/widgets/range/range-ui.d.ts

@@ -1,5 +1,27 @@
-import { RangeUIProps } from './types.js';
+import { RangeDataItem, RangeItemValue } from './types.js';
+export interface RangeUIProps {
+    items: readonly RangeDataItem[];
+    /**
+     * Fires on every pointer tick while a thumb is being dragged (mirrors
+     * MUI `<Slider>`'s `onChange`). Use this to update local UI state —
+     * not to persist expensive operations like remote queries.
+     */
+    onChange?: (index: number, value: RangeItemValue) => void;
+    /**
+     * Fires once when the user *releases* a slider thumb after dragging,
+     * after an arrow-key adjustment commits, or when the text inputs
+     * blur / Enter. Mirrors MUI `<Slider>`'s `onChangeCommitted`. Use
+     * this for side-effects you want to throttle to "drag end" — e.g.
+     * writing the value to a source filter that triggers refetches.
+     */
+    onChangeCommitted?: (index: number, value: RangeItemValue) => void;
+    /** Number formatter for the slider tooltip and the text input display. */
+    formatter?: (value: number) => string;
+}
 /**
- * Renders a range widget with one or more interactive dual-slider controls for selecting value ranges.
+ * Pure presentational component for the Range widget. Renders one MUI Slider
+ * per item with editable min/max text inputs below — matching the Range v1
+ * UX. Each item is always a two-thumb range; supply `value` to seed the
+ * starting selection, otherwise it defaults to `[min, max]`.
  */
-export declare function RangeUI(props: RangeUIProps): import('react').JSX.Element;
+export declare function RangeUI({ items, onChange, onChangeCommitted, formatter, }: RangeUIProps): import('react').JSX.Element;

package/dist/types/widgets/range/skeleton.d.ts

@@ -1 +1,9 @@
-export declare function RangeSkeleton(): import('react').JSX.Element;
+export interface RangeSkeletonProps {
+    count?: number;
+}
+/**
+ * Loading placeholder for the Range widget. Renders `count` rows, each
+ * matching the slider-then-inputs layout of {@link RangeUI} so the layout
+ * doesn't jump when data resolves.
+ */
+export declare function RangeSkeleton({ count }: RangeSkeletonProps): import('react').JSX.Element;

package/dist/types/widgets/range/style.d.ts

@@ -1,2 +1,40 @@
-import { SxProps, Theme } from '@mui/material';
-export declare const styles: Record<string, SxProps<Theme>>;
+import { Theme } from '@mui/material';
+export declare const styles: {
+    root: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        py: number;
+    };
+    item: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+    };
+    sliderContainer: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        px: number;
+    };
+    slider: {
+        width: string;
+        '&.Mui-disabled': {
+            color: (theme: Theme) => string;
+        };
+    };
+    inputsRow: {
+        display: "flex";
+        gap: number;
+        alignItems: "center";
+    };
+    input: {
+        flex: number;
+        '& .MuiInputBase-input': {
+            textAlign: "center";
+        };
+    };
+    note: {
+        color: "text.secondary";
+    };
+};

package/dist/types/widgets/range/types.d.ts

@@ -1,33 +1,37 @@
 import { ReactNode } from 'react';
-import { BaseWidgetState, WidgetsStoreProps } from '../stores/types.js';
-import { WrapperState } from '../wrapper/types.js';
-import { DownloadItem } from '../actions/download/types.js';
-export interface RangeUIProps {
-    id: WidgetsStoreProps['id'];
-}
+/**
+ * A single two-thumb range entry. Renders as an MUI `<Slider>` with editable
+ * `min` / `max` text inputs below, mirroring the Range v1 widget UX.
+ */
 export interface RangeDataItem {
+    /** Lower bound of the slider track. */
     min: number;
+    /** Upper bound of the slider track. */
     max: number;
-    value?: number[];
+    /**
+     * Current selected range `[low, high]`. When omitted, defaults to
+     * `[min, max]` — i.e. the full track. The consumer owns this value and
+     * updates it in response to `onChange`.
+     */
+    value?: readonly [number, number];
+    /** Step granularity (default `1`). */
     step?: number;
-    marks?: boolean | {
+    /**
+     * Tick marks. Pass `true` to enable MUI's auto-marks (one per `step`); pass
+     * an array for explicit marks; omit for no marks.
+     */
+    marks?: boolean | readonly {
         value: number;
         label?: string;
     }[];
+    /** Disable user interaction for this row (slider + inputs). */
     disabled?: boolean;
+    /** Override the slider's track / thumb colour (any CSS / MUI palette path). */
     color?: string;
-    note?: string | ReactNode;
-}
-export interface RangeItemProps {
-    id: WidgetsStoreProps['id'];
-    index: number;
-}
-export type RangeWidgetData = RangeDataItem[];
-export type RangeWidgetState = BaseWidgetState<WrapperState<RangeWidgetConfig>> & {
-    data: RangeWidgetData;
-};
-export interface RangeWidgetConfig {
-    formatter?: (value: number) => string;
-    onChange?: (value: number[], index: number) => void;
+    /** Optional caption rendered below the inputs row. */
+    note?: ReactNode;
 }
-export type RangeDownloadConfig = DownloadItem<RangeWidgetData>[];
+/** Range widget data — one or more two-thumb entries rendered stacked. */
+export type RangeWidgetData = readonly RangeDataItem[];
+/** The shape `onChange` reports — always a `[low, high]` tuple. */
+export type RangeItemValue = readonly [number, number];

package/dist/types/widgets/scatterplot/index.d.ts

@@ -1,3 +1,5 @@
-export type { ScatterplotWidgetData, ScatterplotWidgetState, ScatterplotWidgetConfig, ScatterplotConfig, } from './types.js';
-export { scatterplotConfig, scatterplotDownloadConfig } from './config.js';
-export { ScatterplotSkeleton } from './skeleton.js';
+export { scatterplotOptions, createScatterplotOptionFactory } from './options.js';
+export { ScatterplotSkeleton, type ScatterplotSkeletonProps } from './skeleton.js';
+export { createScatterplotDownloadConfig } from './download.js';
+export { toRelativeScatterplotData, filterScatterplotByLockedPoints, } from './transforms.js';
+export type { ScatterplotDatum, ScatterplotWidgetData, ScatterplotOptionsInput, ScatterplotOptionFactoryInput, ScatterplotEChartsOption, } from './types.js';

package/dist/types/widgets/scatterplot/skeleton.d.ts

@@ -1 +1,12 @@
-export declare function ScatterplotSkeleton(): import('react').JSX.Element;
+export interface ScatterplotSkeletonProps {
+    /** Number of dots to render. */
+    count?: number;
+}
+/**
+ * Loading state for the Scatterplot widget. Mirrors a scatter chart's
+ * silhouette — a deterministic spread of small circular dots in the plot
+ * area plus a legend stub — so the skeleton reads as "a scatter chart"
+ * rather than a generic list. Matches bar/histogram/pie skeleton structure
+ * (grid stub + legend stub in a flex column).
+ */
+export declare function ScatterplotSkeleton({ count }: ScatterplotSkeletonProps): import('react').JSX.Element;

package/dist/types/widgets/scatterplot/types.d.ts

@@ -1,9 +1,54 @@
-import { EchartWidgetState } from '../echart/index.js';
-import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types.js';
-import { ConfigProps } from '../loader/index.js';
-export type ScatterplotWidgetData = [number, number][][];
-export type ScatterplotWidgetState = EchartWidgetState;
-export type ScatterplotWidgetConfig = EchartWidgetProps & {
-    type: 'scatterplot';
-};
-export type ScatterplotConfig = ConfigProps & EchartWidgetOptionProps<ScatterplotWidgetData>;
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types.js';
+/** A single point — `[x, y]` tuple. */
+export type ScatterplotDatum = readonly [number, number];
+/** Scatterplot widget data — array of series, each a list of `[x, y]` tuples. */
+export type ScatterplotWidgetData = readonly (readonly ScatterplotDatum[])[];
+/** Inputs to the structural-only {@link scatterplotOptions} builder. */
+export interface ScatterplotOptionsInput {
+    theme: Theme;
+    /** Optional formatter for x-axis values. */
+    xFormatter?: (value: number) => string;
+    /** Optional formatter for y-axis values. */
+    yFormatter?: (value: number) => string;
+}
+/**
+ * Combined inputs for the scatterplot option factory creator. Carries
+ * everything the widget needs across BOTH phases — the structural-build
+ * (`theme`, `xFormatter`, `yFormatter`, `optionsOverride`) AND the data
+ * merge (`series`, `symbolSize`, `selection`).
+ */
+export interface ScatterplotOptionFactoryInput {
+    theme: Theme;
+    /**
+     * Optional x-axis value formatter. Drives the structural x-axis
+     * label and the reactive tooltip path: when RelativeData overrides
+     * `state.formatter` (the y formatter) the merger rebuilds the tooltip
+     * and reads `xFormatter` to render coordinates correctly. xFormatter
+     * itself isn't relativized — x stays raw.
+     */
+    xFormatter?: (value: number) => string;
+    /** Optional formatter for y-axis values (structural baseline). */
+    yFormatter?: (value: number) => string;
+    /**
+     * Per-series metadata — drives the legend, `series[i].name`, and
+     * (when `color` is set) a per-series colour override on the points.
+     */
+    series?: readonly WidgetSeries[];
+    /** Symbol size in px (default `8`). */
+    symbolSize?: number;
+    /**
+     * Selected point keys, one per `${seriesIndex}:${dataIndex}` pair. Points
+     * not in this list render dimmed (`itemStyle.opacity: 0.15`). `null`/empty
+     * means no selection.
+     */
+    selection?: readonly string[] | 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 ScatterplotEChartsOption = EChartsOption;

package/dist/types/widgets/selection-summary/selection-summary.d.ts

@@ -1,13 +1,29 @@
-import { WidgetSelectionSummaryProps } from './types.js';
+import { SvgIconProps } from '@mui/material';
+import { ComponentType } from 'react';
+import { SelectionSummaryLabels } from './labels.js';
+export interface SelectionSummaryProps {
+    /** Number of currently selected items. */
+    count: number;
+    /** Optional total — when `undefined` or `0` the component renders nothing (no data). */
+    total?: number;
+    /** Clear callback. The Clear control is shown only when `count > 0` and `onClear` is provided. */
+    onClear?: () => void;
+    labels?: Partial<SelectionSummaryLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
 /**
- * Displays the count of selected items with an optional clear button. Commonly used with the LockSelection action to show selection state in widgets.
+ * Renders a `selected / total` count.
  *
- * @example
- * ```tsx
- * <WidgetSelectionSummary
- *   selections={selectedItems.length}
- *   onClear={() => setSelectedItems([])}
- * />
- * ```
+ * Render rules:
+ *   - `!total` (undefined or 0) → render nothing (no data to summarize).
+ *   - `count === 0` → display `total / total` (everything is implicitly in
+ *     scope); no Clear button.
+ *   - `count > 0` → display `count / total` + Clear (when `onClear` is given).
+ *
+ * The count is two-tone by default (selected number bold/`text.primary`,
+ * ` / total` in `text.secondary`). Pass `labels.summary` to render a custom
+ * node instead — it receives the already-resolved displayed number (which
+ * equals `total` when nothing is selected).
  */
-export declare function WidgetSelectionSummary({ selections, onClear, labels, }: WidgetSelectionSummaryProps): import('react').JSX.Element;
+export declare function SelectionSummary({ count, total, onClear, labels, icon: Icon, iconProps, }: SelectionSummaryProps): import('react').JSX.Element | null;

package/dist/types/widgets/selection-summary/style.d.ts

@@ -1,9 +1,38 @@
-import { Theme } from '@mui/material';
 export declare const styles: {
     root: {
         display: "flex";
         alignItems: "center";
-        flex: string;
-        gap: ({ spacing }: Theme) => string;
+        gap: number;
+        minHeight: number;
+    };
+    label: {
+        color: "text.secondary";
+    };
+    count: {
+        display: "inline-flex";
+        alignItems: "baseline";
+        gap: number;
+    };
+    selected: {
+        color: "text.primary";
+        fontWeight: number;
+    };
+    separator: {
+        color: "text.secondary";
+    };
+    total: {
+        color: "text.secondary";
+    };
+    clear: {
+        color: "primary.main";
+        cursor: "pointer";
+        fontWeight: number;
+        '&:hover': {
+            textDecoration: string;
+        };
+    };
+    icon: {
+        fontSize: number;
+        color: "text.secondary";
     };
 };

package/dist/types/widgets/spread/index.d.ts

@@ -1,9 +1,7 @@
-export { SpreadUI } from './spread-ui.js';
-export { SpreadSkeleton } from './skeleton.js';
-export { spreadConfig, spreadDownloadConfig } from './config.js';
-export { MinValue } from './components/min-value.js';
-export { MaxValue } from './components/max-value.js';
-export { Separator } from './components/separator.js';
-export { Item, Row, Prefix, Suffix, Series } from '../formula/index.js';
-export type { RowProps, ValueProps, SpreadWidgetState, SpreadWidgetConfig, SpreadWidgetData, SpreadDownloadConfig, ItemProps, SpreadDataItem, SpreadUIProps, } from './types.js';
-export type { SeriesConfig } from '../formula/types.js';
+export { Spread } from './spread.js';
+export { SpreadUI, type SpreadUIProps } from './spread-ui.js';
+export { Separator } from './separator.js';
+export { SpreadSkeleton, type SpreadSkeletonProps } from './skeleton.js';
+export { createSpreadDownloadConfig } from './download.js';
+export { getSpreadBand, type SpreadVariant, type GetSpreadBandOptions, } from './band.js';
+export type { SpreadDataItem, SpreadWidgetData } from './types.js';

package/dist/types/widgets/spread/skeleton.d.ts

@@ -1 +1,9 @@
-export declare function SpreadSkeleton(): import('react').JSX.Element;
+export interface SpreadSkeletonProps {
+    count?: number;
+}
+/**
+ * Loading placeholder for the Spread widget. Renders `count` rows, each
+ * sized for the `min — max` pair so the layout doesn't jump once data
+ * resolves. Mirrors the row-per-item structure of {@link SpreadUI}.
+ */
+export declare function SpreadSkeleton({ count }: SpreadSkeletonProps): import('react').JSX.Element;

package/dist/types/widgets/spread/spread-ui.d.ts

@@ -1,5 +1,18 @@
-import { SpreadUIProps } from './types.js';
+import { Ref } from 'react';
+import { SpreadDataItem } from './types.js';
+export interface SpreadUIProps {
+    items: readonly SpreadDataItem[];
+    /** Number formatter — applied to each item's `min` and `max`. */
+    formatter?: (value: number) => string;
+    /** Forwarded to the root `<Box>` so consumers can capture the DOM (PNG export). */
+    ref?: Ref<HTMLDivElement>;
+}
 /**
- * Renders a spread widget displaying min-max value pairs with optional prefixes, suffixes, and series indicators.
+ * Pure presentational component for the Spread widget. Each item renders as
+ * a row containing (in order): optional `Series` avatar, a body with
+ * `[prefix] min — max [suffix]` plus optional `Note`. Reuses the Formula
+ * primitives ({@link Series}, {@link Prefix}, {@link Value}, {@link Suffix},
+ * {@link Note}) and the Formula row styles so Spread and Formula stay
+ * visually aligned when used together.
  */
-export declare function SpreadUI(props: SpreadUIProps): import('react').JSX.Element;
+export declare function SpreadUI({ items, formatter, ref }: SpreadUIProps): import('react').JSX.Element;