@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,46 +0,0 @@
-import { ReactElement } from 'react';
-/**
- * Passed to {@link DownloadItem.resolve} by `<Widget.Download>`.
- */
-export interface DownloadContext {
-    /**
-     * Id of the widget store the menu was opened from — the dialog's own
-     * store when opened from `FullScreen.Slot`'s header, so an export matches
-     * what the user is looking at. `null` outside a `<Widget.Provider>`.
-     */
-    id: string | null;
-}
-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: (ctx: DownloadContext) => Promise<{
-        url: string;
-        filename: string;
-        revoke?: () => void;
-    }>;
-}

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

@@ -1,85 +0,0 @@
-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 {
-    /**
-     * The widget body. Rendered twice, identically: in the card, and again in
-     * the dialog while it's open. The components inside don't know which copy
-     * they are; the dialog's just runs on a widget store of its own — a copy
-     * of the card's taken on open, handed back to the card on close — so read
-     * the widget id with `useWidgetId()` inside the body rather than closing
-     * over the card's `id`.
-     *
-     * @deprecated The function form `(isFullScreen) => ReactNode` still works
-     * (`false` for the card, `true` for the dialog copy) but will be removed
-     * in the next major: pass the body as plain children.
-     */
-    children: ReactNode | ((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;
-/** Id of the widget store the dialog copy runs on. */
-export declare function fullScreenStoreId(id: string): string;
-/**
- * Body wrapper. The card keeps its copy of the body while the dialog is
- * open, and the dialog mounts a second one on a store of its own: a copy
- * of the card's UI state taken on open, and handed back to the card when
- * the dialog closes. While open the two don't affect each other. MUI
- * mounts the dialog copy on open and unmounts it after the close
- * transition, which drops its store.
- */
-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} />}>
- *     <Body />
- *   </Widget.FullScreen.Slot>
- * </Widget.Content>
- * ```
- */
-export declare const FullScreen: {
-    Trigger: typeof FullScreenTrigger;
-    Slot: typeof FullScreenSlot;
-};
-export {};

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

@@ -1,14 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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 DownloadContext, 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/lock-selection.d.ts

@@ -1,57 +0,0 @@
-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/relative-data/relative-data.d.ts

@@ -1,39 +0,0 @@
-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/searcher/searcher-toggle.d.ts

@@ -1,23 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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;

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

@@ -1,10 +0,0 @@
-import { ComponentType } from 'react';
-import { SvgIconProps } from '@mui/material';
-import { StackToggleLabels } from './labels.js';
-export interface StackToggleProps {
-    initialEnabled?: boolean;
-    labels?: Partial<StackToggleLabels>;
-    icon?: ComponentType<SvgIconProps>;
-    iconProps?: SvgIconProps;
-}
-export declare function StackToggle({ initialEnabled, labels, icon: Icon, iconProps, }: StackToggleProps): import('react').JSX.Element;

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

@@ -1,12 +0,0 @@
-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/zoom-toggle/style.d.ts

@@ -1,12 +0,0 @@
-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/zoom-toggle/zoom-toggle.d.ts

@@ -1,35 +0,0 @@
-import { ComponentType } from 'react';
-import { SvgIconProps } from '@mui/material';
-import { ZoomAxis } from './transforms.js';
-import { ZoomToggleLabels } from './labels.js';
-export interface ZoomToggleProps {
-    initialEnabled?: boolean;
-    labels?: Partial<ZoomToggleLabels>;
-    icon?: ComponentType<SvgIconProps>;
-    iconProps?: SvgIconProps;
-    /**
-     * Which axes the zoom controls. Default `['x']` — matches bar /
-     * histogram / timeseries (horizontal pan on the category axis). Pass
-     * `['x', 'y']` for 2D zoom on a scatterplot-style chart (mouse-wheel
-     * scales both axes; horizontal slider at bottom + vertical slider on
-     * the right).
-     */
-    axes?: readonly ZoomAxis[];
-}
-/**
- * Toggle a `dataZoom` slider + wheel-zoom on the chart. The transform is
- * theme-bound so the slider gets v1's CARTO chrome (blue-tinted filler,
- * secondary-color preview, white pill handles).
- *
- * `dataZoom` is intentionally NOT in `replaceMergeKeys` — ECharts merges
- * subsequent `setOption` calls so the user's dragged range survives
- * unrelated re-renders (data updates, formatter swaps, RelativeData toggles).
- *
- * On disable the transform is unregistered, but ECharts' merge semantics
- * would otherwise *keep* the live `dataZoom` component visible. To remove
- * the slider immediately we issue a one-shot
- * `setOption({}, { replaceMerge: ['dataZoom'] })` against the live chart
- * instance via {@link getEchartInstance} — this bypasses the pipeline so
- * unrelated transforms aren't disturbed.
- */
-export declare function ZoomToggle({ initialEnabled, labels, icon: Icon, iconProps, axes, }: ZoomToggleProps): import('react').JSX.Element;

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

@@ -1,24 +0,0 @@
-import { DownloadContext, DownloadItem } from '../actions/download/index.js';
-import { BarWidgetData } from './types.js';
-export interface BarDownloadConfigArgs {
-    filename: string;
-    getData: (ctx: DownloadContext) => BarWidgetData;
-    /**
-     * Optional getter for the widget's capture element (registered by
-     * `Widget.State` on its success path). When provided, a PNG item is
-     * prepended to the returned list. Wire it to
-     * `() => getCaptureEl(id)`.
-     */
-    getCaptureEl?: (ctx: DownloadContext) => HTMLElement | null;
-    /** PNG `pixelRatio` (default 2). */
-    pngPixelRatio?: number;
-    /** PNG `backgroundColor` (default transparent). */
-    pngBackgroundColor?: string | null;
-}
-/**
- * Builds download items for the Bar widget. Always includes a CSV item
- * with one `name,value` block per series, separated by an empty row when
- * there are multiple. When `getCaptureEl` is supplied, also prepends a PNG
- * item that rasterises the captured element via `html2canvas`.
- */
-export declare function createBarDownloadConfig(args: BarDownloadConfigArgs): DownloadItem[];

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

@@ -1,4 +0,0 @@
-export { barOptions, createBarOptionFactory } from './options.js';
-export { BarSkeleton } from './skeleton.js';
-export { createBarDownloadConfig } from './download.js';
-export type { BarDatum, BarWidgetData, BarOptionsInput, BarOptionFactoryInput, BarEChartsOption, } from './types.js';

package/dist/types/widgets-v2/bar/skeleton.d.ts

@@ -1,6 +0,0 @@
-/**
- * Loading state for the Bar widget. Mirrors a bar chart's silhouette — five
- * vertical bars at staggered heights anchored to the bottom, plus a legend
- * stub — so the skeleton reads as "a bar chart" rather than a generic list.
- */
-export declare function BarSkeleton(): import('react').JSX.Element;

package/dist/types/widgets-v2/bar/types.d.ts

@@ -1,46 +0,0 @@
-import { Theme } from '@mui/material';
-import { EChartsOption } from 'echarts';
-import { WidgetSeries } from '../types.js';
-/** A single category entry in a bar series. */
-export interface BarDatum {
-    name: string | number;
-    value: number;
-}
-/** v2 bar widget data shape: array of series, each a flat list of `{name, value}`. */
-export type BarWidgetData = readonly (readonly BarDatum[])[];
-/** Inputs to the structural-only {@link barOptions} builder. */
-export interface BarOptionsInput {
-    theme: Theme;
-    formatter?: (value: number) => string;
-    labelFormatter?: (value: string | number) => string | number;
-}
-/**
- * Combined inputs for the option factory creator. Carries everything the
- * widget needs across BOTH phases — the structural-build (`theme`,
- * `formatter`, `labelFormatter`, `optionsOverride`) AND the data merge
- * (`series`, `selection`).
- */
-export interface BarOptionFactoryInput {
-    theme: Theme;
-    formatter?: (value: number) => string;
-    labelFormatter?: (value: string | number) => string | number;
-    /**
-     * Per-series metadata — drives the legend, `series[i].name`, and
-     * (when `color` is set) per-series `itemStyle.color`. Paired with the
-     * data series by index.
-     */
-    series?: readonly WidgetSeries[];
-    /**
-     * When set, every datum whose `name` is **not** in this list renders dimmed
-     * (`itemStyle.opacity: 0.15`, matching `outOfBrush` styling). `null`/empty
-     * means "no selection active" — every bar is fully opaque.
-     */
-    selection?: readonly (string | number)[] | null;
-    /**
-     * Consumer-supplied partial option merged into the structural option at
-     * structural-build time (via `mergeOptions`). Lets stories override pieces
-     * of the theme-aware base without forking the structural builder.
-     */
-    optionsOverride?: Partial<EChartsOption>;
-}
-export type BarEChartsOption = EChartsOption;

package/dist/types/widgets-v2/category/category-ui.d.ts

@@ -1,96 +0,0 @@
-import { CategoryKey, CategoryLabels, CategorySeriesConfig, CategorySize, CategoryWidgetData } from './types.js';
-export interface CategoryUIProps {
-    data: CategoryWidgetData;
-    /** Currently-selected category names (destination-owned). */
-    selection?: readonly CategoryKey[];
-    /** Fires with the next selection set when a row is clicked. */
-    onSelectionChange?: (next: readonly CategoryKey[]) => void;
-    /** Number formatter applied to each row's value. */
-    formatter?: (value: number) => string;
-    /**
-     * Display-only transform for category names. Selection callbacks always
-     * receive the raw `item.name` regardless of this formatter.
-     */
-    labelFormatter?: (value: string | number) => string | number;
-    /**
-     * Per-series metadata. Enables the legend (for multi-series) and
-     * overrides palette colors per series index. Length need not match
-     * `data.length`; mismatches degrade gracefully (extras ignored, gaps
-     * fall back to palette).
-     */
-    series?: readonly CategorySeriesConfig[];
-    /**
-     * Caps the number of visible category rows.
-     *
-     * - `undefined` (omitted) — caps at {@link DEFAULT_MAX_ITEMS} (20).
-     *   Surplus rows fold into a single "Others <count>" footer row.
-     *   `undefined` cannot mean "no cap" because it's consumed by the
-     *   default-parameter syntax — pass `null` instead.
-     * - positive finite N — same as the default but with a custom cap.
-     * - `0` — **no cap WITH scroll**: every row renders inside a
-     *   fixed-height viewport that scrolls internally. The viewport's
-     *   max-height is the list's natural `clientHeight` measured on the
-     *   first render where the list was NOT in scroll mode (i.e., the
-     *   capped view) — frozen for the component's lifetime. If the
-     *   consumer mounts directly into scroll mode and we never see a
-     *   capped render, the viewport falls back to `8 × ROW_HEIGHT_PX`.
-     *   Composers flip into this mode while the user is searching
-     *   (`maxItems = searcherOpen ? 0 : userMaxItems`) so the widget
-     *   card height stays stable.
-     * - `null` / `Infinity` / negative — **no cap, no scroll**: render
-     *   every row; the list grows with content. Matches v1's "undefined"
-     *   behavior. Use `null` as the canonical explicit form.
-     */
-    maxItems?: number | null;
-    /** Labels for the "Other" overflow row. `{count}` placeholder is replaced. */
-    labels?: CategoryLabels;
-    /**
-     * When provided, the "Other" overflow row becomes a button — clicking it
-     * fires `onShowAll`, which a composer typically wires to expand the widget
-     * (drop the row cap) so every category becomes reachable. When omitted the
-     * overflow row stays a static summary.
-     */
-    onShowAll?: () => void;
-    /** Manual override for the bar-width denominator. */
-    maxOverride?: number;
-    /**
-     * Visual density of the bar primitive. `'small'` (default) keeps the
-     * historical 4px-tall pill; `'medium'` switches to a 12px-tall track
-     * with a 2px corner radius. Only the bar track + fill change.
-     */
-    size?: CategorySize;
-    /**
-     * Multi-series stacked mode. When `true` and `data.length > 1`, each
-     * category renders as a single segmented bar (one segment per series)
-     * with a `formatter(sum)` total in the header and a per-series
-     * breakdown line below. Composers typically thread this from
-     * `useTransformEnabled(id, 'stack-toggle')`.
-     *
-     * No-op for single-series data — same convention as the legend.
-     */
-    stacked?: boolean;
-    /**
-     * Series indices hidden via the legend. Leave both this and
-     * `onHiddenSeriesChange` unset and CategoryUI keeps the set itself; pass
-     * them to own it — `Category` does, so the card and the fullscreen copy
-     * share it through the widget store.
-     */
-    hiddenSeries?: ReadonlySet<number>;
-    onHiddenSeriesChange?: (next: ReadonlySet<number>) => void;
-}
-/**
- * Pure presentational component for the Category widget. Renders
- * single-series rows (`data.length === 1`) as a compact grid or
- * multi-series rows (`data.length > 1`) as stacked-bar groups, capped at
- * `maxItems` with an overflow summary, and an optional sticky color
- * legend when `series` metadata is supplied.
- *
- * Selection is destination-owned: clicking a row fires
- * `onSelectionChange(next)` with the toggled set; the consumer keeps the
- * list in their own store. `aria-pressed` + Enter/Space keyboard
- * activation give full a11y parity with the mouse path.
- *
- * Returns `null` when there's nothing to render — `Widget.State` is the
- * empty-state authority in the canonical compositor.
- */
-export declare function CategoryUI({ data, selection, onSelectionChange, formatter, labelFormatter, series, maxItems, labels, onShowAll, maxOverride, size, stacked, hiddenSeries: hiddenSeriesProp, onHiddenSeriesChange, }: CategoryUIProps): import('react').JSX.Element | null;

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

@@ -1,23 +0,0 @@
-import { CategorySize } from '../types.js';
-export interface CategoryBarProps {
-    /** Numeric value driving the fill width. */
-    value: number;
-    /** Denominator for the percentage fill. `0` → empty bar (no division by zero). */
-    maxValue: number;
-    /** Fill color. Honors any CSS color or MUI theme token. */
-    color: string;
-    /**
-     * Visual density. `'small'` (default) keeps the historical 4px pill;
-     * `'medium'` renders a 12px-tall track with a 2px corner radius. Only
-     * the bar track + fill change — every other token in the parent row is
-     * size-invariant.
-     */
-    size?: CategorySize;
-}
-/**
- * Single horizontal bar (track + proportional fill). Pure presentation.
- * Selection / dimming live at the row level; this component is unaware of
- * both — bars stay vivid regardless of selection state (per the v2
- * "row-bg + row-dim, never muted bar" rule).
- */
-export declare function CategoryBar({ value, maxValue, color, size, }: CategoryBarProps): import('react').JSX.Element;

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

@@ -1,34 +0,0 @@
-import { CategorySeriesConfig } from '../types.js';
-export interface CategoryLegendProps {
-    /** Series metadata. Empty array → renders nothing. */
-    series: readonly CategorySeriesConfig[];
-    /**
-     * Per-series colour resolver. Receives the series index and returns the
-     * palette colour (or `undefined` to fall back to the MUI default). The
-     * legend derives its dot colour from this on the fly — the caller does
-     * NOT pre-compute a `colors` array (avoids passing two views of the
-     * same source).
-     */
-    colorAt: (index: number) => string | undefined;
-    /**
-     * Series indices currently hidden from the chart. Renders dimmed.
-     * Optional — defaults to none hidden. Added after this component's first
-     * release; kept optional (not required) so it stays a non-breaking
-     * addition for any direct consumer of `CategoryLegend` (a public
-     * subpath export) that predates the hide feature.
-     */
-    hiddenSeries?: ReadonlySet<number>;
-    /**
-     * Fires with the series index when its legend item is clicked. Optional
-     * — omitting it renders a legend with no hide affordance (same
-     * reasoning as `hiddenSeries`).
-     */
-    onToggle?: (index: number) => void;
-}
-/**
- * Sticky color legend rendered below a multi-series Category list.
- * Per-series `color` overrides the matching `colorAt(i)` result. Clicking an
- * item toggles that series' visibility in the rows above (mirrors ECharts'
- * native legend click-to-hide).
- */
-export declare function CategoryLegend({ series, colorAt, hiddenSeries, onToggle, }: CategoryLegendProps): import('react').JSX.Element | null;

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

@@ -1,31 +0,0 @@
-import { CategoryKey, CategorySize } from '../types.js';
-export interface CategoryRowMultiProps {
-    /** Raw category key — what gets emitted to `onToggle`. */
-    name: CategoryKey;
-    /** Display label (post-`labelFormatter`). Falls back to `name`. */
-    displayName?: string | number;
-    /** One value per series. `0` is rendered as an empty bar (track only). */
-    values: readonly number[];
-    /** One color per series (palette + per-series overrides resolved upstream). */
-    colors: readonly string[];
-    /** Shared max across all series + rows (or `maxOverride`). */
-    maxValue: number;
-    formatter: (n: number) => string;
-    selected: boolean;
-    onToggle: (name: CategoryKey) => void;
-    /** Bar visual density. Forwarded to every {@link CategoryBar} in the row. */
-    size?: CategorySize;
-}
-/**
- * Multi-series category row: label spans the top; bar+value pairs stack
- * vertically below, one per series. Each bar uses the full row width
- * track (no shared grid) for legibility at N>=2 series. Click anywhere
- * in the row (label OR any bar/value) toggles selection by `name`.
- *
- * Visual selection / dim signal lives ENTIRELY in the bar colors
- * (`colors` prop) — every series in a dimmed row receives
- * `theme.palette.action.disabled`; selected / unselected-no-selection
- * rows receive their real palette colors. Computed upstream by
- * `CategoryUI`. The row itself has no bg tint, no opacity rule.
- */
-export declare function CategoryRowMulti({ name, displayName, values, colors, maxValue, formatter, selected, onToggle, size, }: CategoryRowMultiProps): import('react').JSX.Element;