@carto/ps-react-ui 4.7.1 → 4.9.0

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;

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

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

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

@@ -0,0 +1,13 @@
+export interface CategoryRowOtherProps {
+    hiddenCount: number;
+    /** Label for the overflow row. Defaults to `'Other'`. */
+    otherLabel?: string;
+    /** Count text with `{count}` placeholder. Defaults to `'{count} more'`. */
+    otherCountLabel?: string;
+}
+/**
+ * Static "Other (X more)" overflow summary row. Rendered after the last
+ * visible category row when `data.length > maxItems`. Non-interactive —
+ * no selection, no keyboard target.
+ */
+export declare function CategoryRowOther({ hiddenCount, otherLabel, otherCountLabel, }: CategoryRowOtherProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,28 @@
+import { CategoryKey, CategorySize } from '../types';
+export interface CategoryRowSingleProps {
+    /** 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: (n: number) => string;
+    selected: boolean;
+    onToggle: (name: CategoryKey) => void;
+    /** Bar visual density. Forwarded to {@link CategoryBar}. */
+    size?: CategorySize;
+}
+/**
+ * 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, displayName, value, maxValue, color, formatter, selected, onToggle, size, }: CategoryRowSingleProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,38 @@
+import { CategoryKey, CategorySize } from '../types';
+export interface CategoryRowStackedProps {
+    /** 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. Zero values still appear in the breakdown row. */
+    values: readonly number[];
+    /** One color per series (palette + per-series overrides resolved upstream). */
+    colors: readonly string[];
+    /** Series names for the breakdown row. Missing entries fall back to `Series N`. */
+    seriesNames: readonly string[];
+    formatter: (n: number) => string;
+    selected: boolean;
+    onToggle: (name: CategoryKey) => void;
+    /** Bar visual density. Forwarded to the inner {@link CategoryBarStacked}. */
+    size?: CategorySize;
+}
+/**
+ * Stacked-mode category row: label + total share a header line; a single
+ * segmented bar sits below; an inline breakdown lists each series with its
+ * formatted value. Click anywhere in the row toggles selection by `name`.
+ *
+ * Per-row normalization: the stacked bar always fills 100% of the track,
+ * with each segment sized as `value_i / sum(values)`. This is intentionally
+ * different from `CategoryRowMulti` (which scales bars against the global
+ * `maxValue` for cross-row comparison) — in stacked mode the comparable
+ * axis is the proportion of each series within the row, not the row's
+ * total relative to other rows. The total numeric value is still shown in
+ * the header so the per-row magnitude isn't lost.
+ *
+ * Visual selection / dim signal lives entirely in the segment colors
+ * (`colors` prop) — every series in a dimmed row receives
+ * `theme.palette.action.disabled`. The bar visually collapses to a single
+ * grey shape when dimmed, but the breakdown text stays at full color so the
+ * per-series values remain legible.
+ */
+export declare function CategoryRowStacked({ name, displayName, values, colors, seriesNames, formatter, selected, onToggle, size, }: CategoryRowStackedProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,16 @@
+import { DownloadItem } from '../actions/download';
+import { CategoryWidgetData } from './types';
+/**
+ * Download menu items for the Category widget. Always includes a CSV item
+ * with `series, name, value` columns (one row per item). When
+ * `getCaptureEl` is supplied, prepends a PNG item that rasterises the
+ * captured element via `html2canvas`.
+ */
+export declare function createCategoryDownloadConfig(args: {
+    filename: string;
+    getData: () => CategoryWidgetData;
+    seriesNames?: readonly string[];
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

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

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

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

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

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

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

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

@@ -0,0 +1,166 @@
+import { SxProps, Theme } from '@mui/material';
+import { CategorySize } from './types';
+export declare const styles: {
+    root: {
+        display: string;
+        flexDirection: string;
+        position: string;
+        width: string;
+    };
+    list: {
+        display: string;
+        flexDirection: string;
+        gap: number;
+        py: 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: 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;
+        };
+    };
+    name: {
+        overflow: string;
+        whiteSpace: string;
+        textOverflow: string;
+        color: string;
+        fontWeight: string;
+    };
+    multiName: {
+        overflow: string;
+        whiteSpace: string;
+        textOverflow: string;
+        color: string;
+        fontWeight: string;
+    };
+    value: {
+        color: string;
+        fontVariantNumeric: string;
+        minWidth: number;
+        textAlign: string;
+    };
+    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;
+        };
+    };
+    stackedHeader: {
+        display: string;
+        justifyContent: string;
+        alignItems: string;
+        gap: number;
+    };
+    stackedTotal: {
+        color: string;
+        fontWeight: string;
+        fontVariantNumeric: string;
+        minWidth: number;
+        textAlign: string;
+    };
+    stackedBreakdown: {
+        display: string;
+        flexWrap: string;
+        columnGap: number;
+        rowGap: number;
+    };
+    stackedBreakdownItem: {
+        color: string;
+        fontVariantNumeric: string;
+    };
+    legend: {
+        display: string;
+        alignItems: string;
+        gap: number;
+        flexWrap: string;
+        pt: number;
+        mt: number;
+        position: string;
+        bottom: number;
+        bgcolor: string;
+        borderTop: (theme: Theme) => string;
+    };
+    legendItem: {
+        display: string;
+        alignItems: string;
+        gap: number;
+    };
+    legendDot: {
+        width: number;
+        height: number;
+        borderRadius: string;
+    };
+    legendLabel: {
+        color: string;
+        textTransform: string;
+        fontWeight: string;
+    };
+    otherRow: {
+        display: string;
+        justifyContent: string;
+        alignItems: string;
+        py: number;
+        px: number;
+    };
+    otherLabel: {
+        fontStyle: string;
+        color: string;
+        fontWeight: string;
+    };
+    otherCount: {
+        color: string;
+    };
+};

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

@@ -0,0 +1,53 @@
+import { WidgetSeries } from '../types';
+/** A single row in a Category widget. `name` is the category key. */
+export interface CategoryDataItem {
+    name: string | number;
+    value: number;
+    /** Optional per-row color override (wins over series + palette). */
+    color?: string;
+}
+/**
+ * Category widget data — array of series, each a flat list of `{name, value}`.
+ *
+ * Single-series (`data.length === 1`) renders one bar per row.
+ * Multi-series (`data.length > 1`) groups items by `name` across series and
+ * renders N vertically-stacked bars per row, with a sticky legend at the
+ * bottom when `series` metadata is supplied.
+ */
+export type CategoryWidgetData = readonly (readonly CategoryDataItem[])[];
+/**
+ * The keyspace of selectable items. Per the destination-owned selection
+ * principle, the consumer keeps this in their own store.
+ */
+export type CategoryKey = string | number;
+/**
+ * Per-series metadata. Supplied to enable the legend and override the
+ * auto-assigned palette color for a given series index. Length should
+ * mirror `data.length` for a full legend; shorter/longer arrays degrade
+ * gracefully (extra entries ignored; missing entries get palette
+ * defaults and are absent from the legend).
+ */
+/**
+ * Per-series metadata. Type alias of the cross-widget
+ * {@link WidgetSeries} shape (`{ name, color? }`) so Category, Formula,
+ * Spread, and the echart-based widgets all consume the same input
+ * shape. Kept as a named export for backwards compatibility.
+ */
+export type CategorySeriesConfig = WidgetSeries;
+/**
+ * Labels for the "Other" overflow row (rendered when `data.length`
+ * exceeds `maxItems`). `{count}` in `otherCount` is replaced with the
+ * number of hidden categories.
+ */
+export interface CategoryLabels {
+    other?: string;
+    otherCount?: string;
+}
+/**
+ * Visual density of the bar primitive. `'small'` (default) keeps the
+ * original 4px-tall, fully-rounded track. `'medium'` renders a 12px-tall
+ * track with a 2px corner radius (squarer affordance for denser layouts).
+ * Only the bar track + fill are affected — row layout, label typography,
+ * value column, legend, and hover affordance are unchanged.
+ */
+export type CategorySize = 'small' | 'medium';