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

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

@@ -0,0 +1,56 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { BrushToggleLabels } from './labels';
+export interface BrushToggleProps {
+    initialEnabled?: boolean;
+    /**
+     * ECharts brush type. `'lineX'` (default) selects a range on the
+     * x-axis — appropriate for bar / histogram / timeseries. `'rect'`
+     * selects a 2-D rectangle — use for scatterplot. Other ECharts
+     * brush types (`'lineY'`, `'polygon'`) are also accepted.
+     */
+    brushType?: 'lineX' | 'lineY' | 'rect' | 'polygon';
+    /**
+     * `'multiple'` (default) lets the user draw additional brushes on
+     * top of existing ones. `'single'` replaces the previous brush on
+     * each new draw.
+     */
+    brushMode?: 'multiple' | 'single';
+    /**
+     * Optional view of the consumer-owned selection. When provided and
+     * the array is empty (`[]`), any brush rectangles currently drawn on
+     * the chart are wiped — keeps the UI in sync when the parent clears
+     * the selection externally (e.g. via `Widget.SelectionSummary`'s
+     * `onClear`). Pass the same array that drives `useChartSelection` /
+     * the option factory's `selection` input.
+     *
+     * Leave `undefined` to opt out — the sync effect becomes a no-op.
+     */
+    selection?: readonly unknown[] | null;
+    labels?: Partial<BrushToggleLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+/**
+ * Toggle ECharts' brush selection mode. Two-part wiring:
+ *
+ *   1. The config transform (`addBrush`) installs the `brush`
+ *      component on the option so brushed items get the
+ *      `outOfBrush` dim treatment.
+ *   2. ECharts only enters "brush cursor" mode when something
+ *      dispatches `takeGlobalCursor({ key: 'brush', ... })`. This
+ *      component drives that dispatch via {@link useEchartInstance},
+ *      reacting when the chart instance becomes available (the
+ *      `BrushToggle` mounts before `Widget.Echart` in tree order, so
+ *      on first mount the chart isn't ready yet).
+ *
+ *   3. ECharts clears the global cursor on every `setOption`, so we
+ *      re-dispatch on each `'finished'` event — required for
+ *      `brushMode: 'multiple'` to keep working across selection-driven
+ *      re-renders, RelativeData toggles, etc.
+ *
+ * Selection events (`brushSelected` / `brushEnd`) flow through the
+ * existing `useChartSelection` wiring at the consumer level — no extra
+ * plumbing here.
+ */
+export declare function BrushToggle({ initialEnabled, brushType, brushMode, selection, labels, icon: Icon, iconProps, }: BrushToggleProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,3 @@
+export { BrushToggle, type BrushToggleProps } from './brush-toggle';
+export { addBrush } from './transforms';
+export { DEFAULT_BRUSH_TOGGLE_LABELS, type BrushToggleLabels } from './labels';

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

@@ -0,0 +1,5 @@
+export interface BrushToggleLabels {
+    on: string;
+    off: string;
+}
+export declare const DEFAULT_BRUSH_TOGGLE_LABELS: BrushToggleLabels;

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

@@ -0,0 +1,12 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    toggle: {
+        p: number;
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
+        };
+    };
+    toggleActive: {
+        background: (theme: Theme) => string;
+    };
+};

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

@@ -0,0 +1,11 @@
+/**
+ * Brush config transform: enables ECharts' brush component on the option
+ * object. Module-level constant — identity stable across renders.
+ *
+ * Pairs with `replaceMergeKeys: ['brush']` so the pipeline replaces (not
+ * merges) the brush config on every config-pipeline run. v1 needed a
+ * mousemove re-dispatch hack to keep the brush state across data updates;
+ * v2 keeps brush state continuous via `notMerge: false` + dynamic
+ * replaceMerge in the EchartUI layer (D6) — no hack required.
+ */
+export declare const addBrush: (option: unknown) => unknown;

package/dist/types/widgets-v2/actions/change-column/change-column-icon.d.ts

@@ -0,0 +1,2 @@
+import { SvgIconProps } from '@mui/material';
+export declare function ChangeColumnIcon(props: SvgIconProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets-v2/actions/change-column/change-column.d.ts

@@ -0,0 +1,29 @@
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { ChangeColumnLabels } from './labels';
+export interface ChangeColumnItem {
+    id: string;
+    label: ReactNode;
+}
+export interface ChangeColumnProps {
+    /**
+     * Master list of columns (id + label) in their default order. The current
+     * effective order is derived by combining this list with the widget's
+     * `columnOrder` extension state.
+     */
+    columns: readonly ChangeColumnItem[];
+    labels?: Partial<ChangeColumnLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    dragHandleIcon?: ComponentType<SvgIconProps>;
+}
+/**
+ * Action that lets users reorder columns via drag-and-drop. The new order is
+ * persisted on the widget store as `columnOrder` (an array of ids) on the
+ * {@link ChangeColumnWidgetState} extension. `<Table>` (and other column-aware
+ * bridges) merge that order with their own `columns` prop via
+ * `resolveColumns()` from the table primitives.
+ *
+ * Returns `null` when there are fewer than two columns to reorder.
+ */
+export declare function ChangeColumn({ columns, labels, icon: Icon, iconProps, dragHandleIcon, }: ChangeColumnProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/widgets-v2/actions/change-column/index.d.ts

@@ -0,0 +1,3 @@
+export { ChangeColumn, type ChangeColumnProps, type ChangeColumnItem, } from './change-column';
+export { DEFAULT_CHANGE_COLUMN_LABELS, type ChangeColumnLabels } from './labels';
+export type { ChangeColumnWidgetState } from './types';

package/dist/types/widgets-v2/actions/change-column/labels.d.ts

@@ -0,0 +1,5 @@
+export interface ChangeColumnLabels {
+    trigger: string;
+    reset: string;
+}
+export declare const DEFAULT_CHANGE_COLUMN_LABELS: ChangeColumnLabels;

package/dist/types/widgets-v2/actions/change-column/sortable-column-item.d.ts

@@ -0,0 +1,14 @@
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps } from '@mui/material';
+export interface SortableColumnItemProps {
+    id: string;
+    label: ReactNode;
+    dragHandleIcon?: ComponentType<SvgIconProps>;
+}
+/**
+ * Draggable menu item used inside ChangeColumn's `<DndContext>`. Wraps a
+ * MUI `<MenuItem>` so it inherits keyboard / theming behavior, and exposes
+ * the dnd-kit listeners on the whole row so the user can grab anywhere on
+ * the row to reorder.
+ */
+export declare function SortableColumnItem({ id, label, dragHandleIcon: HandleIcon, }: SortableColumnItemProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets-v2/actions/change-column/style.d.ts

@@ -0,0 +1,33 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    toggle: {
+        p: number;
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
+        };
+    };
+    toggleActive: {
+        background: (theme: Theme) => string;
+    };
+    menuPaper: {
+        overflow: "hidden";
+        minWidth: number;
+    };
+    item: {
+        cursor: "grab";
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: "primary.main";
+            outlineOffset: number;
+        };
+    };
+    itemDragging: {
+        opacity: number;
+        cursor: "grabbing";
+    };
+    dragHandle: {
+        color: "text.secondary";
+        mr: number;
+        fontSize: number;
+    };
+};

package/dist/types/widgets-v2/actions/change-column/types.d.ts

@@ -0,0 +1,10 @@
+import { WidgetState } from '../../stores';
+/**
+ * State extension owned by the ChangeColumn action. Stored on the per-widget
+ * Zustand store; read by `<Table>` (and any other column-aware bridge) to
+ * resolve the effective column order.
+ */
+export interface ChangeColumnWidgetState extends WidgetState {
+    /** Ordered list of column ids. Empty / unset means "use props order". */
+    columnOrder?: readonly string[];
+}

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

@@ -0,0 +1,18 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { DownloadItem } from './types';
+import { DownloadLabels } from './labels';
+export interface DownloadProps {
+    items: readonly DownloadItem[];
+    labels?: Partial<DownloadLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Fires when an item's `resolve()` rejects (or any step in the click-through
+     * path throws). The error is normalised to a real `Error` first. Surface
+     * to your telemetry / toast layer here; the trigger already shows a visual
+     * error indicator independently.
+     */
+    onError?: (err: Error) => void;
+}
+export declare function Download({ items, labels, icon: Icon, iconProps, onError, }: DownloadProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,37 @@
+/**
+ * Pure download helpers — no React, no DOM lifecycle outside the link click.
+ * Component layer in {@link ./download.tsx} orchestrates these.
+ */
+export interface DownloadHandle {
+    url: string;
+    revoke: () => void;
+}
+export declare function toCsvString(rows: readonly (readonly unknown[])[]): string;
+export declare function downloadToCSV(rows: readonly (readonly unknown[])[]): DownloadHandle;
+export declare function sanitizeFilename(name: string): string;
+/**
+ * Triggers a browser download for the given URL by synthesizing an anchor,
+ * clicking it, and removing it. Pure DOM — no React. The filename is run
+ * through {@link sanitizeFilename} before being assigned to `a.download`.
+ */
+export declare function triggerLinkDownload(args: {
+    url: string;
+    filename: string;
+}): void;
+export interface DownloadDOMToPNGOptions {
+    element: HTMLElement;
+    /** html2canvas `scale`. Default 2 — crisp on hi-DPI displays. */
+    pixelRatio?: number;
+    /**
+     * html2canvas `backgroundColor`. Default `null` (transparent) so the PNG
+     * inherits whatever surface it lands on when the user pastes it.
+     */
+    backgroundColor?: string | null;
+}
+/**
+ * Rasterise an HTMLElement to PNG via `html2canvas` and wrap the result in
+ * a `DownloadHandle`. The caller is responsible for calling `handle.revoke`
+ * after the link click is dispatched. Used by per-widget download configs
+ * to power the PNG menu item.
+ */
+export declare function downloadDOMToPNG(opts: DownloadDOMToPNGOptions): Promise<DownloadHandle>;

package/dist/types/widgets-v2/actions/download/icons.d.ts

@@ -0,0 +1,12 @@
+import { SvgIconProps } from '@mui/material';
+/**
+ * Generic "image" glyph used for the PNG download item. Wraps MUI's
+ * `ImageOutlined` so callers can swap it via the per-widget download
+ * config's `icon` override without pulling MUI directly.
+ */
+export declare function PNGIcon(props: SvgIconProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * "CSV" rectangle with the letters spelled inside — matches v1 visual and is
+ * easier to recognise in a download menu than a generic table glyph.
+ */
+export declare function CSVIcon(props: SvgIconProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets-v2/actions/download/index.d.ts

@@ -0,0 +1,6 @@
+export { Download, type DownloadProps } from './download';
+export { downloadToCSV, downloadDOMToPNG, toCsvString, triggerLinkDownload, type DownloadHandle, type DownloadDOMToPNGOptions, } from './exports';
+export { CSVIcon, PNGIcon } from './icons';
+export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item';
+export type { DownloadItem } from './types';
+export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels';

package/dist/types/widgets-v2/actions/download/labels.d.ts

@@ -0,0 +1,11 @@
+export interface DownloadLabels {
+    trigger: string;
+    /** Tooltip / aria-label shown on the trigger while a download is in flight. */
+    loading: string;
+    /**
+     * Tooltip / aria-label shown on the trigger after a download failed. Cleared
+     * the next time the menu opens.
+     */
+    error: string;
+}
+export declare const DEFAULT_DOWNLOAD_LABELS: DownloadLabels;

package/dist/types/widgets-v2/actions/download/png-item.d.ts

@@ -0,0 +1,24 @@
+import { DownloadItem } from './types';
+export interface BuildPngDownloadItemArgs {
+    /** Base filename (without extension). The item appends `.png`. */
+    filename: string;
+    /**
+     * Reads the capture element to rasterise. Called at click time so the
+     * download config doesn't capture a stale reference. Wire it to
+     * `() => getCaptureEl(id)` from `widgets-v2/stores`.
+     */
+    getCaptureEl: () => HTMLElement | null;
+    /** html2canvas `scale`. Default 2. */
+    pixelRatio?: number;
+    /** html2canvas `backgroundColor`. Default transparent (`null`). */
+    backgroundColor?: string | null;
+    /** Override the menu label. Default `'PNG'`. */
+    label?: string;
+}
+/**
+ * Builds the standard PNG `DownloadItem` used by every per-widget download
+ * config. Centralised so the menu label, icon, error message, and filename
+ * suffix stay consistent across widgets without each `create*DownloadConfig`
+ * re-deriving the same shape.
+ */
+export declare function buildPngDownloadItem(args: BuildPngDownloadItemArgs): DownloadItem;

package/dist/types/widgets-v2/actions/download/style.d.ts

@@ -0,0 +1 @@
+export declare const styles: {};

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

@@ -0,0 +1,35 @@
+import { ReactElement } from 'react';
+export interface DownloadItem {
+    /** Unique key (also used as menu label key). */
+    id: string;
+    /** Display label in the menu. */
+    label: string;
+    /**
+     * Optional leading icon shown next to the label. Pass a rendered element
+     * (e.g. `<DownloadIcon fontSize='small' />`) so consumers can fully
+     * control sizing / colour. Rendered inside an MUI `<ListItemIcon>`.
+     */
+    icon?: ReactElement;
+    /**
+     * When `true`, the menu item is rendered but non-clickable (greyed out).
+     * Useful for items whose underlying export is unavailable in the current
+     * widget state (no rows, missing permission, etc.).
+     */
+    disabled?: boolean;
+    /**
+     * Override for the resolved filename. When set, `resolve()`'s `filename`
+     * is ignored and this value is used instead — handy when the consumer
+     * wants to template the filename with widget metadata without having to
+     * close over it inside `resolve()`.
+     */
+    filename?: string;
+    /**
+     * Resolves to a Blob URL the trigger will click. Optional `revoke` is
+     * called after the click is dispatched.
+     */
+    resolve: () => Promise<{
+        url: string;
+        filename: string;
+        revoke?: () => void;
+    }>;
+}

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

@@ -0,0 +1,59 @@
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { FullScreenLabels } from './labels';
+export interface FullScreenTriggerProps {
+    labels?: Partial<FullScreenLabels>;
+    enterIcon?: ComponentType<SvgIconProps>;
+    exitIcon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+export interface FullScreenSlotProps {
+    /**
+     * Render-prop body. Receives the live `isFullScreen` flag so the consumer
+     * can branch per-mode props (e.g., `Widget.Toolbox visibleCount`) without
+     * duplicating the JSX.
+     */
+    children: (isFullScreen: boolean) => ReactNode;
+    /** Header text rendered above the body when the modal is open. */
+    title?: ReactNode;
+    labels?: Partial<FullScreenLabels>;
+    closeIcon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+/**
+ * Toggle button placed inside `<Widget.Actions>`. Reads / writes
+ * {@link FullScreenWidgetState.isFullScreen} on the per-widget store. The
+ * matching modal is rendered by {@link FullScreenSlot} (typically inside
+ * `<Widget.Content>`).
+ */
+declare function FullScreenTrigger({ labels, enterIcon: EnterIcon, exitIcon: ExitIcon, iconProps, }: FullScreenTriggerProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Body wrapper. Renders its render-prop children once, via a single
+ * `createPortal` call whose container is a stable `<div>` we hold as a ref.
+ * That div is moved imperatively between an inline placeholder and the
+ * `<DialogContent>` of an MUI `<Dialog keepMounted>`. Because both the
+ * React parent (the portal call site) AND the portal container are
+ * identical across the toggle, the subtree keeps its fiber identity and
+ * ECharts (or any other heavy child) stays mounted while only its DOM
+ * parent changes.
+ */
+declare function FullScreenSlot({ children, title, labels, closeIcon: CloseSvg, iconProps, }: FullScreenSlotProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Namespace export. Consumers compose with:
+ *
+ * ```tsx
+ * <Widget.Actions>
+ *   <Widget.FullScreen.Trigger />
+ * </Widget.Actions>
+ * <Widget.Content>
+ *   <Widget.FullScreen.Slot title={title}>
+ *     {(isFullScreen) => <Body visibleCount={isFullScreen ? undefined : 2} />}
+ *   </Widget.FullScreen.Slot>
+ * </Widget.Content>
+ * ```
+ */
+export declare const FullScreen: {
+    Trigger: typeof FullScreenTrigger;
+    Slot: typeof FullScreenSlot;
+};
+export {};

package/dist/types/widgets-v2/actions/fullscreen/index.d.ts

@@ -0,0 +1,3 @@
+export { FullScreen, type FullScreenTriggerProps, type FullScreenSlotProps, } from './fullscreen';
+export { DEFAULT_FULLSCREEN_LABELS, type FullScreenLabels } from './labels';
+export type { FullScreenWidgetState } from './types';

package/dist/types/widgets-v2/actions/fullscreen/labels.d.ts

@@ -0,0 +1,5 @@
+export interface FullScreenLabels {
+    open: string;
+    close: string;
+}
+export declare const DEFAULT_FULLSCREEN_LABELS: FullScreenLabels;

package/dist/types/widgets-v2/actions/fullscreen/style.d.ts

@@ -0,0 +1,48 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    inlineSlot: {
+        display: "flex";
+        flexDirection: "column";
+        flex: number;
+        minHeight: number;
+        gap: number;
+    };
+    trigger: {
+        p: number;
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
+        };
+    };
+    triggerActive: {
+        background: (theme: Theme) => string;
+    };
+    dialogPaper: {
+        width: string;
+        height: string;
+        maxWidth: string;
+        maxHeight: string;
+    };
+    dialogTitle: {
+        display: "flex";
+        alignItems: "center";
+        justifyContent: "space-between";
+        gap: number;
+        py: number;
+        pr: number;
+        pb: number;
+    };
+    titleText: {
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    dialogContent: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        py: number;
+        px: number;
+        overflow: "auto";
+    };
+};

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

@@ -0,0 +1,14 @@
+import { WidgetState } from '../../stores';
+/**
+ * State extension owned by FullScreen. The base `WidgetState` deliberately
+ * stays free of widget-specific UI flags (R12 from the round-5 amendment);
+ * actions that need persistent UI state declare it here and read it via the
+ * generic `useWidget<T, S>(id, sel)` form.
+ *
+ * `isFullScreen` survives `keepAlive` remounts because it lives on the same
+ * store the rest of `WidgetState` does — a kept-alive widget that was
+ * fullscreen reopens fullscreen automatically.
+ */
+export interface FullScreenWidgetState extends WidgetState {
+    isFullScreen: boolean;
+}

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

@@ -0,0 +1,9 @@
+export { Searcher, SearcherToggle, setSearcherText, filterBySearchText, DEFAULT_SEARCHER_LABELS, type SearcherProps, type SearcherToggleProps, type SearcherLabels, } from './searcher';
+export { StackToggle, addStack, DEFAULT_STACK_TOGGLE_LABELS, type StackToggleProps, type StackToggleLabels, } from './stack-toggle';
+export { ZoomToggle, addZoom, createAddZoom, ZOOM_LAYOUT, DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleProps, type ZoomToggleLabels, } from './zoom-toggle';
+export { BrushToggle, addBrush, DEFAULT_BRUSH_TOGGLE_LABELS, type BrushToggleProps, type BrushToggleLabels, } from './brush-toggle';
+export { RelativeData, toRelativeData, createPercentFormatter, DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataProps, type RelativeDataLabels, } from './relative-data';
+export { Download, downloadToCSV, downloadDOMToPNG, toCsvString, triggerLinkDownload, buildPngDownloadItem, CSVIcon, PNGIcon, DEFAULT_DOWNLOAD_LABELS, type DownloadProps, type DownloadItem, type DownloadHandle, type DownloadDOMToPNGOptions, type BuildPngDownloadItemArgs, type DownloadLabels, } from './download';
+export { FullScreen, DEFAULT_FULLSCREEN_LABELS, type FullScreenTriggerProps, type FullScreenSlotProps, type FullScreenLabels, type FullScreenWidgetState, } from './fullscreen';
+export { LockSelection, filterByLockedItems, DEFAULT_LOCK_SELECTION_LABELS, type LockSelectionProps, type LockSelectionKey, type LockSelectionLabels, } from './lock-selection';
+export { ChangeColumn, DEFAULT_CHANGE_COLUMN_LABELS, type ChangeColumnProps, type ChangeColumnItem, type ChangeColumnLabels, type ChangeColumnWidgetState, } from './change-column';

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

@@ -0,0 +1,3 @@
+export { LockSelection, type LockSelectionProps, type LockSelectionKey, } from './lock-selection';
+export { filterByLockedItems } from './transforms';
+export { DEFAULT_LOCK_SELECTION_LABELS, type LockSelectionLabels, } from './labels';

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

@@ -0,0 +1,6 @@
+export interface LockSelectionLabels {
+    lock: string;
+    unlock: string;
+    disabled: string;
+}
+export declare const DEFAULT_LOCK_SELECTION_LABELS: LockSelectionLabels;

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

@@ -0,0 +1,36 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { LockSelectionLabels } from './labels';
+export type LockSelectionKey = string | number;
+export interface LockSelectionProps {
+    /**
+     * Currently-selected items (destination-owned). On lock, this set is
+     * snapshotted into `lockedItems` via `onLockChange`.
+     */
+    selection: readonly LockSelectionKey[];
+    /**
+     * Currently-locked items (destination-owned). When non-empty, the widget's
+     * data is filtered to these items via the registered transform.
+     */
+    lockedItems: readonly LockSelectionKey[];
+    /**
+     * Fires when the user toggles the lock. The destination is responsible for
+     * persisting the new locked set (and re-feeding it via `lockedItems`).
+     */
+    onLockChange: (next: readonly LockSelectionKey[]) => void;
+    labels?: Partial<LockSelectionLabels>;
+    /** Lock icon (default: `LockIcon`). */
+    lockIcon?: ComponentType<SvgIconProps>;
+    /** Unlock icon (default: `LockOpenIcon`). */
+    unlockIcon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+/**
+ * Action that pins the current selection so the widget's data filters down
+ * to those items even as the user changes selections. Selection and lock
+ * state are destination-owned; this component is a controlled UI + a data
+ * transform registered against the widget's pipeline.
+ *
+ * The trigger is disabled when there is nothing to lock and nothing locked.
+ */
+export declare function LockSelection({ selection, lockedItems, onLockChange, labels, lockIcon: LockSvg, unlockIcon: UnlockSvg, iconProps, }: LockSelectionProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    toggle: {
+        p: number;
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
+        };
+    };
+    toggleActive: {
+        background: (theme: Theme) => string;
+    };
+};

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

@@ -0,0 +1,6 @@
+/**
+ * Filters a 2D series of `{name, ...}` records, keeping only items whose
+ * `name` is in the locked set. Multi-series shape is preserved (one inner
+ * array per series). Used by the LockSelection action's data transform.
+ */
+export declare function filterByLockedItems(input: unknown, lockedItems: readonly (string | number)[]): unknown;

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

@@ -0,0 +1,3 @@
+export { RelativeData, type RelativeDataProps } from './relative-data';
+export { toRelativeData, createPercentFormatter } from './transforms';
+export { DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataLabels } from './labels';

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

@@ -0,0 +1,5 @@
+export interface RelativeDataLabels {
+    on: string;
+    off: string;
+}
+export declare const DEFAULT_RELATIVE_DATA_LABELS: RelativeDataLabels;

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

@@ -0,0 +1,39 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { RelativeDataLabels } from './labels';
+export interface RelativeDataProps {
+    initialEnabled?: boolean;
+    /**
+     * BCP-47 locale tag forwarded to `Intl.NumberFormat`. Defaults to the
+     * runtime locale.
+     */
+    locale?: string;
+    labels?: Partial<RelativeDataLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Data-side transform that rewrites the widget's series into their
+     * relative (0–100) form. Defaults to {@link toRelativeData}, which
+     * handles the canonical `{ name, value }[]` shape (bar / pie /
+     * timeseries / category). Widgets with a different data shape pass
+     * their own — `toRelativeHistogramData` for histogram's `number[]`,
+     * `toRelativeScatterplotData` for scatter's `[x, y][]`.
+     *
+     * Should be a stable top-level reference; inline `(data) => ...`
+     * literals re-register the transform every render.
+     */
+    transform?: (data: unknown) => unknown;
+}
+/**
+ * Toggle between absolute and relative (percentage) values.
+ *
+ *   - **Data side**: a single data transform ({@link toRelativeData}) registered
+ *     through `useSingleTransform`. When disabled, the pipeline skips it and the
+ *     derived `data` reverts to `rawData` automatically.
+ *   - **Formatter side**: an effect writes directly to `state.formatter`. When
+ *     enabled it installs the Intl-based percent formatter; when disabled it
+ *     reads `state.rawFormatter` (the consumer-supplied original, always live)
+ *     and writes it back to `formatter`. No "original" snapshot is captured —
+ *     `rawFormatter` is the original.
+ */
+export declare function RelativeData({ initialEnabled, locale, labels, icon: Icon, iconProps, transform, }: RelativeDataProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { Theme } from '@mui/material';
+export declare const styles: {
+    toggle: {
+        p: number;
+        '& .MuiSvgIcon-root': {
+            fontSize: number;
+        };
+    };
+    toggleActive: {
+        background: (theme: Theme) => string;
+    };
+};