@carto/ps-react-ui 5.3.0 → 6.1.0

package/dist/types/widgets/actions/fullscreen/fullscreen.d.ts

@@ -1,15 +1,85 @@
-import { FullScreenProps } from './types.js';
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps, SxProps, Theme } from '@mui/material';
+import { FullScreenLabels } from './labels.js';
+export interface FullScreenTriggerProps {
+    labels?: Partial<FullScreenLabels>;
+    enterIcon?: ComponentType<SvgIconProps>;
+    exitIcon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+export interface FullScreenSlotProps {
+    /**
+     * The widget body. Rendered twice, identically: in the card, and again in
+     * the dialog while it's open. The components inside don't know which copy
+     * they are; the dialog's just runs on a widget store of its own — a copy
+     * of the card's taken on open, handed back to the card on close — so read
+     * the widget id with `useWidgetId()` inside the body rather than closing
+     * over the card's `id`.
+     *
+     * @deprecated The function form `(isFullScreen) => ReactNode` still works
+     * (`false` for the card, `true` for the dialog copy) but will be removed
+     * in the next major: pass the body as plain children.
+     */
+    children: ReactNode | ((isFullScreen: boolean) => ReactNode);
+    /** Header text rendered above the body when the modal is open. */
+    title?: ReactNode;
+    /**
+     * Buttons rendered in the modal header, to the left of the close icon —
+     * the fullscreen counterpart of `<Widget.Actions>`, which lives in the
+     * wrapper's summary row and is covered by the dialog. Pass the same
+     * elements you compose there (typically `<Widget.Download>`); the
+     * fullscreen trigger is intentionally not among them, since the close
+     * icon already exits.
+     */
+    actions?: ReactNode;
+    /**
+     * Per-widget override merged over the default `90vw x 90vh` dialog paper.
+     * Charts want the default (their canvas grows to fill it); content-sized
+     * widgets (Range, Markdown) pass their own width / `height: 'auto'` so the
+     * modal doesn't leave a large empty box around them.
+     *
+     * Shallow-merged over the default, same as `Widget.Actions`' `sx`: pass a
+     * plain style object, not the array or theme-callback form.
+     */
+    paperSx?: SxProps<Theme>;
+    labels?: Partial<FullScreenLabels>;
+    closeIcon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
 /**
- * Displays widget content in a fullscreen modal dialog.
- *
- * Manages fullscreen state via the widget store and renders a MUI Dialog
- * with the widget title and a close button.
+ * Toggle button placed inside `<Widget.Actions>`. Reads / writes
+ * {@link FullScreenWidgetState.isFullScreen} on the per-widget store. The
+ * matching modal is rendered by {@link FullScreenSlot} (typically inside
+ * `<Widget.Content>`).
+ */
+declare function FullScreenTrigger({ labels, enterIcon: EnterIcon, exitIcon: ExitIcon, iconProps, }: FullScreenTriggerProps): import('react').JSX.Element;
+/** Id of the widget store the dialog copy runs on. */
+export declare function fullScreenStoreId(id: string): string;
+/**
+ * Body wrapper. The card keeps its copy of the body while the dialog is
+ * open, and the dialog mounts a second one on a store of its own: a copy
+ * of the card's UI state taken on open, and handed back to the card when
+ * the dialog closes. While open the two don't affect each other. MUI
+ * mounts the dialog copy on open and unmounts it after the close
+ * transition, which drops its store.
+ */
+declare function FullScreenSlot({ children, title, actions, paperSx, labels, closeIcon: CloseSvg, iconProps, }: FullScreenSlotProps): import('react').JSX.Element;
+/**
+ * Namespace export. Consumers compose with:
  *
- * @example
  * ```tsx
- * <FullScreen id="my-widget" labels={{ ariaLabel: 'Expand chart' }}>
- *   <ChartContent id="my-widget" />
- * </FullScreen>
+ * <Widget.Actions>
+ *   <Widget.FullScreen.Trigger />
+ * </Widget.Actions>
+ * <Widget.Content>
+ *   <Widget.FullScreen.Slot title={title} actions={<Widget.Download items={items} />}>
+ *     <Body />
+ *   </Widget.FullScreen.Slot>
+ * </Widget.Content>
  * ```
  */
-export declare function FullScreen({ id, labels, children, Icon, IconButtonProps, DialogContentProps: { sx, ...DialogContentProps }, DialogProps, }: FullScreenProps): import('react').JSX.Element;
+export declare const FullScreen: {
+    Trigger: typeof FullScreenTrigger;
+    Slot: typeof FullScreenSlot;
+};
+export {};

package/dist/types/widgets/actions/fullscreen/types.d.ts

@@ -1,21 +1,14 @@
-import { DialogContentProps, IconButtonProps, DialogProps } from '@mui/material';
-import { ReactNode } from 'react';
-import { BaseWidgetState } from '../../../widgets/stores/types.js';
-export type FullScreenState<T = unknown> = BaseWidgetState<T & FullScreenConfigProps & {
-    title: string;
-}>;
-export interface FullScreenConfig {
-    isFullScreen?: boolean;
-}
-export type FullScreenConfigProps = FullScreenConfig;
-export interface FullScreenProps {
-    id: FullScreenState['id'];
-    labels?: {
-        ariaLabel?: string;
-    };
-    children: ReactNode;
-    DialogContentProps?: DialogContentProps;
-    DialogProps?: DialogProps;
-    IconButtonProps?: IconButtonProps;
-    Icon?: ReactNode;
+import { WidgetState } from '../../stores/index.js';
+/**
+ * State extension owned by FullScreen. The base `WidgetState` deliberately
+ * stays free of widget-specific UI flags (R12 from the round-5 amendment);
+ * actions that need persistent UI state declare it here and read it via the
+ * generic `useWidget<T, S>(id, sel)` form.
+ *
+ * `isFullScreen` survives `keepAlive` remounts because it lives on the same
+ * store the rest of `WidgetState` does — a kept-alive widget that was
+ * fullscreen reopens fullscreen automatically.
+ */
+export interface FullScreenWidgetState extends WidgetState {
+    isFullScreen: boolean;
 }

package/dist/types/widgets/actions/index.d.ts

@@ -1,20 +1,10 @@
-export { FullScreen } from './fullscreen/fullscreen.js';
-export type { FullScreenState, FullScreenConfig, FullScreenProps, } from './fullscreen/types.js';
-export { Download } from './download/download.js';
-export type { DownloadItem, DownloadProps } from './download/types.js';
-export { downloadToCSV, downloadToPNG } from './download/exports.js';
-export { RelativeData, RELATIVE_DATA_TOOL_ID, RELATIVE_DATA_CONFIG_TOOL_ID, } from './relative-data/relative-data.js';
-export type { RelativeDataProps, RelativeDataState, } from './relative-data/types.js';
-export { ZoomToggle, ZOOM_TOGGLE_TOOL_ID } from './zoom-toggle/zoom-toggle.js';
-export type { ZoomToggleProps, ZoomState, ZoomConfig, } from './zoom-toggle/types.js';
-export { StackToggle, STACK_TOGGLE_TOOL_ID } from './stack-toggle/stack-toggle.js';
-export type { StackToggleProps, StackToggleState } from './stack-toggle/types.js';
-export { Searcher, SEARCHER_TOOL_ID } from './searcher/searcher.js';
-export { SearcherToggle } from './searcher/searcher-toggle.js';
-export type { SearcherToggleProps, SearcherProps, SearcherFilterFn, SearcherState, SearcherStateProps, } from './searcher/types.js';
-export { ChangeColumn, CHANGE_COLUMN_TOOL_ID, } from './change-column/change-column.js';
-export type { ChangeColumnProps } from './change-column/types.js';
-export { LockSelection, LOCK_SELECTION_TOOL_ID, } from './lock-selection/lock-selection.js';
-export type { LockSelectionProps, LockSelectionState, LockSelectionStateProps, } from './lock-selection/types.js';
-export { BrushToggle, BRUSH_TOGGLE_TOOL_ID } from './brush-toggle/brush-toggle.js';
-export type { BrushToggleProps, BrushState, BrushConfig, BrushSelectedItems, } from './brush-toggle/types.js';
+export { Searcher, SearcherToggle, setSearcherText, filterBySearchText, DEFAULT_SEARCHER_LABELS, type SearcherProps, type SearcherToggleProps, type SearcherLabels, } from './searcher/index.js';
+export { StackToggle, addStack, DEFAULT_STACK_TOGGLE_LABELS, type StackToggleProps, type StackToggleLabels, } from './stack-toggle/index.js';
+export { ShowAllToggle, setShowAll, SHOW_ALL_ID, DEFAULT_SHOW_ALL_LABELS, type ShowAllToggleProps, type ShowAllLabels, } from './show-all/index.js';
+export { ZoomToggle, addZoom, createAddZoom, ZOOM_LAYOUT, DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleProps, type ZoomToggleLabels, } from './zoom-toggle/index.js';
+export { BrushToggle, addBrush, DEFAULT_BRUSH_TOGGLE_LABELS, type BrushToggleProps, type BrushToggleLabels, } from './brush-toggle/index.js';
+export { RelativeData, toRelativeData, createPercentFormatter, DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataProps, type RelativeDataLabels, } from './relative-data/index.js';
+export { Download, downloadToCSV, downloadDOMToPNG, toCsvString, triggerLinkDownload, buildPngDownloadItem, buildCsvDownloadItem, withPngItem, CSVIcon, PNGIcon, MarkdownIcon, DEFAULT_DOWNLOAD_LABELS, DOWNLOAD_ITEM_IDS, type DownloadProps, type DownloadItem, type DownloadContext, type DownloadItemId, type DownloadHandle, type DownloadDOMToPNGOptions, type BuildPngDownloadItemArgs, type BuildCsvDownloadItemArgs, type WidgetDownloadArgs, type DownloadLabels, } from './download/index.js';
+export { FullScreen, DEFAULT_FULLSCREEN_LABELS, type FullScreenTriggerProps, type FullScreenSlotProps, type FullScreenLabels, type FullScreenWidgetState, } from './fullscreen/index.js';
+export { LockSelection, filterByLockedItems, DEFAULT_LOCK_SELECTION_LABELS, type LockSelectionProps, type LockSelectionKey, type LockSelectionLabels, } from './lock-selection/index.js';
+export { ChangeColumn, DEFAULT_CHANGE_COLUMN_LABELS, type ChangeColumnProps, type ChangeColumnItem, type ChangeColumnLabels, type ChangeColumnWidgetState, } from './change-column/index.js';

package/dist/types/widgets/actions/lock-selection/lock-selection.d.ts

@@ -1,19 +1,57 @@
-import { LockSelectionProps } from './types.js';
-export declare const LOCK_SELECTION_TOOL_ID = "lock-selection";
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { LockSelectionLabels } from './labels.js';
+export type LockSelectionKey = string | number;
+export interface LockSelectionProps<K extends LockSelectionKey = LockSelectionKey> {
+    /**
+     * Currently-selected items (destination-owned). On lock, this set is
+     * snapshotted into `lockedItems` via `onLockChange`.
+     */
+    selection: readonly K[];
+    /**
+     * Currently-locked items (destination-owned). When non-empty, the widget's
+     * data is filtered to these items via the registered transform.
+     */
+    lockedItems: readonly K[];
+    /**
+     * Fires when the user toggles the lock. The destination is responsible for
+     * persisting the new locked set (and re-feeding it via `lockedItems`).
+     */
+    onLockChange: (next: readonly K[]) => void;
+    labels?: Partial<LockSelectionLabels>;
+    /** Lock icon (default: `LockIcon`). */
+    lockIcon?: ComponentType<SvgIconProps>;
+    /** Unlock icon (default: `LockOpenIcon`). */
+    unlockIcon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Data transform applied while locked. Defaults to {@link filterByLockedItems}
+     * (keeps only `{name, ...}` items whose `name` is in `lockedItems`, across a
+     * `X[][]` series shape — matches Bar/Pie/Category/Timeseries data). Widgets
+     * whose data shape or selection identity differs (bin index, composite
+     * point key, flat rows) pass their own — e.g. Histogram's
+     * `filterHistogramByLockedBins`, Scatterplot's
+     * `filterScatterplotByLockedPoints`, Table's `filterTableByLockedRows`.
+     */
+    filterFn?: (data: unknown, lockedItems: readonly K[], filterKey?: string | number) => unknown;
+    /**
+     * Configuration the filter needs beyond the locked set — Table's
+     * `keyColumn`, say. Handed to `filterFn` as its third argument, so the
+     * filter can go by reference:
+     * `filterFn={filterTableByLockedRows} filterKey={keyColumn}`.
+     *
+     * Pass it rather than capturing it: `filterFn`'s identity is not a
+     * pipeline dependency (see {@link useMemoPair}), so a fresh closure over a
+     * new key is picked up while nothing re-runs.
+     */
+    filterKey?: string | number;
+}
 /**
- * Widget action button to lock the current selection.
+ * Action that pins the current selection so the widget's data filters down
+ * to those items even as the user changes selections. Selection and lock
+ * state are destination-owned; this component is a controlled UI + a data
+ * transform registered against the widget's pipeline.
  *
- * When locked, the widget data is filtered to only show the selected items.
- * The button is only visible when there are selected items.
- * Registers a transformation tool in the widget pipeline when mounted.
- *
- * @example
- * ```tsx
- * <LockSelection
- *   id="my-widget"
- *   order={30}
- *   selectedItems={selectedItems}
- * />
- * ```
+ * The trigger is disabled when there is nothing to lock and nothing locked.
  */
-export declare function LockSelection({ id, selectedItems, order, labels, Icon, IconButtonProps, }: LockSelectionProps): import('react').JSX.Element | null;
+export declare function LockSelection<K extends LockSelectionKey = LockSelectionKey>({ selection, lockedItems, onLockChange, labels, lockIcon: LockSvg, unlockIcon: UnlockSvg, iconProps, filterFn, filterKey, }: LockSelectionProps<K>): import('react').JSX.Element;

package/dist/types/widgets/actions/relative-data/relative-data.d.ts

@@ -1,24 +1,39 @@
-import { RelativeDataProps } from './types.js';
-export declare const RELATIVE_DATA_TOOL_ID = "relative-data";
-export declare const RELATIVE_DATA_CONFIG_TOOL_ID = "relative-data-config";
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { RelativeDataLabels } from './labels.js';
+export interface RelativeDataProps {
+    initialEnabled?: boolean;
+    /**
+     * BCP-47 locale tag forwarded to `Intl.NumberFormat`. Defaults to the
+     * runtime locale.
+     */
+    locale?: string;
+    labels?: Partial<RelativeDataLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Data-side transform that rewrites the widget's series into their
+     * relative (0–100) form. Defaults to {@link toRelativeData}, which
+     * handles the canonical `{ name, value }[]` shape (bar / pie /
+     * timeseries / category). Widgets with a different data shape pass
+     * their own — `toRelativeHistogramData` for histogram's `number[]`,
+     * `toRelativeScatterplotData` for scatter's `[x, y][]`.
+     *
+     * Should be a stable top-level reference; inline `(data) => ...`
+     * literals re-register the transform every render.
+     */
+    transform?: (data: unknown) => unknown;
+}
 /**
- * Widget action to toggle between relative (percentage) and absolute data display.
+ * Toggle between absolute and relative (percentage) values.
  *
- * Registers two transformation tools in the widget pipeline when mounted:
- * - A data tool that converts values to percentages (enabled/disabled via store)
- * - A config tool that is **always enabled** and reads `isRelative` from the store
- *   to decide whether to apply the percentage formatter or restore the original one.
- *   The config tool must always participate because the original formatter may have
- *   been set via `setWidget` (not in the base config), so disabling the tool would
- *   leave the percentage formatter stuck on the widget.
- *
- * @example
- * ```tsx
- * <RelativeData
- *   id="my-widget"
- *   order={20}
- *   defaultIsRelative={false}
- * />
- * ```
+ *   - **Data side**: a single data transform ({@link toRelativeData}) registered
+ *     through `useSingleTransform`. When disabled, the pipeline skips it and the
+ *     derived `data` reverts to `rawData` automatically.
+ *   - **Formatter side**: an effect writes directly to `state.formatter`. When
+ *     enabled it installs the Intl-based percent formatter; when disabled it
+ *     reads `state.rawFormatter` (the consumer-supplied original, always live)
+ *     and writes it back to `formatter`. No "original" snapshot is captured —
+ *     `rawFormatter` is the original.
  */
-export declare function RelativeData({ id, order, defaultIsRelative, labels, Icon, IconButtonProps, }: RelativeDataProps): import('react').JSX.Element;
+export declare function RelativeData({ initialEnabled, locale, labels, icon: Icon, iconProps, transform, }: RelativeDataProps): import('react').JSX.Element;

package/dist/types/{widgets-v2 → widgets}/actions/relative-data/transforms.d.ts

@@ -8,8 +8,8 @@
  * Used by widgets whose series are arrays of `{ name, value }`
  * objects — bar, pie, timeseries, category. Widgets with a different
  * data shape pass their own transform via
- * `<RelativeData transform={...} />`; see `widgets-v2/histogram` and
- * `widgets-v2/scatterplot` for in-tree examples.
+ * `<RelativeData transform={...} />`; see `widgets/histogram` and
+ * `widgets/scatterplot` for in-tree examples.
  *
  * The denominator is the sum of |value| across the series so mixed-sign
  * series (e.g. cashflow with inflows + outflows) produce sane signed

package/dist/types/widgets/actions/searcher/searcher-toggle.d.ts

@@ -1,18 +1,26 @@
-import { SearcherToggleProps } from './types.js';
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { WidgetState } from '../../stores/index.js';
+import { SearcherLabels } from './labels.js';
+export interface SearcherToggleProps {
+    labels?: Partial<SearcherLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Whether the searcher transform is enabled on first mount. Defaults
+     * to `false` so the toggle renders un-pressed and the
+     * `filterBySearchText` transform stays dormant until the user clicks
+     * it. Set to `true` for search-first widgets where the input is the
+     * primary affordance.
+     */
+    initialEnabled?: boolean;
+}
+export declare function SearcherToggle({ labels, icon: Icon, iconProps, initialEnabled, }: SearcherToggleProps): import('react').JSX.Element;
+/** The widget's current search text; empty until someone types. */
+export declare function selectSearchText(s: WidgetState): string;
 /**
- * Widget action button to toggle search functionality.
- *
- * Stores the enabled state in the widget store using the provided id.
- * When search is active, the button shows an active state with a light background.
- * Use in conjunction with the Searcher component to display the search input.
- *
- * @example
- * ```tsx
- * <SearcherToggle id="my-widget" />
- * <Searcher
- *   id="my-widget"
- *   data={widgetData}
- * />
- * ```
+ * Imperatively writes the search text into the widget store. Used by the
+ * Searcher input to update text inside transformStates without going through
+ * a re-rendered React subscription.
  */
-export declare function SearcherToggle({ id, defaultEnabled, labels, Icon, IconButtonProps, }: SearcherToggleProps): import('react').JSX.Element;
+export declare function setSearcherText(widgetId: string, value: string): void;

package/dist/types/widgets/actions/searcher/searcher.d.ts

@@ -1,21 +1,11 @@
-import { SearcherProps } from './types.js';
-export declare const SEARCHER_TOOL_ID = "searcher";
+import { SearcherLabels } from './labels.js';
+export interface SearcherProps {
+    labels?: Partial<SearcherLabels>;
+    /** Debounce delay before the input value is written to the widget store. */
+    debounceMs?: number;
+}
 /**
- * Search input component that works with SearcherToggle.
- *
- * Registers a transformation tool in the widget pipeline when mounted.
- * Reads the enabled state from the widget store using the provided id.
- * Uses a debounced search to filter data via the transformation pipeline.
- * Auto-focuses when enabled becomes true.
- *
- * @example
- * ```tsx
- * <SearcherToggle id="my-widget" />
- * <Searcher
- *   id="my-widget"
- *   order={10}
- *   labels={{ placeholder: 'Search categories...' }}
- * />
- * ```
+ * Renders only when the matching `<SearcherToggle />` is enabled — drives the
+ * `transformStates['searcher'].searchText` field via a debounced setter.
  */
-export declare function Searcher({ id, filterFn, order, labels, TextFieldProps, ClearIcon, debounceDelay, }: SearcherProps): import('react').JSX.Element | null;
+export declare function Searcher({ labels, debounceMs, }: SearcherProps): import('react').JSX.Element | null;

package/dist/types/widgets/actions/stack-toggle/stack-toggle.d.ts

@@ -1,17 +1,10 @@
-import { StackToggleProps } from './types.js';
-export declare const STACK_TOGGLE_TOOL_ID = "stack-toggle";
-/**
- * Widget action to toggle stacking behavior in ECharts bar and histogram widgets.
- *
- * Registers as a config pipeline tool so that stack configuration is automatically
- * re-applied when the base config is updated (e.g., by WidgetLoader).
- *
- * @example
- * ```tsx
- * <StackToggle
- *   id="my-widget"
- *   defaultIsStacked={false}
- * />
- * ```
- */
-export declare function StackToggle({ id, defaultIsStacked, labels, Icon, IconButtonProps, }: StackToggleProps): import('react').JSX.Element | null;
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { StackToggleLabels } from './labels.js';
+export interface StackToggleProps {
+    initialEnabled?: boolean;
+    labels?: Partial<StackToggleLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+export declare function StackToggle({ initialEnabled, labels, icon: Icon, iconProps, }: StackToggleProps): import('react').JSX.Element;

package/dist/types/widgets/actions/zoom-toggle/style.d.ts

@@ -1,13 +1,12 @@
 import { Theme } from '@mui/material';
 export declare const styles: {
-    container: {
-        display: "flex";
-        alignItems: "center";
-        gap: ({ spacing }: Theme) => string;
-    };
-    trigger: {
-        '&[data-active="true"]': {
-            background: (theme: Theme) => string;
+    toggle: {
+        p: number;
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
         };
     };
+    toggleActive: {
+        background: (theme: Theme) => string;
+    };
 };

package/dist/types/widgets/actions/zoom-toggle/zoom-toggle.d.ts

@@ -1,26 +1,35 @@
-import { ZoomToggleProps } from './types.js';
-export declare const ZOOM_TOGGLE_TOOL_ID = "zoom-toggle";
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { ZoomAxis } from './transforms.js';
+import { ZoomToggleLabels } from './labels.js';
+export interface ZoomToggleProps {
+    initialEnabled?: boolean;
+    labels?: Partial<ZoomToggleLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Which axes the zoom controls. Default `['x']` — matches bar /
+     * histogram / timeseries (horizontal pan on the category axis). Pass
+     * `['x', 'y']` for 2D zoom on a scatterplot-style chart (mouse-wheel
+     * scales both axes; horizontal slider at bottom + vertical slider on
+     * the right).
+     */
+    axes?: readonly ZoomAxis[];
+}
 /**
- * Widget action to toggle EChart zoom functionality.
+ * Toggle a `dataZoom` slider + wheel-zoom on the chart. The transform is
+ * theme-bound so the slider gets v1's CARTO chrome (blue-tinted filler,
+ * secondary-color preview, white pill handles).
  *
- * Registers as a config pipeline tool so that zoom configuration is automatically
- * re-applied when the base config is updated (e.g., by WidgetLoader).
+ * `dataZoom` is intentionally NOT in `replaceMergeKeys` — ECharts merges
+ * subsequent `setOption` calls so the user's dragged range survives
+ * unrelated re-renders (data updates, formatter swaps, RelativeData toggles).
  *
- * Zoom state (enabled, range) is stored in the widget store root, and the tool
- * derives its `enabled` flag from the store. This keeps state accessible across
- * component instances.
- *
- * When zoom is active, displays an inline reset button to disable zoom.
- * Only intended for use in fullscreen ToolbarActions for bar and histogram widgets.
- *
- * @example
- * ```tsx
- * <ZoomToggle
- *   id="my-widget"
- *   defaultZoom={false}
- *   zoomStart={0}
- *   zoomEnd={100}
- * />
- * ```
+ * On disable the transform is unregistered, but ECharts' merge semantics
+ * would otherwise *keep* the live `dataZoom` component visible. To remove
+ * the slider immediately we issue a one-shot
+ * `setOption({}, { replaceMerge: ['dataZoom'] })` against the live chart
+ * instance via {@link getEchartInstance} — this bypasses the pipeline so
+ * unrelated transforms aren't disturbed.
  */
-export declare function ZoomToggle({ id, defaultZoom, defaultZoomStart, defaultZoomEnd, labels, Icon, ResetIcon, IconButtonProps, }: ZoomToggleProps): import('react').JSX.Element;
+export declare function ZoomToggle({ initialEnabled, labels, icon: Icon, iconProps, axes, }: ZoomToggleProps): import('react').JSX.Element;

package/dist/types/widgets/bar/download.d.ts

@@ -0,0 +1,10 @@
+import { DownloadItem, WidgetDownloadArgs } from '../actions/download/index.js';
+import { BarWidgetData } from './types.js';
+export type BarDownloadConfigArgs = WidgetDownloadArgs<BarWidgetData>;
+/**
+ * Builds download items for the Bar widget. Always includes a CSV item with
+ * one `name,value` block per series, separated by an empty row when there
+ * are multiple. When `getCaptureEl` is given, also prepends a PNG item that
+ * rasterises the captured element via `html2canvas`.
+ */
+export declare function createBarDownloadConfig(args: BarDownloadConfigArgs): DownloadItem[];

package/dist/types/widgets/bar/index.d.ts

@@ -1,3 +1,4 @@
-export { barConfig, barDownloadConfig } from './config.js';
+export { barOptions, createBarOptionFactory } from './options.js';
 export { BarSkeleton } from './skeleton.js';
-export type { BarWidgetData, BarWidgetState, BarConfig, BarWidgetConfig, } from './types.js';
+export { createBarDownloadConfig } from './download.js';
+export type { BarDatum, BarWidgetData, BarOptionsInput, BarOptionFactoryInput, BarEChartsOption, } from './types.js';

package/dist/types/widgets/bar/skeleton.d.ts

@@ -1 +1,6 @@
+/**
+ * Loading state for the Bar widget. Mirrors a bar chart's silhouette — five
+ * vertical bars at staggered heights anchored to the bottom, plus a legend
+ * stub — so the skeleton reads as "a bar chart" rather than a generic list.
+ */
 export declare function BarSkeleton(): import('react').JSX.Element;

package/dist/types/widgets/bar/types.d.ts

@@ -1,9 +1,46 @@
-import { EchartWidgetData, EchartWidgetState } from '../echart/index.js';
-import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types.js';
-import { ConfigProps } from '../loader/index.js';
-export type BarWidgetData = EchartWidgetData;
-export type BarWidgetState = EchartWidgetState;
-export type BarWidgetConfig = EchartWidgetProps & {
-    type: 'bar';
-};
-export type BarConfig = ConfigProps & EchartWidgetOptionProps<BarWidgetData>;
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types.js';
+/** A single category entry in a bar series. */
+export interface BarDatum {
+    name: string | number;
+    value: number;
+}
+/** v2 bar widget data shape: array of series, each a flat list of `{name, value}`. */
+export type BarWidgetData = readonly (readonly BarDatum[])[];
+/** Inputs to the structural-only {@link barOptions} builder. */
+export interface BarOptionsInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+}
+/**
+ * Combined inputs for the option factory creator. Carries everything the
+ * widget needs across BOTH phases — the structural-build (`theme`,
+ * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
+ * (`series`, `selection`).
+ */
+export interface BarOptionFactoryInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+    /**
+     * Per-series metadata — drives the legend, `series[i].name`, and
+     * (when `color` is set) per-series `itemStyle.color`. Paired with the
+     * data series by index.
+     */
+    series?: readonly WidgetSeries[];
+    /**
+     * When set, every datum whose `name` is **not** in this list renders dimmed
+     * (`itemStyle.opacity: 0.15`, matching `outOfBrush` styling). `null`/empty
+     * means "no selection active" — every bar is fully opaque.
+     */
+    selection?: readonly (string | number)[] | null;
+    /**
+     * Consumer-supplied partial option merged into the structural option at
+     * structural-build time (via `mergeOptions`). Lets stories override pieces
+     * of the theme-aware base without forking the structural builder.
+     */
+    optionsOverride?: Partial<EChartsOption>;
+}
+export type BarEChartsOption = EChartsOption;