@researchdatabox/sails-ng-common 0.2.1 → 5.0.0-RC2

package/dist/src/status.model.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormStatus = exports.FormFieldComponentStatus = void 0;
+/**
+ * The status of a component.
+ */
+var FormFieldComponentStatus;
+(function (FormFieldComponentStatus) {
+    FormFieldComponentStatus["INIT"] = "INIT";
+    FormFieldComponentStatus["INIT_VIEW_READY"] = "INIT_VIEW_READY";
+    FormFieldComponentStatus["READY"] = "READY";
+    FormFieldComponentStatus["BUSY"] = "BUSY";
+    FormFieldComponentStatus["ERROR"] = "ERROR";
+})(FormFieldComponentStatus || (exports.FormFieldComponentStatus = FormFieldComponentStatus = {}));
+/**
+ * The status of a form.
+ */
+var FormStatus;
+(function (FormStatus) {
+    FormStatus["INIT"] = "INIT";
+    FormStatus["READY"] = "READY";
+    FormStatus["SAVING"] = "SAVING";
+    FormStatus["DELETING"] = "DELETING";
+    FormStatus["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    FormStatus["LOAD_ERROR"] = "LOAD_ERROR";
+    FormStatus["VALIDATION_PENDING"] = "VALIDATION_PENDING";
+})(FormStatus || (exports.FormStatus = FormStatus = {}));
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RhdHVzLm1vZGVsLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3N0YXR1cy5tb2RlbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQTs7R0FFRztBQUNILElBQVksd0JBTVg7QUFORCxXQUFZLHdCQUF3QjtJQUNsQyx5Q0FBYSxDQUFBO0lBQ2IsK0RBQW1DLENBQUE7SUFDbkMsMkNBQWUsQ0FBQTtJQUNmLHlDQUFhLENBQUE7SUFDYiwyQ0FBZSxDQUFBO0FBQ2pCLENBQUMsRUFOVyx3QkFBd0Isd0NBQXhCLHdCQUF3QixRQU1uQztBQUNEOztHQUVHO0FBQ0gsSUFBWSxVQVFYO0FBUkQsV0FBWSxVQUFVO0lBQ3BCLDJCQUFhLENBQUE7SUFDYiw2QkFBZSxDQUFBO0lBQ2YsK0JBQWlCLENBQUE7SUFDakIsbUNBQXFCLENBQUE7SUFDckIsbURBQXFDLENBQUE7SUFDckMsdUNBQXlCLENBQUE7SUFDekIsdURBQXlDLENBQUE7QUFDM0MsQ0FBQyxFQVJXLFVBQVUsMEJBQVYsVUFBVSxRQVFyQiJ9

package/dist/src/template.outline.d.ts

@@ -0,0 +1,82 @@
+import { LineagePath } from "./config/names/naming-helpers";
+export declare const templateCompileKind: readonly ["jsonata", "handlebars"];
+export type TemplateCompileKind = typeof templateCompileKind[number];
+export type TemplateCompileKey = LineagePath;
+export type TemplateCompileKeyFormatted = string;
+export type TemplateCompileValue = string;
+/**
+ * One compile mapping builder input or output.
+ */
+export interface TemplateCompileItem {
+    /**
+     * The key to access the compiled value in the output mapping.
+     *
+     * Must be unique across all inputs for one call to the compiled mapping builder.
+     */
+    key: TemplateCompileKey;
+    /**
+     * The value string in either the raw form or the compiled form.
+     */
+    value: TemplateCompileValue;
+}
+/**
+ * One input to the compile mapping builder.
+ */
+export interface TemplateCompileInput extends TemplateCompileItem {
+    /**
+     * The kind indicates the format of the value.
+     */
+    kind: TemplateCompileKind;
+}
+/**
+ * Build a string key that can be used on the server and client.
+ * @param key The array of names and indexes.
+ */
+export declare function buildKeyString(key: TemplateCompileKey): TemplateCompileKeyFormatted;
+/**
+ * The form config lineage path to use as the key for selecting the compiled template.
+ */
+export type DynamicScriptResponseEvaluateKey = TemplateCompileKey;
+/**
+ * Context to pass to the template evaluator.
+ */
+export type DynamicScriptResponseEvaluateContext = unknown;
+/**
+ * Provide the template library evaluator functions.
+ */
+export type DynamicScriptResponseEvaluateExtra = {
+    libraries?: {
+        jsonata?: Function;
+        handlebars?: Function;
+        [key: string]: unknown;
+    };
+};
+/**
+ * The result of evaluating the template.
+ */
+export type DynamicScriptResponseEvaluateResult = unknown;
+/**
+ * The evaluator function provided by the server to the client.
+ */
+export type DynamicScriptResponseEvaluate = (
+/**
+ * The form config lineage path to use as the key for selecting the compiled template.
+ */
+key: DynamicScriptResponseEvaluateKey, 
+/**
+ * Context to pass to the template evaluator.
+ */
+context: DynamicScriptResponseEvaluateContext, 
+/**
+ * Provide the template library evaluator functions.
+ */
+extra?: DynamicScriptResponseEvaluateExtra) => DynamicScriptResponseEvaluateResult;
+/**
+ * The type of the dynamic script asset response after import.
+ */
+export interface DynamicScriptResponse {
+    /**
+     * The evaluator function provided by the server to the client.
+     */
+    evaluate: DynamicScriptResponseEvaluate;
+}

package/dist/src/template.outline.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.templateCompileKind = void 0;
+exports.buildKeyString = buildKeyString;
+const naming_helpers_1 = require("./config/names/naming-helpers");
+exports.templateCompileKind = ["jsonata", "handlebars"];
+/**
+ * Build a string key that can be used on the server and client.
+ * @param key The array of names and indexes.
+ */
+function buildKeyString(key) {
+    return (key ?? [])?.map(i => (0, naming_helpers_1.normaliseVisual)(i))?.join('__');
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVtcGxhdGUub3V0bGluZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90ZW1wbGF0ZS5vdXRsaW5lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQXlDQSx3Q0FFQztBQTNDRCxrRUFBMkU7QUFFOUQsUUFBQSxtQkFBbUIsR0FBRyxDQUFDLFNBQVMsRUFBRSxZQUFZLENBQVUsQ0FBQztBQW1DdEU7OztHQUdHO0FBQ0gsU0FBZ0IsY0FBYyxDQUFDLEdBQXVCO0lBQ2xELE9BQU8sQ0FBQyxHQUFHLElBQUksRUFBRSxDQUFDLEVBQUUsR0FBRyxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsSUFBQSxnQ0FBZSxFQUFDLENBQUMsQ0FBQyxDQUFDLEVBQUUsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0FBQ2pFLENBQUMifQ==

package/dist/src/translation-helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Guess at whether the key is a natural language string.
+ * This is useful for translating only keys that are likely to be translation codes.
+ *
+ * TODO: The long-term goal is to have everything specify if it is natural langauge or translation code,
+ *       to remove the need for this method.
+ *
+ * @param key The string to guess as natual language or not.
+ * @return True if the key is likely natural language and not a translation key.
+ */
+export declare function isLikelyNaturalLanguage(key: string | null | undefined): boolean;
+/**
+ * Guess at the parts of a full name.
+ *
+ * TODO: This is best-effort only, and is likely to be incorrect.
+ *       The long-term goal is to not have to guess at names.
+ *       This is needed while some form fields prompt for full names and others need parts of names.
+ *
+ * @param value Guess at the parts of this full name.
+ * @return Object with guessed values for full, first, and last names.
+ */
+export declare function guessNameParts(value: string): {
+    full: string;
+    first: string;
+    last: string;
+};

package/dist/src/translation-helpers.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLikelyNaturalLanguage = isLikelyNaturalLanguage;
+exports.guessNameParts = guessNameParts;
+/**
+ * Guess at whether the key is a natural language string.
+ * This is useful for translating only keys that are likely to be translation codes.
+ *
+ * TODO: The long-term goal is to have everything specify if it is natural langauge or translation code,
+ *       to remove the need for this method.
+ *
+ * @param key The string to guess as natual language or not.
+ * @return True if the key is likely natural language and not a translation key.
+ */
+function isLikelyNaturalLanguage(key) {
+    const value = String(key ?? "").trim();
+    const containsSpace = value.includes(' ');
+    const startsCapitalLetter = value.length > 0 ? value[0].toLowerCase() !== value[0] : false;
+    // An empty string is not natural language.
+    // Treat default conversion of object to string as not natural language.
+    // Likely a translation code if contains '{{' or '}}'.
+    // Likely a translation code if starts with '@' and no spaces and does not start with a capital letter.
+    // Likely a translation code if contains '_' and no spaces and does not start with a capital letter.
+    if (!value ||
+        value.includes('[object Object]') ||
+        value.includes('{{') || value.includes('}}') ||
+        (value.startsWith('@') && !containsSpace && !startsCapitalLetter) ||
+        (value.includes('_') && !containsSpace && !startsCapitalLetter)) {
+        return false;
+    }
+    // Likely natural language if contains a space or starts with a capital letter.
+    if (containsSpace || startsCapitalLetter) {
+        return true;
+    }
+    // Likely a translation code if contains any of ':', '{', '}'.
+    if (value.includes(':') ||
+        value.includes('{') ||
+        value.includes('}')) {
+        return false;
+    }
+    // Otherwise, be conservative and say the translation key is not natural language.
+    return false;
+}
+/**
+ * Guess at the parts of a full name.
+ *
+ * TODO: This is best-effort only, and is likely to be incorrect.
+ *       The long-term goal is to not have to guess at names.
+ *       This is needed while some form fields prompt for full names and others need parts of names.
+ *
+ * @param value Guess at the parts of this full name.
+ * @return Object with guessed values for full, first, and last names.
+ */
+function guessNameParts(value) {
+    let full = String(value ?? "").replace(/\s+/g, ' ').trim(), first = '', last = '';
+    if (!full) {
+        return { full, first, last };
+    }
+    // If there are no spaces, assume this is the last name.
+    if (!full.includes(' ')) {
+        last = full;
+        return { full, first, last };
+    }
+    // If there are spaces, assume the first 'word' is the first name, and the rest is the last name.
+    const words = full.split(' ').filter(w => !!w?.trim());
+    full = words.join(' ');
+    first = words[0];
+    last = words.slice(1).join(' ');
+    return { full, first, last };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhbnNsYXRpb24taGVscGVycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90cmFuc2xhdGlvbi1oZWxwZXJzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBVUEsMERBcUNDO0FBWUQsd0NBcUJDO0FBaEZEOzs7Ozs7Ozs7R0FTRztBQUNILFNBQWdCLHVCQUF1QixDQUFDLEdBQThCO0lBQ3BFLE1BQU0sS0FBSyxHQUFHLE1BQU0sQ0FBQyxHQUFHLElBQUksRUFBRSxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUM7SUFFdkMsTUFBTSxhQUFhLEdBQUcsS0FBSyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUMxQyxNQUFNLG1CQUFtQixHQUFHLEtBQUssQ0FBQyxNQUFNLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsV0FBVyxFQUFFLEtBQUssS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUM7SUFFM0YsMkNBQTJDO0lBQzNDLHdFQUF3RTtJQUN4RSxzREFBc0Q7SUFDdEQsdUdBQXVHO0lBQ3ZHLG9HQUFvRztJQUNwRyxJQUNFLENBQUMsS0FBSztRQUNOLEtBQUssQ0FBQyxRQUFRLENBQUMsaUJBQWlCLENBQUM7UUFDakMsS0FBSyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsSUFBSSxLQUFLLENBQUMsUUFBUSxDQUFDLElBQUksQ0FBQztRQUM1QyxDQUFDLEtBQUssQ0FBQyxVQUFVLENBQUMsR0FBRyxDQUFDLElBQUksQ0FBQyxhQUFhLElBQUksQ0FBQyxtQkFBbUIsQ0FBQztRQUNqRSxDQUFDLEtBQUssQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLElBQUksQ0FBQyxhQUFhLElBQUksQ0FBQyxtQkFBbUIsQ0FBQyxFQUMvRCxDQUFDO1FBQ0QsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBRUQsK0VBQStFO0lBQy9FLElBQUksYUFBYSxJQUFJLG1CQUFtQixFQUFFLENBQUM7UUFDekMsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0lBRUQsOERBQThEO0lBQzlELElBQ0UsS0FBSyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUM7UUFDbkIsS0FBSyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUM7UUFDbkIsS0FBSyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsRUFDbkIsQ0FBQztRQUNELE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUVELGtGQUFrRjtJQUNsRixPQUFPLEtBQUssQ0FBQztBQUNmLENBQUM7QUFFRDs7Ozs7Ozs7O0dBU0c7QUFDSCxTQUFnQixjQUFjLENBQUMsS0FBYTtJQUMxQyxJQUFJLElBQUksR0FBRyxNQUFNLENBQUMsS0FBSyxJQUFJLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxNQUFNLEVBQUUsR0FBRyxDQUFDLENBQUMsSUFBSSxFQUFFLEVBQ3hELEtBQUssR0FBRyxFQUFFLEVBQ1YsSUFBSSxHQUFFLEVBQUUsQ0FBQztJQUVYLElBQUksQ0FBQyxJQUFJLEVBQUUsQ0FBQztRQUNWLE9BQU8sRUFBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLElBQUksRUFBQyxDQUFDO0lBQzdCLENBQUM7SUFFRCx3REFBd0Q7SUFDeEQsSUFBSSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLEVBQUMsQ0FBQztRQUN2QixJQUFJLEdBQUcsSUFBSSxDQUFDO1FBQ1osT0FBTyxFQUFDLElBQUksRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFDLENBQUM7SUFDN0IsQ0FBQztJQUVELGlHQUFpRztJQUNqRyxNQUFNLEtBQUssR0FBRyxJQUFJLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxDQUFDLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQztJQUN2RCxJQUFJLEdBQUcsS0FBSyxDQUFDLElBQUksQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUN2QixLQUFLLEdBQUcsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ2pCLElBQUksR0FBRyxLQUFLLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUNoQyxPQUFPLEVBQUMsSUFBSSxFQUFFLEtBQUssRUFBRSxJQUFJLEVBQUMsQ0FBQztBQUM3QixDQUFDIn0=

package/dist/src/validation/form.model.d.ts

@@ -1,41 +1,323 @@
+import { LineagePath, LineagePaths, LineagePathsPartial } from "../config/names/naming-helpers";
+/**
+ * The parameters for a validator error.
+ * The parameters are different for each validator.
+ *
+ * These can be used with the translation message id to create the translated text.
+ *
+ * For example:
+ * {actual: 2, requiredThreshold: 3}
+ */
+export type FormValidatorErrorParams = {
+    [key: string]: unknown;
+};
+/**
+ * The map of validation errors.
+ *
+ * Typically, has a property that is the validation class, e.g. 'min', and
+ * value is a dictionary of message and params that are arbitrary values
+ * that can be used to render an error message template.
+ *
+ * This is similar to FormValidatorComponentErrors, but with the class as the key in a parent object.
+ *
+ * This is similar to the angular form ValidationErrors type (type ValidationErrors = { [key: string]: any;}).
+ */
 export type FormValidatorErrors = {
     [key: string]: {
         message: string;
-        params: {
-            [key: string]: unknown;
-        };
-    };
+        params: FormValidatorErrorParams;
+        /**
+         * The validator class.
+         *
+         * Only set when the error key differs from the class, which happens when the same
+         * validator class is used more than once on a control. In that case the key is made
+         * unique so Angular's error merging keeps every instance, while this property carries
+         * the real class for display.
+         */
+        class?: string;
+    } & FormValidatorTargetField;
 };
-export type FormValidatorConfig = {
+/**
+ * The map of validator config.
+ * The config is different for each validator.
+ */
+export type FormValidatorCreateConfig = {
+    class?: string;
+    message?: string;
+    /**
+     * The key to use for this validator's entry in the merged errors object.
+     *
+     * Defaults to the class. Set to a unique value when the same class is used more than
+     * once on a control, so Angular's error merging does not overwrite earlier instances.
+     *
+     * @internal - This field is managed automatically by the framework. Do not set it
+     * manually in form configuration; doing so will produce an error key that does not
+     * match the validator class, breaking the display recovery in
+     * `getFormValidatorComponentErrors`.
+     */
+    errorKey?: string;
     [key: string]: unknown;
-};
-export type FormValidatorControl = {
+} & FormValidatorTargetField;
+/**
+ * The interface that a form control must implement to be validated by a validator function.
+ * Some form controls are a collection of controls, these must provide a way to access the controls they contain.
+ *
+ * This is similar to the angular AbstractControl class, with only the properties needed for validation.
+ *
+ * @see https://angular.dev/api/forms/AbstractControl
+ */
+export interface FormValidatorControl {
+    /**
+     * The value of the control.
+     * @see https://angular.dev/api/forms/AbstractControl#value
+     */
+    value: unknown;
+    /**
+     * Get the descendant control that matches the path.
+     * @see https://angular.dev/api/forms/AbstractControl#get
+     * @param path
+     */
+    get<P extends string | LineagePath>(path: P): FormValidatorControl | null;
+}
+/**
+ * A simple form validator control that can be used on the server-side to mimic client-side controls.
+ *
+ * Do not use this on the client-side.
+ */
+export declare class SimpleServerFormValidatorControl implements FormValidatorControl {
     value: unknown;
-    get<P extends string>(path: P): FormValidatorControl | null;
-    setErrors(errors: FormValidatorErrors | null): void;
+    constructor(value: unknown);
+    get<P extends string | LineagePath>(path: P): FormValidatorControl | null;
+}
+/**
+ * The validator function.
+ *
+ * Accepts an AbstractControl and returns either validation errors or no errors (null).
+ *
+ * This is similar to the angular form ValidatorFn interface.
+ */
+export interface FormValidatorFn {
+    (control: FormValidatorControl): FormValidatorErrors | null;
+}
+/**
+ * The asynchronous validation function.
+ *
+ * Accepts an AbstractControl and returns a promise that resolves with either validation errors or no errors (null).
+ *
+ * This is similar to the angular form AsyncValidatorFn interface.
+ */
+export interface FormAsyncValidatorFn {
+    (control: FormValidatorControl): Promise<FormValidatorErrors | null>;
+}
+export type FormValidatorFns = {
+    syncDefs: FormValidatorFn[];
+    asyncDefs: FormAsyncValidatorFn[];
 };
-export type FormValidatorFn = (control: FormValidatorControl) => FormValidatorErrors | null;
-export type FormValidatorCreateFn = (config: FormValidatorConfig | null | undefined) => FormValidatorFn;
-export interface FormValidatorDefinition {
-    name: string;
+/**
+ * The validation function creator.
+ *
+ * Takes one config argument, which contains config for the specific validator.
+ *
+ * Returns a form validator function.
+ */
+export type FormValidatorCreateFn = (config: FormValidatorCreateConfig | null | undefined) => FormValidatorFn;
+/**
+ * The asynchronous validation function creator.
+ *
+ * Takes one config argument, which contains config for the specific validator.
+ *
+ * Returns a form async validator function.
+ */
+export type FormAsyncValidatorCreateFn = (config: FormValidatorCreateConfig | null | undefined) => FormAsyncValidatorFn;
+/**
+ * The definition of a validator for a form or a form control, with no create function.
+ */
+export interface FormBaseValidatorDefinition {
+    /**
+     * The unique name of the form validator.
+     */
+    class: string;
+    /**
+     * The message id to display when the validator fails.
+     */
     message: string;
+}
+/**
+ * The definition of a validator for a form or a form control.
+ */
+export interface FormSyncValidatorDefinition extends FormBaseValidatorDefinition {
+    /**
+     * The validation function creator.
+     */
     create: FormValidatorCreateFn;
 }
-export interface FormValidatorBlock {
-    name: string;
-    message?: string | null | undefined;
-    config?: FormValidatorConfig | null | undefined;
+/**
+ * The definition of an async validator for a form or a form control.
+ */
+export interface FormAsyncValidatorDefinition extends FormBaseValidatorDefinition {
+    /**
+     * The async validation function creator.
+     */
+    createAsync: FormAsyncValidatorCreateFn;
 }
-export interface FormValidatorComponentErrors {
-    message: string | null;
-    name: string | null;
-    params?: {
-        [key: string]: unknown;
-    };
+/**
+ * The definition of a validator for a form or a form control.
+ */
+export type FormValidatorDefinition = FormSyncValidatorDefinition | FormAsyncValidatorDefinition;
+/**
+ * The configuration block for a validator for a form or a form control.
+ */
+export interface FormValidatorConfig {
+    /**
+     * The 'class' key used to reference one validator definition.
+     * The optional message and config will be applied to the validator definition with this class.
+     */
+    class: string;
+    /**
+     * The optional message id to display when the validator fails.
+     * This is only needed if the message to show is different to the validator definition.
+     */
+    message?: string;
+    /**
+     * The optional validator config.
+     * Can be left out if the validator takes no config.
+     */
+    config?: FormValidatorCreateConfig;
+    /**
+     * Zero or more validation group names this validator belongs to.
+     *
+     * Validation groups make it easier to run a subset of validators on a form.
+     * The validator will be enabled if any of the groups it is part of are enabled.
+     *
+     * Note that a validation group with 'initialMembership: "all"' will include all validators (that aren't excluded),
+     * even if the validators do not include the group name.
+     */
+    groups?: FormFieldValidationGroup;
+}
+/**
+ * Allows specifying a field to 'own' any validation failures.
+ */
+export interface FormValidatorTargetField {
+    /**
+     * Lineage paths to a target field that will 'own' any validation failures.
+     */
+    targetField?: LineagePathsPartial;
+}
+/**
+ * Form-level validator config that allows specifying a field to 'own' any validation failures.
+ */
+export interface FormValidatorTargetFieldConfig extends FormValidatorConfig, FormValidatorTargetField {
+}
+/**
+ * One validator error.
+ */
+export interface FormValidatorComponentErrors extends FormValidatorTargetField {
+    /**
+     * The message id for the validator.
+     */
+    message: string;
+    /**
+     * The class of the validator.
+     */
+    class: string;
+    /**
+     * The params for rendering the translated message.
+     */
+    params: FormValidatorErrorParams;
 }
+/**
+ * Form or form control errors from a validator.
+ *
+ * Controls can be nested, so validation errors can be nested.
+ * The nesting is how the client-side is able to reveal a form field when
+ * a link in the validation summary is clicked.
+ *
+ * If all errors arrays are empty, then the validation summary is treated as 'form is valid'.
+ */
 export interface FormValidatorSummaryErrors {
+    /**
+     * The id of the form control.
+     *
+     * This is used on the client-side for linking to the form control to reveal it.
+     * If this is not available, the validation error is rendered with the form field label and with no link.
+     */
     id: string | null;
+    /**
+     * The message id for the form control label.
+     *
+     * This is passed to the translation service to get the label text.
+     * If this is not available, the id is used, otherwise a default label is used.
+     */
     message: string | null;
+    /**
+     * The validation errors for the form control.
+     *
+     * These are rendered using the translation service - the message id can use the params to calculate the text to show.
+     * If there are no errors, then the form field is not shown in the error summary.
+     */
     errors: FormValidatorComponentErrors[];
-    parents: string[] | null;
+    /**
+     * The lineage paths to this form control.
+     *
+     * This enables revealing the parents, to be able to navigate to the form control.
+     */
+    lineagePaths: LineagePaths;
+}
+/**
+ * Form validation groups, where the key is the name, and the value is the definition.
+ */
+export interface FormValidationGroups {
+    /**
+     * The key is the name of the validation group.
+     */
+    [key: string]: FormValidationGroup;
+}
+/**
+ * A form validation group,
+ * which describes the purpose or usage of the group and the initial membership of the group.
+ */
+export interface FormValidationGroup {
+    /**
+     * A short description of the purpose or usage of the validation group.
+     */
+    description: string;
+    /**
+     * The approach this validation group uses to specify which validators are included.
+     *
+     * Default is "none".
+     */
+    initialMembership?: FormValidationGroupMembership;
+}
+/**
+ * The available form validation group membership approaches.
+ *
+ * Options:
+ * - 'all': Every known / available validator.
+ * - 'none': An empty array / no validators.
+ */
+export declare const formValidationGroupMembership: readonly ["all", "none"];
+/**
+ * The type for the available form validation group membership approaches.
+ */
+export type FormValidationGroupMembership = typeof formValidationGroupMembership[number];
+/**
+ * Specify the validation groups to include or exclude.
+ * All the validation groups used here must also be present in the form top-level validationGroups property.
+ * The groups will be added or removed from some list of validation groups.
+ */
+export interface FormFieldValidationGroup {
+    /**
+     * A list of the validation groups to include / add / enable.
+     *
+     * Default is empty array.
+     * Use when a validator should be included in a group with initial membership of none.
+     */
+    include?: string[];
+    /**
+     * A list of the validation groups to exclude / remove / disable.
+     *
+     * Default is empty array.
+     * Use when a validator should be excluded from a group with initial membership of all.
+     */
+    exclude?: string[];
 }

package/dist/src/validation/form.model.js

@@ -1,3 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9ybS5tb2RlbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy92YWxpZGF0aW9uL2Zvcm0ubW9kZWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9
+exports.formValidationGroupMembership = exports.SimpleServerFormValidatorControl = void 0;
+const lodash_1 = require("lodash");
+/**
+ * A simple form validator control that can be used on the server-side to mimic client-side controls.
+ *
+ * Do not use this on the client-side.
+ */
+class SimpleServerFormValidatorControl {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    get(path) {
+        const result = (0, lodash_1.get)(this.value, path) ?? null;
+        // For debugging:
+        // console.debug(`SimpleServerFormValidatorControl.get path ${JSON.stringify(path)} with result ${JSON.stringify(result)} from value ${JSON.stringify(this.value)}`);
+        return result;
+    }
+}
+exports.SimpleServerFormValidatorControl = SimpleServerFormValidatorControl;
+/**
+ * The available form validation group membership approaches.
+ *
+ * Options:
+ * - 'all': Every known / available validator.
+ * - 'none': An empty array / no validators.
+ */
+exports.formValidationGroupMembership = ["all", "none"];
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9ybS5tb2RlbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy92YWxpZGF0aW9uL2Zvcm0ubW9kZWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsbUNBQXFDO0FBdUZyQzs7OztHQUlHO0FBQ0gsTUFBYSxnQ0FBZ0M7SUFDekMsS0FBSyxDQUFVO0lBRWYsWUFBWSxLQUFjO1FBQ3RCLElBQUksQ0FBQyxLQUFLLEdBQUcsS0FBSyxDQUFDO0lBQ3ZCLENBQUM7SUFFRCxHQUFHLENBQWlDLElBQU87UUFDdkMsTUFBTSxNQUFNLEdBQUcsSUFBQSxZQUFJLEVBQUMsSUFBSSxDQUFDLEtBQUssRUFBRSxJQUFJLENBQUMsSUFBSSxJQUFJLENBQUM7UUFFOUMsaUJBQWlCO1FBQ2pCLHFLQUFxSztRQUVySyxPQUFPLE1BQU0sQ0FBQztJQUNsQixDQUFDO0NBQ0o7QUFmRCw0RUFlQztBQXNORDs7Ozs7O0dBTUc7QUFDVSxRQUFBLDZCQUE2QixHQUFHLENBQUMsS0FBSyxFQUFFLE1BQU0sQ0FBVSxDQUFDIn0=

package/dist/src/validation/helpers.d.ts

@@ -1,8 +1,16 @@
-import { FormValidatorConfig } from "./form.model";
+import { FormValidatorCreateConfig, FormValidatorErrorParams, FormValidatorErrors } from "./form.model";
+/**
+ * Extract the length property in case it's an array or a string.
+ * Extract the size property in case it's a set.
+ * Return null else.
+ * @param value Either an array, set or undefined.
+ */
 export declare function formValidatorLengthOrSize(value: null | string | unknown[] | Set<unknown> | unknown): number | null;
-export declare function formValidatorGetDefinitionItem(config: FormValidatorConfig | null | undefined, key: string, defaultValue?: unknown): unknown;
-export declare function formValidatorGetDefinitionString(config: FormValidatorConfig | null | undefined, key: string, defaultValue?: string | undefined): string;
-export declare function formValidatorGetDefinitionNumber(config: FormValidatorConfig | null | undefined, key: string, defaultValue?: string | undefined): number;
-export declare function formValidatorGetDefinitionBoolean(config: FormValidatorConfig | null | undefined, key: string, defaultValue?: boolean | undefined): boolean;
-export declare function formValidatorGetDefinitionRegexp(config: FormValidatorConfig | null | undefined, key: string, defaultValue?: RegExp | undefined): RegExp;
-export declare function formValidatorGetDefinitionArray(config: FormValidatorConfig | null | undefined, key: string, defaultValue?: unknown[] | undefined): unknown[];
+export declare function formValidatorGetDefinitionItem(config: FormValidatorCreateConfig | null | undefined, key: string, defaultValue?: unknown): unknown;
+export declare function formValidatorGetDefinitionString(config: FormValidatorCreateConfig | null | undefined, key: string, defaultValue?: string | undefined): string;
+export declare function formValidatorGetDefinitionNumber(config: FormValidatorCreateConfig | null | undefined, key: string, defaultValue?: string | undefined): number;
+export declare function formValidatorGetDefinitionBoolean(config: FormValidatorCreateConfig | null | undefined, key: string, defaultValue?: boolean | undefined): boolean;
+export declare function formValidatorGetDefinitionRegexp(config: FormValidatorCreateConfig | null | undefined, key: string, defaultValue?: RegExp | undefined): RegExp;
+export declare function formValidatorGetDefinitionArray(config: FormValidatorCreateConfig | null | undefined, key: string, defaultValue?: unknown[] | undefined): unknown[];
+export declare function formValidatorGetDefinitionObject(config: FormValidatorCreateConfig | null | undefined, key: string, defaultValue?: Record<string, unknown> | undefined): Record<string, unknown>;
+export declare function formValidatorBuildError(config: FormValidatorCreateConfig | null | undefined, params?: FormValidatorErrorParams): FormValidatorErrors;