@carto/ps-react-ui 4.7.0 → 4.8.0

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

@@ -0,0 +1,44 @@
+import { SxProps, Theme } from '@mui/material';
+import * as echarts from 'echarts';
+export declare const DEFAULT_INIT_OPTS: {
+    renderer: "svg";
+    height: number;
+};
+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: 304 }`.
+     */
+    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-runtime").JSX.Element;

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

@@ -0,0 +1,75 @@
+import { EchartsEventHandler } from './echart-ui';
+import type * as echarts from 'echarts';
+/**
+ * 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;
+}
+/**
+ * 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.
+ *
+ * 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({ optionFactory, onEvents, init, className, }: EchartProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,4 @@
+export { EchartUI, DEFAULT_INIT_OPTS, type EchartUIProps, type EchartsEventHandler, } from './echart-ui';
+export { Echart, type EchartProps, type OptionFactory, type OptionFactoryContext, } from './echart';
+export { useChartSelection, type SelectionKey, type UseChartSelectionOptions, type ChartSelectionWiring, } from './use-chart-selection';
+export { observeResize, __resetSharedResizeObserver, } from './shared-resize-observer';

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

@@ -0,0 +1,5 @@
+type ResizeCallback = () => void;
+export declare function observeResize(element: Element, callback: ResizeCallback): () => void;
+/** @internal — for tests only. */
+export declare function __resetSharedResizeObserver(): void;
+export {};

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

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

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

@@ -0,0 +1,6 @@
+export declare const styles: {
+    root: {
+        width: string;
+        minHeight: number;
+    };
+};

package/dist/types/widgets-v2/echart/use-chart-selection.d.ts

@@ -0,0 +1,51 @@
+import { CallbackDataParams } from 'echarts/types/dist/shared';
+import { EchartsEventHandler } from './echart-ui';
+export type SelectionKey = string | number;
+export interface UseChartSelectionOptions<K extends SelectionKey> {
+    /** Controlled selection. `undefined` is treated the same as `[]`. */
+    selection?: readonly K[];
+    /** Receives the next selection. When omitted the wiring is a no-op. */
+    onSelectionChange?: (next: readonly K[]) => void;
+    /**
+     * Pull a selection key out of an ECharts `click` event. Return `null` to
+     * skip (e.g. a click on empty plot area). For Bar/Pie/Timeseries this is
+     * usually `(p) => p.name`; for Histogram/Scatterplot it's the dataIndex.
+     */
+    keyFromClick: (params: CallbackDataParams) => K | null;
+    /**
+     * Map a `brushSelected` payload's `selected[*]` entries (each carrying a
+     * `seriesIndex` + `dataIndex[]`) into the full set of selection keys for
+     * the brushed area. Called once per brush event.
+     */
+    keysFromBrush: (selected: readonly {
+        seriesIndex: number;
+        dataIndex: number[];
+    }[]) => K[];
+}
+export interface ChartSelectionWiring<K extends SelectionKey> {
+    /**
+     * Pass straight to `<Widget.Echart onEvents={…}>`. Wires `click` and
+     * `brushSelected` so the user's interactions reach `onSelectionChange`.
+     */
+    onEvents: Record<string, EchartsEventHandler>;
+    /**
+     * The current selection — `null` when the consumer didn't pass one or it's
+     * empty. Mergers should treat `null` as "no dimming" and a non-null array
+     * as "render only these as fully opaque, dim the rest".
+     */
+    selection: readonly K[] | null;
+}
+/**
+ * Translate ECharts' click + brush events into a consumer-owned selection
+ * with the expected dashboard semantics:
+ *
+ *   - **Click toggles** — clicking an item adds it to the selection if
+ *     absent, removes it if present.
+ *   - **Brush replaces** — finishing a brush stroke overwrites the selection
+ *     with whatever the brush covered (drag-to-empty clears).
+ *
+ * Wire the returned `onEvents` into `<Widget.Echart>` and feed
+ * `wiring.selection` to the widget's option factory so the merger can dim
+ * non-selected rows at fusion time.
+ */
+export declare function useChartSelection<K extends SelectionKey>({ selection, onSelectionChange, keyFromClick, keysFromBrush, }: UseChartSelectionOptions<K>): ChartSelectionWiring<K>;

package/dist/types/widgets-v2/formula/delta.d.ts

@@ -0,0 +1,22 @@
+import { ChipProps } from '@mui/material';
+import { DeltaSeverity } from './types';
+export interface DeltaProps {
+    /** Numeric magnitude. Used for the default percent label and severity inference. */
+    value: number;
+    /** Pre-formatted label override; skips the default percent formatter. */
+    label?: string;
+    /**
+     * Visual treatment. When omitted it's derived from the sign of `value`:
+     * `>0 → 'positive'`, `<0 → 'negative'`, `=0 → 'neutral'`.
+     */
+    severity?: DeltaSeverity;
+    /** Override the default `Intl.NumberFormat({style:'percent'})` formatter. */
+    format?: (value: number) => string;
+    ChipProps?: ChipProps;
+}
+/**
+ * Comparative delta rendered as a small filled chip. Colour is driven by
+ * `severity` (or the sign of `value`); content is `label`, the result of
+ * `format(value)`, or the default percent format.
+ */
+export declare function Delta({ value, label, severity, format, ChipProps: chipProps, }: DeltaProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,20 @@
+import { DownloadItem } from '../actions/download';
+import { FormulaWidgetData } from './types';
+export interface FormulaDownloadConfigArgs {
+    filename: string;
+    getData: () => FormulaWidgetData;
+    /**
+     * Optional getter for the widget's capture element (registered by
+     * `Widget.State`). When provided, a PNG item is prepended.
+     */
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}
+/**
+ * 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 supplied, prepends a PNG item that rasterises the
+ * captured element via `html2canvas`.
+ */
+export declare function createFormulaDownloadConfig(args: FormulaDownloadConfigArgs): DownloadItem[];

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

@@ -0,0 +1,20 @@
+import { Ref } from 'react';
+import { FormulaDataItem } from './types';
+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>;
+}
+/**
+ * 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({ items, formatter, ref }: FormulaUIProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,8 @@
+/**
+ * Stateful Formula bridge — reads `data` (post-pipeline) and `formatter` from
+ * the per-widget store and forwards them to the pure {@link FormulaUI}. Sits
+ * inside `<Widget.Provider>`. Demonstrates that the composition shell
+ * (Provider, Wrapper, State) doesn't care whether the rendered child is
+ * ECharts (Bar) or a custom DOM tree (Formula).
+ */
+export declare function Formula(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,11 @@
+export { Formula } from './formula';
+export { FormulaUI, type FormulaUIProps } from './formula-ui';
+export { Prefix, type PrefixProps } from './prefix';
+export { Suffix, type SuffixProps } from './suffix';
+export { Value, type ValueProps } from './value';
+export { Series, type SeriesProps } from './series';
+export { Note, type NoteProps } from './note';
+export { Delta, type DeltaProps } from './delta';
+export { FormulaSkeleton, type FormulaSkeletonProps } from './skeleton';
+export { createFormulaDownloadConfig } from './download';
+export type { FormulaDataItem, FormulaWidgetData, FormulaSeries, FormulaDelta, DeltaSeverity, } from './types';

package/dist/types/widgets-v2/formula/note.d.ts

@@ -0,0 +1,11 @@
+import { TypographyProps } from '@mui/material';
+import { ReactNode } from 'react';
+export interface NoteProps {
+    children: ReactNode;
+    TypographyProps?: TypographyProps;
+}
+/**
+ * Small subdued caption rendered below a Formula value. Use for short
+ * descriptive text (e.g. "Last 7 days", "Excludes refunds").
+ */
+export declare function Note({ children, TypographyProps }: NoteProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/widgets-v2/formula/prefix.d.ts

@@ -0,0 +1,12 @@
+import { TypographyProps } from '@mui/material';
+import { ReactNode } from 'react';
+export interface PrefixProps {
+    children: ReactNode;
+    TypographyProps?: TypographyProps;
+}
+/**
+ * Prefix slot for a Formula KPI — large, bold, muted (`text.secondary`).
+ * Composable building block for custom formula layouts; the canonical
+ * {@link FormulaUI} renders one of these per item when `prefix` is set.
+ */
+export declare function Prefix({ children, TypographyProps }: PrefixProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,16 @@
+import { AvatarProps } from '@mui/material';
+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;
+    /** Diameter in px. Default `24`. */
+    size?: number;
+    AvatarProps?: AvatarProps;
+}
+/**
+ * Series indicator — circular avatar showing the first letter of `name`.
+ * Background colour is `color` (consumer-supplied) or a neutral disabled
+ * colour, with text colour computed for contrast against it.
+ */
+export declare function Series({ name, color, size, AvatarProps: avatarProps, }: SeriesProps): import("react/jsx-runtime").JSX.Element;

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

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

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

@@ -0,0 +1,29 @@
+export declare const styles: {
+    root: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        alignItems: "stretch";
+    };
+    row: {
+        display: "flex";
+        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-v2/formula/suffix.d.ts

@@ -0,0 +1,12 @@
+import { TypographyProps } from '@mui/material';
+import { ReactNode } from 'react';
+export interface SuffixProps {
+    children: ReactNode;
+    TypographyProps?: TypographyProps;
+}
+/**
+ * Suffix slot for a Formula KPI — large, bold, muted (`text.secondary`).
+ * Composable building block for custom formula layouts; the canonical
+ * {@link FormulaUI} renders one of these per item when `suffix` is set.
+ */
+export declare function Suffix({ children, TypographyProps }: SuffixProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,40 @@
+/** Series metadata rendered as a coloured avatar at the start of a row. */
+export interface FormulaSeries {
+    /** 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;
+}
+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;
+    /** 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;
+}
+/** 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?: string;
+    /** 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;
+}
+/**
+ * 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/formula/value.d.ts

@@ -0,0 +1,14 @@
+import { TypographyProps } from '@mui/material';
+import { ReactNode } from 'react';
+export interface ValueProps {
+    children: ReactNode;
+    /** Override the default `text.primary` color — useful for sparkline tints. */
+    color?: string;
+    TypographyProps?: TypographyProps;
+}
+/**
+ * Value slot for a Formula KPI — large, bold, primary text color. Composable
+ * building block for custom formula layouts; the canonical {@link FormulaUI}
+ * renders one of these per item.
+ */
+export declare function Value({ children, color, TypographyProps }: ValueProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,17 @@
+import { DownloadItem } from '../actions/download';
+import { HistogramWidgetData } from './types';
+/**
+ * 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 supplied, prepends a PNG item that
+ * rasterises the captured element via `html2canvas`.
+ */
+export declare function createHistogramDownloadConfig(args: {
+    filename: string;
+    getData: () => HistogramWidgetData;
+    getTicks: () => readonly number[];
+    seriesNames?: readonly string[];
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

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

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

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

@@ -0,0 +1,5 @@
+export { histogramOptions, createHistogramOptionFactory } from './options';
+export { HistogramSkeleton, type HistogramSkeletonProps } from './skeleton';
+export { createHistogramDownloadConfig } from './download';
+export { toRelativeHistogramData } from './transforms';
+export type { HistogramWidgetData, HistogramOptionsInput, HistogramOptionFactoryInput, HistogramEChartsOption, } from './types';

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

@@ -0,0 +1,42 @@
+import { OptionFactory } from '../echart';
+import { HistogramEChartsOption, HistogramOptionFactoryInput, HistogramOptionsInput } from './types';
+/**
+ * Builds the **structural** ECharts option for a histogram widget — axes,
+ * grid, tooltip, value-axis label formatter, themed legend. Mirrors
+ * {@link import('../bar/options').barOptions} so the two widgets share v1
+ * look-and-feel: themed dark tooltip with positioner, CARTO color palette,
+ * structural legend (`show` toggled by the merger based on series count),
+ * y-axis labels rendered inside the plot via the `niceNum` closure pattern.
+ *
+ * Intentional deviations from bar (histogram-specific):
+ *   - **No `xAxis.axisLabel.formatter`.** Bin labels are pre-formatted in
+ *     the merger via `formatNumber(lo)–formatNumber(hi)` and optionally
+ *     the consumer's `labelFormatter`. The strings on the axis are
+ *     already display-ready, so there's nothing to post-format here.
+ *   - **Tooltip formatter reads the array-tuple row shape.** The dataset
+ *     uses positional `encode: { x: 0, y: 1 }`, so `item.value` comes in
+ *     as `[binLabel, count]` rather than bar's `{ name, value }` object.
+ *
+ * Intentionally data-agnostic: no series, no dataset, no x-axis category
+ * data (those depend on data + ticks and are added by the option factory's
+ * merge phase via {@link createHistogramOptionFactory}).
+ */
+export declare function histogramOptions({ theme, formatter, }: HistogramOptionsInput): HistogramEChartsOption;
+/**
+ * Returns the histogram widget's {@link OptionFactory} — one closure that
+ * owns BOTH phases of option construction:
+ *
+ *   - **Structural phase** (`option == null`) — builds the theme-aware
+ *     structural option via {@link histogramOptions}, optionally merging
+ *     the consumer-supplied `optionsOverride`. Called once by Provider to
+ *     seed `rawOptions` in the store.
+ *   - **Merge phase** (`option != null`) — fuses post-pipeline `state.data`
+ *     (`HistogramWidgetData` — `number[][]`) into the option via the
+ *     dataset API. Each series gets its own dataset of `[binLabel, count]`
+ *     pairs derived from `ticks`; series reference their dataset by
+ *     `datasetIndex` and are encoded by column position. Reactive
+ *     `ctx.formatter` (driven by RelativeData → `%`) plus `niceMin`/`niceMax`
+ *     are re-derived here so the y-axis label formatter and the tooltip
+ *     pick up live store values, mirroring bar.
+ */
+export declare function createHistogramOptionFactory(options: HistogramOptionFactoryInput): OptionFactory;

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

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

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

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

package/dist/types/widgets-v2/histogram/transforms.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Histogram-specific `RelativeData` transform. Histogram data is
+ * `number[][]` — each series is a flat list of bin counts. This
+ * rewrites each count to its share of the series total (0–100), so
+ * pairing with `createPercentFormatter` renders the y-axis as
+ * percentages.
+ *
+ * Pass to `<Widget.RelativeData transform={toRelativeHistogramData} />`.
+ *
+ * The denominator is the sum of |value| across the series so mixed-sign
+ * inputs 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. Inputs
+ * whose shape isn't `number[][]` fall through untouched (same defensive
+ * shape-check pattern as the default transform).
+ */
+export declare const toRelativeHistogramData: (input: unknown) => unknown;

package/dist/types/widgets-v2/histogram/transforms.test.d.ts

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

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

@@ -0,0 +1,47 @@
+import { Theme } from '@mui/material';
+import { EChartsOption } from 'echarts';
+/**
+ * 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`,
+ * `seriesNames`, `labelFormatter`, `selection`).
+ */
+export interface HistogramOptionFactoryInput {
+    theme: Theme;
+    formatter?: (value: number) => string;
+    /** Bin boundaries — length = bins + 1. */
+    ticks: readonly number[];
+    /** Optional series names — drives the legend. */
+    seriesNames?: readonly string[];
+    /**
+     * 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;
+    /**
+     * 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;