@vaadin/master-detail-layout 25.1.0 → 25.2.0-alpha2

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

@@ -4,8 +4,6 @@
  * 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 { SlotStylesMixin } from '@vaadin/component-base/src/slot-styles-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 export interface MasterDetailLayoutCustomEventMap {
@@ -21,25 +19,52 @@ export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterD
  * (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.
  *
+ * ### Slots
+ *
+ * The component has two main content areas: the master area (default slot)
+ * and the detail area (`detail` slot). When the detail doesn't fit next to
+ * the master, it is shown as an overlay on top of the master area:
+ *
+ * ```html
+ * <vaadin-master-detail-layout>
+ *   <div>Master content</div>
+ *   <div slot="detail">Detail content</div>
+ * </vaadin-master-detail-layout>
+ * ```
+ *
+ * The component also supports a `detail-placeholder` slot for content shown
+ * in the detail area when no detail is selected. Unlike the `detail` slot,
+ * the placeholder is simply hidden when it doesn't fit next to the master area,
+ * rather than shown as an overlay:
+ *
+ * ```html
+ * <vaadin-master-detail-layout>
+ *   <div>Master content</div>
+ *   <div slot="detail-placeholder">Select an item</div>
+ * </vaadin-master-detail-layout>
+ * ```
+ *
  * ### Styling
  *
  * The following shadow DOM parts are available for styling:
  *
- * Part name      | Description
- * ---------------|----------------------
- * `backdrop`     | Backdrop covering the master area in the drawer mode
- * `master`       | The master area
- * `detail`       | The detail area
+ * Part name             | Description
+ * ----------------------|----------------------
+ * `backdrop`            | Backdrop covering the master area in the overlay mode
+ * `master`              | The master area
+ * `detail`              | The detail area
+ * `detail-placeholder`  | The detail placeholder 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.
- * `drawer`       | Set when the layout is using the drawer mode.
- * `stack`        | Set when the layout is using the stack mode.
+ * Attribute                 | Description
+ * --------------------------|----------------------
+ * `expand`                  | Set to `master`, `detail`, or `both`.
+ * `orientation`             | Set to `horizontal` or `vertical` depending on the orientation.
+ * `has-detail`              | Set when the detail content is provided and visible.
+ * `has-detail-placeholder`  | Set when the detail placeholder content is provided.
+ * `overlay`                 | Set when columns don't fit and the detail is shown as an overlay.
+ * `overlay-containment`     | Set to `layout` or `viewport`.
  *
  * The following custom CSS properties are available for styling:
  *
@@ -53,53 +78,38 @@ export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterD
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
- * @fires {CustomEvent} backdrop-click - Fired when the user clicks the backdrop in the drawer mode.
+ * @fires {CustomEvent} backdrop-click - Fired when the user clicks the backdrop in the overlay mode.
  * @fires {CustomEvent} detail-escape-press - Fired when the user presses Escape in the detail area.
  */
-declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMixin(ElementMixin(HTMLElement)))) {
+declare class MasterDetailLayout extends 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 details are shown as an overlay:
-   * either as drawer or stack, depending on the `stackOverlay` property.
+   * Size (in CSS length units) to be set on the detail area in
+   * the CSS grid layout. If there is not enough space to show
+   * master and detail areas next to each other, the detail area
+   * is shown as an overlay. Defaults to 15em.
    *
    * @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 details are shown as an overlay:
-   * either as drawer or stack, depending on the `stackOverlay` property.
-   *
-   * @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 details are shown as an overlay:
-   * either as drawer or stack, depending on the `stackOverlay` property.
+   * Size (in CSS length units) to be set on the master area in
+   * the CSS grid layout. If there is not enough space to show
+   * master and detail areas next to each other, the detail area
+   * is shown as an overlay. Defaults to 30em.
    *
    * @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 details are shown as an overlay:
-   * either as drawer or stack, depending on the `stackOverlay` property.
+   * Size (in CSS length units) for the detail area when shown as an
+   * overlay. When not set, falls back to `detailSize`. Set to `100%`
+   * to make the detail cover the full layout.
    *
-   * @attr {string} master-min-size
+   * @attr {string} overlay-size
    */
-  masterMinSize: string | null | undefined;
+  overlaySize: string | null | undefined;
 
   /**
    * Define how master and detail areas are shown next to each other,
@@ -109,38 +119,22 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    */
   orientation: 'horizontal' | 'vertical';
 
-  /**
-   * When specified, forces the details to be shown as an overlay
-   * (either as drawer or stack), even if there is enough space for
-   * master and detail to be shown next to each other using the default
-   * (split) mode.
-   *
-   * In order to enforce the stack mode, use this property together with
-   * `stackOverlay` property and set both to `true`.
-   *
-   * @attr {boolean} force-overlay
-   */
-  forceOverlay: boolean;
-
   /**
    * 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`.
+   *
+   * @attr {string} overlay-containment
    */
-  containment: 'layout' | 'viewport';
+  overlayContainment: 'layout' | 'viewport';
 
   /**
-   * When true, the layout in the overlay mode is rendered as a stack,
-   * making detail area fully cover the master area. Otherwise, it is
-   * rendered as a drawer and has a visual backdrop.
-   *
-   * In order to enforce the stack mode, use this property together with
-   * `forceOverlay` property and set both to `true`.
-   *
-   * @attr {string} stack-threshold
+   * Controls which column(s) expand to fill available space.
+   * Possible values: `'master'`, `'detail'`, `'both'`.
+   * Defaults to `'master'`.
    */
-  stackOverlay: boolean;
+  expand: 'master' | 'detail' | 'both';
 
   /**
    * When true, the layout does not use animated transitions for the detail area.