@carto/ps-react-ui 5.0.0-widgets.8 → 5.0.0

package/dist/types/widgets-v2/selection-summary/labels.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+export interface SelectionSummaryLabels {
+    /**
+     * Optional custom renderer for the count. Defaults to the built-in two-tone
+     * `selected / total` rendering. Receives the already-resolved displayed
+     * number (which equals `total` when nothing is selected).
+     */
+    summary?: (selected: number, total: number) => ReactNode;
+    clear: string;
+}
+export declare const DEFAULT_SELECTION_SUMMARY_LABELS: SelectionSummaryLabels;

package/dist/types/widgets-v2/selection-summary/selection-summary.d.ts

@@ -0,0 +1,29 @@
+import { SvgIconProps } from '@mui/material';
+import { ComponentType } from 'react';
+import { SelectionSummaryLabels } from './labels.js';
+export interface SelectionSummaryProps {
+    /** Number of currently selected items. */
+    count: number;
+    /** Optional total — when `undefined` or `0` the component renders nothing (no data). */
+    total?: number;
+    /** Clear callback. The Clear control is shown only when `count > 0` and `onClear` is provided. */
+    onClear?: () => void;
+    labels?: Partial<SelectionSummaryLabels>;
+    icon?: ComponentType<SvgIconProps>;
+    iconProps?: SvgIconProps;
+}
+/**
+ * Renders a `selected / total` count.
+ *
+ * Render rules:
+ *   - `!total` (undefined or 0) → render nothing (no data to summarize).
+ *   - `count === 0` → display `total / total` (everything is implicitly in
+ *     scope); no Clear button.
+ *   - `count > 0` → display `count / total` + Clear (when `onClear` is given).
+ *
+ * The count is two-tone by default (selected number bold/`text.primary`,
+ * ` / total` in `text.secondary`). Pass `labels.summary` to render a custom
+ * node instead — it receives the already-resolved displayed number (which
+ * equals `total` when nothing is selected).
+ */
+export declare function SelectionSummary({ count, total, onClear, labels, icon: Icon, iconProps, }: SelectionSummaryProps): import('react').JSX.Element | null;

package/dist/types/widgets-v2/selection-summary/style.d.ts

@@ -0,0 +1,38 @@
+export declare const styles: {
+    root: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        minHeight: number;
+    };
+    label: {
+        color: "text.secondary";
+    };
+    count: {
+        display: "inline-flex";
+        alignItems: "baseline";
+        gap: number;
+    };
+    selected: {
+        color: "text.primary";
+        fontWeight: number;
+    };
+    separator: {
+        color: "text.secondary";
+    };
+    total: {
+        color: "text.secondary";
+    };
+    clear: {
+        color: "primary.main";
+        cursor: "pointer";
+        fontWeight: number;
+        '&:hover': {
+            textDecoration: string;
+        };
+    };
+    icon: {
+        fontSize: number;
+        color: "text.secondary";
+    };
+};

package/dist/types/widgets-v2/spread/band.d.ts

@@ -0,0 +1,37 @@
+/**
+ * How a `spread` amount is applied to a centre value.
+ *
+ * - `percentage` — `spread` is a whole-number percentage of the centre
+ *   value, so `5` means +/-5%.
+ * - `absolute` — `spread` is a raw offset in the value's own units.
+ */
+export type SpreadVariant = 'percentage' | 'absolute';
+export interface GetSpreadBandOptions {
+    /** The centre value the band is drawn around. */
+    value: number;
+    /** Half-width of the band, read according to `variant`. */
+    spread: number;
+    /** Defaults to `percentage`. */
+    variant?: SpreadVariant;
+}
+/**
+ * Derives the `min` / `max` band around a centre value, for feeding a
+ * {@link SpreadDataItem} from a single aggregated number (a prediction, a
+ * target) plus a tolerance — rather than from a real column range.
+ *
+ * `spread` is read as a percentage by default, which is what a tolerance
+ * almost always is: an absolute offset is meaningless without knowing the
+ * value's magnitude, and gets visually lost on large values (+/-5 on a
+ * prediction of 204,113 renders as a range indistinguishable from a single
+ * number).
+ *
+ * @example
+ * getSpreadBand({ value: 1000, spread: 5 })
+ * // -> { min: 950, max: 1050 }
+ * getSpreadBand({ value: 1000, spread: 5, variant: 'absolute' })
+ * // -> { min: 995, max: 1005 }
+ */
+export declare function getSpreadBand({ value, spread, variant, }: GetSpreadBandOptions): {
+    min: number;
+    max: number;
+};

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

@@ -0,0 +1,15 @@
+import { DownloadItem } from '../actions/download/index.js';
+import { SpreadWidgetData } from './types.js';
+/**
+ * Download menu items for the Spread widget. Always includes a CSV item
+ * with `series, prefix, min, max, suffix, note` columns (one row per
+ * entry). When `getCaptureEl` is supplied, prepends a PNG item that
+ * rasterises the captured element via `html2canvas`.
+ */
+export declare function createSpreadDownloadConfig(args: {
+    filename: string;
+    getData: () => SpreadWidgetData;
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

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

@@ -0,0 +1,7 @@
+export { Spread } from './spread.js';
+export { SpreadUI, type SpreadUIProps } from './spread-ui.js';
+export { Separator } from './separator.js';
+export { SpreadSkeleton, type SpreadSkeletonProps } from './skeleton.js';
+export { createSpreadDownloadConfig } from './download.js';
+export { getSpreadBand, type SpreadVariant, type GetSpreadBandOptions, } from './band.js';
+export type { SpreadDataItem, SpreadWidgetData } from './types.js';

package/dist/types/widgets-v2/spread/separator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Em-dash separator placed between a Spread row's `min` and `max` values.
+ * Built from the Formula {@link Value} primitive so typography (h5/600,
+ * baseline alignment) matches the numbers around it. Renders with
+ * `text.secondary` so it visually recedes between the two bounds.
+ */
+export declare function Separator(): import('react').JSX.Element;

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

@@ -0,0 +1,9 @@
+export interface SpreadSkeletonProps {
+    count?: number;
+}
+/**
+ * Loading placeholder for the Spread widget. Renders `count` rows, each
+ * sized for the `min — max` pair so the layout doesn't jump once data
+ * resolves. Mirrors the row-per-item structure of {@link SpreadUI}.
+ */
+export declare function SpreadSkeleton({ count }: SpreadSkeletonProps): import('react').JSX.Element;

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

@@ -0,0 +1,18 @@
+import { Ref } from 'react';
+import { SpreadDataItem } from './types.js';
+export interface SpreadUIProps {
+    items: readonly SpreadDataItem[];
+    /** Number formatter — applied to each item's `min` and `max`. */
+    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 Spread widget. Each item renders as
+ * a row containing (in order): optional `Series` avatar, a body with
+ * `[prefix] min — max [suffix]` plus optional `Note`. Reuses the Formula
+ * primitives ({@link Series}, {@link Prefix}, {@link Value}, {@link Suffix},
+ * {@link Note}) and the Formula row styles so Spread and Formula stay
+ * visually aligned when used together.
+ */
+export declare function SpreadUI({ items, formatter, ref }: SpreadUIProps): import('react').JSX.Element;

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

@@ -0,0 +1,5 @@
+/**
+ * Stateful Spread bridge — reads `data` (post-pipeline) and `formatter` from
+ * the per-widget store and forwards them to the pure {@link SpreadUI}.
+ */
+export declare function Spread(): import('react').JSX.Element;

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

@@ -0,0 +1,25 @@
+import { FormulaSeries } from '../formula/index.js';
+/**
+ * A single min/max pair rendered by the Spread widget. Mirrors
+ * {@link FormulaDataItem} — same optional `series`, `prefix`, `suffix`,
+ * `color`, and `note` slots — but the value is a range (`min` … `max`)
+ * rather than a single `value`.
+ */
+export interface SpreadDataItem {
+    min: number;
+    max: number;
+    prefix?: string;
+    suffix?: string;
+    /** Override the values' 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 values. */
+    note?: string;
+}
+/**
+ * Spread widget data — an array of `{min, max, …}` pairs rendered
+ * top-to-bottom, one row per entry. Visual structure matches the Formula
+ * widget so the two can sit side-by-side without style drift.
+ */
+export type SpreadWidgetData = readonly SpreadDataItem[];

package/dist/types/widgets-v2/state/labels.d.ts

@@ -0,0 +1,7 @@
+export interface StateLabels {
+    errorTitle: string;
+    errorMessage: (error: unknown) => string;
+    emptyTitle: string;
+    emptyDescription: string;
+}
+export declare const DEFAULT_STATE_LABELS: StateLabels;

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

@@ -0,0 +1,19 @@
+export declare const styles: {
+    emptyRoot: {
+        display: "flex";
+        flexDirection: "column";
+        gap: number;
+        paddingTop: number;
+        paddingBottom: number;
+        paddingX: number;
+        width: string;
+        minHeight: string;
+    };
+    captureBox: {
+        width: string;
+        minHeight: number;
+        display: "flex";
+        flexDirection: "column";
+        flex: number;
+    };
+};

package/dist/types/widgets-v2/state/widget-state.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { StateLabels } from './labels.js';
+export interface StateProps {
+    skeleton: ReactNode;
+    children: ReactNode;
+    /** Override the empty-state predicate. Receives `rawData` (pre-pipeline). */
+    isEmpty?: (rawData: unknown) => boolean;
+    /** Render an alternative error UI. When omitted, the default ErrorView is used. */
+    fallback?: (error: Error) => ReactNode;
+    labels?: Partial<StateLabels>;
+}
+/**
+ * Priority chain: loading → error → empty → content. Both consumer-supplied
+ * errors (set via Provider's `error` prop) and transform-throw errors (set by
+ * the pipeline middleware) flow through the same `error` field. Render-time
+ * errors thrown by `children` are caught by the inlined error boundary and
+ * routed through the same path.
+ */
+export declare function State({ skeleton, children, isEmpty, fallback, labels, }: StateProps): import('react').JSX.Element;

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

@@ -0,0 +1,8 @@
+export type { TransformType, TransformDescriptor, TransformFn, Transform, TransformPair, WidgetState, WidgetInit, WidgetStoreApi, } from './types.js';
+export { applyTransforms, upsertTransform, removeTransform } from './transforms.js';
+export { pipelineMiddleware } from './pipeline-middleware.js';
+export { WidgetContext, useWidgetId } from './widget-context.js';
+export { getWidgetStore, hasWidgetStore, deleteWidgetStore, resetWidgetStore, clearAllWidgetStores, registerWidgetStore, unregisterWidgetStore, setWidgetStoreEntry, createWidgetStore, useWidget, useWidgetShallow, setCaptureEl, getCaptureEl, clearAllCaptureEls, setEchartInstance, getEchartInstance, subscribeEchartInstance, clearAllEchartInstances, __debugListWidgetStores, } from './widget-store-registry.js';
+export { useEchartInstance } from './use-echart-instance.js';
+export { useTransform, useSingleTransform, type UseTransformOptions, type TransformControls, } from './use-transform.js';
+export { useTransformEnabled } from './use-transform-enabled.js';

package/dist/types/widgets-v2/stores/pipeline-middleware.d.ts

@@ -0,0 +1,5 @@
+import { StateCreator, StoreMutatorIdentifier } from 'zustand';
+import { WidgetState } from './types.js';
+type PipelineMiddleware = <T extends WidgetState, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(config: StateCreator<T, Mps, Mcs>) => StateCreator<T, Mps, Mcs>;
+export declare const pipelineMiddleware: PipelineMiddleware;
+export {};

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

@@ -0,0 +1,4 @@
+import { Transform } from './types.js';
+export declare function applyTransforms(input: unknown, transforms: readonly Transform[], onError?: (id: string, error: Error) => void): unknown;
+export declare function upsertTransform(transforms: readonly Transform[], next: Transform): readonly Transform[];
+export declare function removeTransform(transforms: readonly Transform[], id: string): readonly Transform[];

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

@@ -0,0 +1,55 @@
+import { StoreApi } from 'zustand';
+export type TransformType = 'data' | 'config';
+export interface TransformDescriptor {
+    id: string;
+    type: TransformType;
+    order: number;
+    disables?: string[];
+    replaceMergeKeys?: string[];
+}
+export type TransformFn = (input: unknown) => unknown;
+export interface Transform extends TransformDescriptor {
+    fn: TransformFn;
+    enabled: boolean;
+}
+export interface TransformPair {
+    descriptor: TransformDescriptor;
+    fn: TransformFn;
+}
+export interface WidgetState {
+    rawData: unknown;
+    data: unknown;
+    dataTransforms: readonly Transform[];
+    configTransforms: readonly Transform[];
+    transformStates: Record<string, {
+        enabled: boolean;
+        [k: string]: unknown;
+    }>;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: unknown;
+    /**
+     * Original formatter as supplied by the consumer (Provider's `formatter`
+     * prop). Always live-synced — never overridden by actions. Actions that need
+     * to display a different formatter (e.g. {@link RelativeData}'s percent
+     * formatter) should write to {@link WidgetState.formatter} and read this
+     * field when restoring the absolute view.
+     */
+    rawFormatter?: (value: number) => string;
+    /**
+     * Active formatter — what consumer code (tooltips, axis labels, legends,
+     * etc.) reads. Defaults to {@link WidgetState.rawFormatter}; actions may
+     * override it temporarily and restore it from `rawFormatter` later.
+     */
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+}
+export interface WidgetInit {
+    data: unknown;
+    isLoading?: boolean;
+    isFetching?: boolean;
+    error?: unknown;
+    formatter?: (value: number) => string;
+    labelFormatter?: (value: string | number) => string | number;
+}
+export type WidgetStoreApi = StoreApi<WidgetState>;

package/dist/types/widgets-v2/stores/use-echart-instance.d.ts

@@ -0,0 +1,15 @@
+import { ECharts } from 'echarts';
+/**
+ * Reactive read of the live ECharts instance for a widget. Returns
+ * `null` before the `Widget.Echart` bridge has mounted (or after it's
+ * disposed); the consumer re-renders when the instance arrives /
+ * departs / changes.
+ *
+ * Wraps {@link subscribeEchartInstance} via `useSyncExternalStore`, so
+ * actions can use it inside an effect's deps array to react to chart
+ * lifecycle events without polling. Required for actions like
+ * `BrushToggle` whose effect needs to dispatch `takeGlobalCursor` the
+ * moment the chart exists, then re-dispatch on every `'finished'`
+ * event.
+ */
+export declare function useEchartInstance(id: string): ECharts | null;

package/dist/types/widgets-v2/stores/use-transform-enabled.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reactive read of a single transform's `enabled` flag from the
+ * per-widget store. Returns `false` if the transform hasn't been
+ * registered yet (i.e., the action component hasn't mounted) — safe
+ * default for "the feature is off".
+ *
+ * Used by widget composers that want to react to an action's on/off
+ * cycle without having the widget primitive import the action. For
+ * example, the `CategoryWidget` storybook composer wires the
+ * SearcherToggle's open state into `<Widget.Category searcherOpen=…>`
+ * so the library primitive stays renderer-agnostic.
+ *
+ * Magic-string `transformId` is intentional — it lives at the composer
+ * layer where the action is already imported by JSX, so the string
+ * appears alongside the same name in the toolbox.
+ */
+export declare function useTransformEnabled(id: string, transformId: string): boolean;

package/dist/types/widgets-v2/stores/use-transform.d.ts

@@ -0,0 +1,12 @@
+import { Dispatch, SetStateAction } from 'react';
+import { TransformDescriptor, TransformFn, TransformPair } from './types.js';
+export interface UseTransformOptions {
+    initialEnabled?: boolean;
+}
+export interface TransformControls {
+    enabled: boolean;
+    setEnabled: Dispatch<SetStateAction<boolean>>;
+    toggle: () => void;
+}
+export declare function useTransform(id: string, pairs: readonly TransformPair[], options?: UseTransformOptions): TransformControls;
+export declare function useSingleTransform(id: string, descriptor: TransformDescriptor, fn: TransformFn, options?: UseTransformOptions): TransformControls;

package/dist/types/widgets-v2/stores/widget-context.d.ts

@@ -0,0 +1,2 @@
+export declare const WidgetContext: import('react').Context<string | null>;
+export declare function useWidgetId(): string;

package/dist/types/widgets-v2/stores/widget-store-registry.d.ts

@@ -0,0 +1,74 @@
+import { ECharts } from 'echarts';
+import { WidgetInit, WidgetState, WidgetStoreApi } from './types.js';
+type EchartInstanceListener = (chart: ECharts | null) => void;
+export declare function getWidgetStore(id: string): WidgetStoreApi;
+export declare function hasWidgetStore(id: string): boolean;
+export declare function deleteWidgetStore(id: string): void;
+export declare function resetWidgetStore(id: string): void;
+export declare function clearAllWidgetStores(): void;
+/**
+ * Register or clear the capture element for a widget. Pass `null` to clear.
+ * Called by `Widget.State` via a callback ref on its success-path content
+ * wrapper. The element is read by per-widget download configs at click time
+ * to feed `html2canvas` for PNG export.
+ */
+export declare function setCaptureEl(id: string, el: HTMLElement | null): void;
+/**
+ * Read the currently registered capture element for a widget. Returns `null`
+ * when no `Widget.State` is on its success path (loading / error / empty)
+ * or when the widget hasn't mounted.
+ */
+export declare function getCaptureEl(id: string): HTMLElement | null;
+/** @internal — exposed for tests and debugging only. */
+export declare function clearAllCaptureEls(): void;
+/**
+ * Register or clear the live ECharts instance for a widget. Pass `null`
+ * to clear. Called by the `Widget.Echart` bridge on mount / dispose.
+ * Read by actions (e.g. `ZoomToggle`'s disable handler) that need to
+ * dispatch on the live chart without going through the pipeline.
+ *
+ * Notifies subscribers registered via {@link subscribeEchartInstance}
+ * after the map mutation, so reactive consumers (the
+ * `useEchartInstance` hook) re-render with the new value.
+ */
+export declare function setEchartInstance(id: string, chart: ECharts | null): void;
+/**
+ * Read the currently registered ECharts instance for a widget. Returns
+ * `null` when no `Widget.Echart` is mounted, or before the bridge has
+ * created the instance.
+ */
+export declare function getEchartInstance(id: string): ECharts | null;
+/**
+ * Subscribe to changes of the registered ECharts instance for a widget.
+ * The listener is called *after* every {@link setEchartInstance} (with
+ * the new chart, or `null` when cleared). Returns an unsubscribe
+ * function. Used by the `useEchartInstance` hook to drive React effects
+ * that need to react to instance arrival / departure (e.g.
+ * `BrushToggle`'s `'finished'` re-dispatch loop).
+ */
+export declare function subscribeEchartInstance(id: string, listener: EchartInstanceListener): () => void;
+/** @internal — exposed for tests and debugging only. */
+export declare function clearAllEchartInstances(): void;
+/** @internal — exposed for tests and debugging only. */
+export declare function __debugListWidgetStores(): string[];
+/**
+ * Insert or replace a store entry in the registry without refcounting or
+ * duplicate-id detection. Used by Provider's lazy `useState` init so the
+ * store is reachable from `useWidget(id)` calls in children that render
+ * before the Provider's mount effect runs. Refcounting and dev warns happen
+ * in {@link registerWidgetStore} during the mount effect.
+ *
+ * @internal
+ */
+export declare function setWidgetStoreEntry(id: string, store: WidgetStoreApi): void;
+/** @internal — used by Provider; not part of the public API. */
+export declare function createWidgetStore(id: string, init: WidgetInit): WidgetStoreApi;
+/** @internal — registers a Provider mount and tracks/warns on duplicate ids in dev. */
+export declare function registerWidgetStore(id: string, store: WidgetStoreApi): void;
+/** @internal — Provider unmount counterpart; on last unmount removes the refcount entry. */
+export declare function unregisterWidgetStore(id: string, options: {
+    keepAlive: boolean;
+}): void;
+export declare function useWidget<T, S extends WidgetState = WidgetState>(id: string, selector: (state: S) => T): T;
+export declare function useWidgetShallow<T, S extends WidgetState = WidgetState>(id: string, selector: (state: S) => T): T;
+export {};

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

@@ -0,0 +1,10 @@
+export declare const styles: {
+    root: {
+        display: "grid";
+        gridTemplateColumns: string;
+        alignItems: "center";
+        gap: number;
+        minHeight: number;
+        pb: number;
+    };
+};

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

@@ -0,0 +1,11 @@
+import { SxProps, Theme } from '@mui/material';
+import { ReactNode } from 'react';
+export interface SubheaderProps {
+    sx?: SxProps<Theme>;
+    children: ReactNode;
+}
+/**
+ * Stateless layout: CSS grid `1fr auto`. Children self-place — typically
+ * `<Widget.SelectionSummary />` (left) and `<Widget.Toolbox>` (right).
+ */
+export declare function Subheader({ sx, children }: SubheaderProps): import('react').JSX.Element;

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

@@ -0,0 +1,18 @@
+import { DownloadItem } from '../actions/download/index.js';
+import { TableColumn, TableWidgetData } from './types.js';
+/**
+ * Download menu items for the Table widget. Always includes a CSV item
+ * that pulls the latest data from the widget store via `getData()` (so
+ * locked / sorted / filtered state is honored); headers come from
+ * `column.label`, cells from `row[column.id]`. When `getCaptureEl` is
+ * supplied, prepends a PNG item that rasterises the captured element via
+ * `html2canvas`.
+ */
+export declare function createTableDownloadConfig(opts: {
+    filename: string;
+    getData: () => TableWidgetData;
+    columns: readonly TableColumn[];
+    getCaptureEl?: () => HTMLElement | null;
+    pngPixelRatio?: number;
+    pngBackgroundColor?: string | null;
+}): DownloadItem[];

package/dist/types/widgets-v2/table/helpers.d.ts

@@ -0,0 +1,32 @@
+import { TableColumn, TableRow, TableSortDirection, TableWidgetData } from './types.js';
+/**
+ * Compares two values with a consistent ordering across primitive types.
+ * Strings use locale comparison; numbers subtract; booleans rank false < true;
+ * objects/arrays compare by JSON serialization. Null/undefined sort to the end
+ * regardless of direction.
+ */
+export declare function compareValues(a: unknown, b: unknown, direction: TableSortDirection): number;
+/** Returns a new array sorted by the named column. Does not mutate the input. */
+export declare function sortRows<T extends TableRow>(rows: readonly T[], columnId: string, direction: TableSortDirection): T[];
+/** Returns the slice for the requested page. Out-of-range pages return []. */
+export declare function paginateRows<T>(rows: readonly T[], page: number, pageSize: number): T[];
+/**
+ * Resolves the effective column list. When the widget store has a
+ * `columnOrder` set (e.g. ChangeColumn was used), the column array is
+ * reordered to match. Unknown ids in the order are skipped; columns not
+ * present in the order keep their original relative position at the end.
+ */
+export declare function resolveColumns(columns: readonly TableColumn[], columnOrder: readonly string[] | undefined): readonly TableColumn[];
+/** Applies sort and pagination to the input data. Pure. */
+export declare function deriveVisibleRows<T extends TableRow>(rows: readonly T[], options: {
+    sort?: {
+        columnId: string | null;
+        direction: TableSortDirection;
+    };
+    page: number;
+    pageSize: number;
+}): {
+    sorted: readonly T[];
+    visible: T[];
+};
+export declare function tableDataToCsv(data: TableWidgetData, columns: readonly TableColumn[]): string;

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

@@ -0,0 +1,8 @@
+export { Table, type TableProps } from './table.js';
+export { TableUI, type TableUIProps } from './table-ui.js';
+export { TableSkeleton, type TableSkeletonProps } from './skeleton.js';
+export { createTableDownloadConfig } from './download.js';
+export { filterTableByLockedRows } from './transforms.js';
+export { compareValues, sortRows, paginateRows, resolveColumns, deriveVisibleRows, tableDataToCsv, } from './helpers.js';
+export { DEFAULT_TABLE_LABELS, type TableLabels } from './labels.js';
+export { DEFAULT_TABLE_PAGE_SIZE, DEFAULT_TABLE_PAGE_SIZE_OPTIONS, type TableColumn, type TableRow, type TableWidgetData, type TableWidgetState, type TableSortDirection, type TableSortState, } from './types.js';

package/dist/types/widgets-v2/table/labels.d.ts

@@ -0,0 +1,22 @@
+import { ReactNode } from 'react';
+export interface TableLabels {
+    selectAll: string;
+    selectRow: (rowId: string | number) => string;
+    rowsPerPage: string;
+    /**
+     * Renders the displayed-rows summary in the pagination footer. Returns
+     * a `ReactNode` so the default can emphasise the active range
+     * (`from-to`) with a bolder weight while keeping the trailing
+     * ` of total` muted. Override to localise wording or restyle.
+     */
+    paginationOf: (from: number, to: number, total: number) => ReactNode;
+    /** aria-label for the first-page pagination button. */
+    firstPage: string;
+    /** aria-label for the previous-page pagination button. */
+    previousPage: string;
+    /** aria-label for the next-page pagination button. */
+    nextPage: string;
+    /** aria-label for the last-page pagination button. */
+    lastPage: string;
+}
+export declare const DEFAULT_TABLE_LABELS: TableLabels;

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

@@ -0,0 +1,22 @@
+import { TableProps as MuiTableProps } from '@mui/material';
+export interface TableSkeletonProps {
+    /** Number of body rows to render. Defaults to `5` (matches v1). */
+    rows?: number;
+    /** Number of columns to render. Defaults to `4` (matches v1). */
+    columns?: number;
+    /**
+     * Forwarded to MUI's `<Table size>` so the loading layout matches the
+     * size you'll render in {@link TableUI}. Leave `undefined` (the
+     * default) to use MUI's own default density.
+     */
+    size?: MuiTableProps['size'];
+}
+/**
+ * Loading placeholder for the Table widget. Renders the same MUI table
+ * primitives that {@link TableUI} uses so the loading layout (column
+ * widths, header band, row density) doesn't shift when data resolves.
+ *
+ * Mirrors the v1 widget's `<TableSkeleton>` structure with v2's themed
+ * `styles.headerCell`.
+ */
+export declare function TableSkeleton({ rows, columns, size, }: TableSkeletonProps): import('react').JSX.Element;

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

@@ -0,0 +1,40 @@
+export declare const styles: {
+    container: {
+        width: string;
+        overflowX: "auto";
+    };
+    table: {
+        minWidth: number;
+    };
+    headerCell: {
+        fontWeight: number;
+        backgroundColor: "background.paper";
+    };
+    /**
+     * Strip the bottom border from the last body row so the body flushes
+     * against the pagination border instead of doubling it up. Mirrors v1.
+     */
+    row: {
+        '&:last-child td, &:last-child th': {
+            border: number;
+        };
+    };
+    rowClickable: {
+        cursor: "pointer";
+    };
+    pagination: {
+        borderTop: string;
+        borderColor: "divider";
+    };
+    paginationActions: {
+        display: "flex";
+        alignItems: "center";
+        gap: number;
+        ml: number;
+    };
+    empty: {
+        textAlign: "center";
+        color: "text.secondary";
+        py: number;
+    };
+};