grid headless API

declare function applyTransaction<T>(cache: GridRowProjectionCache<T>, transaction: {
  readonly add?: readonly {
    readonly row: T;
    readonly index?: number;
  }[];
  readonly update?: readonly T[];
  readonly remove?: readonly string[];
}, model: GridRowProjectionModel<T>): GridRowProjection<T>;

declare function computeColumnWindow(params: {
  readonly scrollOffset: number;
  readonly viewportSize: number;
  readonly columnCount: number;
  readonly estimatedColumnSize: number;
  readonly overscan?: number;
}): VirtualWindow;

declare function computeVirtualWindow(params: {
  readonly scrollOffset: number;
  readonly viewportSize: number;
  readonly itemCount: number;
  readonly estimatedItemSize: number;
  readonly measuredSizes?: ReadonlyMap<number, number>;
  readonly overscan?: number;
}): VirtualWindow;

declare function connectGrid<T>(service: GridService<T>, scope: PartScope, options: GridConnectOptions<T>, remoteSnapshot?: GridRemoteSnapshot<T> | (() => GridRemoteSnapshot<T>)): GridApi<T>;

declare function createGridInput<T>(options: GridConnectOptions<T>, remoteSnapshot?: GridRemoteSnapshot<T>): GridInput<T>;

declare function createGridRemoteRows<T>(options: GridRemoteRowsOptions<T>): GridRemoteRows<T>;

declare function createGridRemoteRunCommand<T>(options: GridRemoteRunCommandOptions<T>): RunCommand<GridCommand, GridEvent>;

declare function createGridRowProjectionCache<T>(): GridRowProjectionCache<T>;

declare function exportGridCSV<T>(projection: GridRowProjection<T>, columnDefs: readonly GridColumnDef<T>[], options?: {
  readonly includeHeader?: boolean;
  readonly delimiter?: string;
}): string;

export declare const GRID_ROW_HEIGHT: 44;

export declare const GRID_SELECTION_COLUMN_WIDTH: 44;

export declare const GRID_VIEWPORT_HEIGHT: 352;

export declare const gridAnatomy: {
  readonly scope: "grid";
  readonly parts: readonly ["root", "scroller", "content", "header", "header-row", "header-cell", "column-resize-handle", "column-menu-trigger", "body", "row", "group-row", "group-toggle", "cell", "cell-editor", "select-all", "row-checkbox", "quick-filter-input", "column-filter-panel", "overlay", "live-region"];
};

interface GridApi<T = unknown> {
  rootProps(): PartProps;
  scrollerProps(): PartProps;
  contentProps(): PartProps;
  headerProps(): PartProps;
  headerRowProps(): PartProps;
  selectionHeaderProps(): PartProps;
  headerCellProps(columnKey: string): PartProps;
  columnResizeHandleProps(columnKey: string): PartProps;
  columnMenuTriggerProps(columnKey: string): PartProps;
  bodyProps(): PartProps;
  rowProps(rowId: string, index: number): PartProps;
  groupRowProps(groupKey: string, index: number): PartProps;
  groupToggleProps(groupKey: string): PartProps;
  selectionCellProps(rowId: string): PartProps;
  cellProps(rowId: string, columnKey: string, columnIndex: number): PartProps;
  cellEditorProps(rowId: string, columnKey: string): PartProps;
  selectAllProps(): PartProps;
  rowCheckboxProps(rowId: string): PartProps;
  quickFilterInputProps(): PartProps;
  columnFilterPanelProps(columnKey: string): PartProps;
  overlayProps(kind: "loading" | "empty" | "error"): PartProps;
  liveRegionProps(): PartProps;
  columnDefs: readonly GridColumnDef<T>[];
  columnProjection(): GridColumnProjection<T>;
  projection(): GridRowProjection<T>;
  rowIdDiagnostics(): readonly DiagnosticObject[];
  readonly selectionMode: SelectionMode;
  readonly selectedIds: readonly string[];
}

declare function gridCellParams<T>(service: GridService<T>, options: GridConnectOptions<T>, row: T, rowId: string, column: GridColumnDef<T>): GridCellParams<T>;

type GridCellValidation = boolean | {
  readonly valid: boolean;
  readonly message?: string;
};

type GridColumnProjection<T = unknown> = {
  readonly columns: readonly GridColumnDef<T>[];
  readonly widths: Readonly<Record<string, number>>;
  readonly pinnedOffsets: Readonly<Record<string, number>>;
  readonly gridTemplateColumns: string;
};

type GridConnectOptions<T = unknown> = GridCommonOptions<T> & GridRowsInput<T>;

type GridDataSource<T> = (query: GridRemoteQuery, tools: {
  readonly signal: AbortSignal;
}) => PromiseLike<{
  readonly rows: readonly T[];
  readonly total?: number;
  readonly nextCursor?: import("@grassroot/statechart").JsonValue | null;
}>;

interface GridEditCommitDetail<T = unknown> {
  readonly rowId: string;
  readonly colKey: string;
  readonly value: unknown;
  readonly previousValue: unknown;
  readonly reason: string;
  readonly row?: T;
  readonly column?: GridColumnDef<T>;
}

type GridGroup<T> = {
  readonly key: string;
  readonly level: number;
  readonly ids: readonly string[];
  readonly rows: readonly T[];
};

declare function gridKeyboardEvent(event: GridKeyboardEventLike, position: GridKeyboardPosition, rowCount: number, columnCount: number): GridKeyboardResult | null;

type GridKeyboardEventLike = {
  readonly key?: string;
  readonly ctrlKey?: boolean;
  readonly metaKey?: boolean;
  readonly shiftKey?: boolean;
  preventDefault?: () => void;
};

type GridKeyboardPosition = {
  readonly rowIndex: number;
  readonly columnIndex: number;
};

type GridKeyboardResult = {
  readonly direction: GridFocusDirection;
  readonly extend?: boolean;
};

interface GridMount<T> {
  destroy(): void;
  service: ReturnType<typeof createService>;
  api: GridApi<T>;
  remote?: GridRemoteRows<T>;
}

type GridPart = (typeof parts)[number];

declare function gridProjection<T>(service: GridService<T>, options: GridConnectOptions<T>, remoteSnapshot?: GridRemoteSnapshot<T> | (() => GridRemoteSnapshot<T>)): GridRowProjection<T>;

type GridRemoteRows<T> = {
  readonly getSnapshot: () => GridRemoteSnapshot<T>;
  readonly subscribe: (listener: () => void) => () => void;
  readonly begin: (request: GridRemoteQuery) => boolean;
  readonly handleCommand: (command: GridRemoteCommand) => boolean;
  readonly covers: (range: {
    readonly start: number;
    readonly end: number;
  }) => boolean;
  readonly nextAppendRequest: () => GridRemoteQuery | null;
  readonly selectWindow: (range: {
    readonly start: number;
    readonly end: number;
  }) => void;
  readonly destroy: () => void;
};

type GridRemoteRowsOptions<T> = {
  readonly rowModel: "server" | "infinite";
  readonly getRowId: (row: T, absoluteIndex: number) => string;
  readonly blockSize?: number;
  readonly initialRows?: readonly T[];
  readonly initialTotal?: number;
  readonly onDiagnostic?: (diagnostic: DiagnosticObject) => void;
};

type GridRemoteRunCommandOptions<T> = {
  readonly dataSource: GridDataSource<T>;
  readonly sidecar: GridRemoteRows<T>;
  readonly scheduler?: Scheduler;
  readonly next?: RunCommand<GridCommand, GridEvent>;
  readonly onDiagnostic?: (diagnostic: DiagnosticObject) => void;
};

type GridRemoteSnapshot<T> = {
  readonly rows: readonly T[];
  /** Absolute index represented by rows[0] for a server virtual window. */
  readonly baseIndex?: number;
  readonly total?: number;
  readonly nextCursor?: import("@grassroot/statechart").JsonValue | null;
  readonly status: GridRemoteStatus;
  readonly error?: unknown;
  readonly loadedRanges: readonly {
    readonly start: number;
    readonly end: number;
  }[];
  readonly lastRequest?: GridRemoteQuery;
};

type GridRemoteStatus = "idle" | "loading" | "refreshing" | "loading-more" | "error";

declare function gridRemoteWindowEvent<T>(options: {
  readonly rowModel: "server" | "infinite";
  readonly mode?: "virtualized" | "paginated";
  readonly sidecar: GridRemoteRows<T>;
  readonly start: number;
  readonly end: number;
  readonly loadMoreThreshold?: number;
}): GridEvent | null;

type GridRowProjection<T> = {
  readonly orderedIds: readonly string[];
  readonly rowsById: ReadonlyMap<string, T>;
  readonly groups: readonly GridGroup<T>[];
  readonly aggregates: ReadonlyMap<string, Readonly<Record<string, number>>>;
  readonly total: number;
  /** Absolute index represented by orderedIds[0]; zero for client and infinite rows. */
  readonly baseIndex?: number;
  readonly rowIndexById?: ReadonlyMap<string, number>;
  readonly cache?: GridRowProjectionCache<T>;
};

interface GridRowProjectionCache<T> {
  rows?: readonly T[];
  model?: GridRowProjectionModel<T>;
  projection?: GridRowProjection<T>;
}

type GridRowProjectionModel<T> = {
  readonly filterModel: GridFilterModel;
  readonly sortModel: readonly GridSortEntry[];
  readonly groupModel: {
    readonly groupBy: readonly string[];
    readonly expandedGroupKeys: readonly string[];
    readonly aggFor?: Readonly<Record<string, "sum" | "avg" | "count" | "min" | "max" | "custom">>;
  };
  readonly getRowId: (row: T, index: number) => string;
  readonly columnDefs: readonly GridColumnDef<T>[];
  readonly page?: {
    readonly page: number;
    readonly pageSize: number;
  };
  readonly customFilters?: Readonly<Record<string, (row: T, value: unknown) => boolean>>;
};

type GridService<T = unknown> = Service<GridInput<T>, "ready", GridContext, GridEvent, GridCommand>;

declare function gridValue<T>(row: T, column: GridColumnDef<T>): unknown;

declare function mountGrid<T>(container: HTMLElement, options: MountGridOptions<T>): GridMount<T>;

type MountGridOptions<T> = GridConnectOptions<T> & {
  readonly input?: Parameters<typeof gridMachine.initial>[0];
  readonly seed?: string;
};

declare function projectColumns<T>(columnDefs: readonly GridColumnDef<T>[], columnState: GridColumnState): GridColumnProjection<T>;

declare function projectRemoteRows<T>(rows: readonly T[], options: {
  readonly getRowId: (row: T, absoluteIndex: number) => string;
  readonly baseIndex?: number;
  readonly total: number;
}): GridRowProjection<T>;

declare function projectRows<T>(rows: readonly T[], model: GridRowProjectionModel<T>, cache?: GridRowProjectionCache<T>): GridRowProjection<T>;

declare function resolveGridKeyboardTarget(result: GridKeyboardResult, position: GridKeyboardPosition, rowCount: number, columnCount: number): GridKeyboardPosition;

declare function runGridCommand<T>(command: GridCommand, options: GridConnectOptions<T>, _service: GridService<T>): void;

declare function validateGridRowIds<T>(rows: readonly T[], getRowId: (row: T, index: number) => string): readonly DiagnosticObject[];

type VirtualWindow = {
  readonly start: number;
  readonly end: number;
  readonly offsets: readonly number[];
  readonly totalSize: number;
};