@carto/ps-react-ui 4.4.0-chat-ui.5 → 4.4.0-chat-ui.7

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

@@ -1,2 +1,7 @@
 import { RangeWidgetConfig } from './types';
+/**
+ * Returns the default configuration for range (value range with labels) widgets.
+ *
+ * @returns Default range widget config.
+ */
 export declare function rangeConfig(): RangeWidgetConfig;

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

@@ -1,2 +1,5 @@
 import { RangeUIProps } from './types';
+/**
+ * Renders a range widget with one or more interactive dual-slider controls for selecting value ranges.
+ */
 export declare function RangeUI(props: RangeUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,9 @@
 import { ScatterplotConfig, ScatterplotWidgetConfig, ScatterplotWidgetData } from './types';
-import { DownloadItem } from '../actions';
-import { ConfigProps } from '../loader/types';
-export declare function scatterplotDownloadConfig({ refUI, }: ConfigProps): DownloadItem<ScatterplotWidgetData>[];
+export declare const scatterplotDownloadConfig: ({ refUI }: import('../loader').ConfigProps) => import('../actions').DownloadItem<ScatterplotWidgetData>[];
+/**
+ * Generates ECharts configuration for X-Y scatter plot widgets with value axes, legend support, and CARTO qualitative color palette.
+ *
+ * @param props - Scatterplot configuration including data points and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export declare function scatterplotConfig(props: ScatterplotConfig): ScatterplotWidgetConfig;

package/dist/types/widgets/selection-summary/selection-summary.d.ts

@@ -1,2 +1,13 @@
 import { WidgetSelectionSummaryProps } from './types';
+/**
+ * Displays the count of selected items with an optional clear button. Commonly used with the LockSelection action to show selection state in widgets.
+ *
+ * @example
+ * ```tsx
+ * <WidgetSelectionSummary
+ *   selections={selectedItems.length}
+ *   onClear={() => setSelectedItems([])}
+ * />
+ * ```
+ */
 export declare function WidgetSelectionSummary({ selections, onClear, labels, }: WidgetSelectionSummaryProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/skeleton-loader/skeleton-loader.d.ts

@@ -1,2 +1,12 @@
 import { SkeletonLoaderProps } from './types';
+/**
+ * Displays a skeleton loading placeholder while widget data is loading. Subscribes to widget loading state in the store and renders the provided Skeleton component or children accordingly.
+ *
+ * @example
+ * ```tsx
+ * <SkeletonLoader id="sales-chart" Skeleton={BarSkeleton}>
+ *   <Bar id="sales-chart" />
+ * </SkeletonLoader>
+ * ```
+ */
 export declare function SkeletonLoader({ id, children, Skeleton, }: SkeletonLoaderProps): 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;

package/dist/types/widgets/spread/components/max-value.d.ts

@@ -1,2 +1,5 @@
 import { ValueProps } from '../types';
+/**
+ * Displays the formatted maximum value for a spread widget data item.
+ */
 export declare function MaxValue({ id, index, ...props }: ValueProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/spread/components/min-value.d.ts

@@ -1,2 +1,5 @@
 import { ValueProps } from '../types';
+/**
+ * Displays the formatted minimum value for a spread widget data item.
+ */
 export declare function MinValue({ id, index, ...props }: ValueProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/spread/components/separator.d.ts

@@ -1,2 +1,5 @@
 import { ItemProps } from '../../formula/types';
+/**
+ * Renders a dash separator between the min and max values in a spread widget.
+ */
 export declare function Separator(props: Omit<ItemProps, 'children'>): import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,16 @@
 import { DownloadItem } from '../actions';
 import { ConfigProps } from '../loader/types';
 import { SpreadWidgetConfig, SpreadWidgetData } from './types';
+/**
+ * Creates download configuration for spread widgets, supporting PNG (screenshot) and CSV (min/max data) exports.
+ *
+ * @param props - Configuration with `refUI` reference for PNG export.
+ * @returns Array of download items for use with the Download action.
+ */
 export declare function spreadDownloadConfig({ refUI, }: ConfigProps): DownloadItem<SpreadWidgetData>[];
+/**
+ * Returns the default configuration for spread (min/max value range) widgets.
+ *
+ * @returns Default spread widget config with empty series.
+ */
 export declare function spreadConfig(): SpreadWidgetConfig;

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

@@ -1,2 +1,5 @@
 import { SpreadUIProps } from './types';
+/**
+ * Renders a spread widget displaying min-max value pairs with optional prefixes, suffixes, and series indicators.
+ */
 export declare function SpreadUI(props: SpreadUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,2 +1,3 @@
-export { useWidgetStore } from './widget-store';
-export type { BaseWidgetState, ToolType, WidgetsStoreProps, WidgetState, WidgetStore, WidgetStoreActions, WidgetStoreState, } from './types';
+export { useWidgetStore, widgetStoreActions } from './widget-store';
+export { useWidgetSelector } from './use-widget-selector';
+export type { BaseWidgetState, ToolRegistration, ToolTransformFunction, ToolType, WidgetsStoreProps, WidgetState, WidgetStore, WidgetStoreActions, WidgetStoreState, } from './types';

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

@@ -12,6 +12,10 @@ export interface WidgetsStoreProps {
     type: string;
     /** Widget data - flexible to accommodate different widget types */
     data: unknown;
+    /** Original pre-pipeline data. Used by NoData to distinguish
+     *  "no data from API" from "pipeline tools filtered everything out".
+     *  Set automatically by executeToolPipeline — not a component prop. */
+    sourceData?: unknown;
     /** Loading state */
     isLoading: boolean;
     /** Fetching state (e.g., for async data) */
@@ -29,6 +33,8 @@ export interface WidgetsStoreProps {
     registeredTools?: ToolRegistration[];
     /** Formatter function for widget values */
     formatter?: (value: number) => string;
+    /** Formatter function for widget label/category values */
+    labelFormatter?: (value: string | number) => string | number;
     /** Locale for number formatting (e.g., 'en-US', 'es-ES', 'fr-FR') */
     locale?: string;
 }
@@ -36,7 +42,7 @@ export interface WidgetsStoreProps {
  * Tool transformation function type
  * Can be synchronous or asynchronous to support remote operations
  */
-export type ToolTransformFunction = (data: unknown, config?: Record<string, unknown>) => Promise<unknown> | unknown;
+export type ToolTransformFunction = (data: unknown) => unknown;
 /**
  * Tool registration for widget pipeline
  *
@@ -78,8 +84,6 @@ export interface ToolRegistration {
     enabled: boolean;
     /** 'data' (default) transforms data, 'config' transforms widget config/option */
     type?: ToolType;
-    /** Tool-specific configuration */
-    config?: Record<string, unknown>;
     /**
      * Array of tool IDs to disable when this tool is active.
      * During pipeline execution, if this tool is enabled, any tools listed
@@ -145,13 +149,6 @@ export interface WidgetStoreActions {
      * @param toolId - Tool ID to remove
      */
     unregisterTool: (widgetId: string, toolId: string) => void;
-    /**
-     * Update tool configuration
-     * @param widgetId - Widget ID
-     * @param toolId - Tool ID
-     * @param config - New configuration to merge
-     */
-    updateToolConfig: (widgetId: string, toolId: string, config: Record<string, unknown>) => void;
     /**
      * Set tool enabled state
      * @param widgetId - Widget ID
@@ -159,6 +156,11 @@ export interface WidgetStoreActions {
      * @param enabled - Whether tool should be enabled
      */
     setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) => void;
+    /**
+     * Trigger pipeline re-execution by bumping the registeredTools reference.
+     * @param widgetId - Widget ID
+     */
+    triggerToolPipeline: (widgetId: string) => void;
     /**
      * Execute the tool transformation pipeline
      * Supports both synchronous and asynchronous tools

package/dist/types/widgets/stores/use-widget-selector.d.ts

@@ -0,0 +1,35 @@
+import { WidgetState } from './types';
+/**
+ * Scoped selector hook for reading a single widget's state from the store.
+ *
+ * Consolidates multiple `useWidgetStore(useShallow(...))` calls into a single
+ * subscription per component. The selector receives only this widget's state
+ * (or undefined if not yet registered), and uses shallow comparison to avoid
+ * re-renders when unrelated properties change.
+ *
+ * @param widgetId - The widget ID to subscribe to.
+ * @param selector - A function that extracts the needed properties from the widget state.
+ *   Must be a stable reference (inline arrow is fine due to useCallback wrapping).
+ *
+ * @example
+ * ```tsx
+ * // Before: 4 separate subscriptions
+ * const title = useWidgetStore(useShallow((s) => s.getWidget(id)?.title))
+ * const collapsed = useWidgetStore(useShallow((s) => s.getWidget(id)?.collapsed))
+ * const disabled = useWidgetStore(useShallow((s) => s.getWidget(id)?.disabled))
+ * const isFetching = useWidgetStore(useShallow((s) => s.getWidget(id)?.isFetching))
+ *
+ * // After: 1 subscription
+ * const { title, collapsed, disabled, isFetching } = useWidgetSelector(id, (w) => ({
+ *   title: w?.title, collapsed: w?.collapsed, disabled: w?.disabled, isFetching: w?.isFetching,
+ * }))
+ *
+ * // With extra dependencies (e.g., index prop):
+ * const value = useWidgetSelector(
+ *   id,
+ *   (w) => (w as MyState | undefined)?.data?.[index]?.value,
+ *   [index],
+ * )
+ * ```
+ */
+export declare function useWidgetSelector<T>(widgetId: string, selector: (widget: WidgetState | undefined) => T): T;

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

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

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

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

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

@@ -1,39 +1,60 @@
-import { WidgetStore } from './types';
+import { WidgetStore, WidgetStoreActions } from './types';
 /**
  * Zustand store for managing widget state across the application.
  *
- * This store provides centralized state management for all widget UI components
+ * Provides centralized state management for all widget UI components, including
+ * data/config transformation pipelines via registered tools.
  *
- * @example
+ * **Performance optimizations:**
+ * - `registerTool` skips the store update when structural properties (order, enabled,
+ *   type, disables) haven't changed — only `fn` is updated via direct mutation,
+ *   avoiding a new `registeredTools` array reference and WidgetLoader pipeline cascades.
+ * - `setToolEnabled` skips the store update when the enabled state is already the
+ *   requested value.
+ * - `executeToolPipeline` / `executeConfigPipeline` skip the final `set()` when
+ *   the transformed data/config is referentially identical to what's already in the store.
+ * - Both pipelines support cancellation — newer executions for the same widget
+ *   automatically cancel in-progress ones.
+ *
+ * @example Reading widget state (prefer useWidgetSelector for performance)
  * ```tsx
- * // Import the store
- * import { useWidgetStore } from '@carto/ps-react-ui/widgets'
- *
- * // Use in a component
- * function MyWidget() {
- *   const setWidget = useWidgetStore((state) => state.setWidget)
- *   const widget = useWidgetStore((state) => state.widgets['my-widget'])
- *
- *   useEffect(() => {
- *     setWidget({
- *       id: 'my-widget',
- *       type: 'formula',
- *       title: 'Total Sales',
- *       isLoading: false,
- *       visible: true,
- *       data: { value: 1000, prefix: '$' }
- *     })
- *   }, [setWidget])
- *
- *   return <div>{widget?.data?.value}</div>
+ * import { useWidgetSelector } from '@carto/ps-react-ui/widgets'
+ *
+ * function MyWidget({ id }: { id: string }) {
+ *   const { title, data } = useWidgetSelector(id, (w) => ({
+ *     title: w?.title,
+ *     data: w?.data,
+ *   }))
+ *   return <div>{title}: {JSON.stringify(data)}</div>
  * }
  * ```
  *
- * @example
+ * @example Writing widget state
  * ```tsx
- * // Get widgets by type
- * const getWidgetsByType = useWidgetStore((state) => state.getWidgetsByType)
- * const formulaWidgets = getWidgetsByType('formula')
+ * import { widgetStoreActions } from '@carto/ps-react-ui/widgets'
+ *
+ * const { setWidget } = widgetStoreActions
+ * setWidget('my-widget', { type: 'formula', isLoading: false, data: { value: 1000 } })
  * ```
  */
 export declare const useWidgetStore: import('node_modules/zustand/esm/react.mjs').UseBoundStore<import('node_modules/zustand/esm/vanilla.mjs').StoreApi<WidgetStore>>;
+/**
+ * Stable references to store actions, accessible without creating a subscription.
+ *
+ * Use this instead of `useWidgetStore((state) => state.setWidget)` to avoid
+ * unnecessary subscriber evaluations. Actions are stable functions that never
+ * change, so subscribing to them wastes cycles on every store update.
+ *
+ * @example
+ * ```tsx
+ * import { widgetStoreActions } from '@carto/ps-react-ui/widgets'
+ *
+ * const { setWidget, registerTool } = widgetStoreActions
+ *
+ * useEffect(() => {
+ *   registerTool(id, { id: 'my-tool', order: 10, enabled: true, fn: (d) => d })
+ *   return () => widgetStoreActions.unregisterTool(id, 'my-tool')
+ * }, [id])
+ * ```
+ */
+export declare const widgetStoreActions: WidgetStoreActions;

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

@@ -1,2 +1,13 @@
 import { WidgetSubHeaderProps } from './types';
+/**
+ * Flexible two-slot layout for displaying supplementary widget information such as totals, timestamps, or controls. Uses flexbox with space-between justification.
+ *
+ * @example
+ * ```tsx
+ * <WidgetSubHeader
+ *   slotLeft={<Typography variant="caption">Total: 1,234</Typography>}
+ *   slotRight={<Typography variant="caption">Updated: 2m ago</Typography>}
+ * />
+ * ```
+ */
 export declare function WidgetSubHeader({ slotLeft, slotRight, sx, }: WidgetSubHeaderProps): import("react/jsx-runtime").JSX.Element;

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

@@ -6,11 +6,16 @@ export declare const DEFAULT_ROWS_PER_PAGE_OPTIONS: number[];
 export declare const DEFAULT_COLUMN_ID: null;
 export declare const DEFAULT_DIRECTION: SortDirection;
 /**
- * Default table download configuration
- * Supports PNG export (screenshot) and CSV export (data)
+ * Creates download configuration for table widgets, supporting PNG (screenshot) and CSV (data) exports. CSV output uses column keys as headers and filters out `id` fields.
+ *
+ * @param props - Configuration with `refUI` reference for PNG export.
+ * @returns Array of download items for use with the Download action.
  */
 export declare function tableDownloadConfig({ refUI, }: ConfigProps): TableDownloadConfig;
 /**
- * Default table widget configuration
+ * Returns the default configuration for table widgets with pagination and sorting, including column definitions and local data mode.
+ *
+ * @param columns - Array of column definitions for the table.
+ * @returns Default table widget config.
  */
 export declare function tableConfig(columns?: TableColumn[]): TableWidgetConfig;

package/dist/types/widgets/table/config.test.d.ts

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

package/dist/types/widgets/table/hooks/use-pagination.d.ts

@@ -26,8 +26,16 @@ export interface UsePaginationResult<T> {
     goToPreviousPage: () => void;
 }
 /**
- * Hook for managing table pagination
- * Supports both local (client-side) and remote (server-side) pagination
- * State is persisted in the widget store for the given widgetId
+ * Hook for managing table pagination with support for both local (client-side) and remote (server-side) modes.
+ * State is persisted in the widget store for the given widget ID.
+ *
+ * @param widgetId - The widget ID to persist pagination state under.
+ * @param data - The full data array (used for local pagination and total count fallback).
+ * @returns Pagination state and navigation helpers.
+ *
+ * @example
+ * ```tsx
+ * const { page, setPage, paginatedData, totalPages } = usePagination(widgetId, data)
+ * ```
  */
 export declare function usePagination<T extends TableRow>(widgetId: string, data: T[]): UsePaginationResult<T>;

package/dist/types/widgets/table/hooks/use-selection.d.ts

@@ -24,7 +24,16 @@ export interface UseSelectionResult {
     clearSelection: () => void;
 }
 /**
- * Hook for managing table row selection
- * Selection persists across pagination and is stored in the widget store
+ * Hook for managing table row selection with persistence across pagination.
+ * Selection state is stored in the widget store for the given widget ID.
+ *
+ * @param widgetId - The widget ID to persist selection state under.
+ * @param options - Optional configuration including an `onSelectionChange` callback.
+ * @returns Selection state and control functions (toggle, select, deselect, clear).
+ *
+ * @example
+ * ```tsx
+ * const { selectedIds, isAllSelected, handleSelectRow, clearSelection } = useSelection(widgetId)
+ * ```
  */
 export declare function useSelection(widgetId: string, options?: UseSelectionOptions): UseSelectionResult;

package/dist/types/widgets/table/hooks/use-sort.d.ts

@@ -15,8 +15,16 @@ export interface UseSortResult<T> extends SortState {
     clearSort: () => void;
 }
 /**
- * Hook for managing table sorting
- * Supports both local (client-side) and remote (server-side) sorting
- * State is persisted in the widget store for the given widgetId
+ * Hook for managing table sorting with support for both local (client-side) and remote (server-side) modes.
+ * State is persisted in the widget store for the given widget ID.
+ *
+ * @param widgetId - The widget ID to persist sort state under.
+ * @param data - The data array to sort (for local mode).
+ * @returns Sort state, sorted data, and sort control functions.
+ *
+ * @example
+ * ```tsx
+ * const { sortedData, sortField, sortDirection, handleSort } = useSort(widgetId, data)
+ * ```
  */
 export declare function useSort<T extends TableRow>(widgetId: string, data: T[]): UseSortResult<T>;

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

@@ -3,11 +3,15 @@ export { Row } from './components/row';
 export { Pagination } from './components/pagination';
 export { PaginationActions } from './components/pagination-actions';
 export { Table } from './table-ui';
-export { usePagination, useSort, useSelection } from './hooks';
+export { usePagination } from './hooks/use-pagination';
+export { useSort } from './hooks/use-sort';
+export { useSelection } from './hooks/use-selection';
 export { tableConfig, tableDownloadConfig } from './config';
 export { TableSkeleton } from './skeleton';
 export { sanitizeTableRow, sanitizeTableData } from './serializer';
 export { getCellValue, compareValues, sortData, paginateData } from './helpers';
 export { styles as tableStyles } from './style';
 export type { TableUIProps, TableColumn, TableRow, TableWidgetData, TablePaginationState, SortDirection, SortState, Mode, TableWidgetConfig, TableWidgetState, TableDownloadConfig, TableProps, CellHeaderProps, RowProps, PaginationProps, PaginationActionsProps, } from './types';
-export type { UsePaginationResult, UseSortResult, UseSelectionOptions, UseSelectionResult, } from './hooks';
+export type { UsePaginationResult } from './hooks/use-pagination';
+export type { UseSortResult } from './hooks/use-sort';
+export type { UseSelectionOptions, UseSelectionResult, } from './hooks/use-selection';

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

@@ -75,7 +75,7 @@ export interface TableWidgetConfig {
     /** Enable row selection with checkboxes */
     selectable?: boolean;
     /** Currently selected row IDs */
-    selected: (string | number)[];
+    selected?: (string | number)[];
     /** Pagination and sort mode: local (client-side) or remote (server-side) */
     mode: Mode;
     /** Pagination configuration */

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

@@ -1,5 +1,9 @@
-import { TimeseriesConfig, TimeseriesWidgetConfig, TimeseriesWidgetData } from './types';
-import { DownloadItem } from '../actions';
-import { ConfigProps } from '../loader/types';
-export declare function timeseriesDownloadConfig({ refUI, }: ConfigProps): DownloadItem<TimeseriesWidgetData>[];
+import { TimeseriesConfig, TimeseriesWidgetConfig } from './types';
+export declare const timeseriesDownloadConfig: ({ refUI }: import('../loader').ConfigProps) => import('../actions').DownloadItem<import('../echart').EchartWidgetData>[];
+/**
+ * Generates ECharts configuration for line and area chart widgets over time, with smooth curves, rotated axis labels, and CARTO qualitative color palette.
+ *
+ * @param props - Timeseries configuration including data and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export declare function timeseriesConfig(props: TimeseriesConfig): TimeseriesWidgetConfig;

package/dist/types/widgets/utils/chart-config/download-config.d.ts

@@ -0,0 +1,3 @@
+import { DownloadItem } from '../../actions';
+import { ConfigProps } from '../../loader/types';
+export declare function createChartDownloadConfig<TData>(csvModifier: (data: TData) => string[][]): ({ refUI }: ConfigProps) => DownloadItem<TData>[];

package/dist/types/widgets/{_shared → utils}/chart-config/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * Shared utilities for chart widget configuration
  */
+export { defaultFormatter, defaultLabelFormatter } from '../formatter';
 export { createChartWidgetConfig } from './config-factory';
 export type { ChartWidgetBaseConfig, CreateChartWidgetConfigParams, } from './config-factory';
 export { flattenObjectArrayToCSV, scatterplotDataToCSV } from './csv-modifiers';
-export { buildLegendConfig, buildGridConfig, createTooltipPositioner, createAxisLabelFormatter, createTooltipFormatter, applyXAxisFormatter, applyYAxisFormatter, niceNum, } from './option-builders';
+export { buildLegendConfig, buildGridConfig, createTooltipPositioner, createAxisLabelFormatter, createTooltipFormatter, applyXAxisFormatter, applyYAxisFormatter, niceNum, buildSeriesLabelConfig, buildHistogramSeriesLabelConfig, } from './option-builders';
+export { createChartDownloadConfig } from './download-config';

package/dist/types/widgets/{_shared → utils}/chart-config/option-builders.d.ts

@@ -1,6 +1,6 @@
 import { Theme } from '@mui/material';
 import { LegendComponentOption } from 'echarts';
-import { CallbackDataParams, TopLevelFormatterParams } from '../../../../node_modules/echarts/types/dist/shared';
+import { CallbackDataParams, TopLevelFormatterParams } from 'echarts/types/dist/shared';
 /**
  * Shared EChart configuration builders for chart widgets
  */
@@ -14,10 +14,15 @@ export declare function niceNum(value: number): number;
 /**
  * Builds standard legend configuration for chart widgets
  *
- * @param hasLegend - Whether to show the legend
+ * @param params - Legend configuration parameters
+ * @param params.hasLegend - Whether to show the legend
+ * @param params.labelFormatter - Optional formatter for legend item names
  * @returns Legend configuration object
  */
-export declare function buildLegendConfig(hasLegend: boolean): LegendComponentOption;
+export declare function buildLegendConfig({ hasLegend, labelFormatter, }: {
+    hasLegend: boolean;
+    labelFormatter?: (value: string | number) => string | number;
+}): LegendComponentOption;
 /**
  * Builds standard grid configuration with legend-aware spacing
  *
@@ -49,16 +54,16 @@ export declare function createTooltipPositioner(theme: Theme): (point: [number,
  */
 export declare function createAxisLabelFormatter(formatter?: (value: number) => string): ((value: number) => string) | undefined;
 /**
- * Applies formatter to xAxis configuration
- * Only applies to single axis objects (not arrays) with type 'value'
+ * Applies labelFormatter to xAxis configuration
+ * Applies to any xAxis regardless of axis type (category, value, etc.)
  *
  * @param xAxis - Existing xAxis configuration
- * @param formatter - Optional formatter function from widget config
- * @returns Updated xAxis configuration or undefined if no changes needed
+ * @param labelFormatter - Optional labelFormatter function from widget config
+ * @returns Updated xAxis configuration
  */
-export declare function applyXAxisFormatter(xAxis: unknown, formatter?: (value: number) => string): {
+export declare function applyXAxisFormatter(xAxis: unknown, formatter?: (value: string | number) => string | number): {
     axisLabel: {
-        formatter: ((value: number) => string) | undefined;
+        formatter: ((value: string | number) => string) | undefined;
     };
     type?: string;
 };
@@ -90,3 +95,30 @@ export declare function createTooltipFormatter(callback: (item: CallbackDataPara
     marker: string;
     value: string | number;
 }): (params: TopLevelFormatterParams) => string;
+/**
+ * Builds a series `label` config that applies formatter to the data value
+ * extracted from a dataset row using ECharts encode/dimensionNames.
+ *
+ * Does not set `show` — labels remain hidden by default per ECharts defaults.
+ *
+ * @param formatter - Optional numeric value formatter
+ * @param encodeKey - The encode dimension key to extract ('y' for vertical charts, 'x' for horizontal)
+ */
+export declare function buildSeriesLabelConfig(formatter?: (value: number) => string, encodeKey?: string): {
+    label: {
+        formatter: (params: CallbackDataParams) => string;
+    };
+} | object;
+/**
+ * Builds a series `label` config that applies formatter to a raw numeric value.
+ * Used by histogram where series data is number[] (not datasets).
+ *
+ * Does not set `show` — labels remain hidden by default per ECharts defaults.
+ *
+ * @param formatter - Optional numeric value formatter
+ */
+export declare function buildHistogramSeriesLabelConfig(formatter?: (value: number) => string): {
+    label: {
+        formatter: (params: CallbackDataParams) => string;
+    };
+} | object;

package/dist/types/widgets/utils/chart-config/option-builders.test.d.ts

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

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

@@ -0,0 +1,2 @@
+export declare const defaultFormatter: (value: number) => string;
+export declare const defaultLabelFormatter: (value: string | number) => string | number;

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

@@ -0,0 +1,7 @@
+export { defaultFormatter, defaultLabelFormatter } from './formatter';
+export { createChartWidgetConfig } from './chart-config';
+export type { ChartWidgetBaseConfig, CreateChartWidgetConfigParams, } from './chart-config';
+export { flattenObjectArrayToCSV, scatterplotDataToCSV } from './chart-config';
+export { buildLegendConfig, buildGridConfig, createTooltipPositioner, createAxisLabelFormatter, createTooltipFormatter, applyXAxisFormatter, applyYAxisFormatter, niceNum, } from './chart-config';
+export { baseSkeletonStyles } from './skeleton';
+export { createChartDownloadConfig } from './chart-config';

package/dist/types/widgets/wrapper/components/actions.d.ts

@@ -1,2 +1,5 @@
 import { WrapperActionsProps } from '../types';
+/**
+ * Renders action buttons in the widget wrapper header. Each action click event is stopped from propagating to the accordion.
+ */
 export declare function Actions({ actions }: WrapperActionsProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/wrapper/components/options.d.ts

@@ -1,2 +1,5 @@
 import { WrapperOptionsProps } from '../types';
+/**
+ * Renders a dropdown options menu in the widget wrapper header, triggered by a vertical ellipsis icon button.
+ */
 export declare function Options({ labels, options, }: WrapperOptionsProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/wrapper/components/title.d.ts

@@ -1,5 +1,8 @@
 import { ReactNode } from 'react';
 import { WrapperOptionsProps } from '../types';
+/**
+ * Renders the widget title text inside the wrapper header with smart tooltip support for truncated titles.
+ */
 export declare function Title({ label, children, }: {
     children: ReactNode;
     label?: NonNullable<WrapperOptionsProps['labels']>['title'];

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

@@ -1,2 +1,16 @@
 import { WrapperUIProps } from './types';
+/**
+ * Presentational wrapper component that renders the widget accordion UI with title, actions, options menu, and loading indicator. For uncontrolled usage without automatic widget store synchronization, use this instead of WidgetWrapper.
+ *
+ * @example
+ * ```tsx
+ * <WrapperUI
+ *   id="my-widget"
+ *   actions={[<Download key="download" id="my-widget" />]}
+ *   onChangeCollapsed={(e, collapsed) => console.log(collapsed)}
+ * >
+ *   <div>Content</div>
+ * </WrapperUI>
+ * ```
+ */
 export declare function WrapperUI({ children, id, actions, sx, labels, options, onChangeCollapsed, }: WrapperUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,2 +1,16 @@
 import { WrapperProps } from './types';
+/**
+ * Container component providing a collapsible header with title, action buttons, and options menu for widgets. Syncs collapse, disabled, and title state with the widget store.
+ *
+ * @example
+ * ```tsx
+ * <WidgetWrapper
+ *   id="my-widget"
+ *   title="Sales Overview"
+ *   actions={[<Download key="download" id="my-widget" items={downloads} />]}
+ * >
+ *   {children}
+ * </WidgetWrapper>
+ * ```
+ */
 export declare function WidgetWrapper({ id, title, defaultCollapsed, disabled, sx, actions, options, labels, children, onChangeCollapsed, }: WrapperProps): import("react/jsx-runtime").JSX.Element;