An open source design system that's fully customizable and agent ready
TypeScript
docs(AST-059): anchored layers re-pick once after scrolling stops (#10289)
Cindy Zhang14b138763ef3
diff --git a/docs/specs/AST-059-layer-viewport-inset/spec.md b/docs/specs/AST-059-layer-viewport-inset/spec.mdindex 3367acd28e..c8fc09e168 100644--- a/docs/specs/AST-059-layer-viewport-inset/spec.md+++ b/docs/specs/AST-059-layer-viewport-inset/spec.md@@ -226,15 +226,26 @@ the app reaches every layer instead of the components that happen to read it.as that option still fits: when its anchor moves, the layer moves to theside that is now roomier rather than shrinking to a sliver. During a scroll,CSS anchor positioning alone places the layer: the runtime reads no layout,- forces no layout, and does not make the engine choose an option again. The+ forces no layout, and does not make the engine choose an option again. When+ scrolling stops, the runtime re-picks the layer's position once, so a layer+ a scroll carried to the edge does not stay off-screen. Scrolling stops when+ the `scrollend` event fires on any scrolling ancestor of the anchor, the page+ included; the single re-pick runs in the first painted frame after each such+ event. `scrollend` fires per wheel step in Chromium; the read waits one+ painted frame after each `scrollend`, so a long wheel scroll re-checks more+ than once; no read happens during the scroll itself. Where `scrollend` is not+ supported at the browser floor (Safari before 26.2), the same single re-pick+ runs after 150 ms with no `scroll` event on those ancestors; the scroll+ listener only arms the timer and reads nothing. No layout read happens in any+ scroll handler (DEC-8). Thedon't-cover check — whether the box covers its anchor or, while the anchor isin view, leaves the viewport on the block axis, read from the layer's settledbox without the transform its entry animation applies — runs only when thelayer shows or remounts, on ResizeObserver reports (the layer's size, itscontent's, its anchor's, and a replacement anchor's when the caller replaces- the anchor element while the layer stays open) and on window resize. A- scroll never re-checks it, no `scroll` or `scrollend` event is read, and no- observer watches for a trigger that moves without resizing. A check that+ the anchor element while the layer stays open) and on window resize. No+ frame during a scroll re-checks it, and no observer watches for a trigger+ that moves without resizing. A check thatfails places the layer afresh from the combined list in the same task,without painting and without closing it. Every CSS animation and transitionof the layer and its content keeps every writable member the engine exposes@@ -283,7 +294,9 @@ the app reaches every layer instead of the components that happen to read it.them. During a scroll, CSS anchor positioning places every anchor-modelayer: no scroll frame reads layout or forces it for a layer, and theruntime makes no new choice of option mid-scroll (FR4). The runtime makes- three observations, each driven by an event rather than by the scroll. Whether the anchor is in view+ four observations, each driven by an event rather than by the scroll. Once+ scrolling stops, it re-picks the layer's position once, in the first painted+ frame after the stop (FR4, DEC-8). Whether the anchor is in view(FR5) is read before the layer's first paint and thereafter only when theanchor's visibility changes, so a layer opened while its anchor is alreadyout of view holds from its first frame. The runtime keeps this hold rather@@ -376,11 +389,11 @@ When this ships:decides whether it arrives, and no layer resolves placement through it.- Add an invariant for FR8: no geometry input is measured after paint andthen applied; the first painted frame is the settled frame; no scroll frame- reads or forces layout for a layer (DEC-7).+ reads or forces layout for a layer (DEC-7, DEC-8).- Positioning and INV12 describe the anchor-move intersection observers, a- re-read in every frame of a scroll, the forced re-pick after a scroll, and- the read that decides whether a layer scrolls as current behavior; they- follow FR4, FR8, and DEC-7 when those ship.+ re-read in every frame of a scroll, a re-pick after a scroll other than the+ one DEC-8 keeps, and the read that decides whether a layer scrolls as+ current behavior; they follow FR4, FR8, DEC-7, and DEC-8 when those ship.- INV11 and INV12 add the software keyboard's cap (FR9) and FR10's timing:the cap is read from the layer's own box without its entrance transform whenthe keyboard moves, and it changes once per keyboard movement, the one@@ -461,20 +474,20 @@ surface styling. A playground story with a draggable trigger and live width,placement, and alignment controls exists for exploration; it is not evidencefor 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); 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 |+| 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, DEC-8) | 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; the tooltip suite's scroll-edge case; a count of forced layouts per scroll with the re-pick after `scrollend`, and with the 150 ms fallback where `scrollend` is unsupported | 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 wheel scroll that ends with the trigger at the scroll edge | 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; the scroll-edge case fails, a layout read lands during the scroll or in a scroll handler, or the re-pick runs before the first painted frame after the stop |+| 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 neitherside of its trigger) and whose anchor leaves and returns can come back@@ -597,7 +610,7 @@ a UIKit popover does.Rejected: the keyboard as a declared block-end inset (FR6), because thefallback order applies a block inset to both block edges (FR4).-### DEC-7 — During a scroll, CSS places anchored layers; the runtime keeps three event-driven reads+### DEC-7 — During a scroll, CSS places anchored layers; the runtime keeps event-driven reads**Reference:** `spec:AST-059/DEC-7`**Decider:** `cixzhang`, `2026-11-06`@@ -616,7 +629,8 @@ runtime mechanism near that path has one disposition:- Off the scroll path: the don't-cover check runs at show and on a sizechange, never per scroll frame (FR4, FR8).- The runtime keeps it: the out-of-view hold (FR5), the read on window- resize, and the keyboard clearance (FR9).+ resize, the keyboard clearance (FR9), and the single re-pick after+ scrolling stops (DEC-8).Two measured gaps in CSS alone decide the keeps and the shape of the list.Inside a scrolling panel, Chrome does not choose a CSS-anchored layer's option@@ -630,11 +644,27 @@ resize is not a scroll path. iOS Safari has no CSS for the software keyboard(`env(keyboard-inset-*)` is Chrome-only, and the `interactive-widget`viewport key is not supported there), so the keyboard clearance stays. Ascroll therefore costs the runtime layout work only in the frame in which an-anchor's visibility changes.+anchor's visibility changes and in the frame after scrolling stops (DEC-8).Rejected: CSS alone for every row (the two gaps above), and per-frame checksduring a scroll (each forces layout in every scroll frame).+### DEC-8 — Anchored layers re-pick once, a painted frame after scrolling stops++**Reference:** `spec:AST-059/DEC-8`+**Decider:** `cixzhang`, `2026-11-06`++An anchored layer re-picks its position once, in the first painted frame after+scrolling stops; nothing reads layout during the scroll (FR4). Chromium never+chooses a CSS-anchored layer's option again during a scroll, so a tooltip a+scroll carried to the edge would otherwise stay off-screen. Measured in+Chromium, a scroll costs 5 to 20 forced layouts with this re-pick, against 12+to 27 with a re-pick in every frame, and the edge case of the tooltip suite+passes.++Rejected: CSS alone (the tooltip stays off-screen at the edge), and a re-pick+in every scroll frame (the layer bounces mid-scroll).+## Open questionsNone. Every decision above is the owner's.