@gridengine/angular-datagrid-enterprise 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gridengine/angular-datagrid-enterprise",
-  "version": "0.5.0",
+  "version": "0.7.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

@@ -648,5 +648,327 @@ declare class RowLockEngine {
     private _notify;
 }
 
-export { AuditTrailEngine, CellPermissionEngine, ClipboardEngine, DEFAULT_MASK, DataGridPro, FillHandleEngine, FormulaEngine, GridLicenseWatermark, LicenseManager, MasterDetailEngine, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, RowLockEngine, SSRMEngine, TransactionEngine, UndoRedoManager, parseTSV, provideGridEngineLicense, toNumber, toTimestamp };
-export type { AuditEntry, AuditTrailEngineOptions, Block, BlockState, CellEditCommand, CellPermission, CellPermissionEngineOptions, CellRange, ClipboardEngineOptions, DeleteCommand, DetailEntry, DetailLoadState, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, FormulaEngineOptions, GridRow, LockedRow, MasterDetailEngineOptions, PasteCommand, RangeSelectionEngineOptions, RowLockEngineOptions, SSRMDataSource, SSRMEngineOptions, SSRMGetRowsParams, SSRMGetRowsResult, TransactionDelta, TransactionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };
+/**
+ * Advanced filter builder — a nestable AND/OR/NOT tree of conditions with a
+ * pure evaluator, URL-safe serialize/deserialize for shareable filter links,
+ * and a named-preset store. No React, no DOM.
+ */
+
+type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'isEmpty' | 'isNotEmpty';
+/** A single leaf filter condition. */
+interface FilterCondition {
+    kind: 'condition';
+    field: string;
+    operator: FilterOperator;
+    value?: unknown;
+}
+/** A nestable group of conditions/groups combined with AND or OR. */
+interface FilterGroup {
+    kind: 'group';
+    combinator: 'and' | 'or';
+    /** Negates the entire group's result. */
+    not?: boolean;
+    children: FilterNode[];
+}
+type FilterNode = FilterCondition | FilterGroup;
+/** A named, persistable filter preset. */
+interface FilterPreset {
+    id: string;
+    name: string;
+    filter: FilterNode;
+    isShared?: boolean;
+}
+interface FilterPresetEngineOptions {
+    /** Presets to seed the store with. */
+    presets?: FilterPreset[];
+    /** Called when a preset is saved. */
+    onSave?: (preset: FilterPreset) => void | Promise<void>;
+    /** ID generator (injectable for tests). */
+    generateId?: () => string;
+}
+/** Evaluate a filter node against a row. */
+declare function evaluateFilter(node: FilterNode, row: GridRow): boolean;
+/** Serialize a filter tree to a URL-safe string. */
+declare function serializeFilter(node: FilterNode): string;
+/** Deserialize a URL-safe string back into a filter tree. Throws if invalid. */
+declare function deserializeFilter(encoded: string): FilterNode;
+declare class FilterPresetEngine {
+    private readonly _onSave?;
+    private readonly _generateId;
+    private _presets;
+    private _seq;
+    private _onChange?;
+    constructor(options?: FilterPresetEngineOptions);
+    subscribe(listener: () => void): () => void;
+    getPresets(): readonly FilterPreset[];
+    getPreset(id: string): FilterPreset | undefined;
+    /** Save a new preset (or replace one with the same name). Returns it. */
+    savePreset(name: string, filter: FilterNode, isShared?: boolean): FilterPreset;
+    deletePreset(id: string): void;
+    /** Filter an array of rows through a filter tree. */
+    applyFilter(node: FilterNode, rows: GridRow[]): GridRow[];
+    private _notify;
+}
+
+/**
+ * SavedViewsEngine — manages named grid views (column layout, sort, filter,
+ * group, density, etc.) across personal + admin-shared tiers. Server sync is
+ * delegated to async callbacks so the engine stays pure and Node-testable.
+ */
+interface SavedView {
+    id: string;
+    name: string;
+    isShared?: boolean;
+    layout: Record<string, unknown>;
+}
+interface SavedViewsEngineOptions {
+    /** Async loader for the user's saved views. */
+    getSavedViews?: () => Promise<SavedView[]>;
+    /** Persist a saved view. */
+    onSaveView?: (view: SavedView) => Promise<void> | void;
+    /** Delete a saved view. */
+    onDeleteView?: (viewId: string) => Promise<void> | void;
+    /** Notified when the active view changes. */
+    onViewChange?: (view: SavedView | null) => void;
+    /** Seed views (used when no async loader is supplied). */
+    views?: SavedView[];
+    /** ID generator (injectable for tests). */
+    generateId?: () => string;
+}
+declare class SavedViewsEngine {
+    private readonly _getSavedViews?;
+    private readonly _onSaveView?;
+    private readonly _onDeleteView?;
+    private readonly _onViewChange?;
+    private readonly _generateId;
+    private _views;
+    private _activeViewId;
+    private _seq;
+    private _onChange?;
+    constructor(options?: SavedViewsEngineOptions);
+    subscribe(listener: () => void): () => void;
+    /** Load views from the async source, replacing local state. */
+    load(): Promise<void>;
+    getViews(): readonly SavedView[];
+    getView(id: string): SavedView | undefined;
+    /** Personal (non-shared) views. */
+    getPersonalViews(): SavedView[];
+    /** Admin-shared views. */
+    getSharedViews(): SavedView[];
+    getActiveView(): SavedView | null;
+    /** Create a new view or update an existing one by name. Returns the view. */
+    saveView(name: string, layout: Record<string, unknown>, options?: {
+        isShared?: boolean;
+        id?: string;
+    }): Promise<SavedView>;
+    /** Delete a view. If it was active, the active view is cleared. */
+    deleteView(id: string): Promise<void>;
+    /** Activate a view (or clear with null). Fires onViewChange. */
+    setActiveView(id: string | null): void;
+    private _notify;
+}
+
+/**
+ * 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;
+}
+
+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, deserializeFilter, evaluateFilter, parseCSV, parseTSV, provideGridEngineLicense, serializeFilter, toNumber, 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 };