@gridengine/angular-datagrid-enterprise 0.4.0 → 0.6.0

package/package.json

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

@@ -498,5 +498,275 @@ declare class MasterDetailEngine {
     private _notify;
 }
 
-export { ClipboardEngine, DataGridPro, FillHandleEngine, FormulaEngine, GridLicenseWatermark, LicenseManager, MasterDetailEngine, PRODUCT_ID, PURCHASE_URL, RangeSelectionEngine, SSRMEngine, TransactionEngine, UndoRedoManager, parseTSV, provideGridEngineLicense, toNumber, toTimestamp };
-export type { Block, BlockState, CellEditCommand, CellRange, ClipboardEngineOptions, DeleteCommand, DetailEntry, DetailLoadState, FillCell, FillCommand, FillDirection, FillHandleEngineOptions, FillResult, FormulaEngineOptions, GridRow, MasterDetailEngineOptions, PasteCommand, RangeSelectionEngineOptions, SSRMDataSource, SSRMEngineOptions, SSRMGetRowsParams, SSRMGetRowsResult, TransactionDelta, TransactionEngineOptions, UndoRedoCommand, UndoRedoManagerOptions };
+/**
+ * CellPermissionEngine — enforces per-cell read/edit permissions from a
+ * caller-supplied policy. Unreadable cells are masked ('●●●') everywhere
+ * (display, export, clipboard); non-editable cells can't be edited regardless
+ * of the column's `editable`. Results are cached per (rowId, field). Pure logic.
+ */
+
+interface CellPermission {
+    canRead: boolean;
+    canEdit: boolean;
+}
+/** Default mask string used for unreadable cells. */
+declare const DEFAULT_MASK = "\u25CF\u25CF\u25CF";
+interface CellPermissionEngineOptions {
+    /** Policy returning permissions for a cell; called once per (rowId, field). */
+    policy: (row: GridRow, field: string) => CellPermission;
+    /** Field used as the unique row ID. Default: 'id' */
+    rowIdField?: string;
+    /** String shown in place of unreadable cell values. Default: '●●●' */
+    maskValue?: string;
+}
+declare class CellPermissionEngine {
+    private readonly _policy;
+    private readonly _rowIdField;
+    private readonly _maskValue;
+    private readonly _cache;
+    constructor(options: CellPermissionEngineOptions);
+    /** The resolved permission for a cell (cached). */
+    getPermission(row: GridRow, field: string): CellPermission;
+    canRead(row: GridRow, field: string): boolean;
+    canEdit(row: GridRow, field: string): boolean;
+    /** The display value for a cell, masked when not readable. */
+    getDisplayValue(row: GridRow, field: string): unknown;
+    /** The value for copy/export; unreadable cells return '' so data never leaks. */
+    getExportValue(row: GridRow, field: string): unknown;
+    /** True if the given value is the mask placeholder. */
+    isMasked(value: unknown): boolean;
+    get maskValue(): string;
+    /** Clear one row's cached permissions, or the whole cache when omitted. */
+    clearCache(rowId?: string | number): void;
+    private _key;
+}
+
+/**
+ * AuditTrailEngine — records an immutable log of every cell edit (who/what/when
+ * + prev/next values) in a bounded in-memory ring buffer, emitting each entry
+ * via `onEntry` for persistence. Pure logic.
+ */
+interface AuditEntry {
+    timestamp: number;
+    userId: string | undefined;
+    rowId: string | number;
+    field: string;
+    prevValue: unknown;
+    nextValue: unknown;
+}
+interface AuditTrailEngineOptions {
+    /** User identifier stamped on every entry. */
+    userId?: string;
+    /** Called for every new entry — persist to a server here. */
+    onEntry?: (entry: AuditEntry) => void;
+    /** Maximum entries retained in memory (oldest evicted first). Default: 1000 */
+    maxEntries?: number;
+    /** Injectable clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}
+declare class AuditTrailEngine {
+    private readonly _userId?;
+    private readonly _onEntry?;
+    private readonly _maxEntries;
+    private readonly _now;
+    private _entries;
+    private _onChange?;
+    constructor(options?: AuditTrailEngineOptions);
+    subscribe(listener: () => void): () => void;
+    /** Record a cell edit; no-op edits (prev === next) return null. */
+    record(rowId: string | number, field: string, prevValue: unknown, nextValue: unknown): AuditEntry | null;
+    /** All entries, oldest first (read-only snapshot). */
+    getEntries(): readonly AuditEntry[];
+    /** Entries for a specific row, oldest first. */
+    getEntriesForRow(rowId: string | number): AuditEntry[];
+    /** Entries for a specific cell (row + field), oldest first. */
+    getEntriesForCell(rowId: string | number, field: string): AuditEntry[];
+    get size(): number;
+    /** Discard all entries. */
+    clear(): void;
+    private _notify;
+}
+
+/**
+ * RowLockEngine — tracks which rows are locked (by other users) so the grid can
+ * show a lock indicator and block edits. Supports an async source of locks
+ * (e.g. polled from a collaboration server) plus optimistic local lock/unlock.
+ * Pure logic.
+ */
+
+interface LockedRow {
+    rowId: string | number;
+    lockedByUserId: string;
+    lockedByDisplayName?: string;
+    lockedAt: number;
+}
+interface RowLockEngineOptions {
+    /** The current user's ID. Locks held by this user do not block editing. */
+    currentUserId?: string;
+    /** Async source of currently locked rows (server state). */
+    getLockedRows?: () => Promise<LockedRow[]>;
+    /** Called when the current user attempts to edit a row locked by someone else. */
+    onLockConflict?: (row: GridRow, lockedBy: string) => void;
+    /** Field used as the unique row ID. Default: 'id' */
+    rowIdField?: string;
+    /** Injectable clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}
+declare class RowLockEngine {
+    private readonly _currentUserId?;
+    private readonly _getLockedRows?;
+    private readonly _onLockConflict?;
+    private readonly _rowIdField;
+    private readonly _now;
+    private _locks;
+    private _onChange?;
+    constructor(options?: RowLockEngineOptions);
+    subscribe(listener: () => void): () => void;
+    /** Load locks from the async source and replace local state. */
+    refresh(): Promise<void>;
+    /** Optimistically lock a row for a user. */
+    lockRow(rowId: string | number, userId: string, displayName?: string): void;
+    /** Remove a lock. */
+    unlockRow(rowId: string | number): void;
+    /** Remove all locks. */
+    clear(): void;
+    /** The lock for a row, or undefined if unlocked. */
+    getLock(rowId: string | number): LockedRow | undefined;
+    /** True if the row is locked by anyone. */
+    isLocked(rowId: string | number): boolean;
+    /** True if the row is locked by someone OTHER than the current user. */
+    isLockedByOther(rowId: string | number): boolean;
+    /** All current locks. */
+    getLocks(): LockedRow[];
+    get size(): number;
+    /**
+     * Whether the row may be edited by the current user. If it's locked by
+     * another user, fires `onLockConflict` and returns false.
+     */
+    canEditRow(row: GridRow): boolean;
+    private _rowId;
+    private _notify;
+}
+
+/**
+ * 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;
+}
+
+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 };