@carto/ps-react-ui 4.7.1 → 4.8.0

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

@@ -0,0 +1,107 @@
+import { Provider } from './provider/widget-provider';
+import { Wrapper, Actions, Options, Content, Footer, DEFAULT_WRAPPER_LABELS } from './wrapper';
+import { Subheader } from './subheader/subheader';
+import { State } from './state/widget-state';
+import { DEFAULT_STATE_LABELS } from './state/labels';
+import { SelectionSummary } from './selection-summary/selection-summary';
+import { DEFAULT_SELECTION_SUMMARY_LABELS } from './selection-summary/labels';
+import { Toolbox } from './toolbox/toolbox';
+import { DEFAULT_TOOLBOX_LABELS } from './toolbox/labels';
+import { Echart, EchartUI, DEFAULT_INIT_OPTS } from './echart';
+import { DEFAULT_NOTE_LABELS } from './note/labels';
+import { Searcher, SearcherToggle, StackToggle, ZoomToggle, BrushToggle, RelativeData, Download, LockSelection, ChangeColumn } from './actions';
+import { Formula, FormulaUI } from './formula';
+import { Markdown, MarkdownUI } from './markdown';
+import { Spread, SpreadUI } from './spread';
+import { Range, RangeUI } from './range';
+import { Category, CategoryUI } from './category';
+import { Table, TableUI } from './table';
+/**
+ * Curated namespace export — the only way to reach v2 widget components.
+ * Consumers import the const and access components via property access:
+ *
+ * ```tsx
+ * import { Widget } from '@carto/ps-react-ui/widgets-v2'
+ *
+ * <Widget.Provider id={id} data={data}>
+ *   <Widget.Wrapper title='Sales'>
+ *     <Widget.Content>
+ *       <Widget.State skeleton={<BarSkeleton />}>
+ *         <Widget.Echart optionFactory={optionFactory} />
+ *       </Widget.State>
+ *     </Widget.Content>
+ *   </Widget.Wrapper>
+ * </Widget.Provider>
+ * ```
+ *
+ * Component identifiers are not surfaced as separate named exports — Types
+ * (props, data shapes, label types, default-label consts) and per-widget
+ * subpath entries (`@carto/ps-react-ui/widgets-v2/bar`, `…/category`,
+ * `…/table`, `…/actions`, `…/stores`, `…/utils`, etc.) remain available for
+ * direct import where needed.
+ */
+export declare const Widget: {
+    readonly Provider: typeof Provider;
+    readonly Wrapper: typeof Wrapper;
+    readonly Actions: typeof Actions;
+    readonly Options: typeof Options;
+    readonly Content: typeof Content;
+    readonly Footer: typeof Footer;
+    readonly Subheader: typeof Subheader;
+    readonly State: typeof State;
+    readonly SelectionSummary: typeof SelectionSummary;
+    readonly Toolbox: typeof Toolbox;
+    readonly Note: (({ lineClamp, labels, children }: import('.').NoteProps) => import("react/jsx-runtime").JSX.Element) & {
+        Markdown: ({ content, lineClamp, labels }: import('.').NoteMarkdownProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    readonly Echart: typeof Echart;
+    readonly EchartUI: typeof EchartUI;
+    readonly Searcher: typeof Searcher;
+    readonly SearcherToggle: typeof SearcherToggle;
+    readonly StackToggle: typeof StackToggle;
+    readonly ZoomToggle: typeof ZoomToggle;
+    readonly BrushToggle: typeof BrushToggle;
+    readonly RelativeData: typeof RelativeData;
+    readonly Download: typeof Download;
+    readonly FullScreen: {
+        Trigger: ({ labels, enterIcon: EnterIcon, exitIcon: ExitIcon, iconProps, }: import('./actions').FullScreenTriggerProps) => import("react/jsx-runtime").JSX.Element;
+        Slot: ({ children, title, labels, closeIcon: CloseSvg, iconProps, }: import('./actions').FullScreenSlotProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    readonly LockSelection: typeof LockSelection;
+    readonly ChangeColumn: typeof ChangeColumn;
+    readonly Formula: typeof Formula;
+    readonly FormulaUI: typeof FormulaUI;
+    readonly Markdown: typeof Markdown;
+    readonly MarkdownUI: typeof MarkdownUI;
+    readonly Spread: typeof Spread;
+    readonly SpreadUI: typeof SpreadUI;
+    readonly Range: typeof Range;
+    readonly RangeUI: typeof RangeUI;
+    readonly Category: typeof Category;
+    readonly CategoryUI: typeof CategoryUI;
+    readonly Table: typeof Table;
+    readonly TableUI: typeof TableUI;
+};
+export { DEFAULT_WRAPPER_LABELS, DEFAULT_STATE_LABELS, DEFAULT_SELECTION_SUMMARY_LABELS, DEFAULT_TOOLBOX_LABELS, DEFAULT_NOTE_LABELS, DEFAULT_INIT_OPTS, };
+export type { ProviderProps } from './provider/widget-provider';
+export type { WrapperProps, ActionsProps, OptionsProps, ContentProps, FooterProps, WrapperLabels, } from './wrapper';
+export type { SubheaderProps } from './subheader/subheader';
+export type { StateProps } from './state/widget-state';
+export type { StateLabels } from './state/labels';
+export type { SelectionSummaryProps } from './selection-summary/selection-summary';
+export type { SelectionSummaryLabels } from './selection-summary/labels';
+export type { ToolboxProps } from './toolbox/toolbox';
+export type { ToolboxLabels } from './toolbox/labels';
+export type { EchartProps, EchartUIProps, EchartsEventHandler } from './echart';
+export type { NoteProps, NoteMarkdownProps } from './note/widget-note';
+export type { NoteLabels } from './note/labels';
+export type { SearcherProps, SearcherToggleProps, StackToggleProps, ZoomToggleProps, BrushToggleProps, RelativeDataProps, DownloadProps, DownloadItem, FullScreenTriggerProps, FullScreenSlotProps, LockSelectionProps, LockSelectionKey, ChangeColumnProps, ChangeColumnItem, } from './actions';
+export type { FormulaUIProps, FormulaDataItem, FormulaWidgetData, } from './formula';
+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 { RangeProps, RangeUIProps, RangeDataItem, RangeWidgetData, RangeItemValue, } from './range';
+export type { CategoryProps, CategoryUIProps, CategoryDataItem, CategoryWidgetData, CategoryKey, CategorySeriesConfig, CategoryLabels, } from './category';
+export type { TableProps, TableUIProps, TableColumn, TableRow, TableWidgetData, TableWidgetState, TableSortDirection, TableSortState, } from './table';

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

@@ -0,0 +1,16 @@
+import { toCsvString, triggerLinkDownload, DownloadItem } from '../actions/download';
+import { MarkdownWidgetData } from './types';
+/**
+ * Download menu items for the Markdown widget. Always includes a `.md`
+ * item that saves the markdown source verbatim. When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export declare function createMarkdownDownloadConfig(args: {
+    filename: string;
+    getData: () => MarkdownWidgetData;
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];
+export { toCsvString, triggerLinkDownload };

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

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

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

@@ -0,0 +1,6 @@
+export { Markdown } from './markdown';
+export { MarkdownUI, type MarkdownUIProps } from './markdown-ui';
+export { MarkdownContent, type MarkdownContentProps } from './markdown-content';
+export { MarkdownSkeleton, type MarkdownSkeletonProps } from './skeleton';
+export { createMarkdownDownloadConfig } from './download';
+export type { MarkdownWidgetData } from './types';

package/dist/types/widgets-v2/markdown/markdown-content.d.ts

@@ -0,0 +1,34 @@
+import { Components } from 'react-markdown';
+export interface MarkdownContentProps {
+    /** Markdown source. */
+    content: string;
+    /**
+     * Element overrides. Consumers (`MarkdownUI`, `Note`, …) supply their own
+     * typography / link styling here; the engine itself stays opinion-free.
+     */
+    components?: Components;
+    /**
+     * When `true`, raw HTML in the source is rendered. Defaults to `false` so
+     * caption slots like `Note` stay safe-by-default; the document-style
+     * Markdown widget opts in.
+     */
+    allowHtml?: boolean;
+    /**
+     * When `true`, `<img>` / `![alt](url)` markdown produces an `<img>` tag.
+     * Defaults to `false` so caption slots stay text-only by default.
+     */
+    allowImages?: boolean;
+}
+/**
+ * Low-level Markdown rendering primitive. Wraps `react-markdown` with two
+ * opt-in capabilities (`allowHtml`, `allowImages`) and a consumer-supplied
+ * component map for typography. Both default OFF — Note-style consumers
+ * are safe-by-default; MarkdownUI opts both ON to render rich content.
+ *
+ * `allowHtml` plugs in `rehype-raw` so raw HTML nodes in the source are
+ * actually parsed, then `rehype-sanitize` with the default schema strips
+ * `<script>`, event handlers, and dangerous URL schemes from the parsed
+ * tree. `safeUrlTransform` is always applied as a second layer for markdown
+ * links/images on the `allowHtml=false` path.
+ */
+export declare function MarkdownContent({ content, components, allowHtml, allowImages, }: MarkdownContentProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+export interface MarkdownUIProps {
+    content: string;
+}
+/**
+ * Pure presentational component for the Markdown widget. Delegates the
+ * `react-markdown` engine to {@link MarkdownContent} and supplies a
+ * document-style MUI element mapping (body2 paragraphs, real heading
+ * typography). Opts INTO raw HTML and inline images — the Markdown widget is
+ * the one slot in the library where authors can ship rich content. Caption
+ * slots like `Note` keep the conservative defaults.
+ */
+export declare function MarkdownUI({ content }: MarkdownUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,6 @@
+/**
+ * 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(): import("react/jsx-runtime").JSX.Element;

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

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

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

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

@@ -0,0 +1,4 @@
+/** Markdown widget data — a single markdown source string. */
+export interface MarkdownWidgetData {
+    content: string;
+}

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

@@ -0,0 +1,5 @@
+export interface NoteLabels {
+    showMore: string;
+    showLess: string;
+}
+export declare const DEFAULT_NOTE_LABELS: NoteLabels;

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

@@ -0,0 +1,26 @@
+export declare const styles: {
+    root: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+    };
+    text: {
+        color: "text.secondary";
+        overflow: "hidden";
+        overflowWrap: "anywhere";
+    };
+    clamped: {
+        display: "-webkit-box";
+        WebkitBoxOrient: "vertical";
+        WebkitLineClamp: number;
+    };
+    toggle: {
+        alignSelf: "flex-start";
+        color: "primary.main";
+        fontWeight: number;
+        cursor: "pointer";
+        '&:hover': {
+            textDecoration: string;
+        };
+    };
+};

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,50 @@
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+/** 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
+ * (`seriesNames`, `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;
+    /** Series names — drives the legend and series.name. */
+    seriesNames?: readonly string[];
+    /**
+     * 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,19 @@
+import { RangeDataItem, RangeItemValue } from './types';
+export interface RangeUIProps {
+    items: readonly RangeDataItem[];
+    /**
+     * Fires when the user drags a thumb or commits a new value via the text
+     * inputs. Per the destination-owned principle, the consumer owns the
+     * value — this widget surfaces changes but does not store them.
+     */
+    onChange?: (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, formatter }: RangeUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,19 @@
+import { RangeItemValue } from './types';
+export interface RangeProps {
+    /**
+     * Fires when the user moves a slider thumb or commits a new value via the
+     * text inputs. Receives the item index in `state.data` and the new
+     * `[low, high]` tuple. The consumer owns the data state — the widget
+     * surfaces changes but does not persist them.
+     */
+    onChange?: (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` — 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 }: 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];