@carto/ps-react-ui 4.7.0 → 4.8.0

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,50 @@
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+/** 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 (`seriesNames`, `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;
+    /** Series names — drives the legend and `series[i].name`. */
+    seriesNames?: readonly string[];
+    /** 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;

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

@@ -0,0 +1,5 @@
+/**
+ * Stateful Spread bridge — reads `data` (post-pipeline) and `formatter` from
+ * the per-widget store and forwards them to the pure {@link SpreadUI}.
+ */
+export declare function Spread(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,25 @@
+import { FormulaSeries } from '../formula';
+/**
+ * A single min/max pair rendered by the Spread widget. Mirrors
+ * {@link FormulaDataItem} — same optional `series`, `prefix`, `suffix`,
+ * `color`, and `note` slots — but the value is a range (`min` … `max`)
+ * rather than a single `value`.
+ */
+export interface SpreadDataItem {
+    min: number;
+    max: number;
+    prefix?: string;
+    suffix?: string;
+    /** Override the values' text colour (e.g. `'success.main'`). */
+    color?: string;
+    /** Optional series indicator — coloured avatar with first letter of `name`. */
+    series?: FormulaSeries;
+    /** Optional caption rendered below the values. */
+    note?: string;
+}
+/**
+ * Spread widget data — an array of `{min, max, …}` pairs rendered
+ * top-to-bottom, one row per entry. Visual structure matches the Formula
+ * widget so the two can sit side-by-side without style drift.
+ */
+export type SpreadWidgetData = readonly SpreadDataItem[];

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

@@ -0,0 +1,7 @@
+export interface StateLabels {
+    errorTitle: string;
+    errorMessage: (error: unknown) => string;
+    emptyTitle: string;
+    emptyDescription: string;
+}
+export declare const DEFAULT_STATE_LABELS: StateLabels;

package/dist/types/widgets-v2/state/labels.test.d.ts

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

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

@@ -0,0 +1,19 @@
+export declare const styles: {
+    emptyRoot: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        paddingTop: number;
+        paddingBottom: number;
+        paddingX: number;
+        width: string;
+        minHeight: string;
+    };
+    captureBox: {
+        width: string;
+        minHeight: number;
+        display: "flex";
+        flexDirection: "column";
+        flex: number;
+    };
+};

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

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { StateLabels } from './labels';
+export interface StateProps {
+    skeleton: ReactNode;
+    children: ReactNode;
+    /** Override the empty-state predicate. Receives `rawData` (pre-pipeline). */
+    isEmpty?: (rawData: unknown) => boolean;
+    /** Render an alternative error UI. When omitted, the default ErrorView is used. */
+    fallback?: (error: Error) => ReactNode;
+    labels?: Partial<StateLabels>;
+}
+/**
+ * Priority chain: loading → error → empty → content. Both consumer-supplied
+ * errors (set via Provider's `error` prop) and transform-throw errors (set by
+ * the pipeline middleware) flow through the same `error` field. Render-time
+ * errors thrown by `children` are caught by the inlined error boundary and
+ * routed through the same path.
+ */
+export declare function State({ skeleton, children, isEmpty, fallback, labels, }: StateProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,8 @@
+export type { TransformType, TransformDescriptor, TransformFn, Transform, TransformPair, WidgetState, WidgetInit, WidgetStoreApi, } from './types';
+export { applyTransforms, upsertTransform, removeTransform } from './transforms';
+export { pipelineMiddleware } from './pipeline-middleware';
+export { WidgetContext, useWidgetId } from './widget-context';
+export { getWidgetStore, hasWidgetStore, deleteWidgetStore, resetWidgetStore, clearAllWidgetStores, registerWidgetStore, unregisterWidgetStore, setWidgetStoreEntry, createWidgetStore, useWidget, useWidgetShallow, setCaptureEl, getCaptureEl, clearAllCaptureEls, setEchartInstance, getEchartInstance, subscribeEchartInstance, clearAllEchartInstances, __debugListWidgetStores, } from './widget-store-registry';
+export { useEchartInstance } from './use-echart-instance';
+export { useTransform, useSingleTransform, type UseTransformOptions, type TransformControls, } from './use-transform';
+export { useTransformEnabled } from './use-transform-enabled';

package/dist/types/widgets-v2/stores/pipeline-middleware.d.ts

@@ -0,0 +1,5 @@
+import { StateCreator, StoreMutatorIdentifier } from 'zustand';
+import { WidgetState } from './types';
+type PipelineMiddleware = <T extends WidgetState, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(config: StateCreator<T, Mps, Mcs>) => StateCreator<T, Mps, Mcs>;
+export declare const pipelineMiddleware: PipelineMiddleware;
+export {};

package/dist/types/widgets-v2/stores/pipeline-middleware.test.d.ts

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

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

@@ -0,0 +1,4 @@
+import { Transform } from './types';
+export declare function applyTransforms(input: unknown, transforms: readonly Transform[], onError?: (id: string, error: Error) => void): unknown;
+export declare function upsertTransform(transforms: readonly Transform[], next: Transform): readonly Transform[];
+export declare function removeTransform(transforms: readonly Transform[], id: string): readonly Transform[];

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

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

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

@@ -0,0 +1,55 @@
+import { StoreApi } from 'zustand';
+export type TransformType = 'data' | 'config';
+export interface TransformDescriptor {
+    id: string;
+    type: TransformType;
+    order: number;
+    disables?: string[];
+    replaceMergeKeys?: string[];
+}
+export type TransformFn = (input: unknown) => unknown;
+export interface Transform extends TransformDescriptor {
+    fn: TransformFn;
+    enabled: boolean;
+}
+export interface TransformPair {
+    descriptor: TransformDescriptor;
+    fn: TransformFn;
+}
+export interface WidgetState {
+    rawData: unknown;
+    data: unknown;
+    dataTransforms: readonly Transform[];
+    configTransforms: readonly Transform[];
+    transformStates: Record<string, {
+        enabled: boolean;
+        [k: string]: unknown;
+    }>;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: unknown;
+    /**
+     * Original formatter as supplied by the consumer (Provider's `formatter`
+     * prop). Always live-synced — never overridden by actions. Actions that need
+     * to display a different formatter (e.g. {@link RelativeData}'s percent
+     * formatter) should write to {@link WidgetState.formatter} and read this
+     * field when restoring the absolute view.
+     */
+    rawFormatter?: (value: number) => string;
+    /**
+     * Active formatter — what consumer code (tooltips, axis labels, legends,
+     * etc.) reads. Defaults to {@link WidgetState.rawFormatter}; actions may
+     * override it temporarily and restore it from `rawFormatter` later.
+     */
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+}
+export interface WidgetInit {
+    data: unknown;
+    isLoading?: boolean;
+    isFetching?: boolean;
+    error?: unknown;
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+}
+export type WidgetStoreApi = StoreApi<WidgetState>;

package/dist/types/widgets-v2/stores/use-echart-instance.d.ts

@@ -0,0 +1,15 @@
+import { ECharts } from 'echarts';
+/**
+ * Reactive read of the live ECharts instance for a widget. Returns
+ * `null` before the `Widget.Echart` bridge has mounted (or after it's
+ * disposed); the consumer re-renders when the instance arrives /
+ * departs / changes.
+ *
+ * Wraps {@link subscribeEchartInstance} via `useSyncExternalStore`, so
+ * actions can use it inside an effect's deps array to react to chart
+ * lifecycle events without polling. Required for actions like
+ * `BrushToggle` whose effect needs to dispatch `takeGlobalCursor` the
+ * moment the chart exists, then re-dispatch on every `'finished'`
+ * event.
+ */
+export declare function useEchartInstance(id: string): ECharts | null;

package/dist/types/widgets-v2/stores/use-transform-enabled.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reactive read of a single transform's `enabled` flag from the
+ * per-widget store. Returns `false` if the transform hasn't been
+ * registered yet (i.e., the action component hasn't mounted) — safe
+ * default for "the feature is off".
+ *
+ * Used by widget composers that want to react to an action's on/off
+ * cycle without having the widget primitive import the action. For
+ * example, the `CategoryWidget` storybook composer wires the
+ * SearcherToggle's open state into `<Widget.Category searcherOpen=…>`
+ * so the library primitive stays renderer-agnostic.
+ *
+ * Magic-string `transformId` is intentional — it lives at the composer
+ * layer where the action is already imported by JSX, so the string
+ * appears alongside the same name in the toolbox.
+ */
+export declare function useTransformEnabled(id: string, transformId: string): boolean;

package/dist/types/widgets-v2/stores/use-transform.d.ts

@@ -0,0 +1,12 @@
+import { Dispatch, SetStateAction } from 'react';
+import { TransformDescriptor, TransformFn, TransformPair } from './types';
+export interface UseTransformOptions {
+    initialEnabled?: boolean;
+}
+export interface TransformControls {
+    enabled: boolean;
+    setEnabled: Dispatch<SetStateAction<boolean>>;
+    toggle: () => void;
+}
+export declare function useTransform(id: string, pairs: readonly TransformPair[], options?: UseTransformOptions): TransformControls;
+export declare function useSingleTransform(id: string, descriptor: TransformDescriptor, fn: TransformFn, options?: UseTransformOptions): TransformControls;

package/dist/types/widgets-v2/stores/widget-context.d.ts

@@ -0,0 +1,2 @@
+export declare const WidgetContext: import('react').Context<string | null>;
+export declare function useWidgetId(): string;

package/dist/types/widgets-v2/stores/widget-store-registry.d.ts

@@ -0,0 +1,74 @@
+import { ECharts } from 'echarts';
+import { WidgetInit, WidgetState, WidgetStoreApi } from './types';
+type EchartInstanceListener = (chart: ECharts | null) => void;
+export declare function getWidgetStore(id: string): WidgetStoreApi;
+export declare function hasWidgetStore(id: string): boolean;
+export declare function deleteWidgetStore(id: string): void;
+export declare function resetWidgetStore(id: string): void;
+export declare function clearAllWidgetStores(): void;
+/**
+ * Register or clear the capture element for a widget. Pass `null` to clear.
+ * Called by `Widget.State` via a callback ref on its success-path content
+ * wrapper. The element is read by per-widget download configs at click time
+ * to feed `html2canvas` for PNG export.
+ */
+export declare function setCaptureEl(id: string, el: HTMLElement | null): void;
+/**
+ * Read the currently registered capture element for a widget. Returns `null`
+ * when no `Widget.State` is on its success path (loading / error / empty)
+ * or when the widget hasn't mounted.
+ */
+export declare function getCaptureEl(id: string): HTMLElement | null;
+/** @internal — exposed for tests and debugging only. */
+export declare function clearAllCaptureEls(): void;
+/**
+ * Register or clear the live ECharts instance for a widget. Pass `null`
+ * to clear. Called by the `Widget.Echart` bridge on mount / dispose.
+ * Read by actions (e.g. `ZoomToggle`'s disable handler) that need to
+ * dispatch on the live chart without going through the pipeline.
+ *
+ * Notifies subscribers registered via {@link subscribeEchartInstance}
+ * after the map mutation, so reactive consumers (the
+ * `useEchartInstance` hook) re-render with the new value.
+ */
+export declare function setEchartInstance(id: string, chart: ECharts | null): void;
+/**
+ * Read the currently registered ECharts instance for a widget. Returns
+ * `null` when no `Widget.Echart` is mounted, or before the bridge has
+ * created the instance.
+ */
+export declare function getEchartInstance(id: string): ECharts | null;
+/**
+ * Subscribe to changes of the registered ECharts instance for a widget.
+ * The listener is called *after* every {@link setEchartInstance} (with
+ * the new chart, or `null` when cleared). Returns an unsubscribe
+ * function. Used by the `useEchartInstance` hook to drive React effects
+ * that need to react to instance arrival / departure (e.g.
+ * `BrushToggle`'s `'finished'` re-dispatch loop).
+ */
+export declare function subscribeEchartInstance(id: string, listener: EchartInstanceListener): () => void;
+/** @internal — exposed for tests and debugging only. */
+export declare function clearAllEchartInstances(): void;
+/** @internal — exposed for tests and debugging only. */
+export declare function __debugListWidgetStores(): string[];
+/**
+ * Insert or replace a store entry in the registry without refcounting or
+ * duplicate-id detection. Used by Provider's lazy `useState` init so the
+ * store is reachable from `useWidget(id)` calls in children that render
+ * before the Provider's mount effect runs. Refcounting and dev warns happen
+ * in {@link registerWidgetStore} during the mount effect.
+ *
+ * @internal
+ */
+export declare function setWidgetStoreEntry(id: string, store: WidgetStoreApi): void;
+/** @internal — used by Provider; not part of the public API. */
+export declare function createWidgetStore(id: string, init: WidgetInit): WidgetStoreApi;
+/** @internal — registers a Provider mount and tracks/warns on duplicate ids in dev. */
+export declare function registerWidgetStore(id: string, store: WidgetStoreApi): void;
+/** @internal — Provider unmount counterpart; on last unmount removes the refcount entry. */
+export declare function unregisterWidgetStore(id: string, options: {
+    keepAlive: boolean;
+}): void;
+export declare function useWidget<T, S extends WidgetState = WidgetState>(id: string, selector: (state: S) => T): T;
+export declare function useWidgetShallow<T, S extends WidgetState = WidgetState>(id: string, selector: (state: S) => T): T;
+export {};

package/dist/types/widgets-v2/stores/widget-store-registry.test.d.ts

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

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

@@ -0,0 +1,10 @@
+export declare const styles: {
+    root: {
+        display: "grid";
+        gridTemplateColumns: string;
+        alignItems: "center";
+        gap: number;
+        minHeight: number;
+        pb: number;
+    };
+};

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 {};