Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(AST-059): anchored layers flip before moving beside (#10257)

Cindy Zhang4ceed673bd4a
diff --git a/docs/specs/AST-059-layer-viewport-inset/spec.md b/docs/specs/AST-059-layer-viewport-inset/spec.md
index e45c49bc5f..3367acd28e 100644
--- a/docs/specs/AST-059-layer-viewport-inset/spec.md
+++ b/docs/specs/AST-059-layer-viewport-inset/spec.md
@@ -68,15 +68,15 @@ review_triggers: [layering, layout, behavior, public-api]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | The layer runtime owns the viewport inset: one gutter definition (FR1), one size cap — the viewport, never the span beside the trigger (FR2, FR3) — one standard fallback order and an anchor-clear order for a layer that keeps its anchor clear (FR4, FR5), and one place an app declares a persistent bar floating over a viewport edge: `LayerProvider`'s `inset`, read by anchored layers and the toast viewport alike (FR6, DEC-4, DEC-5). Popover is an application of the layer that adds styling on top (DEC-1). |
-| Behavior | A layer renders at its own size — the caller's explicit size, or its content's — up to the viewport minus its gutters, and never beyond: content that cannot fit the viewport overflows inside the layer, where the composing component scrolls or clips it (FR2, FR3). Content that can wrap fits beside the trigger by wrapping; a size that cannot shrink flips, and fitting neither side it keeps its size and slides along the alignment axis into view (FR4, DEC-2); a tooltip instead goes beside its trigger or to the roomier side (FR4). A layer whose anchor has left the viewport holds its position and its size (FR5, DEC-3). The first frame a layer paints is its settled frame; it never paints and then moves, save the keyboard cap's change that FR8 names. During a scroll, CSS places every anchored layer and the runtime does no layout work per scroll frame (FR4, FR8, DEC-7). |
-| End-user impact | A person who opens a 352px menu from a control near the edge of a panel gets a 352px menu, not a 274px one. A long menu on a phone keeps its labels readable instead of squeezing beside its trigger. A layer never ends under a phone navigation bar the app has declared (FR6). Nothing moves for an app that declares no bar. On a phone, a layer that would run under the software keyboard ends 10 px above it, its content scrolling (FR9). |
-| Builder impact | `Popover.width` and `DropdownMenu.menuWidth` become ordinary sizes. An app with a floating bar declares it once, as `inset` on the `LayerProvider` it already mounts, beside `toast`; toasts and anchored layers both clear it. Components that compose `useLayer` or `usePopover` inherit the gutter, the caps, and the fallbacks without a record change (FR7). |
-| Compatibility/readiness | Behavior change, one additive prop. An explicit size near an edge renders at its size instead of shrinking; unwrappable content near an edge flips or slides instead of overflowing its box; prose still wraps beside its trigger (DEC-2). Every anchor-mode layer gains the gutter and caps (FR7). `LayerProvider.inset` defaults to zero on every edge, so an app that declares none renders as before, with or without a provider; an existing `toast.inset` keeps its meaning (DEC-5). Authority: `current`, approved by the owner on 2026-10-03. |
-| Review checks | Reject a second definition of the viewport gutter outside the layer runtime; a `max-inline-size` resolved against the anchor's span; a layer box that can exceed the viewport on either axis; a fallback list authored by a component for an anchor-mode layer; a branch on whether a size was explicit; a slide that continues once the anchor has left the viewport; a `layer` theme target or a theme value standing in for an app's bar; a second place to declare the bar beside `LayerProvider.inset`; a consumer minimum that is not clamped by the runtime's cap; a layer under a default provider that renders differently from one with no provider; a geometry input read after paint and applied, except as FR8 permits; a layout read, forced layout, or forced new choice of option in a scroll path; an option in an anchor-clear list that can overlap its anchor; a story that asserts only settled geometry. |
-| Governing rules | [`architecture:layer-runtime`](../../architecture/layer-runtime.md) INV3, INV5 for anchor-mode placement, fallbacks, and direction, INV10 for what `LayerProvider` is; [`spec:AST-003`](../AST-003/spec.md) FR21–FR23 for the reduced behavior where CSS Anchor Positioning is absent; `component:Popover` FR4, ORD4 for Popover's conditional scrolling, which this record leaves in place. |
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | The layer runtime owns the viewport inset: one gutter definition (FR1), one size cap — the viewport, never the span beside the trigger (FR2, FR3) — one standard fallback order and an anchor-clear order for a layer that keeps its anchor clear (FR4, FR5), and one place an app declares a persistent bar floating over a viewport edge: `LayerProvider`'s `inset`, read by anchored layers and the toast viewport alike (FR6, DEC-4, DEC-5). Popover is an application of the layer that adds styling on top (DEC-1). |
+| Behavior | A layer renders at its own size — the caller's explicit size, or its content's — up to the viewport minus its gutters, and never beyond: content that cannot fit the viewport overflows inside the layer, where the composing component scrolls or clips it (FR2, FR3). Content that can wrap fits beside the trigger by wrapping; a size that cannot shrink flips, and fitting neither side it keeps its size and slides along the alignment axis into view (FR4, DEC-2); a tooltip instead flips to the opposite side, then goes beside its trigger, then to the roomier side (FR4). A layer whose anchor has left the viewport holds its position and its size (FR5, DEC-3). The first frame a layer paints is its settled frame; it never paints and then moves, save the keyboard cap's change that FR8 names. During a scroll, CSS places every anchored layer and the runtime does no layout work per scroll frame (FR4, FR8, DEC-7). |
+| End-user impact | A person who opens a 352px menu from a control near the edge of a panel gets a 352px menu, not a 274px one. A long menu on a phone keeps its labels readable instead of squeezing beside its trigger. A layer never ends under a phone navigation bar the app has declared (FR6). Nothing moves for an app that declares no bar. On a phone, a layer that would run under the software keyboard ends 10 px above it, its content scrolling (FR9). |
+| Builder impact | `Popover.width` and `DropdownMenu.menuWidth` become ordinary sizes. An app with a floating bar declares it once, as `inset` on the `LayerProvider` it already mounts, beside `toast`; toasts and anchored layers both clear it. Components that compose `useLayer` or `usePopover` inherit the gutter, the caps, and the fallbacks without a record change (FR7). |
+| Compatibility/readiness | Behavior change, one additive prop. An explicit size near an edge renders at its size instead of shrinking; unwrappable content near an edge flips or slides instead of overflowing its box; prose still wraps beside its trigger (DEC-2). Every anchor-mode layer gains the gutter and caps (FR7). `LayerProvider.inset` defaults to zero on every edge, so an app that declares none renders as before, with or without a provider; an existing `toast.inset` keeps its meaning (DEC-5). Authority: `current`, approved by the owner on 2026-10-03. |
+| Review checks | Reject a second definition of the viewport gutter outside the layer runtime; a `max-inline-size` resolved against the anchor's span; a layer box that can exceed the viewport on either axis; a fallback list authored by a component for an anchor-mode layer; a branch on whether a size was explicit; a slide that continues once the anchor has left the viewport; a `layer` theme target or a theme value standing in for an app's bar; a second place to declare the bar beside `LayerProvider.inset`; a consumer minimum that is not clamped by the runtime's cap; a layer under a default provider that renders differently from one with no provider; a geometry input read after paint and applied, except as FR8 permits; a layout read, forced layout, or forced new choice of option in a scroll path; an option in an anchor-clear list that can overlap its anchor; a story that asserts only settled geometry. |
+| Governing rules | [`architecture:layer-runtime`](../../architecture/layer-runtime.md) INV3, INV5 for anchor-mode placement, fallbacks, and direction, INV10 for what `LayerProvider` is; [`spec:AST-003`](../AST-003/spec.md) FR21–FR23 for the reduced behavior where CSS Anchor Positioning is absent; `component:Popover` FR4, ORD4 for Popover's conditional scrolling, which this record leaves in place. |
This table is a review projection; the body below is authoritative.
@@ -206,12 +206,14 @@ the app reaches every layer instead of the components that happen to read it.
from the edge it meets. A layer that keeps its anchor clear — Tooltip, which
the hover on its trigger keeps open — never settles over its anchor, and no
painted frame shows it there. An above or below layer of this kind uses one
- combined list in place of the order above: its preferred position, then
- beside the anchor on the inline end, then on the inline start, each at its
- content's inline size and capped to the viewport, then the opposite block
- side at its own size, and only then the preferred block side and the other,
- each only while it is the side with more room and sized to the room on that
- side. No option in the list lets the box overlap its anchor, at any scroll
+ combined list in place of the order above: its preferred position, then the
+ opposite block side at its own size (the flip), then beside the anchor on
+ the inline end, then on the inline start, each at its content's inline size
+ and capped to the viewport, and only then the preferred block side and the
+ other, each only while it is the side with more room and sized to the room
+ on that side. A fitting layer that loses room on its side flips to the
+ opposite side before it moves beside the trigger; it goes beside the trigger
+ only when neither its preferred side nor the flip fits. No option in the list lets the box overlap its anchor, at any scroll
position: an option that runs out of room overflows away from the anchor and
is never shifted onto it, because inside a scrolling panel Chrome does not
choose a layer's option again while the panel scrolls, so a layer that could
@@ -459,20 +461,20 @@ surface styling. A playground story with a draggable trigger and live width,
placement, and alignment controls exists for exploration; it is not evidence
for any row.
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR7 | One gutter module; a source scan for a second gutter or a `100%`-of-span cap among anchor-mode layers; story "the gutter" at both viewports | Default gutter at every edge; a wrapping layer beside a trigger flush with the edge | A second gutter constant among anchor-mode layers, or a layer inside the 16px gutter |
-| FR2 | Stories "explicit size near an edge (352px)", "content-sized, fits beside the trigger", "content-sized, does not fit beside the trigger", "neither side fits" at both viewports; clamp strings in Popover and DropdownMenu suites | 352px end-aligned on a trigger 45px from the edge; a short content-sized layer; an unbreakable run wider than a phone; a 1000px layer on a phone, where the cap is 358px | A layer narrower than `min(asked, cap)`, a layer box wider than the cap at any viewport, or `100%` of the anchor span in a cap |
-| FR3 | Story "taller than the viewport" at both viewports; the runtime's viewport-fit style on every anchor-mode layer | Content 2000px tall | The layer box's block size exceeds the viewport minus gutters |
-| FR4 | Stories "content-sized, does not fit beside the trigger", "trigger near an edge flips", "neither side fits", "trigger near the bottom flips above", "wide layer, trigger near the bottom" at both viewports | A flip to end alignment at content size and at an explicit size; a 1000px layer slid inside the gutters where it fits; a block flip with room only above; a block flip when the inline axis is also capped | A layer squeezed into the span, a flipped edge off the trigger's edge, a layer outside the gutters on either axis, or a layer left on the side with no room |
-| FR4, Tooltip | The `TooltipTallContent` and `TooltipTallContentTracking` real-engine suites (Chromium, WebKit) at 1280×720 and 390×700; the runtime's anchor-clear unit suite; a wheel and a keyboard pass over a fitting and a tall tooltip in Chromium, before and after | A 60-line tooltip mid-page (beside it); on a phone, trigger in the upper or lower half (roomier side); a fitting tooltip; content growth, host move, trigger move by layout, a page scroll and a scroll inside a scrolling panel that carry the trigger past an edge, window resize, replaced trigger; a wheel over a fitting tooltip and at the end of a tall one; Tab through a page that holds a fitting and a scrolling tooltip | Covers its trigger in any frame, including every frame of a scroll inside a panel; closes under a resting pointer, leaves the viewport, won't scroll, or a fitting tooltip moves; a wheel over a fitting tooltip does not scroll the page, or a tall tooltip's scroll does not chain to the page at its end; CSS `overflow-y: auto` adds a Tab stop in Chromium |
-| FR5 | Stories "anchor leaves the viewport" and "anchor already off-screen when the layer opens"; the runtime's anchor-visibility unit suite | Horizontal scroll carries the trigger out of view while the layer is open, then back; a layer opened with its anchor already off-screen | The layer slides toward the viewport edge after the anchor is gone, changes size, does not return with its anchor, or opens pinned to the edge |
-| FR6 | Stories "app-declared inset (floating bar)" and "layer portaled out of its JSX position"; `LayerProvider` and `ToastViewport` unit suites | An 80px bar declared as `inset={{blockEnd: 80}}`; a toast under the same provider; a `toast.inset` override; no provider; a layer hosted outside the paragraph it was rendered in | A layer or toast ends under the bar, an unset edge moves anything, a `toast.inset` edge stops overriding, no-provider geometry differs from the default provider's, or a portaled layer loses the inset |
-| FR8 | Every story above (first frame compared with settled); stories "inset changes while the layer is open", "layer opens in the frame the inset arrives", "inset measured by the app", "anchor already off-screen when the layer opens" | The provider's inset changes 80→160 with the layer open; a layer mounted open in the provider's first commit; a bar the app measures before paint and declares; an off-screen anchor at open | The first frame's rectangle differs from the settled one, or the first frame after a declaration change is not already at the new geometry |
-| FR4, FR8 scroll (DEC-7) | Before-and-after evidence in real Chromium for each of DEC-7's seven rows; a performance trace of a page scroll and a scroll inside a scrolling panel that carry a tooltip's trigger past the scroll edge, counting forced layouts per scroll frame before and after; the runtime's anchor-clear unit suite for when the don't-cover check runs | An open tooltip whose trigger a page scroll carries out of the page and back; the same inside a scrolling panel; the layer's show, a remount, a ResizeObserver report, and a window resize; a top-layer layer whose anchor leaves the page | A forced layout or layout read for a layer in a scroll frame other than one in which the anchor's visibility changes; a don't-cover check, `scroll` or `scrollend` read, or forced re-pick during a scroll; an observer of a trigger that moves without resizing; a layer that slides or vanishes instead of holding when its anchor leaves the page |
-| FR9 | `useLayerKeyboardClearance.test.tsx`; Popover's keyboard browser proofs in Chromium and WebKit with a stand-in keyboard; the iOS simulator | A tall Popover below its trigger with a field; a keyboard already up at the open; a short layer; a layer above its trigger | A capped layer ending under the keyboard or more than 10 px above it, an unreached layer that changes, a bottom-held layer that moves, or a layer measuring the keyboard itself |
-| FR10 | `useLayerKeyboardClearance.test.tsx`; Popover's keyboard browser proofs | A rising keyboard before and after it arrives; a falling keyboard; a keyboard that changes at once; a tap on Save as the keyboard falls | A cap written while the keyboard rises, kept as it falls, or taken off under a press before its click |
-| FR1 safe area | A device run: `env(safe-area-inset-*)` is set only by a real device and Chromium emulation does not populate it, so no Storybook story can show it. | Landscape phone with a notch on one side | A layer under the notch |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR7 | One gutter module; a source scan for a second gutter or a `100%`-of-span cap among anchor-mode layers; story "the gutter" at both viewports | Default gutter at every edge; a wrapping layer beside a trigger flush with the edge | A second gutter constant among anchor-mode layers, or a layer inside the 16px gutter |
+| FR2 | Stories "explicit size near an edge (352px)", "content-sized, fits beside the trigger", "content-sized, does not fit beside the trigger", "neither side fits" at both viewports; clamp strings in Popover and DropdownMenu suites | 352px end-aligned on a trigger 45px from the edge; a short content-sized layer; an unbreakable run wider than a phone; a 1000px layer on a phone, where the cap is 358px | A layer narrower than `min(asked, cap)`, a layer box wider than the cap at any viewport, or `100%` of the anchor span in a cap |
+| FR3 | Story "taller than the viewport" at both viewports; the runtime's viewport-fit style on every anchor-mode layer | Content 2000px tall | The layer box's block size exceeds the viewport minus gutters |
+| FR4 | Stories "content-sized, does not fit beside the trigger", "trigger near an edge flips", "neither side fits", "trigger near the bottom flips above", "wide layer, trigger near the bottom" at both viewports | A flip to end alignment at content size and at an explicit size; a 1000px layer slid inside the gutters where it fits; a block flip with room only above; a block flip when the inline axis is also capped | A layer squeezed into the span, a flipped edge off the trigger's edge, a layer outside the gutters on either axis, or a layer left on the side with no room |
+| FR4, Tooltip | The `TooltipTallContent` and `TooltipTallContentTracking` real-engine suites (Chromium, WebKit) at 1280×720 and 390×700; the runtime's anchor-clear unit suite; a wheel and a keyboard pass over a fitting and a tall tooltip in Chromium, before and after | A 60-line tooltip mid-page (beside it); a fitting tooltip whose side loses room in a scroll (it flips to the opposite side, not beside); on a phone, trigger in the upper or lower half (roomier side); a fitting tooltip; content growth, host move, trigger move by layout, a page scroll and a scroll inside a scrolling panel that carry the trigger past an edge, window resize, replaced trigger; a wheel over a fitting tooltip and at the end of a tall one; Tab through a page that holds a fitting and a scrolling tooltip | Moves beside its trigger while the flip to the opposite side fits; covers its trigger in any frame, including every frame of a scroll inside a panel; closes under a resting pointer, leaves the viewport, won't scroll, or a fitting tooltip moves; a wheel over a fitting tooltip does not scroll the page, or a tall tooltip's scroll does not chain to the page at its end; CSS `overflow-y: auto` adds a Tab stop in Chromium |
+| FR5 | Stories "anchor leaves the viewport" and "anchor already off-screen when the layer opens"; the runtime's anchor-visibility unit suite | Horizontal scroll carries the trigger out of view while the layer is open, then back; a layer opened with its anchor already off-screen | The layer slides toward the viewport edge after the anchor is gone, changes size, does not return with its anchor, or opens pinned to the edge |
+| FR6 | Stories "app-declared inset (floating bar)" and "layer portaled out of its JSX position"; `LayerProvider` and `ToastViewport` unit suites | An 80px bar declared as `inset={{blockEnd: 80}}`; a toast under the same provider; a `toast.inset` override; no provider; a layer hosted outside the paragraph it was rendered in | A layer or toast ends under the bar, an unset edge moves anything, a `toast.inset` edge stops overriding, no-provider geometry differs from the default provider's, or a portaled layer loses the inset |
+| FR8 | Every story above (first frame compared with settled); stories "inset changes while the layer is open", "layer opens in the frame the inset arrives", "inset measured by the app", "anchor already off-screen when the layer opens" | The provider's inset changes 80→160 with the layer open; a layer mounted open in the provider's first commit; a bar the app measures before paint and declares; an off-screen anchor at open | The first frame's rectangle differs from the settled one, or the first frame after a declaration change is not already at the new geometry |
+| FR4, FR8 scroll (DEC-7) | Before-and-after evidence in real Chromium for each of DEC-7's seven rows; a performance trace of a page scroll and a scroll inside a scrolling panel that carry a tooltip's trigger past the scroll edge, counting forced layouts per scroll frame before and after; the runtime's anchor-clear unit suite for when the don't-cover check runs | An open tooltip whose trigger a page scroll carries out of the page and back; the same inside a scrolling panel; the layer's show, a remount, a ResizeObserver report, and a window resize; a top-layer layer whose anchor leaves the page | A forced layout or layout read for a layer in a scroll frame other than one in which the anchor's visibility changes; a don't-cover check, `scroll` or `scrollend` read, or forced re-pick during a scroll; an observer of a trigger that moves without resizing; a layer that slides or vanishes instead of holding when its anchor leaves the page |
+| FR9 | `useLayerKeyboardClearance.test.tsx`; Popover's keyboard browser proofs in Chromium and WebKit with a stand-in keyboard; the iOS simulator | A tall Popover below its trigger with a field; a keyboard already up at the open; a short layer; a layer above its trigger | A capped layer ending under the keyboard or more than 10 px above it, an unreached layer that changes, a bottom-held layer that moves, or a layer measuring the keyboard itself |
+| FR10 | `useLayerKeyboardClearance.test.tsx`; Popover's keyboard browser proofs | A rising keyboard before and after it arrives; a falling keyboard; a keyboard that changes at once; a tap on Save as the keyboard falls | A cap written while the keyboard rises, kept as it falls, or taken off under a press before its click |
+| FR1 safe area | A device run: `env(safe-area-inset-*)` is set only by a real device and Chromium emulation does not populate it, so no Storybook story can show it. | Landscape phone with a notch on one side | A layer under the notch |
**Verification gap — VG1.** A layer that had to slide (it fit on neither
side of its trigger) and whose anchor leaves and returns can come back
@@ -605,9 +607,11 @@ runtime mechanism near that path has one disposition:
- CSS carries it: a trigger that moves without resizing needs no observer,
because the anchor-clear options are in the layer's list from the start;
- the choice of option during a scroll comes from one combined list whose
- options never overlap the trigger, within Chromium's five fallbacks, with
- no forced new choice; and whether a layer scrolls is CSS overflow, not a
+ the choice of option during a scroll comes from one combined list, within
+ Chromium's five fallbacks, whose options never overlap the trigger and run
+ preferred side, flip, beside the trigger, then a room-sized side, so a
+ fitting layer that loses room on its side flips to the opposite side before
+ it moves beside the trigger, with no forced new choice; and whether a layer scrolls is CSS overflow, not a
read (FR4).
- Off the scroll path: the don't-cover check runs at show and on a size
change, never per scroll frame (FR4, FR8).