@vaadin/custom-field 24.2.0-dev.e9803eea7 → 24.3.0-alpha1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/custom-field",
-  "version": "24.2.0-dev.e9803eea7",
+  "version": "24.3.0-alpha1",
   "publishConfig": {
     "access": "public"
   },
@@ -21,6 +21,8 @@
   "type": "module",
   "files": [
     "src",
+    "!src/vaadin-lit-custom-field.d.ts",
+    "!src/vaadin-lit-custom-field.js",
     "theme",
     "vaadin-*.d.ts",
     "vaadin-*.js",
@@ -34,32 +36,33 @@
     "web-component"
   ],
   "dependencies": {
+    "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/a11y-base": "24.2.0-dev.e9803eea7",
-    "@vaadin/component-base": "24.2.0-dev.e9803eea7",
-    "@vaadin/field-base": "24.2.0-dev.e9803eea7",
-    "@vaadin/vaadin-lumo-styles": "24.2.0-dev.e9803eea7",
-    "@vaadin/vaadin-material-styles": "24.2.0-dev.e9803eea7",
-    "@vaadin/vaadin-themable-mixin": "24.2.0-dev.e9803eea7"
+    "@vaadin/a11y-base": "24.3.0-alpha1",
+    "@vaadin/component-base": "24.3.0-alpha1",
+    "@vaadin/field-base": "24.3.0-alpha1",
+    "@vaadin/vaadin-lumo-styles": "24.3.0-alpha1",
+    "@vaadin/vaadin-material-styles": "24.3.0-alpha1",
+    "@vaadin/vaadin-themable-mixin": "24.3.0-alpha1"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/combo-box": "24.2.0-dev.e9803eea7",
-    "@vaadin/date-picker": "24.2.0-dev.e9803eea7",
-    "@vaadin/email-field": "24.2.0-dev.e9803eea7",
-    "@vaadin/form-layout": "24.2.0-dev.e9803eea7",
-    "@vaadin/number-field": "24.2.0-dev.e9803eea7",
-    "@vaadin/password-field": "24.2.0-dev.e9803eea7",
-    "@vaadin/select": "24.2.0-dev.e9803eea7",
-    "@vaadin/testing-helpers": "^0.4.3",
-    "@vaadin/text-area": "24.2.0-dev.e9803eea7",
-    "@vaadin/text-field": "24.2.0-dev.e9803eea7",
-    "@vaadin/time-picker": "24.2.0-dev.e9803eea7",
+    "@vaadin/combo-box": "24.3.0-alpha1",
+    "@vaadin/date-picker": "24.3.0-alpha1",
+    "@vaadin/email-field": "24.3.0-alpha1",
+    "@vaadin/form-layout": "24.3.0-alpha1",
+    "@vaadin/number-field": "24.3.0-alpha1",
+    "@vaadin/password-field": "24.3.0-alpha1",
+    "@vaadin/select": "24.3.0-alpha1",
+    "@vaadin/testing-helpers": "^0.5.0",
+    "@vaadin/text-area": "24.3.0-alpha1",
+    "@vaadin/text-field": "24.3.0-alpha1",
+    "@vaadin/time-picker": "24.3.0-alpha1",
     "sinon": "^13.0.2"
   },
   "web-types": [
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "a065b79b9d5a189e457fab312cc8aff0d7f2f910"
+  "gitHead": "9ca6f3ca220a777e8eea181a1f5717e39a732240"
 }

package/src/vaadin-custom-field-mixin.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright (c) 2019 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+import type { FocusMixinClass } from '@vaadin/a11y-base/src/focus-mixin.js';
+import type { KeyboardMixinClass } from '@vaadin/a11y-base/src/keyboard-mixin.js';
+import type { FieldMixinClass } from '@vaadin/field-base/src/field-mixin.js';
+import type { LabelMixinClass } from '@vaadin/field-base/src/label-mixin.js';
+import type { ValidateMixinClass } from '@vaadin/field-base/src/validate-mixin.js';
+
+export type CustomFieldParseValueFn = (value: string) => unknown[];
+
+export type CustomFieldFormatValueFn = (inputValues: unknown[]) => string;
+
+/**
+ * A mixin providing common custom field functionality.
+ */
+export declare function CustomFieldMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<CustomFieldMixinClass> &
+  Constructor<FieldMixinClass> &
+  Constructor<FocusMixinClass> &
+  Constructor<KeyboardMixinClass> &
+  Constructor<LabelMixinClass> &
+  Constructor<ValidateMixinClass> &
+  T;
+
+export declare class CustomFieldMixinClass {
+  /**
+   * Array of available input nodes
+   */
+  readonly inputs: HTMLElement[] | undefined;
+
+  /**
+   * A function to format the values of the individual fields contained by
+   * the custom field into a single component value. The function receives
+   * an array of all values of the individual fields in the order of their
+   * presence in the DOM, and must return a single component value.
+   * This function is called each time a value of an internal field is
+   * changed.
+   *
+   * Example:
+   * ```js
+   * customField.formatValue = (fieldValues) => {
+   *   return fieldValues.join("-");
+   * }
+   * ```
+   */
+  formatValue: CustomFieldFormatValueFn | undefined;
+
+  /**
+   * A function to parse the component value into values for the individual
+   * fields contained by the custom field. The function receives the
+   * component value, and must return an array of values for the individual
+   * fields in the order of their presence in the DOM.
+   * The function is called each time the value of the component changes.
+   *
+   * Example:
+   * ```js
+   * customField.parseValue = (componentValue) => {
+   *   return componentValue.split("-");
+   * }
+   * ```
+   */
+  parseValue: CustomFieldParseValueFn | undefined;
+
+  /**
+   * The name of the control, which is submitted with the form data.
+   */
+  name: string | null | undefined;
+
+  /**
+   * The value of the field. When wrapping several inputs, it will contain `\t`
+   * (Tab character) as a delimiter indicating parts intended to be used as the
+   * corresponding inputs values.
+   * Use the [`formatValue`](#/elements/vaadin-custom-field#property-formatValue)
+   * and [`parseValue`](#/elements/vaadin-custom-field#property-parseValue)
+   * properties to customize this behavior.
+   */
+  value: string | null | undefined;
+}

package/src/vaadin-custom-field-mixin.js

@@ -0,0 +1,301 @@
+/**
+ * @license
+ * Copyright (c) 2019 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { FocusMixin } from '@vaadin/a11y-base/src/focus-mixin.js';
+import { KeyboardMixin } from '@vaadin/a11y-base/src/keyboard-mixin.js';
+import { getFlattenedElements } from '@vaadin/component-base/src/dom-utils.js';
+import { TooltipController } from '@vaadin/component-base/src/tooltip-controller.js';
+import { FieldMixin } from '@vaadin/field-base/src/field-mixin.js';
+
+/**
+ * Default implementation of the parse function that creates individual field
+ * values from the single component value.
+ * @param value
+ * @returns {*}
+ */
+const defaultParseValue = (value) => {
+  return value.split('\t');
+};
+
+/**
+ * Default implementation of the format function that creates a single component
+ * value from individual field values.
+ * @param inputValues
+ * @returns {*}
+ */
+const defaultFormatValue = (inputValues) => {
+  return inputValues.join('\t');
+};
+
+/**
+ * @polymerMixin
+ * @mixes FieldMixin
+ * @mixes FocusMixin
+ * @mixes KeyboardMixin
+ */
+export const CustomFieldMixin = (superClass) =>
+  class CustomFieldMixin extends FieldMixin(FocusMixin(KeyboardMixin(superClass))) {
+    static get properties() {
+      return {
+        /**
+         * The name of the control, which is submitted with the form data.
+         */
+        name: String,
+
+        /**
+         * The value of the field. When wrapping several inputs, it will contain `\t`
+         * (Tab character) as a delimiter indicating parts intended to be used as the
+         * corresponding inputs values.
+         * Use the [`formatValue`](#/elements/vaadin-custom-field#property-formatValue)
+         * and [`parseValue`](#/elements/vaadin-custom-field#property-parseValue)
+         * properties to customize this behavior.
+         */
+        value: {
+          type: String,
+          observer: '__valueChanged',
+          notify: true,
+        },
+
+        /**
+         * Array of available input nodes
+         * @type {!Array<!HTMLElement> | undefined}
+         */
+        inputs: {
+          type: Array,
+          readOnly: true,
+        },
+
+        /**
+         * A function to format the values of the individual fields contained by
+         * the custom field into a single component value. The function receives
+         * an array of all values of the individual fields in the order of their
+         * presence in the DOM, and must return a single component value.
+         * This function is called each time a value of an internal field is
+         * changed.
+         *
+         * Example:
+         * ```js
+         * customField.formatValue = (fieldValues) => {
+         *   return fieldValues.join("-");
+         * }
+         * ```
+         * @type {!CustomFieldFormatValueFn | undefined}
+         */
+        formatValue: {
+          type: Function,
+        },
+
+        /**
+         * A function to parse the component value into values for the individual
+         * fields contained by the custom field. The function receives the
+         * component value, and must return an array of values for the individual
+         * fields in the order of their presence in the DOM.
+         * The function is called each time the value of the component changes.
+         *
+         * Example:
+         * ```js
+         * customField.parseValue = (componentValue) => {
+         *   return componentValue.split("-");
+         * }
+         * ```
+         * @type {!CustomFieldParseValueFn | undefined}
+         */
+        parseValue: {
+          type: Function,
+        },
+
+        /**
+         * Whether the field is dirty.
+         *
+         * The field is automatically marked as dirty once the user triggers
+         * an `input` or `change` event. Additionally, the field can be manually
+         * marked as dirty by setting the property to `true`.
+         */
+        dirty: {
+          type: Boolean,
+          value: false,
+          notify: true,
+        },
+      };
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+
+      // See https://github.com/vaadin/vaadin-web-components/issues/94
+      this.setAttribute('role', 'group');
+
+      this.ariaTarget = this;
+
+      this.__childrenObserver = new MutationObserver(() => {
+        this.__setInputsFromSlot();
+      });
+
+      this.__setInputsFromSlot();
+      this.$.slot.addEventListener('slotchange', () => {
+        this.__setInputsFromSlot();
+
+        // Observe changes to any children except inputs
+        // to allow wrapping `<input>` with `<div>` etc.
+        getFlattenedElements(this.$.slot)
+          .filter((el) => !this.__isInput(el))
+          .forEach((el) => {
+            this.__childrenObserver.observe(el, { childList: true });
+          });
+      });
+
+      this._tooltipController = new TooltipController(this);
+      this.addController(this._tooltipController);
+      this._tooltipController.setShouldShow((target) => {
+        const inputs = target.inputs || [];
+        return !inputs.some((el) => el.opened);
+      });
+    }
+
+    /** @protected */
+    focus() {
+      if (this.inputs && this.inputs[0]) {
+        this.inputs[0].focus();
+      }
+    }
+
+    /**
+     * Override method inherited from `FocusMixin` to validate on blur.
+     * @param {boolean} focused
+     * @protected
+     */
+    _setFocused(focused) {
+      super._setFocused(focused);
+
+      if (!focused) {
+        this.validate();
+      }
+    }
+
+    /**
+     * Override method inherited from `FocusMixin` to not remove focused
+     * state when focus moves to another input in the custom field.
+     * @param {FocusEvent} event
+     * @return {boolean}
+     * @protected
+     */
+    _shouldRemoveFocus(event) {
+      const { relatedTarget } = event;
+      return !this.inputs.some((el) => relatedTarget === (el.focusElement || el));
+    }
+
+    /**
+     * Returns true if the current inputs values satisfy all constraints (if any).
+     *
+     * @return {boolean}
+     */
+    checkValidity() {
+      const invalidFields = this.inputs.filter((input) => !(input.validate || input.checkValidity).call(input));
+
+      if (invalidFields.length || (this.required && !this.value.trim())) {
+        // Either 1. one of the input fields is invalid or
+        // 2. the custom field itself is required but doesn't have a value
+        return false;
+      }
+      return true;
+    }
+
+    /**
+     * @param {KeyboardEvent} e
+     * @protected
+     * @override
+     */
+    _onKeyDown(e) {
+      if (e.key === 'Tab') {
+        if (
+          (this.inputs.indexOf(e.target) < this.inputs.length - 1 && !e.shiftKey) ||
+          (this.inputs.indexOf(e.target) > 0 && e.shiftKey)
+        ) {
+          this.dispatchEvent(new CustomEvent('internal-tab'));
+        } else {
+          // FIXME(yuriy): remove this workaround when value should not be updated before focusout
+          this.__setValue();
+        }
+      }
+    }
+
+    /** @protected */
+    _onInput() {
+      this.dirty = true;
+    }
+
+    /** @protected */
+    _onChange(event) {
+      // Stop native change events
+      event.stopPropagation();
+      this.dirty = true;
+
+      this.__setValue();
+      this.validate();
+      this.dispatchEvent(
+        new CustomEvent('change', {
+          bubbles: true,
+          cancelable: false,
+          detail: {
+            value: this.value,
+          },
+        }),
+      );
+    }
+
+    /** @private */
+    __setValue() {
+      this.__settingValue = true;
+      const formatFn = this.formatValue || defaultFormatValue;
+      this.value = formatFn.apply(this, [this.inputs.map((input) => input.value)]);
+      this.__settingValue = false;
+    }
+
+    /** @private */
+    __isInput(node) {
+      const isSlottedInput = node.getAttribute('slot') === 'input' || node.getAttribute('slot') === 'textarea';
+      return !isSlottedInput && (node.validate || node.checkValidity);
+    }
+
+    /** @private */
+    __getInputsFromSlot() {
+      return getFlattenedElements(this.$.slot).filter((node) => this.__isInput(node));
+    }
+
+    /** @private */
+    __setInputsFromSlot() {
+      this._setInputs(this.__getInputsFromSlot());
+      this.__setValue();
+    }
+
+    /** @private */
+    __toggleHasValue(value) {
+      this.toggleAttribute('has-value', value !== null && value.trim() !== '');
+    }
+
+    /** @private */
+    __valueChanged(value, oldValue) {
+      if (this.__settingValue || !this.inputs) {
+        return;
+      }
+
+      this.__toggleHasValue(value);
+
+      const parseFn = this.parseValue || defaultParseValue;
+      const valuesArray = parseFn.apply(this, [value]);
+      if (!valuesArray || valuesArray.length === 0) {
+        console.warn('Value parser has not provided values array');
+        return;
+      }
+
+      this.inputs.forEach((input, id) => {
+        input.value = valuesArray[id];
+      });
+      if (oldValue !== undefined) {
+        this.validate();
+      }
+    }
+  };

package/src/vaadin-custom-field-styles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright (c) 2019 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { CSSResult } from 'lit';
+
+export const customFieldStyles: CSSResult;

package/src/vaadin-custom-field-styles.js

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright (c) 2019 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { css } from 'lit';
+
+export const customFieldStyles = css`
+  :host {
+    display: inline-flex;
+  }
+
+  :host::before {
+    content: '\\2003';
+    width: 0;
+    display: inline-block;
+    /* Size and position this element on the same vertical position as the input-field element
+           to make vertical align for the host element work as expected */
+  }
+
+  :host([hidden]) {
+    display: none !important;
+  }
+
+  .vaadin-custom-field-container {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .inputs-wrapper {
+    flex: none;
+  }
+`;

package/src/vaadin-custom-field.d.ts

@@ -3,15 +3,11 @@
  * Copyright (c) 2019 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { FocusMixin } from '@vaadin/a11y-base/src/focus-mixin.js';
-import { KeyboardMixin } from '@vaadin/a11y-base/src/keyboard-mixin.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
-import { FieldMixin } from '@vaadin/field-base/src/field-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { CustomFieldMixin } from './vaadin-custom-field-mixin.js';
 
-export type CustomFieldParseValueFn = (value: string) => unknown[];
-
-export type CustomFieldFormatValueFn = (inputValues: unknown[]) => string;
+export { CustomFieldFormatValueFn, CustomFieldParseValueFn } from './vaadin-custom-field-mixin.js';
 
 /**
  * Fired when the user commits a value change.
@@ -20,6 +16,11 @@ export type CustomFieldChangeEvent = Event & {
   target: CustomField;
 };
 
+/**
+ * Fired when the `dirty` property changes.
+ */
+export type CustomFieldDirtyChangedEvent = CustomEvent<{ value: boolean }>;
+
 /**
  * Fired when the `invalid` property changes.
  */
@@ -43,6 +44,8 @@ export type CustomFieldInternalTabEvent = Event & {
 };
 
 export interface CustomFieldCustomEventMap {
+  'dirty-changed': CustomFieldDirtyChangedEvent;
+
   'invalid-changed': CustomFieldInvalidChangedEvent;
 
   'value-changed': CustomFieldValueChangedEvent;
@@ -95,64 +98,12 @@ export interface CustomFieldEventMap extends HTMLElementEventMap, CustomFieldCus
  *
  * @fires {Event} change - Fired when the user commits a value change for any of the internal inputs.
  * @fires {Event} internal-tab - Fired on Tab keydown triggered from the internal inputs, meaning focus will not leave the inputs.
+ * @fires {CustomEvent} dirty-changed - Fired when the `dirty` property changes.
  * @fires {CustomEvent} invalid-changed - Fired when the `invalid` property changes.
  * @fires {CustomEvent} value-changed - Fired when the `value` property changes.
  * @fires {CustomEvent} validated - Fired whenever the field is validated.
  */
-declare class CustomField extends FieldMixin(FocusMixin(KeyboardMixin(ThemableMixin(ElementMixin(HTMLElement))))) {
-  /**
-   * Array of available input nodes
-   */
-  readonly inputs: HTMLElement[] | undefined;
-
-  /**
-   * A function to format the values of the individual fields contained by
-   * the custom field into a single component value. The function receives
-   * an array of all values of the individual fields in the order of their
-   * presence in the DOM, and must return a single component value.
-   * This function is called each time a value of an internal field is
-   * changed.
-   *
-   * Example:
-   * ```js
-   * customField.formatValue = (fieldValues) => {
-   *   return fieldValues.join("-");
-   * }
-   * ```
-   */
-  formatValue: CustomFieldFormatValueFn | undefined;
-
-  /**
-   * A function to parse the component value into values for the individual
-   * fields contained by the custom field. The function receives the
-   * component value, and must return an array of values for the individual
-   * fields in the order of their presence in the DOM.
-   * The function is called each time the value of the component changes.
-   *
-   * Example:
-   * ```js
-   * customField.parseValue = (componentValue) => {
-   *   return componentValue.split("-");
-   * }
-   * ```
-   */
-  parseValue: CustomFieldParseValueFn | undefined;
-
-  /**
-   * The name of the control, which is submitted with the form data.
-   */
-  name: string | null | undefined;
-
-  /**
-   * The value of the field. When wrapping several inputs, it will contain `\t`
-   * (Tab character) as a delimiter indicating parts intended to be used as the
-   * corresponding inputs values.
-   * Use the [`formatValue`](#/elements/vaadin-custom-field#property-formatValue)
-   * and [`parseValue`](#/elements/vaadin-custom-field#property-parseValue)
-   * properties to customize this behavior.
-   */
-  value: string | null | undefined;
-
+declare class CustomField extends CustomFieldMixin(ThemableMixin(ElementMixin(HTMLElement))) {
   addEventListener<K extends keyof CustomFieldEventMap>(
     type: K,
     listener: (this: CustomField, ev: CustomFieldEventMap[K]) => void,