@orangelogic/design-system 2.130.0 → 2.132.0

package/library/packages/hybrid/table-core/src/tabulator-tables/modules/Validate/Validate.d.ts

@@ -1,36 +1,104 @@
+import { CellValidationFailure, ICellComponent, StandardValidatorType, ValidationSummary, Validator } from '../../../../../../types/src/table';
 import { default as Cell } from '../../core/cell/Cell';
 import { default as Column } from '../../core/column/Column';
 import { default as Module } from '../../core/Module';
 import { default as Row } from '../../core/row/Row';
 import { default as Tabulator } from '../../core/Tabulator';
 
-type ValidatorFunction = (cell: any, value: any, parameters: any) => boolean;
+/**
+ * Attribute carrying the joined failure messages of an invalid cell.
+ * Consumers (e.g. cx-table) read it to display a tooltip — a data attribute
+ * instead of `title` so the native browser tooltip does not compete with it.
+ */
+export declare const VALIDATION_MESSAGE_ATTRIBUTE = "data-validation-message";
+type ValidatorFunction = (cell: ICellComponent, value: unknown, parameters?: unknown) => boolean;
 type ValidatorConfig = {
     func: ValidatorFunction;
-    params: any;
+    message?: string;
+    params: unknown;
     type: string;
 };
 export default class Validate extends Module {
     static readonly moduleName = "validate";
     static readonly validators: Record<string, ValidatorFunction>;
-    invalidCells: Cell[];
+    /**
+     * Validation results keyed by row → column. Virtual renderers delete and
+     * recreate Cell objects as rows scroll in and out of the render window,
+     * while Row and Column objects persist — so keying by row/column keeps
+     * invalid state (and counts) stable across scrolling. Cells without a
+     * row/column (detached mocks) key by the cell itself.
+     */
+    private readonly invalidState;
+    get invalidCells(): Cell[];
+    set invalidCells(cells: Cell[]);
+    /**
+     * Bumped whenever data is replaced or a new table-wide validation starts, so
+     * results of superseded async validations are discarded instead of applied.
+     */
+    private validationGeneration;
+    /** Batch operations set this to emit one validationChanged instead of one per cell. */
+    private suppressValidationChanged;
     constructor(table: Tabulator);
     initialize(): void;
-    editValidate(cell: Cell, value: any, _previousValue: any): boolean | any;
+    editValidate(cell: Cell, value: unknown, _previousValue: unknown): boolean | CellValidationFailure[];
     editorClear(cell: Cell, cancelled: boolean): void;
     editedClear(cell: Cell): void;
+    /**
+     * A deleted cell must NOT drop its validation state: virtual renderers
+     * delete and recreate Cell objects as rows scroll in and out of the render
+     * window, and the row-keyed record is restored by layoutCell when the cell
+     * is rebuilt. True removals are handled by rowDeleted/columnDeleted.
+     */
+    cellDeleted(cell: Cell): void;
+    rowDeleted(row: Row): void;
+    columnDeleted(column: Column): void;
+    /**
+     * Cells are recycled by the virtual renderers, so persisted validation state
+     * must be restored onto the freshly built cell whenever its DOM is (re)built.
+     */
+    layoutCell(cell: Cell): void;
+    dataProcessed(): void;
     cellIsValid(cell: Cell): boolean;
-    cellValidate(cell: Cell): boolean | any;
-    columnValidate(column: Column): any[] | boolean;
-    rowValidate(row: Row): any[] | boolean;
-    userClearCellValidation(cells?: any): void;
-    userValidate(_cells?: any): any[] | boolean;
+    cellValidate(cell: Cell): CellValidationFailure[] | boolean;
+    columnValidate(column: Column): ICellComponent[] | boolean;
+    rowValidate(row: Row): ICellComponent[] | boolean;
+    userClearCellValidation(cells?: ICellComponent | ICellComponent[]): void;
+    userValidate(_cells?: unknown): ICellComponent[] | boolean;
+    /**
+     * Validates the whole dataset without blocking the main thread on large
+     * tables: below `validationWorkerThreshold` rows it runs synchronously,
+     * above it JSON rules are offloaded to a shared Web Worker (columns with
+     * function validators stay on the main thread, processed in yielding
+     * chunks). Superseded runs (new validation or data reload) are discarded.
+     */
+    validateAsync(): Promise<ValidationSummary>;
+    getValidationSummary(): ValidationSummary;
     initializeColumnCheck(column: Column): void;
     initializeColumn(column: Column): void;
-    _extractValidator(value: any): ValidatorConfig | false;
-    _buildValidator(type: string | ValidatorFunction, params?: any): ValidatorConfig | false;
-    validate(validators: ValidatorConfig[] | false | undefined, cell: Cell, value: any): any[] | boolean;
-    getInvalidCells(): any[];
+    _extractValidator(value: StandardValidatorType | Validator | ValidatorFunction | string): ValidatorConfig | false;
+    _buildValidator(type: string | ValidatorFunction, params?: unknown, message?: string): ValidatorConfig | false;
+    validate(validators: ValidatorConfig[] | false | undefined, cell: Cell, value: unknown): CellValidationFailure[] | boolean;
+    getInvalidCells(): ICellComponent[];
     clearValidation(cell: Cell): void;
+    private rowKeyOf;
+    private columnKeyOf;
+    private getInvalidRecord;
+    private registerInvalidCell;
+    private unregisterInvalidCell;
+    private countInvalidCells;
+    private getValidatedColumns;
+    private validateColumnsOnWorker;
+    private applyWorkerResults;
+    private applyBatchFailures;
+    /**
+     * Columns with function validators cannot run in the worker; validate them
+     * on the main thread in chunks, yielding between chunks to keep the UI
+     * responsive.
+     */
+    private validateColumnsOnMainThread;
+    private applyCellInvalidState;
+    private clearCellInvalidState;
+    private runSuppressed;
+    private dispatchValidationChanged;
 }
 export {};

package/library/packages/hybrid/table-core/src/tabulator-tables/modules/Validate/defaults/rule-functions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure validation rule functions shared by the main-thread Validate module and
+ * the validation Web Worker.
+ *
+ * Every function is side-effect free and depends only on its arguments — no
+ * cell, DOM, or table access — so the same code can run inside a worker where
+ * only JSON-serializable data is available. Cell/table-dependent inputs (e.g.
+ * the column values needed by `unique`) are passed in through `RuleContext`.
+ *
+ * Semantics preserved from the original validators: an empty value
+ * (`''`, `null`, `undefined`) passes every rule except `required`.
+ */
+/** Extra inputs a rule may need that are not part of the cell value itself. */
+export interface RuleContext {
+    /** All values of the cell's column (used by `unique`), excluding the cell's own row. */
+    columnValues?: unknown[];
+}
+export type RuleFunction = (value: unknown, parameters?: any, context?: RuleContext) => boolean;
+declare const ruleFunctions: Record<string, RuleFunction>;
+export default ruleFunctions;

package/library/packages/hybrid/table-core/src/tabulator-tables/modules/Validate/defaults/validators.d.ts

@@ -1,18 +1,9 @@
-declare const _default: {
-    alphanumeric: (_cell: any, value: any, _parameters: any) => boolean;
-    ends: (_cell: any, value: any, parameters: any) => boolean;
-    float: (_cell: any, value: any, _parameters: any) => boolean;
-    in: (_cell: any, value: any, parameters: any) => boolean;
-    integer: (_cell: any, value: any, _parameters: any) => boolean;
-    max: (_cell: any, value: any, parameters: any) => boolean;
-    maxLength: (_cell: any, value: any, parameters: any) => boolean;
-    min: (_cell: any, value: any, parameters: any) => boolean;
-    minLength: (_cell: any, value: any, parameters: any) => boolean;
-    numeric: (_cell: any, value: any, _parameters: any) => boolean;
-    regex: (_cell: any, value: any, parameters: any) => boolean;
-    required: (_cell: any, value: any, _parameters: any) => boolean;
-    starts: (_cell: any, value: any, parameters: any) => boolean;
-    string: (_cell: any, value: any, _parameters: any) => boolean;
-    unique: (this: any, cell: any, value: any, _parameters: any) => boolean;
-};
-export default _default;
+import { ICellComponent } from '../../../../../../../types/src/table';
+
+/**
+ * Cell-facing validator signature expected by the Validate module and custom
+ * consumer validators. Mirrors `ValidatorFunction` in `Validate.ts`.
+ */
+export type CellValidator = (cell: ICellComponent, value: unknown, parameters?: unknown) => boolean;
+declare const validators: Record<string, CellValidator>;
+export default validators;

package/library/packages/hybrid/table-core/src/tabulator-tables/modules/Validate/validation-worker-client.d.ts

@@ -0,0 +1,13 @@
+import { ValidationWorkerFailureEntry, ValidationWorkerField } from './validation.worker';
+
+export type { ValidationWorkerFailureEntry, ValidationWorkerField };
+/**
+ * Validates pre-extracted column values against JSON rules on the shared
+ * validation worker.
+ *
+ * Resolves with every failure entry once the worker finishes; `onChunk` fires
+ * per processed row chunk for progressive application. Rejects if the worker
+ * crashes or cannot start — callers should fall back to synchronous
+ * validation.
+ */
+export declare function validateBatch(fields: ValidationWorkerField[], onChunk?: (results: ValidationWorkerFailureEntry[]) => void): Promise<ValidationWorkerFailureEntry[]>;

package/library/packages/types/src/table.d.ts

@@ -928,6 +928,11 @@ export interface ITabulatorFull extends ITabulator {
     createFilterFieldFunction: IFilter['createFilterFieldFunction'];
     clearFilter: IFilter['clearFilter'];
     setSort: (sortList: string | Sorter[], dir?: SortDirection) => void;
+    validate: () => true | ICellComponent[];
+    validateAsync: () => Promise<ValidationSummary>;
+    getValidationSummary: () => ValidationSummary;
+    getInvalidCells: () => ICellComponent[];
+    clearCellValidation: (cells?: ICellComponent | ICellComponent[]) => void;
 }
 /**
  * Table type
@@ -1769,6 +1774,19 @@ export interface OptionsGeneral {
      * manual - no validation is automatically performed on edit, but it can be triggered by calling the validate function on the table or any Component Object
      */
     validationMode?: 'blocking' | 'highlight' | 'manual';
+    /**
+     * When true, the whole dataset is validated automatically each time data is
+     * loaded or replaced (`data-processed`). Defaults to false for backward
+     * compatibility.
+     */
+    validateOnLoad?: boolean;
+    /**
+     * Row-count threshold above which table-wide validation passes
+     * (`validateAsync` / `validateOnLoad`) are offloaded to a Web Worker instead
+     * of running synchronously on the main thread. Set to `false` to always
+     * validate synchronously. Defaults to 2000.
+     */
+    validationWorkerThreshold?: number | false;
     textDirection?: TextDirection;
     /**
      * Sometimes it can be useful to add a visual header to the start of a row.
@@ -2607,10 +2625,45 @@ export type JSONRecord = Record<string, string | number | boolean>;
  *     {title:"Example", field:"example", validator:"regex:\\.com$"} \\allow strings that end in '.com'
  * ```
  */
-export type StandardValidatorType = 'required' | 'unique' | 'integer' | 'float' | 'numeric' | 'string' | 'alphanumeric';
+export type StandardValidatorType = 'required' | 'unique' | 'integer' | 'float' | 'numeric' | 'string' | 'alphanumeric' | 'boolean' | 'date' | 'in' | 'regex';
+/** Range constraints accepted by the numeric-type validators (`numeric`, `integer`, `float`). */
+export interface NumericValidatorParameters {
+    min?: number;
+    max?: number;
+}
+/** Length constraints accepted by the `string` validator. */
+export interface StringValidatorParameters {
+    minLength?: number;
+    maxLength?: number;
+}
+/**
+ * Range constraints accepted by the `date` validator. `starts` / `ends` are
+ * inclusive bounds as ISO date strings (or anything `Date.parse` understands).
+ */
+export interface DateValidatorParameters {
+    starts?: string;
+    ends?: string;
+}
 export interface Validator {
     type: StandardValidatorType | ((cell: ICellComponent, value: any, parameters?: any) => boolean);
     parameters?: any;
+    /**
+     * Optional human-readable error message attached to validation failures for
+     * this rule. Propagated to cell validation state, the cell `title` tooltip,
+     * and validation events. JSON-serializable.
+     */
+    message?: string;
+}
+/** A single failed validation rule on a cell. */
+export interface CellValidationFailure {
+    type: string;
+    parameters?: any;
+    message?: string;
+}
+/** Aggregate result of a table-wide validation pass. */
+export interface ValidationSummary {
+    invalidCellCount: number;
+    invalidCells: ICellComponent[];
 }
 export type ColumnSorterParamLookupFunction = (column: IColumnComponent, dir: SortDirection) => Record<string, unknown>;
 export type ColumnLookup = IColumn | IColumnComponent | ColumnDefinition | HTMLElement | string;
@@ -2815,6 +2868,7 @@ export interface RangeComponent {
 }
 export interface EventCallBackMethods {
     validationFailed: (cell: ICellComponent, value: any, validators: Validator[]) => void;
+    validationChanged: (summary: ValidationSummary) => void;
     scrollHorizontal: (left: number, leftDir: boolean) => void;
     scrollVertical: (top: number, topDir: boolean) => void;
     rowAdded: (row: IRowComponent) => void;