Skip to content

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

TypeScript

spec(AST-099): one shared on-screen keyboard module (#8304)

Cindy Zhangc899f0bb6774
diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md
index 96673a649f..b9c2df7a63 100644
--- a/docs/architecture/react-component-runtime.md
+++ b/docs/architecture/react-component-runtime.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-09-07
+approved_at: 2026-10-24
owners: [cixzhang]
applies_to: [packages/core/src/, packages/lab/src/]
verified_by:
@@ -15,7 +15,7 @@ verified_by:
packages/core/src/Layer/useLayer.test.tsx,
packages/core/src/utils/sharedResizeObserver.test.ts,
]
-deciding_specs: [spec:AST-086/DEC-2]
+deciding_specs: [spec:AST-086/DEC-2, spec:AST-099/DEC-1]
---
# React component runtime architecture
@@ -34,7 +34,8 @@ deciding_specs: [spec:AST-086/DEC-2]
"INV5",
"INV6",
"INV8",
- "INV10"
+ "INV10",
+ "INV11"
]
}
}
@@ -136,6 +137,28 @@ those contracts.
adopting components hold no Effect, observer, timer, or
listener of their own to detect page load, read rendered text, or write that
announcement. The module follows INV3 and INV5.
+- **INV11 — The on-screen keyboard has one owner.** In `@astryxdesign/core`,
+ one shared internal hook in the keyboard module (`packages/core/src/keyboard/`)
+ measures the on-screen keyboard, keeps the page
+ from panning on focus, and dismisses the keyboard when a surface moves
+ (`spec:AST-099`); it is not exported. The keyboard height and each keyboard
+ change's transition (start time, resting value, curve) reach styles only as
+ the hook's value and live only in the hook: each consumer applies them
+ through a StyleX functional style on its own element, and no CSS custom
+ property on the document root or a shared ancestor carries them. No Core
+ component keeps its own visual-viewport listener for the keyboard. The hook
+ publishes each keyboard change as one transition: a start time, a resting
+ value, and a curve. Every Core consumer that rides the keyboard rides that
+ transition with compositor animations, a translate to the resting value,
+ never JavaScript per frame, and the hook makes at most one layout read per
+ keyboard change. A component outside Core does not ride; it commits the
+ resting value once. Packages outside Core cannot import the hook; a
+ component 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
+ does, blurs as FR5 does, applies the height through a functional style on
+ its own elements, and follows INV3 and INV5. The hook follows INV3 and
+ INV5.
## Authoring guidance
@@ -255,6 +278,8 @@ contracts.
- `spec:AST-086/DEC-2` — own-content announcements behave the same in every
component that announces its own rendered content (INV10).
+- `spec:AST-099/DEC-1` — one keyboard height for every component, kept
+ internal and applied through functional styles (INV11).
Component, family, API, accessibility, layer, interaction, and style records
remain authoritative for the other user-facing outcomes delegated above.
@@ -268,12 +293,13 @@ observable-behavior predicates require review or runtime evidence. Likewise, a
focused test proves only its named behavior and mutation expectation; a green
component 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 |
+| 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 |
diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.md
new file mode 100644
index 0000000000..1c2ce40be7
--- /dev/null
+++ b/docs/specs/AST-099-mobile-keyboard/spec.md
@@ -0,0 +1,245 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-099
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-24
+phase: accepted
+owners: [cixzhang]
+affects_architecture: [architecture:react-component-runtime]
+affects_families: []
+affects_contributing: []
+affects_consumer_docs:
+ [
+ packages/cli/assets/docs/browser-support.doc.mjs,
+ packages/core/src/BottomSheet/BottomSheet.doc.mjs,
+ ]
+---
+
+# On-screen keyboard system spec
+
+<!-- path-applicability:v1 -->
+
+```json
+{
+ "paths": ["packages/core/src/BottomSheet/**"]
+}
+```
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+## Intent
+
+A person typing on a phone sees the field they are typing in, and the surface
+around it, above the on-screen keyboard, and the page does not lurch when a
+field takes focus. Every surface that responds to the keyboard measures it the
+same way and keeps the page still, so the keyboard behaves the same in a sheet,
+a chat composer, or a search field.
+
+## Non-goals
+
+- Layer geometry: how Popover and other anchor-mode layers stay above the
+ keyboard belongs to `spec:AST-059`.
+- Hardware keyboard access and focus order, owned by `spec:AST-025`,
+ `spec:AST-020`, and component records.
+- The curve or timing of an animation that moves a surface with the keyboard,
+ beyond FR3's sync and FR8's limits; under reduced motion it follows
+ `design:reduced-motion`.
+- The app's viewport `<meta>` element, which the app owns.
+- `@astryxdesign/native`, where the platform's own keyboard avoidance applies
+ (`spec:AST-082` FR11).
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Requirements
+
+- **FR1 — One keyboard height for every component.** Every Core and Lab
+ component 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
+ BottomSheet, the chat composer, a search field placed at the bottom, tab bar
+ search, drag to dismiss, and any keyboard layout guide, so no two components disagree about where the
+ keyboard is. `architecture:react-component-runtime` INV11 owns the single
+ source of that height and how a component outside Core conforms.
+- **FR2 — The height a pan or a zoom cannot corrupt.** The keyboard height is
+ the layout viewport height minus the visual viewport height multiplied by the
+ visual viewport's scale, in CSS pixels. It is 0 when no keyboard is shown,
+ including while the page is pinch-zoomed. A page pan or a visual-viewport
+ offset is a pan to put back (FR4), never a smaller keyboard.
+- **FR3 — The keyboard height stays internal and keeps layout correct.** No
+ public CSS custom property, export, or prop exposes the keyboard height.
+ Each component applies it on its own element, such as a bottom offset, a
+ padding, or a maximum height, so layout is correct with no animation running:
+ the chat composer, a search field placed at the bottom, and tab bar search
+ position from it, and a fully expanded sheet extends its own scroll range by
+ it. How the value reaches styles is
+ `architecture:react-component-runtime` INV11. Riding the keyboard's motion
+ layers on top of that layout, so layout never depends on it; FR8 requires it
+ where it applies. When surfaces ride it, such as
+ a composer, a scroll view, and a header, they all move in sync along the same
+ motion to the resting value with no per-frame layout work, and each commits
+ the resting value once to layout, as an offset, a padding, or a spacer, so
+ nothing is hidden or unscrollable. How the motion is shared is
+ `architecture:react-component-runtime` INV11; no public API or CSS custom
+ property exposes it.
+- **FR4 — Focus never pans the page.** Every route into a text-entry control
+ inside a keyboard-aware surface, including a tap, the keyboard's
+ previous and next buttons, Tab, and programmatic focus, delivers focus
+ without the browser scrolling the document, and the surface brings the
+ control into view with its own scroller. When the keyboard's Done button
+ ends entry, focus moves to the surface so the next tap is handled the same
+ way. A document scroll that still happens while the page is scroll-locked,
+ such as on returning to the app, is put back in the same frame.
+- **FR5 — Moving a surface dismisses the keyboard.** When a surface that holds
+ the focused control starts to move, such as a sheet dragged between heights,
+ a drag to dismiss, or a close, the control is blurred so the keyboard
+ dismisses, and the surface keeps its keyboard layout until the visual
+ viewport has recovered, so content does not jump on the first frame of the
+ move.
+- **FR6 — Capability detection.** Keyboard handling acts where the visual viewport
+ shrinks for the keyboard while the layout viewport keeps its height. It
+ detects 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.
+- **FR7 — Top-level documents only.** Inside an iframe the frame's visual
+ viewport does not change when the keyboard opens, so the keyboard height is
+ 0 there and nothing changes. Behavior and evidence for this record come
+ from a top-level document.
+- **FR8 — Browsers that report the keyboard ride it smoothly.** In a browser
+ that 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
+ keyboard-aware surfaces ride the keyboard on show and on hide: they move with
+ the keyboard's slide, within one frame of it on the measured keyboards, with
+ no one-step jump and no surface left under the keyboard, no JavaScript per
+ frame, and one layout commit at rest (FR3). Under reduced motion nothing
+ travels 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
+ `interactive-widget=resizes-content`, which Astryx documents and does not
+ set, still applies there. An Android browser without a keyboard geometry API
+ that shrinks only its visual viewport, such as Firefox for Android, gets
+ FR2–FR5 under FR6.
+
+### Platform support
+
+- Supported feature/engine floor: the package's supported browsers
+ (`spec:AST-013` FR3). FR2–FR5 apply to Safari on iOS, in the browser and as a
+ home-screen app, and to Firefox for Android; FR8's ride applies wherever the
+ browser reports the keyboard itself, such as Chrome on Android.
+- Unsupported behavior: with no on-screen keyboard, or no visual-viewport
+ support, the keyboard height is 0 and nothing changes. During server render it
+ renders nothing and reads no viewport.
+- Browser evidence: Safari on iOS, in the iOS Simulator or on a device and in a
+ top-level document, proves the iOS claims of FR2–FR5, and Chrome on Android, in an emulator or on a device, proves FR8, with
+ Firefox for Android proving FR2–FR5 there
+ (`spec:AST-013` FR10); DOM and visual-viewport tests prove the rest of
+ FR1–FR7. Simulator and emulator evidence in a top-level document gates
+ merge, with Gboard on the Android emulator; a pass on a physical iPhone and a
+ physical Android phone, including Samsung Keyboard and the phone's real
+ refresh timing, is required before the keyboard module ships in a release
+ (DEC-3).
+
+## Current-state impact
+
+- BottomSheet's internal keyboard hook implements FR2, FR4, and FR5 for a
+ fully expanded Tall sheet on iOS, detects iOS from the user agent, and writes
+ a private inset on the sheet body as the custom property
+ `--_sheet-keyboard-inset`, which retires: the sheet applies the height
+ through a functional style on its own element. It moves into Core's
+ keyboard module, `packages/core/src/keyboard/`, the single source
+ `architecture:react-component-runtime` INV11 names: FR6 replaces the
+ user-agent check, FR3 keeps the height internal, and BottomSheet consumes the
+ shared source (`component:BottomSheet`).
+- No other component on `main` measures the keyboard. A component that later
+ responds to the keyboard uses the same height (FR1).
+- Layer caps do not account for the keyboard: `spec:AST-059` owns layer
+ geometry, and keeping Popover and other anchor-mode layers above the keyboard
+ is an amendment to that record that consumes this height.
+- Today's hook omits FR2's zoom term, so a pinch-zoomed page reads as a
+ keyboard; FR2 corrects that.
+- Today's hook gates only its focus claim on an iOS user agent. Under FR8, a
+ fully expanded Tall sheet in
+ Chrome on Android keeps the keyboard accommodation `BottomSheet.doc.mjs`
+ documents and moves with the keyboard, so no consumer loses behavior and no
+ breaking change applies; `BottomSheet.doc.mjs` states each platform's
+ behavior. Firefox for Android gets FR2–FR5.
+- No public API exposes the keyboard height, and FR3 keeps it that way.
+- The consumer documentation gains the Android viewport setting (FR8).
+
+## 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 |
+
+## Decision log
+
+### DEC-1 — One keyboard height for every component, measured so a pan cannot corrupt it
+
+**Reference:** `spec:AST-099/DEC-1`
+**Decider:** `cixzhang`, `2026-10-24`
+
+BottomSheet's keyboard hook already keeps a fixed surface still on every focus
+route and measures the keyboard so a page pan cannot shrink it, which are the
+two failures that leave a field under the keyboard. Making it the one source
+Core components use, and the definition a component outside Core measures by,
+keeps components from drifting into different measurements. Applying the
+hook's height through StyleX functional styles keeps layout correct with no
+animation and keeps the shared API constrained: the height stays internal, and
+an app that later needs it gets a deliberate public-API decision rather than a
+variable it came to rely on.
+Animation layers on top of correct layout and never makes layout correct.
+
+Rejected: each component measuring the keyboard by its own rule and predicting its motion, which pans with any unclaimed focus route and diverges; a public CSS custom property for the height, which a hook-derived value does not need.
+
+### DEC-2 — Chrome on Android rides the keyboard smoothly
+
+**Reference:** `spec:AST-099/DEC-2`
+**Decider:** `cixzhang`, `2026-10-24`
+
+People on Android should see the same smooth keyboard motion as on iPhone: a
+surface that jumps once the keyboard has finished, or sits under it while it
+moves, 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.
+
+Rejected: a one-step relayout that jumps after the keyboard settles; and overriding the app's viewport setting outside keyboard-aware fields.
+
+### DEC-3 — Simulators gate merge; physical phones gate release
+
+**Reference:** `spec:AST-099/DEC-3`
+**Decider:** `cixzhang`, `2026-10-24`
+
+Simulator and emulator evidence in a top-level document, with Gboard on the
+Android emulator, is enough to merge keyboard work, so it is not blocked on
+hardware, while a pass on a physical iPhone and a physical Android phone,
+including Samsung Keyboard and the phone's real refresh timing, is required
+before the keyboard module ships in a release, because keyboard timing and viewport behavior differ on
+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.
+
+## Open questions
+
+None.
diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.md
index 90ad74515a..bfe8299218 100644
--- a/packages/core/src/BottomSheet/BottomSheet.spec.md
+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md
@@ -6,8 +6,8 @@ id: component:BottomSheet
authority: current
archive_reason: null
superseded_by: null
-approved_by: imdreamrunner
-approved_at: 2026-10-21
+approved_by: cixzhang
+approved_at: 2026-10-24
owners: [cixzhang]
review_triggers: [theming, layout, public-api]
verified_by:
@@ -30,7 +30,7 @@ architecture:
architecture:layer-runtime,
]
contributing: []
-system_specs: [spec:AST-025]
+system_specs: [spec:AST-025, spec:AST-099]
---
# BottomSheet component contract
@@ -177,6 +177,7 @@ a decision that they must remain unthemeable.
and records that sheets retain local scrim and swipe behavior.
- `spec:AST-025` owns effective scroll measurement, overflow and containment,
automatic keyboard-owner selection, and focus continuity.
+- BottomSheet's on-screen keyboard behavior is owned by `spec:AST-099`.
- `family:overlay-dismissal` owns shared Escape and platform-close ordering. A
standalone BottomSheet registers with the shared stack while it is presented;
a switcher-hosted sheet is covered by BottomSheetSwitcher's registration.