[RFC] Popup position

[bmdalex]

Popup position

We are currently implementing a Popup component (#150) and in the first version of the API we're still undecided how to define the position of the popup relative to its trigger element (the element that created the popup and offers relevant info about positioning it).

Problem description

In our terminology, element has four sides - start, end, top, bottom.

In current proposal that is introduced by #150 the popup's positioning is defined by the position prop, a string that can take the following values:

'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'before-start' | 'before' | 'before-end' | 'after-start' | 'after' | 'after-end'

As one can see, popup position consists of two words:

1. the first one defines popup position relative to trigger element:

• top
• bottom
• before
• after

2. the second one defines which side of the popup and trigger are aligned:

• start in top-start and bottom-start means start sides are aligned
• end in top-end and bottom-end means end sides are aligned
• start in before-start and after-start means top sides are aligned
• end in before-end and after-end means bottom sides are aligned

It is confusing that start and end are used for both vertical and horizontal alignment. This supports flex terminology (which uses start/end for both main and cross axis) as well as popper.js, but in Stardust context it collides with start and end which we use for left and right.

Other libraries examples

1. Popper.js popup

Valid placements are: 'auto' | 'top' | 'right' | 'bottom' | 'left'
Each placement can have a variation from this list: '-start' | '-end'

2. MDN web docs: Popup Guid: Positioning

Single Word Alignment Values	Example
before_start: The left side of the popup is aligned with the left side of the anchor, and the bottom of the popup is aligned along the top of the anchor. Equivalent to topleft bottomleft	​
before_end: The right side of the popup is aligned with the right side of the anchor, and the bottom of the popup is aligned along the top of the anchor. Equivalent to topright bottomright	​
after_start: The left side of the popup is aligned with the left side of the anchor, and the top of the popup is aligned along the bottom of the anchor. This value is commonly used for menu buttons. Equivalent to bottomleft topleft	​
after_end: The right side of the popup is aligned with the right side of the anchor, and the top of the popup is aligned along the bottom of the anchor. Equivalent to bottomright topright	​
start_before: The top edge of the popup is aligned with the top edge of the anchor, and the right side of the popup is aligned along the left side of the anchor. Equivalent to topleft topright	​
start_after: The bottom side of the popup is aligned with the bottom side of the anchor, and the right side of the popup is aligned along the left side of the anchor.  Equivalent to bottomleft bottomright	​
end_before: The top edge of the popup is aligned with the top edge of the anchor, and the left side of the popup is aligned along the right side of the anchor. This value is used for submenus. Equivalent to topright topleft	​
end_after: The bottom side of the popup is aligned with the bottom side of the anchor, and the left side of the popup is aligned along the right side of the anchor. Equivalent to bottomright bottomleft

3. Jquery popup overlay

1	2	3	4
horizontal	center' / 'left' / 'right' / 'leftedge' / 'rightedge'	'center'	Sets horizontal position. Options leftedge and rightedge can be used only for tooltips, and will align the tooltip to the left or right edge of the opening element (openelement).
--	--	--	--
vertical	'center' / 'top' / 'bottom' / 'topedge' / 'bottomedge'	'center'	Sets vertical position. Options topedge and bottomedge can be used only for tooltips, and will align the tooltip to the top or bottom edge of the opening element (openelement).

4. JqueryUI popup

(default: "center")
Type: String

Defines which position on the element being positioned to align with the target element: horizontal vertical alignment.

A single value such as right will be normalized to right center, top will be normalized to center top (following CSS convention). Acceptable horizontal values: left, center, right.

Acceptable vertical values: top, center, bottom. Example: left top or center center. Each dimension can also contain offsets, in pixels or percent, e.g., right+10 top-25%. Percentage offsets are relative to the element being positioned.

5. Tippyjs popup

A tooltip can be placed in four different ways in relation to its reference element. Additionally, the tooltip can be shifted:
'Top' | 'Bottom' | 'Left' | 'Right' | 'Top-Start' | 'Top-End'

6. Bootstrap popup

Four directions
Four options are available: 'top, right, bottom, and left aligned.

Proposed solutions

Proposal 1

Without checking other libraries, we introduce new terminology:

• for position: 'above' | 'below' | 'before' | 'after'
• for alignment: 'start' | 'end' | 'top' | 'bottom'
• add third word -aligned?

That results in combinations like:
position="above-start"
position="above-start-aligned"

Other ideas is renaming the prop to placement: that results in combinations like:
placement="above-start"
placement="above-start-aligned"

Proposal 2

Do we really need to combine the two into a single property? Wouldn't it make sense to leave them separate? Drawback is it allows conflicting combinations.

Proposal 3

Current proposal of #150

Proposal 4

See above: 2. MDN web docs: Popup Guid: Positioning

[levithomason]

Excellent write up, thanks! I would go with proposal 2, position prop and align prop. This is also consistent with other component props we have.

[levithomason]

Per our call, most agree with proposal 2 so let's start there.

[bmdalex]

implemented in #150