## Background
### Problem summary
Some components, notably Menu and the future Popup, have an element that need special sizing and positioning treatment, both when initially displayed and in reaction to changes and interactions like scroll and window resize. These elements sit above the rest of the UI ("float"), and must be properly positioned relative to their triggering element, and sized so that they are fully visible ("clipped").
Currently, the Menu component's root element is positioned absolutely at its natural vertical position relative to the container that wraps its triggering element (the Select handle or Lookup text input) and the Menu itself, with a `left` value of 0 (or `right` in RTL). The Menu is rendered in its natural place in the DOM.
Although we have no comprehensive sizing or positioning solution at this time, we have created a solution for menu components in dialogs.
#### Menu components in Dialogs
When the Dialog component was introduced, we knew that menus would need to be able to extend past the end of the Dialog, e.g. if you open a Select menu that is longer than the space it has before the edge of the dialog body:
{F37645315}
This works as long as the dialog body is not scrollable (see remaining bugs below) by doing the following in components that have menus:
- Setting `position: static` on the root element, so that the menu will be positioned relative to the dialog backdrop instead
- Finding the current width of the root element
- Applying that width to the menu, plus `left: auto` for horizontal alignment with the parent component
- Using [[ https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver | ResizeObserver ]] to recalculate that width when the root element is resized or the template ref changes
#### Remaining bugs
##### Menu positioning in scrollable dialogs
T344542 details a significant shortcoming of the above solution: when the dialog body is scrollable, the menu position does not change, so it becomes visually "detached" from its trigger element. See [[ https://phabricator.wikimedia.org/T344542#9111910 | this comment ]] for a video demonstration. The menu should "float" along with its triggering element on scroll.
##### Menu extends past the edge of the viewport
T344776 demonstrates what happens when you open a Select that is near the bottom of the viewport: the menu extends beyond the edge of the viewport, so you have to scroll to read it:
{F37618883}
There are two options to improve the UX here:
1. Change the vertical position of the menu ("flip") so that it appears to open up above the triggering element instead of down below it
2. Clip the menu so that it fits in the space available between the triggering element and the edge of the viewport
In cases like this, OOUI seems to prefer flipping menus but clipping popups.
### Requirements
**Menus and popups should:**
1. Always remain "attached" to their triggering element
2. Always have an appropriate width (e.g. in most cases, menus are the width of their triggering element)
3. Always be fully visible within the viewport and not extend past it
4. Be able to extend past the bounds of their container
**This should all work:**
- With the menu or popup attached in any direction (see the FloatableElement test on the [[ https://doc.wikimedia.org/oojs-ui/master/demos/?page=dialogs&theme=wikimediaui&direction=ltr&platform=desktop | OOUI dialog demo page ]])
- With a static "footer" element under the menu or popup
- With scrolling
- With window resizing
- In LTR and RTL
## OOUI support
OOUI supports the above requirements through two mixins: ClippableElement and FloatableElement.
### ClippableElement
Clippable elements can be automatically clipped to visible boundaries, first when the element is mounted to the DOM, then in response to scroll or resize. Any time the natural height changes, `ClippableElement.clip()` must be run to make sure the clippable element is still properly sized.
It's possible to have a clippable element and a statically-sized element (e.g. footer) inside a clippable container: when the clippable container is resized, the static element won't change, but the clippable element will.
Along with `height`, this mixin also sets a `max-height` to control for situations where calling `ClippableElement.clip()` isn't possible, e.g. if an element outside of this context changes.
How it works:
- The parent element runs `ClippableElement.toggleClipping()` to turn clipping on or off. When clipping is on, this method sets up some necessary references (like the closest scrollable container) and scroll and resize handlers, and runs `.clip()` for an initial resize. When clipping is off, those references and the event listeners are removed. For example, MenuSelectWidget turns clipping on when the menu is visible, and off when it is not.
- The main `clip()` method figures out the clippable element's "scrollable container," which may be the body or html element, and gets its bounding client rect, accounting for:
- Scrollbar gutter
- A 7px buffer, meant to head off single-pixel miscalculations and allow room for drop shadows
- Determines if there's anything inside the clippable container besides the clippable element and, if so, accounts for its dimensions
- Extends the clippable element's rectangle to its maximum size, to account for the fact that it might have been clipped before
- Figures out the allotted width and height, based on the max size of the clippable element and the viewport size
- Determines if it needs to clip the width and/or height, based on whether the allotted sizes are different than the natural sizes.
- If so, sets the sizes and max sizes, with code/reflows that account for browser bugs related to scrollbars
Directionality considerations:
- The element is horizontally clipped on the side opposite its "anchor" edge
- The scrollbar can be on either size depending on reading direction
### FloatableElement
FloatableElements stick to a specified container, even when inserted elsewhere in the document (like an overlay). The element's position is automatically calculated and maintained on window resize or page scroll, and you can manually reposition when you make your own changes. FloatableElements can be attached to any side of their container (vertically: below, above, top, bottom, or center; horizontally: before, after, start, end, or center).
By default FloatableElements should not be out of view, but you can configure them to allow this.
How it works:
- Similar to ClippableElement, the parent element runs `FloatableElement.togglePositioning()` to toggle positioning on or off. When on, this sets up data like the closest scrollable container, adds handlers for resize and scroll, and runs `.position()` for an initial reposition. When off, the data and event handlers are unset.
- `verticalPosition` and `horizontalPosition` are passed in by the parent
- The main `.position()` method does a bunch of checks to make sure it can/should run, then sets CSS positioning rules on the floatable element. It also runs `this.clip()` if the element is also clippable.
- The positioning rules are calculated as follows:
- Find the offsetParent and see if its scrollable horizontally and/or vertically
- Calculate scrollbar widths
- Find the position values of the container by looking at the offsetParent, seeing if its scrollable and accounting for scrollbar widths, and determining the container's relative position
- Depending on the `verticalPosition` and `horizontalPosition`, set the floatable element's new position to align with the container
- Account for scroll position and scrollbar gutter
Directionality considerations:
- Start and end positions are flipped in RTL. This affects positioning and scrollbar offsets
## Modern tools
The OOUI mixins described above were developed 10 years ago, before some of the tools listed below existed or had sufficient browser support. Some parts of the OOUI implementation could be swapped out for browser APIs, and we could consider using external libraries.
Browser APIs:
- **[[ https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API | IntersectionObserver ]]**: A browser API that can detect when an element intersects with an ancestor element or the viewport. Codex already has a `useIntersectionObserver` composable that reports whether the provided template ref is visible.
- **[[ https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver | ResizeObserver ]]**: A browser API that reports changes to an element's dimensions. Codex already has a `useResizeObserver` composable that reports changes to a provided template ref's dimensions.
- (more?)
External libraries:
- **[[ https://floating-ui.com/ | FloatingUI ]]**: A JavaScript library with Vue bindings that positions and resizes floating elements
- (more?)
See Eric's demo of the [[ https://gerrit.wikimedia.org/r/c/design/codex/+/953740 | FloatingUI library applied to the Select component ]], which fixes the "detached menu" bug documented above.
---
## Acceptance criteria
- [] Finalize requirements
- [] Decide whether to consider relying on third party libraries
- [] If so, consider which library(ies) to use and what supplementary functionality is needed (e.g. additional RTL support)
- [] If a home-grown solution is needed wholly or in part, determine its architecture
- [] Document next steps in Phabricator, separating out work that is necessary to resolve [[ T344542 | this 1.0 blocker ]] from [[ T344776 | this less-urgent bug ]] if possible