@lion/ui 0.0.1

package/components/form-core/src/registration/FormRegisteringMixin.js

@@ -0,0 +1,59 @@
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+
+/**
+ * @typedef {import('lit').LitElement} LitElement
+ * @typedef {import('../../types/FormControlMixinTypes.js').FormControlHost} FormControlHost
+ * @typedef {import('../../types/registration/FormRegisteringMixinTypes.js').FormRegisteringMixin} FormRegisteringMixin
+ * @typedef {import('../../types/registration/FormRegisteringMixinTypes.js').FormRegisteringHost} FormRegisteringHost
+ * @typedef {import('../../types/registration/FormRegistrarMixinTypes.js').ElementWithParentFormGroup} ElementWithParentFormGroup
+ * @typedef {import('../../types/registration/FormRegistrarMixinTypes.js').FormRegistrarHost} FormRegistrarHost
+ */
+
+/**
+ * #FormRegisteringMixin:
+ *
+ * This Mixin registers a form element to a Registrar
+ *
+ * @type {FormRegisteringMixin}
+ * @param {import('@open-wc/dedupe-mixin').Constructor<LitElement>} superclass
+ */
+const FormRegisteringMixinImplementation = superclass =>
+  // @ts-ignore https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051
+  class extends superclass {
+    constructor() {
+      super();
+      /**
+       * The registrar this FormControl registers to, Usually a descendant of FormGroup or
+       * ChoiceGroup
+       * @type {FormRegistrarHost | undefined}
+       */
+      this._parentFormGroup = undefined;
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+      this.dispatchEvent(
+        new CustomEvent('form-element-register', {
+          detail: { element: this },
+          bubbles: true,
+        }),
+      );
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      this.__unregisterFormElement();
+    }
+
+    /**
+     * Putting this in a separate method makes testing easier
+     * @private
+     */
+    __unregisterFormElement() {
+      if (this._parentFormGroup) {
+        this._parentFormGroup.removeFormElement(/** @type {* & FormRegisteringHost} */ (this));
+      }
+    }
+  };
+
+export const FormRegisteringMixin = dedupeMixin(FormRegisteringMixinImplementation);

package/components/form-core/src/registration/FormRegistrarMixin.js

@@ -0,0 +1,277 @@
+// eslint-disable-next-line max-classes-per-file
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { FormControlsCollection } from './FormControlsCollection.js';
+import { FormRegisteringMixin } from './FormRegisteringMixin.js';
+
+/**
+ * @typedef {import('../../types/FormControlMixinTypes.js').FormControlHost} FormControlHost
+ * @typedef {import('../../types/registration/FormRegistrarMixinTypes.js').FormRegistrarMixin} FormRegistrarMixin
+ * @typedef {import('../../types/registration/FormRegistrarMixinTypes.js').FormRegistrarHost} FormRegistrarHost
+ * @typedef {import('../../types/registration/FormRegistrarMixinTypes.js').ElementWithParentFormGroup} ElementWithParentFormGroup
+ * @typedef {import('../../types/registration/FormRegisteringMixinTypes.js').FormRegisteringHost} FormRegisteringHost
+ * @typedef {FormControlHost & HTMLElement & {_parentFormGroup?:HTMLElement, checked?:boolean}} FormControl
+ */
+
+/**
+ * @desc This allows an element to become the manager of a register.
+ * It basically keeps track of a FormControlsCollection that it stores in .formElements
+ * This will always be an array of all elements.
+ * In case of a form or fieldset(sub form), it will also act as a key based object with FormControl
+ * (fields, choice groups or fieldsets)as keys.
+ * For choice groups, the value will only stay an array.
+ * See FormControlsCollection for more information
+ * @type {FormRegistrarMixin}
+ * @param {import('@open-wc/dedupe-mixin').Constructor<import('lit').LitElement>} superclass
+ */
+const FormRegistrarMixinImplementation = superclass =>
+  // eslint-disable-next-line no-shadow, no-unused-vars
+  // @ts-ignore https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051
+  class extends FormRegisteringMixin(superclass) {
+    /** @type {any} */
+    static get properties() {
+      return {
+        _isFormOrFieldset: { type: Boolean },
+      };
+    }
+
+    constructor() {
+      super();
+
+      /**
+       * Closely mimics the natively supported HTMLFormControlsCollection. It can be accessed
+       * both like an array and an object (based on control/element names).
+       * @type {FormControlsCollection}
+       */
+      this.formElements = new FormControlsCollection();
+
+      /**
+       * Flag that determines how ".formElements" should behave.
+       * For a regular fieldset (see LionFieldset) we expect ".formElements"
+       * to be accessible as an object.
+       * In case of a radio-group, a checkbox-group or a select/listbox,
+       * it should act like an array (see ChoiceGroupMixin).
+       * Usually, when false, we deal with a choice-group (radio-group, checkbox-group,
+       * (multi)select)
+       * @type {boolean}
+       * @protected
+       */
+      this._isFormOrFieldset = false;
+
+      this._onRequestToAddFormElement = this._onRequestToAddFormElement.bind(this);
+      this._onRequestToChangeFormElementName = this._onRequestToChangeFormElementName.bind(this);
+
+      this.addEventListener(
+        'form-element-register',
+        /** @type {EventListenerOrEventListenerObject} */ (this._onRequestToAddFormElement),
+      );
+      this.addEventListener(
+        'form-element-name-changed',
+        /** @type {EventListenerOrEventListenerObject} */ (this._onRequestToChangeFormElementName),
+      );
+
+      /**
+       * initComplete resolves after all pending initialization logic
+       * (for instance `<form-group .serializedValue=${{ child1: 'a', child2: 'b' }}>`)
+       * is executed
+       * @type {Promise<any>}
+       */
+      this.initComplete = new Promise((resolve, reject) => {
+        this.__resolveInitComplete = resolve;
+        this.__rejectInitComplete = reject;
+      });
+
+      /**
+       * registrationComplete waits for all children formElements to have registered
+       * @type {Promise<any> & {done?:boolean}}
+       */
+      this.registrationComplete = new Promise((resolve, reject) => {
+        this.__resolveRegistrationComplete = resolve;
+        this.__rejectRegistrationComplete = reject;
+      });
+      this.registrationComplete.done = false;
+      this.registrationComplete.then(
+        () => {
+          this.registrationComplete.done = true;
+          this.__resolveInitComplete(undefined);
+        },
+        () => {
+          this.registrationComplete.done = true;
+          this.__rejectInitComplete(undefined);
+          throw new Error(
+            'Registration could not finish. Please use await el.registrationComplete;',
+          );
+        },
+      );
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+      this._completeRegistration();
+    }
+
+    /**
+     * Resolves the registrationComplete promise. Subclassers can delay if needed
+     * @overridable
+     */
+    _completeRegistration() {
+      Promise.resolve().then(() => this.__resolveRegistrationComplete(undefined));
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      if (this.registrationComplete.done === false) {
+        Promise.resolve().then(() => {
+          Promise.resolve().then(() => {
+            this.__rejectRegistrationComplete();
+          });
+        });
+      }
+    }
+
+    /**
+     *
+     * @param {ElementWithParentFormGroup} el
+     */
+    isRegisteredFormElement(el) {
+      return this.formElements.some(exitingEl => exitingEl === el);
+    }
+
+    /**
+     * @param {FormControl} child the child element (field)
+     * @param {number} indexToInsertAt index to insert the form element at
+     */
+    addFormElement(child, indexToInsertAt) {
+      // This is a way to let the child element (a lion-fieldset or lion-field) know, about its parent
+      // eslint-disable-next-line no-param-reassign
+      child._parentFormGroup = /** @type {* & FormRegistrarHost} */ (this);
+
+      // 1. Add children as array element
+      if (indexToInsertAt >= 0) {
+        this.formElements.splice(indexToInsertAt, 0, child);
+      } else {
+        this.formElements.push(child);
+      }
+
+      // 2. Add children as object key
+      if (this._isFormOrFieldset) {
+        const { name } = child;
+        if (name === this.name) {
+          console.info('Error Node:', child); // eslint-disable-line no-console
+          throw new TypeError(`You can not have the same name "${name}" as your parent`);
+        }
+
+        if (name.substr(-2) === '[]') {
+          if (!Array.isArray(this.formElements[name])) {
+            this.formElements[name] = new FormControlsCollection();
+          }
+          if (indexToInsertAt > 0) {
+            this.formElements[name].splice(indexToInsertAt, 0, child);
+          } else {
+            this.formElements[name].push(child);
+          }
+        } else if (!this.formElements[name]) {
+          this.formElements[name] = child;
+        } else {
+          console.info('Error Node:', child); // eslint-disable-line no-console
+          throw new TypeError(
+            `Name "${name}" is already registered - if you want an array add [] to the end`,
+          );
+        }
+      }
+    }
+
+    /**
+     * @param {FormControlHost} child the child element (field)
+     */
+    removeFormElement(child) {
+      // 1. Handle array based children
+      const index = this.formElements.indexOf(child);
+      if (index > -1) {
+        this.formElements.splice(index, 1);
+      }
+
+      // 2. Handle name based object keys
+      if (this._isFormOrFieldset) {
+        const { name } = child; // FIXME: <-- ElementWithParentFormGroup should become LionFieldWithParentFormGroup so that "name" exists
+        if (name.substr(-2) === '[]' && this.formElements[name]) {
+          const idx = this.formElements[name].indexOf(child);
+          if (idx > -1) {
+            this.formElements[name].splice(idx, 1);
+          }
+        } else if (this.formElements[name]) {
+          delete this.formElements[name];
+        }
+      }
+    }
+
+    /**
+     * Hook for Subclassers to perform logic before an element is added
+     * @param {CustomEvent} ev
+     * @protected
+     */
+    _onRequestToAddFormElement(ev) {
+      const child = ev.detail.element;
+      if (child === this) {
+        // as we fire and listen - don't add ourselves
+        return;
+      }
+      if (this.isRegisteredFormElement(child)) {
+        // do not readd already existing elements
+        return;
+      }
+      ev.stopPropagation();
+
+      // Check for DOM order to determine the right order to insert into formElements
+      // If there is no other element, index is -1 (e.g. add it to the end)
+      let indexToInsertAt = -1;
+      if (this.formElements && Array.isArray(this.formElements)) {
+        // we start comparing from the end of the array as it's the most likely position where the element will be added
+        for (const [i, formElement] of this.formElements.entries()) {
+          // compareDocumentPosition returns a bitmask
+          // eslint-disable-next-line no-bitwise
+          if (formElement.compareDocumentPosition(child) & Node.DOCUMENT_POSITION_FOLLOWING) {
+            // nothing as child is after formElement in DOM
+          } else {
+            // first time child is NOT after formElement in DOM we insert it
+            indexToInsertAt = i;
+            break;
+          }
+        }
+      }
+      this.addFormElement(child, indexToInsertAt);
+    }
+
+    /**
+     * @param {CustomEvent} ev
+     * @protected
+     */
+    _onRequestToChangeFormElementName(ev) {
+      const element = this.formElements[ev.detail.oldName];
+      if (element) {
+        this.formElements[ev.detail.newName] = element;
+        delete this.formElements[ev.detail.oldName];
+      }
+    }
+
+    /**
+     * @param {CustomEvent} ev
+     * @protected
+     */
+    _onRequestToRemoveFormElement(ev) {
+      const child = ev.detail.element;
+      if (child === this) {
+        // as we fire and listen - don't remove ourselves
+        return;
+      }
+      if (!this.isRegisteredFormElement(child)) {
+        // do not remove non existing elements
+        return;
+      }
+      ev.stopPropagation();
+
+      this.removeFormElement(child);
+    }
+  };
+
+export const FormRegistrarMixin = dedupeMixin(FormRegistrarMixinImplementation);

package/components/form-core/src/registration/FormRegistrarPortalMixin.js

@@ -0,0 +1,63 @@
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+
+/**
+ * @typedef {import('../../types/registration/FormRegistrarPortalMixinTypes.js').FormRegistrarPortalMixin} FormRegistrarPortalMixin
+ * @typedef {import('../../types/registration/FormRegistrarPortalMixinTypes.js').FormRegistrarPortalHost} FormRegistrarPortalHost
+ */
+
+/**
+ * This allows to register fields within a form even though they are not within the same dom tree.
+ * It does that by redispatching the event on the registration target.
+ * Neither form or field need to know about the portal. It acts as if the field is part of the dom tree.
+ *
+ * @example
+ * <my-form></my-form>
+ * <my-portal .registrationTarget=${document.querySelector('my-form')}>
+ *   <my-field></my-field>
+ * </my-portal>
+ * // my-field will be registered within my-form
+ * @type {FormRegistrarPortalMixin}
+ * @param {import('@open-wc/dedupe-mixin').Constructor<HTMLElement>} superclass
+ */
+const FormRegistrarPortalMixinImplementation = superclass =>
+  // eslint-disable-next-line no-shadow, no-unused-vars
+  // @ts-ignore https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051
+  class extends superclass {
+    constructor() {
+      super();
+
+      /**
+       * Registration target: an element, usually in the body of the dom, that captures events
+       * and redispatches them on host
+       * @type {(FormRegistrarPortalHost & HTMLElement) | undefined}
+       */
+      this.registrationTarget = undefined;
+      this.__redispatchEventForFormRegistrarPortalMixin =
+        this.__redispatchEventForFormRegistrarPortalMixin.bind(this);
+      this.addEventListener(
+        'form-element-register',
+        /** @type {EventListenerOrEventListenerObject} */ (
+          this.__redispatchEventForFormRegistrarPortalMixin
+        ),
+      );
+    }
+
+    /**
+     * @param {CustomEvent} ev
+     * @private
+     */
+    __redispatchEventForFormRegistrarPortalMixin(ev) {
+      ev.stopPropagation();
+      if (!this.registrationTarget) {
+        throw new Error('A FormRegistrarPortal element requires a .registrationTarget');
+      }
+      this.registrationTarget.dispatchEvent(
+        new CustomEvent('form-element-register', {
+          detail: { element: ev.detail.element },
+          bubbles: true,
+        }),
+      );
+    }
+  };
+
+export const FormRegistrarPortalMixin = dedupeMixin(FormRegistrarPortalMixinImplementation);

package/components/form-core/src/utils/AsyncQueue.js

@@ -0,0 +1,46 @@
+// TODO: still needed? It can be solved with while loop as well
+
+/**
+ * Use the `.add` method to add async functions to the queue
+ * Await the `.complete` if you want to ensure the queue is empty at any point
+ * `complete` resolves whenever no more tasks are running.
+ * Important note: Currently runs tasks 1 by 1, there is no concurrency option at the moment
+ */
+export class AsyncQueue {
+  constructor() {
+    this.__running = false;
+    /** @type {function[]} */
+    this.__queue = [];
+  }
+
+  /**
+   *
+   * @param {function} task
+   */
+  add(task) {
+    this.__queue.push(task);
+    if (!this.__running) {
+      // We have a new queue, because before there was nothing in the queue
+      this.complete = new Promise(resolve => {
+        /** @type {function} */
+        this.__callComplete = resolve;
+      });
+      this.__run();
+    }
+  }
+
+  /** @private */
+  async __run() {
+    this.__running = true;
+    await this.__queue[0]();
+    this.__queue.shift();
+    if (this.__queue.length > 0) {
+      this.__run();
+    } else {
+      this.__running = false;
+      if (this.__callComplete) {
+        this.__callComplete();
+      }
+    }
+  }
+}

package/components/form-core/src/utils/SyncUpdatableMixin.js

@@ -0,0 +1,137 @@
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+
+// TODO: will be moved to @Lion/core later?
+
+/**
+ * @typedef {import('../../types/utils/SyncUpdatableMixinTypes.js').SyncUpdatableMixin} SyncUpdatableMixin
+ * @typedef {import('../../types/utils/SyncUpdatableMixinTypes.js').SyncUpdatableNamespace} SyncUpdatableNamespace
+ */
+
+/**
+ * Why this mixin?
+ * - it adheres to the "Member Order Independence" web components standard:
+ * https://github.com/webcomponents/gold-standard/wiki/Member-Order-Independence
+ * - sync observers can be dependent on the outcome of the render function (or, more generically
+ * speaking, the light and shadow dom). This aligns with the 'updated' callback that is supported
+ * out of the box by LitElement, which runs after connectedCallback as well.
+ * - makes the propertyAccessor.`hasChanged` compatible in synchronous updates:
+ * `updateSync` will only be called when new value differs from old value.
+ * See: https://lit-element.polymer-project.org/guide/lifecycle#haschanged
+ * - it is a stable abstraction on top of a protected/non official lifecycle LitElement api.
+ * Whenever the implementation of `requestUpdate` changes (this happened in the past for
+ * `requestUpdate`) we only have to change our abstraction instead of all our components
+ * @type {SyncUpdatableMixin}
+ * @param {import('@open-wc/dedupe-mixin').Constructor<import('lit').LitElement>} superclass
+ */
+const SyncUpdatableMixinImplementation = superclass =>
+  // @ts-ignore https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051
+  class extends superclass {
+    constructor() {
+      super();
+
+      /**
+       * Namespace for this mixin that guarantees naming clashes will not occur...
+       * @type {SyncUpdatableNamespace}
+       */
+      this.__SyncUpdatableNamespace = {};
+    }
+
+    /**
+     * Empty pending queue in order to guarantee order independence
+     *
+     * @param {import('lit-element').PropertyValues } changedProperties
+     */
+    firstUpdated(changedProperties) {
+      super.firstUpdated(changedProperties);
+      this.__syncUpdatableInitialize();
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+      this.__SyncUpdatableNamespace.connected = true;
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      this.__SyncUpdatableNamespace.connected = false;
+    }
+
+    /**
+     * Makes the propertyAccessor.`hasChanged` compatible in synchronous updates
+     * @param {string} name
+     * @param {*} newValue
+     * @param {*} oldValue
+     * @private
+     */
+    static __syncUpdatableHasChanged(name, newValue, oldValue) {
+      // @ts-expect-error [external]: accessing private lit property
+      const properties = this.elementProperties;
+      if (properties.get(name) && properties.get(name).hasChanged) {
+        return properties.get(name).hasChanged(newValue, oldValue);
+      }
+      return newValue !== oldValue;
+    }
+
+    /** @private */
+    __syncUpdatableInitialize() {
+      const ns = this.__SyncUpdatableNamespace;
+      const ctor =
+        /** @type {typeof SyncUpdatableMixin & typeof import('../../types/utils/SyncUpdatableMixinTypes.js').SyncUpdatableHost} */ (
+          this.constructor
+        );
+
+      ns.initialized = true;
+      // Empty queue...
+      if (ns.queue) {
+        Array.from(ns.queue).forEach(name => {
+          // @ts-ignore [allow-private] in test
+          if (ctor.__syncUpdatableHasChanged(name, this[name], undefined)) {
+            this.updateSync(name, undefined);
+          }
+        });
+      }
+    }
+
+    /**
+     * @param {string} name
+     * @param {*} oldValue
+     */
+    requestUpdate(name, oldValue) {
+      super.requestUpdate(name, oldValue);
+
+      this.__SyncUpdatableNamespace = this.__SyncUpdatableNamespace || {};
+      const ns = this.__SyncUpdatableNamespace;
+
+      const ctor =
+        /** @type {typeof SyncUpdatableMixin & typeof import('../../types/utils/SyncUpdatableMixinTypes.js').SyncUpdatableHost} */ (
+          this.constructor
+        );
+      // Before connectedCallback: queue
+      if (!ns.initialized) {
+        ns.queue = ns.queue || new Set();
+        // Makes sure that we only initialize one time, with most up to date value
+        ns.queue.add(name);
+      } // After connectedCallback: guarded proxy to updateSync
+      // @ts-ignore [allow-private] in test
+      else if (ctor.__syncUpdatableHasChanged(name, this[name], oldValue)) {
+        this.updateSync(name, oldValue);
+      }
+    }
+
+    /**
+     * An abstraction that has the exact same api as `requestUpdate`, but taking
+     * into account:
+     * - [member order independence](https://github.com/webcomponents/gold-standard/wiki/Member-Order-Independence)
+     * - property effects start when all (light) dom has initialized (on firstUpdated)
+     * - property effects don't interrupt the first meaningful paint
+     * - compatible with propertyAccessor.`hasChanged`: no manual checks needed or accidentally
+     * run property effects / events when no change happened
+     * effects when values didn't change
+     * All code previously present in requestUpdate can be placed in this method.
+     * @param {string} name
+     * @param {*} oldValue
+     */
+    updateSync(name, oldValue) {} // eslint-disable-line class-methods-use-this, no-unused-vars
+  };
+
+export const SyncUpdatableMixin = dedupeMixin(SyncUpdatableMixinImplementation);

package/components/form-core/src/utils/getAriaElementsInRightDomOrder.js

@@ -0,0 +1,43 @@
+/* eslint-disable no-bitwise */
+import { browserDetection } from '@lion/ui/core.js';
+
+const moveDownConditions = [
+  Node.DOCUMENT_POSITION_PRECEDING,
+  Node.DOCUMENT_POSITION_CONTAINS,
+  Node.DOCUMENT_POSITION_CONTAINS | Node.DOCUMENT_POSITION_PRECEDING,
+];
+
+/**
+ * @desc Let the order of adding ids to aria element by DOM order, so that the screen reader
+ * respects visual order when reading:
+ * https://developers.google.com/web/fundamentals/accessibility/focus/dom-order-matters
+ * @param {HTMLElement[]} descriptionElements - holds references to description or label elements whose
+ * id should be returned
+ * @param {Object} opts
+ * @param {boolean} [opts.reverse]
+ * @returns {HTMLElement[]} sorted set of elements based on dom order
+ */
+export function getAriaElementsInRightDomOrder(descriptionElements, { reverse } = {}) {
+  /**
+   * @param {HTMLElement} a
+   * @param {HTMLElement} b
+   * @return {-1|1}
+   */
+  const putPrecedingSiblingsAndLocalParentsFirst = (a, b) => {
+    // https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition
+    const pos = a.compareDocumentPosition(b);
+
+    // Unfortunately, for IE, we have to switch the order (?)
+    if (moveDownConditions.includes(pos)) {
+      return browserDetection.isIE11 ? -1 : 1;
+    }
+    return browserDetection.isIE11 ? 1 : -1;
+  };
+
+  const descriptionEls = descriptionElements.filter(el => el); // filter out null references
+  descriptionEls.sort(putPrecedingSiblingsAndLocalParentsFirst);
+  if (reverse) {
+    descriptionEls.reverse();
+  }
+  return descriptionEls;
+}

package/components/form-core/src/utils/pascalCase.js

@@ -0,0 +1,9 @@
+/**
+ * Return PascalCased version of the camelCased string
+ *
+ * @param {string} str
+ * @return {string}
+ */
+export function pascalCase(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}