Description

A 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.

Tier

Free

License

Apache 2.0

Motivation

Background

Master-detail layouts are ubiquitous in modern business applications. Common examples include email clients where the master area contains a list of emails and the detail side displays the contents of the currently selected email.

Problem

Although master-detail layouts are superficially simple, it is far from trivial to implement them in a way that is

• responsive to the UI's size so that the way it's split between master and detail is optimized (e.g. by automatically rendering the detail area as an overlay if it doesn't fit side-by-side)
• accessible to ensure good usability on different devices and assistive technologies;
• router-integrated in that the application's URL is appropriately mapped to the state and contents of the details area, to enable bookmarking, correct back-button behavior, etc.

While the CRUD component does provide a master-detail layout solution, it is highly optimized for Grid+form use cases and doesn't cater well to other use cases.

Solution

A generic master-detail layout component that can be used for any content suited for a primary/secondary split UI, including, but not limited to, the master-detail pattern.

The layout, which can be horizontal or vertical, can be configured to render the detail area in three different ways:

• Split, where master and detail areas are displayed horizontally side by side [interactive illustration];
• Overlay, where the detail area is displayed as a modal overlay anchored to its side of the layout [interactive illustration];
• Stack, where the detail area is rendered as a modal overlay fully covering the master area [interactive illustration]

Additionally, the detail overlay (in overlay or stack modes) can be configured to render only over the master area, or over the entire viewport. (Due to limitations in the Safari version supported in V24, the latter has some limitations which need to be noted in the documentation. In V25 this limitation can be removed.)

The layout responsively "falls back" from split to overlay to stack, based on the space available in it and the minimum widths defined for the two areas.

The component can be used as a route layout in Flow and Hilla, so that the state (visibility and contents) of the detail area can be easily mapped to the URL for bookmarking, back-button support, etc.

In Stack and Overlay modes, keyboard focus automatically moves to the detail area when it is displayed.

The following accommodations are made for screen reader support:

• In Split mode, Master and Detail areas have role="region" and APIs for setting aria-label / aria-labelledby
• In Stack and Overlay modes, the detail area has role="dialog"
• When the detail overlay is configured to cover the entire viewport, the detail area has aria-modal="true". When configured to only cover the master area, the inert attribute is applied to the master area

Notes

• Master and Detail areas are not scroll containers (Scroller should be used for that instead)
• For easy integration with the routing mechanisms in Flow and Hilla, the visibility of the detail area is controlled by the presence of content inside it. (An explicit API may be provided for non-router use cases.)

Requirements

• Orientation toggle (horizontal / vertical)

• Detail area visibility toggling via API and/or presence of content

• APIs for setting the size and min-size of the two areas

• Split mode that responsively switches to Overlay

• Overlay mode that responsively switches to Stack

• Stack mode

• Containment modes: viewport / layout

• Part names and/or attributes for styling the master and detail areas and the current mode

• RTL support

• CSS animations / view transitions

• Lumo and Material styling (Aura styling can be added later)

• Documentation

Nice-to-haves

• User-resizable areas (like SplitLayout)
• Placeholder content in the detail area

Risks, limitations and breaking changes

Risks

No risks known at this point.

Limitations

• In V24, Overlay and Stack mode configured to cover the viewport (as opposed to just the master area) are limited by the stacking context within which the layout is rendered – if the stacking context doesn't cover the entire viewport, the positioning and modality of the overlay also doesn't cover the entire viewport. In V25 this limitation can be removed by refactoring all overlays to use the native popover feature.

Breaking changes

None, as this is a brand new component.

Out of scope

• Non-modal overlays were decided to be left out, at least for now, as modal overlays and split layouts serve most use cases far better;

Materials

• RFC: https://docs.google.com/document/d/1rcKkuLci6QJrY-b9kwSSGapkWNUPEiq2Rp12zLsfp8Y/edit?usp=sharing
• Feature request: MasterDetailLayout component web-components#7963

Metrics

Tracked metric: usage.
Success criteria: percentage of users reporting responsive layouting to be a challenge is reduced to at most 20% (cf. 26% in 2023Q4).

Pre-implementation checklist

• Estimated (estimate entered into Estimate custom field)
• Product Manager sign-off
• Engineering Manager sign-off

Pre-release checklist

• Documented (link to documentation provided in sub-issue or comment)
• UX/DX tests conducted and blockers addressed
• Approved for release by Product Manager