An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-099): the keyboard height comes from the visual viewport in every browser (#8385)
Christopher Chedeau106a98cfbd56
diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.mdindex b9c2df7a63..d4c3042915 100644--- a/docs/architecture/react-component-runtime.md+++ b/docs/architecture/react-component-runtime.md@@ -154,8 +154,7 @@ those contracts.keyboard change. A component outside Core does not ride; it commits theresting value once. Packages outside Core cannot import the hook; acomponent there that responds to the keyboard keeps one listener that- measures as `spec:AST-099` FR2 defines, or takes the browser's keyboard report- where FR8 applies, keeps focus from panning as FR4+ measures as `spec:AST-099` FR2 defines, keeps focus from panning as FR4does, blurs as FR5 does, applies the height through a functional style onits own elements, and follows INV3 and INV5. The hook follows INV3 andINV5.@@ -293,13 +292,13 @@ observable-behavior predicates require review or runtime evidence. Likewise, afocused test proves only its named behavior and mutation expectation; a greencomponent suite is not blanket conformance with every invariant.-| Invariant | Evidence | Failure signal |-| ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |-| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |-| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |-| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |-| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |-| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |-| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |-| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2 or, where it applies, FR8, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |+| Invariant | Evidence | Failure signal |+| ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |+| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |+| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |+| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |+| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |+| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |+| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |+| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.mdindex 1c2ce40be7..11360a051d 100644--- a/docs/specs/AST-099-mobile-keyboard/spec.md+++ b/docs/specs/AST-099-mobile-keyboard/spec.md@@ -59,8 +59,8 @@ a chat composer, or a search field.- **FR1 — One keyboard height for every component.** Every Core and Labcomponent that positions, sizes, or dismisses relative to the on-screen- keyboard responds to the same keyboard height at the same moment (FR2, or- FR8 where it applies), including+ keyboard responds to the same keyboard height (FR2) at the same moment,+ includingBottomSheet, the chat composer, a search field placed at the bottom, tab barsearch, drag to dismiss, and any keyboard layout guide, so no two components disagree about where thekeyboard is. `architecture:react-component-runtime` INV11 owns the single@@ -103,30 +103,34 @@ a chat composer, or a search field.- **FR6 — Capability detection.** Keyboard handling acts where the visual viewportshrinks for the keyboard while the layout viewport keeps its height. Itdetects that from the platform's viewport and keyboard capabilities, never- from the user agent (`spec:AST-013` FR6). Where the browser itself reports- the on-screen keyboard's geometry, as Chrome on Android does, the- visual-viewport measurement does not apply and FR8 governs, on any device- that shows an on-screen keyboard; a browser that offers the report but shows- no on-screen keyboard reads 0. A page that is not a secure context gets no- such report and follows FR2.+ from the user agent (`spec:AST-013` FR6). Where the browser also reports+ the on-screen keyboard's geometry, as Chrome on Android does, the height+ comes from FR2 there too and FR8 governs how surfaces ride the keyboard, on any+ device that shows an on-screen keyboard; a browser that offers the report but+ shows no on-screen keyboard reads 0. A page that is not a secure context gets+ no such report, so FR8 does not apply there.- **FR7 — Top-level documents only.** Inside an iframe the frame's visualviewport does not change when the keyboard opens, so the keyboard height is0 there and nothing changes. Behavior and evidence for this record comefrom a top-level document.- **FR8 — Browsers that report the keyboard ride it smoothly.** In a browserthat reports the on-screen keyboard's geometry itself, such as Chrome on- Android, the keyboard height comes from that report rather than FR2's- visual-viewport measurement, and Core's+ Android, the keyboard height comes from FR2's visual-viewport+ measurement there too (DEC-4), and Core'skeyboard-aware surfaces ride the keyboard on show and on hide: they move withthe keyboard's slide, within one frame of it on the measured keyboards, withno one-step jump and no surface left under the keyboard, no JavaScript perframe, and one layout commit at rest (FR3). Under reduced motion nothingtravels with the keyboard, and the change follows `design:reduced-motion`DR2, a cross-fade on a touch screen. A Lab surface commits the resting value without riding- (`architecture:react-component-runtime` INV11). Outside keyboard-aware- fields, Astryx never overrides the app's own viewport setting; the app's+ (`architecture:react-component-runtime` INV11). Astryx never overrides+ the app's own viewport setting. Where the app sets`interactive-widget=resizes-content`, which Astryx documents and does not- set, still applies there. An Android browser without a keyboard geometry API+ set, Chrome on Android shrinks the layout viewport with the keyboard, so+ FR2 reads 0: a keyboard-aware field's keyboard height is 0 there and it+ does not ride, since the browser has already made the room. Everywhere+ else, keyboard-aware surfaces ride the visual-viewport height (DEC-4).+ An Android browser without a keyboard geometry APIthat shrinks only its visual viewport, such as Firefox for Android, getsFR2–FR5 under FR6.@@ -178,19 +182,19 @@ a chat composer, or a search field.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| FR1 | Source boundary check over Core and Lab plus a shared test that drives one keyboard change | each listed consumer; a new keyboard-aware component | Two components reading different heights for one keyboard, or a component measuring by a rule other than FR2 or, where it applies, FR8 |-| FR2 | Module tests driving visual-viewport resize and scroll events | keyboard shown; hidden; page panned with the keyboard shown; offset without a keyboard; page pinch-zoomed with and without the keyboard | A pan that lowers the reported height, or a height when no keyboard is shown |-| FR3 | Consumer tests of computed layout, plus a public-surface check | keyboard shown and hidden; composer, bottom search field, tab bar search, Tall sheet; no animation running; a ride animation running with the composer, a scroll view, and a header together | A consumer whose layout ignores the height, layout that is only correct after an animation, riding surfaces out of sync on one keyboard change, per-frame layout work during a ride, content hidden or unscrollable at the resting value, or a public CSS custom property, export, or prop for the height |-| FR4 | Focus-route tests with document scroll spies | tap, previous and next buttons, Tab, programmatic focus, Done then tap, app resume while scroll-locked | A route that scrolls the document, or a slipped scroll left in place |-| FR5 | Surface move tests | sheet drag between heights, drag to dismiss, close, with a focused field | The field stays focused after a move starts, or content jumps on the first frame |-| FR6 | Capability tests with the user agent varied | visual viewport shrinking with a fixed layout viewport; Chrome on Android reporting keyboard geometry; a desktop browser with the API and no on-screen keyboard; a page that is not a secure context; neither | Behavior that changes with the user agent alone, or measurement where the platform geometry API applies |-| FR7 | Tests in an iframe and in a top-level document | the same keyboard event sequence in both | A non-zero value or a claimed focus inside an iframe |-| FR8 | Chrome on Android in the emulator with Gboard, top-level document, plus a consumer documentation check | keyboard show and hide with the composer and a Tall sheet; a Lab bottom search field; reduced motion on; an app with `interactive-widget=resizes-content`, focus outside keyboard-aware fields | A Core surface jumping after the keyboard settles, lagging the keyboard by more than a frame, left under the keyboard, moved by JavaScript per frame, or committing layout more than once; a Lab surface riding instead of committing at rest; anything travelling with the keyboard under reduced motion instead of DR2's cross-fade; the app's viewport setting overridden outside keyboard-aware fields; or the setting missing from the docs |-| FR8 | Firefox for Android, emulator or device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |-| FR2–FR5 | Safari on iOS in the iOS Simulator or on a device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, in Safari and as a home-screen app | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |-| FR2–FR5, FR8 | Release gate: physical devices in a top-level document (DEC-3) | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; Firefox for Android (FR2–FR5); Android Chrome with Gboard and Samsung Keyboard at the phone's refresh rate | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Source boundary check over Core and Lab plus a shared test that drives one keyboard change | each listed consumer; a new keyboard-aware component | Two components reading different heights for one keyboard, or a component measuring by a rule other than FR2 |+| FR2 | Module tests driving visual-viewport resize and scroll events | keyboard shown; hidden; page panned with the keyboard shown; offset without a keyboard; page pinch-zoomed with and without the keyboard | A pan that lowers the reported height, or a height when no keyboard is shown |+| FR3 | Consumer tests of computed layout, plus a public-surface check | keyboard shown and hidden; composer, bottom search field, tab bar search, Tall sheet; no animation running; a ride animation running with the composer, a scroll view, and a header together | A consumer whose layout ignores the height, layout that is only correct after an animation, riding surfaces out of sync on one keyboard change, per-frame layout work during a ride, content hidden or unscrollable at the resting value, or a public CSS custom property, export, or prop for the height |+| FR4 | Focus-route tests with document scroll spies | tap, previous and next buttons, Tab, programmatic focus, Done then tap, app resume while scroll-locked | A route that scrolls the document, or a slipped scroll left in place |+| FR5 | Surface move tests | sheet drag between heights, drag to dismiss, close, with a focused field | The field stays focused after a move starts, or content jumps on the first frame |+| FR6 | Capability tests with the user agent varied | visual viewport shrinking with a fixed layout viewport; Chrome on Android reporting keyboard geometry; a desktop browser with the API and no on-screen keyboard; a page that is not a secure context; neither | Behavior that changes with the user agent alone, or a height taken from the browser's keyboard geometry report instead of FR2's measurement |+| FR7 | Tests in an iframe and in a top-level document | the same keyboard event sequence in both | A non-zero value or a claimed focus inside an iframe |+| FR8 | Chrome on Android in the emulator with Gboard, top-level document, plus a consumer documentation check | keyboard show and hide with the composer and a Tall sheet; a Lab bottom search field; reduced motion on; focus inside a keyboard-aware field, which rides by the visual-viewport height; an app with `interactive-widget=resizes-content`, focus inside and outside keyboard-aware fields, where a field's keyboard height is 0 | A Core surface jumping after the keyboard settles, lagging the keyboard by more than a frame, left under the keyboard, moved by JavaScript per frame, or committing layout more than once; a Lab surface riding instead of committing at rest; anything travelling with the keyboard under reduced motion instead of DR2's cross-fade; the app's viewport setting overridden; a keyboard-aware field not riding by the visual-viewport height, or adding an offset under `interactive-widget=resizes-content`; or the setting missing from the docs |+| FR8 | Firefox for Android, emulator or device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |+| FR2–FR5 | Safari on iOS in the iOS Simulator or on a device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, in Safari and as a home-screen app | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |+| FR2–FR5, FR8 | Release gate: physical devices in a top-level document (DEC-3) | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; Firefox for Android (FR2–FR5); Android Chrome with Gboard and Samsung Keyboard at the phone's refresh rate | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard |## Decision log@@ -220,11 +224,13 @@ Rejected: each component measuring the keyboard by its own rule and predicting iPeople on Android should see the same smooth keyboard motion as on iPhone: asurface that jumps once the keyboard has finished, or sits under it while itmoves, feels broken. So keyboard-aware surfaces ride the keyboard's slide on-show and hide in Chrome on Android too, while the app's own viewport setting-stays in charge everywhere else. The mechanism is left to the implementation;-this record states only the motion and its limits.+show and hide in Chrome on Android too, by the visual-viewport height+(DEC-4), and the app's own viewport setting stays in charge: where the app+sets `interactive-widget=resizes-content`, the browser already makes the room+and those surfaces have nothing to ride. The mechanism is left to the+implementation; this record states only the motion and its limits.-Rejected: a one-step relayout that jumps after the keyboard settles; and overriding the app's viewport setting outside keyboard-aware fields.+Rejected: a one-step relayout that jumps after the keyboard settles; and overriding the app's viewport setting.### DEC-3 — Simulators gate merge; physical phones gate release@@ -240,6 +246,21 @@ real devices.Rejected: physical devices as a merge gate, which blocks work on hardware; and physical devices as optional follow-up, which can ship untested keyboard behavior.+### DEC-4 — The keyboard height comes from the visual viewport in every browser++**Reference:** `spec:AST-099/DEC-4`+**Decider:** `cixzhang`, `2026-10-25`++In Chrome on Android the visual viewport shrinks for the keyboard as the+keyboard starts to slide, so FR2's measurement reaches the page in time for+surfaces to join the slide within a frame, and reading it changes nothing on+the page. The browser's own keyboard geometry report needs the page to overlay+the keyboard, arrives later and less steadily, and in Chromium hides the+bottom toolbar on the keyboard's frame, which moves the layout. One+measurement in every browser also keeps FR1's single height.++Rejected: the browser's keyboard geometry report as the height, which arrives later and less steadily and shifts the layout.+## Open questionsNone.