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

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

@@ -1,10 +1,16 @@
 import { RelativeDataProps } from './types';
 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

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

@@ -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/zoom-toggle/zoom-toggle.d.ts

@@ -6,6 +6,10 @@ export declare const ZOOM_TOGGLE_TOOL_ID = "zoom-toggle";
  * 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.
  *

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 '../loader/types';
-export declare function barDownloadConfig({ refUI, }: ConfigProps): DownloadItem<BarWidgetData>[];
+import { BarConfig, BarWidgetConfig } from './types';
+export declare const barDownloadConfig: ({ refUI }: import('../loader').ConfigProps) => import('../actions').DownloadItem<import('../echart').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/category/category-ui.d.ts

@@ -1,2 +1,5 @@
 import { CategoryUIProps } from './types';
+/**
+ * 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-runtime").JSX.Element | null;

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

@@ -4,4 +4,7 @@ export interface CategoryBarProps {
     color: string;
     selected?: boolean;
 }
+/**
+ * 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-runtime").JSX.Element;

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

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

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

@@ -5,7 +5,11 @@ export interface CategoryRowMultiProps {
     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-runtime").JSX.Element;

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

@@ -3,4 +3,7 @@ export interface CategoryRowOtherProps {
     otherLabel?: string;
     otherCountLabel?: string;
 }
+/**
+ * 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-runtime").JSX.Element;

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

@@ -5,7 +5,11 @@ export interface CategoryRowSingleProps {
     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-runtime").JSX.Element;

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

@@ -4,6 +4,17 @@ import { CategoryWidgetConfig, CategoryWidgetData, CategorySeriesConfig } from '
 interface CategoryDownloadConfigProps extends ConfigProps {
     series?: CategorySeriesConfig[];
 }
+/**
+ * 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 { CategoryBar } from './components/category-bar';
+export type { CategoryBarProps } from './components/category-bar';
+export { CategoryRowSingle } from './components/category-row-single';
+export type { CategoryRowSingleProps } from './components/category-row-single';
+export { CategoryRowMulti } from './components/category-row-multi';
+export type { CategoryRowMultiProps } from './components/category-row-multi';
+export { CategoryRowOther } from './components/category-row-other';
+export type { CategoryRowOtherProps } from './components/category-row-other';
+export { CategoryLegend } from './components/category-legend';
+export type { CategoryLegendProps } from './components/category-legend';
 export type { CategoryUIProps, CategoryWidgetData, CategoryWidgetState, CategoryWidgetConfig, CategoryDownloadConfig, CategoryDataItem, CategorySeriesConfig, CategoryLabels, } from './types';

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

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

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

@@ -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';
+/**
+ * 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-runtime").JSX.Element;

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

@@ -1,2 +1,8 @@
 import { EchartProps } from './types';
+/**
+ * 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-runtime").JSX.Element | null;

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

@@ -1,2 +1,9 @@
 import { EchartOptionsProps, EchartWidgetOptionProps } from './types';
+/**
+ * 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 { Ref, RefObject } from 'react';
 import { theme as CartoTheme } from '@carto/meridian-ds/theme';
 import type * as echarts from 'echarts';
 export type EchartOptionsProps = EChartsOption;
@@ -21,14 +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,7 +1,36 @@
 import { EchartOptionsProps } from './types';
 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, bottomOffset, }?: {
@@ -68,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/echart/utils.test.d.ts

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

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

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

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

@@ -2,8 +2,9 @@ import { WidgetNoDataProps } from './types';
 /**
  * NoData wrapper component that displays empty state UI when widget has no data
  *
- * Integrates with widget store to check loading/fetching state and data availability.
- * Works in conjunction with SkeletonLoader for complete loading/empty state handling.
+ * Integrates with widget store to check loading/fetching state and source data availability.
+ * Uses `sourceData` (pre-pipeline data) instead of `data` (post-pipeline) to distinguish
+ * "API returned nothing" from "pipeline tools filtered everything out".
  *
  * @example Basic usage
  * ```tsx

package/dist/types/widgets/no-data/types.d.ts

@@ -54,7 +54,11 @@ export interface WidgetNoDataProps {
      */
     description?: string;
     /**
-     * Optional custom function to determine if data is empty
+     * Optional custom function to determine if source data is empty.
+     * Receives `sourceData` (pre-pipeline data from the API), not `data`
+     * (post-pipeline). This allows distinguishing "API returned nothing"
+     * from "pipeline tools filtered everything out".
+     *
      * If not provided, uses default isEmpty logic that handles:
      * - null/undefined → empty
      * - [] (empty array) → empty

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;