@acusti/dropdown 1.0.0-alpha.5 → 1.0.0-alpha.7

package/README.md

@@ -524,7 +524,11 @@ Placement is best customized in CSS instead of props. The component exposes
 CSS custom properties for the most common low-level placement controls:
 
 - `--uktdd-body-position-area`
-- `--uktdd-body-position-try-fallbacks`
+- `--uktdd-body-position-try-fallback-1` and
+  `--uktdd-body-position-try-fallback-2` (the two author fallbacks, tried
+  in order after the primary placement)
+- `--uktdd-body-fill-fallbacks` (the last-resort fill placements, tried
+  when the body fits nowhere at its natural size)
 - `--uktdd-body-gap` (space between the trigger and the body)
 - `--uktdd-body-min-height`
 - `--uktdd-body-min-width`
@@ -536,8 +540,8 @@ Example:
 ```css
 .settings-dropdown {
     --uktdd-body-position-area: block-end span-inline-start;
-    --uktdd-body-position-try-fallbacks:
-        --uktdd-top-end, --uktdd-bottom-start, --uktdd-top-start;
+    --uktdd-body-position-try-fallback-1: --uktdd-top-end;
+    --uktdd-body-position-try-fallback-2: --uktdd-bottom-start;
     --uktdd-body-gap: 8px;
 }
 
@@ -551,15 +555,17 @@ placement and sizing control when a product surface needs it.
 
 ### Changing the Default Direction
 
-`--uktdd-body-position-area` and `--uktdd-body-position-try-fallbacks`
-always change together. `--uktdd-body-position-area` is the primary
-placement, used whenever it fits in the viewport — that’s what actually
-determines the direction a dropdown opens by default. The fallbacks list is
-only consulted when the primary placement doesn’t fit, so overriding it
-alone changes nothing in the common case where the primary already fits.
-Overriding the primary alone works, but leaves behind a fallback cascade
-tuned for the old primary — in a cramped viewport, the dropdown can fall
-back toward the direction you just moved away from.
+`--uktdd-body-position-area` and its two fallback slots
+(`--uktdd-body-position-try-fallback-1`,
+`--uktdd-body-position-try-fallback-2`) always change together.
+`--uktdd-body-position-area` is the primary placement, used whenever it
+fits in the viewport — that’s what actually determines the direction a
+dropdown opens by default. The fallback slots are tried in order only when
+the primary placement doesn’t fit. Set all three together to ensure the
+menu behaves the way you want it to in all possible contexts. If the new
+direction has only one meaningful fallback (a centered menu, say), put it
+in slot 1 and set slot 2 to the shipped no-op `--uktdd-noop` so it doesn’t
+inherit that flip.
 
 The four `@position-try` blocks the component ships (`--uktdd-top-start`,
 `--uktdd-top-end`, `--uktdd-bottom-start`, `--uktdd-bottom-end`) are named
@@ -574,15 +580,21 @@ physical keyword on one axis with a logical one on the other — though
 `block-start`/`block-end` read as `top`/`bottom` in the near-universal
 horizontal-tb writing mode.
 
-Pick the row matching the direction you want, and set both variables to its
-pair:
+Pick the row matching the direction you want, and set the three CSS custom
+properties to the corresponding values:
 
-| Direction                           | `--uktdd-body-position-area`    | `--uktdd-body-position-try-fallbacks`                         |
-| ----------------------------------- | ------------------------------- | ------------------------------------------------------------- |
-| Bottom, start-aligned (the default) | `block-end span-inline-end`     | `--uktdd-top-start, --uktdd-bottom-end, --uktdd-top-end`      |
-| Bottom, end-aligned                 | `block-end span-inline-start`   | `--uktdd-top-end, --uktdd-bottom-start, --uktdd-top-start`    |
-| Top, start-aligned                  | `block-start span-inline-end`   | `--uktdd-bottom-start, --uktdd-top-end, --uktdd-bottom-end`   |
-| Top, end-aligned                    | `block-start span-inline-start` | `--uktdd-bottom-end, --uktdd-top-start, --uktdd-bottom-start` |
+| Direction                           | `--uktdd-body-position-area`    | `…try-fallback-1`      | `…try-fallback-2`      |
+| ----------------------------------- | ------------------------------- | ---------------------- | ---------------------- |
+| Bottom, start-aligned (the default) | `block-end span-inline-end`     | `--uktdd-top-start`    | `--uktdd-bottom-end`   |
+| Bottom, end-aligned                 | `block-end span-inline-start`   | `--uktdd-top-end`      | `--uktdd-bottom-start` |
+| Top, start-aligned                  | `block-start span-inline-end`   | `--uktdd-bottom-start` | `--uktdd-top-end`      |
+| Top, end-aligned                    | `block-start span-inline-start` | `--uktdd-bottom-end`   | `--uktdd-top-start`    |
+
+(The `…try-fallback-N` columns are `--uktdd-body-position-try-fallback-1`
+and `-2`.)
+
+The two Top rows should also flip the last-resort fill pair to match:
+`--uktdd-body-fill-fallbacks: --uktdd-fill-top, --uktdd-fill-bottom`.
 
 For example, to make a dropdown open upward and end-aligned (useful for a
 trigger pinned to the bottom of the viewport, near the inline-end edge):
@@ -590,11 +602,17 @@ trigger pinned to the bottom of the viewport, near the inline-end edge):
 ```css
 .bottom-toolbar-dropdown {
     --uktdd-body-position-area: block-start span-inline-start;
-    --uktdd-body-position-try-fallbacks:
-        --uktdd-bottom-end, --uktdd-top-start, --uktdd-bottom-start;
+    --uktdd-body-position-try-fallback-1: --uktdd-bottom-end;
+    --uktdd-body-position-try-fallback-2: --uktdd-top-start;
+    --uktdd-body-fill-fallbacks: --uktdd-fill-top, --uktdd-fill-bottom;
 }
 ```
 
+The last line flips the last-resort fill pair to match the recipe’s
+direction: when the body is too tall to fit anywhere at its natural size,
+it fills and scrolls on the upward side first (more on the fill pair
+below).
+
 See the [`DirectionRecipes` story][] for a live demo of all four.
 
 [`DirectionRecipes` story]:
@@ -604,9 +622,77 @@ The primary placement wins whenever the body fits there at its natural
 size, then the fallbacks are tried in order — the body opens in the
 direction you asked for as long as that side can hold it, and never flips
 to the opposite side just because the viewport happens to have more empty
-space there. Only when the body fits in none of those placements does it
-size itself to the block-axis space its preferred side has and let the
-content scroll, so it never overflows the viewport or covers the trigger.
+space there. Only when the body fits in none of those placements do the
+`--uktdd-body-fill-fallbacks` placements
+(`--uktdd-fill-bottom, --uktdd-fill-top` by default) take over: the body
+sizes itself to the block-axis space below the trigger — or above it,
+whichever the pair lists first that has room — and lets the content scroll,
+so it never overflows the viewport or covers the trigger. A dropdown that
+opens upward should flip the pair
+(`--uktdd-body-fill-fallbacks: --uktdd-fill-top, --uktdd-fill-bottom`) so
+the last-resort fill also prefers the upward side. In these fill placements
+the body spans the trigger (centered over it, shifted inward as needed to
+stay on-screen) rather than keeping the primary placement’s edge alignment.
+Submenus have their own last-resort fills
+([`--uktdd-submenu-fill-fallbacks`](#submenu-placement-and-styling)) that
+keep them beside the parent rather than covering it, so this pair applies
+to the body alone.
+
+In the fills, `--uktdd-body-min-height` marks a side as too cramped to
+bother with: a fill whose side is shorter than it is rejected so the
+roomier opposite side is tried. That floor is capped at the worst-case side
+— half the viewport minus the trigger, the most a vertically centered
+trigger can guarantee — so a min-height above half the viewport (honored in
+full by the named placements) can’t reject both fills: the body fills the
+roomier side and scrolls rather than overflowing.
+
+There are exactly two author fallback slots by design. The
+[CSS spec](https://drafts.csswg.org/css-anchor-position-1/#fallback-apply)
+requires implementations to support at least five position options,
+including the element’s base position, and `@acusti/dropdown` appends two
+last-resort placements to the end, so that leaves two fallbacks that you
+can specify, hence why they are exposed as two separate custom properties.
+The two default slots are the single-axis flips of the primary (a block
+flip and an inline flip); the mirror opposite diagonal is intentionally not
+a slot, so that a trigger crammed into the corner diagonal to the primary
+opening direction lands in a fill rather than a natural placement. See the
+[recipes above](#changing-the-default-direction) for different common
+placement scenarios. For a recipe with a single meaningful fallback (a
+centered menu, say), set slot 1 and leave slot 2 as the shipped no-op
+`--uktdd-noop`, so it doesn’t inherit the default’s flip.
+
+### Trading Trigger Coverage for a Full-Height Menu
+
+The block-side fills never cover the trigger, which bounds their height by
+where the trigger sits. When the body already fits horizontally, the opt-in
+`--uktdd-fill-cover` placement (in no default list) can trade that
+guarantee away: it keeps the strict start-aligned inline edge (compose
+`--uktdd-fill-cover flip-inline` for end alignment) and loosens the block
+axis instead, sizing the body to the viewport’s full block size — covering
+the trigger — so a too-tall menu gets the whole viewport to scroll in
+rather than one side of it.
+
+```css
+.tall-menu {
+    --uktdd-body-position-try-fallback-1: --uktdd-top-start;
+    --uktdd-body-position-try-fallback-2: --uktdd-bottom-end;
+    --uktdd-body-fill-fallbacks:
+        --uktdd-fill-cover, --uktdd-fill-bottom, --uktdd-fill-top;
+}
+```
+
+The cover fill is rejected whenever the body is too wide for the region
+between the trigger’s inline-start edge and the viewport edge, so the
+guaranteed pair still rescues corner triggers — but the pair must stay
+within the evaluation budget: with three fills you get at most two author
+fallback slots, for six position options total. That’s the ceiling every
+current engine clears (Chromium evaluates exactly six; Safari and Firefox
+go well beyond), though only five are spec-guaranteed — drop to one author
+fallback if you want the whole list within that floor. Two caveats: don’t
+use it on searchable dropdowns, since the body overlays the trigger’s input
+while open; and while the body covers the trigger, clicking the trigger’s
+position hits the body instead — dismiss with Escape or a click elsewhere
+outside.
 
 Use `--uktdd-body-gap` for the space between the trigger and the body. It
 is applied as a symmetric `margin-block`, so the gap lands on whichever
@@ -629,8 +715,8 @@ the menu size itself from its contents.
 ```css
 .avatar-menu {
     --uktdd-body-position-area: block-end span-inline-start;
-    --uktdd-body-position-try-fallbacks:
-        --uktdd-top-end, --uktdd-top-start, --uktdd-bottom-end;
+    --uktdd-body-position-try-fallback-1: --uktdd-top-end;
+    --uktdd-body-position-try-fallback-2: --uktdd-top-start;
 }
 ```
 
@@ -651,13 +737,17 @@ the trigger always overflows it — and `position-try` refuses to select a
 fallback that overflows, so a `bottom center` → `top center` setup never
 flips. `span-all` centers over the trigger identically but spans the full
 width, so it flips cleanly and clamps to the viewport near an edge. The
-menu opens below by default and flips above only when it doesn’t fit below;
-list the flipped fallback so that flip is available:
+menu opens below by default and flips above only when it doesn’t fit below.
+It has one meaningful fallback (the flipped centered placement), so set it
+in slot 1 and leave slot 2 as the no-op — otherwise slot 2 keeps the
+default’s corner flip and the menu can land off-center in a cramped
+viewport:
 
 ```css
 .centered-menu {
     --uktdd-body-position-area: bottom span-all;
-    --uktdd-body-position-try-fallbacks: --centered-menu-top;
+    --uktdd-body-position-try-fallback-1: --centered-menu-top;
+    --uktdd-body-position-try-fallback-2: --uktdd-noop;
 }
 
 /* define the flipped fallback in your own CSS */
@@ -778,7 +868,19 @@ it flush to the parent item’s edge across browsers. Placement custom
 properties follow the established naming scheme:
 
 - `--uktdd-submenu-position-area` (default: `inline-end span-block-end`)
-- `--uktdd-submenu-position-try-fallbacks`
+- `--uktdd-submenu-position-try-fallback` (default:
+  `--uktdd-submenu-inline-start`; a single slot, not a list)
+- `--uktdd-submenu-fill-fallbacks` (the last-resort fills for a submenu too
+  tall to open beside its parent at natural size; default
+  `--uktdd-submenu-fill, --uktdd-submenu-fill flip-inline` — a full-height
+  fill on each inline side that anchor-centers on the block axis, so the
+  submenu fills the viewport height beside the parent and scrolls rather
+  than covering the parent menu, the way macOS never covers a parent with
+  its submenu. Flip the pair for a submenu that opens `inline-start` by
+  default. A submenu wider than the space on either side of its parent is
+  the one case this default doesn’t handle; append
+  `--uktdd-fill-bottom, --uktdd-fill-top` here to restore the
+  parent-covering rescue if you need it)
 - `--uktdd-submenu-gap` (space between the parent item and the submenu;
   applied as a symmetric `margin-inline`, the inline-axis counterpart to
   `--uktdd-body-gap`, so it auto-reverses when the submenu flips to the