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

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/relative-data/transforms.test.d.ts

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

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';
+export { SearcherToggle, setSearcherText, type SearcherToggleProps, } from './searcher-toggle';
+export { filterBySearchText } from './filter';
+export { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels';

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

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

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

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

@@ -0,0 +1,3 @@
+export { StackToggle, type StackToggleProps } from './stack-toggle';
+export { addStack } from './transforms';
+export { DEFAULT_STACK_TOGGLE_LABELS, type StackToggleLabels } from './labels';

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

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

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

@@ -0,0 +1,10 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { StackToggleLabels } from './labels';
+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-runtime").JSX.Element;

package/dist/types/widgets-v2/actions/stack-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/stack-toggle/transforms.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stack-mode config transform: marks every series with `stack: 'total'` so
+ * ECharts stacks them vertically (bar) or by value (line). Module-level
+ * constant so identity is stable across renders — no `useCallback` needed.
+ *
+ * Widgets that bake series into options at build time get marked in place.
+ * Widgets that build series at data-fusion time (`bar`, `histogram`,
+ * `timeseries`) have no `series` array yet at config-transform time, so we
+ * also emit a single-entry **broadcast template** (`[{ stack: 'total' }]`).
+ * Their option factories merge that template into every series they emit
+ * at fusion time, so the `stack` mark survives end-to-end.
+ */
+export declare const addStack: (option: unknown) => unknown;

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

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

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

@@ -0,0 +1,3 @@
+export { ZoomToggle, type ZoomToggleProps } from './zoom-toggle';
+export { addZoom, createAddZoom, ZOOM_LAYOUT, type ZoomAxis, type CreateAddZoomOptions, } from './transforms';
+export { DEFAULT_ZOOM_TOGGLE_LABELS, type ZoomToggleLabels } from './labels';

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

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

package/dist/types/widgets-v2/actions/zoom-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/zoom-toggle/transforms.d.ts

@@ -0,0 +1,51 @@
+import { Theme } from '@mui/material';
+/** Which chart axis (or axes) zoom applies to. */
+export type ZoomAxis = 'x' | 'y';
+export interface CreateAddZoomOptions {
+    /**
+     * Axes to enable zoom on. Default `['x']` (matches bar / histogram /
+     * timeseries — horizontal pan/zoom on the category axis). Pass
+     * `['x', 'y']` for a scatterplot-style 2D zoom (mouse-wheel scales both
+     * axes; a horizontal slider sits at the bottom for x-range and a
+     * vertical slider sits on the right for y-range).
+     */
+    axes?: readonly ZoomAxis[];
+}
+/**
+ * Theme-bound zoom config transform: adds one inside `dataZoom`
+ * (mouse-wheel + drag) per axis plus a styled slider per axis with the
+ * v1 chrome (blue-tinted filler, secondary-color data preview, white
+ * pill handles, CARTO typography). The x-slider is horizontal at the
+ * bottom; the y-slider is vertical on the right.
+ *
+ * Returned function has stable identity for a given theme + axes
+ * combination; pair with `useMemo` at the call site.
+ *
+ * **No `start` / `end`** are emitted: ECharts defaults to `0–100` on the
+ * first `setOption` and then keeps the runtime slider state across
+ * subsequent merges (no `replaceMerge` for `dataZoom`). Re-running the
+ * transform on data/formatter/RelativeData updates therefore preserves the
+ * user's dragged range instead of snapping it back.
+ */
+export declare function createAddZoom(theme: Theme, options?: CreateAddZoomOptions): (option: unknown) => unknown;
+/**
+ * Back-compat untyped transform — produces the bare `dataZoom` config from
+ * the original v2 implementation. Use {@link createAddZoom} when a theme is
+ * available so the slider matches the v1 styling.
+ *
+ * `start` / `end` are intentionally omitted so ECharts preserves the user's
+ * runtime range across subsequent `setOption` merges (see {@link createAddZoom}).
+ */
+export declare const addZoom: (option: unknown) => unknown;
+/**
+ * Visual layout constants used by the data-fusion mergers (bar, histogram,
+ * timeseries) when laying out the slider against the legend / grid.
+ */
+export declare const ZOOM_LAYOUT: {
+    /** Slider height in px (matches `createAddZoom` output). */
+    readonly sliderHeight: 32;
+    /** Vertical gap between chart grid and the slider. */
+    readonly sliderGap: 8;
+    /** Slider `bottom` when a legend is shown — sits above the legend row. */
+    readonly sliderBottomWithLegend: 28;
+};

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

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

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

@@ -0,0 +1,35 @@
+import { ComponentType } from 'react';
+import { SvgIconProps } from '@mui/material';
+import { ZoomAxis } from './transforms';
+import { ZoomToggleLabels } from './labels';
+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-runtime").JSX.Element;

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

@@ -0,0 +1,24 @@
+import { DownloadItem } from '../actions/download';
+import { BarWidgetData } from './types';
+export interface BarDownloadConfigArgs {
+    filename: string;
+    getData: () => 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?: () => 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

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

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

@@ -0,0 +1,43 @@
+import { OptionFactory } from '../echart';
+import { BarEChartsOption, BarOptionFactoryInput, BarOptionsInput } from './types';
+/**
+ * Builds the **structural** ECharts option for a bar widget — axes, grid,
+ * tooltip styling, themed legend. Intentionally data-agnostic: no series,
+ * no dataset, no `legend.show` (those depend on data and are added by the
+ * option factory's merge phase). This separation is what lets data-side
+ * pipeline transforms (Searcher, RelativeData) drive the rendered chart —
+ * the merge happens at render time inside the Echart bridge.
+ *
+ * Styling matches the v1 `barConfig` look-and-feel: minimal axes (only
+ * min/max y-labels rendered inside the plot via `niceNum`), themed tooltip,
+ * scroll legend, and CARTO color palette. The y-axis min/max + label
+ * formatter and the tooltip formatter are wired here for the no-data case;
+ * {@link createBarOptionFactory} re-derives them at fusion time so reactive
+ * formatter changes (RelativeData) and stack templates (StackToggle) flow
+ * through to the chart.
+ */
+export declare function barOptions({ theme, formatter, labelFormatter, }: BarOptionsInput): BarEChartsOption;
+/**
+ * Returns the bar widget's {@link OptionFactory} — a single closure that
+ * handles BOTH option-construction phases:
+ *
+ *   - **Structural phase** (`option == null`) — builds the theme-aware
+ *     structural option via {@link barOptions}, optionally merging the
+ *     consumer-supplied `optionsOverride` on top. Called once by Provider
+ *     to seed `rawOptions` in the store; configTransforms (StackToggle /
+ *     ZoomToggle / BrushToggle) then mutate it via the pipeline middleware.
+ *   - **Merge phase** (`option != null`) — fuses post-pipeline `state.data`
+ *     (`BarWidgetData`) into the option via the dataset API: one dataset
+ *     per series, each series referencing its dataset by index, encoded
+ *     by `name` (x) and `value` (y). Spreads any series-template fields
+ *     already on the incoming option (e.g. `{ stack: 'total' }` from
+ *     `addStack`) into every emitted series so configTransforms compose
+ *     end-to-end. Reactive `ctx.formatter` / `ctx.labelFormatter` drive
+ *     the y-axis min/max-only label and the tooltip formatter at fusion
+ *     time so RelativeData's percent formatter flows through without a
+ *     structural rebuild.
+ *
+ * Stable identity when the inputs don't change (consumers should wrap the
+ * call in `useMemo` keyed on the same inputs).
+ */
+export declare function createBarOptionFactory(options: BarOptionFactoryInput): OptionFactory;

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

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

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

@@ -0,0 +1,6 @@
+/**
+ * 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-runtime").JSX.Element;

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

@@ -0,0 +1,46 @@
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types';
+/** 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

@@ -0,0 +1,81 @@
+import { CategoryKey, CategoryLabels, CategorySeriesConfig, CategorySize, CategoryWidgetData } from './types';
+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 italic "Other (X more)" footer.
+     *   `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;
+    /** 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;
+}
+/**
+ * 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, maxOverride, size, stacked, }: CategoryUIProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,48 @@
+import { CategoryKey, CategoryLabels, CategorySeriesConfig, CategorySize } from './types';
+export interface CategoryProps {
+    /** Currently-selected category names. Destination-owned. */
+    selection?: readonly CategoryKey[];
+    /** Fires when a row is clicked. Consumer updates the destination's store. */
+    onSelectionChange?: (next: readonly CategoryKey[]) => void;
+    /** Per-series metadata. Enables the legend + overrides palette per index. */
+    series?: readonly CategorySeriesConfig[];
+    /**
+     * Cap visible rows; overflow folds into "Other (X more)". Default 20
+     * (when omitted). Pass `0` to swap the cap for a scrollable viewport
+     * (composers use this when the user opens the SearcherToggle —
+     * `maxItems = searcherOpen ? 0 : userMaxItems`). Pass `null` to disable
+     * the cap entirely without adding a scroll viewport.
+     */
+    maxItems?: number | null;
+    /** Labels for the "Other" overflow row. */
+    labels?: CategoryLabels;
+    /**
+     * Manual override for the bar-width denominator. When omitted, the
+     * bridge auto-fills from the widget store's `rawData` so bar widths
+     * stay coherent across data transforms (e.g., the Searcher filtering
+     * rows in and out — bars don't rescale just because the larger rows
+     * got hidden). Pass an explicit number to fix the denominator
+     * regardless of the data.
+     */
+    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. Forwarded as-is to {@link CategoryUI}.
+     */
+    size?: CategorySize;
+    /**
+     * Multi-series stacked mode. Forwarded as-is to {@link CategoryUI}.
+     * Composers typically wire this from
+     * `useTransformEnabled(id, 'stack-toggle')`. No-op for single-series.
+     */
+    stacked?: boolean;
+}
+/**
+ * Stateful Category bridge — reads `data`, `formatter`, and
+ * `labelFormatter` (post-pipeline) from the per-widget store and
+ * forwards them to the pure {@link CategoryUI}. `selection` and
+ * `onSelectionChange` follow the destination-owned principle: the
+ * consumer keeps the list in their own store and passes it through.
+ */
+export declare function Category({ selection, onSelectionChange, series, maxItems, labels, maxOverride, size, stacked, }: CategoryProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,28 @@
+import { CategorySize } from '../types';
+export interface CategoryBarStackedProps {
+    /** One value per series. Zero values render no segment (visually + in the DOM). */
+    values: readonly number[];
+    /** One color per series. Resolved upstream by `CategoryUI.colorAt`. */
+    colors: readonly string[];
+    /**
+     * Shared denominator across all rows + series (or `maxOverride`). Same
+     * value `CategoryBar` uses — segments scale identically to single-bar rows
+     * so cross-row comparison is preserved.
+     */
+    maxValue: number;
+    /** Visual density. Forwarded to the track styling; segments inherit height. */
+    size?: CategorySize;
+}
+/**
+ * Stacked horizontal bar: one rounded track containing N square segments
+ * placed side-by-side. Each segment's width is `value_i / maxValue * 100%`
+ * and its left offset is the cumulative sum of preceding values. Square
+ * interior edges + the parent track's `overflow: hidden` + rounded radius
+ * mean the outer ends of the stacked bar match a single `CategoryBar` while
+ * interior segment boundaries meet cleanly.
+ *
+ * Pure presentation — selection / dimming is resolved upstream by the row
+ * via the `colors` prop. Each segment carries `data-bar-fill='true'` so the
+ * existing row-hover brightening selector still fires on every segment.
+ */
+export declare function CategoryBarStacked({ values, colors, maxValue, size, }: CategoryBarStackedProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,23 @@
+import { CategorySize } from '../types';
+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-runtime").JSX.Element;

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

@@ -0,0 +1,18 @@
+import { CategorySeriesConfig } from '../types';
+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;
+}
+/**
+ * Sticky color legend rendered below a multi-series Category list.
+ * Per-series `color` overrides the matching `colorAt(i)` result.
+ */
+export declare function CategoryLegend({ series, colorAt }: CategoryLegendProps): import("react/jsx-runtime").JSX.Element | null;