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.mdindex 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 |