@carto/ps-react-ui 5.1.0 → 6.0.0

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

@@ -1,5 +1,88 @@
-import { CategoryUIProps } from './types.js';
+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;
+}
 /**
- * Renders a category widget displaying horizontal bars for categorical data with support for single and multi-series layouts, selection, and overflow grouping.
+ * 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({ id }: CategoryUIProps): import('react').JSX.Element | null;
+export declare function CategoryUI({ data, selection, onSelectionChange, formatter, labelFormatter, series, maxItems, labels, onShowAll, maxOverride, size, stacked, }: CategoryUIProps): import('react').JSX.Element | null;

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

@@ -1,9 +1,10 @@
+import { CssColor } from '../../../components/types.js';
 import { CategorySize } from '../types.js';
 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[];
+    colors: readonly CssColor[];
     /**
      * Shared denominator across all rows + series (or `maxOverride`). Same
      * value `CategoryBar` uses — segments scale identically to single-bar rows

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

@@ -1,10 +1,24 @@
+import { CssColor } from '../../../components/types.js';
+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;
-    color: string;
-    selected?: boolean;
+    /** Fill color, already resolved by `CategoryUI.colorAt`. */
+    color: CssColor;
+    /**
+     * 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;
 }
 /**
- * Renders a single horizontal bar fill proportional to its value relative to the maximum.
+ * 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, selected, }: CategoryBarProps): import('react').JSX.Element;
+export declare function CategoryBar({ value, maxValue, color, size, }: CategoryBarProps): import('react').JSX.Element;

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

@@ -1,9 +1,35 @@
+import { CssColor } from '../../../components/types.js';
 import { CategorySeriesConfig } from '../types.js';
 export interface CategoryLegendProps {
-    series: CategorySeriesConfig[];
-    colors: string[];
+    /** 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) => CssColor | 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;
 }
 /**
- * Renders a color-coded legend for multi-series category widgets.
+ * 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, colors }: CategoryLegendProps): import('react').JSX.Element | null;
+export declare function CategoryLegend({ series, colorAt, hiddenSeries, onToggle, }: CategoryLegendProps): import('react').JSX.Element | null;

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

@@ -1,15 +1,32 @@
-import { CategoryWidgetConfig } from '../types.js';
+import { CssColor } from '../../../components/types.js';
+import { CategoryKey, CategorySize } from '../types.js';
 export interface CategoryRowMultiProps {
-    name: string;
-    values: number[];
+    /** 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 CssColor[];
+    /** Shared max across all series + rows (or `maxOverride`). */
     maxValue: number;
-    colors: string[];
-    formatter: NonNullable<CategoryWidgetConfig['formatter']>;
-    labelFormatter?: CategoryWidgetConfig['labelFormatter'];
-    onClick?: CategoryWidgetConfig['onRowClick'];
-    selected?: boolean;
+    formatter: (n: number) => string;
+    selected: boolean;
+    onToggle: (name: CategoryKey) => void;
+    /** Bar visual density. Forwarded to every {@link CategoryBar} in the row. */
+    size?: CategorySize;
 }
 /**
- * Renders a multi-series category row with a label and multiple color-coded bars stacked vertically.
+ * 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, values, maxValue, colors, formatter, labelFormatter, onClick, selected, }: CategoryRowMultiProps): import('react').JSX.Element;
+export declare function CategoryRowMulti({ name, displayName, values, colors, maxValue, formatter, selected, onToggle, size, }: CategoryRowMultiProps): import('react').JSX.Element;

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

@@ -1,9 +1,26 @@
 export interface CategoryRowOtherProps {
     hiddenCount: number;
+    /** Label for the overflow row. Defaults to `'Others'`. */
     otherLabel?: string;
+    /** Count text with `{count}` placeholder. Defaults to `'{count}'`. */
     otherCountLabel?: string;
+    /**
+     * When provided, the row becomes a button: clicking it (or Enter/Space)
+     * fires `onShowAll`, expanding the widget to reveal every category. When
+     * omitted the row renders as a static, non-interactive summary.
+     */
+    onShowAll?: () => void;
+    /** Tooltip shown over the button form. Defaults to `'Show all'`. */
+    showAllLabel?: string;
 }
 /**
- * Renders an "Other" summary row indicating how many additional categories are hidden beyond `maxItems`.
+ * Overflow summary row rendered after the last visible category row when
+ * `data.length > maxItems`. Shows `Others <count>` (count muted, no
+ * parentheses).
+ *
+ * When `onShowAll` is supplied the row is an interactive button — clicking
+ * it (or Enter/Space) expands the widget to show all categories, mirroring
+ * the Searcher's full-list view. Without `onShowAll` it stays a static,
+ * non-interactive summary (backward-compatible default).
  */
-export declare function CategoryRowOther({ hiddenCount, otherLabel, otherCountLabel, }: CategoryRowOtherProps): import('react').JSX.Element;
+export declare function CategoryRowOther({ hiddenCount, otherLabel, otherCountLabel, onShowAll, showAllLabel, }: CategoryRowOtherProps): import('react').JSX.Element;

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

@@ -1,15 +1,29 @@
-import { CategoryWidgetConfig } from '../types.js';
+import { CssColor } from '../../../components/types.js';
+import { CategoryKey, CategorySize } from '../types.js';
 export interface CategoryRowSingleProps {
-    name: string;
+    /** Raw category key — what gets emitted to `onToggle` regardless of formatter. */
+    name: CategoryKey;
+    /** Display label (post-`labelFormatter`). Falls back to `name` when omitted. */
+    displayName?: string | number;
     value: number;
     maxValue: number;
-    color: string;
-    formatter: NonNullable<CategoryWidgetConfig['formatter']>;
-    labelFormatter?: CategoryWidgetConfig['labelFormatter'];
-    onClick?: CategoryWidgetConfig['onRowClick'];
-    selected?: boolean;
+    color: CssColor;
+    formatter: (n: number) => string;
+    selected: boolean;
+    onToggle: (name: CategoryKey) => void;
+    /** Bar visual density. Forwarded to {@link CategoryBar}. */
+    size?: CategorySize;
 }
 /**
- * Renders a single-series category row with a label, formatted value, and proportional bar.
+ * Single-series category row: `[label] [bar] [value]` grid. Click /
+ * Enter / Space toggles `name` in/out of the selection set via
+ * `onToggle`. Selection key is always the raw `name` — `displayName` is
+ * presentation only.
+ *
+ * Visual selection / dim signal lives ENTIRELY in the bar color
+ * (`color` prop) — computed upstream by `CategoryUI` (real palette
+ * color when selected or no-selection; `theme.palette.action.disabled`
+ * when a selection exists and this row isn't in it). The row itself
+ * has no bg tint, no opacity rule.
  */
-export declare function CategoryRowSingle({ name, value, maxValue, color, formatter, labelFormatter, onClick, selected, }: CategoryRowSingleProps): import('react').JSX.Element;
+export declare function CategoryRowSingle({ name, displayName, value, maxValue, color, formatter, selected, onToggle, size, }: CategoryRowSingleProps): import('react').JSX.Element;

package/dist/types/{widgets-v2 → widgets}/category/components/category-row-stacked.d.ts

@@ -1,3 +1,4 @@
+import { CssColor } from '../../../components/types.js';
 import { CategoryKey, CategorySize } from '../types.js';
 export interface CategoryRowStackedProps {
     /** Raw category key — what gets emitted to `onToggle`. */
@@ -7,7 +8,7 @@ export interface CategoryRowStackedProps {
     /** One value per series. Zero values still appear in the breakdown row. */
     values: readonly number[];
     /** One color per series (palette + per-series overrides resolved upstream). */
-    colors: readonly string[];
+    colors: readonly CssColor[];
     /**
      * Series names for the breakdown row, one per visible series, already
      * resolved by the caller (unnamed series fall back to `Series N` using

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

@@ -1,14 +1,10 @@
-export { CategoryUI } from './category-ui.js';
-export { CategorySkeleton } from './skeleton.js';
-export { categoryConfig, categoryDownloadConfig } from './config.js';
-export { CategoryBar } from './components/category-bar.js';
-export type { CategoryBarProps } from './components/category-bar.js';
-export { CategoryRowSingle } from './components/category-row-single.js';
-export type { CategoryRowSingleProps } from './components/category-row-single.js';
-export { CategoryRowMulti } from './components/category-row-multi.js';
-export type { CategoryRowMultiProps } from './components/category-row-multi.js';
-export { CategoryRowOther } from './components/category-row-other.js';
-export type { CategoryRowOtherProps } from './components/category-row-other.js';
-export { CategoryLegend } from './components/category-legend.js';
-export type { CategoryLegendProps } from './components/category-legend.js';
-export type { CategoryUIProps, CategoryWidgetData, CategoryWidgetState, CategoryWidgetConfig, CategoryDownloadConfig, CategoryDataItem, CategorySeriesConfig, CategoryLabels, } from './types.js';
+export { Category, type CategoryProps } from './category.js';
+export { CategoryUI, type CategoryUIProps } from './category-ui.js';
+export { CategorySkeleton, type CategorySkeletonProps } from './skeleton.js';
+export { createCategoryDownloadConfig } from './download.js';
+export { CategoryBar, type CategoryBarProps } from './components/category-bar.js';
+export { CategoryRowSingle, type CategoryRowSingleProps, } from './components/category-row-single.js';
+export { CategoryRowMulti, type CategoryRowMultiProps, } from './components/category-row-multi.js';
+export { CategoryRowOther, type CategoryRowOtherProps, } from './components/category-row-other.js';
+export { CategoryLegend, type CategoryLegendProps, } from './components/category-legend.js';
+export type { CategoryDataItem, CategoryWidgetData, CategoryKey, CategorySeriesConfig, CategoryLabels, CategorySize, } from './types.js';

package/dist/types/widgets/category/skeleton.d.ts

@@ -1 +1,11 @@
-export declare function CategorySkeleton(): import('react').JSX.Element;
+import { CategorySize } from './types.js';
+export interface CategorySkeletonProps {
+    rows?: number;
+    /**
+     * Visual density. Mirrors the live widget's `size` prop so the loading
+     * shimmer's bar height matches what's about to render — no row jump
+     * on data settle.
+     */
+    size?: CategorySize;
+}
+export declare function CategorySkeleton({ rows, size, }: CategorySkeletonProps): import('react').JSX.Element;

package/dist/types/widgets/category/style.d.ts

@@ -1,82 +1,153 @@
-import { Theme } from '@mui/material';
+import { SxProps, Theme } from '@mui/material';
+import { CategorySize } from './types.js';
 export declare const styles: {
     root: {
-        display: "flex";
-        flexDirection: "column";
-        position: "relative";
+        display: string;
+        flexDirection: string;
+        position: string;
         width: string;
     };
     list: {
-        display: "flex";
-        flexDirection: "column";
-        gap: (theme: Theme) => string;
-    };
-    row: {
-        display: "flex";
-        flexDirection: "column";
-        gap: (theme: Theme) => string;
-        pointerEvents: "none";
-    };
-    rowClickable: {
-        pointerEvents: "auto";
+        display: string;
+        flexDirection: string;
+        gap: number;
+        py: number;
+    };
+    listScroll: {
+        pr: number;
+    };
+    rowSingle: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        cursor: string;
+        userSelect: string;
+        transition: string;
+        '&:hover [data-bar-fill="true"]': {
+            filter: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
+        };
     };
     rowHeader: {
-        display: "flex";
-        justifyContent: "space-between";
-        alignItems: "center";
+        display: string;
+        justifyContent: string;
+        alignItems: string;
+        gap: number;
+    };
+    rowMulti: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        cursor: string;
+        userSelect: string;
+        transition: string;
+        '&:hover [data-bar-fill="true"]': {
+            filter: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
+        };
     };
-    rowLabel: {
-        typography: string;
+    name: {
+        overflow: string;
+        whiteSpace: string;
+        textOverflow: string;
+        color: string;
         fontWeight: string;
-        color: "text.primary";
     };
-    rowValue: {
-        typography: string;
-        color: "text.secondary";
+    multiName: {
+        overflow: string;
+        whiteSpace: string;
+        textOverflow: string;
+        color: string;
+        fontWeight: string;
     };
-    barContainer: {
-        display: "flex";
-        flexDirection: "column";
+    value: {
+        color: string;
+        fontVariantNumeric: string;
+        minWidth: number;
+        textAlign: string;
     };
-    bar: {
-        height: number;
-        borderRadius: number;
-        backgroundColor: (theme: Theme) => string;
-        overflow: "hidden";
-        position: "relative";
-        transition: "background-color 0.15s ease-in-out";
-        cursor: "pointer";
-        '&:hover': {
-            backgroundColor: (theme: Theme) => string;
-            '& > div': {
-                filter: "brightness(1.2)";
-            };
+    bar: Record<CategorySize, SxProps<Theme>>;
+    barFill: Record<CategorySize, SxProps<Theme>>;
+    stackedSegment: Record<CategorySize, SxProps<Theme>>;
+    multiBarRow: {
+        display: string;
+        alignItems: string;
+        gap: number;
+    };
+    multiBarContainer: {
+        flex: number;
+    };
+    rowStacked: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        cursor: string;
+        userSelect: string;
+        transition: string;
+        '&:hover [data-bar-fill="true"]': {
+            filter: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
         };
     };
-    barFill: {
-        height: string;
-        borderRadius: number;
-        transition: "width 0.3s ease-in-out, background-color 0.15s ease-in-out";
+    stackedHeader: {
+        display: string;
+        justifyContent: string;
+        alignItems: string;
+        gap: number;
+    };
+    stackedTotal: {
+        color: string;
+        fontWeight: string;
+        fontVariantNumeric: string;
+        minWidth: number;
+        textAlign: string;
     };
-    barFillMuted: {
-        backgroundColor: (theme: Theme) => string;
+    stackedBreakdown: {
+        display: string;
+        flexWrap: string;
+        columnGap: number;
+        rowGap: number;
+    };
+    stackedBreakdownItem: {
+        color: string;
+        fontVariantNumeric: string;
     };
     legend: {
-        display: "flex";
-        alignItems: "center";
-        gap: (theme: Theme) => string;
-        flexWrap: "wrap";
-        paddingTop: (theme: Theme) => string;
-        position: "sticky";
+        display: string;
+        alignItems: string;
+        gap: number;
+        flexWrap: string;
+        pt: number;
+        mt: number;
+        position: string;
         bottom: number;
-        backgroundColor: "background.paper";
+        bgcolor: string;
         borderTop: (theme: Theme) => string;
-        marginTop: (theme: Theme) => string;
     };
     legendItem: {
-        display: "flex";
-        alignItems: "center";
-        gap: (theme: Theme) => string;
+        display: string;
+        alignItems: string;
+        gap: number;
+        cursor: string;
+    };
+    legendItemHidden: {
+        display: string;
+        alignItems: string;
+        gap: number;
+        cursor: string;
+        opacity: number;
     };
     legendDot: {
         width: number;
@@ -84,38 +155,39 @@ export declare const styles: {
         borderRadius: string;
     };
     legendLabel: {
-        typography: string;
-        color: "text.secondary";
-        textTransform: "uppercase";
+        color: string;
+        textTransform: string;
         fontWeight: string;
     };
-    multiBarRow: {
-        display: "flex";
-        alignItems: "center";
-        gap: (theme: Theme) => string;
-    };
-    multiBarValue: {
-        typography: string;
-        color: "text.secondary";
-        minWidth: number;
-        textAlign: "right";
-    };
-    multiBarContainer: {
-        flex: number;
-    };
     otherRow: {
-        display: "flex";
-        justifyContent: "space-between";
-        alignItems: "center";
+        display: string;
+        alignItems: string;
+        gap: number;
+        py: number;
+        px: number;
+    };
+    otherLabelButton: {
+        cursor: string;
+        userSelect: string;
+        borderRadius: number;
+        px: number;
+        ml: number;
+        transition: string;
+        '&:hover': {
+            bgcolor: string;
+        };
+        '&:focus-visible': {
+            outline: string;
+            outlineColor: string;
+            outlineOffset: number;
+        };
     };
     otherLabel: {
-        typography: string;
+        color: string;
         fontWeight: string;
-        color: "text.secondary";
-        fontStyle: "italic";
     };
     otherCount: {
-        typography: string;
-        color: "text.disabled";
+        color: string;
+        fontVariantNumeric: string;
     };
 };