npm - @vaadin/master-detail-layout - Versions diffs - 24.8.0-alpha10 - Mend

@vaadin/master-detail-layout 24.8.0-alpha10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/LICENSE +190 -0
package/README.md +60 -0
package/package.json +54 -0
package/src/vaadin-master-detail-layout-transition-styles.js +289 -0
package/src/vaadin-master-detail-layout.d.ts +133 -0
package/src/vaadin-master-detail-layout.js +682 -0
package/theme/lumo/vaadin-master-detail-layout-styles.d.ts +1 -0
package/theme/lumo/vaadin-master-detail-layout-styles.js +28 -0
package/theme/lumo/vaadin-master-detail-layout.d.ts +2 -0
package/theme/lumo/vaadin-master-detail-layout.js +2 -0
package/theme/material/vaadin-master-detail-layout-styles.d.ts +2 -0
package/theme/material/vaadin-master-detail-layout-styles.js +30 -0
package/theme/material/vaadin-master-detail-layout.d.ts +2 -0
package/theme/material/vaadin-master-detail-layout.js +2 -0
package/vaadin-master-detail-layout.d.ts +1 -0
package/vaadin-master-detail-layout.js +3 -0
package/web-types.json +232 -0
package/web-types.lit.json +90 -0

package/src/vaadin-master-detail-layout.js ADDED Viewed

@@ -0,0 +1,682 @@
+/**
+ * @license
+ * Copyright (c) 2025 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { css, html, LitElement, nothing } from 'lit';
+import { getFocusableElements } 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 { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
+import { SlotStylesMixin } from '@vaadin/component-base/src/slot-styles-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { transitionStyles } from './vaadin-master-detail-layout-transition-styles.js';
+/**
+ * `<vaadin-master-detail-layout>` is a web component for building UIs with a master
+ * (or primary) area and a detail (or secondary) area that is displayed next to, or
+ * overlaid on top of, the master area, depending on configuration and viewport size.
+ *
+ * ### Styling
+ *
+ * The following custom CSS properties are available for styling (needed to be set
+ * on the `<html>` element since they are used by the global view transitions):
+ *
+ * Custom CSS property                                  | Description         | Default
+ * -----------------------------------------------------|---------------------|--------
+ * `--vaadin-master-detail-layout-transition-duration`  | Transition duration | 300ms
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name      | Description
+ * ---------------|----------------------
+ * `backdrop`     | Backdrop covering the master area in the overlay mode
+ * `master`       | The master area
+ * `detail`       | The detail area
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------| -----------
+ * `containment`  | Set to `layout` or `viewport` depending on the containment.
+ * `orientation`  | Set to `horizontal` or `vertical` depending on the orientation.
+ * `has-detail`   | Set when the detail content is provided.
+ * `overlay`      | Set when the layout is using the overlay mode.
+ * `stack`        | Set when the layout is using the stack mode.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @customElement
+ * @extends HTMLElement
+ * @mixes ThemableMixin
+ * @mixes ElementMixin
+ * @mixes ResizeMixin
+ * @mixes SlotStylesMixin
+ */
+class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement))))) {
+  static get is() {
+    return 'vaadin-master-detail-layout';
+  }
+  static get styles() {
+    return css`
+      :host {
+        display: flex;
+        box-sizing: border-box;
+        height: 100%;
+      }
+      :host([hidden]) {
+        display: none !important;
+      }
+      :host(:not([has-detail])) [part='detail'],
+      [part='backdrop'] {
+        display: none;
+      }
+      /* Overlay mode */
+      :host(:is([overlay], [stack])) {
+        position: relative;
+      }
+      :host(:is([overlay], [stack])[containment='layout']) [part='detail'],
+      :host([overlay][containment='layout']) [part='backdrop'] {
+        position: absolute;
+      }
+      :host(:is([overlay], [stack])[containment='viewport']) [part='detail'],
+      :host([overlay][containment='viewport']) [part='backdrop'] {
+        position: fixed;
+      }
+      :host([overlay][has-detail]) [part='backdrop'] {
+        display: block;
+        inset: 0;
+        z-index: 1;
+      }
+      :host([overlay]) [part='detail'] {
+        z-index: 1;
+      }
+      :host([overlay][orientation='horizontal']) [part='detail'] {
+        inset-inline-end: 0;
+        height: 100%;
+        width: var(--_detail-min-size, min-content);
+        max-width: 100%;
+      }
+      :host([overlay][orientation='horizontal'][containment='viewport']) [part='detail'] {
+        inset-block-start: 0;
+      }
+      :host([overlay][orientation='horizontal']) [part='master'] {
+        max-width: 100%;
+      }
+      /* No fixed size */
+      :host(:not([has-master-size])) [part='master'],
+      :host(:not([has-detail-size])) [part='detail'] {
+        flex-grow: 1;
+        flex-basis: 50%;
+      }
+      /* Fixed size */
+      :host([has-master-size]) [part='master'],
+      :host([has-detail-size]) [part='detail'] {
+        flex-shrink: 0;
+      }
+      :host([has-master-size][orientation='horizontal']) [part='master'] {
+        width: var(--_master-size);
+      }
+      :host([has-detail-size][orientation='horizontal']:not([stack])) [part='detail'] {
+        width: var(--_detail-size);
+      }
+      :host([has-master-size][has-detail-size]) [part='master'] {
+        flex-grow: 1;
+        flex-basis: var(--_master-size);
+      }
+      :host([has-master-size][has-detail-size]) [part='detail'] {
+        flex-grow: 1;
+        flex-basis: var(--_detail-size);
+      }
+      /* Min size */
+      :host([has-master-min-size][orientation='horizontal']:not([overlay])) [part='master'] {
+        min-width: var(--_master-min-size);
+      }
+      :host([has-detail-min-size][orientation='horizontal']:not([overlay]):not([stack])) [part='detail'] {
+        min-width: var(--_detail-min-size);
+      }
+      :host([has-master-min-size]) [part='master'],
+      :host([has-detail-min-size]) [part='detail'] {
+        flex-shrink: 0;
+      }
+      /* Vertical */
+      :host([orientation='vertical']) {
+        flex-direction: column;
+      }
+      :host([orientation='vertical'][overlay]) [part='master'] {
+        max-height: 100%;
+      }
+      :host([orientation='vertical'][overlay]) [part='detail'] {
+        inset-block-end: 0;
+        width: 100%;
+        height: var(--_detail-min-size, min-content);
+      }
+      :host([overlay][orientation='vertical'][containment='viewport']) [part='detail'] {
+        inset-inline-start: 0;
+      }
+      /* Fixed size */
+      :host([has-master-size][orientation='vertical']) [part='master'] {
+        height: var(--_master-size);
+      }
+      :host([has-detail-size][orientation='vertical']:not([stack])) [part='detail'] {
+        height: var(--_detail-size);
+      }
+      /* Min size */
+      :host([has-master-min-size][orientation='vertical']:not([overlay])) [part='master'],
+      :host([has-master-min-size][orientation='vertical'][overlay]) {
+        min-height: var(--_master-min-size);
+      }
+      :host([has-detail-min-size][orientation='vertical']:not([overlay]):not([stack])) [part='detail'] {
+        min-height: var(--_detail-min-size);
+      }
+      /* Stack mode */
+      :host([stack]) [part='master'] {
+        max-height: 100%;
+      }
+      :host([stack]) [part='detail'] {
+        inset: 0;
+      }
+      [part='master']::before {
+        background-position-y: var(--_stack-threshold);
+      }
+    `;
+  }
+  static get properties() {
+    return {
+      /**
+       * Fixed size (in CSS length units) to be set on the detail area.
+       * When specified, it prevents the detail area from growing or
+       * shrinking. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
+       *
+       * @attr {string} detail-size
+       */
+      detailSize: {
+        type: String,
+        sync: true,
+        observer: '__detailSizeChanged',
+      },
+      /**
+       * Minimum size (in CSS length units) to be set on the detail area.
+       * When specified, it prevents the detail area from shrinking below
+       * this size. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
+       *
+       * @attr {string} detail-min-size
+       */
+      detailMinSize: {
+        type: String,
+        sync: true,
+        observer: '__detailMinSizeChanged',
+      },
+      /**
+       * Fixed size (in CSS length units) to be set on the master area.
+       * When specified, it prevents the master area from growing or
+       * shrinking. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
+       *
+       * @attr {string} master-size
+       */
+      masterSize: {
+        type: String,
+        sync: true,
+        observer: '__masterSizeChanged',
+      },
+      /**
+       * Minimum size (in CSS length units) to be set on the master area.
+       * When specified, it prevents the master area from shrinking below
+       * this size. If there is not enough space to show master and detail
+       * areas next to each other, the layout switches to the overlay mode.
+       *
+       * @attr {string} master-min-size
+       */
+      masterMinSize: {
+        type: String,
+        sync: true,
+        observer: '__masterMinSizeChanged',
+      },
+      /**
+       * Define how master and detail areas are shown next to each other,
+       * and the way how size and min-size properties are applied to them.
+       * Possible values are: `horizontal` or `vertical`.
+       * Defaults to horizontal.
+       */
+      orientation: {
+        type: String,
+        value: 'horizontal',
+        reflectToAttribute: true,
+        observer: '__orientationChanged',
+        sync: true,
+      },
+      /**
+       * When specified, forces the layout to use overlay mode, even if
+       * there is enough space for master and detail to be shown next to
+       * each other using the default (split) mode.
+       *
+       * @attr {boolean} force-overlay
+       */
+      forceOverlay: {
+        type: Boolean,
+        value: false,
+        observer: '__forceOverlayChanged',
+        sync: true,
+      },
+      /**
+       * Defines the containment of the detail area when the layout is in
+       * overlay mode. When set to `layout`, the overlay is confined to the
+       * layout. When set to `viewport`, the overlay is confined to the
+       * browser's viewport. Defaults to `layout`.
+       */
+      containment: {
+        type: String,
+        value: 'layout',
+        reflectToAttribute: true,
+        sync: true,
+      },
+      /**
+       * The threshold (in CSS length units) at which the layout switches to
+       * the "stack" mode, making detail area fully cover the master area.
+       *
+       * @attr {string} stack-threshold
+       */
+      stackThreshold: {
+        type: String,
+        observer: '__stackThresholdChanged',
+        sync: true,
+      },
+      /**
+       * When true, the layout does not use animated transitions for the detail area.
+       *
+       * @attr {boolean} no-animation
+       */
+      noAnimation: {
+        type: Boolean,
+        value: false,
+      },
+      /**
+       * When true, the component uses the overlay mode. This property is read-only.
+       * In order to enforce the overlay mode, use `forceOverlay` property.
+       * @protected
+       */
+      _overlay: {
+        type: Boolean,
+        attribute: 'overlay',
+        reflectToAttribute: true,
+        sync: true,
+      },
+      /**
+       * When true, the component uses the stack mode. This property is read-only.
+       * In order to enforce the stack mode, use `stackThreshold` property.
+       * @protected
+       */
+      _stack: {
+        type: Boolean,
+        attribute: 'stack',
+        reflectToAttribute: true,
+        sync: true,
+      },
+      /**
+       * When true, the component has the detail content provided.
+       * @protected
+       */
+      _hasDetail: {
+        type: Boolean,
+        attribute: 'has-detail',
+        reflectToAttribute: true,
+        sync: true,
+      },
+    };
+  }
+  static get experimental() {
+    return true;
+  }
+  /** @override */
+  get slotStyles() {
+    return [transitionStyles];
+  }
+  /** @protected */
+  render() {
+    return html`
+      <div part="backdrop"></div>
+      <div id="master" part="master" ?inert="${this._hasDetail && this._overlay && this.containment === 'layout'}">
+        <slot></slot>
+      </div>
+      <div
+        id="detail"
+        part="detail"
+        role="${this._overlay || this._stack ? 'dialog' : nothing}"
+        aria-modal="${this._overlay && this.containment === 'viewport' ? 'true' : nothing}"
+      >
+        <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
+      </div>
+    `;
+  }
+  /** @private */
+  __onDetailSlotChange(e) {
+    const children = e.target.assignedNodes();
+    this._hasDetail = children.length > 0;
+    this.__detectLayoutMode();
+    // Move focus to the detail area when it is added to the DOM,
+    // in case if the layout is using overlay or stack mode.
+    if ((this.hasAttribute('overlay') || this.hasAttribute('stack')) && children.length > 0) {
+      const focusables = getFocusableElements(children[0]);
+      if (focusables.length) {
+        focusables[0].focus();
+      }
+    }
+  }
+  /**
+   * @protected
+   * @override
+   */
+  _onResize() {
+    this.__detectLayoutMode();
+  }
+  /** @private */
+  __detailSizeChanged(size, oldSize) {
+    this.__updateStyleProperty('detail-size', size, oldSize);
+    this.__detectLayoutMode();
+  }
+  /** @private */
+  __detailMinSizeChanged(size, oldSize) {
+    this.__updateStyleProperty('detail-min-size', size, oldSize);
+    this.__detectLayoutMode();
+  }
+  /** @private */
+  __masterSizeChanged(size, oldSize) {
+    this.__updateStyleProperty('master-size', size, oldSize);
+    this.__detectLayoutMode();
+  }
+  /** @private */
+  __masterMinSizeChanged(size, oldSize) {
+    this.__updateStyleProperty('master-min-size', size, oldSize);
+    this.__detectLayoutMode();
+  }
+  /** @private */
+  __orientationChanged(orientation, oldOrientation) {
+    if (orientation || oldOrientation) {
+      this.__detectLayoutMode();
+    }
+  }
+  /** @private */
+  __forceOverlayChanged(forceOverlay, oldForceOverlay) {
+    if (forceOverlay || oldForceOverlay) {
+      this.__detectLayoutMode();
+    }
+  }
+  /** @private */
+  __stackThresholdChanged(threshold, oldThreshold) {
+    if (threshold || oldThreshold) {
+      if (threshold) {
+        this.$.master.style.setProperty('--_stack-threshold', threshold);
+      } else {
+        this.$.master.style.removeProperty('--_stack-threshold');
+      }
+      this.__detectLayoutMode();
+    }
+  }
+  /** @private */
+  __updateStyleProperty(prop, size, oldSize) {
+    if (size) {
+      this.style.setProperty(`--_${prop}`, size);
+    } else if (oldSize) {
+      this.style.removeProperty(`--_${prop}`);
+    }
+    this.toggleAttribute(`has-${prop}`, !!size);
+  }
+  /** @private */
+  __detectLayoutMode() {
+    this._overlay = false;
+    this._stack = false;
+    if (this.forceOverlay) {
+      this._overlay = true;
+      return;
+    }
+    if (this.stackThreshold != null) {
+      // Set stack to true to disable masterMinSize and detailMinSize
+      // that would affect size measurements below when in split mode
+      this._stack = true;
+      const threshold = this.__getStackThresholdInPixels();
+      const size = this.orientation === 'vertical' ? this.offsetHeight : this.offsetWidth;
+      if (size > threshold) {
+        this._stack = false;
+      } else {
+        return;
+      }
+    }
+    if (!this._hasDetail) {
+      return;
+    }
+    if (this.orientation === 'vertical') {
+      this.__detectVerticalMode();
+    } else {
+      this.__detectHorizontalMode();
+    }
+  }
+  /** @private */
+  __detectHorizontalMode() {
+    const detailWidth = this.$.detail.offsetWidth;
+    // Detect minimum width needed by master content. Use max-width to ensure
+    // the layout can switch back to split mode once there is enough space.
+    // If there is master  size or min-size set, use that instead to force the
+    // overlay mode by setting `masterSize` / `masterMinSize` to 100%/
+    this.$.master.style.maxWidth = this.masterSize || this.masterMinSize || 'min-content';
+    const masterWidth = this.$.master.offsetWidth;
+    this.$.master.style.maxWidth = '';
+    // If the combined minimum size of both the master and the detail content
+    // exceeds the size of the layout, the layout changes to the overlay mode.
+    this._overlay = this.offsetWidth < masterWidth + detailWidth;
+    // Toggling the overlay resizes master content, which can cause document
+    // scroll bar to appear or disappear, and trigger another resize of the
+    // layout which can affect previous measurements and end up in horizontal
+    // scroll. Check if that is the case and if so, preserve the overlay mode.
+    if (this.offsetWidth < this.scrollWidth) {
+      this._overlay = true;
+    }
+  }
+  /** @private */
+  __detectVerticalMode() {
+    // Remove overlay attribute temporarily to detect if there is enough space
+    // for both areas so that layout could switch back to the split mode.
+    this._overlay = false;
+    const masterHeight = this.$.master.clientHeight;
+    // If the combined minimum size of both the master and the detail content
+    // exceeds the available height, the layout changes to the overlay mode.
+    if (this.offsetHeight < masterHeight + this.$.detail.clientHeight) {
+      this._overlay = true;
+    }
+  }
+  /** @private */
+  __getStackThresholdInPixels() {
+    const { backgroundPositionY } = getComputedStyle(this.$.master, '::before');
+    return parseFloat(backgroundPositionY);
+  }
+  /**
+   * Sets the detail element to be displayed in the detail area and starts a
+   * view transition that animates adding, replacing or removing the detail
+   * area. During the view transition, the element is added to the DOM and
+   * assigned to the `detail` slot. Any previous detail element is removed.
+   * When passing null as the element, the current detail element is removed.
+   *
+   * If the browser does not support view transitions, the respective updates
+   * are applied immediately without starting a transition. The transition can
+   * also be skipped using the `skipTransition` parameter.
+   *
+   * @param element the new detail element, or null to remove the current detail
+   * @param skipTransition whether to skip the transition
+   * @returns {Promise<void>}
+   * @protected
+   */
+  _setDetail(element, skipTransition) {
+    // Don't start a transition if detail didn't change
+    const currentDetail = this.querySelector('[slot="detail"]');
+    if ((element || null) === currentDetail) {
+      return Promise.resolve();
+    }
+    const updateSlot = () => {
+      // Remove old content
+      this.querySelectorAll('[slot="detail"]').forEach((oldElement) => oldElement.remove());
+      // Add new content
+      if (element) {
+        element.setAttribute('slot', 'detail');
+        this.appendChild(element);
+      }
+    };
+    if (skipTransition) {
+      updateSlot();
+      return Promise.resolve();
+    }
+    const hasDetail = !!currentDetail;
+    const transitionType = hasDetail && element ? 'replace' : hasDetail ? 'remove' : 'add';
+    return this._startTransition(transitionType, () => {
+      // Update the DOM
+      updateSlot();
+      // Finish the transition
+      this._finishTransition();
+    });
+  }
+  /**
+   * Starts a view transition that animates adding, replacing or removing the
+   * detail area. Once the transition is ready and the browser has taken a
+   * snapshot of the current layout, the provided update callback is called.
+   * The callback should update the DOM, which can happen asynchronously.
+   * Once the DOM is updated, the caller must call `_finishTransition`,
+   * which results in the browser taking a snapshot of the new layout and
+   * animating the transition.
+   *
+   * If the browser does not support view transitions, or the `noAnimation`
+   * property is set, the update callback is called immediately without
+   * starting a transition.
+   *
+   * @param transitionType
+   * @param updateCallback
+   * @returns {Promise<void>}
+   * @protected
+   */
+  _startTransition(transitionType, updateCallback) {
+    const useTransition = typeof document.startViewTransition === 'function' && !this.noAnimation;
+    if (!useTransition) {
+      updateCallback();
+      return Promise.resolve();
+    }
+    this.setAttribute('transition', transitionType);
+    this.__transition = document.startViewTransition(() => {
+      // Return a promise that can be resolved once the DOM is updated
+      return new Promise((resolve) => {
+        this.__resolveUpdateCallback = resolve;
+        // Notify the caller that the transition is ready, so that they can
+        // update the DOM
+        updateCallback();
+      });
+    });
+    return this.__transition.finished;
+  }
+  /**
+   * Finishes the current view transition, if any. This method should be called
+   * after the DOM has been updated to finish the transition and animate the
+   * change in the layout.
+   *
+   * @returns {Promise<void>}
+   * @protected
+   */
+  async _finishTransition() {
+    // Detect new layout mode after DOM has been updated
+    this.__detectLayoutMode();
+    if (!this.__transition) {
+      return Promise.resolve();
+    }
+    // Resolve the update callback to finish the transition
+    this.__resolveUpdateCallback();
+    await this.__transition.finished;
+    this.removeAttribute('transition');
+    this.__transition = null;
+    this.__resolveUpdateCallback = null;
+  }
+}
+defineCustomElement(MasterDetailLayout);
+export { MasterDetailLayout };

package/theme/lumo/vaadin-master-detail-layout-styles.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ import '@vaadin/vaadin-lumo-styles/color.js';

package/theme/lumo/vaadin-master-detail-layout-styles.js ADDED Viewed

@@ -0,0 +1,28 @@
+import '@vaadin/vaadin-lumo-styles/color.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+registerStyles(
+  'vaadin-master-detail-layout',
+  css`
+    :host(:is([overlay], [stack])) [part='detail'] {
+      background-color: var(--lumo-base-color);
+    }
+    :host([overlay]) [part='detail'] {
+      box-shadow: var(--lumo-box-shadow-s);
+    }
+    :host([overlay][orientation='horizontal']) [part='detail'] {
+      border-inline-start: 1px solid var(--lumo-contrast-10pct);
+    }
+    :host([overlay][orientation='vertical']) [part='detail'] {
+      border-block-start: 1px solid var(--lumo-contrast-10pct);
+    }
+    :host([overlay]) [part='backdrop'] {
+      background-color: var(--lumo-shade-20pct);
+    }
+  `,
+  { moduleId: 'lumo-master-detail-layout' },
+);