Skip to content

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

TypeScript

docs(react-component-runtime): read layout as little as possible (#10219)

Cindy Zhange2a9286d7ee3
diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md
index 4e414f2a4a..b72b3f7d65 100644
--- a/docs/architecture/react-component-runtime.md
+++ b/docs/architecture/react-component-runtime.md
@@ -46,7 +46,8 @@ deciding_specs:
"INV12",
"INV13",
"INV15",
- "INV16"
+ "INV16",
+ "INV18"
]
},
"concerns": {
@@ -362,6 +363,21 @@ those contracts.
Popover, and Table's sticky columns each keep their own `ResizeObserver`
beside `sharedResizeObserver`; and other Core sites keep their own
`MutationObserver` beside `sharedMutationObserver`.)
+- **INV18 — Layout is read as little as possible.** Placement uses CSS
+ (anchor positioning, container queries, logical properties) instead of
+ measuring in JS, as `architecture:component-style-authoring` INV2 prefers. A
+ per-frame, scroll or resize path reads no layout, except a read a current
+ clause requires there: `architecture:layer-runtime`'s placement re-reads,
+ INV11's keyboard read, and INV12's and `component:Resizable` FR8's
+ before-and-after measurement. Each such read happens in one batched
+ measurement pass per change, never interleaved with writes. A read is one
+ measurement pass: a remaining read names its reason in a comment and happens
+ once per change, not per frame, or as the before-and-after pair a current
+ clause requires. INV11's keyboard hook, which makes at most one layout read
+ per keyboard change, is one instance. (Known implementation gaps include: the
+ chat stream scroll hook reads scroll geometry on every scroll event, and
+ about 49 Core source files that call `getBoundingClientRect` are not yet
+ checked against this rule.)
## Authoring guidance
@@ -518,3 +534,4 @@ component suite is not blanket conformance with every invariant.
| INV15 | Unit tests of the animator's value mode and real-browser proofs of its adopters | A value off its channels' timing (the theme's tokens for a program-started change, a spring only where `spec:AST-094` FR45 keeps one), a count past the component's swap size, a count or cross-fade under reduced motion with a coarse or a fine pointer, an intermediate value announced, or a public export fails |
| INV16 | Review of each Core component that handles a concern Core owns in a shared hook or utility | A Core component that keeps its own effect, listener, or tracker for that concern fails, whether or not it also calls the hook or utility |
| INV16 (slot presence) | `no-nullish-jsx-guard` strict lint over Core and RichText, with no baseline, and `no-truthy-jsx-guard` strict lint over Core, with no baseline; both catch inline guards only, so review also checks for a presence test hoisted into a variable, converted (`!!value`, `Boolean(value)`), made by an early return or a `??` default, or passed through a prop spread, which the lints pass; empty-slot tests that pass `''`, `false`, `true`, and `null` and compare with an omitted slot, plus `0` as content, in Item, MetadataList, ChatSystemMessage, TreeList, TopNavMegaMenu, RichTextEditor, and RichTextEditorToolbar | A slot given `''`, `true`, or `false` draws a wrapper, lane, border, or separator that an omitted slot does not, an element loses the name it has without the slot, `0` does not render, or a new bare nullish or truthiness presence test, inline or hoisted, a truthiness guard past the baseline, a baseline entry added, or a hand-written copy of the check lands |
+| INV18 | Review of every added read that forces layout: `getBoundingClientRect`, `getClientRects`, `offset*`, `client*`, `scroll*` (`scrollTop`, `scrollHeight`, and the rest), `inner*` and `outer*`, `visualViewport` geometry, and `getComputedStyle` (evidence gap: no automated finding yet) | A layout read in a per-frame, scroll or resize path that no current clause requires there, a read interleaved with writes, a read without a comment that names its reason, more than one measurement pass per change beyond the before-and-after pair a current clause requires, or JavaScript measurement where CSS placement serves |