feat: initialize master-detail-layout package (#8767)

web-padawan · web-flow · commit 83d08f94752a · 2025-03-12T15:30:56.000+02:00
diff --git a/dev/master-detail-layout.html b/dev/master-detail-layout.html
@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Master Detail Layout</title>
+    <script type="module" src="./common.js"></script>
+
+    <script type="module">
+      import '@vaadin/master-detail-layout';
+    </script>
+  </head>
+
+  <body>
+    <vaadin-master-detail-layout>
+      <div>Master content</div>
+      <div slot="detail">Detail content</div>
+    </vaadin-master-detail-layout>
+  </body>
+</html>
diff --git a/packages/master-detail-layout/README.md b/packages/master-detail-layout/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.
diff --git a/packages/master-detail-layout/package.json b/packages/master-detail-layout/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@vaadin/master-detail-layout",
+  "version": "24.8.0-alpha2",
+  "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-alpha2",
+    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha2",
+    "@vaadin/vaadin-material-styles": "24.8.0-alpha2",
+    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha2",
+    "lit": "^3.0.0"
+  },
+  "devDependencies": {
+    "@vaadin/chai-plugins": "24.8.0-alpha2",
+    "@vaadin/testing-helpers": "^1.1.0",
+    "sinon": "^18.0.0"
+  },
+  "web-types": [
+    "web-types.json",
+    "web-types.lit.json"
+  ]
+}
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.d.ts b/packages/master-detail-layout/src/vaadin-master-detail-layout.d.ts
@@ -0,0 +1,22 @@
+/**
+ * @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 { 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 ThemableMixin(ElementMixin(HTMLElement)) {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-master-detail-layout': MasterDetailLayout;
+  }
+}
+
+export { MasterDetailLayout };
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.js b/packages/master-detail-layout/src/vaadin-master-detail-layout.js
@@ -0,0 +1,54 @@
+/**
+ * @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 { 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
+ */
+class MasterDetailLayout extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+  static get is() {
+    return 'vaadin-master-detail-layout';
+  }
+
+  static get styles() {
+    return css`
+      :host {
+        display: block;
+      }
+
+      :host([hidden]) {
+        display: none !important;
+      }
+    `;
+  }
+
+  /** @protected */
+  render() {
+    return html`
+      <div part="master">
+        <slot></slot>
+      </div>
+      <div part="detail">
+        <slot name="detail"></slot>
+      </div>
+    `;
+  }
+}
+
+defineCustomElement(MasterDetailLayout);
+
+export { MasterDetailLayout };
diff --git a/packages/master-detail-layout/test/dom/__snapshots__/master-detail-layout.test.snap.js b/packages/master-detail-layout/test/dom/__snapshots__/master-detail-layout.test.snap.js
@@ -0,0 +1,15 @@
+/* @web/test-runner snapshot v1 */
+export const snapshots = {};
+
+snapshots["vaadin-master-detail-layout shadow default"] = 
+`<div part="master">
+  <slot>
+  </slot>
+</div>
+<div part="detail">
+  <slot name="detail">
+  </slot>
+</div>
+`;
+/* end snapshot vaadin-master-detail-layout shadow default */
+
diff --git a/packages/master-detail-layout/test/dom/master-detail-layout.test.js b/packages/master-detail-layout/test/dom/master-detail-layout.test.js
@@ -0,0 +1,17 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync } from '@vaadin/testing-helpers';
+import '../../src/vaadin-master-detail-layout.js';
+
+describe('vaadin-master-detail-layout', () => {
+  let layout;
+
+  beforeEach(() => {
+    layout = fixtureSync('<vaadin-master-detail-layout></vaadin-master-detail-layout>');
+  });
+
+  describe('shadow', () => {
+    it('default', async () => {
+      await expect(layout).shadowDom.to.equalSnapshot();
+    });
+  });
+});
diff --git a/packages/master-detail-layout/test/master-detail-layout.test.js b/packages/master-detail-layout/test/master-detail-layout.test.js
@@ -0,0 +1,32 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync } from '@vaadin/testing-helpers';
+import '../vaadin-master-detail-layout.js';
+
+describe('vaadin-master-detail-layout', () => {
+  let layout;
+
+  beforeEach(() => {
+    layout = fixtureSync(`
+      <vaadin-master-detail-layout>
+        <div>Master content</div>
+        <div slot="detail">Detail content</div>
+      </vaadin-master-detail-layout>
+    `);
+  });
+
+  describe('custom element definition', () => {
+    let tagName;
+
+    beforeEach(() => {
+      tagName = layout.tagName.toLowerCase();
+    });
+
+    it('should be defined in custom element registry', () => {
+      expect(customElements.get(tagName)).to.be.ok;
+    });
+
+    it('should have a valid static "is" getter', () => {
+      expect(customElements.get(tagName).is).to.equal(tagName);
+    });
+  });
+});
diff --git a/packages/master-detail-layout/test/typings/master-detail-layout.types.ts b/packages/master-detail-layout/test/typings/master-detail-layout.types.ts
@@ -0,0 +1,11 @@
+import '../../vaadin-master-detail-layout.js';
+import type { ElementMixinClass } from '@vaadin/component-base/src/element-mixin.js';
+import type { ThemableMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+const assertType = <TExpected>(value: TExpected) => value;
+
+const layout = document.createElement('vaadin-master-detail-layout');
+
+// Mixins
+assertType<ElementMixinClass>(layout);
+assertType<ThemableMixinClass>(layout);
diff --git a/packages/master-detail-layout/theme/lumo/vaadin-master-detail-layout.js b/packages/master-detail-layout/theme/lumo/vaadin-master-detail-layout.js
@@ -0,0 +1 @@
+import '../../src/vaadin-master-detail-layout.js';
diff --git a/packages/master-detail-layout/theme/material/vaadin-master-detail-layout.js b/packages/master-detail-layout/theme/material/vaadin-master-detail-layout.js
@@ -0,0 +1 @@
+import '../../src/vaadin-master-detail-layout.js';
diff --git a/packages/master-detail-layout/vaadin-master-detail-layout.d.ts b/packages/master-detail-layout/vaadin-master-detail-layout.d.ts
@@ -0,0 +1 @@
+export * from './src/vaadin-master-detail-layout.js';
diff --git a/packages/master-detail-layout/vaadin-master-detail-layout.js b/packages/master-detail-layout/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';
