Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 40 additions & 5 deletions docs/architecture/layer-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 |
Expand Down
Loading