@lion/ui 0.0.1

package/components/form-core/src/validate/Validator.js

@@ -0,0 +1,251 @@
+/**
+ * @typedef {import('../../types/validate/index.js').FeedbackMessageData} FeedbackMessageData
+ * @typedef {import('../../types/validate/index.js').ValidatorParam} ValidatorParam
+ * @typedef {import('../../types/validate/index.js').ValidatorConfig} ValidatorConfig
+ * @typedef {import('../../types/validate/index.js').ValidatorOutcome} ValidatorOutcome
+ * @typedef {import('../../types/validate/index.js').ValidatorName} ValidatorName
+ * @typedef {import('../../types/validate/index.js').ValidationType} ValidationType
+ * @typedef {import('../FormControlMixin.js').FormControlHost} FormControlHost
+ */
+
+// TODO: support attribute validators like <my-el my-validator=${dynamicParam}></my-el> =>
+// register in a ValidateService that is read by Validator and adds these attrs in properties
+// object.
+// They would become like configurable
+// [global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes)
+// for FormControls.
+
+export class Validator extends EventTarget {
+  /**
+   * @param {ValidatorParam} [param]
+   * @param {ValidatorConfig} [config]
+   */
+  constructor(param, config) {
+    super();
+
+    /** @type {ValidatorParam} */
+    this.__param = param;
+    /** @type {ValidatorConfig} */
+    this.__config = config || {};
+    /** @type {ValidationType} */
+    this.type = config?.type || 'error'; // Default type supported by ValidateMixin
+  }
+
+  /**
+   * The name under which validation results get registered. For convience and predictability, this
+   * should always be the same as the constructor name (since it will be obfuscated in js builds,
+   * we need to provide it separately).
+   * @type {ValidatorName}
+   */
+  static validatorName = '';
+
+  /**
+   * Whether the validator is asynchronous or not. When true., this means execute function returns
+   * a Promise. This can be handy for:
+   * - server side calls
+   * - validations that are dependent on lazy loaded resources (they can be async until the dependency
+   * is loaded)
+   * @type {boolean}
+   */
+  static async = false;
+
+  /**
+   * The function that returns a validity outcome. When we need to show feedback,
+   * it should return true, otherwise false. So when an error\info|warning|success message
+   * needs to be shown, return true. For async Validators, the function can return a Promise.
+   * It's also possible to return an enum. Let's say that a phone number can have multiple
+   * states: 'invalid-country-code' | 'too-long' | 'too-short'
+   * Those states can be retrieved in the getMessage
+   * @param {any} modelValue
+   * @param {ValidatorParam} [param]
+   * @param {ValidatorConfig} [config]
+   * @returns {ValidatorOutcome|Promise<ValidatorOutcome>}
+   */
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  execute(modelValue, param, config) {
+    const ctor = /** @type {typeof Validator} */ (this.constructor);
+    if (!ctor.validatorName) {
+      throw new Error(
+        'A validator needs to have a name! Please set it via "static get validatorName() { return \'IsCat\'; }"',
+      );
+    }
+    return true;
+  }
+
+  /**
+   * The first argument of the constructor, for instance 3 in `new MinLength(3)`. Will
+   * be stored on Validator instance and passed to `execute` function
+   * @example
+   * ```js
+   *  // Store reference to Validator instance
+   *  const myValidatorInstance = new MyValidator(1);
+   *  // Use this instance initially on a FormControl (that uses ValidateMixin)
+   *  render(html`<validatable-element .validators="${[myValidatorInstance]}"></validatable-element>`, document.body);
+   *  // Based on some event, we need to change the param
+   *  myValidatorInstance.param = 2;
+   * ```
+   * @property {ValidatorParam}
+   */
+  set param(p) {
+    this.__param = p;
+    /**
+     * This event is listened for by ValidateMixin. Whenever the validation parameter has
+     * changed, the FormControl will revalidate itself
+     */
+    this.dispatchEvent(new Event('param-changed'));
+  }
+
+  get param() {
+    return this.__param;
+  }
+
+  /**
+   * The second argument of the constructor, for instance
+   * `new MinLength(3, {getFeedMessage: async () => 'too long'})`.
+   * Will be stored on Validator instance and passed to `execute` function.
+   * @example
+   * ```js
+   *  // Store reference to Validator instance
+   *  const myValidatorInstance = new MyValidator(1, {getMessage() => 'x'});
+   *  // Use this instance initially on a FormControl (that uses ValidateMixin)
+   *  render(html`<validatable-element .validators="${[myValidatorInstance]}"></validatable-element>`, document.body);
+   *  // Based on some event, we need to change the param
+   *  myValidatorInstance.config = {getMessage() => 'y'};
+   * ```
+   * @property {ValidatorConfig}
+   */
+  set config(c) {
+    this.__config = c;
+    /**
+     * This event is listened for by ValidateMixin. Whenever the validation config has
+     * changed, the FormControl will revalidate itself
+     */
+    this.dispatchEvent(new Event('config-changed'));
+  }
+
+  get config() {
+    return this.__config;
+  }
+
+  /**
+   * This is a protected method that usually should not be overridden. It is called by ValidateMixin
+   * and it gathers data to be passed to getMessage functions found:
+   * - `this.config.getMessage`, locally provided by consumers of the Validator (overrides global getMessage)
+   * - `MyValidator.getMessage`, globally provided by creators or consumers of the Validator
+   *
+   * Confusion can arise because of similarities with former mentioned methods. In that regard, a
+   * better name for this function would have been _pepareDataAndCallHighestPrioGetMessage.
+   * @example
+   * ```js
+   * class MyValidator extends Validator {
+   *   // ...
+   *   // 1. globally defined
+   *   static async getMessage() {
+   *     return 'lowest prio, defined globally by Validator author'
+   *   }
+   * }
+   * // 2. globally overridden
+   * MyValidator.getMessage = async() => 'overrides already configured message';
+   * // 3. locally overridden
+   * new MyValidator(myParam, { getMessage: async() => 'locally defined, always wins' });
+   * ```
+   * @param {Partial<FeedbackMessageData>} [data]
+   * @returns {Promise<string|Element>}
+   * @protected
+   */
+  async _getMessage(data) {
+    const ctor = /** @type {typeof Validator} */ (this.constructor);
+    const composedData = {
+      name: ctor.validatorName,
+      type: this.type,
+      params: this.param,
+      config: this.config,
+      ...data,
+    };
+    if (this.config.getMessage) {
+      if (typeof this.config.getMessage === 'function') {
+        return this.config.getMessage(composedData);
+      }
+      throw new Error(
+        `You must provide a value for getMessage of type 'function', you provided a value of type: ${typeof this
+          .config.getMessage}`,
+      );
+    }
+    return ctor.getMessage(composedData);
+  }
+
+  /**
+   * Called inside Validator.prototype._getMessage (see explanation).
+   * @example
+   * ```js
+   * class MyValidator extends Validator {
+   *   static async getMessage() {
+   *     return 'lowest prio, defined globally by Validator author'
+   *   }
+   * }
+   * // globally overridden
+   * MyValidator.getMessage = async() => 'overrides already configured message';
+   * ```
+   * @overridable
+   * @param {Partial<FeedbackMessageData>} [data]
+   * @returns {Promise<string|Element>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  static async getMessage(data) {
+    return `Please configure an error message for "${this.name}" by overriding "static async getMessage()"`;
+  }
+
+  /**
+   * Validators are allowed to have knowledge about FormControls.
+   * In some cases (in case of the Required Validator) we wanted to enhance accessibility by
+   * adding [aria-required]. Also, it would be possible to write an advanced MinLength
+   * Validator that adds a .preprocessor that restricts from typing too many characters
+   * (like the native [minlength] validator).
+   * Will be called when Validator is added to FormControl.validators.
+   * @example
+   * ```js
+   * onFormControlConnect(formControl) {
+   *   if(formControl.inputNode) {
+   *     inputNode.setAttribute('aria-required', 'true');
+   *   }
+   * }
+   *
+   * ```
+   * @configurable
+   * @param {FormControlHost} formControl
+   */
+  onFormControlConnect(formControl) {} // eslint-disable-line
+
+  /**
+   * Also see `onFormControlConnect`.
+   * Will be called when Validator is removed from FormControl.validators.
+   * @example
+   * ```js
+   * onFormControlDisconnect(formControl) {
+   *   if(formControl.inputNode) {
+   *     inputNode.removeAttribute('aria-required');
+   *   }
+   * }
+   * @configurable
+   * @param {FormControlHost} formControl
+   */
+  onFormControlDisconnect(formControl) {} // eslint-disable-line
+
+  /**
+   * @desc Used on async Validators, makes it able to do perf optimizations when there are
+   * pending "execute" calls with outdated values.
+   * ValidateMixin calls Validator.abortExecution() an async Validator can act accordingly,
+   * depending on its implementation of the "execute" function.
+   * - For instance, when fetch was called:
+   * https://stackoverflow.com/questions/31061838/how-do-i-cancel-an-http-fetch-request
+   * - Or, when a webworker was started, its process could be aborted and then restarted.
+   */
+  abortExecution() {} // eslint-disable-line
+}
+
+// For simplicity, a default validator only handles one state:
+// it can either be true or false an it will only have one message.
+// In more advanced cases (think of the feedback mechanism for the maximum number of
+// characters in Twitter), more states are needed. The alternative of
+// having multiple distinct validators would be cumbersome to create and maintain,
+// also because the validations would tie too much into each others logic.

package/components/form-core/src/validate/resultValidators/DefaultSuccess.js

@@ -0,0 +1,33 @@
+import { ResultValidator } from '../ResultValidator.js';
+
+/**
+ * @typedef {import('../Validator.js').Validator} Validator
+ */
+
+export class DefaultSuccess extends ResultValidator {
+  /**
+   * @param  {...any} args
+   */
+  constructor(...args) {
+    super(...args);
+    this.type = 'success';
+  }
+
+  /**
+   *
+   * @param {Object} context
+   * @param {Validator[]} context.regularValidationResult
+   * @param {Validator[]} context.prevValidationResult
+   * @param {Validator[]} context.prevShownValidationResult
+   * @returns {boolean}
+   */
+  // eslint-disable-next-line class-methods-use-this
+  executeOnResults({ regularValidationResult, prevShownValidationResult }) {
+    const errorOrWarning = /** @param {Validator} v */ v =>
+      v.type === 'error' || v.type === 'warning';
+    const hasErrorOrWarning = !!regularValidationResult.filter(errorOrWarning).length;
+    const hasShownErrorOrWarning = !!prevShownValidationResult.filter(errorOrWarning).length;
+
+    return !hasErrorOrWarning && hasShownErrorOrWarning;
+  }
+}

package/components/form-core/src/validate/validators/DateValidators.js

@@ -0,0 +1,103 @@
+/* eslint-disable max-classes-per-file */
+// TODO: move to input-datepicker?
+import { normalizeDateTime } from '@lion/ui/localize.js';
+import { Validator } from '../Validator.js';
+
+/**
+ * @param {?} value
+ */
+function isDate(value) {
+  return (
+    Object.prototype.toString.call(value) === '[object Date]' && !Number.isNaN(value.getTime())
+  );
+}
+
+export class IsDate extends Validator {
+  static get validatorName() {
+    return 'IsDate';
+  }
+
+  /**
+   * @param {?} value
+   */
+  // eslint-disable-next-line class-methods-use-this
+  execute(value) {
+    let hasError = false;
+    if (!isDate(value)) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class MinDate extends Validator {
+  static get validatorName() {
+    return 'MinDate';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, min = this.param) {
+    let hasError = false;
+    if (!isDate(value) || normalizeDateTime(value) < normalizeDateTime(min)) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class MaxDate extends Validator {
+  static get validatorName() {
+    return 'MaxDate';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, max = this.param) {
+    let hasError = false;
+    if (!isDate(value) || normalizeDateTime(value) > normalizeDateTime(max)) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class MinMaxDate extends Validator {
+  static get validatorName() {
+    return 'MinMaxDate';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, { min = 0, max = 0 } = this.param) {
+    let hasError = false;
+    if (
+      !isDate(value) ||
+      normalizeDateTime(value) < normalizeDateTime(min) ||
+      normalizeDateTime(value) > normalizeDateTime(max)
+    ) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class IsDateDisabled extends Validator {
+  static get validatorName() {
+    return 'IsDateDisabled';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, isDisabledFn = this.param) {
+    let hasError = false;
+    if (!isDate(value) || isDisabledFn(value)) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}

package/components/form-core/src/validate/validators/NumberValidators.js

@@ -0,0 +1,80 @@
+/* eslint-disable max-classes-per-file */
+import { Validator } from '../Validator.js';
+
+/**
+ * check for not being NaN (NaN is the only value in javascript which is not equal to itself)
+ *
+ * @param {number} value to check
+ */
+const isNumber = value =>
+  // eslint-disable-next-line no-self-compare
+  value === value && typeof value === 'number';
+
+export class IsNumber extends Validator {
+  static get validatorName() {
+    return 'IsNumber';
+  }
+
+  /**
+   * @param {?} value
+   */
+  // eslint-disable-next-line class-methods-use-this
+  execute(value) {
+    let isEnabled = false;
+    if (!isNumber(value)) {
+      isEnabled = true;
+    }
+    return isEnabled;
+  }
+}
+
+export class MinNumber extends Validator {
+  static get validatorName() {
+    return 'MinNumber';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, min = this.param) {
+    let isEnabled = false;
+    if (!isNumber(value) || value < min) {
+      isEnabled = true;
+    }
+    return isEnabled;
+  }
+}
+
+export class MaxNumber extends Validator {
+  static get validatorName() {
+    return 'MaxNumber';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, max = this.param) {
+    let isEnabled = false;
+    if (!isNumber(value) || value > max) {
+      isEnabled = true;
+    }
+    return isEnabled;
+  }
+}
+
+export class MinMaxNumber extends Validator {
+  static get validatorName() {
+    return 'MinMaxNumber';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, { min = 0, max = 0 } = this.param) {
+    let isEnabled = false;
+    if (!isNumber(value) || value < min || value > max) {
+      isEnabled = true;
+    }
+    return isEnabled;
+  }
+}

package/components/form-core/src/validate/validators/Required.js

@@ -0,0 +1,71 @@
+import { Validator } from '../Validator.js';
+
+/**
+ * @typedef {import('../../../types/FormControlMixinTypes.js').FormControlHost} FormControlHost
+ */
+
+export class Required extends Validator {
+  static get validatorName() {
+    return 'Required';
+  }
+
+  /**
+   * In order to prevent accessibility violations, the aria-required attribute will
+   * be combined with compatible aria roles: https://www.w3.org/TR/wai-aria/#aria-required
+   */
+  static get _compatibleRoles() {
+    return [
+      'combobox',
+      'gridcell',
+      'input',
+      'listbox',
+      'radiogroup',
+      'select',
+      'spinbutton',
+      'textarea',
+      'textbox',
+      'tree',
+    ];
+  }
+
+  /**
+   * In order to prevent accessibility violations, the aria-required attribute will
+   * be combined with compatible platform input elements
+   */
+  static get _compatibleTags() {
+    return ['input', 'select', 'textarea'];
+  }
+
+  /**
+   * We don't have an execute function, since the Required validator is 'special'.
+   * The outcome depends on the modelValue of the FormControl and
+   * FormControl.__isEmpty / FormControl._isEmpty.
+   */
+
+  /**
+   * @param {FormControlHost & HTMLElement} formControl
+   */
+  // @ts-ignore [allow-protected] we are allowed to know FormControl protcected props in form-core
+  // eslint-disable-next-line class-methods-use-this
+  onFormControlConnect({ _inputNode: inputNode }) {
+    if (inputNode) {
+      const role = inputNode.getAttribute('role') || '';
+      const elementTagName = inputNode.tagName.toLowerCase();
+      const ctor = /** @type {typeof Required} */ (this.constructor);
+      if (ctor._compatibleRoles.includes(role) || ctor._compatibleTags.includes(elementTagName)) {
+        inputNode.setAttribute('aria-required', 'true');
+      }
+    }
+  }
+
+  /**
+   * @param {FormControlHost & HTMLElement} formControl
+   */
+  // @ts-ignore [allow-protected] we are allowed to know FormControl protcected props in form-core
+  // eslint-disable-next-line class-methods-use-this
+  onFormControlDisconnect({ _inputNode: inputNode }) {
+    if (inputNode) {
+      inputNode.removeAttribute('aria-required');
+    }
+  }
+}

package/components/form-core/src/validate/validators/StringValidators.js

@@ -0,0 +1,142 @@
+/* eslint-disable max-classes-per-file */
+import { Validator } from '../Validator.js';
+
+/**
+ * @param {?} value
+ */
+const isString = value => typeof value === 'string';
+
+export class IsString extends Validator {
+  static get validatorName() {
+    return 'IsString';
+  }
+
+  /**
+   * @param {?} value
+   */
+  // eslint-disable-next-line class-methods-use-this
+  execute(value) {
+    let hasError = false;
+    if (!isString(value)) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class EqualsLength extends Validator {
+  static get validatorName() {
+    return 'EqualsLength';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, length = this.param) {
+    let hasError = false;
+    if (!isString(value) || value.length !== length) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class MinLength extends Validator {
+  static get validatorName() {
+    return 'MinLength';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, min = this.param) {
+    let hasError = false;
+    if (!isString(value) || value.length < min) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class MaxLength extends Validator {
+  static get validatorName() {
+    return 'MaxLength';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, max = this.param) {
+    let hasError = false;
+    if (!isString(value) || value.length > max) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+export class MinMaxLength extends Validator {
+  static get validatorName() {
+    return 'MinMaxLength';
+  }
+
+  /**
+   * @param {?} value
+   */
+  execute(value, { min = 0, max = 0 } = this.param) {
+    let hasError = false;
+    if (!isString(value) || value.length < min || value.length > max) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+const isEmailRegex =
+  /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
+export class IsEmail extends Validator {
+  static get validatorName() {
+    return 'IsEmail';
+  }
+
+  /**
+   * @param {?} value
+   */
+  // eslint-disable-next-line class-methods-use-this
+  execute(value) {
+    let hasError = false;
+    if (!isString(value) || !isEmailRegex.test(value.toLowerCase())) {
+      hasError = true;
+    }
+    return hasError;
+  }
+}
+
+/**
+ * @param {?} value
+ * @param {RegExp} pattern
+ */
+const hasPattern = (value, pattern) => pattern.test(value);
+export class Pattern extends Validator {
+  static get validatorName() {
+    return 'Pattern';
+  }
+
+  /**
+   * @param {?} value
+   */
+  // eslint-disable-next-line class-methods-use-this
+  execute(value, pattern = this.param) {
+    if (!(pattern instanceof RegExp)) {
+      throw new Error(
+        'Psst... Pattern validator expects RegExp object as parameter e.g, new Pattern(/#LionRocks/) or new Pattern(RegExp("#LionRocks")',
+      );
+    }
+    let hasError = false;
+    if (!isString(value) || !hasPattern(value, pattern)) {
+      hasError = true;
+    }
+
+    return hasError;
+  }
+}