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

package/dist/types/chat/containers/styles.d.ts

@@ -29,7 +29,7 @@ export declare const styles: {
     footer: {
         maxWidth: number;
         margin: string;
-        '& .MuiInputBase-multiline.MuiInputBase-sizeSmall textarea': {
+        '&.MuiFilledInput-root.MuiInputBase-multiline.MuiInputBase-sizeSmall textarea': {
             resize: "none";
             maxHeight: string;
             overflowY: "auto !important";
@@ -52,18 +52,14 @@ export declare const styles: {
         px: number;
         display: "flex";
         flexDirection: "column";
-        '--chat-border-color': ({ palette }: Theme) => string;
-        borderTop: string;
-        borderBottom: string;
-        '@supports (animation-timeline: scroll())': {
-            animation: `${{
-                name: string;
-                styles: string;
-                anim: 1;
-                toString: () => string;
-            } & string} linear both`;
-            animationTimeline: "scroll(self)";
-        };
+        borderTopWidth: string;
+        borderTopStyle: "solid";
+        borderBottomWidth: string;
+        borderBottomStyle: "solid";
+    };
+    sentinel: {
+        height: string;
+        flexShrink: number;
     };
     jumpToLatestWrapper: {
         position: "sticky";
@@ -74,20 +70,7 @@ export declare const styles: {
         zIndex: number;
     };
     jumpToLatest: {
-        opacity: number;
-        pointerEvents: "none";
-        '@supports (animation-timeline: scroll())': {
-            animation: `${{
-                name: string;
-                styles: string;
-                anim: 1;
-                toString: () => string;
-            } & string} linear both`;
-            animationTimeline: "scroll(nearest)";
-        };
-        '@supports not (animation-timeline: scroll())': {
-            display: "none";
-        };
+        transition: "opacity 0.2s";
     };
     starter: {
         display: "flex";

package/dist/types/chat/feedback/chat-tool-code-area.d.ts

@@ -1,4 +1,2 @@
 import { ChatToolCodeAreaProps } from '../types';
-export declare function ChatToolCodeArea({ content, title, isError, labels, sx, }: ChatToolCodeAreaProps & {
-    isError?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
+export declare function ChatToolCodeArea({ content, title, isError, labels, sx, }: ChatToolCodeAreaProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/chat/index.d.ts

@@ -1,4 +1,4 @@
-export type { ChatSxProps, ChatErrorAction, ChatUserMessageProps, ChatAgentMessageProps, ChatErrorMessageProps, ChatSuggestionButtonProps, ChatThinkingProps, ChatLoaderProps, ChatContentProps, ChatHeaderProps, ChatFooterProps, ChatStarterItem, ChatStarterProps, ChatActionsContainerProps, ChatRatingActionProps, ChatToolItem, ChatToolTraceProps, ChatToolCodeAreaProps, ChatToolFullViewDialogProps, ChatToolGroupProps, } from './types';
+export type { ChatSxProps, ChatErrorAction, ChatUserMessageProps, ChatAgentMessageProps, ChatErrorMessageProps, ChatSuggestionButtonProps, ChatThinkingProps, ChatLoaderProps, ChatContentProps, ChatContentRef, ChatHeaderProps, ChatFooterProps, ChatStarterItem, ChatStarterProps, ChatRatingActionProps, ChatToolItem, ChatToolTraceProps, ChatToolCodeAreaProps, ChatToolFullViewDialogProps, ChatToolGroupProps, } from './types';
 export { CHAT_MAX_WIDTH, CHAT_SCROLL_DELAY, CHAT_DIVIDER_DELAY, CHAT_TOOL_CODE_AREA_MAX_HEIGHT, } from './const';
 export { useTypewriter } from './use-typewriter';
 export { ChatUserMessage } from './bubbles/chat-user-message';

package/dist/types/chat/types.d.ts

@@ -38,10 +38,32 @@ export interface ChatLoaderProps extends ChatSxProps {
 }
 export interface ChatContentProps extends ChatSxProps {
     children: ReactNode;
+    /**
+     * Smooth-scrolls to the bottom whenever new content is added — but only if
+     * the user was already at (or near) the bottom. Readers who scrolled up to
+     * revisit older messages are left alone. Defaults to `true`; pass `false`
+     * to opt out and manage scroll yourself via the ref.
+     */
+    autoScroll?: boolean;
     labels?: {
         jumpToLatest?: string;
     };
 }
+/**
+ * Imperative handle exposed by `ChatContent` via `ref`. Use it to drive scroll
+ * from the parent — for example, calling `scrollToBottom()` when a new agent
+ * message arrives.
+ */
+export interface ChatContentRef {
+    /** Smooth-scrolls the content area to the bottom. */
+    scrollToBottom: () => void;
+    /** Smooth-scrolls the content area to the top. */
+    scrollToTop: () => void;
+    /** `true` when the content area is scrolled to (or near) its bottom edge. */
+    isAtBottom: boolean;
+    /** `true` when the content area is scrolled to (or near) its top edge. */
+    isAtTop: boolean;
+}
 export interface ChatHeaderProps extends ChatSxProps {
     leftSlot?: ReactNode;
     title: ReactNode;
@@ -49,17 +71,28 @@ export interface ChatHeaderProps extends ChatSxProps {
     onClose?: () => void;
 }
 export interface ChatFooterProps extends ChatSxProps {
+    /** Current value of the chat message area. */
     value: string;
+    /** Called with the new textarea value on every keystroke. */
     onChange: (value: string) => void;
+    /** Called when the send button is clicked or Enter is pressed (without Shift). */
     onSend: () => void;
+    /** Called when the stop button is clicked. Only shown while `isGenerating` is true. */
     onStop?: () => void;
+    /** When true, swaps the send button for a stop button and disables the textarea. */
     isGenerating?: boolean;
+    /** Disables the textarea and both send/stop buttons. */
     disabled?: boolean;
+    /** Placeholder text for the textarea. Defaults to `'Type a message...'`. */
     placeholder?: string;
+    /** Accessible labels for the send and stop buttons (used as `aria-label`). */
     labels?: {
+        /** Defaults to `'Send'`. */
         send?: string;
+        /** Defaults to `'Stop'`. */
         stop?: string;
     };
+    /** Helper text rendered under the input. Defaults to an AI disclaimer; pass `null` to hide. */
     caption?: ReactNode;
 }
 export interface ChatStarterItem {
@@ -74,9 +107,6 @@ export interface ChatStarterProps extends ChatSxProps {
     size?: 'small' | 'medium';
     onSelect?: (prompt: string) => void;
 }
-export interface ChatActionsContainerProps extends ChatSxProps {
-    children: ReactNode;
-}
 export interface ChatRatingActionProps {
     onRatingChange?: (rating: 'up' | 'down' | null) => void;
     rating?: 'up' | 'down' | null;
@@ -126,6 +156,8 @@ export interface ChatToolCodeAreaProps extends ChatSxProps {
     content: string;
     /** Label for the full view dialog title */
     title?: string;
+    /** Render with error styling (red left border, tinted background) */
+    isError?: boolean;
     labels?: {
         fullView?: string;
     };

package/dist/types/components/basemaps/basemaps.d.ts

@@ -1,3 +1,23 @@
 import { BasemapsUIProps } from './types';
 import { JSX } from 'react';
+/**
+ * Provides an interactive basemap selector with responsive drawer, grouping support, and customizable positioning.
+ *
+ * @remarks
+ * This is an uncontrolled component focused on UI presentation. Typically used with the `BasemapsControls` HOC from `@carto/ps-react-maps` for automatic state management.
+ *
+ * @example
+ * ```tsx
+ * <BasemapsControls mapId={mapId}>
+ *   {({ basemap, setBasemap }) => (
+ *     <BasemapsUI
+ *       options={basemapOptions}
+ *       selected={basemap}
+ *       onChange={setBasemap}
+ *       position="bottom-right"
+ *     />
+ *   )}
+ * </BasemapsControls>
+ * ```
+ */
 export declare function BasemapsUI({ options, labels: _labels, position, selected, onChange, TooltipProps, }: BasemapsUIProps): JSX.Element;

package/dist/types/components/geolocation-controls/geolocation-controls.d.ts

@@ -1,3 +1,14 @@
 import { GeolocationControlProps } from './types';
 import { JSX } from 'react';
+/**
+ * Provides a seamless interface for accessing device location through the browser's Geolocation API, with permission handling, continuous tracking, and error management.
+ *
+ * @example
+ * ```tsx
+ * <GeolocationControls
+ *   onChange={(coords) => console.log(coords.latitude, coords.longitude)}
+ *   onError={(error) => console.error(error.message)}
+ * />
+ * ```
+ */
 export declare function GeolocationControls({ disabled, labels, PaperProps, TooltipProps, watch, onChange, onError, }: GeolocationControlProps): JSX.Element;

package/dist/types/components/lasso-tool/lasso-tool-inline.d.ts

@@ -1,3 +1,20 @@
 import { JSX } from 'react';
 import { LassoToolsInlineComponentProps } from './types';
+/**
+ * Provides an inline layout variant of the lasso tools interface with toggle button groups for mode selection and inline chip management for spatial filters.
+ *
+ * @example
+ * ```tsx
+ * <LassoToolsInlineUI
+ *   enabled={enabled}
+ *   values={spatialFilters}
+ *   modes={modes}
+ *   modesMapping={modesMapping}
+ *   modeSelected={modeSelected}
+ *   onChangeMode={setModeSelected}
+ *   onChipToggle={handleChipToggle}
+ *   onDelete={handleDelete}
+ * />
+ * ```
+ */
 export declare function LassoToolsInlineUI({ enabled, values, chipProps, labels, modes, modesMapping, modeSelected, BoxProps: { sx, ...BoxProps }, onChipToggle, onDelete, onChangeMode, onAllChipToggle, onAllDelete, }: LassoToolsInlineComponentProps): JSX.Element;

package/dist/types/components/lasso-tool/lasso-tool.d.ts

@@ -1,6 +1,27 @@
 import { JSX } from 'react';
 import { PickDeep } from 'type-fest';
 import { LassoToolsComponentProps, OptionsChildrenProps } from './types';
+/**
+ * Provides a comprehensive floating interface for spatial selection and drawing operations on maps, supporting polygon, rectangle, circle, freehand lasso, and edit modes.
+ *
+ * @remarks
+ * Supports customizable slots for action, options, chips, and secondary actions via compound component pattern (e.g., `LassoToolsUI.Action`, `LassoToolsUI.Chips`).
+ *
+ * @example
+ * ```tsx
+ * <LassoToolsUI
+ *   enabled={enabled}
+ *   values={spatialFilters}
+ *   modes={modes}
+ *   modesMapping={modesMapping}
+ *   modeSelected={modeSelected}
+ *   onActionToggle={setEnabled}
+ *   onChangeMode={setModeSelected}
+ *   onChipToggle={handleChipToggle}
+ *   onDelete={handleDelete}
+ * />
+ * ```
+ */
 export declare function LassoToolsUI({ enabled, values, actionProps, chipProps, labels, modes, modesMapping, modeSelected, PaperProps: { sx, ...PaperProps }, onActionToggle, onChipToggle, onDelete, onChangeMode, onAllChipToggle, onAllDelete, ChipsSlot, ActionSlot, SecondaryActionsSlot, OptionsSlot, }: LassoToolsComponentProps): JSX.Element;
 export declare namespace LassoToolsUI {
     var Action: ({ modes, modesMapping, modeSelected, actionProps, enabled, labels, onActionToggle, }: Partial<Omit<LassoToolsComponentProps, "ChipsSlot" | "ActionsSlot" | "OptionsSlot" | "SecondaryActionsSlot">> & {

package/dist/types/components/list-data/list-data.d.ts

@@ -1,3 +1,19 @@
 import { JSX } from 'react';
 import { ListDataProps } from './types';
+/**
+ * Displays structured data in an accessible list format with expandable views, interactive selection, tooltips, and loading states.
+ *
+ * @example
+ * ```tsx
+ * <ListDataUI
+ *   data={[
+ *     { id: '1', label: 'Population', value: '8.4M' },
+ *     { id: '2', label: 'Median Age', value: '32 years' },
+ *   ]}
+ *   maxItems={3}
+ *   onItemClick={(item) => setSelectedId(item.id)}
+ *   selectedItemId={selectedId}
+ * />
+ * ```
+ */
 export declare function ListDataUI({ data, isLoading, maxItems, labels, showDivider, selectedItemId, tooltipProps, onExpand, onItemClick, }: ListDataProps): JSX.Element;

package/dist/types/components/measurement-tools/measurement-tools.d.ts

@@ -1,3 +1,23 @@
 import { JSX } from 'react';
 import { MeasurementToolsComponentProps } from './types';
+/**
+ * Provides a measurement interface for calculating distances, areas, and buffers on maps with support for metric and imperial unit systems and real-time unit conversion.
+ *
+ * @example
+ * ```tsx
+ * <MeasurementToolsUI
+ *   enabled={enabled}
+ *   value={measurementValue}
+ *   modes={DEFAULT_MEASUREMENT_TOOLS_MODES}
+ *   units={DEFAULT_MEASUREMENT_TOOLS_UNITS}
+ *   modesMapping={DEFAULT_MEASUREMENT_TOOLS_MODES_MAPPING}
+ *   unitsMapping={DEFAULT_MEASUREMENT_TOOLS_UNITS_MAPPING}
+ *   modeSelected={mode}
+ *   unitSelected={unit}
+ *   onActionToggle={setEnabled}
+ *   onChangeMode={setMode}
+ *   onChangeUnit={setUnit}
+ * />
+ * ```
+ */
 export declare function MeasurementToolsUI({ enabled, actionProps, labels, modes, modesMapping, unitsMapping, modeSelected, PaperProps: { sx, ...PaperProps }, units, unitSelected, onActionToggle, onChangeMode, onChangeUnit, }: MeasurementToolsComponentProps): JSX.Element;

package/dist/types/components/smart-tooltip/smart-tooltip.d.ts

@@ -1,5 +1,22 @@
 import { TooltipProps } from '@mui/material';
 import { JSX, Ref } from 'react';
+/**
+ * An intelligent tooltip wrapper that automatically detects text overflow and displays a tooltip only when content is truncated.
+ *
+ * @remarks
+ * Uses a render prop pattern. The child function receives a `ref` that must be attached to the element being monitored for overflow. Use the `dependencies` array to trigger re-evaluation when content or container size changes.
+ *
+ * @example
+ * ```tsx
+ * <SmartTooltip title="This is a long text that might get truncated">
+ *   {({ ref }) => (
+ *     <Typography ref={ref} noWrap sx={{ overflow: 'hidden', textOverflow: 'ellipsis' }}>
+ *       This is a long text that might get truncated
+ *     </Typography>
+ *   )}
+ * </SmartTooltip>
+ * ```
+ */
 export declare function SmartTooltip<T extends HTMLElement>({ title, dependencies, timeout, TooltipProps, children, }: {
     title: string | undefined;
     dependencies?: unknown[];

package/dist/types/components/tooltip/tooltip.d.ts

@@ -10,4 +10,17 @@ import { TooltipProps } from '@mui/material';
  * </Tooltip>
  */
 export declare function Tooltip({ children, title, enterNextDelay, ...props }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Sets the global default `enterNextDelay` for all Tooltip components in the application.
+ *
+ * @param delay - Delay in milliseconds before showing tooltips on subsequent hovers.
+ *
+ * @example
+ * ```tsx
+ * import { setTooltipEnterDelay } from '@carto/ps-react-ui/components';
+ *
+ * // Set global delay to 300ms at app initialization
+ * setTooltipEnterDelay(300);
+ * ```
+ */
 export declare function setTooltipEnterDelay(delay: number): void;

package/dist/types/components/zoom-controls/zoom-controls.d.ts

@@ -1,3 +1,19 @@
 import { ZoomControlProps } from './types';
 import { JSX } from 'react';
+/**
+ * Provides intuitive zoom controls for maps and zoomable interfaces with flexible layouts, loading states, and optional reset functionality.
+ *
+ * @remarks
+ * This is an uncontrolled component. Typically used with the `ZoomControls` HOC from `@carto/ps-react-maps` for automatic state management.
+ *
+ * @example
+ * ```tsx
+ * <ZoomControlsUI
+ *   zoom={zoom}
+ *   onChange={setZoom}
+ *   minZoom={2}
+ *   maxZoom={20}
+ * />
+ * ```
+ */
 export declare function ZoomControlsUI({ zoom, disabled, direction, reverse, isLoading, maxZoom, minZoom, PaperProps, ResetViewProps, showZoom, onChange, onReset, }: ZoomControlProps): JSX.Element;

package/dist/types/hooks/index.d.ts

@@ -1,2 +1 @@
-export { useDebounce } from './use-debounce';
 export { useWidgetRef } from './use-widget-ref';

package/dist/types/hooks/use-widget-ref.d.ts

@@ -1,17 +1,20 @@
 /**
- * Custom hook for registering a DOM element ref with the widget store.
- * This allows other parts of the application to access the widget's DOM element.
+ * Registers a DOM element ref and an ECharts instance ref with the widget store.
+ * This allows other parts of the application (e.g., screenshot export) to access the widget's DOM element.
  *
- * @param widgetId - The widget ID to register the ref under
- * @returns A ref object to attach to the DOM element
+ * @param widgetId - The widget ID to register the refs under.
+ * @returns An object with `ref` (DOM element) and `instance` (ECharts instance) refs.
  *
  * @example
  * ```tsx
  * function MyWidget({ id }: { id: string }) {
- *   const ref = useWidgetRef<HTMLDivElement>(id)
+ *   const { ref } = useWidgetRef<HTMLDivElement>(id)
  *
  *   return <div ref={ref}>Widget content</div>
  * }
  * ```
  */
-export declare function useWidgetRef<T extends HTMLElement = HTMLElement>(widgetId: string): import('react').RefObject<T | null>;
+export declare function useWidgetRef<T extends HTMLElement = HTMLElement>(widgetId: string): {
+    ref: import('react').RefObject<T | null>;
+    instance: import('react').RefObject<import('node_modules/echarts').ECharts | null>;
+};

package/dist/types/widgets/actions/brush-toggle/brush-overlay.d.ts

@@ -0,0 +1,24 @@
+interface BrushOverlayProps {
+    id: string;
+    multiBrush?: boolean;
+}
+/**
+ * Portaled overlay rendered inside the ECharts chart `<div>`. Handles brush
+ * drawing entirely in DOM, independent of ECharts' built-in brush.
+ *
+ * Rectangles are stored in x-axis data coords (category indices) in the
+ * widget store. The overlay re-projects them to pixel coords on every chart
+ * `finished` event and container resize, so `setOption({ notMerge: true })`
+ * by the config pipeline is a non-event.
+ *
+ * Pointer capture and rectangle rendering are both clamped to the ECharts
+ * grid (plot area), so the legend, axis labels, and other chart chrome
+ * receive their usual events and aren't visually covered.
+ *
+ * Hit-testing happens on `pointerup` using `hitTestRects` against the widget's
+ * data length (derived from `widget.data`). The result is written to
+ * `brushSelection` in the store; `BrushToggle` subscribes to that and invokes
+ * the consumer's `onBrushSelected` callback.
+ */
+export declare function BrushOverlay({ id, multiBrush }: BrushOverlayProps): import('react').ReactPortal | null;
+export {};

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

@@ -0,0 +1,29 @@
+import { BrushToggleProps } from './types';
+/**
+ * Kept for backwards compatibility. The tool is no longer registered with the
+ * widget store — brush state is now owned directly by this component and the
+ * associated DOM overlay instead of being driven through the config pipeline.
+ * Existing code that looks this constant up in `registeredTools` will simply
+ * find no match.
+ */
+export declare const BRUSH_TOGGLE_TOOL_ID = "brush-toggle";
+/**
+ * Widget action to toggle brush-style selection on bar and histogram widgets.
+ *
+ * Renders a toggle button and a portaled overlay rendered inside the chart's
+ * `<div>`. The overlay handles all pointer interactions, draws selection
+ * rectangles in DOM, and hit-tests against the widget data. All state lives
+ * in the widget store — rectangles survive config-pipeline re-renders
+ * (`setOption({ notMerge: true })`) automatically.
+ *
+ * Only intended for bar and histogram widgets (both use `xAxis.type === 'category'`).
+ *
+ * @example
+ * ```tsx
+ * <BrushToggle
+ *   id="my-widget"
+ *   onBrushSelected={(items) => console.log(items)}
+ * />
+ * ```
+ */
+export declare function BrushToggle({ id, onBrushSelected, multiBrush, selections, defaultEnabled, labels, Icon, IconButtonProps, }: BrushToggleProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/actions/brush-toggle/hit-test.d.ts

@@ -0,0 +1,19 @@
+import { BrushRect } from './types';
+/**
+ * Returns integer dataIndices covered by a brush rectangle on a category axis.
+ *
+ * `xStart` / `xEnd` come from `instance.convertFromPixel({ xAxisIndex: 0 }, …)`
+ * which, for a category axis, returns fractional positions around integer
+ * category indices (e.g. `1.3` lands between categories 1 and 2). We snap the
+ * range outward (`floor` / `ceil`) so a drag that visually covers any part of
+ * a category's bar includes that index.
+ *
+ * Results are clamped to `[0, dataLength - 1]` and returned in ascending order.
+ */
+export declare function hitTestCategoryRange(xStart: number, xEnd: number, dataLength: number): number[];
+/**
+ * Union of `hitTestCategoryRange` across multiple rectangles. Used for
+ * multi-brush selections where each drawn rectangle contributes to the
+ * combined selection.
+ */
+export declare function hitTestRects(rects: BrushRect[], dataLength: number): number[];

package/dist/types/widgets/actions/brush-toggle/hit-test.test.d.ts

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

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

@@ -0,0 +1,21 @@
+import { Theme } from '@mui/material';
+import { CSSProperties } from 'react';
+export declare const styles: {
+    container: {
+        display: "flex";
+        alignItems: "center";
+        gap: ({ spacing }: Theme) => string;
+    };
+    trigger: {
+        '&[data-active="true"]': {
+            background: (theme: Theme) => string;
+        };
+    };
+};
+/**
+ * Plain CSS objects for the brush overlay — we're outside MUI's sx pipeline
+ * here because the rectangles are rendered via a React portal into the chart
+ * div (not part of the MUI tree). Colors borrow from the base palette; if
+ * theme-aware styling is needed later, move to styled components.
+ */
+export declare const overlayStyles: Record<string, CSSProperties>;

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

@@ -0,0 +1,73 @@
+import { IconButtonProps } from '@mui/material';
+import { ReactNode } from 'react';
+import { BaseWidgetState } from '../../stores/types';
+/**
+ * Brush selection result emitted by BrushToggle.
+ * Contains raw indices so consumers can resolve data according to their widget type.
+ */
+export interface BrushSelectedItems {
+    /** Data indices of the selected items in the dataset */
+    dataIndex: number[];
+    /** Series index from the brush event (defaults to 0) */
+    seriesIndex: number;
+}
+/**
+ * A selection rectangle in x-axis data coords. Stored in the widget store so
+ * it survives config-pipeline re-renders (which call `setOption` with
+ * `notMerge: true` and wipe any ECharts-side state). The overlay re-projects
+ * these to pixel positions on every chart render / resize.
+ *
+ * Both bar and histogram widgets use `xAxis.type === 'category'`, so the
+ * coords are category indices (possibly fractional — `convertFromPixel`
+ * returns floats like `1.3` between categories 1 and 2).
+ */
+export interface BrushRect {
+    xStart: number;
+    xEnd: number;
+}
+/**
+ * State stored in widget store for brush functionality.
+ */
+export interface BrushConfig {
+    /** Whether brush mode is enabled. */
+    brush?: boolean;
+    /** Persisted selection rectangles in data-axis coords. */
+    brushRects?: BrushRect[];
+    /** Last selection emitted to the `onBrushSelected` callback. */
+    brushSelection?: BrushSelectedItems;
+}
+export type BrushState<T = unknown> = BaseWidgetState<T & BrushConfig>;
+export interface BrushToggleProps {
+    /** Widget ID to update brush state in the widget store */
+    id: string;
+    /** Callback fired when items are selected via brush */
+    onBrushSelected?: (items: BrushSelectedItems) => void;
+    /** When true, allows multiple brush selection areas. Brush stays active after each selection. */
+    multiBrush?: boolean;
+    /**
+     * Initial brush-enabled state. Only applied on first mount if the widget
+     * store has no `brush` value yet — subsequent remounts preserve whatever
+     * state the user has toggled to.
+     */
+    defaultEnabled?: boolean;
+    /**
+     * Current selection count from the consumer (e.g. `selectedItems.length`).
+     * When this transitions to `0` (typically when the user presses the clear
+     * button in `WidgetSelectionSummary`), BrushToggle clears its persisted
+     * brush rectangles and the on-chart selection.
+     */
+    selections?: number;
+    /** Custom labels for the action */
+    labels?: {
+        /** Tooltip when brush is disabled (button will enable brush) */
+        enable?: string;
+        /** Tooltip when brush is enabled (button will disable brush) */
+        disable?: string;
+        /** Accessibility label */
+        ariaLabel?: string;
+    };
+    /** Props passed to the IconButton component */
+    IconButtonProps?: IconButtonProps;
+    /** Custom icon to display for brush toggle */
+    Icon?: ReactNode;
+}

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

@@ -1,2 +1,13 @@
 import { DownloadProps } from './types';
+/**
+ * Dropdown menu action for exporting widget data in various formats (CSV, PNG, etc.).
+ *
+ * Reads widget data from the store and triggers downloads using the modifier
+ * function defined in each `DownloadItem`.
+ *
+ * @example
+ * ```tsx
+ * <Download id={widgetId} items={barDownloadConfig({ refUI })} />
+ * ```
+ */
 export declare function Download({ id, items, labels, Icon, IconButtonProps, }: DownloadProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets/actions/download/exports.d.ts

@@ -1,6 +1,21 @@
 import { Ref } from 'react';
 import { DownloadItem } from './types';
+/**
+ * Pre-configured download item for exporting widget data as a CSV file.
+ *
+ * Converts a 2D array of data into CSV format with proper escaping and
+ * triggers a browser download. Revokes the object URL after download.
+ */
 export declare const downloadToCSV: DownloadItem<unknown[][]>;
+/**
+ * Pre-configured download item for exporting a widget as a PNG image.
+ *
+ * Uses html2canvas to capture the widget DOM element referenced by a React ref.
+ * Strips toolbar and action elements before capturing.
+ *
+ * @remarks
+ * The modifier expects a React ref to the widget's root HTML element, not raw data.
+ */
 export declare const downloadToPNG: Omit<DownloadItem, 'modifier'> & {
     modifier: (ref: Ref<HTMLElement | null> | undefined) => Promise<string | undefined>;
 };

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

@@ -1,2 +1,15 @@
 import { FullScreenProps } from './types';
+/**
+ * Displays widget content in a fullscreen modal dialog.
+ *
+ * Manages fullscreen state via the widget store and renders a MUI Dialog
+ * with the widget title and a close button.
+ *
+ * @example
+ * ```tsx
+ * <FullScreen id="my-widget" labels={{ ariaLabel: 'Expand chart' }}>
+ *   <ChartContent id="my-widget" />
+ * </FullScreen>
+ * ```
+ */
 export declare function FullScreen({ id, labels, children, Icon, IconButtonProps, DialogContentProps: { sx, ...DialogContentProps }, DialogProps, }: FullScreenProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,18 +1,20 @@
 export { FullScreen } from './fullscreen/fullscreen';
-export type { FullScreenState, FullScreenConfig } from './fullscreen/types';
+export type { FullScreenState, FullScreenConfig, FullScreenProps, } from './fullscreen/types';
 export { Download } from './download/download';
 export type { DownloadItem, DownloadProps } from './download/types';
 export { downloadToCSV, downloadToPNG } from './download/exports';
-export { RelativeData, RELATIVE_DATA_TOOL_ID, } from './relative-data/relative-data';
-export type { RelativeDataProps } from './relative-data/types';
+export { RelativeData, RELATIVE_DATA_TOOL_ID, RELATIVE_DATA_CONFIG_TOOL_ID, } from './relative-data/relative-data';
+export type { RelativeDataProps, RelativeDataState, } from './relative-data/types';
 export { ZoomToggle, ZOOM_TOGGLE_TOOL_ID } from './zoom-toggle/zoom-toggle';
 export type { ZoomToggleProps, ZoomState, ZoomConfig, } from './zoom-toggle/types';
 export { StackToggle, STACK_TOGGLE_TOOL_ID } from './stack-toggle/stack-toggle';
 export type { StackToggleProps, StackToggleState } from './stack-toggle/types';
 export { Searcher, SEARCHER_TOOL_ID } from './searcher/searcher';
 export { SearcherToggle } from './searcher/searcher-toggle';
-export type { SearcherToggleProps, SearcherProps, SearcherFilterFn, SearcherState, } from './searcher/types';
+export type { SearcherToggleProps, SearcherProps, SearcherFilterFn, SearcherState, SearcherStateProps, } from './searcher/types';
 export { ChangeColumn, CHANGE_COLUMN_TOOL_ID, } from './change-column/change-column';
 export type { ChangeColumnProps } from './change-column/types';
 export { LockSelection, LOCK_SELECTION_TOOL_ID, } from './lock-selection/lock-selection';
-export type { LockSelectionProps, LockSelectionState, } from './lock-selection/types';
+export type { LockSelectionProps, LockSelectionState, LockSelectionStateProps, } from './lock-selection/types';
+export { BrushToggle, BRUSH_TOGGLE_TOOL_ID } from './brush-toggle/brush-toggle';
+export type { BrushToggleProps, BrushState, BrushConfig, BrushSelectedItems, } from './brush-toggle/types';

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

@@ -33,4 +33,6 @@ export interface LockSelectionProps {
 export interface LockSelectionStateProps {
     /** Whether the selection is currently locked */
     isLocked?: boolean;
+    /** Items locked for filtering */
+    lockedItems?: string[];
 }