@carto/ps-react-ui 5.0.0-widgets.9 → 5.1.0

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

@@ -0,0 +1,12 @@
+/**
+ * Canonical `DownloadItem.id`s for the built-in download formats. Centralised
+ * so the per-format builders — and anything that keys off the id (menu logic,
+ * tests) — reference one source of truth instead of re-typing string literals.
+ * The Markdown format keeps the short `'md'` id to match its `.md` extension.
+ */
+export declare const DOWNLOAD_ITEM_IDS: {
+    readonly png: "png";
+    readonly csv: "csv";
+    readonly markdown: "md";
+};
+export type DownloadItemId = (typeof DOWNLOAD_ITEM_IDS)[keyof typeof DOWNLOAD_ITEM_IDS];

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

@@ -0,0 +1,38 @@
+import { DownloadItem } from './types.js';
+interface BuildCsvDownloadItemBase {
+    /** Base filename (without extension). The item appends `.csv`. */
+    filename: string;
+    /** Override the menu label. Default `'CSV'`. */
+    label?: string;
+}
+/**
+ * Args for {@link buildCsvDownloadItem}. A discriminated union: a caller must
+ * supply exactly one content source — `getRows` (rows serialised through the
+ * shared `toCsvString`) or `getCsv` (a pre-built CSV string). The `?: never`
+ * arms make passing both — or neither — a compile-time error.
+ */
+export type BuildCsvDownloadItemArgs = (BuildCsvDownloadItemBase & {
+    /**
+     * Builds the CSV rows at click time. Used by most widgets — rows are run
+     * through `toCsvString` so escaping (incl. the spreadsheet
+     * formula-injection guard) stays consistent across widgets.
+     */
+    getRows: () => readonly (readonly unknown[])[];
+    getCsv?: never;
+}) | (BuildCsvDownloadItemBase & {
+    /**
+     * Returns a pre-built CSV string at click time. Escape hatch for widgets
+     * (e.g. Table) that already serialise their own CSV with bespoke
+     * header/cell handling.
+     */
+    getCsv: () => string;
+    getRows?: never;
+});
+/**
+ * Builds the standard CSV `DownloadItem` used by every per-widget download
+ * config. Centralised so the menu label, icon, and `.csv` filename suffix stay
+ * consistent across widgets — mirrors {@link buildPngDownloadItem} so neither
+ * format can drift again.
+ */
+export declare function buildCsvDownloadItem(args: BuildCsvDownloadItemArgs): DownloadItem;
+export {};

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.js';
+import { DownloadLabels } from './labels.js';
+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.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,18 @@
+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.Element;
+/**
+ * Generic "document" glyph used for the Markdown download item. Wraps MUI's
+ * `ArticleOutlined`, mirroring {@link PNGIcon}, so the Markdown menu item
+ * carries an icon consistent with the other download formats.
+ */
+export declare function MarkdownIcon(props: SvgIconProps): import('react').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.Element;

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

@@ -0,0 +1,8 @@
+export { Download, type DownloadProps } from './download.js';
+export { downloadToCSV, downloadDOMToPNG, toCsvString, triggerLinkDownload, type DownloadHandle, type DownloadDOMToPNGOptions, } from './exports.js';
+export { CSVIcon, PNGIcon, MarkdownIcon } from './icons.js';
+export { buildPngDownloadItem, type BuildPngDownloadItemArgs } from './png-item.js';
+export { buildCsvDownloadItem, type BuildCsvDownloadItemArgs } from './csv-item.js';
+export { DOWNLOAD_ITEM_IDS, type DownloadItemId } from './constants.js';
+export type { DownloadItem } from './types.js';
+export { DEFAULT_DOWNLOAD_LABELS, type DownloadLabels } from './labels.js';

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.js';
+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,78 @@
+import { ComponentType, ReactNode } from 'react';
+import { SvgIconProps, SxProps, Theme } from '@mui/material';
+import { FullScreenLabels } from './labels.js';
+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;
+    /**
+     * Buttons rendered in the modal header, to the left of the close icon —
+     * the fullscreen counterpart of `<Widget.Actions>`, which lives in the
+     * wrapper's summary row and is covered by the dialog. Pass the same
+     * elements you compose there (typically `<Widget.Download>`); the
+     * fullscreen trigger is intentionally not among them, since the close
+     * icon already exits.
+     */
+    actions?: ReactNode;
+    /**
+     * Per-widget override merged over the default `90vw x 90vh` dialog paper.
+     * Charts want the default (their canvas grows to fill it); content-sized
+     * widgets (Range, Markdown) pass their own width / `height: 'auto'` so the
+     * modal doesn't leave a large empty box around them.
+     *
+     * Shallow-merged over the default, same as `Widget.Actions`' `sx`: pass a
+     * plain style object, not the array or theme-callback form.
+     */
+    paperSx?: SxProps<Theme>;
+    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.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, actions, paperSx, labels, closeIcon: CloseSvg, iconProps, }: FullScreenSlotProps): import('react').JSX.Element;
+/**
+ * Namespace export. Consumers compose with:
+ *
+ * ```tsx
+ * <Widget.Actions>
+ *   <Widget.FullScreen.Trigger />
+ * </Widget.Actions>
+ * <Widget.Content>
+ *   <Widget.FullScreen.Slot title={title} actions={<Widget.Download items={items} />}>
+ *     {(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.js';
+export { DEFAULT_FULLSCREEN_LABELS, type FullScreenLabels } from './labels.js';
+export type { FullScreenWidgetState } from './types.js';

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,57 @@
+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;
+        minWidth: string;
+        minHeight: string;
+        maxWidth: string;
+        maxHeight: string;
+    };
+    dialogTitle: {
+        display: "flex";
+        alignItems: "center";
+        justifyContent: "space-between";
+        gap: number;
+        py: number;
+        pr: number;
+        pb: number;
+    };
+    dialogActions: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        flexShrink: number;
+    };
+    titleText: {
+        minWidth: number;
+        overflow: "hidden";
+        textOverflow: "ellipsis";
+        whiteSpace: "nowrap";
+    };
+    dialogContent: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        py: number;
+        px: number;
+        overflow: "auto";
+        minHeight: number;
+    };
+};

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

@@ -0,0 +1,14 @@
+import { WidgetState } from '../../stores/index.js';
+/**
+ * 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,10 @@
+export { Searcher, SearcherToggle, setSearcherText, filterBySearchText, DEFAULT_SEARCHER_LABELS, type SearcherProps, type SearcherToggleProps, type SearcherLabels, } from './searcher/index.js';
+export { StackToggle, addStack, DEFAULT_STACK_TOGGLE_LABELS, type StackToggleProps, type StackToggleLabels, } from './stack-toggle/index.js';
+export { ShowAllToggle, setShowAll, SHOW_ALL_ID, DEFAULT_SHOW_ALL_LABELS, type ShowAllToggleProps, type ShowAllLabels, } from './show-all/index.js';
+export { ZoomToggle, addZoom, createAddZoom, ZOOM_LAYOUT, DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleProps, type ZoomToggleLabels, } from './zoom-toggle/index.js';
+export { BrushToggle, addBrush, DEFAULT_BRUSH_TOGGLE_LABELS, type BrushToggleProps, type BrushToggleLabels, } from './brush-toggle/index.js';
+export { RelativeData, toRelativeData, createPercentFormatter, DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataProps, type RelativeDataLabels, } from './relative-data/index.js';
+export { Download, downloadToCSV, downloadDOMToPNG, toCsvString, triggerLinkDownload, buildPngDownloadItem, buildCsvDownloadItem, CSVIcon, PNGIcon, MarkdownIcon, DEFAULT_DOWNLOAD_LABELS, DOWNLOAD_ITEM_IDS, type DownloadProps, type DownloadItem, type DownloadItemId, type DownloadHandle, type DownloadDOMToPNGOptions, type BuildPngDownloadItemArgs, type BuildCsvDownloadItemArgs, type DownloadLabels, } from './download/index.js';
+export { FullScreen, DEFAULT_FULLSCREEN_LABELS, type FullScreenTriggerProps, type FullScreenSlotProps, type FullScreenLabels, type FullScreenWidgetState, } from './fullscreen/index.js';
+export { LockSelection, filterByLockedItems, DEFAULT_LOCK_SELECTION_LABELS, type LockSelectionProps, type LockSelectionKey, type LockSelectionLabels, } from './lock-selection/index.js';
+export { ChangeColumn, DEFAULT_CHANGE_COLUMN_LABELS, type ChangeColumnProps, type ChangeColumnItem, type ChangeColumnLabels, type ChangeColumnWidgetState, } from './change-column/index.js';

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

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

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,57 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { LockSelectionLabels } from './labels.js';
+export type LockSelectionKey = string | number;
+export interface LockSelectionProps<K extends LockSelectionKey = LockSelectionKey> {
+    /**
+     * Currently-selected items (destination-owned). On lock, this set is
+     * snapshotted into `lockedItems` via `onLockChange`.
+     */
+    selection: readonly K[];
+    /**
+     * Currently-locked items (destination-owned). When non-empty, the widget's
+     * data is filtered to these items via the registered transform.
+     */
+    lockedItems: readonly K[];
+    /**
+     * 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 K[]) => void;
+    labels?: Partial<LockSelectionLabels>;
+    /** Lock icon (default: `LockIcon`). */
+    lockIcon?: ComponentType<SvgIconProps>;
+    /** Unlock icon (default: `LockOpenIcon`). */
+    unlockIcon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Data transform applied while locked. Defaults to {@link filterByLockedItems}
+     * (keeps only `{name, ...}` items whose `name` is in `lockedItems`, across a
+     * `X[][]` series shape — matches Bar/Pie/Category/Timeseries data). Widgets
+     * whose data shape or selection identity differs (bin index, composite
+     * point key, flat rows) pass their own — e.g. Histogram's
+     * `filterHistogramByLockedBins`, Scatterplot's
+     * `filterScatterplotByLockedPoints`, Table's `filterTableByLockedRows`.
+     */
+    filterFn?: (data: unknown, lockedItems: readonly K[], filterKey?: string | number) => unknown;
+    /**
+     * Configuration the filter needs beyond the locked set — Table's
+     * `keyColumn`, say. Handed to `filterFn` as its third argument, so the
+     * filter can go by reference:
+     * `filterFn={filterTableByLockedRows} filterKey={keyColumn}`.
+     *
+     * Pass it rather than capturing it: `filterFn`'s identity is not a
+     * pipeline dependency (see {@link useMemoPair}), so a fresh closure over a
+     * new key is picked up while nothing re-runs.
+     */
+    filterKey?: string | number;
+}
+/**
+ * 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<K extends LockSelectionKey = LockSelectionKey>({ selection, lockedItems, onLockChange, labels, lockIcon: LockSvg, unlockIcon: UnlockSvg, iconProps, filterFn, filterKey, }: LockSelectionProps<K>): import('react').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.js';
+export { toRelativeData, createPercentFormatter } from './transforms.js';
+export { DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataLabels } from './labels.js';

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.js';
+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.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;
+    };
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Default data-side transform for `RelativeData`: rewrite each
+ * `{ name, value }` datum's `value` to its share of the series total
+ * expressed as 0–100 (matches v1's range). The companion percent
+ * formatter divides by 100 so it can call `Intl.NumberFormat` with
+ * `style: 'percent'`.
+ *
+ * Used by widgets whose series are arrays of `{ name, value }`
+ * objects — bar, pie, timeseries, category. Widgets with a different
+ * data shape pass their own transform via
+ * `<RelativeData transform={...} />`; see `widgets-v2/histogram` and
+ * `widgets-v2/scatterplot` for in-tree examples.
+ *
+ * The denominator is the sum of |value| across the series so mixed-sign
+ * series (e.g. cashflow with inflows + outflows) produce sane signed
+ * shares-of-magnitude. A series whose total magnitude is zero (all-zero
+ * or empty input) is returned unchanged so a stalled or empty data set
+ * doesn't show misleading 0% values. Series whose shape doesn't match
+ * the named-value pattern fall through untouched.
+ */
+export declare const toRelativeData: (input: unknown) => unknown;
+/**
+ * Build a percent formatter using `Intl.NumberFormat`. The returned function
+ * expects values in the 0–100 range (output of {@link toRelativeData}) and
+ * divides by 100 internally before calling `style: 'percent'`.
+ *
+ * Locale: passed straight to `Intl.NumberFormat`. Falls back to the runtime
+ * default when omitted.
+ */
+export declare function createPercentFormatter(locale?: string): (value: number) => string;

package/dist/types/widgets-v2/actions/searcher/filter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Filters a 2D series of `{name, ...}` records by case-insensitive substring on
+ * the `name` field. Keeps the dataset shape (one inner array per series).
+ * Used by the Searcher action's data transform.
+ */
+export declare function filterBySearchText(input: unknown, search: string): unknown;

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

@@ -0,0 +1,4 @@
+export { Searcher, type SearcherProps } from './searcher.js';
+export { SearcherToggle, setSearcherText, type SearcherToggleProps, } from './searcher-toggle.js';
+export { filterBySearchText } from './filter.js';
+export { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels.js';

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

@@ -0,0 +1,7 @@
+export interface SearcherLabels {
+    toggle: string;
+    placeholder: string;
+    clearAriaLabel: string;
+    noResults: string;
+}
+export declare const DEFAULT_SEARCHER_LABELS: SearcherLabels;

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

@@ -0,0 +1,23 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { SearcherLabels } from './labels.js';
+export interface SearcherToggleProps {
+    labels?: Partial<SearcherLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+    /**
+     * Whether the searcher transform is enabled on first mount. Defaults
+     * to `false` so the toggle renders un-pressed and the
+     * `filterBySearchText` transform stays dormant until the user clicks
+     * it. Set to `true` for search-first widgets where the input is the
+     * primary affordance.
+     */
+    initialEnabled?: boolean;
+}
+export declare function SearcherToggle({ labels, icon: Icon, iconProps, initialEnabled, }: SearcherToggleProps): import('react').JSX.Element;
+/**
+ * Imperatively writes the search text into the widget store. Used by the
+ * Searcher input to update text inside transformStates without going through
+ * a re-rendered React subscription.
+ */
+export declare function setSearcherText(widgetId: string, value: string): void;

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

@@ -0,0 +1,11 @@
+import { SearcherLabels } from './labels.js';
+export interface SearcherProps {
+    labels?: Partial<SearcherLabels>;
+    /** Debounce delay before the input value is written to the widget store. */
+    debounceMs?: number;
+}
+/**
+ * Renders only when the matching `<SearcherToggle />` is enabled — drives the
+ * `transformStates['searcher'].searchText` field via a debounced setter.
+ */
+export declare function Searcher({ labels, debounceMs, }: SearcherProps): import('react').JSX.Element | null;