@opencorestack/opengridx 3.5.1 → 3.7.0

package/lib/types/dataSource.ts

@@ -0,0 +1,40 @@
+import type { GridRowModel, GridValidRowModel } from './rows';
+import type { GridSortItem } from './sorting';
+import type { GridFilterModel } from './filtering';
+import type { GridAggregationModel } from './grouping';
+
+export interface GridGetRowsParams {
+  startRow: number;
+  endRow: number;
+  sortModel: GridSortItem[];
+  filterModel: GridFilterModel;
+  groupKeys: string[];
+    aggregationModel?: GridAggregationModel;
+}
+
+export interface GridGetRowsResponse<R extends GridValidRowModel = GridRowModel> {
+  rows: R[];
+  rowCount?: number;
+    aggregationResults?: Record<string, unknown>;
+}
+
+/**
+ * Interface for providing data to the grid from a remote source.
+ * Enables server-side sorting, filtering, and pagination.
+ */
+export interface GridDataSource<R extends GridValidRowModel = GridRowModel> {
+  /**
+   * Fetches a chunk of rows based on current grid state.
+   * @param params Sorting, filtering, and range parameters.
+   */
+  getRows: (params: GridGetRowsParams) => Promise<GridGetRowsResponse<R>>;
+  /**
+   * Optional: Fetches aggregation results for the entire dataset.
+   */
+  getAggregations?: (params: Omit<GridGetRowsParams, 'startRow' | 'endRow'>) => Promise<Record<string, unknown>>;
+}
+
+export interface GridPaginationModel {
+  page: number;
+  pageSize: number;
+}

package/lib/types/editing.ts

@@ -0,0 +1,77 @@
+import type { GridRowId, GridRowModel, GridValidRowModel } from './rows';
+import type { GridColDef } from './columns';
+import type { GridCellCoordinates } from './selection';
+
+/** The way a fill extends the cell range. @since v3.5 */
+export type GridFillDirection = 'down' | 'up' | 'right' | 'left';
+
+/** Parameters passed to `GridColDef.fillValue`. @since v3.5 */
+export interface GridFillValueParams<R extends GridValidRowModel = GridRowModel> {
+  /** The row of the cell being filled, as stored now. */
+  row: R;
+  id: GridRowId;
+  field: string;
+  colDef: GridColDef<R>;
+  direction: GridFillDirection;
+  /** The source cells' values in fill order: the value next to the first filled cell is last. */
+  sourceValues: unknown[];
+  /** Position of this cell among the filled cells of its line, from 0 (next to the source). */
+  index: number;
+  /** What the grid would write: the continued series, the repeated pattern or a copy. */
+  value: unknown;
+  /** Whether a copy was asked for (Alt held at release, or the keyboard shortcuts), so no series. */
+  copy: boolean;
+}
+
+/** `onFill` details: the batch edit result plus the direction of the fill. @since v3.5 */
+export interface GridFillResult extends GridBatchEditResult {
+  direction: GridFillDirection;
+}
+
+/**
+ * Why a cell of a batch edit (paste, range clear, undo, redo) was not written:
+ * - `'notEditable'`: the column is not `editable`, `isCellEditable` returned false, or the row is a
+ *   synthetic row (group header, subtotal, tree auto-parent, pivot Grand Total);
+ * - `'invalidValue'`: the pasted text does not parse for the column type (or `valueParser` rejected it);
+ * - `'changed'`: undo/redo only, the cell no longer holds the value the history recorded;
+ * - `'missing'`: undo/redo only, the row is gone.
+ * @since v3.4
+ */
+export type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
+
+/** What a batch edit (paste, range clear, undo, redo) did. @since v3.4 */
+export interface GridBatchEditResult {
+  /** Rows whose `processRowUpdate` succeeded and that were stored, in the order they were first touched. */
+  updated: GridRowId[];
+  /** Rows whose `valueSetter` or `processRowUpdate` threw or rejected (also reported to `onProcessRowUpdateError`). */
+  failed: { id: GridRowId; error: unknown }[];
+  /** Cells that were not written, with the reason. */
+  skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[];
+}
+
+/** `onClipboardPaste` details: the batch edit result plus the text that was pasted. @since v3.4 */
+export interface GridClipboardPasteResult extends GridBatchEditResult {
+  text: string;
+}
+
+/** `onBeforeClipboardPaste` params. @since v3.4 */
+export interface GridBeforeClipboardPasteParams {
+  /** The clipboard text (`text/plain`). */
+  text: string;
+  /** The cell the paste starts from (the range's top-left cell, or the focused cell). */
+  anchor: GridCellCoordinates | null;
+}
+
+/** `onHistoryChange` params. @since v3.4 */
+export interface GridHistoryChangeParams {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Number of actions that can be undone. */
+  size: number;
+}
+
+/** `undoRedo` options. @since v3.4 */
+export interface GridUndoRedoOptions {
+  /** How many actions are kept; the oldest is dropped beyond it. Default: 100. */
+  limit?: number;
+}

package/lib/types/export.ts

@@ -0,0 +1,164 @@
+import type { GridRowId, GridRowModel, GridValidRowModel } from './rows';
+import type { GridFilterModel } from './filtering';
+import type { GridAggregationModel } from './grouping';
+
+/**
+ * Configuration options for exporting the DataGrid to PDF format.
+ * Requires jspdf and jspdf-autotable peer dependencies.
+ */
+export interface PdfExportOptions<R extends GridValidRowModel = GridRowModel> {
+  /**
+   * Output filename without extension. Default: 'export'
+   */
+  fileName?: string;
+
+  /**
+   * Title text displayed in the document header.
+   * When omitted, no header block is rendered.
+   */
+  title?: string;
+
+  /**
+   * URL or data URI of a logo image rendered left of the title.
+   * Only used when `title` is also set. Default: none
+   */
+  logoUrl?: string;
+
+  /**
+   * Page orientation. Default: 'landscape'
+   */
+  orientation?: 'portrait' | 'landscape';
+
+  /**
+   * If provided, only rows whose id is in this array are exported. A non-empty selection takes
+   * precedence over `groupedRows` (the selected rows are exported flat), and the footer totals
+   * are recomputed over the selected rows.
+   */
+  selectedRows?: (string | number)[];
+
+  /**
+   * The grid's `getRowId`, when it has one: `selectedRows` holds those ids, and the grid does not
+   * copy them onto `row.id` (v3.0+). Defaults to `row.id`.
+   */
+  getRowId?: (row: R) => GridRowId;
+
+  /**
+   * Aggregation result from apiRef.current.getAggregationResult().
+   * When provided alongside aggregationModel, appends a footer row.
+   */
+  aggregationResult?: Record<string, unknown> | null;
+
+  /**
+   * Aggregation model from apiRef.current.getAggregationModel().
+   */
+  aggregationModel?: GridAggregationModel | null;
+
+  /**
+   * Active filter model. When provided, a filter summary is shown in the header.
+   */
+  filterModel?: GridFilterModel | null;
+
+  /**
+   * Whether to apply alternating row shading. Default: true
+   */
+  alternateRowColor?: boolean;
+
+  /**
+   * Column header background color (hex). Default: '#4f46e5'
+   */
+  headerBackgroundColor?: string;
+
+  /**
+   * Column header text color (hex). Default: '#ffffff'
+   */
+  headerTextColor?: string;
+
+  /**
+   * Base font size in points for table body. Default: 9
+   */
+  fontSize?: number;
+
+  /**
+   * A TrueType font for the whole document. The built-in Helvetica font only covers Latin-1 and
+   * WinAnsi punctuation (é, ü, €, “ ”, •). Without this option other characters (₹, Greek,
+   * Cyrillic, CJK, Devanagari, U+202F used by some locales as a thousands separator) are
+   * replaced with `?` (spaces and minus signs with their ASCII forms) and a warning is logged.
+   * `data` is the `.ttf` file as a base64 string; `boldData` is an optional bold face for the
+   * title, header and totals (the regular face is used when omitted). jsPDF does not shape
+   * complex scripts, so Devanagari or Arabic ligatures may not join.
+   * @since v3.0
+   */
+  font?: {
+    /** Font family name, e.g. 'NotoSans'. */
+    name: string;
+    /** Base64-encoded .ttf file. */
+    data: string;
+    /** Base64-encoded bold .ttf file. Default: `data`. */
+    boldData?: string;
+  };
+
+  /**
+   * Pre-built grouped export rows from `apiRef.current.getGroupedExportRows()`.
+   * When provided, the PDF table reflects the grouping structure (group headers,
+   * leaf rows, per-group subtotals, grand total) instead of a flat row list.
+   * Has no effect when the grid has no active `rowGroupingModel`, or when `selectedRows` is non-empty.
+   */
+  groupedRows?: GridGroupedExportRow[];
+
+  /**
+   * Called as the export advances: `prepare` (formatting rows; `total` = source rows or grouped
+   * entries), `render` (drawing table rows; `total` = table body rows) and `save` (`0/1` before the
+   * file is written, `1/1` after). `done` never decreases within a phase and ends at `total`.
+   * @since v3.2
+   */
+  onProgress?: (progress: PdfExportProgress) => void;
+
+  /**
+   * Cancels the export. When aborted, the returned promise rejects with a `DOMException` named
+   * `'AbortError'` and no file is saved. Checked between slices of work, so cancellation takes
+   * effect within one slice; the final save step cannot be interrupted once started.
+   * @since v3.2
+   */
+  signal?: AbortSignal;
+
+  /**
+   * Table-row count above which a development-mode warning recommends `exportToCsv` or
+   * `exportToExcelAdvanced`. The export still runs (nothing is thrown). Pass `Infinity` to silence it.
+   * Default: 20000
+   * @since v3.2
+   */
+  maxRows?: number;
+}
+
+/** Progress reported by `PdfExportOptions.onProgress`. @since v3.2 */
+export interface PdfExportProgress {
+  phase: 'prepare' | 'render' | 'save';
+  done: number;
+  total: number;
+}
+
+/**
+ * A single entry in the ordered list returned by `GridApi.getGroupedExportRows()`.
+ * Traverse in array order to reproduce the on-screen grouping structure.
+ */
+export interface GridGroupedExportRow {
+  /** Discriminator: the kind of row this entry represents. */
+  type: 'group-header' | 'leaf' | 'group-subtotal' | 'grand-total';
+  /** Nesting depth (0 = top-level group, 1 = nested group, etc.). */
+  depth: number;
+  /** The grouping field for this level (absent on 'leaf' and 'grand-total'). */
+  groupField?: string;
+  /** The raw grouping value for this level (absent on 'leaf' and 'grand-total'). */
+  groupValue?: unknown;
+  /**
+   * The group label exactly as the grid shows it (from `groupingValueFormatter`, else `"field: value"`),
+   * on 'group-header' and 'group-subtotal' entries from `getGroupedExportRows()`. Exporters use it for
+   * group-header rows; when absent they apply the column's `groupingValueFormatter` themselves.
+   * @since v3.0
+   */
+  groupLabel?: string;
+  /** Per-group aggregation results (present on 'group-subtotal' and 'grand-total'). */
+  aggregatedValues?: Record<string, unknown>;
+  /** The original data row (only present when `type === 'leaf'`). */
+  row?: GridRowModel;
+}

package/lib/types/filtering.ts

@@ -0,0 +1,52 @@
+export type GridFilterOperator =
+  | 'contains'
+  | 'equals'
+  | 'startsWith'
+  | 'endsWith'
+  | 'isEmpty'
+  | 'isNotEmpty'
+  | 'isAnyOf'
+  | '='
+  | '>'
+  | '>='
+  | '<'
+  | '<='
+  | '!='
+  | 'is'
+  | 'not'
+  | 'after'
+  | 'onOrAfter'
+  | 'before'
+  | 'onOrBefore';
+
+/** Describes a filter condition for a specific column. */
+export interface GridFilterItem {
+  /** Optional ID for the filter item. */
+  id?: string | number;
+  /** The field name to filter. */
+  field: string;
+  /** The comparison operator. */
+  operator: GridFilterOperator;
+  /** The value to compare against. */
+  value?: unknown;
+}
+
+/** Describes a group of filters combined with a logical operator. */
+export interface GridFilterGroup {
+    /** Optional ID for the group. */
+    id?: string | number;
+    /** Logical operator to join child items ('and' | 'or'). */
+    logicOperator: 'and' | 'or';
+    /** Array of child filter items or groups. */
+    items: (GridFilterItem | GridFilterGroup)[];
+}
+
+/** The overall state of grid filtering. */
+export interface GridFilterModel {
+  /** Root-level filter items or groups. */
+  items?: (GridFilterItem | GridFilterGroup)[];
+  /** Global logical operator (defaults to 'and'). */
+  logicOperator?: 'and' | 'or';
+  /** Array of strings used for the quick search feature across all columns. */
+  quickFilterValues?: string[];
+}

package/lib/types/grouping.ts

@@ -0,0 +1,27 @@
+export type GridRowGroupingModel = string[];
+
+export interface GridAggregationModel {
+  [field: string]: string;
+}
+
+export type GridAggregationResult = Record<string, unknown>;
+
+/**
+ * Where a group's aggregates are shown, as returned by `getAggregationPosition`: `'inline'` on the group row,
+ * `'footer'` on a subtotal row after the group's children, `null` hidden.
+ */
+export type GridAggregationPosition = 'inline' | 'footer' | null;
+
+export type GridPivotAggFn = 'sum' | 'avg' | 'count' | 'min' | 'max';
+
+export interface GridPivotValueField {
+        field: string;
+        aggFn: GridPivotAggFn;
+        headerName?: string;
+}
+
+export interface GridPivotModel {
+    rowFields:    string[];
+    columnFields: string[];
+    valueFields:  GridPivotValueField[];
+}