Dialog anchor positioning (draft)

rolfsmeds commented 1 month ago

Description

Automatic positioning of Dialog based on another element, including scroll-following, so that Dialog can be used as a generic popover component.

Use cases

Custom dropdown fields
Popups opened from buttons
Interactive toggletips

Acceptance criteria

[ ] API for designating another UI element as the anchor to which the Dialog is positioned.
- [ ] Flow API
- [ ] WC / React API
[ ] API for specifying how the Dialog is positioned relative to the anchor element (above, below, left, right, offset, alignment)
- [ ] Flow API
- [ ] WC / React API
[ ] Dialog theme variant that sets padding, border-radius and box-shadow more appropriate for popovers (e.g. popover)

Open questions

Should the target element automatically get an aria-controls attribute referencing the Dialog?
Should the popover theme variant be set automatically when anchor positioning is used?
Should focus automatically move to the dialog when opened?
Should modal be supported?
Should resizing and/or dragging be supported?

General criteria

[ ] APIs reviewed
[ ] Design
[ ] Performance
[ ] UX/DX tests in Alpha
[ ] Documentation:
[ ] How to test?
[ ] Limitations:

Security

[ ] Security implications have been taken into account (elaborate or link to product security requirement specification if there are implications)

knoobie commented 1 month ago

Custom dropdown fields Popups opened from buttons Interactive toggletips

From accessibility standpoint; the use cases are so different and probably need different markup.. so I feel like this needs separate components - even tho the dialog / overlay can be used as base. Meaning: Please create high level components for each use case in Java / React for better accessibility of the apps and hopefully better DX with appropriate names for each components.. could this also help your marketing with multiple components - even tho it's just the same; just with slightly different inner workings?

Examples: popup button with role menu

https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant/

and tooltips with role tooltips

https://github.com/w3c/aria-practices/issues/127#issuecomment-1039621115

as well custom field drop-down with role listbox https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/

Open Questions

All answers to those questions probably need clarification if you create a single component to rule them all.. or different components for each use case so that each use case can get their perfect roles and behavior.

TatuLund commented 1 month ago

I think this should not be a feature in Dialog, but introduced as a separate component ala Popup. Such component already exists in Directory https://vaadin.com/directory/component/popup and could be adopted as part of the official component set.

Also noting, that there are other things in wish list for Dialog like components, like full positioning API, which may introduce conflicts or interesting edge cases with feature like this.

Regarding the positioning API, I am also inclined not to include it in Dialog, but introduce extended new component, say Window, as I have drafted here: https://github.com/tatulund/mdi-demo

Fourth variant is a having a special Dialog that slides in either from left or right side of the view and stays on either side of the display. This kind of Dialog is often called OffCanvas in many design system. With positioning API naturally a Window can be substitute OffCanvas to some extent, but then usually lacks the wanted animation.

For me it is sounds like a better plan to have Dialog, Popup, Window and OffCanvas as separate components. That will eliminate odd combinations of API's that are incompatible. I.e. it is possible to maintain more coherent API's.

Example lets say we implement both the anchoring and positioning API's. If the developer applies both, which one should take precedence. The same applies to anchor vs. off-canvas functionality.

rolfsmeds commented 1 month ago

We are also considering building a separate overlay/popover component as well, but for now this would be a quick way to provide a way to create custom popovers in a significantly less problematic way (in terms of a11y etc) than the approach currently taken by most developers: abusing Context Menu as a generic overlay.

We already have a Tooltip component, action menu buttons (MenuBar, ContextMenu), and fields with dropdown lists (Select and ComboBox). This is not intended to replace any of those, so none of the associated accessibility semantics are relevant.

This is intended for overlays that have interactive content (thus not tooltips). This is intended as a generic popover, not list-dropdowns (since those are already covered by existing components).

As tooltips and traditional lists/menus are already covered, the missing piece is essentially any other overlay with whatever custom content developers might come up with. And the appropriate semantics for such a feature is role="dialog", which the Dialog already has, so I don't really see any problem with this from a semantics / accessibility POV (but I'd be happy to hear specific concerns).

As for DX, certainly, we could provide three different components based on the same underlying implementation, but when you start to consider the various ways in which e.g. a popover differs from a dialog, you quickly realize that there really aren't many factors that clearly belong in one and not the other. Anchor positioning is arguably one such thing, but I would not want to introduce a new component just for that. (I'd be happy to hear suggestions of what those components and their exclusive features would be, however, if you have other suggetions.)

As for conflicts between different positioning models, there are plenty of examples of features in components that do not make sense to be used simultaneously, so I don't feel that that is a reason to introduce new components. We can instead solve those by documentation, console warnings, exceptions, etc. And in most cases features like that are quite obviously mutually exclusive (as I would surely expect anchor vs static positioning to be).

rolfsmeds commented 1 month ago

Here are some examples of dialog-like popovers that this feature is intended to enable: _(Technically these could just as well be regular, statically positioned modals, but being positioned and aligned to the trigger element clearly has some UX advantages.)_