@happyvertical/smrt-ui 0.42.2 → 0.42.4

package/dist/components/data/DataTableController.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Headless, transport-neutral state for DataTable.
+ *
+ * The controller intentionally stores only view preferences. It never stores
+ * rows, callbacks, query objects, principals, or persistence adapters.
+ */
+export type DataTableRowId = string | number;
+/** A caller-owned binding for an all-matching server-side selection. */
+export interface DataTableQueryRevision {
+    queryFingerprint: string;
+    queryRevision: string;
+}
+/**
+ * Selection is deliberately a tagged union. `allMatching` never serializes
+ * loaded IDs: the receiving action must verify its query binding before use.
+ */
+export type DataTableSelection = {
+    scope: 'page';
+    rowIds: DataTableRowId[];
+} | {
+    scope: 'explicit';
+    rowIds: DataTableRowId[];
+} | ({
+    scope: 'allMatching';
+    expectedCount: number;
+} & DataTableQueryRevision);
+export type DataTableJsonPrimitive = string | number | boolean | null;
+export type DataTableJsonValue = DataTableJsonPrimitive | DataTableJsonValue[] | {
+    [key: string]: DataTableJsonValue;
+};
+export type DataTableOperationMode = 'local' | 'manual';
+/** Which layer owns each transformation. `manual` means the caller supplied it. */
+export interface DataTableModes {
+    filtering: DataTableOperationMode;
+    sorting: DataTableOperationMode;
+    pagination: DataTableOperationMode;
+}
+export interface DataTableSortRule {
+    columnId: string;
+    direction: 'asc' | 'desc';
+}
+export type DataTableFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte' | 'isNull' | 'isNotNull';
+/** A serializable, declarative filter. Filters are combined with AND semantics. */
+export interface DataTableFilter {
+    columnId: string;
+    operator: DataTableFilterOperator;
+    value?: DataTableJsonValue;
+}
+/** A column visibility entry. The array form keeps snapshots JSON-safe. */
+export interface DataTableColumnVisibility {
+    columnId: string;
+    visible: boolean;
+}
+/**
+ * The JSON-safe, persistable portion of a table view. Selection and expansion
+ * are serialized as canonical arrays rather than Sets.
+ */
+export interface DataTableViewState {
+    search: string;
+    filters: DataTableFilter[];
+    sorting: DataTableSortRule[];
+    page: number;
+    pageSize: number | null;
+    columnOrder: string[];
+    columnVisibility: DataTableColumnVisibility[];
+    selection: DataTableSelection;
+    /**
+     * Legacy shorthand for row-ID selections. It is always derived from
+     * `selection`, and is empty for `allMatching` selections.
+     */
+    selectedRowIds: DataTableRowId[];
+    expandedRowIds: DataTableRowId[];
+}
+/**
+ * Accepts a version-1 controlled state while the controller always emits the
+ * normalized version-2 `DataTableViewState` with an explicit selection.
+ */
+export type DataTableViewStateInput = Omit<DataTableViewState, 'selection'> & {
+    selection?: DataTableSelection;
+};
+/** The stable envelope intended for URL and saved-view adapters. */
+export interface DataTableSnapshot {
+    version: 2;
+    modes: DataTableModes;
+    state: DataTableViewState;
+}
+/** Every mutable table interaction has a plain-data command representation. */
+export type DataTableCommand = {
+    type: 'setSearch';
+    search: string;
+} | {
+    type: 'setFilters';
+    filters: DataTableFilter[];
+} | {
+    type: 'setSorting';
+    sorting: DataTableSortRule[];
+} | {
+    type: 'toggleSorting';
+    columnId: string;
+    multi?: boolean;
+} | {
+    type: 'setPage';
+    page: number;
+} | {
+    type: 'setPageSize';
+    pageSize: number | null;
+} | {
+    type: 'setColumnOrder';
+    columnIds: string[];
+} | {
+    type: 'setColumnVisibility';
+    columns: DataTableColumnVisibility[];
+} | {
+    type: 'setSelection';
+    selection: DataTableSelection;
+} | {
+    type: 'setPageSelection';
+    rowIds: DataTableRowId[];
+} | ({
+    type: 'selectAllMatching';
+    expectedCount: number;
+} & DataTableQueryRevision) | {
+    type: 'setSelectedRows';
+    rowIds: DataTableRowId[];
+} | {
+    type: 'toggleRowSelection';
+    rowId: DataTableRowId;
+} | {
+    type: 'setExpandedRows';
+    rowIds: DataTableRowId[];
+} | {
+    type: 'toggleRowExpansion';
+    rowId: DataTableRowId;
+} | {
+    type: 'reset';
+};
+export interface DataTableTransition {
+    command: DataTableCommand | null;
+    previous: DataTableSnapshot;
+    next: DataTableSnapshot;
+    changed: boolean;
+}
+export interface DataTableControllerOptions {
+    /** Used by uncontrolled controllers. */
+    initialState?: Partial<DataTableViewState>;
+    /** Makes transitions proposals until `replaceState` supplies the next value. */
+    state?: DataTableViewStateInput;
+    modes?: Partial<DataTableModes>;
+    /** Optional known columns let the controller ignore stale saved-view fields. */
+    columnIds?: readonly string[];
+    onStateChange?: (state: DataTableViewState, command: DataTableCommand) => void;
+}
+export type DataTableStateListener = (transition: DataTableTransition) => void;
+export declare function assertDataTableRowId(value: unknown): DataTableRowId;
+export declare function compareDataTableRowIds(left: DataTableRowId, right: DataTableRowId): number;
+export declare function dataTableRowIdKey(value: DataTableRowId): string;
+/**
+ * Refuse an all-matching selection when the action's query has changed since
+ * selection. Domain actions must call this before a destructive operation.
+ */
+export declare function assertDataTableSelectionCurrent(selection: DataTableSelection, currentQuery: DataTableQueryRevision): void;
+/** Apply one command without mutating the supplied state. */
+export declare function transitionDataTableState(state: DataTableViewState, command: DataTableCommand): DataTableViewState;
+/** Parse persisted state defensively before an external adapter restores it. */
+export declare function hydrateDataTableSnapshot(value: unknown): DataTableSnapshot;
+/** A headless state owner used by both rendered controls and programmatic commands. */
+export declare class DataTableController {
+    private state;
+    private modes;
+    private columnIds?;
+    private controlled;
+    private readonly listeners;
+    private readonly onStateChange?;
+    private pendingControlledState?;
+    constructor(options?: DataTableControllerOptions);
+    getState(): DataTableViewState;
+    getModes(): DataTableModes;
+    snapshot(): DataTableSnapshot;
+    subscribe(listener: DataTableStateListener): () => void;
+    /** Dispatches a serializable command. Controlled controllers emit a proposal only. */
+    dispatch(command: DataTableCommand): DataTableTransition;
+    /** Supplies state from a controlled host or an external persistence adapter. */
+    replaceState(state: DataTableViewStateInput): DataTableTransition;
+    /** Changes ownership without treating it as a user command. */
+    setControlled(controlled: boolean): void;
+    /** Configures transformation ownership; this remains outside persisted state. */
+    setModes(modes: Partial<DataTableModes>): DataTableTransition;
+    /** Reconciles stale saved-view column IDs with the renderer's current columns. */
+    setColumnIds(columnIds: readonly string[]): DataTableTransition;
+    /** Clamp against a reliable total. A missing total intentionally does not guess. */
+    clampPage(totalRows: number | null | undefined): DataTableTransition;
+    private emit;
+}
+export declare function createDataTableController(options?: DataTableControllerOptions): DataTableController;
+//# sourceMappingURL=DataTableController.d.ts.map

package/dist/components/data/DataTableController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataTableController.d.ts","sourceRoot":"","sources":["../../../src/components/data/DataTableController.ts"],"names":[],"mappings":"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"}