@carto/ps-react-ui 5.0.0-widgets.9 → 5.1.0

package/dist/types/widgets-v2/category/components/category-row-other.d.ts

@@ -0,0 +1,26 @@
+export interface CategoryRowOtherProps {
+    hiddenCount: number;
+    /** Label for the overflow row. Defaults to `'Others'`. */
+    otherLabel?: string;
+    /** Count text with `{count}` placeholder. Defaults to `'{count}'`. */
+    otherCountLabel?: string;
+    /**
+     * When provided, the row becomes a button: clicking it (or Enter/Space)
+     * fires `onShowAll`, expanding the widget to reveal every category. When
+     * omitted the row renders as a static, non-interactive summary.
+     */
+    onShowAll?: () => void;
+    /** Tooltip shown over the button form. Defaults to `'Show all'`. */
+    showAllLabel?: string;
+}
+/**
+ * Overflow summary row rendered after the last visible category row when
+ * `data.length > maxItems`. Shows `Others <count>` (count muted, no
+ * parentheses).
+ *
+ * When `onShowAll` is supplied the row is an interactive button — clicking
+ * it (or Enter/Space) expands the widget to show all categories, mirroring
+ * the Searcher's full-list view. Without `onShowAll` it stays a static,
+ * non-interactive summary (backward-compatible default).
+ */
+export declare function CategoryRowOther({ hiddenCount, otherLabel, otherCountLabel, onShowAll, showAllLabel, }: CategoryRowOtherProps): import('react').JSX.Element;

package/dist/types/widgets-v2/category/components/category-row-single.d.ts

@@ -0,0 +1,28 @@
+import { CategoryKey, CategorySize } from '../types.js';
+export interface CategoryRowSingleProps {
+    /** Raw category key — what gets emitted to `onToggle` regardless of formatter. */
+    name: CategoryKey;
+    /** Display label (post-`labelFormatter`). Falls back to `name` when omitted. */
+    displayName?: string | number;
+    value: number;
+    maxValue: number;
+    color: string;
+    formatter: (n: number) => string;
+    selected: boolean;
+    onToggle: (name: CategoryKey) => void;
+    /** Bar visual density. Forwarded to {@link CategoryBar}. */
+    size?: CategorySize;
+}
+/**
+ * Single-series category row: `[label] [bar] [value]` grid. Click /
+ * Enter / Space toggles `name` in/out of the selection set via
+ * `onToggle`. Selection key is always the raw `name` — `displayName` is
+ * presentation only.
+ *
+ * Visual selection / dim signal lives ENTIRELY in the bar color
+ * (`color` prop) — computed upstream by `CategoryUI` (real palette
+ * color when selected or no-selection; `theme.palette.action.disabled`
+ * when a selection exists and this row isn't in it). The row itself
+ * has no bg tint, no opacity rule.
+ */
+export declare function CategoryRowSingle({ name, displayName, value, maxValue, color, formatter, selected, onToggle, size, }: CategoryRowSingleProps): import('react').JSX.Element;

package/dist/types/widgets-v2/category/components/category-row-stacked.d.ts

@@ -0,0 +1,43 @@
+import { CategoryKey, CategorySize } from '../types.js';
+export interface CategoryRowStackedProps {
+    /** Raw category key — what gets emitted to `onToggle`. */
+    name: CategoryKey;
+    /** Display label (post-`labelFormatter`). Falls back to `name`. */
+    displayName?: string | number;
+    /** One value per series. Zero values still appear in the breakdown row. */
+    values: readonly number[];
+    /** One color per series (palette + per-series overrides resolved upstream). */
+    colors: readonly string[];
+    /**
+     * Series names for the breakdown row, one per visible series, already
+     * resolved by the caller (unnamed series fall back to `Series N` using
+     * their ORIGINAL series index — this component has no notion of which
+     * series were hidden, so it must not recompute a positional fallback).
+     */
+    seriesNames: readonly string[];
+    formatter: (n: number) => string;
+    selected: boolean;
+    onToggle: (name: CategoryKey) => void;
+    /** Bar visual density. Forwarded to the inner {@link CategoryBarStacked}. */
+    size?: CategorySize;
+}
+/**
+ * Stacked-mode category row: label + total share a header line; a single
+ * segmented bar sits below; an inline breakdown lists each series with its
+ * formatted value. Click anywhere in the row toggles selection by `name`.
+ *
+ * Per-row normalization: the stacked bar always fills 100% of the track,
+ * with each segment sized as `value_i / sum(values)`. This is intentionally
+ * different from `CategoryRowMulti` (which scales bars against the global
+ * `maxValue` for cross-row comparison) — in stacked mode the comparable
+ * axis is the proportion of each series within the row, not the row's
+ * total relative to other rows. The total numeric value is still shown in
+ * the header so the per-row magnitude isn't lost.
+ *
+ * Visual selection / dim signal lives entirely in the segment colors
+ * (`colors` prop) — every series in a dimmed row receives
+ * `theme.palette.action.disabled`. The bar visually collapses to a single
+ * grey shape when dimmed, but the breakdown text stays at full color so the
+ * per-series values remain legible.
+ */
+export declare function CategoryRowStacked({ name, displayName, values, colors, seriesNames, formatter, selected, onToggle, size, }: CategoryRowStackedProps): import('react').JSX.Element;

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

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

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

@@ -0,0 +1,10 @@
+export { Category, type CategoryProps } from './category.js';
+export { CategoryUI, type CategoryUIProps } from './category-ui.js';
+export { CategorySkeleton, type CategorySkeletonProps } from './skeleton.js';
+export { createCategoryDownloadConfig } from './download.js';
+export { CategoryBar, type CategoryBarProps } from './components/category-bar.js';
+export { CategoryRowSingle, type CategoryRowSingleProps, } from './components/category-row-single.js';
+export { CategoryRowMulti, type CategoryRowMultiProps, } from './components/category-row-multi.js';
+export { CategoryRowOther, type CategoryRowOtherProps, } from './components/category-row-other.js';
+export { CategoryLegend, type CategoryLegendProps, } from './components/category-legend.js';
+export type { CategoryDataItem, CategoryWidgetData, CategoryKey, CategorySeriesConfig, CategoryLabels, CategorySize, } from './types.js';

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

@@ -0,0 +1,11 @@
+import { CategorySize } from './types.js';
+export interface CategorySkeletonProps {
+    rows?: number;
+    /**
+     * Visual density. Mirrors the live widget's `size` prop so the loading
+     * shimmer's bar height matches what's about to render — no row jump
+     * on data settle.
+     */
+    size?: CategorySize;
+}
+export declare function CategorySkeleton({ rows, size, }: CategorySkeletonProps): import('react').JSX.Element;

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

@@ -0,0 +1,193 @@
+import { SxProps, Theme } from '@mui/material';
+import { CategorySize } from './types.js';
+export declare const styles: {
+    root: {
+        display: string;
+        flexDirection: string;
+        position: string;
+        width: string;
+    };
+    list: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        py: number;
+    };
+    listScroll: {
+        pr: number;
+    };
+    rowSingle: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        cursor: string;
+        userSelect: string;
+        transition: string;
+        '&:hover [data-bar-fill="true"]': {
+            filter: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
+        };
+    };
+    rowHeader: {
+        display: string;
+        justifyContent: string;
+        alignItems: string;
+        gap: number;
+    };
+    rowMulti: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        cursor: string;
+        userSelect: string;
+        transition: string;
+        '&:hover [data-bar-fill="true"]': {
+            filter: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
+        };
+    };
+    name: {
+        overflow: string;
+        whiteSpace: string;
+        textOverflow: string;
+        color: string;
+        fontWeight: string;
+    };
+    multiName: {
+        overflow: string;
+        whiteSpace: string;
+        textOverflow: string;
+        color: string;
+        fontWeight: string;
+    };
+    value: {
+        color: string;
+        fontVariantNumeric: string;
+        minWidth: number;
+        textAlign: string;
+    };
+    bar: Record<CategorySize, SxProps<Theme>>;
+    barFill: Record<CategorySize, SxProps<Theme>>;
+    stackedSegment: Record<CategorySize, SxProps<Theme>>;
+    multiBarRow: {
+        display: string;
+        alignItems: string;
+        gap: number;
+    };
+    multiBarContainer: {
+        flex: number;
+    };
+    rowStacked: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        cursor: string;
+        userSelect: string;
+        transition: string;
+        '&:hover [data-bar-fill="true"]': {
+            filter: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
+        };
+    };
+    stackedHeader: {
+        display: string;
+        justifyContent: string;
+        alignItems: string;
+        gap: number;
+    };
+    stackedTotal: {
+        color: string;
+        fontWeight: string;
+        fontVariantNumeric: string;
+        minWidth: number;
+        textAlign: string;
+    };
+    stackedBreakdown: {
+        display: string;
+        flexWrap: string;
+        columnGap: number;
+        rowGap: number;
+    };
+    stackedBreakdownItem: {
+        color: string;
+        fontVariantNumeric: string;
+    };
+    legend: {
+        display: string;
+        alignItems: string;
+        gap: number;
+        flexWrap: string;
+        pt: number;
+        mt: number;
+        position: string;
+        bottom: number;
+        bgcolor: string;
+        borderTop: (theme: Theme) => string;
+    };
+    legendItem: {
+        display: string;
+        alignItems: string;
+        gap: number;
+        cursor: string;
+    };
+    legendItemHidden: {
+        display: string;
+        alignItems: string;
+        gap: number;
+        cursor: string;
+        opacity: number;
+    };
+    legendDot: {
+        width: number;
+        height: number;
+        borderRadius: string;
+    };
+    legendLabel: {
+        color: string;
+        textTransform: string;
+        fontWeight: string;
+    };
+    otherRow: {
+        display: string;
+        alignItems: string;
+        gap: number;
+        py: number;
+        px: number;
+    };
+    otherLabelButton: {
+        cursor: string;
+        userSelect: string;
+        borderRadius: number;
+        px: number;
+        ml: number;
+        transition: string;
+        '&:hover': {
+            bgcolor: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
+        };
+    };
+    otherLabel: {
+        color: string;
+        fontWeight: string;
+    };
+    otherCount: {
+        color: string;
+        fontVariantNumeric: string;
+    };
+};

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

@@ -0,0 +1,55 @@
+import { WidgetSeries } from '../types.js';
+/** A single row in a Category widget. `name` is the category key. */
+export interface CategoryDataItem {
+    name: string | number;
+    value: number;
+    /** Optional per-row color override (wins over series + palette). */
+    color?: string;
+}
+/**
+ * Category widget data — array of series, each a flat list of `{name, value}`.
+ *
+ * Single-series (`data.length === 1`) renders one bar per row.
+ * Multi-series (`data.length > 1`) groups items by `name` across series and
+ * renders N vertically-stacked bars per row, with a sticky legend at the
+ * bottom when `series` metadata is supplied.
+ */
+export type CategoryWidgetData = readonly (readonly CategoryDataItem[])[];
+/**
+ * The keyspace of selectable items. Per the destination-owned selection
+ * principle, the consumer keeps this in their own store.
+ */
+export type CategoryKey = string | number;
+/**
+ * Per-series metadata. Supplied to enable the legend and override the
+ * auto-assigned palette color for a given series index. Length should
+ * mirror `data.length` for a full legend; shorter/longer arrays degrade
+ * gracefully (extra entries ignored; missing entries get palette
+ * defaults and are absent from the legend).
+ */
+/**
+ * Per-series metadata. Type alias of the cross-widget
+ * {@link WidgetSeries} shape (`{ name, color? }`) so Category, Formula,
+ * Spread, and the echart-based widgets all consume the same input
+ * shape. Kept as a named export for backwards compatibility.
+ */
+export type CategorySeriesConfig = WidgetSeries;
+/**
+ * Labels for the "Other" overflow row (rendered when `data.length`
+ * exceeds `maxItems`). `{count}` in `otherCount` is replaced with the
+ * number of hidden categories.
+ */
+export interface CategoryLabels {
+    other?: string;
+    otherCount?: string;
+    /** Tooltip shown over the clickable "Others" row. Defaults to `'Show all'`. */
+    showAll?: string;
+}
+/**
+ * Visual density of the bar primitive. `'small'` (default) keeps the
+ * original 4px-tall, fully-rounded track. `'medium'` renders a 12px-tall
+ * track with a 2px corner radius (squarer affordance for denser layouts).
+ * Only the bar track + fill are affected — row layout, label typography,
+ * value column, legend, and hover affordance are unchanged.
+ */
+export type CategorySize = 'small' | 'medium';

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

@@ -0,0 +1,44 @@
+import { SxProps, Theme } from '@mui/material';
+import * as echarts from 'echarts';
+export declare const DEFAULT_INIT_OPTS: {
+    renderer: "svg";
+};
+export type EchartsEventHandler = (event: unknown) => void;
+export interface EchartUIProps {
+    option: echarts.EChartsOption;
+    /**
+     * Keys to merge as arrays (replace by index) instead of by id. The middleware
+     * memoizes this content-stably, so identical sets don't re-trigger setOption.
+     */
+    replaceMerge?: readonly string[];
+    /**
+     * Opaque ECharts event passthrough — handlers fire untransformed.
+     *
+     * **Must be referentially stable** (memoize it with `useMemo` /
+     * `useCallback`, or hoist to module scope). The binding effect depends on
+     * the `onEvents` object identity; an inline `{ click: handler }` literal
+     * recreates the object on every render and causes every listener to be
+     * detached and re-attached each commit.
+     */
+    onEvents?: Record<string, EchartsEventHandler>;
+    /**
+     * Init options forwarded to echarts.init. Captured at mount only — to change
+     * `renderer` or `height` after mount, unmount and remount the chart.
+     * Defaults: `{ renderer: 'svg' }` — height is container-driven, so prefer
+     * `sx={{ minHeight }}` over pinning `height` here.
+     */
+    init?: echarts.EChartsInitOpts;
+    /**
+     * Optional callback fired once after the ECharts instance is created
+     * (`onInstance(chart)`) and once when it's about to be disposed
+     * (`onInstance(null)`). Used by `Widget.Echart` to publish the live
+     * instance to the per-widget registry so other actions (e.g.
+     * `ZoomToggle`'s disable handler) can reach it without DOM lookups.
+     * No need to memoize — the bridge wraps it in `useEffectEvent` so an
+     * unstable reference does not re-init the chart.
+     */
+    onInstance?: (chart: echarts.ECharts | null) => void;
+    className?: string;
+    sx?: SxProps<Theme>;
+}
+export declare function EchartUI({ option, replaceMerge, onEvents, init, onInstance, className, sx, }: EchartUIProps): import('react').JSX.Element;

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

@@ -0,0 +1,83 @@
+import { SxProps, Theme } from '@mui/material';
+import { EchartsEventHandler } from './echart-ui.js';
+import type * as echarts from 'echarts';
+/**
+ * Reactive context passed to every {@link OptionFactory} call so the
+ * factory can rebuild render-time pieces (axis label / tooltip formatters)
+ * from the live store. Drives RelativeData / consumer-formatter changes
+ * through to the chart without rebuilding the structural option.
+ */
+export interface OptionFactoryContext {
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+}
+/**
+ * The per-widget option factory — a single callable that owns BOTH phases
+ * of option construction:
+ *
+ * - **Structural phase** — when `option == null`, return the theme-aware
+ *   structural option (tooltip / legend / color palette / series
+ *   template, optionally merged with a consumer-supplied `optionsOverride`).
+ *   No data is read. `<Widget.Echart>` calls the factory with
+ *   `(undefined, undefined)` synchronously during render to derive the
+ *   structural base; `configTransforms` (Stack/Zoom/Brush) then mutate it
+ *   in the same render pass.
+ * - **Merge phase** — when `option` is defined, fuse `data` into the
+ *   post-configTransforms option at fusion time. `<Widget.Echart>` calls
+ *   the factory with `(transformed, data, ctx)` on every render.
+ *
+ * The two phases share a closure (the factory creator captures `theme`,
+ * `formatter`, `labelFormatter`, `seriesNames`, `selection`, `optionsOverride`,
+ * …), so structural and merge agree on the same widget configuration.
+ *
+ * The third arg `ctx` carries the **live** store-side formatters at the
+ * call site — distinct from the closure-time formatters because actions
+ * like RelativeData can install a percent formatter on the store after
+ * the factory was constructed. The merge phase reads from `ctx`; the
+ * structural phase typically uses the closure-time values.
+ */
+export type OptionFactory = (option: echarts.EChartsOption | undefined, data: unknown, ctx?: OptionFactoryContext) => echarts.EChartsOption;
+export interface EchartProps {
+    /**
+     * The per-widget {@link OptionFactory}. Required — `<Widget.Echart>`
+     * derives the structural option from it (so configTransforms have a base
+     * to mutate) and fuses `state.data` into the post-pipeline option at
+     * render time. Wrap the factory creator in `useMemo` so its identity is
+     * stable across renders.
+     */
+    optionFactory: OptionFactory;
+    onEvents?: Record<string, EchartsEventHandler>;
+    init?: echarts.EChartsInitOpts;
+    className?: string;
+    /**
+     * Styles for the chart container — this is where its height comes from.
+     * `min-height` defaults to the card height (304px) and `flex: 1` lets the
+     * chart fill a taller parent; override either here, e.g.
+     * `sx={{ minHeight: 400 }}` for a taller card.
+     */
+    sx?: SxProps<Theme>;
+}
+/**
+ * Stateful Echart bridge — owns the entire ECharts coupling. The whole
+ * option pipeline lives here, not in the store:
+ *
+ * 1. **Structural** — `optionFactory(undefined, undefined)` produces the
+ *    theme-aware base. Memoized on the factory identity, so the consumer's
+ *    `useMemo` ID gates the rebuild.
+ * 2. **Transformed** — `applyTransforms(structural, configTransforms)`
+ *    applies any registered configTransforms (Stack/Zoom/Brush) over the
+ *    structural base. Memoized on `[structural, configTransforms]`.
+ * 3. **`replaceMerge`** — derived from the enabled configTransforms'
+ *    `replaceMergeKeys`, deduped and sorted, seeded with
+ *    {@link DEFAULT_REPLACE_MERGE}. Memoized on `[configTransforms]` so
+ *    ECharts sees a stable array reference across non-transform changes.
+ * 4. **Merge** — `optionFactory(transformed, data, ctx)` fuses post-
+ *    pipeline data into the option. Reactive `ctx` carries the live store
+ *    formatters so RelativeData's percent formatter flows through without
+ *    a structural rebuild.
+ *
+ * The `<Widget.Provider>` doesn't know about the factory at all: it stays
+ * a renderer-agnostic shell. The `ProviderProps` surface has no ECharts
+ * coupling, so non-Echart widgets don't transitively import the type.
+ */
+export declare function Echart({ optionFactory, onEvents, init, className, sx, }: EchartProps): import('react').JSX.Element;

package/dist/types/widgets-v2/echart/edge-label-clamp.d.ts

@@ -0,0 +1,57 @@
+import { ECharts, EChartsOption } from 'echarts';
+/**
+ * Render-time clamp that stops the first/last **category x-axis** labels from
+ * clipping at the chart edges — *only when they actually overflow*.
+ *
+ * ECharts centers each category label on its tick; the first/last ticks sit at
+ * the plot boundary, so a wide edge label spills past the chart and is cut off.
+ * `grid.containLabel` does not contain this horizontal overflow and the v6
+ * `outerBounds` shrink is unreliable, so we measure at render time and anchor
+ * the overflowing edge label inward (`alignMinLabel: 'left'` /
+ * `alignMaxLabel: 'right'`). Labels that fit stay centered.
+ *
+ * Lives in the generic bridge because the verdict needs the laid-out chart
+ * (`convertToPixel`, `getWidth`); everything else is read from the `option`.
+ * Auto-targets bar + histogram (category x-axis); pie's horizontal-bar fallback
+ * (category *y*-axis), scatterplot (value) and timeseries (time) are skipped.
+ */
+export interface EdgeAlignment {
+    alignMinLabel: 'left' | null;
+    alignMaxLabel: 'right' | null;
+}
+export declare const CENTERED: EdgeAlignment;
+/**
+ * Pure overflow decision. Inputs are anchor-independent (tick centers and text
+ * width don't depend on the label's current `text-anchor`), so feeding the
+ * result back via `setOption` doesn't change them — the next pass yields the
+ * same verdict, keeping the clamp loop-stable.
+ */
+export declare function decideEdgeAlignment(args: {
+    firstLabel: string;
+    lastLabel: string;
+    font: string;
+    firstTickX: number;
+    lastTickX: number;
+    width: number;
+}): EdgeAlignment;
+/**
+ * Extracts the displayed first/last category strings and the label font from
+ * the option, reading categories generically via `series[0].encode.x` into the
+ * referenced dataset (`'name'` for bar, `0` for histogram). Returns `null` when
+ * the option isn't a measurable category x-axis (fewer than 2 categories, no
+ * dataset, etc.).
+ */
+export declare function resolveEdgeLabels(option: EChartsOption): {
+    firstLabel: string;
+    lastLabel: string;
+    font: string;
+    count: number;
+} | null;
+/**
+ * Measures the rendered chart and, when the edge labels would clip, applies
+ * `alignMinLabel`/`alignMaxLabel` (or clears them) via an imperative merge
+ * `setOption`. Returns the alignment now in effect so the caller can keep a
+ * `prev` ref and skip redundant `setOption`s. Should be invoked from the
+ * chart's `finished` event (layout is settled, so `convertToPixel` is valid).
+ */
+export declare function clampEdgeLabels(chart: ECharts, option: EChartsOption, prev: EdgeAlignment): EdgeAlignment;

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

@@ -0,0 +1,4 @@
+export { EchartUI, DEFAULT_INIT_OPTS, type EchartUIProps, type EchartsEventHandler, } from './echart-ui.js';
+export { Echart, type EchartProps, type OptionFactory, type OptionFactoryContext, } from './echart.js';
+export { useChartSelection, type SelectionKey, type UseChartSelectionOptions, type ChartSelectionWiring, } from './use-chart-selection.js';
+export { observeResize, __resetSharedResizeObserver, } from './shared-resize-observer.js';

package/dist/types/widgets-v2/echart/shared-resize-observer.d.ts

@@ -0,0 +1,5 @@
+type ResizeCallback = () => void;
+export declare function observeResize(element: Element, callback: ResizeCallback): () => void;
+/** @internal — for tests only. */
+export declare function __resetSharedResizeObserver(): void;
+export {};

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

@@ -0,0 +1,7 @@
+export declare const styles: {
+    root: {
+        width: string;
+        flex: number;
+        minHeight: number;
+    };
+};

package/dist/types/widgets-v2/echart/use-chart-selection.d.ts

@@ -0,0 +1,57 @@
+import { CallbackDataParams } from 'echarts/types/dist/shared';
+import { EchartsEventHandler } from './echart-ui.js';
+export type SelectionKey = string | number;
+export interface UseChartSelectionOptions<K extends SelectionKey> {
+    /**
+     * Controlled selection. `undefined`/`null`/an explicit `[]` all mean "no
+     * selection interaction" — every current merger already treats an empty
+     * selection as "nothing excluded," so this hook collapses all three to
+     * `null` rather than promising per-merger `[]` semantics it doesn't
+     * implement.
+     */
+    selection?: readonly K[];
+    /** Receives the next selection. When omitted the wiring is a no-op. */
+    onSelectionChange?: (next: readonly K[]) => void;
+    /**
+     * Pull a selection key out of an ECharts `click` event. Return `null` to
+     * skip (e.g. a click on empty plot area). For Bar/Pie/Timeseries this is
+     * usually `(p) => p.name`; for Histogram/Scatterplot it's the dataIndex.
+     */
+    keyFromClick: (params: CallbackDataParams) => K | null;
+    /**
+     * Map a `brushSelected` payload's `selected[*]` entries (each carrying a
+     * `seriesIndex` + `dataIndex[]`) into the full set of selection keys for
+     * the brushed area. Called once per brush event.
+     */
+    keysFromBrush: (selected: readonly {
+        seriesIndex: number;
+        dataIndex: number[];
+    }[]) => K[];
+}
+export interface ChartSelectionWiring<K extends SelectionKey> {
+    /**
+     * Pass straight to `<Widget.Echart onEvents={…}>`. Wires `click` and
+     * `brushSelected` so the user's interactions reach `onSelectionChange`.
+     */
+    onEvents: Record<string, EchartsEventHandler>;
+    /**
+     * The current selection — `null` for "no selection interaction"
+     * (`undefined`/`null`/an explicit `[]`), or a non-empty array meaning
+     * "render only these as fully opaque, dim the rest".
+     */
+    selection: readonly K[] | null;
+}
+/**
+ * Translate ECharts' click + brush events into a consumer-owned selection
+ * with the expected dashboard semantics:
+ *
+ *   - **Click toggles** — clicking an item adds it to the selection if
+ *     absent, removes it if present.
+ *   - **Brush replaces** — finishing a brush stroke overwrites the selection
+ *     with whatever the brush covered (drag-to-empty clears).
+ *
+ * Wire the returned `onEvents` into `<Widget.Echart>` and feed
+ * `wiring.selection` to the widget's option factory so the merger can dim
+ * non-selected rows at fusion time.
+ */
+export declare function useChartSelection<K extends SelectionKey>({ selection, onSelectionChange, keyFromClick, keysFromBrush, }: UseChartSelectionOptions<K>): ChartSelectionWiring<K>;