@carto/ps-react-ui 4.7.1 → 4.9.0

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

@@ -0,0 +1,11 @@
+import { SxProps, Theme } from '@mui/material';
+import { ReactNode } from 'react';
+export interface SubheaderProps {
+    sx?: SxProps<Theme>;
+    children: ReactNode;
+}
+/**
+ * Stateless layout: CSS grid `1fr auto`. Children self-place — typically
+ * `<Widget.SelectionSummary />` (left) and `<Widget.Toolbox>` (right).
+ */
+export declare function Subheader({ sx, children }: SubheaderProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,18 @@
+import { DownloadItem } from '../actions/download';
+import { TableColumn, TableWidgetData } from './types';
+/**
+ * Download menu items for the Table widget. Always includes a CSV item
+ * that pulls the latest data from the widget store via `getData()` (so
+ * locked / sorted / filtered state is honored); headers come from
+ * `column.label`, cells from `row[column.id]`. When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export declare function createTableDownloadConfig(opts: {
+    filename: string;
+    getData: () => TableWidgetData;
+    columns: readonly TableColumn[];
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

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

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

package/dist/types/widgets-v2/table/helpers.d.ts

@@ -0,0 +1,32 @@
+import { TableColumn, TableRow, TableSortDirection, TableWidgetData } from './types';
+/**
+ * Compares two values with a consistent ordering across primitive types.
+ * Strings use locale comparison; numbers subtract; booleans rank false < true;
+ * objects/arrays compare by JSON serialization. Null/undefined sort to the end
+ * regardless of direction.
+ */
+export declare function compareValues(a: unknown, b: unknown, direction: TableSortDirection): number;
+/** Returns a new array sorted by the named column. Does not mutate the input. */
+export declare function sortRows<T extends TableRow>(rows: readonly T[], columnId: string, direction: TableSortDirection): T[];
+/** Returns the slice for the requested page. Out-of-range pages return []. */
+export declare function paginateRows<T>(rows: readonly T[], page: number, pageSize: number): T[];
+/**
+ * Resolves the effective column list. When the widget store has a
+ * `columnOrder` set (e.g. ChangeColumn was used), the column array is
+ * reordered to match. Unknown ids in the order are skipped; columns not
+ * present in the order keep their original relative position at the end.
+ */
+export declare function resolveColumns(columns: readonly TableColumn[], columnOrder: readonly string[] | undefined): readonly TableColumn[];
+/** Applies sort and pagination to the input data. Pure. */
+export declare function deriveVisibleRows<T extends TableRow>(rows: readonly T[], options: {
+    sort?: {
+        columnId: string | null;
+        direction: TableSortDirection;
+    };
+    page: number;
+    pageSize: number;
+}): {
+    sorted: readonly T[];
+    visible: T[];
+};
+export declare function tableDataToCsv(data: TableWidgetData, columns: readonly TableColumn[]): string;

package/dist/types/widgets-v2/table/helpers.test.d.ts

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

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

@@ -0,0 +1,7 @@
+export { Table, type TableProps } from './table';
+export { TableUI, type TableUIProps } from './table-ui';
+export { TableSkeleton, type TableSkeletonProps } from './skeleton';
+export { createTableDownloadConfig } from './download';
+export { compareValues, sortRows, paginateRows, resolveColumns, deriveVisibleRows, tableDataToCsv, } from './helpers';
+export { DEFAULT_TABLE_LABELS, type TableLabels } from './labels';
+export { DEFAULT_TABLE_PAGE_SIZE, DEFAULT_TABLE_PAGE_SIZE_OPTIONS, type TableColumn, type TableRow, type TableWidgetData, type TableWidgetState, type TableSortDirection, type TableSortState, } from './types';

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

@@ -0,0 +1,22 @@
+import { ReactNode } from 'react';
+export interface TableLabels {
+    selectAll: string;
+    selectRow: (rowId: string | number) => string;
+    rowsPerPage: string;
+    /**
+     * Renders the displayed-rows summary in the pagination footer. Returns
+     * a `ReactNode` so the default can emphasise the active range
+     * (`from-to`) with a bolder weight while keeping the trailing
+     * ` of total` muted. Override to localise wording or restyle.
+     */
+    paginationOf: (from: number, to: number, total: number) => ReactNode;
+    /** aria-label for the first-page pagination button. */
+    firstPage: string;
+    /** aria-label for the previous-page pagination button. */
+    previousPage: string;
+    /** aria-label for the next-page pagination button. */
+    nextPage: string;
+    /** aria-label for the last-page pagination button. */
+    lastPage: string;
+}
+export declare const DEFAULT_TABLE_LABELS: TableLabels;

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

@@ -0,0 +1,22 @@
+import { TableProps as MuiTableProps } from '@mui/material';
+export interface TableSkeletonProps {
+    /** Number of body rows to render. Defaults to `5` (matches v1). */
+    rows?: number;
+    /** Number of columns to render. Defaults to `4` (matches v1). */
+    columns?: number;
+    /**
+     * Forwarded to MUI's `<Table size>` so the loading layout matches the
+     * size you'll render in {@link TableUI}. Leave `undefined` (the
+     * default) to use MUI's own default density.
+     */
+    size?: MuiTableProps['size'];
+}
+/**
+ * Loading placeholder for the Table widget. Renders the same MUI table
+ * primitives that {@link TableUI} uses so the loading layout (column
+ * widths, header band, row density) doesn't shift when data resolves.
+ *
+ * Mirrors the v1 widget's `<TableSkeleton>` structure with v2's themed
+ * `styles.headerCell`.
+ */
+export declare function TableSkeleton({ rows, columns, size, }: TableSkeletonProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,40 @@
+export declare const styles: {
+    container: {
+        width: string;
+        overflowX: "auto";
+    };
+    table: {
+        minWidth: number;
+    };
+    headerCell: {
+        fontWeight: number;
+        backgroundColor: "background.paper";
+    };
+    /**
+     * Strip the bottom border from the last body row so the body flushes
+     * against the pagination border instead of doubling it up. Mirrors v1.
+     */
+    row: {
+        '&:last-child td, &:last-child th': {
+            border: number;
+        };
+    };
+    rowClickable: {
+        cursor: "pointer";
+    };
+    pagination: {
+        borderTop: string;
+        borderColor: "divider";
+    };
+    paginationActions: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        ml: number;
+    };
+    empty: {
+        textAlign: "center";
+        color: "text.secondary";
+        py: number;
+    };
+};

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

@@ -0,0 +1,44 @@
+import { TableProps as MuiTableProps } from '@mui/material';
+import { TableLabels } from './labels';
+import { TableColumn, TableRow, TableSortState } from './types';
+export interface TableUIProps<T extends TableRow = TableRow> {
+    columns: readonly TableColumn[];
+    /** Already-paginated, already-sorted rows for the current view. */
+    rows: readonly T[];
+    /** Total row count (across all pages). Required for pagination footer. */
+    total: number;
+    page: number;
+    pageSize: number;
+    pageSizeOptions?: readonly number[];
+    sort?: TableSortState;
+    /**
+     * Column name to use as the row identity. Drives selection lookup,
+     * React keys, and aria labels. Defaults to `'id'` — point it at
+     * another column when your rows don't carry an `id` field.
+     */
+    keyColumn?: string;
+    /** Selected row ids. Destination-owned. */
+    selection?: readonly (string | number)[];
+    selectable?: boolean;
+    onSortChange?: (next: TableSortState) => void;
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (pageSize: number) => void;
+    onSelectionChange?: (next: readonly (string | number)[]) => void;
+    onRowClick?: (row: T) => void;
+    onRowHover?: (row: T | null) => void;
+    labels?: Partial<TableLabels>;
+    /** Row rendered when `rows` is empty for the current page. */
+    emptyContent?: React.ReactNode;
+    /**
+     * Forwarded to MUI's `<Table size>` — `'small'` for compact rows,
+     * `'medium'` for the default density. Leave `undefined` (the default)
+     * to let MUI's own default kick in.
+     */
+    size?: MuiTableProps['size'];
+}
+/**
+ * Pure renderer for a paginated, sortable, optionally-selectable table.
+ * Has no widget-store coupling — `<Table>` (the bridge) reads from the store
+ * and feeds this UI with already-projected data.
+ */
+export declare function TableUI<T extends TableRow = TableRow>({ columns, rows, total, page, pageSize, pageSizeOptions, sort, keyColumn, selection, selectable, onSortChange, onPageChange, onPageSizeChange, onSelectionChange, onRowClick, onRowHover, labels, emptyContent, size, }: TableUIProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,50 @@
+import { TableUIProps } from './table-ui';
+import { TableColumn, TableRow, TableSortState } from './types';
+export interface TableProps<T extends TableRow = TableRow> extends Pick<TableUIProps<T>, 'pageSizeOptions' | 'selectable' | 'labels' | 'emptyContent' | 'size' | 'keyColumn'> {
+    /**
+     * Column definitions. Order can be overridden by ChangeColumn via the
+     * `columnOrder` field on the extended widget state.
+     */
+    columns: readonly TableColumn[];
+    /**
+     * When set, render only the first `visibleColumns` entries **after**
+     * applying the user's `columnOrder` from the store. Useful for showing
+     * a compact projection while letting consumers (e.g. `Widget.ChangeColumn`)
+     * see the full column list. When omitted, every column renders.
+     */
+    visibleColumns?: number;
+    /** Initial page size (only on first mount; afterwards lives on the store). */
+    initialPageSize?: number;
+    /** Selected row ids (destination-owned). */
+    selection?: readonly (string | number)[];
+    onSelectionChange?: (next: readonly (string | number)[]) => void;
+    onRowClick?: (row: T) => void;
+    onRowHover?: (row: T | null) => void;
+    /**
+     * When `true`, the bridge stops sorting and paginating locally and
+     * renders `data` as-is — the consumer is then responsible for
+     * refetching the slice that matches the active `page` / `pageSize` /
+     * `sort` from the outbound callbacks below. `total` is required in
+     * this mode (the server already knows the full row count; the
+     * widget can't infer it from a partial page).
+     */
+    remote?: boolean;
+    /**
+     * Server-reported total row count. Required when `remote === true`;
+     * ignored in local mode (where the bridge derives total from the
+     * sorted result of `deriveVisibleRows`).
+     */
+    total?: number;
+    /** Fires after the store-level sort write so the consumer can refetch. */
+    onSortChange?: (next: TableSortState) => void;
+    /** Fires after the store-level page write so the consumer can refetch. */
+    onPageChange?: (page: number) => void;
+    /** Fires after the store-level pageSize write so the consumer can refetch. */
+    onPageSizeChange?: (pageSize: number) => void;
+}
+/**
+ * Bridge component — reads the widget store's `data`, applies sort + pagination
+ * locally, and feeds `<TableUI />`. Sort, page, and pageSize live on the
+ * extended widget state ({@link TableWidgetState}).
+ */
+export declare function Table<T extends TableRow = TableRow>({ columns, visibleColumns, initialPageSize, selection, onSelectionChange, onRowClick, onRowHover, remote, total: remoteTotal, onSortChange, onPageChange, onPageSizeChange, ...uiProps }: TableProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,48 @@
+import { ReactNode } from 'react';
+import { WidgetState } from '../stores';
+/**
+ * Single row of tabular data.
+ *
+ * The default row-identity column is `id`. Consumers that don't have a
+ * literal `id` field can point `<Table>` / `<TableUI>` at a different
+ * column via the `keyColumn` prop; the library reads `row[keyColumn]`
+ * for selection lookup, React keys, and aria labels.
+ */
+export interface TableRow extends Record<string, unknown> {
+    /**
+     * Default row identity. Required when no `keyColumn` is configured.
+     * Omit when wiring `keyColumn` to a different column.
+     */
+    id?: string | number;
+}
+export type TableWidgetData = readonly TableRow[];
+export type TableSortDirection = 'asc' | 'desc';
+export interface TableSortState {
+    columnId: string | null;
+    direction: TableSortDirection;
+}
+export interface TableColumn {
+    /** Unique column identifier; matches the field name on each row. */
+    id: string;
+    /** Header label. */
+    label: ReactNode;
+    align?: 'left' | 'center' | 'right';
+    width?: number | string;
+    sortable?: boolean;
+    /** Custom cell renderer. Falls back to a string-cast of the raw value. */
+    formatter?: (value: unknown, row: TableRow) => ReactNode;
+}
+/**
+ * State extension carrying Table-specific UI state on the per-widget store.
+ * Per R12: widget-specific UI state lives in widget-specific extensions of
+ * `WidgetState`, not on the base type.
+ */
+export interface TableWidgetState extends WidgetState {
+    /** Optional reordered column list driven by ChangeColumn. Falls back to props. */
+    columnOrder?: readonly string[];
+    sort?: TableSortState;
+    page: number;
+    pageSize: number;
+}
+export declare const DEFAULT_TABLE_PAGE_SIZE = 10;
+export declare const DEFAULT_TABLE_PAGE_SIZE_OPTIONS: readonly [10, 25, 50, 100];

package/dist/types/widgets-v2/test-utils.d.ts

@@ -0,0 +1,52 @@
+import { vi } from 'vitest';
+import { ECharts, EChartsOption } from 'echarts';
+import { WidgetState, WidgetStoreApi } from './stores';
+export interface MockChartHandlers {
+    finished?: () => void;
+    rendered?: () => void;
+    click?: (params: unknown) => void;
+    globalcursortaken?: (params: unknown) => void;
+    datazoom?: (params: unknown) => void;
+    brushselected?: (params: unknown) => void;
+    brushend?: (params: unknown) => void;
+    [key: string]: ((params?: unknown) => void) | undefined;
+}
+export interface MockChart {
+    dispatchAction: ReturnType<typeof vi.fn>;
+    setOption: ReturnType<typeof vi.fn>;
+    getOption: ReturnType<typeof vi.fn>;
+    resize: ReturnType<typeof vi.fn>;
+    clear: ReturnType<typeof vi.fn>;
+    dispose: ReturnType<typeof vi.fn>;
+    isDisposed: ReturnType<typeof vi.fn>;
+    getWidth: ReturnType<typeof vi.fn>;
+    getHeight: ReturnType<typeof vi.fn>;
+    getDom: ReturnType<typeof vi.fn>;
+    on: (event: string, callback: (params?: unknown) => void) => void;
+    off: (event: string, callback?: (params?: unknown) => void) => void;
+    __handlers: MockChartHandlers;
+    __emit: (event: keyof MockChartHandlers, params?: unknown) => void;
+}
+/**
+ * Returns a duck-typed `ECharts` instance suitable for tests. The instance
+ * captures `on()` handlers in `__handlers` so tests can `__emit('finished')`
+ * directly, and all imperative methods (`dispatchAction`, `setOption`,
+ * `resize`, …) are `vi.fn()` spies.
+ */
+export declare function createMockChart(): MockChart;
+/** Convenience cast for tests that need an `ECharts`-typed reference. */
+export declare const asEcharts: (chart: MockChart) => ECharts;
+/**
+ * Returns a `vi.fn()` option factory. The factory takes the standard
+ * `(option, data, ctx)` signature and returns the supplied `output` unchanged.
+ * Useful when the test only cares about how the bridge wires the factory in.
+ */
+export declare function createMockOptionFactory(output?: EChartsOption): import('vitest').Mock<() => EChartsOption>;
+/**
+ * Typed re-export of `getWidgetStore(id).getState()` — the verbose form
+ * shows up dozens of times across the suite. Tests that need the store
+ * api itself (`setState`, `subscribe`) still call `getWidgetStore(id)`.
+ */
+export declare function getState(id: string): WidgetState;
+/** Typed re-export of `getWidgetStore(id)` for tests that need the api. */
+export declare function getStore(id: string): WidgetStoreApi;

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

@@ -0,0 +1,17 @@
+import { DownloadItem } from '../actions/download';
+import { TimeseriesWidgetData } from './types';
+/**
+ * Download menu items for the Timeseries widget. Always includes a CSV
+ * item with `time, series_1, series_2, …` columns (one row per unique time
+ * across all series; ISO-8601 strings for `Date`/numeric times). When
+ * `getCaptureEl` is supplied, prepends a PNG item that rasterises the
+ * captured element via `html2canvas`.
+ */
+export declare function createTimeseriesDownloadConfig(args: {
+    filename: string;
+    getData: () => TimeseriesWidgetData;
+    seriesNames?: readonly string[];
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

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

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

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

@@ -0,0 +1,4 @@
+export { timeseriesOptions, createTimeseriesOptionFactory } from './options';
+export { TimeseriesSkeleton } from './skeleton';
+export { createTimeseriesDownloadConfig } from './download';
+export type { TimeseriesDatum, TimeseriesWidgetData, TimeseriesOptionsInput, TimeseriesOptionFactoryInput, TimeseriesEChartsOption, } from './types';

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

@@ -0,0 +1,39 @@
+import { OptionFactory } from '../echart';
+import { TimeseriesEChartsOption, TimeseriesOptionFactoryInput, TimeseriesOptionsInput } from './types';
+/**
+ * Builds the **structural** ECharts option for a timeseries widget —
+ * time x-axis, value y-axis, themed tooltip, themed legend, CARTO color
+ * palette. Mirrors {@link import('../bar/options').barOptions} so all
+ * four ECharts widgets share v1 look-and-feel.
+ *
+ * Intentional deviations from bar (timeseries-specific):
+ *   - **X-axis is `type: 'time'`** (not 'category'). ECharts handles
+ *     uneven sample spacing and zoom-level-aware label formatting.
+ *     `labelFormatter` is wrapped so the consumer sees a `Date`, not
+ *     a numeric timestamp.
+ *   - **Tooltip body reads `{ name, value }` rows**, same as bar, but
+ *     the `name` may arrive as `Date | number | string`. The
+ *     `labelFormatter` receives a `Date` regardless.
+ *
+ * Intentionally data-agnostic: no series, no dataset, no `legend.show`
+ * (those depend on data and are added by the option factory's merge
+ * phase via {@link createTimeseriesOptionFactory}).
+ */
+export declare function timeseriesOptions({ theme, formatter, labelFormatter, }: TimeseriesOptionsInput): TimeseriesEChartsOption;
+/**
+ * Returns the timeseries 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 timeseriesOptions}, 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`
+ *     (`TimeseriesWidgetData`) into the option via the dataset API: one
+ *     dataset per series, each series referencing its dataset by index,
+ *     encoded by `name` (x — time) and `value` (y). Mirrors {@link import('../bar/options').createBarOptionFactory}:
+ *     series-template merge for `addStack`, reactive formatters from
+ *     `ctx`, `niceNum`-rounded y-axis bounds at fusion time, and
+ *     `positionDataZoomForLegend` layout for ZoomToggle sliders.
+ */
+export declare function createTimeseriesOptionFactory(options: TimeseriesOptionFactoryInput): OptionFactory;

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

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

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

@@ -0,0 +1,8 @@
+/**
+ * Loading state for the Timeseries widget. Mirrors a line chart's
+ * silhouette — three thin horizontal segments at staggered offsets to
+ * suggest a moving line, plus a 2-dot legend stub. Sibling-consistent
+ * with Bar / Histogram / Scatter skeletons (column-flex container with
+ * legend strip below).
+ */
+export declare function TimeseriesSkeleton(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,60 @@
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types';
+/**
+ * A single point on a time series. `name` is the time coordinate — accepts a
+ * Date object, a number (ms-since-epoch), or an ISO-8601 string. ECharts'
+ * time axis parses any of these.
+ */
+export interface TimeseriesDatum {
+    name: Date | number | string;
+    value: number;
+}
+/** Timeseries widget data — one array of points per series. */
+export type TimeseriesWidgetData = readonly (readonly TimeseriesDatum[])[];
+/** Inputs to the structural-only {@link timeseriesOptions} builder. */
+export interface TimeseriesOptionsInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+    /** Optional formatter for the time-axis tick labels. Receives a JS Date. */
+    labelFormatter?: (value: Date) => string;
+}
+/**
+ * Combined inputs for the timeseries option factory creator. Carries
+ * everything the widget needs across BOTH phases — the structural-build
+ * (`theme`, `formatter`, `labelFormatter`, `optionsOverride`) AND the
+ * data merge (`series`, `smooth`, `area`, `selection`).
+ */
+export interface TimeseriesOptionFactoryInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+    /**
+     * Time-axis label formatter (also used in the tooltip name). Receives
+     * a JS Date — applied both at structural-build time (x-axis ticks) and
+     * at fusion time (tooltip name) so the date-aware labeling survives
+     * RelativeData's reactive formatter swaps.
+     */
+    labelFormatter?: (value: Date) => string;
+    /**
+     * Per-series metadata — drives the legend, `series[i].name`, and
+     * (when `color` is set) per-series line + marker colour overrides.
+     */
+    series?: readonly WidgetSeries[];
+    /** Smooth lines (default `true`). */
+    smooth?: boolean;
+    /** Filled area below each line (default `false`). */
+    area?: boolean;
+    /**
+     * Selected point keys (matched against `TimeseriesDatum.name`; `Date`
+     * names are normalized to ms-since-epoch). Points 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 TimeseriesEChartsOption = EChartsOption;

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

@@ -0,0 +1,5 @@
+export interface ToolboxLabels {
+    trigger: string;
+    close: string;
+}
+export declare const DEFAULT_TOOLBOX_LABELS: ToolboxLabels;

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

@@ -0,0 +1,30 @@
+export declare const styles: {
+    root: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        width: string;
+        borderRadius: number;
+        gridColumn: number;
+        height: string;
+    };
+    preview: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+    };
+    triggerActive: {
+        bgcolor: "primary.relatedLight";
+    };
+    paper: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        px: number;
+        py: number;
+        mx: number;
+        mt: string;
+        bgcolor: "background.paper";
+        borderRadius: number;
+    };
+};

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

@@ -0,0 +1,49 @@
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps, SxProps, Theme } from '@mui/material';
+import { ToolboxLabels } from './labels';
+export interface ToolboxProps {
+    /**
+     * Maximum number of (non-`data-toolbar-hidden`) children rendered inline
+     * when collapsed. Excess children are revealed via the overflow trigger
+     * inside a floating Paper. When omitted, all children render inline.
+     */
+    visibleCount?: number;
+    labels?: Partial<ToolboxLabels>;
+    /**
+     * Glyph used for the closed-state trigger. Defaults to the meridian-ds
+     * `WidgetOptions` icon (matches v1's `ToolbarActions`).
+     */
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Side the overflow Paper opens toward. `'right'` (default) places the
+     * trigger on the left and the Paper covers the row to the right;
+     * `'left'` is the mirror.
+     */
+    direction?: 'left' | 'right';
+    sx?: SxProps<Theme>;
+    children: ReactNode;
+}
+/**
+ * Smart overflow toolbar with **single-mount** items. Children mount once
+ * into a stable, hidden host element and are *physically reparented* via
+ * `appendChild` between the inline preview area and the overflow `<Paper>`
+ * as the popper opens / closes — same pattern as `Widget.FullScreen.Slot`.
+ * Items with no inline space when closed are kept mounted but visually
+ * hidden via `display: none`.
+ *
+ * Why this matters: every toggle's `useTransform` registers a config /
+ * data transform on mount and removes it on unmount. If items remounted
+ * on each open / close, the brief setup → cleanup window would re-emit
+ * the pipeline (transform missing → transform present), causing a visible
+ * flicker on state-bearing transforms (Stack, Zoom, RelativeData). With
+ * stable mounts the transform stays registered across the whole popover
+ * lifecycle.
+ *
+ * Children flagged with `data-toolbar-hidden` (e.g. dividers) skip the
+ * visibility budget but still render in their natural position. Trailing
+ * hidden items past the budget are excluded from the inline preview so
+ * they don't appear as orphan separators in the inline row; they're still
+ * there in the popover.
+ */
+export declare function Toolbox({ visibleCount, labels, icon: Icon, iconProps, direction, sx, children, }: ToolboxProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,25 @@
+/**
+ * Canonical cross-widget series metadata.
+ *
+ * Every widget that can carry multiple series (Bar, Pie, Histogram,
+ * Scatterplot, Timeseries, Category, Formula, Spread) accepts a
+ * `series: readonly WidgetSeries[]` prop. The `name` drives legends,
+ * tooltips, and category-row avatars; the optional `color` overrides
+ * the default palette assignment.
+ *
+ * For backward compatibility, the widget-specific names
+ * (`FormulaSeries`, `CategorySeriesConfig`) are kept as type aliases of
+ * `WidgetSeries` — see `formula/types.ts` and `category/types.ts`.
+ *
+ * Colours accept MUI theme paths (e.g. `'primary.main'`) as well as raw
+ * CSS strings (`'#ff0000'`, `'rgb(…)'`). The echart-based widgets
+ * resolve them through `resolveThemeColor` (see
+ * `widgets-v2/utils/resolve-theme-color.ts`); Category and Formula/Spread
+ * resolve them implicitly via MUI's `sx` prop.
+ */
+export interface WidgetSeries {
+    /** Display name — drives legend, tooltip, and avatar glyphs. */
+    name: string;
+    /** Optional colour override. MUI theme path or raw CSS string. */
+    color?: string;
+}

package/dist/types/widgets-v2/utils/data-zoom-layout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * If the option includes a `dataZoom` array (from ZoomToggle's transform),
+ * lift any slider entries above the legend row so they don't overlap.
+ * Returns `null` when there is no `dataZoom` — caller skips the layout
+ * adjustment entirely.
+ *
+ * Shared between bar, histogram, and timeseries — every widget with a
+ * horizontal x-axis dataZoom slider needs the same offset when a legend
+ * is rendered below the plot.
+ */
+export declare function positionDataZoomForLegend(dataZoom: unknown, hasLegend: boolean): unknown[] | null;

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

@@ -0,0 +1,3 @@
+export { mergeOptions } from './merge-options';
+export { positionDataZoomForLegend } from './data-zoom-layout';
+export { resolveThemeColor } from './resolve-theme-color';

package/dist/types/widgets-v2/utils/merge-options.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shallow-merges two ECharts option objects:
+ *   - Top-level keys from both are combined.
+ *   - Arrays are merged by index (element-wise shallow merge, primitive override).
+ *   - Plain objects are shallow-merged.
+ *   - Primitives are overridden by the override value.
+ *
+ * Designed for the two-stage memoization pattern: first build a base option
+ * object from data + theme + formatters, then call `mergeOptions(base, override)`
+ * inside a second `useMemo` keyed on `[base, override]`.
+ */
+export declare function mergeOptions<T extends Record<string, unknown>>(base: T, override?: Partial<T>): T;