@carto/ps-react-ui 4.4.0-chat-ui.5 → 4.4.0-chat-ui.7

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-runtime").JSX.Element;

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

@@ -0,0 +1,25 @@
+import { FormulaSeries } from '../formula';
+/**
+ * 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/labels.test.d.ts

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

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';
+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-runtime").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';
+export { applyTransforms, upsertTransform, removeTransform } from './transforms';
+export { pipelineMiddleware } from './pipeline-middleware';
+export { WidgetContext, useWidgetId } from './widget-context';
+export { getWidgetStore, hasWidgetStore, deleteWidgetStore, resetWidgetStore, clearAllWidgetStores, registerWidgetStore, unregisterWidgetStore, setWidgetStoreEntry, createWidgetStore, useWidget, useWidgetShallow, setCaptureEl, getCaptureEl, clearAllCaptureEls, setEchartInstance, getEchartInstance, subscribeEchartInstance, clearAllEchartInstances, __debugListWidgetStores, } from './widget-store-registry';
+export { useEchartInstance } from './use-echart-instance';
+export { useTransform, useSingleTransform, type UseTransformOptions, type TransformControls, } from './use-transform';
+export { useTransformEnabled } from './use-transform-enabled';

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

@@ -0,0 +1,5 @@
+import { StateCreator, StoreMutatorIdentifier } from 'zustand';
+import { WidgetState } from './types';
+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/pipeline-middleware.test.d.ts

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

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

@@ -0,0 +1,4 @@
+import { Transform } from './types';
+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/transforms.test.d.ts

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

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';
+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';
+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/stores/widget-store-registry.test.d.ts

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

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

@@ -0,0 +1,18 @@
+import { DownloadItem } from '../actions/download';
+import { TableColumn, TableWidgetData } from './types';
+/**
+ * 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/download.test.d.ts

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

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

@@ -0,0 +1,32 @@
+import { TableColumn, TableRow, TableSortDirection, TableWidgetData } from './types';
+/**
+ * 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/helpers.test.d.ts

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

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

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

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-runtime").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;
+    };
+};

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

@@ -0,0 +1,44 @@
+import { TableProps as MuiTableProps } from '@mui/material';
+import { TableLabels } from './labels';
+import { TableColumn, TableRow, TableSortState } from './types';
+export interface TableUIProps<T extends TableRow = TableRow> {
+    columns: readonly TableColumn[];
+    /** Already-paginated, already-sorted rows for the current view. */
+    rows: readonly T[];
+    /** Total row count (across all pages). Required for pagination footer. */
+    total: number;
+    page: number;
+    pageSize: number;
+    pageSizeOptions?: readonly number[];
+    sort?: TableSortState;
+    /**
+     * Column name to use as the row identity. Drives selection lookup,
+     * React keys, and aria labels. Defaults to `'id'` — point it at
+     * another column when your rows don't carry an `id` field.
+     */
+    keyColumn?: string;
+    /** Selected row ids. Destination-owned. */
+    selection?: readonly (string | number)[];
+    selectable?: boolean;
+    onSortChange?: (next: TableSortState) => void;
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (pageSize: number) => void;
+    onSelectionChange?: (next: readonly (string | number)[]) => void;
+    onRowClick?: (row: T) => void;
+    onRowHover?: (row: T | null) => void;
+    labels?: Partial<TableLabels>;
+    /** Row rendered when `rows` is empty for the current page. */
+    emptyContent?: React.ReactNode;
+    /**
+     * Forwarded to MUI's `<Table size>` — `'small'` for compact rows,
+     * `'medium'` for the default density. Leave `undefined` (the default)
+     * to let MUI's own default kick in.
+     */
+    size?: MuiTableProps['size'];
+}
+/**
+ * Pure renderer for a paginated, sortable, optionally-selectable table.
+ * Has no widget-store coupling — `<Table>` (the bridge) reads from the store
+ * and feeds this UI with already-projected data.
+ */
+export declare function TableUI<T extends TableRow = TableRow>({ columns, rows, total, page, pageSize, pageSizeOptions, sort, keyColumn, selection, selectable, onSortChange, onPageChange, onPageSizeChange, onSelectionChange, onRowClick, onRowHover, labels, emptyContent, size, }: TableUIProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,50 @@
+import { TableUIProps } from './table-ui';
+import { TableColumn, TableRow, TableSortState } from './types';
+export interface TableProps<T extends TableRow = TableRow> extends Pick<TableUIProps<T>, 'pageSizeOptions' | 'selectable' | 'labels' | 'emptyContent' | 'size' | 'keyColumn'> {
+    /**
+     * Column definitions. Order can be overridden by ChangeColumn via the
+     * `columnOrder` field on the extended widget state.
+     */
+    columns: readonly TableColumn[];
+    /**
+     * When set, render only the first `visibleColumns` entries **after**
+     * applying the user's `columnOrder` from the store. Useful for showing
+     * a compact projection while letting consumers (e.g. `Widget.ChangeColumn`)
+     * see the full column list. When omitted, every column renders.
+     */
+    visibleColumns?: number;
+    /** Initial page size (only on first mount; afterwards lives on the store). */
+    initialPageSize?: number;
+    /** Selected row ids (destination-owned). */
+    selection?: readonly (string | number)[];
+    onSelectionChange?: (next: readonly (string | number)[]) => void;
+    onRowClick?: (row: T) => void;
+    onRowHover?: (row: T | null) => void;
+    /**
+     * When `true`, the bridge stops sorting and paginating locally and
+     * renders `data` as-is — the consumer is then responsible for
+     * refetching the slice that matches the active `page` / `pageSize` /
+     * `sort` from the outbound callbacks below. `total` is required in
+     * this mode (the server already knows the full row count; the
+     * widget can't infer it from a partial page).
+     */
+    remote?: boolean;
+    /**
+     * Server-reported total row count. Required when `remote === true`;
+     * ignored in local mode (where the bridge derives total from the
+     * sorted result of `deriveVisibleRows`).
+     */
+    total?: number;
+    /** Fires after the store-level sort write so the consumer can refetch. */
+    onSortChange?: (next: TableSortState) => void;
+    /** Fires after the store-level page write so the consumer can refetch. */
+    onPageChange?: (page: number) => void;
+    /** Fires after the store-level pageSize write so the consumer can refetch. */
+    onPageSizeChange?: (pageSize: number) => void;
+}
+/**
+ * Bridge component — reads the widget store's `data`, applies sort + pagination
+ * locally, and feeds `<TableUI />`. Sort, page, and pageSize live on the
+ * extended widget state ({@link TableWidgetState}).
+ */
+export declare function Table<T extends TableRow = TableRow>({ columns, visibleColumns, initialPageSize, selection, onSelectionChange, onRowClick, onRowHover, remote, total: remoteTotal, onSortChange, onPageChange, onPageSizeChange, ...uiProps }: TableProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,48 @@
+import { ReactNode } from 'react';
+import { WidgetState } from '../stores';
+/**
+ * Single row of tabular data.
+ *
+ * The default row-identity column is `id`. Consumers that don't have a
+ * literal `id` field can point `<Table>` / `<TableUI>` at a different
+ * column via the `keyColumn` prop; the library reads `row[keyColumn]`
+ * for selection lookup, React keys, and aria labels.
+ */
+export interface TableRow extends Record<string, unknown> {
+    /**
+     * Default row identity. Required when no `keyColumn` is configured.
+     * Omit when wiring `keyColumn` to a different column.
+     */
+    id?: string | number;
+}
+export type TableWidgetData = readonly TableRow[];
+export type TableSortDirection = 'asc' | 'desc';
+export interface TableSortState {
+    columnId: string | null;
+    direction: TableSortDirection;
+}
+export interface TableColumn {
+    /** Unique column identifier; matches the field name on each row. */
+    id: string;
+    /** Header label. */
+    label: ReactNode;
+    align?: 'left' | 'center' | 'right';
+    width?: number | string;
+    sortable?: boolean;
+    /** Custom cell renderer. Falls back to a string-cast of the raw value. */
+    formatter?: (value: unknown, row: TableRow) => ReactNode;
+}
+/**
+ * State extension carrying Table-specific UI state on the per-widget store.
+ * Per R12: widget-specific UI state lives in widget-specific extensions of
+ * `WidgetState`, not on the base type.
+ */
+export interface TableWidgetState extends WidgetState {
+    /** Optional reordered column list driven by ChangeColumn. Falls back to props. */
+    columnOrder?: readonly string[];
+    sort?: TableSortState;
+    page: number;
+    pageSize: number;
+}
+export declare const DEFAULT_TABLE_PAGE_SIZE = 10;
+export declare const DEFAULT_TABLE_PAGE_SIZE_OPTIONS: readonly [10, 25, 50, 100];