@lion/ui 0.0.1

package/components/form-core/types/validate/ValidateMixinTypes.ts

@@ -0,0 +1,238 @@
+import { LitElement } from 'lit';
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { ScopedElementsHost } from '@open-wc/scoped-elements';
+
+import { DisabledHost } from '../../../core/types/DisabledMixinTypes.js';
+import { SlotHost } from '../../../core/types/SlotMixinTypes.js';
+
+import { FormControlHost } from '../FormControlMixinTypes.js';
+import { SyncUpdatableHost } from '../utils/SyncUpdatableMixinTypes.js';
+import { Validator } from '../../src/validate/Validator.js';
+
+type ScopedElementsMap = {
+  [key: string]: typeof HTMLElement;
+};
+
+type FeedbackMessage = {
+  message: string | Node;
+  type: string;
+  validator?: Validator;
+};
+
+export type ValidationType = 'error' | 'warning' | 'info' | 'success' | string;
+
+export declare class ValidateHost {
+  /**
+   * Used by Application Developers to add Validators to a FormControl.
+   * @example
+   * ```html
+   * <form-control .validators="${[new Required(), new MinLength(4, {type: 'warning'})]}">
+   * </form-control>
+   * ```
+   */
+  validators: Validator[];
+
+  /**
+   * As soon as validation happens (after modelValue/validators/validator param change), this
+   * array is updated with the active ValidationTypes ('error'|'warning'|'success'|'info' etc.).
+   * Notice the difference with `.showsFeedbackFor`, which filters `.hasFeedbackFor` based on
+   * `.feedbackCondition()`.
+   *
+   * For styling purposes, will be reflected to [has-feedback-for="error warning"]. This can
+   * be useful for subtle visual feedback on keyup, like a red/green border around an input.
+   *
+   * @readOnly
+   * @example
+   * ```css
+   * :host([has-feedback-for~="error"]) .input-group__container {
+   *   border: 1px solid red;
+   * }
+   * ```
+   */
+  hasFeedbackFor: ValidationType[];
+
+  /**
+   * Based on outcome of feedbackCondition, this array decides what ValidationTypes should be
+   * shown in validationFeedback, based on meta data like interaction states.
+   *
+   * For styling purposes, it reflects it `[shows-feedback-for="error warning"]`
+   * @readOnly
+   * @example
+   * ```css
+   * :host([shows-feedback-for~="success"]) .form-field__feedback {
+   *   transform: scaleY(1);
+   * }
+   * ```
+   */
+  showsFeedbackFor: ValidationType[];
+
+  /**
+   * A temporary storage to transition from hasFeedbackFor to showsFeedbackFor
+   * @type {ValidationType[]}
+   * @readOnly
+   * @private
+   */
+  private shouldShowFeedbackFor: ValidationType[];
+
+  /**
+   * The outcome of a validation 'round'. Keyed by ValidationType and Validator name
+   * @readOnly
+   */
+  validationStates: { [key: string]: { [key: string]: Object } };
+
+  /**
+   * Flag indicating whether async validation is pending.
+   * Creates attribute [is-pending] as a styling hook
+   */
+  isPending: boolean;
+
+  /**
+   * Used by Subclassers to add default Validators to a particular FormControl.
+   * A date input for instance, always needs the isDate validator.
+   * @example
+   * ```js
+   * this.defaultValidators.push(new IsDate());
+   * ```
+   */
+  defaultValidators: Validator[];
+  fieldName: string;
+  validateComplete: Promise<void>;
+  feedbackComplete: Promise<void>;
+
+  static validationTypes: string[];
+
+  /**
+   * Triggered by:
+   *  - modelValue change
+   *  - change in the 'validators' array
+   *  - change in the config of an individual Validator
+   *
+   * Three situations are handled:
+   * - a1) the FormControl is empty: further execution is halted. When the Required Validator
+   * (being mutually exclusive to the other Validators) is applied, it will end up in the
+   * validation result (as the only Validator, since further execution was halted).
+   * - a2) there are synchronous Validators: this is the most common flow. When modelValue hasn't
+   * changed since last async results were generated, 'sync results' are merged with the
+   * 'async results'.
+   * - a3) there are asynchronous Validators: for instance when server side evaluation is needed.
+   * Executions are scheduled and awaited and the 'async results' are merged with the
+   * 'sync results'.
+   *
+   * - b) there are ResultValidators. After steps a1, a2, or a3 are finished, the holistic
+   * ResultValidators (evaluating the total result of the 'regular' (a1, a2 and a3) validators)
+   * will be run...
+   *
+   * Situations a2 and a3 are not mutually exclusive and can be triggered within one `validate()`
+   * call. Situation b will occur after every call.
+   *
+   * @param {{ clearCurrentResult?: boolean }} [opts]
+   */
+  validate(opts?: { clearCurrentResult?: boolean }): void;
+
+  /**
+   * The amount of feedback messages that will visible in LionValidationFeedback
+   */
+  protected _visibleMessagesAmount: number;
+
+  /**
+   * Combination of validators provided by Application Developer and the default validators
+   */
+  protected _allValidators: Validator[];
+
+  /**
+   * Allows Subclassers to add meta info for feedbackCondition
+   */
+  protected get _feedbackConditionMeta(): object;
+
+  /**
+   * Responsible for retrieving messages from Validators and
+   * (delegation of) rendering them.
+   *
+   * For `._feedbackNode` (extension of LionValidationFeedback):
+   * - retrieve messages from highest prio Validators
+   * - provide the result to custom feedback node and let the
+   * custom node decide on their renderings
+   *
+   * In both cases:
+   * - we compute the 'show' flag (like 'hasErrorVisible') for all types
+   * - we set the customValidity message of the highest prio Validator
+   * - we set aria-invalid="true" in case hasErrorVisible is true
+   */
+  protected _updateFeedbackComponent(): void;
+
+  /**
+   * Default feedbackCondition condition, used by Subclassers, that will be used when
+   * `feedbackCondition()` is not overridden by Application Developer.
+   * Show the validity feedback when returning true, don't show when false
+   * @param {string} type could be 'error', 'warning', 'info', 'success' or any other custom
+   * Validator type
+   * @param {object} meta meta info (interaction states etc)
+   */
+  protected _showFeedbackConditionFor(type: string, meta: object): boolean;
+
+  /**
+   * Used to translate `.hasFeedbackFor` and `.shouldShowFeedbackFor` to `.showsFeedbackFor`
+   */
+  protected _hasFeedbackVisibleFor(type: string): boolean;
+  protected _updateShouldShowFeedbackFor(): void;
+
+  /**
+   * Orders all active validators in this.__validationResult. Can also filter out occurrences
+   * (based on interaction states).
+   *
+   * @example
+   * ```js
+   * _prioritizeAndFilterFeedback({ validationResult }) {
+   *   // Put info messages on top; no limitation by `._visibleMessagesAmount`
+   *   const meta = this._feedbackConditionMeta;
+   *   return validationResult.filter(v =>
+   *     this.feedbackCondition(v.type, meta, this._showFeedbackConditionFor.bind(this))
+   *   ).sort((a, b) => a.type === 'info' ? 1 : 0);
+   * }
+   * ```
+   */
+  protected _prioritizeAndFilterFeedback(opts: { validationResult: Validator[] }): Validator[];
+
+  private __syncValidationResult: Validator[];
+  private __asyncValidationResult: Validator[];
+  private __validationResult: Validator[];
+  private __prevValidationResult: Validator[];
+  private __prevShownValidationResult: Validator[];
+  private __childModelValueChanged: boolean;
+
+  private __storePrevResult(): void;
+  private __executeValidators(): void;
+  private __validateCompleteResolve(): void;
+  private __executeSyncValidators(
+    syncValidators: Validator[],
+    value: unknown,
+    opts: { hasAsync: boolean },
+  ): void;
+  private __executeAsyncValidators(asyncValidators: Validator[], value: unknown): void;
+  private __executeResultValidators(regularValidationResult: Validator[]): Validator[];
+  private __finishValidation(options: { source: 'sync' | 'async'; hasAsync?: boolean }): void;
+  private __clearValidationResults(): void;
+  private __onValidatorUpdated(e: Event | CustomEvent): void;
+  private __setupValidators(): void;
+  private __isEmpty(v: unknown): boolean;
+  private __getFeedbackMessages(validators: Validator[]): Promise<FeedbackMessage[]>;
+}
+
+export declare function ValidateImplementation<T extends Constructor<LitElement>>(
+  superclass: T,
+): T &
+  Constructor<ValidateHost> &
+  Pick<typeof ValidateHost, keyof typeof ValidateHost> &
+  Constructor<FormControlHost> &
+  Pick<typeof FormControlHost, keyof typeof FormControlHost> &
+  Constructor<SyncUpdatableHost> &
+  Pick<typeof SyncUpdatableHost, keyof typeof SyncUpdatableHost> &
+  Constructor<DisabledHost> &
+  Pick<typeof DisabledHost, keyof typeof DisabledHost> &
+  Constructor<SlotHost> &
+  Pick<typeof SlotHost, keyof typeof SlotHost> &
+  Constructor<ScopedElementsHost> &
+  Pick<typeof ScopedElementsHost, keyof typeof ScopedElementsHost> &
+  Pick<typeof LitElement, keyof typeof LitElement>;
+
+export type ValidateMixin = typeof ValidateImplementation;

package/components/form-core/types/validate/index.ts

@@ -0,0 +1,2 @@
+export * from './validate.js';
+export * from './ValidateMixinTypes.js';

package/components/form-core/types/validate/validate.ts

@@ -0,0 +1,60 @@
+import { FormControlHost } from '../../src/FormControlMixin.js';
+import { ValidationType } from './ValidateMixinTypes.js';
+
+/**
+ * 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).
+ * @example
+ * ```js
+ * class MyValidator extends Validator {
+ *   static validatorName = 'MyValidator';
+ *   // etc...
+ * }
+ * ```
+ */
+export type ValidatorName = string;
+
+/**
+ * The first argument of the constructor, for instance 3 in `new MinLength(3)`. Will
+ * be stored on Validator instance and passed to `execute` function
+ */
+export type ValidatorParam = any;
+
+/**
+ * The second argument of the constructor, for instance
+ * `new MinLength(3, {getFeedbackMessage: async () => 'too long'})`.
+ * Will be stored on Validator instance and passed to `execute` function
+ */
+export type ValidatorConfig = {
+  getMessage?: (data: Partial<FeedbackMessageData>) => Promise<string | Element> | string | Element;
+  type?: ValidationType;
+  node?: FormControlHost;
+  fieldName?: string | Promise<string>;
+};
+
+/**
+ * Output of the `execute` function that returns a validity outcome. When we need to shpw feedback,
+ * it should return true, otherwise false. So when an error\info|warning|success message
+ * needs to be shown, return true.
+ * 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 function.
+ */
+export type ValidatorOutcome = string | boolean;
+
+/**
+ * Data object that will be provided to `getMessage()` method
+ */
+export type FeedbackMessageData = {
+  modelValue: any;
+  /** Value configured in FormControl.fieldName. Contributes to accessible error messages */
+  fieldName: string;
+  name: ValidatorName;
+  formControl: FormControlHost;
+  type: ValidationType;
+  /* Outcome of Validator.execute function. Can be a boolean (true) or enum */
+  outcome: ValidatorOutcome;
+  config: ValidatorConfig;
+  params: ValidatorParam;
+};

package/components/form-integrations/test/dialog-integrations.test.js

@@ -0,0 +1,73 @@
+import { expect, fixture } from '@open-wc/testing';
+import { html } from 'lit';
+import { getAllTagNames } from './helpers/helpers.js';
+import './helpers/umbrella-form.js';
+import '@lion/ui/define/lion-dialog.js';
+import '@lion/ui/define/lion-checkbox.js';
+import '@lion/ui/define/lion-option.js';
+import '@lion/ui/define/lion-radio.js';
+
+/**
+ * @typedef {import('./helpers/umbrella-form.js').UmbrellaForm} UmbrellaForm
+ * @typedef {import('../../dialog/src/LionDialog.js').LionDialog} LionDialog
+ * @typedef {import('../../form/src/LionForm.js').LionForm} LionForm
+ */
+
+// Test umbrella form inside dialog
+describe('Form inside dialog Integrations', () => {
+  it('Successfully registers all form components inside a dialog', async () => {
+    const el = /** @type {LionDialog} */ await fixture(html` <lion-dialog>
+      <button slot="invoker">Open Dialog</button>
+      <umbrella-form slot="content"></umbrella-form>
+    </lion-dialog>`);
+
+    // @ts-ignore
+    const formEl = /** @type {LionForm} */ (el._overlayCtrl.contentNode._lionFormNode);
+    await formEl.registrationComplete;
+    const registeredEls = getAllTagNames(formEl);
+
+    expect(registeredEls).to.eql([
+      'lion-fieldset',
+      '  lion-input',
+      '  lion-input',
+      'lion-input-date',
+      'lion-input-datepicker',
+      'lion-textarea',
+      'lion-input-amount',
+      'lion-input-iban',
+      'lion-input-email',
+      'lion-input-tel',
+      'lion-input-tel-dropdown',
+      'lion-checkbox-group',
+      '  lion-checkbox',
+      '  lion-checkbox',
+      '  lion-checkbox',
+      'lion-radio-group',
+      '  lion-radio',
+      '  lion-radio',
+      '  lion-radio',
+      'lion-listbox',
+      '  lion-option',
+      '  lion-option',
+      '  lion-option',
+      'lion-combobox',
+      '  lion-option',
+      '  lion-option',
+      '  lion-option',
+      '  lion-option',
+      '  lion-option',
+      '  lion-option',
+      'lion-select-rich',
+      '  lion-option',
+      '  lion-option',
+      '  lion-option',
+      'lion-select',
+      'lion-input-range',
+      'lion-checkbox-group',
+      '  lion-checkbox',
+      'lion-switch',
+      'lion-input-stepper',
+      'lion-textarea',
+    ]);
+  });
+});

package/components/form-integrations/test/form-group-methods.test.js

@@ -0,0 +1,203 @@
+import { elementUpdated, expect, fixture } from '@open-wc/testing';
+import { html } from 'lit';
+import './helpers/umbrella-form.js';
+import { getAllFieldsAndFormGroups } from './helpers/helpers.js';
+
+import '@lion/ui/define/lion-button.js';
+import '@lion/ui/define/lion-button-submit.js';
+import '@lion/ui/define/lion-button-reset.js';
+
+import '@lion/ui/define/lion-checkbox.js';
+import '@lion/ui/define/lion-checkbox-group.js';
+import '@lion/ui/define/lion-combobox.js';
+
+import '@lion/ui/define/lion-dialog.js';
+
+import '@lion/ui/define/lion-form.js';
+import '@lion/ui/define/lion-fieldset.js';
+import '@lion/ui/define/lion-select-rich.js';
+import '@lion/ui/define/lion-select.js';
+
+import '@lion/ui/define/lion-input-stepper.js';
+import '@lion/ui/define/lion-input-range.js';
+import '@lion/ui/define/lion-input-amount.js';
+import '@lion/ui/define/lion-input.js';
+import '@lion/ui/define/lion-input-date.js';
+import '@lion/ui/define/lion-input-iban.js';
+import '@lion/ui/define/lion-input-email.js';
+import '@lion/ui/define/lion-input-tel-dropdown.js';
+import '@lion/ui/define/lion-input-datepicker.js';
+
+import '@lion/ui/define/lion-textarea.js';
+
+import '@lion/ui/define/lion-radio.js';
+import '@lion/ui/define/lion-radio-group.js';
+
+import '@lion/ui/define/lion-listbox.js';
+import '@lion/ui/define/lion-option.js';
+import '@lion/ui/define/lion-options.js';
+
+import '@lion/ui/define/lion-validation-feedback.js';
+/**
+ * @typedef {import('../../form-core/src/LionField.js').LionField} LionField
+ * @typedef {import('../../button/src/LionButton.js').LionButton} LionButton
+ * @typedef {import('./helpers/umbrella-form.js').UmbrellaForm} UmbrellaForm
+ */
+
+const fullyPrefilledSerializedValue = {
+  full_name: { first_name: 'Lorem', last_name: 'Ipsum' },
+  date: '2000-12-12',
+  datepicker: '2020-12-12',
+  bio: 'Lorem',
+  money: '12313.12',
+  iban: '123456',
+  email: 'a@b.com',
+  checkers: ['foo', 'bar'],
+  dinosaurs: 'brontosaurus',
+  favoriteFruit: 'Banana',
+  favoriteMovie: 'Rocky',
+  favoriteColor: 'hotpink',
+  lyrics: '1',
+  notifications: {
+    checked: true,
+    value: 'Lorem',
+  },
+  range: 2.3,
+  rsvp: 'Lorem',
+  terms: ['agreed'],
+  comments: 'Lorem',
+};
+
+const fullyChangedSerializedValue = {
+  full_name: { first_name: 'LoremChanged', last_name: 'IpsumChanged' },
+  date: '1999-12-12',
+  datepicker: '1986-12-12',
+  bio: 'LoremChanged',
+  money: '9912313.12',
+  iban: '99123456',
+  email: 'aChanged@b.com',
+  checkers: ['foo'],
+  dinosaurs: '',
+  favoriteFruit: '',
+  favoriteMovie: '',
+  favoriteColor: '',
+  lyrics: '2',
+  notifications: {
+    checked: false,
+    value: 'Lorem',
+  },
+  range: 3.3,
+  rsvp: 'LoremChanged',
+  terms: [],
+  comments: 'LoremChanged',
+};
+
+describe(`Submitting/Resetting/Clearing Form`, async () => {
+  it('pressing submit button of a form should make submitted true for all fields', async () => {
+    const el = /** @type {UmbrellaForm} */ (await fixture(html`<umbrella-form></umbrella-form>`));
+    await el.updateComplete;
+    const formEl = el._lionFormNode;
+
+    const allElements = getAllFieldsAndFormGroups(formEl);
+
+    allElements.forEach((/** @type {LionField} */ field) => {
+      if (field.tagName === 'LION-SWITCH') {
+        // TODO: remove this when this is fixed: https://github.com/ing-bank/lion/issues/1204
+        return;
+      }
+      // TODO: prefer submitted 'false' over 'undefined'
+      expect(Boolean(field.submitted)).to.be.false;
+    });
+    /** @type {LionButton} */ (formEl.querySelector('#submit_button')).click();
+    await elementUpdated(formEl);
+    await el.updateComplete;
+    allElements.forEach((/** @type {LionField} */ field) => {
+      expect(field.submitted).to.be.true;
+    });
+  });
+
+  it('calling resetGroup() should reset all metadata (interaction states and initial values)', async () => {
+    const el = /** @type {UmbrellaForm} */ (
+      await fixture(
+        html`<umbrella-form .serializedValue="${fullyPrefilledSerializedValue}"></umbrella-form>`,
+      )
+    );
+    await el.updateComplete;
+    const formEl = el._lionFormNode;
+
+    /** @type {LionButton} */ (formEl.querySelector('#submit_button')).click();
+    await elementUpdated(formEl);
+    await formEl.updateComplete;
+
+    const allElements = getAllFieldsAndFormGroups(formEl);
+
+    allElements.forEach((/** @type {LionField} */ field) => {
+      // eslint-disable-next-line no-param-reassign
+      field.touched = true;
+      // eslint-disable-next-line no-param-reassign
+      field.dirty = true;
+    });
+
+    formEl.serializedValue = fullyChangedSerializedValue;
+
+    allElements.forEach((/** @type {LionField} */ field) => {
+      expect(field.submitted).to.be.true;
+      expect(field.touched).to.be.true;
+      expect(field.dirty).to.be.true;
+    });
+
+    /** @type {LionButton} */ (formEl.querySelector('#reset_button')).click();
+    await elementUpdated(formEl);
+    await formEl.updateComplete;
+    expect(formEl.submitted).to.be.false;
+
+    allElements.forEach((/** @type {LionField} */ field) => {
+      expect(field.submitted).to.be.false;
+      expect(field.touched).to.be.false;
+      expect(field.dirty).to.be.false;
+    });
+
+    // TODO: investigate why this doesn't work
+    // expect(formEl.serializedValue).to.eql(fullyPrefilledSerializedValue);
+  });
+
+  // Wait till ListboxMixin properly clears
+  it('calling clearGroup() should clear all fields', async () => {
+    const el = /** @type {UmbrellaForm} */ (
+      await fixture(
+        html`<umbrella-form .serializedValue="${fullyPrefilledSerializedValue}"></umbrella-form>`,
+      )
+    );
+    await el.updateComplete;
+    const formEl = el._lionFormNode;
+
+    formEl.clearGroup();
+    await elementUpdated(formEl);
+    await formEl.updateComplete;
+    expect(formEl.serializedValue).to.eql({
+      full_name: { first_name: '', last_name: '' },
+      date: '',
+      datepicker: '',
+      bio: '',
+      money: '',
+      iban: '',
+      email: '',
+      checkers: [],
+      dinosaurs: '',
+      favoriteFruit: '',
+      favoriteMovie: '',
+      favoriteColor: '',
+      lyrics: '',
+      notifications: {
+        checked: false,
+        value: 'Lorem',
+      },
+      range: '',
+      rsvp: '',
+      tel: '',
+      'tel-dropdown': '',
+      terms: [],
+      comments: '',
+    });
+  });
+});