@carto/ps-react-ui 4.4.0-chat-ui.5 → 4.4.0-chat-ui.7

package/dist/types/widgets-v2/note/widget-note.d.ts

@@ -0,0 +1,46 @@
+import { ReactNode } from 'react';
+import { NoteLabels } from './labels';
+export interface NoteProps {
+    /**
+     * Maximum visible lines before clamping. Defaults to 3. Set to `0` to
+     * disable clamping entirely — full content renders and the Show More/Less
+     * toggle is never shown.
+     */
+    lineClamp?: number;
+    labels?: Partial<NoteLabels>;
+    /**
+     * Renders verbatim inside the caption shell. For markdown source (a
+     * string with `**bold**`, lists, links, etc.) reach for the
+     * `<Note.Markdown>` subcomponent instead — it pipes the string through
+     * the shared {@link MarkdownContent} engine with caption-safe element
+     * mapping.
+     */
+    children: ReactNode;
+}
+export interface NoteMarkdownProps {
+    /** Markdown source. Rendered with caption typography via {@link MarkdownContent}. */
+    content: string;
+    /** Maximum visible lines before clamping. Defaults to 3. */
+    lineClamp?: number;
+    labels?: Partial<NoteLabels>;
+}
+/**
+ * Auxiliary slot for an optional explanatory note below a widget. Clamps to
+ * `lineClamp` lines (default 3) and reveals a Show More/Less toggle when the
+ * content overflows. Overflow detection re-runs on container resize via the
+ * shared singleton ResizeObserver.
+ *
+ * Renders `children` verbatim through caption typography. For markdown
+ * source, use the {@link NoteMarkdown} (`Note.Markdown`) subcomponent.
+ */
+declare function NoteBase({ lineClamp, labels, children }: NoteProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Markdown variant of {@link Note}. Pipes the `content` string through the
+ * shared {@link MarkdownContent} engine with caption-safe element mapping
+ * (headings demoted, links open in new tabs, images/HTML stripped).
+ */
+declare function NoteMarkdown({ content, lineClamp, labels }: NoteMarkdownProps): import("react/jsx-runtime").JSX.Element;
+export declare const Note: typeof NoteBase & {
+    Markdown: typeof NoteMarkdown;
+};
+export {};

package/dist/types/widgets-v2/pie/download.d.ts

@@ -0,0 +1,17 @@
+import { DownloadItem } from '../actions/download';
+import { PieWidgetData } from './types';
+/**
+ * Download menu items for the Pie widget. Always includes a CSV item with
+ * `series, name, value` columns (one row per slice; series labels come from
+ * `seriesNames` if provided, else `series_<n>`). When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export declare function createPieDownloadConfig(args: {
+    filename: string;
+    getData: () => PieWidgetData;
+    seriesNames?: readonly string[];
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

package/dist/types/widgets-v2/pie/download.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+export { pieOptions, createPieOptionFactory } from './options';
+export { PieSkeleton, type PieSkeletonProps } from './skeleton';
+export { createPieDownloadConfig } from './download';
+export type { PieDatum, PieWidgetData, PieOptionsInput, PieOptionFactoryInput, PieEChartsOption, } from './types';

package/dist/types/widgets-v2/pie/options.d.ts

@@ -0,0 +1,35 @@
+import { OptionFactory } from '../echart';
+import { PieEChartsOption, PieOptionFactoryInput, PieOptionsInput } from './types';
+/**
+ * Builds the **structural** ECharts option for a pie / donut widget.
+ * Mirrors v1's pie look-and-feel: themed legend (`buildLegendConfig`),
+ * themed tooltip via `createTooltipPositioner` / `createTooltipFormatter`,
+ * `qualitative.bold` color palette, slice borders against the paper
+ * background, hover-emphasis disabled, and a centered rich-text label.
+ *
+ * Layered like Bar / Histogram:
+ *   - **Theme-aware bits** live here on a series template (slice border,
+ *     center-label rich style sizes, emphasis-disabled).
+ *   - **Reactive bits** (tooltip value formatter, center-label text,
+ *     selection-driven dim) are re-emitted by
+ *     {@link createPieOptionFactory} at fusion time so RelativeData's
+ *     percent override flows through.
+ */
+export declare function pieOptions({ theme, formatter, labelFormatter, }: PieOptionsInput): PieEChartsOption;
+/**
+ * Returns the pie 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 pieOptions}, optionally merging the
+ *     consumer-supplied `optionsOverride` on top. Called once by Provider
+ *     to seed `rawOptions` in the store.
+ *   - **Merge phase** (`option != null`) — fuses post-pipeline `state.data`
+ *     (`PieWidgetData`) into the option via the dataset API. Single-series
+ *     → donut (one dataset, `series[i].encode = { itemName: 'name', value: 'value' }`).
+ *     Multi-series → horizontal-bar fallback (mirrors v1 pie). Reactive
+ *     formatters from `ctx` drive the tooltip + center label at fusion
+ *     time so RelativeData's percent formatter flows through without a
+ *     structural rebuild.
+ */
+export declare function createPieOptionFactory(options: PieOptionFactoryInput): OptionFactory;

package/dist/types/widgets-v2/pie/options.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+export interface PieSkeletonProps {
+    count?: number;
+}
+export declare function PieSkeleton({ count }: PieSkeletonProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,57 @@
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types';
+/** 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-v2/provider/widget-provider.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react';
+export interface ProviderProps {
+    id: string;
+    data: unknown;
+    isLoading?: boolean;
+    isFetching?: boolean;
+    error?: unknown;
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+    /**
+     * When `true`, the per-widget store survives unmount so transformStates,
+     * search text, fullscreen state, etc. are preserved across remounts.
+     * Consumers using keepAlive must call `deleteWidgetStore(id)` themselves
+     * when the widget is permanently removed — there is no automatic GC.
+     */
+    keepAlive?: boolean;
+    children: ReactNode;
+}
+/**
+ * Renderer-agnostic widget shell. Creates a per-widget Zustand store
+ * keyed by `id`, syncs the consumer props (`data`, `isLoading`, `error`,
+ * `formatter`, …) onto it, and exposes the `id` via `WidgetContext` so
+ * descendants can resolve their store with `useWidgetId()`.
+ *
+ * The Provider deliberately doesn't know about ECharts — there's no
+ * `optionFactory` prop here. ECharts-backed widgets pass their factory
+ * to `<Widget.Echart optionFactory={…}>`, which owns the structural
+ * seed + the data-fusion render step entirely. Non-Echart widgets
+ * (Formula, Spread, Range, Table, Category, Markdown) just don't pass
+ * anything ECharts-shaped.
+ */
+export declare function Provider({ id, data, isLoading, isFetching, error, formatter, labelFormatter, keepAlive, children, }: ProviderProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,4 @@
+export { Range, type RangeProps } from './range';
+export { RangeUI, type RangeUIProps } from './range-ui';
+export { RangeSkeleton, type RangeSkeletonProps } from './skeleton';
+export type { RangeDataItem, RangeWidgetData, RangeItemValue } from './types';

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

@@ -0,0 +1,27 @@
+import { RangeDataItem, RangeItemValue } from './types';
+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;
+}
+/**
+ * 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({ items, onChange, onChangeCommitted, formatter, }: RangeUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,24 @@
+import { RangeItemValue } from './types';
+export interface RangeProps {
+    /**
+     * Fires on every pointer tick while a thumb is being dragged. Use this
+     * for cheap UI updates (local state, optimistic display).
+     */
+    onChange?: (index: number, value: RangeItemValue) => void;
+    /**
+     * Fires once when the user *releases* a slider thumb (or when the text
+     * inputs blur / Enter, or when an arrow-key adjustment settles). Use
+     * this for expensive side-effects you want throttled to drag end —
+     * e.g. writing the value to a source filter that refetches widgets.
+     */
+    onChangeCommitted?: (index: number, value: RangeItemValue) => void;
+}
+/**
+ * Stateful Range bridge — reads `data` (post-pipeline) and `formatter` from
+ * the per-widget store and forwards them to the pure {@link RangeUI}. Per
+ * the destination-owned principle, value changes flow back through
+ * `onChange` (per-tick) and `onChangeCommitted` (drag end) — the consumer
+ * is expected to update the data prop on `<Provider>`. Use `disabled` on
+ * individual `RangeDataItem`s to disable specific rows.
+ */
+export declare function Range({ onChange, onChangeCommitted }: RangeProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,9 @@
+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-runtime").JSX.Element;

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

@@ -0,0 +1,40 @@
+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-v2/range/types.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+/**
+ * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Optional caption rendered below the inputs row. */
+    note?: ReactNode;
+}
+/** 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-v2/scatterplot/download.d.ts

@@ -0,0 +1,16 @@
+import { DownloadItem } from '../actions/download';
+import { ScatterplotWidgetData } from './types';
+/**
+ * Download menu items for the Scatterplot widget. Always includes a CSV
+ * item with `series, x, y` columns (one row per point). When
+ * `getCaptureEl` is supplied, prepends a PNG item that rasterises the
+ * captured element via `html2canvas`.
+ */
+export declare function createScatterplotDownloadConfig(args: {
+    filename: string;
+    getData: () => ScatterplotWidgetData;
+    seriesNames?: readonly string[];
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

package/dist/types/widgets-v2/scatterplot/download.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+export { scatterplotOptions, createScatterplotOptionFactory } from './options';
+export { ScatterplotSkeleton, type ScatterplotSkeletonProps } from './skeleton';
+export { createScatterplotDownloadConfig } from './download';
+export { toRelativeScatterplotData } from './transforms';
+export type { ScatterplotDatum, ScatterplotWidgetData, ScatterplotOptionsInput, ScatterplotOptionFactoryInput, ScatterplotEChartsOption, } from './types';

package/dist/types/widgets-v2/scatterplot/options.d.ts

@@ -0,0 +1,42 @@
+import { OptionFactory } from '../echart';
+import { ScatterplotEChartsOption, ScatterplotOptionFactoryInput, ScatterplotOptionsInput } from './types';
+/**
+ * Builds the **structural** ECharts option for a scatterplot widget — both
+ * axes `type: 'value'` (not category, unlike Bar/Histogram), grid, tooltip
+ * triggered per-item rather than per-axis. Intentionally data-agnostic: no
+ * series, no dataset, no `legend.show` (those depend on data and are added
+ * by {@link createScatterplotOptionFactory}).
+ *
+ * Styling parity with v1: dark themed tooltip via `createTooltipFormatter`
+ * + `createTooltipPositioner`, `buildGridConfig`-based grid, polished
+ * axisLine/Tick/splitLine, `overlineDelicate` axis labels, structural
+ * legend wired via `buildLegendConfig` (toggled by the merger), and the
+ * CARTO `qualitative.bold + secondary` palette — same pattern bar /
+ * histogram / pie already use. {@link createScatterplotOptionFactory}
+ * wraps this builder in its structural-phase branch.
+ */
+export declare function scatterplotOptions({ theme, xFormatter, yFormatter, }: ScatterplotOptionsInput): ScatterplotEChartsOption;
+/**
+ * Returns the scatterplot 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 scatterplotOptions}, 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`
+ *     (`ScatterplotWidgetData`) into the option via the dataset API. Each
+ *     series's `[x, y]` tuples land in `dataset[i].source` as 2-column
+ *     rows; the series uses positional encoding (`encode: { x: 0, y: 1 }`)
+ *     and `type: 'scatter'`. niceMin/niceMax are computed over both axes
+ *     so the chart frames data on rounded extents and numeric jitters
+ *     don't shift gridlines per render. Reactive `ctx.formatter` (driven
+ *     by RelativeData) re-derives the y-axis label and tooltip at fusion
+ *     time; `xFormatter` stays baked at structural-build time (relative
+ *     is a values-axis concept; x is coordinate-space).
+ *
+ * When `ZoomToggle` installs a `dataZoom` slider, grid bottom is
+ * extended and the slider is positioned above the legend row (if any) —
+ * same layout dance bar / histogram / timeseries do.
+ */
+export declare function createScatterplotOptionFactory(options: ScatterplotOptionFactoryInput): OptionFactory;

package/dist/types/widgets-v2/scatterplot/options.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+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-runtime").JSX.Element;

package/dist/types/widgets-v2/scatterplot/transforms.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Scatterplot-specific `RelativeData` transform. Scatter data is
+ * `[number, number][]` — each series is a list of `[x, y]` tuples.
+ * Relative is a values-axis concept, so this rewrites `y` to its
+ * share of the series's total `y` (0–100) and leaves `x` raw — x is
+ * coordinate space, not part of the cohort total.
+ *
+ * Pass to `<Widget.RelativeData transform={toRelativeScatterplotData} />`.
+ *
+ * The denominator is the sum of |y| across the series so mixed-sign
+ * y values produce sane signed shares-of-magnitude. A series whose
+ * total y-magnitude is zero (all-zero or empty input) is returned
+ * unchanged so a stalled or empty data set doesn't show misleading 0%
+ * values. Inputs whose shape isn't `[number, number][]` fall through
+ * untouched.
+ */
+export declare const toRelativeScatterplotData: (input: unknown) => unknown;

package/dist/types/widgets-v2/scatterplot/transforms.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,54 @@
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types';
+/** 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-v2/selection-summary/labels.d.ts

@@ -0,0 +1,6 @@
+export interface SelectionSummaryLabels {
+    allSelected: string;
+    selections: (count: number) => string;
+    clear: string;
+}
+export declare const DEFAULT_SELECTION_SUMMARY_LABELS: SelectionSummaryLabels;

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

@@ -0,0 +1,22 @@
+import { SvgIconProps } from '@mui/material';
+import { ComponentType } from 'react';
+import { SelectionSummaryLabels } from './labels';
+export interface SelectionSummaryProps {
+    /** Number of currently selected items. */
+    count: number;
+    /** Optional total — when 0 the component renders nothing (no data to summarize). */
+    total?: number;
+    /** Clear callback. Shown only when count > 0. */
+    onClear?: () => void;
+    labels?: Partial<SelectionSummaryLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+/**
+ * Render rules:
+ *   - `total === 0` → render nothing.
+ *   - `count === 0` → render `labels.allSelected` (matches v1 default),
+ *     prefixed with the optional `icon` glyph when provided.
+ *   - `count > 0`   → render `labels.selections(count)` + Clear (when `onClear`).
+ */
+export declare function SelectionSummary({ count, total, onClear, labels, icon: Icon, iconProps, }: SelectionSummaryProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,23 @@
+export declare const styles: {
+    root: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        minHeight: number;
+    };
+    label: {
+        color: "text.secondary";
+    };
+    clear: {
+        color: "primary.main";
+        cursor: "pointer";
+        fontWeight: number;
+        '&:hover': {
+            textDecoration: string;
+        };
+    };
+    icon: {
+        fontSize: number;
+        color: "text.secondary";
+    };
+};

package/dist/types/widgets-v2/spread/download.d.ts

@@ -0,0 +1,15 @@
+import { DownloadItem } from '../actions/download';
+import { SpreadWidgetData } from './types';
+/**
+ * Download menu items for the Spread widget. Always includes a CSV item
+ * with `series, prefix, min, max, suffix, note` columns (one row per
+ * entry). When `getCaptureEl` is supplied, prepends a PNG item that
+ * rasterises the captured element via `html2canvas`.
+ */
+export declare function createSpreadDownloadConfig(args: {
+    filename: string;
+    getData: () => SpreadWidgetData;
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

package/dist/types/widgets-v2/spread/download.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+export { Spread } from './spread';
+export { SpreadUI, type SpreadUIProps } from './spread-ui';
+export { Separator } from './separator';
+export { SpreadSkeleton, type SpreadSkeletonProps } from './skeleton';
+export { createSpreadDownloadConfig } from './download';
+export type { SpreadDataItem, SpreadWidgetData } from './types';

package/dist/types/widgets-v2/spread/separator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Em-dash separator placed between a Spread row's `min` and `max` values.
+ * Built from the Formula {@link Value} primitive so typography (h5/600,
+ * baseline alignment) matches the numbers around it. Renders with
+ * `text.secondary` so it visually recedes between the two bounds.
+ */
+export declare function Separator(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,9 @@
+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-runtime").JSX.Element;

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

@@ -0,0 +1,18 @@
+import { Ref } from 'react';
+import { SpreadDataItem } from './types';
+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>;
+}
+/**
+ * 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({ items, formatter, ref }: SpreadUIProps): import("react/jsx-runtime").JSX.Element;