@gridengine/angular-datagrid-enterprise 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gridengine/angular-datagrid-enterprise",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Pro/Enterprise features for the GridEngine Angular data grid (license-gated).",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {

package/types/gridengine-angular-datagrid-enterprise.d.ts

@@ -1,3 +1,4 @@
+import { ColDef } from '@gridengine/angular-datagrid';
 export * from '@gridengine/angular-datagrid';
 import * as _angular_core from '@angular/core';
 import { EnvironmentProviders } from '@angular/core';
@@ -768,5 +769,228 @@ declare class SavedViewsEngine {
     private _notify;
 }
 
-export { AuditTrailEngine, CellPermissionEngine, ClipboardEngine, DEFAULT_MASK, DataGridPro, FillHandleEngine, FilterPresetEngine, FormulaEngine, GridLicenseWatermark, LicenseManager, MasterDetailEngine, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, RowLockEngine, SSRMEngine, SavedViewsEngine, TransactionEngine, UndoRedoManager, deserializeFilter, evaluateFilter, parseTSV, provideGridEngineLicense, serializeFilter, toNumber, toTimestamp };
-export type { AuditEntry, AuditTrailEngineOptions, Block, BlockState, CellEditCommand, CellPermission, CellPermissionEngineOptions, CellRange, ClipboardEngineOptions, DeleteCommand, DetailEntry, DetailLoadState, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, FilterCondition, FilterGroup, FilterNode, FilterOperator, FilterPreset, FilterPresetEngineOptions, FormulaEngineOptions, GridRow, LockedRow, MasterDetailEngineOptions, PasteCommand, RangeSelectionEngineOptions, RowLockEngineOptions, SSRMDataSource, SSRMEngineOptions, SSRMGetRowsParams, SSRMGetRowsResult, SavedView, SavedViewsEngineOptions, TransactionDelta, TransactionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };
+/**
+ * ExcelImportEngine — a dependency-free import pipeline that turns a tabular
+ * matrix (header row + data rows) into validated grid rows. File parsing is
+ * kept OUT of the engine: use `parseCSV()` for delimited text, or feed a
+ * `string[][]` produced by SheetJS for .xlsx. Pipeline: loadMatrix → (auto)
+ * mapping → validate → buildRows.
+ */
+
+/** Data type used to validate and coerce imported cell values. */
+type ImportColumnType = 'string' | 'number' | 'boolean' | 'date';
+interface ImportColumn {
+    /** Target grid field the source column maps to. */
+    field: string;
+    /** Header text used for auto-matching against the source sheet. */
+    headerName: string;
+    /** Expected data type. Values are validated/coerced against it. Default: 'string' */
+    type?: ImportColumnType;
+    /** Whether a value is required (empty cells produce a validation error). */
+    required?: boolean;
+}
+/** A single validation problem found during import. */
+interface ImportValidationError {
+    /** Zero-based index into the source data rows (excludes the header row). */
+    rowIndex: number;
+    field: string;
+    value: string;
+    message: string;
+}
+interface ExcelImportEngineOptions {
+    /** Target columns the importer can map onto. */
+    columns: ImportColumn[];
+    /** Explicit source-header → target-field mapping, overriding auto-match. */
+    columnMapping?: Record<string, string>;
+}
+interface ImportPreview {
+    rows: GridRow[];
+    errors: ImportValidationError[];
+}
+/**
+ * Parse delimited text into a matrix of string cells. Handles quoted fields
+ * containing the delimiter, newlines, and escaped quotes (`""`), plus `\n` and
+ * `\r\n` line endings.
+ */
+declare function parseCSV(text: string, delimiter?: string): string[][];
+declare class ExcelImportEngine {
+    private readonly _columns;
+    private _headers;
+    private _dataRows;
+    /** sourceHeader → targetField (null = unmapped). */
+    private _mapping;
+    constructor(options: ExcelImportEngineOptions);
+    /**
+     * Load a matrix of raw cells.
+     * @param matrix        Full sheet, including the header row when hasHeaderRow.
+     * @param hasHeaderRow  When true (default) the first row is treated as headers.
+     */
+    loadMatrix(matrix: string[][], hasHeaderRow?: boolean): void;
+    /** Parse delimited text and load it as the source matrix. */
+    loadCSV(text: string, delimiter?: string, hasHeaderRow?: boolean): void;
+    private _autoMap;
+    getHeaders(): readonly string[];
+    /** Current source-header → target-field mapping. */
+    getMapping(): Record<string, string | null>;
+    /** Manually map (or unmap with null) a source header to a target field. */
+    setMapping(sourceHeader: string, field: string | null): void;
+    /** Source headers not yet mapped to a target field. */
+    getUnmappedHeaders(): string[];
+    /** Target fields that have no source column mapped to them. */
+    getUnmappedFields(): string[];
+    /** Validate all data rows against the mapped column types. */
+    validate(): ImportValidationError[];
+    /** Build validated rows (rows with errors are still returned, best-effort). */
+    buildRows(): GridRow[];
+    /** Full preview: rows plus any validation errors. */
+    preview(): ImportPreview;
+    private _process;
+    /** Number of data rows currently loaded (excludes the header row). */
+    get rowCount(): number;
+}
+
+/**
+ * PDFExportEngine — turns rows + columns + branding options into a paginated,
+ * renderer-agnostic document model (`PdfDocumentModel`). A thin adapter can feed
+ * that model to jsPDF, pdfmake, or an HTML-to-PDF pipeline without this engine
+ * depending on any of them. It preserves the given row/column order, so callers
+ * pass the already filtered/sorted view ("export what the user sees").
+ */
+
+interface PdfExportOptions {
+    /** Report title rendered in the header. */
+    title?: string;
+    /** Logo image URL rendered in the header. */
+    logo?: string;
+    /** Footer text rendered on every page. */
+    footer?: string;
+    /** Page size. Default: 'A4' */
+    pageSize?: 'A4' | 'Letter' | 'Legal';
+    /** Page orientation. Default: 'landscape' */
+    orientation?: 'portrait' | 'landscape';
+    /** Rows per page. Default: 25 */
+    rowsPerPage?: number;
+}
+interface PdfColumn {
+    field: string;
+    headerName: string;
+    /** Optional formatter for the cell value. */
+    format?: (value: unknown, row: GridRow) => string;
+}
+interface PdfPageHeader {
+    title?: string;
+    logo?: string;
+    /** ISO timestamp the export was generated. */
+    generatedAt: string;
+}
+interface PdfPageFooter {
+    text?: string;
+    pageNumber: number;
+    pageCount: number;
+}
+interface PdfPage {
+    header: PdfPageHeader;
+    footer: PdfPageFooter;
+    columnHeaders: string[];
+    /** Already-formatted cell text for each row on this page. */
+    rows: string[][];
+}
+interface PdfDocumentModel {
+    pageSize: NonNullable<PdfExportOptions['pageSize']>;
+    orientation: NonNullable<PdfExportOptions['orientation']>;
+    pages: PdfPage[];
+}
+interface PDFExportEngineOptions extends PdfExportOptions {
+    columns: PdfColumn[];
+    /** Injectable clock for deterministic timestamps in tests. */
+    now?: () => Date;
+}
+declare class PDFExportEngine {
+    private readonly _columns;
+    private readonly _options;
+    private readonly _now;
+    constructor(options: PDFExportEngineOptions);
+    /** Build the paginated document model from the given (already-visible) rows. */
+    build(rows: GridRow[]): PdfDocumentModel;
+    private _formatRow;
+}
+
+/**
+ * FormEditorEngine — backs a slide-in form editor panel: tracks which row is
+ * open, holds an editable draft with dirty-state detection, and supports
+ * prev/next navigation across the row set. Save/delete delegate to async
+ * callbacks. Pure logic.
+ */
+
+interface FormEditorEngineOptions {
+    /** The rows the editor navigates over (current visible order). */
+    rows: GridRow[];
+    /** Field used as the unique row ID. Default: 'id' */
+    rowIdField?: string;
+    onSave?: (row: GridRow) => void | Promise<void>;
+    onDelete?: (row: GridRow) => void | Promise<void>;
+}
+declare class FormEditorEngine {
+    private _rows;
+    private readonly _rowIdField;
+    private readonly _onSave?;
+    private readonly _onDelete?;
+    private _index;
+    private _draft;
+    private _onChange?;
+    constructor(options: FormEditorEngineOptions);
+    subscribe(listener: () => void): () => void;
+    /** Replace the row set; keeps the panel on the same rowId if still present. */
+    setRows(rows: GridRow[]): void;
+    get isOpen(): boolean;
+    get index(): number;
+    /** Open the panel on a row by its ID. */
+    openById(rowId: string | number): void;
+    /** Open the panel on a row by index. */
+    openAt(index: number): void;
+    close(): void;
+    private _openAt;
+    /** The current editable draft (a copy of the row plus unsaved edits). */
+    getDraft(): GridRow | null;
+    /** The original (unedited) row currently open. */
+    getOriginal(): GridRow | null;
+    setFieldValue(field: string, value: unknown): void;
+    /** True when the draft differs from the original row. */
+    get isDirty(): boolean;
+    /** Revert unsaved edits. */
+    revert(): void;
+    get canGoPrev(): boolean;
+    get canGoNext(): boolean;
+    next(): void;
+    prev(): void;
+    /** Save the draft: commits it into the row set and calls onSave. */
+    save(): Promise<void>;
+    /** Delete the open row: removes it and keeps the panel on the next row. */
+    delete(): Promise<void>;
+    private _rowId;
+    private _notify;
+}
+
+/**
+ * Grid integration bridges — connect the framework-agnostic Pro engines to the
+ * open-source `<gd-data-grid>`'s `ColDef` contract, without any DOM coupling.
+ * Consumers feed the transformed column defs straight into `[columnDefs]`.
+ */
+
+/**
+ * Return a copy of `columnDefs` whose cells honour a `CellPermissionEngine`:
+ * unreadable cells resolve to the engine's mask value (so they never reach
+ * renderers, sorting, filtering, or export), and non-editable cells become
+ * non-editable regardless of the column's own `editable`. Columns without a
+ * `field` (e.g. a checkbox-selection column) pass through unchanged.
+ */
+declare function applyCellPermissions<TData>(columnDefs: ColDef<TData>[], engine: CellPermissionEngine): ColDef<TData>[];
+/**
+ * Convert open-source grid column defs into `PdfColumn`s for `PDFExportEngine`,
+ * carrying each column's `headerName` and `valueFormatter`. Hidden columns and
+ * columns without a `field` are omitted.
+ */
+declare function toPdfColumns<TData>(columnDefs: ColDef<TData>[]): PdfColumn[];
+
+export { AuditTrailEngine, CellPermissionEngine, ClipboardEngine, DEFAULT_MASK, DataGridPro, ExcelImportEngine, FillHandleEngine, FilterPresetEngine, FormEditorEngine, FormulaEngine, GridLicenseWatermark, LicenseManager, MasterDetailEngine, PDFExportEngine, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, RowLockEngine, SSRMEngine, SavedViewsEngine, TransactionEngine, UndoRedoManager, applyCellPermissions, deserializeFilter, evaluateFilter, parseCSV, parseTSV, provideGridEngineLicense, serializeFilter, toNumber, toPdfColumns, toTimestamp };
+export type { AuditEntry, AuditTrailEngineOptions, Block, BlockState, CellEditCommand, CellPermission, CellPermissionEngineOptions, CellRange, ClipboardEngineOptions, DeleteCommand, DetailEntry, DetailLoadState, ExcelImportEngineOptions, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, FilterCondition, FilterGroup, FilterNode, FilterOperator, FilterPreset, FilterPresetEngineOptions, FormEditorEngineOptions, FormulaEngineOptions, GridRow, ImportColumn, ImportColumnType, ImportPreview, ImportValidationError, LockedRow, MasterDetailEngineOptions, PDFExportEngineOptions, PasteCommand, PdfColumn, PdfDocumentModel, PdfExportOptions, PdfPage, PdfPageFooter, PdfPageHeader, RangeSelectionEngineOptions, RowLockEngineOptions, SSRMDataSource, SSRMEngineOptions, SSRMGetRowsParams, SSRMGetRowsResult, SavedView, SavedViewsEngineOptions, TransactionDelta, TransactionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };