@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

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

@@ -1,15 +1,6 @@
 import { IconButtonProps } from '@mui/material';
 import { ReactNode } from 'react';
-import { BaseWidgetState } from '../../stores/types';
-/**
- * Lock selection specific state properties.
- */
-export interface LockSelectionStateProps {
-    /** Whether the selection is currently locked */
-    isLocked?: boolean;
-    /** The items that are locked (by name) */
-    lockedItems?: string[];
-}
+import { BaseWidgetState } from '../../stores/types.js';
 /**
  * Widget state extension for lock selection functionality.
  * Extends the base widget state with lock-specific properties.
@@ -36,3 +27,12 @@ export interface LockSelectionProps {
     /** Custom icon to display */
     Icon?: ReactNode;
 }
+/**
+ * Lock selection specific state properties.
+ */
+export interface LockSelectionStateProps {
+    /** Whether the selection is currently locked */
+    isLocked?: boolean;
+    /** Items locked for filtering */
+    lockedItems?: string[];
+}

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

@@ -1,10 +1,16 @@
-import { RelativeDataProps } from './types';
+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";
 /**
  * Widget action to toggle between relative (percentage) and absolute data display.
  *
- * Registers a transformation tool in the widget pipeline when mounted.
- * When relative mode is active, transforms data to percentages via the pipeline.
+ * 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
@@ -15,4 +21,4 @@ export declare const RELATIVE_DATA_TOOL_ID = "relative-data";
  * />
  * ```
  */
-export declare function RelativeData({ id, order, defaultIsRelative, labels, Icon, IconButtonProps, }: RelativeDataProps): import("react/jsx-runtime").JSX.Element;
+export declare function RelativeData({ id, order, defaultIsRelative, labels, Icon, IconButtonProps, }: RelativeDataProps): import('react').JSX.Element;

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

@@ -1,6 +1,6 @@
 import { IconButtonProps } from '@mui/material';
 import { ReactNode } from 'react';
-import { BaseWidgetState } from '../../stores/types';
+import { BaseWidgetState } from '../../../widgets/stores/index.js';
 export interface RelativeDataProps {
     /** Widget ID to update data in the widget store */
     id: string;
@@ -24,4 +24,6 @@ export interface RelativeDataProps {
 }
 export type RelativeDataState<T = unknown> = BaseWidgetState<T & {
     isRelative?: boolean;
+    originalFormatter?: (value: number) => string;
+    originalMax?: number;
 }>;

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

@@ -1,4 +1,4 @@
-import { EchartWidgetData } from '../../echart/types';
+import { EchartWidgetData } from '../../echart/types.js';
 /**
  * Calculates the sum of all numeric values in the data
  */

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

@@ -1,4 +1,4 @@
-import { SearcherToggleProps } from './types';
+import { SearcherToggleProps } from './types.js';
 /**
  * Widget action button to toggle search functionality.
  *
@@ -15,4 +15,4 @@ import { SearcherToggleProps } from './types';
  * />
  * ```
  */
-export declare function SearcherToggle({ id, defaultEnabled, labels, Icon, IconButtonProps, }: SearcherToggleProps): import("react/jsx-runtime").JSX.Element;
+export declare function SearcherToggle({ id, defaultEnabled, labels, Icon, IconButtonProps, }: SearcherToggleProps): import('react').JSX.Element;

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

@@ -1,4 +1,4 @@
-import { SearcherProps } from './types';
+import { SearcherProps } from './types.js';
 export declare const SEARCHER_TOOL_ID = "searcher";
 /**
  * Search input component that works with SearcherToggle.
@@ -18,4 +18,4 @@ export declare const SEARCHER_TOOL_ID = "searcher";
  * />
  * ```
  */
-export declare function Searcher({ id, filterFn, order, labels, TextFieldProps, ClearIcon, debounceDelay, }: SearcherProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Searcher({ id, filterFn, order, labels, TextFieldProps, ClearIcon, debounceDelay, }: SearcherProps): import('react').JSX.Element | null;

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

@@ -1,7 +1,7 @@
 import { IconButtonProps, TextFieldProps } from '@mui/material';
 import { ReactNode } from 'react';
-import { EchartWidgetData } from '../../echart/types';
-import { BaseWidgetState } from '../../stores/types';
+import { EchartWidgetData } from '../../echart/types.js';
+import { BaseWidgetState } from '../../stores/types.js';
 /**
  * Filter function type for custom search filtering logic.
  * Receives the original data and search text, returns filtered data.

package/dist/types/widgets/actions/stack-toggle/grouped-bar-chart-icon.d.ts

@@ -1 +1 @@
-export declare const GroupedBarChartIcon: () => import("react/jsx-runtime").JSX.Element;
+export declare const GroupedBarChartIcon: () => import('react').JSX.Element;

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

@@ -1,9 +1,10 @@
-import { StackToggleProps } from './types';
+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.
  *
- * Stores the stack state in the widget store and updates the ECharts option
- * using getEChartStackConfig to apply stacking to all series.
+ * 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
@@ -13,4 +14,4 @@ import { StackToggleProps } from './types';
  * />
  * ```
  */
-export declare function StackToggle({ id, defaultIsStacked, labels, Icon, IconButtonProps, }: StackToggleProps): import("react/jsx-runtime").JSX.Element;
+export declare function StackToggle({ id, defaultIsStacked, labels, Icon, IconButtonProps, }: StackToggleProps): import('react').JSX.Element | null;

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

@@ -1,6 +1,6 @@
 import { IconButtonProps } from '@mui/material';
 import { ReactNode } from 'react';
-import { BaseWidgetState } from '../../stores/types';
+import { BaseWidgetState } from '../../stores/types.js';
 export interface StackToggleProps {
     /** Widget ID to update stack configuration in the widget store */
     id: string;

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

@@ -1,6 +1,6 @@
 import { IconButtonProps } from '@mui/material';
 import { ReactNode } from 'react';
-import { BaseWidgetState } from '../../stores/types';
+import { BaseWidgetState } from '../../stores/types.js';
 /**
  * State stored in widget store for zoom functionality
  */

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

@@ -1,7 +1,15 @@
-import { ZoomToggleProps } from './types';
+import { ZoomToggleProps } from './types.js';
+export declare const ZOOM_TOGGLE_TOOL_ID = "zoom-toggle";
 /**
  * Widget action to toggle EChart zoom functionality.
  *
+ * Registers as a config pipeline tool so that zoom configuration is automatically
+ * re-applied when the base config is updated (e.g., by WidgetLoader).
+ *
+ * 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.
  *
@@ -15,4 +23,4 @@ import { ZoomToggleProps } from './types';
  * />
  * ```
  */
-export declare function ZoomToggle({ id, defaultZoom, defaultZoomStart, defaultZoomEnd, labels, Icon, ResetIcon, IconButtonProps, }: ZoomToggleProps): import("react/jsx-runtime").JSX.Element;
+export declare function ZoomToggle({ id, defaultZoom, defaultZoomStart, defaultZoomEnd, labels, Icon, ResetIcon, IconButtonProps, }: ZoomToggleProps): import('react').JSX.Element;

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

@@ -1,5 +1,9 @@
-import { BarConfig, BarWidgetConfig, BarWidgetData } from './types';
-import { DownloadItem } from '../actions';
-import { ConfigProps } from '../root/types';
-export declare function barDownloadConfig({ refUI, }: ConfigProps): DownloadItem<BarWidgetData>[];
+import { BarConfig, BarWidgetConfig } from './types.js';
+export declare const barDownloadConfig: ({ refUI }: import('../loader/index.js').ConfigProps) => import('../actions/index.js').DownloadItem<import('../echart/index.js').EchartWidgetData>[];
+/**
+ * Generates ECharts configuration for bar chart widgets (vertical and horizontal), including axis, tooltip, legend, and series options styled with the CARTO theme.
+ *
+ * @param props - Bar chart configuration including data and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export declare function barConfig(props: BarConfig): BarWidgetConfig;

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

@@ -1,3 +1,3 @@
-export { barConfig, barDownloadConfig } from './config';
-export { BarSkeleton } from './skeleton';
-export type { BarWidgetData, BarWidgetState, BarConfig, BarWidgetConfig, } from './types';
+export { barConfig, barDownloadConfig } from './config.js';
+export { BarSkeleton } from './skeleton.js';
+export type { BarWidgetData, BarWidgetState, BarConfig, BarWidgetConfig, } from './types.js';

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

@@ -1 +1 @@
-export declare function BarSkeleton(): import("react/jsx-runtime").JSX.Element;
+export declare function BarSkeleton(): import('react').JSX.Element;

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

@@ -1,6 +1,6 @@
-import { EchartWidgetData, EchartWidgetState } from '../echart';
-import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types';
-import { ConfigProps } from '../root';
+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 & {

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

@@ -1,2 +1,5 @@
-import { CategoryUIProps } from './types';
-export declare function CategoryUI({ id }: CategoryUIProps): import("react/jsx-runtime").JSX.Element | null;
+import { CategoryUIProps } from './types.js';
+/**
+ * Renders a category widget displaying horizontal bars for categorical data with support for single and multi-series layouts, selection, and overflow grouping.
+ */
+export declare function CategoryUI({ id }: CategoryUIProps): import('react').JSX.Element | null;

package/dist/types/widgets/category/components/category-bar.d.ts

@@ -4,4 +4,7 @@ export interface CategoryBarProps {
     color: string;
     selected?: boolean;
 }
-export declare function CategoryBar({ value, maxValue, color, selected, }: CategoryBarProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Renders a single horizontal bar fill proportional to its value relative to the maximum.
+ */
+export declare function CategoryBar({ value, maxValue, color, selected, }: CategoryBarProps): import('react').JSX.Element;

package/dist/types/widgets/category/components/category-legend.d.ts

@@ -1,6 +1,9 @@
-import { CategorySeriesConfig } from '../types';
+import { CategorySeriesConfig } from '../types.js';
 export interface CategoryLegendProps {
     series: CategorySeriesConfig[];
     colors: string[];
 }
-export declare function CategoryLegend({ series, colors }: CategoryLegendProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Renders a color-coded legend for multi-series category widgets.
+ */
+export declare function CategoryLegend({ series, colors }: CategoryLegendProps): import('react').JSX.Element | null;

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

@@ -1,11 +1,15 @@
-import { CategoryWidgetConfig } from '../types';
+import { CategoryWidgetConfig } from '../types.js';
 export interface CategoryRowMultiProps {
     name: string;
     values: number[];
     maxValue: number;
     colors: string[];
     formatter: NonNullable<CategoryWidgetConfig['formatter']>;
+    labelFormatter?: CategoryWidgetConfig['labelFormatter'];
     onClick?: CategoryWidgetConfig['onRowClick'];
     selected?: boolean;
 }
-export declare function CategoryRowMulti({ name, values, maxValue, colors, formatter, onClick, selected, }: CategoryRowMultiProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Renders a multi-series category row with a label and multiple color-coded bars stacked vertically.
+ */
+export declare function CategoryRowMulti({ name, values, maxValue, colors, formatter, labelFormatter, onClick, selected, }: CategoryRowMultiProps): import('react').JSX.Element;

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

@@ -3,4 +3,7 @@ export interface CategoryRowOtherProps {
     otherLabel?: string;
     otherCountLabel?: string;
 }
-export declare function CategoryRowOther({ hiddenCount, otherLabel, otherCountLabel, }: CategoryRowOtherProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Renders an "Other" summary row indicating how many additional categories are hidden beyond `maxItems`.
+ */
+export declare function CategoryRowOther({ hiddenCount, otherLabel, otherCountLabel, }: CategoryRowOtherProps): import('react').JSX.Element;

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

@@ -1,11 +1,15 @@
-import { CategoryWidgetConfig } from '../types';
+import { CategoryWidgetConfig } from '../types.js';
 export interface CategoryRowSingleProps {
     name: string;
     value: number;
     maxValue: number;
     color: string;
     formatter: NonNullable<CategoryWidgetConfig['formatter']>;
+    labelFormatter?: CategoryWidgetConfig['labelFormatter'];
     onClick?: CategoryWidgetConfig['onRowClick'];
     selected?: boolean;
 }
-export declare function CategoryRowSingle({ name, value, maxValue, color, formatter, onClick, selected, }: CategoryRowSingleProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Renders a single-series category row with a label, formatted value, and proportional bar.
+ */
+export declare function CategoryRowSingle({ name, value, maxValue, color, formatter, labelFormatter, onClick, selected, }: CategoryRowSingleProps): import('react').JSX.Element;

package/dist/types/widgets/category/config.d.ts

@@ -1,16 +1,20 @@
-import { DownloadItem } from '../actions';
-import { ConfigProps } from '../root/types';
-import { CategoryWidgetConfig, CategoryWidgetData, CategorySeriesConfig, CategoryLabels } from './types';
-export interface CategoryDownloadConfigProps extends ConfigProps {
+import { DownloadItem } from '../actions/index.js';
+import { ConfigProps } from '../loader/types.js';
+import { CategoryWidgetConfig, CategoryWidgetData, CategorySeriesConfig } from './types.js';
+interface CategoryDownloadConfigProps extends ConfigProps {
     series?: CategorySeriesConfig[];
 }
-export interface CategoryConfigProps {
-    data?: CategoryWidgetData;
-    series?: CategorySeriesConfig[];
-    formatter?: (value: number) => string;
-    maxItems?: number;
-    labels?: CategoryLabels;
-    max?: number;
-}
+/**
+ * Creates download configuration for category widgets, supporting PNG (screenshot) and CSV (data) exports. CSV output groups values by category across multiple series.
+ *
+ * @param props - Configuration with `refUI` reference and optional `series` for CSV column headers.
+ * @returns Array of download items for use with the Download action.
+ */
 export declare function categoryDownloadConfig({ refUI, series, }: CategoryDownloadConfigProps): DownloadItem<CategoryWidgetData>[];
+/**
+ * Returns the default configuration for category list widgets, including empty series and a default `maxItems` of 10.
+ *
+ * @returns Default category widget config.
+ */
 export declare function categoryConfig(): CategoryWidgetConfig;
+export {};

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

@@ -1,6 +1,14 @@
-export { CategoryUI } from './category-ui';
-export { CategorySkeleton } from './skeleton';
-export { categoryConfig, categoryDownloadConfig } from './config';
-export { CategoryBar, CategoryRowSingle, CategoryRowMulti, CategoryLegend, CategoryRowOther, } from './components';
-export type { CategoryBarProps, CategoryRowSingleProps, CategoryRowMultiProps, CategoryLegendProps, CategoryRowOtherProps, } from './components';
-export type { CategoryUIProps, CategoryWidgetData, CategoryWidgetState, CategoryWidgetConfig, CategoryDownloadConfig, CategoryDataItem, CategorySeriesConfig, CategoryLabels, } from './types';
+export { CategoryUI } from './category-ui.js';
+export { CategorySkeleton } from './skeleton.js';
+export { categoryConfig, categoryDownloadConfig } from './config.js';
+export { CategoryBar } from './components/category-bar.js';
+export type { CategoryBarProps } from './components/category-bar.js';
+export { CategoryRowSingle } from './components/category-row-single.js';
+export type { CategoryRowSingleProps } from './components/category-row-single.js';
+export { CategoryRowMulti } from './components/category-row-multi.js';
+export type { CategoryRowMultiProps } from './components/category-row-multi.js';
+export { CategoryRowOther } from './components/category-row-other.js';
+export type { CategoryRowOtherProps } from './components/category-row-other.js';
+export { CategoryLegend } from './components/category-legend.js';
+export type { CategoryLegendProps } from './components/category-legend.js';
+export type { CategoryUIProps, CategoryWidgetData, CategoryWidgetState, CategoryWidgetConfig, CategoryDownloadConfig, CategoryDataItem, CategorySeriesConfig, CategoryLabels, } from './types.js';

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

@@ -1 +1 @@
-export declare function CategorySkeleton(): import("react/jsx-runtime").JSX.Element;
+export declare function CategorySkeleton(): import('react').JSX.Element;

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

@@ -4,7 +4,7 @@ export declare const styles: {
         display: "flex";
         flexDirection: "column";
         position: "relative";
-        overflow: "auto";
+        width: string;
     };
     list: {
         display: "flex";

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

@@ -1,6 +1,6 @@
-import { BaseWidgetState, WidgetsStoreProps } from '../stores/types';
-import { WrapperState } from '../wrapper/types';
-import { DownloadItem } from '../actions/download/types';
+import { BaseWidgetState, WidgetsStoreProps } from '../stores/types.js';
+import { WrapperState } from '../wrapper/types.js';
+import { DownloadItem } from '../actions/download/types.js';
 export interface CategoryUIProps {
     id: WidgetsStoreProps['id'];
 }
@@ -22,6 +22,7 @@ export type CategoryWidgetState = BaseWidgetState<WrapperState<CategoryWidgetCon
 }>;
 export interface CategoryWidgetConfig {
     formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
     series?: CategorySeriesConfig[];
     maxItems?: number;
     labels?: CategoryLabels;

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

@@ -1,2 +1,9 @@
-import { EchartUIProps } from './types';
-export declare function EchartUI({ id, ref, init, option, className, style, onEvents, }: EchartUIProps): import("react/jsx-runtime").JSX.Element;
+import { EchartUIProps } from './types.js';
+/**
+ * Presentational component that initializes and manages an Apache ECharts instance.
+ *
+ * @remarks
+ * Handles chart lifecycle (init, dispose), option updates, resize observation, and event listener management.
+ * Uses SVG renderer with a default height of 304px.
+ */
+export declare function EchartUI(props: EchartUIProps): import('react').JSX.Element;

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

@@ -1,2 +1,8 @@
-import { EchartProps } from './types';
-export declare function Echart(props: EchartProps): import("react/jsx-runtime").JSX.Element | null;
+import { EchartProps } from './types.js';
+/**
+ * Stateful EChart widget component that reads data and options from the widget store and renders an ECharts chart.
+ *
+ * @remarks
+ * Transforms widget data into ECharts dataset format and delegates rendering to {@link EchartUI}.
+ */
+export declare function Echart(props: EchartProps): import('react').JSX.Element | null;

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

@@ -1,5 +1,5 @@
-export { Echart } from './echart';
-export { EchartUI } from './echart-ui';
-export type { EchartProps, EchartOptionsProps, EchartUIProps, EchartWidgetData, EchartWidgetState, } from './types';
-export { getCommonOptions } from './options';
-export { mergeEchartWidgetConfig, getEChartBrushConfig, getEChartStackConfig, getEChartZoomConfig, } from './utils';
+export { Echart } from './echart.js';
+export { EchartUI } from './echart-ui.js';
+export type { EchartProps, EchartOptionsProps, EchartUIProps, EchartWidgetData, EchartWidgetState, } from './types.js';
+export { getCommonOptions } from './options.js';
+export { mergeEchartWidgetConfig, getEChartBrushConfig, getEChartStackConfig, getEChartZoomConfig, } from './utils.js';

package/dist/types/widgets/echart/options.d.ts

@@ -1,2 +1,9 @@
-import { EchartOptionsProps, EchartWidgetOptionProps } from './types';
+import { EchartOptionsProps, EchartWidgetOptionProps } from './types.js';
+/**
+ * Returns the shared base ECharts options used across all EChart-based widgets (bar, pie, histogram, etc.).
+ *
+ * @remarks
+ * Configures grid spacing, tooltip styling, legend, axis pointer, and the default color palette
+ * derived from the MUI theme.
+ */
 export declare function getCommonOptions({ theme, }: EchartWidgetOptionProps<unknown>): EchartOptionsProps;

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

@@ -0,0 +1,12 @@
+/**
+ * Shared ResizeObserver singleton for all ECharts instances.
+ *
+ * Instead of creating 100+ individual ResizeObserver instances (one per chart),
+ * this module provides a single shared observer that efficiently handles resize
+ * callbacks for all registered elements.
+ */
+type ResizeCallback = () => void;
+export declare function observeResize(element: Element, callback: ResizeCallback): () => void;
+/** Reset the shared observer (for testing only). */
+export declare function resetSharedResizeObserver(): void;
+export {};

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

@@ -1,6 +1,6 @@
 import { EChartsOption } from 'echarts';
-import { BaseWidgetState } from '../stores/types';
-import { Ref } from 'react';
+import { BaseWidgetState } from '../stores/types.js';
+import { Ref, RefObject } from 'react';
 import { theme as CartoTheme } from '@carto/meridian-ds/theme';
 import type * as echarts from 'echarts';
 export type EchartOptionsProps = EChartsOption;
@@ -21,13 +21,18 @@ export type EchartWidgetState = BaseWidgetState<{
     option: EchartUIProps['option'];
     onEvents?: EchartUIProps['onEvents'];
     init?: EchartUIProps['init'];
+    instance?: RefObject<echarts.ECharts | null>;
 }>;
 export interface EchartWidgetOptionProps<D> {
     data?: D;
     theme: typeof CartoTheme;
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
 }
 export interface EchartWidgetProps {
     type: string;
     option: EchartUIProps['option'];
     onEvents?: EchartUIProps['onEvents'];
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
 }

package/dist/types/widgets/echart/utils.d.ts

@@ -1,15 +1,45 @@
-import { EchartOptionsProps } from './types';
+import { EchartOptionsProps } from './types.js';
 import { Theme } from '@mui/material';
-export declare function mergeEchartWidgetConfig<T extends EchartOptionsProps>(...options: [T | undefined, T | undefined]): T;
-export declare function getEChartZoomConfig(zoom: boolean, { start, end }?: {
+/**
+ * Deep-merges two ECharts option objects with smart handling for `color`, `axisLabel`, and `series` keys.
+ *
+ * @param optionA - Base ECharts options.
+ * @param optionB - Override ECharts options to merge on top.
+ * @param customMergeFn - Optional function returning a custom merge strategy per key.
+ * @returns The merged ECharts options object.
+ *
+ * @remarks
+ * - `color` arrays are replaced entirely (not concatenated).
+ * - `axisLabel` formatters are composed so the base formatter can suppress values by returning `''`.
+ * - `series` arrays are merged element-by-element rather than concatenated.
+ *
+ * @example
+ * ```tsx
+ * const option = mergeEchartWidgetConfig(props.option, {
+ *   series: [{ barWidth: '60%', itemStyle: { borderRadius: [4, 4, 0, 0] } }],
+ *   tooltip: { trigger: 'axis' },
+ * })
+ * ```
+ */
+export declare function mergeEchartWidgetConfig<T extends EchartOptionsProps>(optionA: T | undefined, optionB: T | undefined, customMergeFn?: (key: string) => ((a: unknown, b: unknown) => unknown) | undefined): T;
+/**
+ * Generates ECharts `dataZoom` configuration for interactive zoom and pan on chart axes.
+ *
+ * @param range - Initial visible range as `{ start, end }` percentages (0-100). Defaults to full range.
+ * @param options - Zoom behavior options including axis sliders, inside zoom, and formatter.
+ * @param theme - Optional MUI theme for styled slider handles and backgrounds.
+ * @returns An object containing the `dataZoom` array configuration.
+ */
+export declare function getEChartZoomConfig({ start, end }?: {
     start: number;
     end: number;
-}, { inside, xSlider, ySlider, showSliders, xAxisLabelFormatter, }?: {
+}, { inside, xSlider, ySlider, showSliders, xAxisLabelFormatter, bottomOffset, }?: {
     inside?: boolean;
     xSlider?: boolean;
     ySlider?: boolean;
     showSliders?: boolean;
     xAxisLabelFormatter?: (value: number) => string;
+    bottomOffset?: number;
 }, theme?: Theme): {
     dataZoom: ({
         throttle: number;
@@ -67,14 +97,32 @@ export declare function getEChartZoomConfig(zoom: boolean, { start, end }?: {
         orientation?: undefined;
     })[];
 };
-export declare function getEChartBrushConfig(brush: boolean): {
+/**
+ * Generates ECharts `brush` configuration for interactive data selection on charts.
+ *
+ * @param options - Brush options including type, mode, and target axis index.
+ * @returns An object containing the `brush` configuration.
+ */
+export declare function getEChartBrushConfig({ brushType, brushMode, xAxisIndex }?: {
+    brushType?: string;
+    brushMode?: string;
+    xAxisIndex?: number;
+    throttleType?: string;
+    throttleDelay?: number;
+}): {
     brush: {
+        toolbox: string[];
         brushType: string;
         brushMode: string;
+        xAxisIndex: number;
     };
-} | {
-    brush?: undefined;
 };
-export declare function getEChartStackConfig(stack: boolean, stackGroup?: string): {
-    stack: string | undefined;
+/**
+ * Returns an ECharts `stack` configuration to group series into a stacked layout.
+ *
+ * @param stackGroup - The stack group identifier. Defaults to the library's default group.
+ * @returns An object with the `stack` property set to the group name.
+ */
+export declare function getEChartStackConfig(stackGroup?: string): {
+    stack: string;
 };

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

@@ -1,2 +1,12 @@
-import { WidgetErrorProps } from './types';
-export declare function WidgetError({ id, children }: WidgetErrorProps): string | number | bigint | boolean | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+import { WidgetErrorProps } from './types.js';
+/**
+ * Displays an error alert when a widget encounters an error during data loading. Reads error state from the widget store and hides errors during loading/fetching to prevent flashing.
+ *
+ * @example
+ * ```tsx
+ * <WidgetError id="my-widget">
+ *   <WidgetContent />
+ * </WidgetError>
+ * ```
+ */
+export declare function WidgetError({ id, children, title: titleProp, description, }: WidgetErrorProps): string | number | bigint | boolean | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | import('react').JSX.Element | null | undefined;

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

@@ -1,2 +1,2 @@
-export { WidgetError } from './error';
-export type { WidgetErrorProps } from './types';
+export { WidgetError } from './error.js';
+export type { WidgetErrorProps } from './types.js';

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

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { WidgetState } from '../stores/types';
+import { WidgetState } from '../stores/types.js';
 export interface WidgetErrorProps {
     /**
      * Widget ID to fetch error state from store
@@ -9,4 +9,12 @@ export interface WidgetErrorProps {
      * Children to render when no error exists
      */
     children: ReactNode;
+    /**
+     * Override error title
+     */
+    title?: string;
+    /**
+     * Override error description/message
+     */
+    description?: string;
 }

package/dist/types/widgets/formula/components/item.d.ts

@@ -1,2 +1,5 @@
-import { ItemProps } from '../types';
-export declare function Item(props: ItemProps): import("react/jsx-runtime").JSX.Element;
+import { ItemProps } from '../types.js';
+/**
+ * Base typography wrapper used by formula sub-components (Value, Prefix, Suffix) to render styled text.
+ */
+export declare function Item(props: ItemProps): import('react').JSX.Element;