form-layoutpackage.src.vaadin-form-layout.js Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of vaadin-webcomponents Show documentation
Mvnpm composite: Vaadin webcomponents
The newest version!
/**
 * @license
 * Copyright (c) 2017 - 2024 Vaadin Ltd.
 * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
 */
import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
import { isElementHidden } from '@vaadin/a11y-base/src/focus-utils.js';
import { defineCustomElement } from '@vaadin/component-base/src/define.js';
import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';

/**
 * `` is a Web Component providing configurable responsive
 * layout for form elements.
 *
 * ```html
 * 
 *
 *   
 *     First Name
 *     
 *   
 *
 *   
 *     Last Name
 *     
 *   
 *
 *   
 *     Email
 *     
 *   
 *
 * 
 * ```
 *
 * It supports any child elements as layout items.
 *
 * By default, it makes a layout of two columns if the element width is equal or
 * wider than 40em, and a single column layout otherwise.
 *
 * The number of columns and the responsive behavior are customizable with
 * the `responsiveSteps` property.
 *
 * ### Spanning Items on Multiple Columns
 *
 * You can use `colspan` or `data-colspan` attribute on the items.
 * In the example below, the first text field spans on two columns:
 *
 * ```html
 * 
 *
 *   
 *     Address
 *     
 *   
 *
 *   
 *     First Name
 *     
 *   
 *
 *   
 *     Last Name
 *     
 *   
 *
 * 
 * ```
 *
 * ### Explicit New Row
 *
 * Use the `
` line break element to wrap the items on a new row:
 *
 * ```html
 * 
 *
 *   
 *     Email
 *     
 *   
 *
 *   

 *
 *   
 *     Confirm Email
 *     
 *   
 *
 * 
 * ```
 *
 * ### CSS Properties Reference
 *
 * The following custom CSS properties are available on the ``
 * element:
 *
 * Custom CSS property | Description | Default
 * ---|---|---
 * `--vaadin-form-layout-column-spacing` | Length of the spacing between columns | `2em`
 *
 * @customElement
 * @extends HTMLElement
 * @mixes ElementMixin
 * @mixes ThemableMixin
 * @mixes ResizeMixin
 */
class FormLayout extends ResizeMixin(ElementMixin(ThemableMixin(PolymerElement))) {
  static get template() {
    return html`
      
      
        
      
    `;
  }

  static get is() {
    return 'vaadin-form-layout';
  }

  static get properties() {
    return {
      /**
       * @typedef FormLayoutResponsiveStep
       * @type {object}
       * @property {string} minWidth - The threshold value for this step in CSS length units.
       * @property {number} columns - Number of columns. Only natural numbers are valid.
       * @property {string} labelsPosition - Labels position option, valid values: `"aside"` (default), `"top"`.
       */

      /**
       * Allows specifying a responsive behavior with the number of columns
       * and the label position depending on the layout width.
       *
       * Format: array of objects, each object defines one responsive step
       * with `minWidth` CSS length, `columns` number, and optional
       * `labelsPosition` string of `"aside"` or `"top"`. At least one item is required.
       *
       * #### Examples
       *
       * ```javascript
       * formLayout.responsiveSteps = [{columns: 1}];
       * // The layout is always a single column, labels aside.
       * ```
       *
       * ```javascript
       * formLayout.responsiveSteps = [
       *   {minWidth: 0, columns: 1},
       *   {minWidth: '40em', columns: 2}
       * ];
       * // Sets two responsive steps:
       * // 1. When the layout width is < 40em, one column, labels aside.
       * // 2. Width >= 40em, two columns, labels aside.
       * ```
       *
       * ```javascript
       * formLayout.responsiveSteps = [
       *   {minWidth: 0, columns: 1, labelsPosition: 'top'},
       *   {minWidth: '20em', columns: 1},
       *   {minWidth: '40em', columns: 2}
       * ];
       * // Default value. Three responsive steps:
       * // 1. Width < 20em, one column, labels on top.
       * // 2. 20em <= width < 40em, one column, labels aside.
       * // 3. Width >= 40em, two columns, labels aside.
       * ```
       *
       * @type {!Array}
       */
      responsiveSteps: {
        type: Array,
        value() {
          return [
            { minWidth: 0, columns: 1, labelsPosition: 'top' },
            { minWidth: '20em', columns: 1 },
            { minWidth: '40em', columns: 2 },
          ];
        },
        observer: '_responsiveStepsChanged',
      },

      /**
       * Current number of columns in the layout
       * @private
       */
      _columnCount: {
        type: Number,
      },

      /**
       * Indicates that labels are on top
       * @private
       */
      _labelsOnTop: {
        type: Boolean,
      },

      /** @private */
      __isVisible: {
        type: Boolean,
      },
    };
  }

  static get observers() {
    return ['_invokeUpdateLayout(_columnCount, _labelsOnTop)'];
  }

  /** @protected */
  ready() {
    // Here we create and attach a style element that we use for validating
    // CSS values in `responsiveSteps`. We can't add this to the `