@vaadin/master-detail-layout 25.1.2 → 25.2.0-alpha10

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,53 @@ 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-master`           | Set when the master area expands to fill available space.
+ * `expand-detail`           | Set when the detail area expands to fill available space.
+ * `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 `page`.
  *
  * The following custom CSS properties are available for styling:
  *
@@ -53,53 +79,44 @@ 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. When there is not enough space to show
+   * master and detail areas next to each other, the detail area
+   * is shown as an overlay.
+   * <p>
+   * If not specified, the size is determined automatically by measuring
+   * the detail content in a `min-content` CSS grid column when it first
+   * becomes visible, and then caching the resulting intrinsic size. To
+   * recalculate the cached intrinsic size, use the `recalculateLayout`
+   * method.
    *
    * @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 +126,33 @@ 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
+   * layout. When set to `page`, the overlay is confined to the
    * browser's viewport. Defaults to `layout`.
+   *
+   * @attr {string} overlay-containment
    */
-  containment: 'layout' | 'viewport';
+  overlayContainment: 'layout' | 'page';
 
   /**
-   * 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.
+   * When true, the master area grows to fill the available space.
+   * If `expandDetail` is also true, both areas share the available
+   * space equally.
    *
-   * In order to enforce the stack mode, use this property together with
-   * `forceOverlay` property and set both to `true`.
+   * @attr {boolean} expand-master
+   */
+  expandMaster: boolean;
+
+  /**
+   * When true, the detail area grows to fill the available space.
+   * If `expandMaster` is also true, both areas share the available
+   * space equally.
    *
-   * @attr {string} stack-threshold
+   * @attr {boolean} expand-detail
    */
-  stackOverlay: boolean;
+  expandDetail: boolean;
 
   /**
    * When true, the layout does not use animated transitions for the detail area.
@@ -149,6 +161,30 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    */
   noAnimation: boolean;
 
+  /**
+   * When true, the layout forces the detail area to be shown as an overlay,
+   * 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: boolean;
+
+  /**
+   * When `detailSize` is not explicitly set, re-measures the cached intrinsic size of
+   * the detail content by placing it in a min-content CSS grid column, then repeats
+   * this process for ancestor master-detail layouts without an explicit `detailSize`,
+   * if any, so that their detail areas also adapt.
+   *
+   * Call this method after changing the detail content in a way that affects its intrinsic
+   * size — for example, when opening a detail in a nested master-detail layout that was
+   * not previously visible.
+   *
+   * NOTE: This method can be expensive in large layouts as it triggers consecutive
+   * synchronous DOM reads and writes.
+   */
+  recalculateLayout(): void;
+
   addEventListener<K extends keyof MasterDetailLayoutEventMap>(
     type: K,
     listener: (this: MasterDetailLayout, ev: MasterDetailLayoutEventMap[K]) => void,