Skip to content

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

TypeScript

docs(architecture): the layer runtime's keyboard cap in INV11 and INV12 (#10143)

Christopher Chedeau992e28c606f3
diff --git a/docs/architecture/layer-runtime.md b/docs/architecture/layer-runtime.md
index d31b043d89..18c0d3e410 100644
--- a/docs/architecture/layer-runtime.md
+++ b/docs/architecture/layer-runtime.md
@@ -28,6 +28,7 @@ verified_by:
[
packages/core/src/Layer/useLayer.test.tsx,
packages/core/src/Layer/layerViewportInset.test.ts,
+ packages/core/src/Layer/useLayerKeyboardClearance.test.tsx,
packages/core/src/Layer/LayerProvider.test.tsx,
packages/core/src/Layer/toastHost.test.tsx,
packages/core/src/Layer/toastHost.lateRegistration.test.tsx,
@@ -510,17 +511,38 @@ layers use Layer rendering without joining Escape/platform dismissal.
beside the trigger, except that a later list for the same query keeps an open
Typeahead popup on its side and grows it only within the room there
(`spec:AST-092` FR6); the first list for a query places it normally, and a
- consumer minimum is clamped by the runtime's cap.
+ consumer minimum is clamped by the runtime's cap. The software keyboard's cap
+ is one of those caps (`spec:AST-059` FR9). While a software keyboard covers
+ the bottom of the viewport, an anchor-mode layer whose block-end edge would
+ run under it keeps its block-start edge and ends 10 px above the keyboard.
+ The keyboard's height is the keyboard module's one height
+ (`architecture:react-component-runtime` INV11). Each layer carries its own
+ keyboard cap on its own element, folded into its block-axis cap, so a layer
+ opened inside a capped layer is never capped by its host. Beside the cap,
+ each layer carries the overflow its surface takes under it, so a surface
+ that reads it scrolls from the frame the cap lands, and its content never
+ paints past the capped box. A layer the keyboard does not reach, a layer
+ placed above its trigger, and a layer in custom or fixed mode stay as they
+ are.
- **INV12 — The first frame is the settled frame.** No input to a layer's
- viewport geometry is measured after paint and then applied, with one
- exception. The runtime observes anchor visibility for every layer, and,
+ viewport geometry is measured after paint and then applied, with two
+ exceptions. The runtime observes anchor visibility for every layer, and,
for a layer that keeps its anchor clear, whether it covers its anchor or
leaves the viewport and whether its content overflows; each is read before
first paint and, while the layer is open, from callbacks that run before the
- frame paints. The exception is a same-size anchor that moves on screen, in
+ frame paints. The first is a same-size anchor that moves on screen, in
layout or by a scroll, which only an intersection observer reports, after
paint: at most one painted frame shows the layer over its anchor before the
- correction. Otherwise a layer never paints at a geometry it is about to
+ correction. The second is the software keyboard's cap (`spec:AST-059` FR10).
+ A box's height cannot change on the compositor, so the cap changes once per
+ keyboard movement: when a rising keyboard has arrived, at once as a falling
+ keyboard starts down, and at once for a keyboard that changes without
+ moving. A change that would move the layer under a press in progress inside
+ it waits for that press's click. The cap is read from the layer's own box
+ without its entrance transform. It is read before the first paint of a layer
+ that opens with a keyboard up, when the keyboard moves, and before the first
+ paint of a layer element the runtime swaps in while the layer is open.
+ Otherwise a layer never paints at a geometry it is about to
correct, and the runtime polls nothing: an anchor that a scrolled
container hides is followed again when an intersection observer reports it
back in view.
@@ -633,6 +655,13 @@ is staged as `[breaking]` (`spec:AST-017` FR32) and `component:SelectableCard`
where neither side fits, a layer wider than the viewport, an anchor that
leaves the viewport or is already out of view, an app-declared inset arriving
or changing, and the first painted frame against the settled one.
+- A software keyboard cap change verifies the cap's timing (a rising keyboard
+ that arrives, a falling one, one that changes at once, and a press in
+ progress inside the layer), a layer opened with the keyboard up in its first
+ frame, capped and with its content clipped, a layer element swapped in while
+ open, a pinch zoom, and the layers it leaves alone:
+ one clear of the keyboard, one placed above its trigger, and one in another
+ positioning.
- A Popover lifecycle change verifies programmatic and browser closes, controlled
state, temporary invoker association, and same-gesture trigger behavior.
- A dismissal-stack change updates `family:overlay-dismissal` when membership or
@@ -665,6 +694,11 @@ is staged as `[breaking]` (`spec:AST-017` FR32) and `component:SelectableCard`
`Layer/layerInset.ts` owns the `--astryx-layer-inset-*` properties a layer or
the toast viewport writes on itself to carry it; `Layer/clampInlineSize.ts`
owns the clamp a consumer applies to a size of its own.
+- `Layer/useLayerKeyboardClearance.ts` owns the software keyboard's cap on an
+ open anchor-mode layer; the runtime imports it through `Layer/LayerTouch.ts`,
+ its one touch module. `Layer/layerKeyboardClearance.ts` holds the clearance
+ and the cap's arithmetic. `Layer/settledBox.ts` reads a layer's box without
+ its entrance transform, for the fallback order and the keyboard's cap.
- `Layer/preserveAnimations.ts` owns carrying the CSS animations and
transitions of a layer and its content across the re-placement's display
reset.
@@ -730,6 +764,7 @@ this current architecture record.
| INV3–INV5 | `useLayer.test.tsx` and `anchorName.test.ts` | A mode leaks geometry, RTL resolves from the wrong context, fallback clips, or a sibling anchor is lost |
| INV11 | `layerViewportInset.test.ts`, `useLayer.test.tsx`, and the `Core/Layer` viewport-inset stories under the story play guard at a desktop and a phone viewport; `BaseTypeahead.incremental.test.tsx` and the Typeahead incremental-results stories for the `spec:AST-092` FR6 exception | A second gutter definition, a `100%`-of-span cap, a layer narrower than its explicit size, a layer box wider than the viewport, a layer inside the gutter, or a layer that slides toward an off-screen anchor; for an open Typeahead popup, a later list for the same query that flips it to the other side or grows it past the room on its side, or a first list for a query that is capped to the span beside the trigger |
| INV12 | The `Core/Layer` viewport-inset stories' first-frame comparison, and `useLayer.test.tsx`'s synchronous anchor read | A layer whose first painted rectangle differs from its settled one |
+| INV11, INV12 | The software keyboard's cap: `useLayerKeyboardClearance.test.tsx` for its rule, its timing, and its read before first paint; `PopoverKeyboard.interaction.browser.spec.ts` and `keyboardCappedLists.interaction.browser.spec.ts` for its rendered geometry in Chromium and WebKit | A layer that runs under the keyboard, or is capped though the keyboard does not reach it; a cap that changes more than once per keyboard movement or under a press; a layer opened with the keyboard up whose first frame is uncapped or paints its content past its box |
| INV6, INV7 | `useLayer.test.tsx`, `Popover.test.tsx`, `DropdownMenu.test.tsx`, and `useMenuHover.test.tsx` | Duplicate close callback or the same press/re-hover reopens a surface |
| INV8 | `useLayerDismissal.test.tsx`, `layerDismissalInvariants.test.tsx`, and `useFocusTrap.test.tsx` | Current top registered layer is skipped, two layers close, or a blocker leaks through |
| INV9 | Representative Dialog, ContextMenu, Tooltip/HoverCard, and BottomSheet source/tests; `useBackdropPress.test.tsx`; `outsidePress.test.ts` | A current local channel silently changes ownership or policy |