@carto/ps-react-ui 4.4.1 → 4.4.3

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

@@ -1,6 +1,35 @@
 import { EchartOptionsProps } from './types';
 import { Theme } from '@mui/material';
+/**
+ * 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;
@@ -68,6 +97,12 @@ export declare function getEChartZoomConfig({ start, end }?: {
         orientation?: undefined;
     })[];
 };
+/**
+ * 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;
@@ -82,6 +117,12 @@ export declare function getEChartBrushConfig({ brushType, brushMode, xAxisIndex
         xAxisIndex: number;
     };
 };
+/**
+ * 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';
+/**
+ * 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-runtime").JSX.Element | null | undefined;

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

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

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

@@ -1,2 +1,5 @@
 import { ValueProps } from '../types';
+/**
+ * Renders the prefix content (e.g., currency symbol) before a formula value, if defined in the data item.
+ */
 export declare function Prefix({ id, index, ...props }: ValueProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,2 +1,5 @@
 import { RowProps } from '../types';
+/**
+ * Iterates over the widget's data items and renders a row for each one using render props.
+ */
 export declare function Row(props: RowProps): import("react/jsx-runtime").JSX.Element[] | undefined;

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

@@ -1,2 +1,5 @@
 import { ValueProps } from '../types';
+/**
+ * Renders a colored avatar badge showing the first letter of the series name for multi-value formula widgets.
+ */
 export declare function Series({ id, index }: Pick<ValueProps, 'id' | 'index'>): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,2 +1,5 @@
 import { ValueProps } from '../types';
+/**
+ * Renders the suffix content (e.g., unit label) after a formula value, if defined in the data item.
+ */
 export declare function Suffix({ id, index, ...props }: ValueProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,2 +1,5 @@
 import { ValueProps } from '../types';
+/**
+ * Displays the formatted numeric value for a formula widget data item, applying the widget's formatter and color.
+ */
 export declare function Value({ id, index, ...props }: ValueProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,4 +1,15 @@
 import { ConfigProps } from '../loader/types';
 import { FormulaDownloadConfig, FormulaWidgetConfig } from './types';
+/**
+ * Creates download configuration for formula widgets, supporting PNG (screenshot) and CSV (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 formulaDownloadConfig({ refUI, }: ConfigProps): FormulaDownloadConfig;
+/**
+ * Returns the default configuration for formula (single or multiple numeric value) widgets.
+ *
+ * @returns Default formula widget config with empty series.
+ */
 export declare function formulaConfig(): FormulaWidgetConfig;

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

@@ -1,2 +1,5 @@
 import { FormulaUIProps } from './types';
+/**
+ * Renders a formula widget displaying one or more KPI values with optional prefixes, suffixes, and series indicators.
+ */
 export declare function FormulaUI(props: FormulaUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,21 @@
-import { HistogramConfig, HistogramWidgetConfig, HistogramWidgetData } from './types';
+import { HistogramConfig, HistogramWidgetConfig } from './types';
 import { DownloadItem } from '../actions';
 import { ConfigProps } from '../loader/types';
-export declare function histogramDownloadConfig({ refUI, }: ConfigProps): DownloadItem<HistogramWidgetData>[];
+export interface HistogramDownloadConfigProps extends ConfigProps {
+    ticks: number[];
+    labelFormatter?: (value: string | number) => string | number;
+}
+export declare function histogramDataToCSV(data: number[][], ticks: number[], labelFormatter?: (value: string | number) => string | number): string[][];
+export declare function histogramDownloadConfig({ refUI, ticks, labelFormatter, }: HistogramDownloadConfigProps): DownloadItem<number[][]>[];
+/**
+ * Generates ECharts configuration for distribution histogram widgets with
+ * adjacent bars (minimal gap) and axis formatting styled with the CARTO theme.
+ *
+ * Accepts raw `number[][]` data and `ticks` boundaries. The ticks and
+ * `labelFormatter` are used to create the x-axis category labels; the raw
+ * numeric data is embedded directly in each series.
+ *
+ * @param props - Histogram configuration including raw data, ticks, and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export declare function histogramConfig(props: HistogramConfig): HistogramWidgetConfig;

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

@@ -1,3 +1,4 @@
 export type { HistogramConfig, HistogramWidgetConfig, HistogramWidgetData, HistogramWidgetState, } from './types';
-export { histogramConfig, histogramDownloadConfig } from './config';
+export type { HistogramDownloadConfigProps } from './config';
+export { histogramConfig, histogramDataToCSV, histogramDownloadConfig, } from './config';
 export { HistogramSkeleton } from './skeleton';

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

@@ -1,9 +1,12 @@
-import { EchartWidgetData, EchartWidgetState } from '../echart';
+import { EchartWidgetState } from '../echart';
 import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types';
 import { ConfigProps } from '../loader';
-export type HistogramWidgetData = EchartWidgetData;
+export type HistogramWidgetData = number[][];
 export type HistogramWidgetState = EchartWidgetState;
 export type HistogramWidgetConfig = EchartWidgetProps & {
     type: 'histogram';
 };
-export type HistogramConfig = ConfigProps & EchartWidgetOptionProps<HistogramWidgetData>;
+export type HistogramConfig = ConfigProps & Pick<EchartWidgetOptionProps<unknown>, 'theme' | 'formatter' | 'labelFormatter'> & {
+    data?: number[][];
+    ticks: number[];
+};

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

@@ -1,2 +1,24 @@
 import { WidgetLoaderProps } from './types';
+/**
+ * Foundation component for all widgets that manages state initialization, synchronization with the widget store, and data transformation pipeline execution.
+ *
+ * @remarks
+ * The WidgetLoader is stateless -- it manages data flow but does not render any UI. Always wrap it with WidgetWrapper for consistent widget appearance.
+ *
+ * @example
+ * ```tsx
+ * <WidgetLoader
+ *   id="sales-chart"
+ *   type="bar"
+ *   data={data}
+ *   isLoading={false}
+ *   isFetching={false}
+ *   config={barConfig({ data })}
+ * >
+ *   <WidgetWrapper id="sales-chart" title="Sales">
+ *     <Echart id="sales-chart" />
+ *   </WidgetWrapper>
+ * </WidgetLoader>
+ * ```
+ */
 export declare function WidgetLoader<T extends object = Record<string, unknown>>(props: WidgetLoaderProps<T>): import('react').ReactNode;

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

@@ -4,9 +4,32 @@
  */
 export type ConfigOrFn<TConfig, TData = unknown> = Partial<TConfig> | ((baseConfig: TConfig, data: TData) => Partial<TConfig>);
 /**
- * Resolves a config that may be either an object or a function.
- * If it's a function, calls it with baseConfig and data.
- * If it's an object (or undefined), returns it as-is.
+ * Resolves a widget config that may be either a partial object or a function receiving the computed base config and data. If it is a function, calls it with `baseConfig` and `data`; otherwise returns the value as-is.
+ *
+ * @param config - The config object or function to resolve.
+ * @param baseConfig - The computed base configuration.
+ * @param data - The widget data.
+ * @returns Resolved partial config, or undefined.
+ *
+ * @example
+ * ```tsx
+ * const resolved = resolveConfig(
+ *   (base, data) => ({ maxItems: base.maxItems + 5 }),
+ *   baseConfig,
+ *   widgetData,
+ * )
+ * ```
  */
 export declare function resolveConfig<TConfig, TData>(config: ConfigOrFn<TConfig, TData> | undefined, baseConfig: TConfig, data: TData): Partial<TConfig> | undefined;
+/**
+ * Deep-merges two partial widget config objects using `deepmerge`, with arrays replaced rather than concatenated.
+ *
+ * @param options - A tuple of two partial configs to merge (base and override).
+ * @returns The merged config object.
+ *
+ * @example
+ * ```tsx
+ * const finalConfig = mergeWidgetConfig(baseConfig, resolvedConfig)
+ * ```
+ */
 export declare function mergeWidgetConfig<T>(...options: [Partial<T> | undefined, Partial<T> | undefined]): T;

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

@@ -1,4 +1,14 @@
 import { DownloadItem } from '../actions';
 import { MarkdownWidgetConfig, MarkdownWidgetData } from './types';
+/**
+ * Creates download configuration for markdown widgets, supporting CSV export of text content. Does not require `refUI` since it only exports text.
+ *
+ * @returns Array of download items for use with the Download action.
+ */
 export declare function markdownDownloadConfig(): DownloadItem<MarkdownWidgetData>[];
+/**
+ * Returns the default configuration for markdown content display widgets.
+ *
+ * @returns Default markdown widget config (empty object).
+ */
 export declare function markdownConfig(): MarkdownWidgetConfig;

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

@@ -1,2 +1,9 @@
 import { MarkdownComponentProps } from './types';
+/**
+ * Presentational component that renders a Markdown string as MUI-styled HTML using react-markdown.
+ *
+ * @remarks
+ * Maps Markdown elements (headings, paragraphs, links, lists) to MUI Typography and Link components.
+ * Custom component overrides can be passed via the `overrides` prop.
+ */
 export declare function MarkdownUI({ children, overrides }: MarkdownComponentProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,2 +1,5 @@
 import { MarkdownUIProps } from './types';
+/**
+ * Stateful markdown widget component that reads content from the widget store and renders it as formatted rich text.
+ */
 export declare function Markdown({ id }: MarkdownUIProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,2 +1,12 @@
 import { WidgetNoteProps } from './types';
+/**
+ * Displays text content with markdown support and automatic show more/less functionality for long content. Automatically detects content exceeding 3 lines and shows an expand/collapse button.
+ *
+ * @example
+ * ```tsx
+ * <WidgetNote>
+ *   {"**Important:** This data is from Q4 2024."}
+ * </WidgetNote>
+ * ```
+ */
 export declare function WidgetNote({ children, labels, }: WidgetNoteProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,5 +1,9 @@
-import { PieConfig, PieWidgetConfig, PieWidgetData } from './types';
-import { DownloadItem } from '../actions';
-import { ConfigProps } from '../loader/types';
-export declare function pieDownloadConfig({ refUI, }: ConfigProps): DownloadItem<PieWidgetData>[];
+import { PieConfig, PieWidgetConfig } from './types';
+export declare const pieDownloadConfig: ({ refUI }: import('../loader').ConfigProps) => import('../actions').DownloadItem<import('../echart').EchartWidgetData>[];
+/**
+ * Generates ECharts configuration for pie and donut chart widgets. Falls back to a horizontal bar layout when multiple data series are provided.
+ *
+ * @param props - Pie chart configuration including data and theme.
+ * @returns Widget config with ECharts option object.
+ */
 export declare function pieConfig(props: PieConfig): PieWidgetConfig;

package/dist/types/widgets/range/components/range-item.d.ts

@@ -1,2 +1,5 @@
 import { RangeItemProps } from '../types';
+/**
+ * Renders a single range slider with editable min/max text inputs, reading its configuration from the widget store.
+ */
 export declare function RangeItem({ id, index }: RangeItemProps): import("react/jsx-runtime").JSX.Element | null;

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/types.d.ts

@@ -29,6 +29,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;
 }

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

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;