@vaadin/master-detail-layout 24.8.0-alpha3

package/README.md

@@ -0,0 +1,58 @@
+# @vaadin/master-detail-layout
+
+A web component for building UIs with a master (or primary) area and a detail (or secondary) area.
+
+```html
+<vaadin-master-detail-layout>
+  <div>Master content</div>
+  <div slot="detail">Detail content</div>
+</vaadin-master-detail-layout>
+```
+
+## Installation
+
+Install the component:
+
+```sh
+npm i @vaadin/master-detail-layout
+```
+
+Once installed, import the component in your application:
+
+```js
+import '@vaadin/master-detail-layout';
+```
+
+## Themes
+
+Vaadin components come with two built-in [themes](https://vaadin.com/docs/latest/styling), Lumo and Material.
+The [main entrypoint](https://github.com/vaadin/web-components/blob/main/packages/master-detail-layout/vaadin-master-detail-layout.js) of the package uses the Lumo theme.
+
+To use the Material theme, import the component from the `theme/material` folder:
+
+```js
+import '@vaadin/master-detail-layout/theme/material/vaadin-master-detail-layout.js';
+```
+
+You can also import the Lumo version of the component explicitly:
+
+```js
+import '@vaadin/master-detail-layout/theme/lumo/vaadin-master-detail-layout.js';
+```
+
+Finally, you can import the un-themed component from the `src` folder to get a minimal starting point:
+
+```js
+import '@vaadin/master-detail-layout/src/vaadin-master-detail-layout.js';
+```
+
+## Contributing
+
+Read the [contributing guide](https://vaadin.com/docs/latest/contributing) to learn about our development process, how to propose bugfixes and improvements, and how to test your changes to Vaadin components.
+
+## License
+
+Apache License 2.0
+
+Vaadin collects usage statistics at development time to improve this product.
+For details and to opt-out, see https://github.com/vaadin/vaadin-usage-statistics.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vaadin/master-detail-layout",
+  "version": "24.8.0-alpha3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Web component for building UIs with a master area and a detail area.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vaadin/web-components.git",
+    "directory": "packages/master-detail-layout"
+  },
+  "author": "Vaadin Ltd",
+  "homepage": "https://vaadin.com/components",
+  "bugs": {
+    "url": "https://github.com/vaadin/web-components/issues"
+  },
+  "main": "vaadin-master-detail-layout.js",
+  "module": "vaadin-master-detail-layout.js",
+  "type": "module",
+  "files": [
+    "src",
+    "theme",
+    "vaadin-*.d.ts",
+    "vaadin-*.js",
+    "web-types.json",
+    "web-types.lit.json"
+  ],
+  "keywords": [
+    "Vaadin",
+    "master-detail",
+    "web-components",
+    "web-component"
+  ],
+  "dependencies": {
+    "@vaadin/component-base": "24.8.0-alpha3",
+    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha3",
+    "@vaadin/vaadin-material-styles": "24.8.0-alpha3",
+    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha3",
+    "lit": "^3.0.0"
+  },
+  "devDependencies": {
+    "@vaadin/chai-plugins": "24.8.0-alpha3",
+    "@vaadin/testing-helpers": "^1.1.0",
+    "sinon": "^18.0.0"
+  },
+  "web-types": [
+    "web-types.json",
+    "web-types.lit.json"
+  ],
+  "gitHead": "8c49e2337a1905ae68d0d7aee2e672500ea72343"
+}

package/src/vaadin-master-detail-layout.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright (c) 2025 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+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';
+
+/**
+ * `<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.
+ */
+declare class MasterDetailLayout extends ResizeMixin(ThemableMixin(ElementMixin(HTMLElement))) {
+  /**
+   * 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: string | null | undefined;
+
+  /**
+   * 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: string | null | undefined;
+
+  /**
+   * 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.
+   * Setting `100%` enforces the overlay mode to be used by default.
+   *
+   * @attr {string} master-size
+   */
+  masterSize: string | null | undefined;
+
+  /**
+   * 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.
+   * Setting `100%` enforces the overlay mode to be used by default.
+   *
+   * @attr {string} master-min-size
+   */
+  masterMinSize: string | null | undefined;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-master-detail-layout': MasterDetailLayout;
+  }
+}
+
+export { MasterDetailLayout };

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

@@ -0,0 +1,266 @@
+/**
+ * @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 } from 'lit';
+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 { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.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.
+ *
+ * @customElement
+ * @extends HTMLElement
+ * @mixes ThemableMixin
+ * @mixes ElementMixin
+ * @mixes ResizeMixin
+ */
+class MasterDetailLayout extends 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'] {
+        display: none;
+      }
+
+      /* Overlay mode */
+      :host([overlay][has-detail]) {
+        position: relative;
+      }
+
+      :host([overlay]) [part='detail'] {
+        position: absolute;
+        inset-inline-end: 0;
+        height: 100%;
+        width: var(--_detail-min-size, min-content);
+        max-width: 100%;
+      }
+
+      :host([overlay]) [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'] {
+        width: var(--_master-size);
+        flex-shrink: 0;
+      }
+
+      :host([has-detail-size]) [part='detail'] {
+        width: var(--_detail-size);
+        flex-shrink: 0;
+      }
+
+      :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]:not([overlay])) [part='master'] {
+        min-width: var(--_master-min-size);
+      }
+
+      :host([has-detail-min-size]:not([overlay])) [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;
+      }
+    `;
+  }
+
+  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.
+       * Setting `100%` enforces the overlay mode to be used by default.
+       *
+       * @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.
+       * Setting `100%` enforces the overlay mode to be used by default.
+       *
+       * @attr {string} master-min-size
+       */
+      masterMinSize: {
+        type: String,
+        sync: true,
+        observer: '__masterMinSizeChanged',
+      },
+    };
+  }
+
+  /** @protected */
+  render() {
+    return html`
+      <div id="master" part="master">
+        <slot></slot>
+      </div>
+      <div id="detail" part="detail">
+        <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
+      </div>
+    `;
+  }
+
+  /** @private */
+  __onDetailSlotChange(e) {
+    this.toggleAttribute('has-detail', e.target.assignedNodes().length > 0);
+    this.__detectLayoutMode();
+  }
+
+  /**
+   * @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 */
+  __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() {
+    if (!this.hasAttribute('has-detail')) {
+      this.removeAttribute('overlay');
+      return;
+    }
+
+    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.
+    if (this.offsetWidth < masterWidth + detailWidth) {
+      this.setAttribute('overlay', '');
+    } else {
+      this.removeAttribute('overlay');
+    }
+
+    // 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.setAttribute('overlay', '');
+    }
+  }
+}
+
+defineCustomElement(MasterDetailLayout);
+
+export { MasterDetailLayout };

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

@@ -0,0 +1 @@
+import '../../src/vaadin-master-detail-layout.js';

package/theme/lumo/vaadin-master-detail-layout.js

@@ -0,0 +1 @@
+import '../../src/vaadin-master-detail-layout.js';

package/theme/material/vaadin-master-detail-layout.d.ts

@@ -0,0 +1 @@
+import '../../src/vaadin-master-detail-layout.js';

package/theme/material/vaadin-master-detail-layout.js

@@ -0,0 +1 @@
+import '../../src/vaadin-master-detail-layout.js';

package/vaadin-master-detail-layout.d.ts

@@ -0,0 +1 @@
+export * from './src/vaadin-master-detail-layout.js';

package/vaadin-master-detail-layout.js

@@ -0,0 +1,3 @@
+import './theme/lumo/vaadin-master-detail-layout.js';
+
+export * from './src/vaadin-master-detail-layout.js';

package/web-types.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json.schemastore.org/web-types",
+  "name": "@vaadin/master-detail-layout",
+  "version": "24.8.0-alpha3",
+  "description-markup": "markdown",
+  "contributions": {
+    "html": {
+      "elements": [
+        {
+          "name": "vaadin-master-detail-layout",
+          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.",
+          "attributes": [
+            {
+              "name": "detail-size",
+              "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "detail-min-size",
+              "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "master-size",
+              "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "master-min-size",
+              "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "theme",
+              "description": "The theme variants to apply to the component.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            }
+          ],
+          "js": {
+            "properties": [
+              {
+                "name": "detailSize",
+                "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "detailMinSize",
+                "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "masterSize",
+                "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.\nSetting `100%` enforces the overlay mode to be used by default.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "masterMinSize",
+                "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.\nSetting `100%` enforces the overlay mode to be used by default.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              }
+            ],
+            "events": []
+          }
+        }
+      ]
+    }
+  }
+}

package/web-types.lit.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json.schemastore.org/web-types",
+  "name": "@vaadin/master-detail-layout",
+  "version": "24.8.0-alpha3",
+  "description-markup": "markdown",
+  "framework": "lit",
+  "framework-config": {
+    "enable-when": {
+      "node-packages": [
+        "lit"
+      ]
+    }
+  },
+  "contributions": {
+    "html": {
+      "elements": [
+        {
+          "name": "vaadin-master-detail-layout",
+          "description": "`<vaadin-master-detail-layout>` is a web component for building UIs with a master\n(or primary) area and a detail (or secondary) area that is displayed next to, or\noverlaid on top of, the master area, depending on configuration and viewport size.",
+          "extension": true,
+          "attributes": [
+            {
+              "name": ".detailSize",
+              "description": "Fixed size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".detailMinSize",
+              "description": "Minimum size (in CSS length units) to be set on the detail area.\nWhen specified, it prevents the detail area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".masterSize",
+              "description": "Fixed size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from growing or\nshrinking. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".masterMinSize",
+              "description": "Minimum size (in CSS length units) to be set on the master area.\nWhen specified, it prevents the master area from shrinking below\nthis size. If there is not enough space to show master and detail\nareas next to each other, the layout switches to the overlay mode.\nSetting `100%` enforces the overlay mode to be used by default.",
+              "value": {
+                "kind": "expression"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  }
+}