@carto/ps-react-ui 5.3.0 → 6.1.0

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

@@ -1,35 +1,55 @@
-import { BaseWidgetState, WidgetsStoreProps } from '../stores/types.js';
-import { WrapperState } from '../wrapper/types.js';
-import { DownloadItem } from '../actions/download/types.js';
-export interface CategoryUIProps {
-    id: WidgetsStoreProps['id'];
-}
-export interface CategorySeriesConfig {
-    name: string;
+import { WidgetSeries } from '../types.js';
+/** 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;
+    /** Tooltip shown over the clickable "Others" row. Defaults to `'Show all'`. */
+    showAll?: string;
 }
-export interface CategoryDataItem extends Record<string, string | number> {
-    name: string;
-    value: number;
-}
-export type CategoryWidgetData = CategoryDataItem[][];
-export type CategoryWidgetState = BaseWidgetState<WrapperState<CategoryWidgetConfig> & {
-    data: CategoryWidgetData;
-}>;
-export interface CategoryWidgetConfig {
-    formatter?: (value: number) => string;
-    labelFormatter?: (value: string | number) => string | number;
-    series?: CategorySeriesConfig[];
-    maxItems?: number;
-    labels?: CategoryLabels;
-    onRowClick?: ({ name }: {
-        name: string;
-    }) => void;
-    selected?: (name: string) => boolean;
-    max?: number;
-}
-export type CategoryDownloadConfig = DownloadItem<CategoryWidgetData>[];
+/**
+ * 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';

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

@@ -1,9 +1,44 @@
-import { EchartUIProps } from './types.js';
-/**
- * Presentational component that initializes and manages an Apache ECharts instance.
- *
- * @remarks
- * Handles chart lifecycle (init, dispose), option updates, resize observation, and event listener management.
- * Uses SVG renderer with a default height of 304px.
- */
-export declare function EchartUI(props: EchartUIProps): import('react').JSX.Element;
+import { SxProps, Theme } from '@mui/material';
+import * as echarts from 'echarts';
+export declare const DEFAULT_INIT_OPTS: {
+    renderer: "svg";
+};
+export type EchartsEventHandler = (event: unknown) => void;
+export interface EchartUIProps {
+    option: echarts.EChartsOption;
+    /**
+     * Keys to merge as arrays (replace by index) instead of by id. The middleware
+     * memoizes this content-stably, so identical sets don't re-trigger setOption.
+     */
+    replaceMerge?: readonly string[];
+    /**
+     * Opaque ECharts event passthrough — handlers fire untransformed.
+     *
+     * **Must be referentially stable** (memoize it with `useMemo` /
+     * `useCallback`, or hoist to module scope). The binding effect depends on
+     * the `onEvents` object identity; an inline `{ click: handler }` literal
+     * recreates the object on every render and causes every listener to be
+     * detached and re-attached each commit.
+     */
+    onEvents?: Record<string, EchartsEventHandler>;
+    /**
+     * Init options forwarded to echarts.init. Captured at mount only — to change
+     * `renderer` or `height` after mount, unmount and remount the chart.
+     * Defaults: `{ renderer: 'svg' }` — height is container-driven, so prefer
+     * `sx={{ minHeight }}` over pinning `height` here.
+     */
+    init?: echarts.EChartsInitOpts;
+    /**
+     * Optional callback fired once after the ECharts instance is created
+     * (`onInstance(chart)`) and once when it's about to be disposed
+     * (`onInstance(null)`). Used by `Widget.Echart` to publish the live
+     * instance to the per-widget registry so other actions (e.g.
+     * `ZoomToggle`'s disable handler) can reach it without DOM lookups.
+     * No need to memoize — the bridge wraps it in `useEffectEvent` so an
+     * unstable reference does not re-init the chart.
+     */
+    onInstance?: (chart: echarts.ECharts | null) => void;
+    className?: string;
+    sx?: SxProps<Theme>;
+}
+export declare function EchartUI({ option, replaceMerge, onEvents, init, onInstance, className, sx, }: EchartUIProps): import('react').JSX.Element;

package/dist/types/widgets/echart/echart.d.ts

@@ -1,8 +1,83 @@
-import { EchartProps } from './types.js';
+import { SxProps, Theme } from '@mui/material';
+import { EchartsEventHandler } from './echart-ui.js';
+import type * as echarts from 'echarts';
 /**
- * Stateful EChart widget component that reads data and options from the widget store and renders an ECharts chart.
+ * Reactive context passed to every {@link OptionFactory} call so the
+ * factory can rebuild render-time pieces (axis label / tooltip formatters)
+ * from the live store. Drives RelativeData / consumer-formatter changes
+ * through to the chart without rebuilding the structural option.
+ */
+export interface OptionFactoryContext {
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+}
+/**
+ * The per-widget option factory — a single callable that owns BOTH phases
+ * of option construction:
+ *
+ * - **Structural phase** — when `option == null`, return the theme-aware
+ *   structural option (tooltip / legend / color palette / series
+ *   template, optionally merged with a consumer-supplied `optionsOverride`).
+ *   No data is read. `<Widget.Echart>` calls the factory with
+ *   `(undefined, undefined)` synchronously during render to derive the
+ *   structural base; `configTransforms` (Stack/Zoom/Brush) then mutate it
+ *   in the same render pass.
+ * - **Merge phase** — when `option` is defined, fuse `data` into the
+ *   post-configTransforms option at fusion time. `<Widget.Echart>` calls
+ *   the factory with `(transformed, data, ctx)` on every render.
+ *
+ * The two phases share a closure (the factory creator captures `theme`,
+ * `formatter`, `labelFormatter`, `seriesNames`, `selection`, `optionsOverride`,
+ * …), so structural and merge agree on the same widget configuration.
+ *
+ * The third arg `ctx` carries the **live** store-side formatters at the
+ * call site — distinct from the closure-time formatters because actions
+ * like RelativeData can install a percent formatter on the store after
+ * the factory was constructed. The merge phase reads from `ctx`; the
+ * structural phase typically uses the closure-time values.
+ */
+export type OptionFactory = (option: echarts.EChartsOption | undefined, data: unknown, ctx?: OptionFactoryContext) => echarts.EChartsOption;
+export interface EchartProps {
+    /**
+     * The per-widget {@link OptionFactory}. Required — `<Widget.Echart>`
+     * derives the structural option from it (so configTransforms have a base
+     * to mutate) and fuses `state.data` into the post-pipeline option at
+     * render time. Wrap the factory creator in `useMemo` so its identity is
+     * stable across renders.
+     */
+    optionFactory: OptionFactory;
+    onEvents?: Record<string, EchartsEventHandler>;
+    init?: echarts.EChartsInitOpts;
+    className?: string;
+    /**
+     * Styles for the chart container — this is where its height comes from.
+     * `min-height` defaults to the card height (304px) and `flex: 1` lets the
+     * chart fill a taller parent; override either here, e.g.
+     * `sx={{ minHeight: 400 }}` for a taller card.
+     */
+    sx?: SxProps<Theme>;
+}
+/**
+ * Stateful Echart bridge — owns the entire ECharts coupling. The whole
+ * option pipeline lives here, not in the store:
+ *
+ * 1. **Structural** — `optionFactory(undefined, undefined)` produces the
+ *    theme-aware base. Memoized on the factory identity, so the consumer's
+ *    `useMemo` ID gates the rebuild.
+ * 2. **Transformed** — `applyTransforms(structural, configTransforms)`
+ *    applies any registered configTransforms (Stack/Zoom/Brush) over the
+ *    structural base. Memoized on `[structural, configTransforms]`.
+ * 3. **`replaceMerge`** — derived from the enabled configTransforms'
+ *    `replaceMergeKeys`, deduped and sorted, seeded with
+ *    {@link DEFAULT_REPLACE_MERGE}. Memoized on `[configTransforms]` so
+ *    ECharts sees a stable array reference across non-transform changes.
+ * 4. **Merge** — `optionFactory(transformed, data, ctx)` fuses post-
+ *    pipeline data into the option. Reactive `ctx` carries the live store
+ *    formatters so RelativeData's percent formatter flows through without
+ *    a structural rebuild.
  *
- * @remarks
- * Transforms widget data into ECharts dataset format and delegates rendering to {@link EchartUI}.
+ * The `<Widget.Provider>` doesn't know about the factory at all: it stays
+ * a renderer-agnostic shell. The `ProviderProps` surface has no ECharts
+ * coupling, so non-Echart widgets don't transitively import the type.
  */
-export declare function Echart(props: EchartProps): import('react').JSX.Element | null;
+export declare function Echart({ optionFactory, onEvents, init, className, sx, }: EchartProps): import('react').JSX.Element;

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

@@ -1,5 +1,4 @@
-export { Echart } from './echart.js';
-export { EchartUI } from './echart-ui.js';
-export type { EchartProps, EchartOptionsProps, EchartUIProps, EchartWidgetData, EchartWidgetState, } from './types.js';
-export { getCommonOptions } from './options.js';
-export { mergeEchartWidgetConfig, getEChartBrushConfig, getEChartStackConfig, getEChartZoomConfig, } from './utils.js';
+export { EchartUI, DEFAULT_INIT_OPTS, type EchartUIProps, type EchartsEventHandler, } from './echart-ui.js';
+export { Echart, type EchartProps, type OptionFactory, type OptionFactoryContext, } from './echart.js';
+export { useChartSelection, type SelectionKey, type UseChartSelectionOptions, type ChartSelectionWiring, } from './use-chart-selection.js';
+export { observeResize, __resetSharedResizeObserver, } from './shared-resize-observer.js';

package/dist/types/widgets/echart/shared-resize-observer.d.ts

@@ -1,12 +1,5 @@
-/**
- * Shared ResizeObserver singleton for all ECharts instances.
- *
- * Instead of creating 100+ individual ResizeObserver instances (one per chart),
- * this module provides a single shared observer that efficiently handles resize
- * callbacks for all registered elements.
- */
 type ResizeCallback = () => void;
 export declare function observeResize(element: Element, callback: ResizeCallback): () => void;
-/** Reset the shared observer (for testing only). */
-export declare function resetSharedResizeObserver(): void;
+/** @internal — for tests only. */
+export declare function __resetSharedResizeObserver(): void;
 export {};

package/dist/types/widgets/formula/download.d.ts

@@ -0,0 +1,10 @@
+import { DownloadItem, WidgetDownloadArgs } from '../actions/download/index.js';
+import { FormulaWidgetData } from './types.js';
+export type FormulaDownloadConfigArgs = WidgetDownloadArgs<FormulaWidgetData>;
+/**
+ * Builds download items for the Formula widget. Always includes a CSV item
+ * with one row per KPI (`prefix`, `value`, `suffix`, `note`, `delta`). When
+ * `getCaptureEl` is given, prepends a PNG item that rasterises the captured
+ * element via `html2canvas`.
+ */
+export declare function createFormulaDownloadConfig(args: FormulaDownloadConfigArgs): DownloadItem[];

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

@@ -1,5 +1,20 @@
-import { FormulaUIProps } from './types.js';
+import { Ref } from 'react';
+import { FormulaDataItem } from './types.js';
+export interface FormulaUIProps {
+    items: readonly FormulaDataItem[];
+    /** Number formatter — applied to each item's `value`. */
+    formatter?: (value: number) => string;
+    /** Forwarded to the root `<Box>` so consumers can capture the DOM (PNG export). */
+    ref?: Ref<HTMLDivElement>;
+}
 /**
- * Renders a formula widget displaying one or more KPI values with optional prefixes, suffixes, and series indicators.
+ * Pure presentational component for the Formula widget. Each item renders as
+ * a row containing (in order): optional `Series` avatar, a body with
+ * `[prefix] value [suffix]` plus optional `Note`, and an optional `Delta`
+ * chip pushed to the right edge.
+ *
+ * For fully custom layouts, compose {@link Series}, {@link Prefix},
+ * {@link Value}, {@link Suffix}, {@link Note}, and {@link Delta} directly
+ * instead of passing `items`.
  */
-export declare function FormulaUI(props: FormulaUIProps): import('react').JSX.Element;
+export declare function FormulaUI({ items, formatter, ref }: FormulaUIProps): import('react').JSX.Element;

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

@@ -1,11 +1,11 @@
-export { Item } from './components/item.js';
-export { Value } from './components/value.js';
-export { Prefix } from './components/prefix.js';
-export { Suffix } from './components/suffix.js';
-export { Series } from './components/series.js';
-export { Row } from './components/row.js';
-export { formulaConfig, formulaDownloadConfig } from './config.js';
-export { FormulaUI } from './formula-ui.js';
-export { FormulaSkeleton } from './skeleton.js';
-export { sanitizeDataItem, sanitizeDataItems } from './serializer.js';
-export type { DataItem, FormulaDownloadConfig, FormulaUIProps, FormulaWidgetConfig, FormulaWidgetData, FormulaWidgetState, ItemProps, RowProps, SeriesConfig, ValueProps, } from './types.js';
+export { Formula } from './formula.js';
+export { FormulaUI, type FormulaUIProps } from './formula-ui.js';
+export { Prefix, type PrefixProps } from './prefix.js';
+export { Suffix, type SuffixProps } from './suffix.js';
+export { Value, type ValueProps } from './value.js';
+export { Series, type SeriesProps } from './series.js';
+export { Note, type NoteProps } from './note.js';
+export { Delta, type DeltaProps } from './delta.js';
+export { FormulaSkeleton, type FormulaSkeletonProps } from './skeleton.js';
+export { createFormulaDownloadConfig } from './download.js';
+export type { FormulaDataItem, FormulaWidgetData, FormulaSeries, FormulaDelta, DeltaSeverity, } from './types.js';

package/dist/types/{widgets-v2 → widgets}/formula/series.d.ts

@@ -1,9 +1,10 @@
 import { AvatarProps } from '@mui/material';
+import { PaletteColor } from '../../components/types.js';
 export interface SeriesProps {
     /** Used for the avatar's first-letter glyph and as accessible label. */
     name: string;
     /** Avatar background colour (any MUI palette path or CSS colour). */
-    color?: string;
+    color?: PaletteColor;
     /** Diameter in px. Default `24`. */
     size?: number;
     AvatarProps?: AvatarProps;

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

@@ -1 +1,4 @@
-export declare function FormulaSkeleton(): import('react').JSX.Element;
+export interface FormulaSkeletonProps {
+    count?: number;
+}
+export declare function FormulaSkeleton({ count }: FormulaSkeletonProps): import('react').JSX.Element;

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

@@ -1,21 +1,29 @@
-import { Theme } from '@mui/material';
 export declare const styles: {
     root: {
         display: "flex";
         flexDirection: "column";
-        gap: (theme: Theme) => string;
-    };
-    item: {
-        '&[data-disabled="true"]': {
-            color: (theme: Theme) => string;
-        };
+        gap: number;
+        alignItems: "stretch";
     };
     row: {
         display: "flex";
-        alignItems: "center";
-        gap: (theme: Theme) => string;
-        '& + &': {
-            marginTop: (theme: Theme) => string;
-        };
+        alignItems: "flex-start";
+        gap: number;
+    };
+    body: {
+        flex: number;
+        minWidth: number;
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+    };
+    valueRow: {
+        display: "inline-flex";
+        alignItems: "baseline";
+        gap: number;
+    };
+    delta: {
+        alignSelf: "center";
+        flexShrink: number;
     };
 };

package/dist/types/widgets/formula/types.d.ts

@@ -1,42 +1,44 @@
-import { TypographyProps } from '@mui/material';
-import { ReactNode } from 'react';
-import { BaseWidgetState, WidgetsStoreProps } from '../stores/types.js';
-import { WrapperState } from '../wrapper/types.js';
-import { DownloadItem } from '../actions/download/types.js';
-export interface FormulaUIProps {
-    id: WidgetsStoreProps['id'];
-}
-export interface DataItem {
+import { PaletteColor } from '../../components/types.js';
+import { WidgetSeries } from '../types.js';
+/**
+ * Series metadata rendered as a coloured avatar at the start of a row.
+ *
+ * Type alias of the cross-widget {@link WidgetSeries} shape so the same
+ * `{ name, color? }` object can drive Formula avatars, Spread avatars,
+ * Category legends, and echart-widget legends with no per-widget shape
+ * gymnastics. Kept as a named export for backwards compatibility.
+ */
+export type FormulaSeries = WidgetSeries;
+export type DeltaSeverity = 'positive' | 'negative' | 'neutral';
+/** Comparative delta rendered as a coloured chip on the right of a row. */
+export interface FormulaDelta {
+    /** Numeric magnitude. Default formatting renders as a percent (e.g. `-12,3 %`). */
     value: number;
-    prefix?: string | ReactNode;
-    suffix?: string | ReactNode;
-    color?: string;
-}
-export interface RowProps {
-    id: WidgetsStoreProps['id'];
-    children: ReactNode | ((props: {
-        index: number;
-    }) => ReactNode);
-}
-export interface ValueProps extends Omit<ItemProps, 'children'> {
-    id: WidgetsStoreProps['id'];
-    index?: number;
+    /** Pre-formatted label override (skips the default percent formatter). */
+    label?: string;
+    /**
+     * Visual treatment override. When omitted it's derived from `value`'s sign:
+     * `>0 → 'positive'`, `<0 → 'negative'`, `=0 → 'neutral'`.
+     */
+    severity?: DeltaSeverity;
 }
-export interface ItemProps {
-    children: ReactNode;
-    disabled?: boolean;
-    TypographyProps?: TypographyProps;
-}
-export type FormulaWidgetData = DataItem[];
-export interface SeriesConfig {
-    name: string;
-    color?: string;
-}
-export type FormulaWidgetState = BaseWidgetState<WrapperState<FormulaWidgetConfig> & {
-    data: FormulaWidgetData;
-}>;
-export interface FormulaWidgetConfig {
-    formatter?: (value: number) => string;
-    series?: SeriesConfig[];
+/** A single KPI value rendered by the Formula widget. */
+export interface FormulaDataItem {
+    value: number;
+    prefix?: string;
+    suffix?: string;
+    /** Override the value's text colour (e.g. `'success.main'`). */
+    color?: PaletteColor;
+    /** Optional series indicator — coloured avatar with first letter of `name`. */
+    series?: FormulaSeries;
+    /** Optional caption rendered below the value. */
+    note?: string;
+    /** Optional comparative delta chip rendered to the right of the row. */
+    delta?: FormulaDelta;
 }
-export type FormulaDownloadConfig = DownloadItem<FormulaWidgetData>[];
+/**
+ * Formula widget data — an array of KPI items rendered top-to-bottom. A common
+ * "single big number" widget is just `[{ value: 123 }]`. Multi-series usage
+ * sets `series`, `note`, and/or `delta` per item.
+ */
+export type FormulaWidgetData = readonly FormulaDataItem[];

package/dist/types/{widgets-v2 → widgets}/formula/value.d.ts

@@ -1,9 +1,10 @@
 import { TypographyProps } from '@mui/material';
 import { ReactNode } from 'react';
+import { PaletteColor } from '../../components/types.js';
 export interface ValueProps {
     children: ReactNode;
     /** Override the default `text.primary` color — useful for sparkline tints. */
-    color?: string;
+    color?: PaletteColor;
     TypographyProps?: TypographyProps;
 }
 /**

package/dist/types/widgets/histogram/download.d.ts

@@ -0,0 +1,12 @@
+import { DownloadItem, WidgetDownloadArgs } from '../actions/download/index.js';
+import { HistogramWidgetData } from './types.js';
+/**
+ * Download menu items for histograms. Always includes a CSV item with
+ * `bin_low, bin_high, series_1_count, series_2_count, …` columns (one row
+ * per bin). When `getCaptureEl` is given, prepends a PNG item that
+ * rasterises the captured element via `html2canvas`.
+ */
+export declare function createHistogramDownloadConfig(args: WidgetDownloadArgs<HistogramWidgetData> & {
+    getTicks: () => readonly number[];
+    seriesNames?: readonly string[];
+}): DownloadItem[];

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

@@ -1,4 +1,5 @@
-export type { HistogramConfig, HistogramWidgetConfig, HistogramWidgetData, HistogramWidgetState, } from './types.js';
-export type { HistogramDownloadConfigProps } from './config.js';
-export { histogramConfig, histogramDataToCSV, histogramDownloadConfig, } from './config.js';
-export { HistogramSkeleton } from './skeleton.js';
+export { histogramOptions, createHistogramOptionFactory } from './options.js';
+export { HistogramSkeleton, type HistogramSkeletonProps } from './skeleton.js';
+export { createHistogramDownloadConfig } from './download.js';
+export { toRelativeHistogramData, filterHistogramByLockedBins, } from './transforms.js';
+export type { HistogramWidgetData, HistogramOptionsInput, HistogramOptionFactoryInput, HistogramEChartsOption, } from './types.js';

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

@@ -1 +1,9 @@
-export declare function HistogramSkeleton(): import('react').JSX.Element;
+export interface HistogramSkeletonProps {
+    bins?: number;
+}
+/**
+ * Loading state for the Histogram widget. Mirrors Bar's skeleton structure
+ * — a grid of bars (bin-shaped silhouette, anchored to the bottom) plus a
+ * legend stub — so the placeholder reads consistently with Bar.
+ */
+export declare function HistogramSkeleton({ bins }: HistogramSkeletonProps): import('react').JSX.Element;

package/dist/types/widgets/histogram/types.d.ts

@@ -1,12 +1,60 @@
-import { EchartWidgetState } from '../echart/index.js';
-import { EchartWidgetOptionProps, EchartWidgetProps } from '../echart/types.js';
-import { ConfigProps } from '../loader/index.js';
-export type HistogramWidgetData = number[][];
-export type HistogramWidgetState = EchartWidgetState;
-export type HistogramWidgetConfig = EchartWidgetProps & {
-    type: 'histogram';
-};
-export type HistogramConfig = ConfigProps & Pick<EchartWidgetOptionProps<unknown>, 'theme' | 'formatter' | 'labelFormatter'> & {
-    data?: number[][];
-    ticks: number[];
-};
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+import { WidgetSeries } from '../types.js';
+/**
+ * Histogram widget data — array of series, each a flat array of bin counts.
+ * The option factory's merge phase (see {@link createHistogramOptionFactory})
+ * combines this with `ticks` to produce a 2-column dataset (`[binLabel, count]`)
+ * for ECharts.
+ */
+export type HistogramWidgetData = readonly (readonly number[])[];
+/** Inputs to the structural-only {@link histogramOptions} builder. */
+export interface HistogramOptionsInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+}
+/**
+ * Combined inputs for the histogram option factory creator. Carries
+ * everything the widget needs across BOTH phases — the structural-build
+ * (`theme`, `formatter`, `optionsOverride`) AND the data merge (`ticks`,
+ * `series`, `labelFormatter`, `selection`).
+ */
+export interface HistogramOptionFactoryInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+    /** Bin boundaries — length = bins + 1. */
+    ticks: readonly number[];
+    /**
+     * Per-series metadata — drives the legend, `series[i].name`, and
+     * (when `color` is set) a per-series colour override on the bars.
+     */
+    series?: readonly WidgetSeries[];
+    /**
+     * Bin-range label transform (e.g. `"0–10"` → `"[0–10)"`). Distinct from
+     * the standard `OptionFactoryContext.labelFormatter` (which operates on
+     * categories): this one is histogram-specific and runs only on the
+     * generated bin-range strings before they hit the x-axis.
+     */
+    labelFormatter?: (label: string) => string;
+    /**
+     * Selected bin indices. Bins not in this list render dimmed
+     * (`itemStyle.opacity: 0.15`). `null`/empty means no selection.
+     */
+    selection?: readonly number[] | null;
+    /**
+     * Locked bin indices (from `LockSelection`). The x-axis crops its visible
+     * window to `[min(lockedItems), max(lockedItems)]` so the chart actually
+     * zooms into the locked range instead of showing every bin label with
+     * zeroed-out bars outside it. `null`/empty means no crop. Histogram's
+     * selection is always a contiguous run (`use-widget-filters`'s BETWEEN
+     * envelope round-trip fills any gaps), so min/max fully describes it.
+     */
+    lockedItems?: readonly number[] | null;
+    /**
+     * Consumer-supplied partial option merged into the structural option at
+     * structural-build time. Lets stories override pieces of the theme-aware
+     * base without forking the structural builder.
+     */
+    optionsOverride?: Partial<EChartsOption>;
+}
+export type HistogramEChartsOption = EChartsOption;

package/dist/types/{widgets-v2 → widgets}/index.d.ts

@@ -21,7 +21,7 @@ import { Table, TableUI } from './table/index.js';
  * Consumers import the const and access components via property access:
  *
  * ```tsx
- * import { Widget } from '@carto/ps-react-ui/widgets-v2'
+ * import { Widget } from '@carto/ps-react-ui/widgets'
  *
  * <Widget.Provider id={id} data={data}>
  *   <Widget.Wrapper title='Sales'>
@@ -36,7 +36,7 @@ import { Table, TableUI } from './table/index.js';
  *
  * Component identifiers are not surfaced as separate named exports — Types
  * (props, data shapes, label types, default-label consts) and per-widget
- * subpath entries (`@carto/ps-react-ui/widgets-v2/bar`, `…/category`,
+ * subpath entries (`@carto/ps-react-ui/widgets/bar`, `…/category`,
  * `…/table`, `…/actions`, `…/stores`, `…/utils`, etc.) remain available for
  * direct import where needed.
  */

package/dist/types/widgets/markdown/download.d.ts

@@ -0,0 +1,10 @@
+import { toCsvString, triggerLinkDownload, DownloadItem, WidgetDownloadArgs } from '../actions/download/index.js';
+import { MarkdownWidgetData } from './types.js';
+/**
+ * Download menu items for the Markdown widget. Always includes a `.md` item
+ * that saves the markdown source verbatim. When `getCaptureEl` is given,
+ * prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export declare function createMarkdownDownloadConfig(args: WidgetDownloadArgs<MarkdownWidgetData>): DownloadItem[];
+export { toCsvString, triggerLinkDownload };

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

@@ -1,5 +1,6 @@
 export { Markdown } from './markdown.js';
-export { MarkdownUI } from './markdown-ui.js';
-export { MarkdownSkeleton } from './skeleton.js';
-export { markdownConfig, markdownDownloadConfig } from './config.js';
-export type { MarkdownComponentProps, MarkdownUIProps, MarkdownWidgetData, MarkdownWidgetState, MarkdownWidgetConfig, MarkdownDownloadConfig, MarkdownDataItem, } from './types.js';
+export { MarkdownUI, type MarkdownUIProps } from './markdown-ui.js';
+export { MarkdownContent, type MarkdownContentProps } from './markdown-content.js';
+export { MarkdownSkeleton, type MarkdownSkeletonProps } from './skeleton.js';
+export { createMarkdownDownloadConfig } from './download.js';
+export type { MarkdownWidgetData } from './types.js';