@vaadin/field-base 22.0.0-alpha1 → 22.0.0-alpha10

package/src/delegate-state-mixin.js

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { dedupingMixin } from '@polymer/polymer/lib/utils/mixin.js';
+
+/**
+ * A mixin to delegate properties and attributes to a target element.
+ *
+ * @polymerMixin
+ */
+export const DelegateStateMixin = dedupingMixin(
+  (superclass) =>
+    class DelegateStateMixinClass extends superclass {
+      static get properties() {
+        return {
+          /**
+           * A target element to which attributes and properties are delegated.
+           * @protected
+           */
+          stateTarget: {
+            type: Object,
+            observer: '_stateTargetChanged'
+          }
+        };
+      }
+
+      /**
+       * An array of the host attributes to delegate to the target element.
+       */
+      static get delegateAttrs() {
+        return [];
+      }
+
+      /**
+       * An array of the host properties to delegate to the target element.
+       */
+      static get delegateProps() {
+        return [];
+      }
+
+      /** @protected */
+      ready() {
+        super.ready();
+
+        this._createDelegateAttrsObserver();
+        this._createDelegatePropsObserver();
+      }
+
+      /** @protected */
+      _stateTargetChanged(target) {
+        if (target) {
+          this._ensureAttrsDelegated();
+          this._ensurePropsDelegated();
+        }
+      }
+
+      /** @protected */
+      _createDelegateAttrsObserver() {
+        this._createMethodObserver(`_delegateAttrsChanged(${this.constructor.delegateAttrs.join(', ')})`);
+      }
+
+      /** @protected */
+      _createDelegatePropsObserver() {
+        this._createMethodObserver(`_delegatePropsChanged(${this.constructor.delegateProps.join(', ')})`);
+      }
+
+      /** @protected */
+      _ensureAttrsDelegated() {
+        this.constructor.delegateAttrs.forEach((name) => {
+          this._delegateAttribute(name, this[name]);
+        });
+      }
+
+      /** @protected */
+      _ensurePropsDelegated() {
+        this.constructor.delegateProps.forEach((name) => {
+          this._delegateProperty(name, this[name]);
+        });
+      }
+
+      /** @protected */
+      _delegateAttrsChanged(...values) {
+        this.constructor.delegateAttrs.forEach((name, index) => {
+          this._delegateAttribute(name, values[index]);
+        });
+      }
+
+      /** @protected */
+      _delegatePropsChanged(...values) {
+        this.constructor.delegateProps.forEach((name, index) => {
+          this._delegateProperty(name, values[index]);
+        });
+      }
+
+      /** @protected */
+      _delegateAttribute(name, value) {
+        if (!this.stateTarget) {
+          return;
+        }
+
+        if (name === 'invalid') {
+          this._delegateAttribute('aria-invalid', value ? 'true' : false);
+        }
+
+        if (typeof value === 'boolean') {
+          this.stateTarget.toggleAttribute(name, value);
+        } else if (value) {
+          this.stateTarget.setAttribute(name, value);
+        } else {
+          this.stateTarget.removeAttribute(name);
+        }
+      }
+
+      /** @protected */
+      _delegateProperty(name, value) {
+        if (!this.stateTarget) {
+          return;
+        }
+
+        this.stateTarget[name] = value;
+      }
+    }
+);

package/src/field-mixin.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { LabelMixin } from './label-mixin.js';
+import { ValidateMixin } from './validate-mixin.js';
+
+/**
+ * A mixin to provide common field logic: label, error message and helper text.
+ */
+declare function FieldMixin<T extends new (...args: any[]) => {}>(base: T): T & FieldMixinConstructor;
+
+interface FieldMixinConstructor {
+  new (...args: any[]): FieldMixin;
+}
+
+interface FieldMixin extends LabelMixin, ValidateMixin {
+  /**
+   * A target element to which ARIA attributes are set.
+   */
+  ariaTarget: HTMLElement;
+
+  /**
+   * String used for the helper text.
+   *
+   * @attr {string} helper-text
+   */
+  helperText: string | null | undefined;
+
+  /**
+   * Error to show when the field is invalid.
+   *
+   * @attr {string} error-message
+   */
+  errorMessage: string;
+}
+
+export { FieldMixin, FieldMixinConstructor };

package/src/field-mixin.js

@@ -0,0 +1,317 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
+import { Debouncer } from '@vaadin/component-base/src/debounce.js';
+import { animationFrame } from '@vaadin/component-base/src/async.js';
+import { LabelMixin } from './label-mixin.js';
+import { ValidateMixin } from './validate-mixin.js';
+
+/**
+ * A mixin to provide common field logic: label, error message and helper text.
+ *
+ * @polymerMixin
+ * @mixes LabelMixin
+ * @mixes ValidateMixin
+ */
+export const FieldMixin = (superclass) =>
+  class FieldMixinClass extends ValidateMixin(LabelMixin(superclass)) {
+    static get properties() {
+      return {
+        /**
+         * A target element to which ARIA attributes are set.
+         * @protected
+         */
+        ariaTarget: {
+          type: Object,
+          observer: '_ariaTargetChanged'
+        },
+
+        /**
+         * Error to show when the field is invalid.
+         *
+         * @attr {string} error-message
+         */
+        errorMessage: {
+          type: String
+        },
+
+        /**
+         * String used for the helper text.
+         * @attr {string} helper-text
+         */
+        helperText: {
+          type: String,
+          observer: '_helperTextChanged'
+        },
+
+        /** @protected */
+        _helperId: String
+      };
+    }
+
+    /** @protected */
+    get slots() {
+      return {
+        ...super.slots,
+        'error-message': () => {
+          const error = document.createElement('div');
+          error.textContent = this.errorMessage;
+          error.setAttribute('aria-live', 'assertive');
+          return error;
+        }
+      };
+    }
+
+    static get observers() {
+      return [
+        '__ariaChanged(invalid, _helperId)',
+        '__observeOffsetHeight(errorMessage, invalid, label, helperText)',
+        '_updateErrorMessage(invalid, errorMessage)'
+      ];
+    }
+
+    /** @protected */
+    get _errorNode() {
+      return this._getDirectSlotChild('error-message');
+    }
+
+    /** @protected */
+    get _helperNode() {
+      return this._getDirectSlotChild('helper');
+    }
+
+    /** @protected */
+    get _ariaAttr() {
+      return 'aria-describedby';
+    }
+
+    constructor() {
+      super();
+
+      // Ensure every instance has unique ID
+      const uniqueId = (FieldMixinClass._uniqueFieldId = 1 + FieldMixinClass._uniqueFieldId || 0);
+      this._errorId = `error-${this.localName}-${uniqueId}`;
+      this._helperId = `helper-${this.localName}-${uniqueId}`;
+
+      // Save generated ID to restore later
+      this.__savedHelperId = this._helperId;
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+
+      const error = this._errorNode;
+      if (error) {
+        error.id = this._errorId;
+
+        this.__applyCustomError();
+
+        this._updateErrorMessage(this.invalid, this.errorMessage);
+      }
+
+      const helper = this._helperNode;
+      if (helper) {
+        this.__applyCustomHelper(helper);
+      }
+
+      this.__helperSlot = this.shadowRoot.querySelector('[name="helper"]');
+
+      this.__helperSlotObserver = new FlattenedNodesObserver(this.__helperSlot, (info) => {
+        const helper = this._currentHelper;
+
+        const newHelper = info.addedNodes.find((node) => node !== helper);
+        const oldHelper = info.removedNodes.find((node) => node === helper);
+
+        if (newHelper) {
+          // Custom helper is added, remove the previous one.
+          if (helper && helper.isConnected) {
+            this.removeChild(helper);
+          }
+
+          this.__applyCustomHelper(newHelper);
+
+          this.__helperIdObserver = new MutationObserver((mutations) => {
+            mutations.forEach((mutation) => {
+              // only handle helper nodes
+              if (
+                mutation.type === 'attributes' &&
+                mutation.attributeName === 'id' &&
+                mutation.target === this._currentHelper &&
+                mutation.target.id !== this.__savedHelperId
+              ) {
+                this.__updateHelperId(mutation.target);
+              }
+            });
+          });
+
+          this.__helperIdObserver.observe(newHelper, { attributes: true });
+        } else if (oldHelper) {
+          // The observer does not exist when default helper is removed.
+          if (this.__helperIdObserver) {
+            this.__helperIdObserver.disconnect();
+          }
+
+          this.__applyDefaultHelper(this.helperText);
+        }
+      });
+    }
+
+    /** @private */
+    __applyCustomError() {
+      const error = this.__errorMessage;
+      if (error && error !== this.errorMessage) {
+        this.errorMessage = error;
+        delete this.__errorMessage;
+      }
+    }
+
+    /** @private */
+    __applyCustomHelper(helper) {
+      this.__updateHelperId(helper);
+      this._currentHelper = helper;
+      this.__toggleHasHelper(helper.children.length > 0 || this.__isNotEmpty(helper.textContent));
+    }
+
+    /** @private */
+    __isNotEmpty(helperText) {
+      return helperText && helperText.trim() !== '';
+    }
+
+    /** @private */
+    __attachDefaultHelper() {
+      let helper = this.__defaultHelper;
+
+      if (!helper) {
+        helper = document.createElement('div');
+        helper.setAttribute('slot', 'helper');
+        this.__defaultHelper = helper;
+      }
+
+      helper.id = this.__savedHelperId;
+      this.appendChild(helper);
+      this._currentHelper = helper;
+
+      return helper;
+    }
+
+    /** @private */
+    __applyDefaultHelper(helperText) {
+      let helper = this._helperNode;
+
+      const hasHelperText = this.__isNotEmpty(helperText);
+      if (hasHelperText && !helper) {
+        // Create helper lazily
+        helper = this.__attachDefaultHelper();
+      }
+
+      // Only set text content for default helper
+      if (helper && helper === this.__defaultHelper) {
+        helper.textContent = helperText;
+      }
+
+      this.__toggleHasHelper(hasHelperText);
+    }
+
+    /** @private */
+    __toggleHasHelper(hasHelper) {
+      this.toggleAttribute('has-helper', hasHelper);
+    }
+
+    /**
+     * Dispatch an event if a specific size measurement property has changed.
+     * Supporting multiple properties here is needed for `vaadin-text-area`.
+     * @protected
+     */
+    _dispatchIronResizeEventIfNeeded(prop, value) {
+      const oldSize = '__old' + prop;
+      if (this[oldSize] !== undefined && this[oldSize] !== value) {
+        this.dispatchEvent(new CustomEvent('iron-resize', { bubbles: true, composed: true }));
+      }
+
+      this[oldSize] = value;
+    }
+
+    /** @private */
+    __observeOffsetHeight() {
+      this.__observeOffsetHeightDebouncer = Debouncer.debounce(
+        this.__observeOffsetHeightDebouncer,
+        animationFrame,
+        () => {
+          this._dispatchIronResizeEventIfNeeded('Height', this.offsetHeight);
+        }
+      );
+    }
+
+    /**
+     * @param {boolean} invalid
+     * @protected
+     */
+    _updateErrorMessage(invalid, errorMessage) {
+      const error = this._errorNode;
+      if (!error) {
+        return;
+      }
+
+      // save the custom error message content
+      if (error.textContent && !errorMessage) {
+        this.__errorMessage = error.textContent.trim();
+      }
+      const hasError = Boolean(invalid && errorMessage);
+      error.textContent = hasError ? errorMessage : '';
+      this.toggleAttribute('has-error-message', hasError);
+    }
+
+    /** @private */
+    __updateHelperId(customHelper) {
+      let newId;
+
+      if (customHelper.id) {
+        newId = customHelper.id;
+      } else {
+        newId = this.__savedHelperId;
+        customHelper.id = newId;
+      }
+
+      this._helperId = newId;
+    }
+
+    /** @protected */
+    _helperTextChanged(helperText) {
+      this.__applyDefaultHelper(helperText);
+    }
+
+    /** @protected */
+    _ariaTargetChanged(target) {
+      if (target) {
+        this._updateAriaAttribute(this.invalid, this._helperId);
+      }
+    }
+
+    /** @protected */
+    _updateAriaAttribute(invalid, helperId) {
+      const attr = this._ariaAttr;
+
+      if (this.ariaTarget && attr) {
+        // For groups, add all IDs to aria-labelledby rather than aria-describedby -
+        // that should guarantee that it's announced when the group is entered.
+        const ariaIds = attr === 'aria-describedby' ? [helperId] : [this._labelId, helperId];
+
+        // Error message ID needs to be dynamically added / removed based on the validity
+        // Otherwise assistive technologies would announce the error, even if we hide it.
+        if (invalid) {
+          ariaIds.push(this._errorId);
+        }
+
+        this.ariaTarget.setAttribute(attr, ariaIds.join(' '));
+      }
+    }
+
+    /** @private */
+    __ariaChanged(invalid, helperId) {
+      this._updateAriaAttribute(invalid, helperId);
+    }
+  };

package/src/input-constraints-mixin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { DelegateStateMixin } from './delegate-state-mixin.js';
+import { InputMixin } from './input-mixin.js';
+import { ValidateMixin } from './validate-mixin.js';
+
+/**
+ * A mixin to combine multiple input validation constraints.
+ */
+declare function InputConstraintsMixin<T extends new (...args: any[]) => {}>(
+  base: T
+): T & InputConstraintsMixinConstructor;
+
+interface InputConstraintsMixinConstructor {
+  new (...args: any[]): InputConstraintsMixin;
+}
+
+interface InputConstraintsMixin extends DelegateStateMixin, InputMixin, ValidateMixin {
+  /**
+   * Returns true if the current input value satisfies all constraints (if any).
+   */
+  checkValidity(): boolean;
+}
+
+export { InputConstraintsMixin, InputConstraintsMixinConstructor };

package/src/input-constraints-mixin.js

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { dedupingMixin } from '@polymer/polymer/lib/utils/mixin.js';
+import { DelegateStateMixin } from './delegate-state-mixin.js';
+import { InputMixin } from './input-mixin.js';
+import { ValidateMixin } from './validate-mixin.js';
+
+/**
+ * A mixin to combine multiple input validation constraints.
+ *
+ * @polymerMixin
+ * @mixes DelegateStateMixin
+ * @mixes InputMixin
+ * @mixes ValidateMixin
+ */
+export const InputConstraintsMixin = dedupingMixin(
+  (superclass) =>
+    class InputConstraintsMixinClass extends DelegateStateMixin(ValidateMixin(InputMixin(superclass))) {
+      /**
+       * An array of attributes which participate in the input validation.
+       * Changing these attributes will cause the input to re-validate.
+       *
+       * IMPORTANT: The attributes should be properly delegated to the input element
+       * from the host using `delegateAttrs` getter (see `DelegateStateMixin`).
+       * The `required` attribute is already delegated.
+       */
+      static get constraints() {
+        return ['required'];
+      }
+
+      static get delegateAttrs() {
+        return [...super.delegateAttrs, 'required'];
+      }
+
+      /** @protected */
+      ready() {
+        super.ready();
+
+        this._createConstraintsObserver();
+      }
+
+      /**
+       * Returns true if the current input value satisfies all constraints (if any).
+       * @return {boolean}
+       */
+      checkValidity() {
+        if (this.inputElement && this._hasValidConstraints(this.constructor.constraints.map((c) => this[c]))) {
+          return this.inputElement.checkValidity();
+        } else {
+          return !this.invalid;
+        }
+      }
+
+      /**
+       * Returns true if some of the provided set of constraints are valid.
+       * @param {Array} constraints
+       * @return {boolean}
+       * @protected
+       */
+      _hasValidConstraints(constraints) {
+        return constraints.some((c) => this.__isValidConstraint(c));
+      }
+
+      /**
+       * Override this method to customize setting up constraints observer.
+       * @protected
+       */
+      _createConstraintsObserver() {
+        // This complex observer needs to be added dynamically instead of using `static get observers()`
+        // to make it possible to tweak this behavior in classes that apply this mixin.
+        this._createMethodObserver(`_constraintsChanged(${this.constructor.constraints.join(', ')})`);
+      }
+
+      /**
+       * Override this method to implement custom validation constraints.
+       * @param {unknown[]} constraints
+       * @protected
+       */
+      _constraintsChanged(...constraints) {
+        // Prevent marking field as invalid when setting required state
+        // or any other constraint before a user has entered the value.
+        if (!this.invalid) {
+          return;
+        }
+
+        if (this._hasValidConstraints(constraints)) {
+          this.validate();
+        } else {
+          this.invalid = false;
+        }
+      }
+
+      /**
+       * Override an event listener inherited from `InputMixin`
+       * to capture native `change` event and make sure that
+       * a new one is dispatched after validation runs.
+       * @param {Event} event
+       * @protected
+       * @override
+       */
+      _onChange(event) {
+        event.stopPropagation();
+
+        this.validate();
+
+        this.dispatchEvent(
+          new CustomEvent('change', {
+            detail: {
+              sourceEvent: event
+            },
+            bubbles: event.bubbles,
+            cancelable: event.cancelable
+          })
+        );
+      }
+
+      /** @private */
+      __isValidConstraint(constraint) {
+        // 0 is valid for `minlength` and `maxlength`
+        return Boolean(constraint) || constraint === 0;
+      }
+    }
+);

package/src/input-control-mixin.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { KeyboardMixin } from '@vaadin/component-base/src/keyboard-mixin.js';
+import { FieldMixin } from './field-mixin.js';
+import { InputConstraintsMixin } from './input-constraints-mixin.js';
+
+/**
+ * A mixin to provide shared logic for the editable form input controls.
+ */
+declare function InputControlMixin<T extends new (...args: any[]) => {}>(base: T): T & InputControlMixinConstructor;
+
+interface InputControlMixinConstructor {
+  new (...args: any[]): InputControlMixin;
+}
+
+interface InputControlMixin extends KeyboardMixin, InputConstraintsMixin, FieldMixin {
+  /**
+   * If true, the input text gets fully selected when the field is focused using click or touch / tap.
+   */
+  autoselect: boolean;
+
+  /**
+   * Set to true to display the clear icon which clears the input.
+   * @attr {boolean} clear-button-visible
+   */
+  clearButtonVisible: boolean;
+
+  /**
+   * The name of this field.
+   */
+  name: string;
+
+  /**
+   * A hint to the user of what can be entered in the field.
+   */
+  placeholder: string;
+
+  /**
+   * When present, it specifies that the field is read-only.
+   */
+  readonly: boolean;
+
+  /**
+   * The text usually displayed in a tooltip popup when the mouse is over the field.
+   */
+  title: string;
+}
+
+export { InputControlMixin, InputControlMixinConstructor };