Repository navigation
Support the IntersectionObserver scrollMargin option - #60153
Open
rubennorte wants to merge 1 commit into
Open
rubennorte wants to merge 1 commit into
rubennorte wants to merge 1 commit into
Conversation
rubennorte
force-pushed
the
intersection-observer-scroll-margin
branch
2 times, most recently
from
November 19, 2026 17:13
8236222 to
f2d860b
Compare
Summary: `rootMargin` only dilates the root intersection rectangle, so it cannot reveal a target hidden inside an intermediate scroll container. Per spec that is `scrollMargin`'s job: it dilates the clip rect of every scrollport on the path from the root to the target, and of the root itself when the root is scrollable. Until now `scrollMargin` was explicitly rejected — the constructor threw on `'scrollMargin' in options` and the getter always threw. D117876568 (react#58177) did the groundwork by adding `clipSpecifiedAncestor` and excluding the observation root from the ancestor clip walk, matching the spec's "while container is not root" loop. Per spec, only nodes with a content clip clip the target, and only scroll containers have their clip rects dilated. RN's clip walk used to clip at every node, including the target itself and `overflow: visible` ancestors (to their content bounds). That is a no-op without margins, but not with them: dilating those clips shrinks the target for negative (or mixed-sign) margins, and not dilating them lets a `visible` node re-clip content that a dilated scroll container below it revealed (e.g. the content container between two nested ScrollViews). So the walk now only clips at nodes with a content clip, only dilates scroll containers, and never dilates the measured node's own clip, since the spec starts the walk at its containing block. `overflowInset` cannot identify these nodes (it is also zero for a `visible` node whose children fit), and `react/renderer/core` cannot see Yoga styles, so `LayoutableShadowNode` gains virtual `hasContentClip()` and `isScrollContainer()` (both default `false`). `YogaLayoutableShadowNode` returns `overflow != visible` for the former and `overflow` is `hidden` or `scroll` for the latter. They're the same set today, but CSS `overflow: clip` is a content clip without being a scroll container, and `isScrollContainer()` uses an exhaustive switch so new `overflow` values must be classified explicitly. Only IntersectionObserver uses this clipping mode. Per spec, "both the scrollMargin and the rootMargin are applied to a scrollable intersection root's rectangle". The rect targets are clipped against is therefore further dilated by `scrollMargin` when the explicit root is a scroll container, with percentages resolved against the undilated root. `rootBounds` is the root intersection rectangle, which only `rootMargin` dilates, so it is unaffected. Changes: - `MarginValue` moves from `IntersectionObserver.h` to `RectangleEdges.h` (`react/renderer/core` cannot depend on `observers/intersection`), gaining `EdgeMargins` and `resolveEdgeMargins()`. This replaces the index-based `std::vector<MarginValue>` with named edges and retires `calculateRootMarginInsets`. - `LayoutInspectingPolicy` gains `std::optional<EdgeMargins> clipMargin`, applied to scroll-container ancestors only. The margins travel unresolved because percentages must resolve against each individual scrollport. - `enableOverflowClipping` only clips at nodes with a content clip. - `LayoutableShadowNode::hasContentClip()` and `isScrollContainer()`, overridden by `YogaLayoutableShadowNode`. - `IntersectionObserver` applies `scrollMargin` to a scrollable explicit root's clip rect. - `parseNormalizedRootMargin` becomes `parseNormalizedMargin`, returning `std::optional<EdgeMargins>` and shared by both options. - JS: `scrollMargin` added to `IntersectionObserverInit`, the throws are removed, and `normalizeRootMargin` becomes `normalizeMargin(value, name)` so errors name the right property. - RNTester: a prefetching example (toggle between `rootMargin` and `scrollMargin`, reporting items of a ScrollView within 500px of the viewport) showing that only `scrollMargin` can see past the ScrollView. One deviation, inherited from the existing `rootMargin` code: percentages on the vertical edges resolve against height (the spec resolves all four against width). Changelog: [GENERAL] [ADDED] - Support the `scrollMargin` option in IntersectionObserver Test Plan: New Fantom tests cover parsing and the getter, plus behaviour: revealing a target past an intermediate ScrollView, partial and insufficient margins, percentages resolved per scrollport, negative values, negative values not affecting `overflow: visible` ancestors or the target itself, `overflow: hidden` ancestors, scrollable and non-scrollable explicit roots (including combination with `rootMargin` and percentage resolution against the undilated root), nested ScrollViews, horizontal edges, the top edge after scrolling, and composition with `rootMargin` on the implicit root. ``` yarn fantom packages/react-native/src/private/webapis/intersectionobserver/ ``` All tests pass. With the C++ changes from the review fixes reverted, the negative-margin and scrollable-root tests fail, as expected. ``` yarn flow-check yarn lint ``` Clean. Manually verified the RNTester example on an iOS simulator. The `scripts/cxx-api/api-snapshots/*.api` files were taken from CI's `validate_cxx_api_snapshots` run (Doxygen 1.16.1); the only changes are the new public symbols above and the codegen'd `scrollMargin` option.
rubennorte
force-pushed
the
intersection-observer-scroll-margin
branch
from
November 19, 2026 18:41
f2d860b to
d64a9d0
Compare
rubennorte
marked this pull request as ready for review
November 19, 2026 18:42
|
@rubennorte has imported this pull request. If you are a Meta employee, you can view this in D133273865. |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Stacked on #60152, which this PR includes. Only the top commit (
feat: support the IntersectionObserver scrollMargin option) is new here.Summary:
rootMarginonly dilates the root intersection rectangle, so it can't reveal a target hidden inside an intermediate scroll container. In the spec, that'sscrollMargin's job: it dilates the clip rect of every scrollport on the path from the root to the target, and the root's own rect when the root is scrollable. A typical use is prefetching data or images for list items before they scroll into view.Until now,
scrollMarginwas rejected: the constructor threw if'scrollMargin' in options, and the getter always threw.Only scroll containers clip, and only their clip rects are dilated. RN's clip walk used to clip at every node, including the target itself and
overflow: visibleancestors (to their content bounds). That's a no-op without margins, but not with them:visiblenode re-clip content that a dilated scroll container below it revealed, e.g. the content container between two nested ScrollViews.So the walk now only clips at scroll containers, and never dilates the measured node's own clip, since the spec starts the walk at its containing block.
overflowInsetcan't identify scroll containers (it's also zero for avisiblenode whose children fit), andreact/renderer/corecan't see Yoga styles. SoLayoutableShadowNodegains a virtualisScrollContainer(), which defaults tofalseand whichYogaLayoutableShadowNodeoverrides to return whetheroverflow != visible. Only IntersectionObserver uses this clipping mode.Scrollable explicit roots. Per spec, "both the scrollMargin and the rootMargin are applied to a scrollable intersection root's rectangle". When the explicit root is a scroll container, the rect targets are clipped against is also dilated by
scrollMargin, with percentages resolved against the undilated root.rootBoundsis the root intersection rectangle, which onlyrootMargindilates, so it's unaffected.Changes:
MarginValuemoves fromIntersectionObserver.htoRectangleEdges.h, becausereact/renderer/corecan't depend onobservers/intersection. It gainsEdgeMarginsandresolveEdgeMargins(), which replace the index-basedstd::vector<MarginValue>with named edges and retirecalculateRootMarginInsets.LayoutInspectingPolicygainsstd::optional<EdgeMargins> clipMargin. The margins are passed unresolved, because percentages must resolve against each individual scrollport.enableOverflowClippingonly clips at scroll containers.LayoutableShadowNode::isScrollContainer(), overridden byYogaLayoutableShadowNode.IntersectionObserverappliesscrollMarginto a scrollable explicit root's clip rect.parseNormalizedRootMarginbecomesparseNormalizedMargin, returningstd::optional<EdgeMargins>, and is shared by both options.scrollMarginis added toIntersectionObserverInit, the throws are removed, andnormalizeRootMarginbecomesnormalizeMargin(value, name)so errors name the right property.rootMarginandscrollMargin. It reports items of aScrollViewwithin 500px of the viewport, showing that onlyscrollMargincan see past theScrollView.One deviation from the spec, inherited from the existing
rootMargincode: percentages on the vertical edges resolve against height, while the spec resolves all four against width.Changelog:
[GENERAL] [ADDED] - Support the
scrollMarginoption in IntersectionObserverTest Plan:
New Fantom tests cover parsing and the getter, plus behaviour:
overflow: visibleancestors or the target itselfoverflow: hiddenancestorsrootMarginand percentage resolution against the undilated rootrootMarginon the implicit root138 passed, 1 skipped. With the C++ clipping changes reverted, the 5 negative-margin and scrollable-root tests fail, as expected.
Clean.
Manually verified the RNTester example (IntersectionObserver → "IntersectionObserver scrollMargin Prefetch Example") on an iOS simulator: with
rootMargin, only items actually visible in the ScrollView are reported; withscrollMargin, items ahead of the scrollport are reported before they scroll into view.Not done yet: the C++ API snapshots (
scripts/cxx-api/api-snapshots/*.api). I couldn't reproduce CI's Doxygen 1.16.1 output locally, so they'll be taken from this PR'svalidate_cxx_api_snapshotsrun. This PR is a draft until then.