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.mdindex 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 openTypeahead 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 orleaves the viewport and whether its content overflows; each is read beforefirst 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, inlayout or by a scroll, which only an intersection observer reports, afterpaint: 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 tocorrect, and the runtime polls nothing: an anchor that a scrolledcontainer hides is followed again when an intersection observer reports itback 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 thatleaves the viewport or is already out of view, an app-declared inset arrivingor 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, controlledstate, 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 orthe 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 andtransitions of a layer and its content across the re-placement's displayreset.@@ -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 |