grid machine

export declare const canonicalGridChildNames: readonly ["columns", "sort", "filter", "selection", "focus", "edit", "groups", "pagination"];

declare function canonicalGridChildren(value: readonly string[] | undefined): readonly GridChildName[];

export declare const columnsSelectors: {
  columnState: (state: GridColumnsChildState) => GridColumnState;
  order: (state: GridColumnsChildState) => readonly string[];
  widths: (state: GridColumnsChildState) => Readonly<Record<string, number>>;
  pinned: (state: GridColumnsChildState) => Readonly<Record<string, GridColumnPin>>;
  hidden: (state: GridColumnsChildState) => Readonly<Record<string, boolean>>;
};

declare function defaultColumnState<T>(defs: readonly GridColumnDef<T>[]): GridColumnState;

export declare const editSelectors: {
  session: (state: GridEditChildState) => GridEditSession | null;
  isEditing: (state: GridEditChildState, rowId: string, colKey: string | "row") => boolean;
};

export declare const filterSelectors: {
  filterModel: (state: GridFilterChildState) => GridFilterModel;
  quickText: (state: GridFilterChildState) => string;
  conditionFor: (state: GridFilterChildState, key: string) => GridFilterCondition | undefined;
  activeFilterCount: (state: GridFilterChildState) => number;
};

export declare const focusSelectors: {
  focusedCell: (state: GridFocusChildState) => GridFocusCell | null;
  isFocused: (state: GridFocusChildState, rowId: string, colKey: string) => boolean;
};

type GridCellEditReason = "enter" | "tab" | "blur" | "click-away" | "programmatic";

interface GridCellParams<T = unknown> {
  readonly row: T;
  readonly rowId: string;
  readonly column: GridColumnDef<T>;
  readonly value: unknown;
  readonly draft: unknown;
  readonly isEditing: boolean;
  readonly invalid: boolean;
  readonly onChange: (value: unknown) => void;
  readonly commit: (reason?: GridCellEditReason) => void;
  readonly cancel: () => void;
}

declare function gridChildEnabled(children: readonly GridChildName[], name: GridChildName): boolean;

type GridChildName = (typeof canonicalGridChildNames)[number];

type GridColumnChangeReason = "pointer" | "keyboard" | "programmatic";

type GridColumnDef<T = unknown> = {
  readonly key: string;
  readonly header?: string;
  readonly width?: number;
  readonly minWidth?: number;
  readonly maxWidth?: number;
  readonly pinned?: GridColumnPin;
  readonly hidden?: boolean;
  readonly sortable?: boolean;
  readonly filterable?: boolean;
  readonly editable?: boolean;
  readonly resizable?: boolean;
  readonly valueGetter?: (row: T) => unknown;
  readonly comparator?: (left: T, right: T) => number;
  readonly filterType?: "text" | "number" | "date" | "set" | "custom";
  /** Framework-owned render prop. It is a connector sidecar, never machine state. */
  readonly cellRenderer?: (params: GridCellParams<T>) => unknown;
  /** Framework-owned editor slot/render prop. It is a connector sidecar, never machine state. */
  readonly cellEditor?: (params: GridCellParams<T>) => unknown;
};

type GridColumnPin = "start" | "end";

type GridColumnsChildCommand = {
  readonly type: "COLUMN_STATE_CHANGE_REQUEST";
  readonly columnState: GridColumnState;
  readonly reason: GridColumnChangeReason;
} | {
  readonly type: "COLUMN_AUTOSIZE_MEASURE_REQUEST";
  readonly colKey: string;
};

type GridColumnsChildEvent = {
  readonly type: "COLUMN_RESIZE";
  readonly colKey: string;
  readonly width: number;
  readonly reason: GridColumnChangeReason;
} | {
  readonly type: "COLUMN_REORDER";
  readonly colKey: string;
  readonly toIndex: number;
  readonly reason: GridColumnChangeReason;
} | {
  readonly type: "COLUMN_PIN";
  readonly colKey: string;
  readonly side: GridColumnPin | null;
  readonly reason: GridColumnChangeReason;
} | {
  readonly type: "COLUMN_HIDE";
  readonly colKey: string;
  readonly hidden: boolean;
  readonly reason: GridColumnChangeReason;
} | {
  readonly type: "COLUMN_GROUP_TOGGLE";
  readonly groupId: string;
  readonly reason: GridColumnChangeReason;
} | {
  readonly type: "COLUMN_AUTOSIZE_REQUEST";
  readonly colKey: string;
} | {
  readonly type: "COLUMN_AUTOSIZE_MEASURED";
  readonly colKey: string;
  readonly width: number;
};

type GridColumnsChildInput<T = unknown> = {
  readonly columnDefs: readonly GridColumnDef<T>[];
  readonly columnState?: GridColumnState;
  readonly defaultColumnState?: GridColumnState;
};

type GridColumnsChildState = {
  readonly value: "ready";
  readonly context: {
    readonly mode: BindingMode;
    readonly columnState: GridColumnState;
  };
};

type GridColumnState = {
  readonly order: readonly string[];
  readonly widths: Readonly<Record<string, number>>;
  readonly pinned: Readonly<Record<string, GridColumnPin>>;
  readonly hidden: Readonly<Record<string, boolean>>;
  readonly groupCollapse: readonly string[];
};

type GridCommand = GridColumnsChildCommand | GridSortChildCommand | GridFilterChildCommand | SelectionCommand | GridFocusChildCommand | GridEditChildCommand | GridGroupsChildCommand | PaginationCommand | GridRemoteCommand | ScheduleCommand<GridRemoteEvent> | CancelCommand;

type GridContext = {
  readonly columns: GridColumnsChildState | null;
  readonly sort: GridSortChildState | null;
  readonly filter: GridFilterChildState | null;
  readonly selection: SelectionMachineState | null;
  readonly focus: GridFocusChildState | null;
  readonly edit: GridEditChildState | null;
  readonly groups: GridGroupsChildState | null;
  readonly pagination: PaginationMachineState | null;
};

export declare const GridDiagnosticCodes: readonly DiagnosticCatalogueEntry[];

type GridEditChildCommand = {
  readonly type: "EDIT_COMMIT_REQUEST";
  readonly rowId: string;
  readonly colKey: string | "row";
  readonly value: JsonValue;
  readonly previousValue: JsonValue;
  readonly reason: GridEditReason;
};

type GridEditChildEvent = {
  readonly type: "EDIT_START";
  readonly rowId: string;
  readonly colKey: string | "row";
  readonly initialValue: unknown;
} | {
  readonly type: "EDIT_CHANGE";
  readonly draft: unknown;
} | {
  readonly type: "EDIT_COMMIT";
  readonly reason: GridEditReason;
  readonly valid: boolean;
  readonly message?: string;
} | {
  readonly type: "EDIT_CANCEL";
  readonly reason: "escape" | "blur" | "programmatic";
};

type GridEditChildInput = Record<string, never>;

type GridEditChildState = {
  readonly value: "idle" | "editing";
  readonly context: {
    readonly session: GridEditSession | null;
  };
};

type GridEditReason = "enter" | "tab" | "blur" | "click-away" | "programmatic";

type GridEditSession = {
  readonly rowId: string;
  readonly colKey: string | "row";
  readonly draft: unknown;
  readonly previousValue: unknown;
  readonly dirty: boolean;
  readonly invalid: boolean;
};

type GridEvent = GridColumnsChildEvent | GridSortChildEvent | GridFilterChildEvent | SelectionEvent | GridFocusChildEvent | GridEditChildEvent | GridGroupsChildEvent | PaginationEvent | GridRemoteEvent;

type GridFilterChildCommand = {
  readonly type: "FILTER_CHANGE_REQUEST";
  readonly filterModel: GridFilterModel;
  readonly reason: "pointer" | "keyboard" | "programmatic";
};

type GridFilterChildEvent = {
  readonly type: "SET_COLUMN_FILTER";
  readonly colKey: string;
  readonly condition: GridFilterCondition | null;
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "SET_QUICK_FILTER";
  readonly text: string;
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "CLEAR_ALL_FILTERS";
  readonly reason: "pointer" | "keyboard" | "programmatic";
};

type GridFilterChildInput = {
  readonly filterModel?: GridFilterModel;
  readonly defaultFilterModel?: GridFilterModel;
};

type GridFilterChildState = {
  readonly value: "ready";
  readonly context: {
    readonly mode: BindingMode;
    readonly filterModel: GridFilterModel;
  };
};

type GridFilterCondition = {
  readonly type: "text";
  readonly operator: "contains" | "equals" | "startsWith" | "endsWith";
  readonly value: string;
} | {
  readonly type: "number";
  readonly operator: "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "between";
  readonly value: number;
  readonly valueTo?: number;
} | {
  readonly type: "date";
  readonly operator: "eq" | "before" | "after" | "between";
  readonly value: string;
  readonly valueTo?: string;
} | {
  readonly type: "set";
  readonly values: readonly string[];
} | {
  readonly type: "custom";
  readonly predicateId: string;
  readonly value: JsonValue;
};

type GridFilterModel = {
  readonly columns: Readonly<Record<string, GridFilterCondition>>;
  readonly quickText: string;
};

type GridFocusCell = {
  readonly rowId: string;
  readonly colKey: string;
};

type GridFocusChildCommand = {
  readonly type: "FOCUS_CHANGE_REQUEST";
  readonly rowId: string | null;
  readonly colKey: string | null;
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "SCROLL_INTO_VIEW_REQUEST";
  readonly rowId: string;
  readonly colKey: string;
};

type GridFocusChildEvent = {
  readonly type: "FOCUS_CELL";
  readonly rowId: string;
  readonly colKey: string;
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "FOCUS_MOVE";
  readonly direction: GridFocusDirection;
  readonly target?: GridFocusCell;
  readonly extend?: boolean;
} | {
  readonly type: "FOCUS_CLEAR";
  readonly reason?: "pointer" | "keyboard" | "programmatic";
};

type GridFocusChildInput = {
  readonly rowIds?: readonly string[];
  readonly columnKeys?: readonly string[];
};

type GridFocusChildState = {
  readonly value: "ready";
  readonly context: {
    readonly focusedCell: GridFocusCell | null;
  };
};

type GridFocusDirection = "up" | "down" | "left" | "right" | "row-start" | "row-end" | "grid-start" | "grid-end" | "page-up" | "page-down";

type GridGroupsChildCommand = {
  readonly type: "GROUP_STATE_CHANGE_REQUEST";
  readonly groupBy: readonly string[];
  readonly reason: "pointer" | "keyboard" | "programmatic";
};

type GridGroupsChildEvent = {
  readonly type: "SET_GROUP_BY";
  readonly columnKeys: readonly string[];
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "GROUP_TOGGLE";
  readonly groupKey: string;
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "GROUP_EXPAND_ALL";
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "GROUP_COLLAPSE_ALL";
  readonly reason: "pointer" | "keyboard" | "programmatic";
} | {
  readonly type: "SET_AGGREGATION";
  readonly colKey: string;
  readonly aggType: string;
  readonly reason: "pointer" | "keyboard" | "programmatic";
};

type GridGroupsChildInput = {
  readonly groupBy?: readonly string[];
  readonly defaultGroupBy?: readonly string[];
  readonly aggFor?: Readonly<Record<string, "sum" | "avg" | "count" | "min" | "max" | "custom">>;
};

type GridGroupsChildState = {
  readonly value: "ready";
  readonly context: {
    readonly mode: BindingMode;
    readonly groupBy: readonly string[];
    readonly expandedGroupKeys: readonly string[];
    readonly aggFor: Readonly<Record<string, string>>;
  };
};

type GridInput<T = unknown> = {
  readonly children?: readonly string[];
  readonly columns?: GridColumnsChildInput<T>;
  readonly sort?: GridSortChildInput;
  readonly filter?: GridFilterChildInput;
  readonly selection?: SelectionInput;
  readonly focus?: GridFocusChildInput;
  readonly edit?: GridEditChildInput;
  readonly groups?: GridGroupsChildInput;
  readonly pagination?: PaginationInput;
  readonly mode?: "virtualized" | "paginated";
  /** Configuration only: fetched rows always remain in the headless sidecar. */
  readonly rowModel?: GridRowModel;
  readonly remote?: {
    readonly blockSize?: number;
    readonly loadMoreThreshold?: number;
  };
};

export declare const gridMachine: GridMachine<any>;

type GridMachine<T = unknown> = Machine<GridInput<T>, GridStateValue, GridContext, GridEvent, GridCommand>;

type GridMachineState = MachineState<GridStateValue, GridContext>;

type GridRemoteCommand = {
  readonly type: "GRID_ROWS_REQUEST";
  readonly key: "grid.rows";
  readonly request: GridRemoteQuery;
  readonly onSettled: {
    readonly type: "GRID_ROWS_LOADED" | "GRID_ROWS_APPENDED";
    readonly payloadKey: "result";
  };
  readonly onFailed: {
    readonly type: "GRID_ROWS_FAILED";
    readonly payloadKey: "error";
  };
} | {
  readonly type: "GRID_ROWS_ADOPT";
  readonly result: GridSerializableRemoteResult;
  readonly append: boolean;
} | {
  readonly type: "GRID_ROWS_ADOPT_ERROR";
  readonly error: JsonValue;
};

type GridRemoteEvent = {
  readonly type: "GRID_REMOTE_RETRY";
  readonly request: GridRemoteQuery;
} | {
  readonly type: "GRID_REMOTE_LOAD_MORE";
  readonly request: GridRemoteQuery;
} | {
  readonly type: "GRID_REMOTE_WINDOW";
  readonly start: number;
  readonly end: number;
} | {
  readonly type: "GRID_REMOTE_QUERY_DUE";
  readonly request: GridRemoteQuery;
} | {
  readonly type: "GRID_ROWS_LOADED";
  readonly result: GridSerializableRemoteResult;
} | {
  readonly type: "GRID_ROWS_APPENDED";
  readonly result: GridSerializableRemoteResult;
} | {
  readonly type: "GRID_ROWS_FAILED";
  readonly error: JsonValue;
};

type GridRemoteQuery = {
  readonly rowModel: "server" | "infinite";
  readonly operation: "replace" | "append";
  readonly sortModel: readonly GridSortEntry[];
  readonly filterModel: GridFilterModel;
  readonly page?: {
    readonly page: number;
    readonly pageSize: number;
  };
  readonly range?: {
    readonly start: number;
    readonly end: number;
  };
  readonly cursor?: JsonValue;
};

type GridRemoteResult<T = unknown> = {
  readonly rows: readonly T[];
  readonly total?: number;
  readonly nextCursor?: JsonValue | null;
};

export declare const gridReplaySequence: readonly GridEvent[];

type GridRowModel = "client" | "server" | "infinite";

export declare const gridSelectors: {
  columns: (snapshot: GridSnapshot) => GridColumnsChildState | null;
  sort: (snapshot: GridSnapshot) => GridSortChildState | null;
  filter: (snapshot: GridSnapshot) => GridFilterChildState | null;
  selection: (snapshot: GridSnapshot) => SelectionMachineState | null;
  focus: (snapshot: GridSnapshot) => GridFocusChildState | null;
  edit: (snapshot: GridSnapshot) => GridEditChildState | null;
  groups: (snapshot: GridSnapshot) => GridGroupsChildState | null;
  pagination: (snapshot: GridSnapshot) => PaginationMachineState | null;
  sortModel: (snapshot: GridSnapshot) => readonly GridSortEntry[];
  filterModel: (snapshot: GridSnapshot) => GridFilterModel;
  selectedIds: (snapshot: GridSnapshot) => SelectionValue;
  focusedCell: (snapshot: GridSnapshot) => GridFocusCell | null;
  editSession: (snapshot: GridSnapshot) => GridEditSession | null;
  groupBy: (snapshot: GridSnapshot) => readonly string[];
  expandedGroupKeys: (snapshot: GridSnapshot) => readonly string[];
  page: (snapshot: GridSnapshot) => number;
  enabledChildren: (snapshot: GridSnapshot) => GridChildName[];
  columnState: (snapshot: GridSnapshot) => GridColumnState | null;
};

type GridSnapshot = Snapshot<GridStateValue, GridContext>;

type GridSortChildCommand = {
  readonly type: "SORT_CHANGE_REQUEST";
  readonly sortModel: readonly GridSortEntry[];
  readonly reason: "pointer" | "keyboard" | "programmatic";
};

type GridSortChildEvent = {
  readonly type: "TOGGLE_SORT";
  readonly key: string;
  readonly sortable: boolean;
  readonly modifier: "replace" | "add";
  readonly reason?: "pointer" | "keyboard" | "programmatic";
};

type GridSortChildInput = {
  readonly sortModel?: readonly GridSortEntry[];
  readonly defaultSortModel?: readonly GridSortEntry[];
  readonly multiSort?: boolean;
  readonly maxSortKeys?: number;
};

type GridSortChildState = {
  readonly value: "ready";
  readonly context: {
    readonly mode: BindingMode;
    readonly sortModel: readonly GridSortEntry[];
  };
};

type GridSortDir = "asc" | "desc";

type GridSortEntry = {
  readonly key: string;
  readonly dir: GridSortDir;
};