From f22fbf46bd4d676a8cddb0373cf1c834ad064481 Mon Sep 17 00:00:00 2001 From: tcaptan-cr <105748547+tcaptan-cr@users.noreply.github.com> Date: Wed, 13 Sep 2023 18:09:36 -0700 Subject: [PATCH] Add Scroll Margin to Intersection Observer (#511) * Added name to editors. * Added ScrollMargin definitions to IntersectionObserver interface section * Added ScrollMargin definitions to IntersectionObserverInit dictionary section * Added ScrollMargin definitions to Initialize a new IntersectionObserver section * Added ScrollMargin definitions to IntersectionObserver section * Add ScrollMargin to Intersection Computation section * Add ScrollMargin to Privacy and Security section * Change `scrollable intersection rectangles` to `scrollport` * Link 'margin' to css-box-3/#margins * Clarified application of both scroll and root margin to root rect * Update scrollMargin to match rootMargin * Fixed grammar and missed matching to rootMargin * Changed 'boxes' to 'clip rects' in scroll margin def * Clarified scrollable container * Simplified margin and scroll container links --- index.bs | 73 +++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 59 insertions(+), 14 deletions(-) diff --git a/index.bs b/index.bs index e2d638d..38c8426 100644 --- a/index.bs +++ b/index.bs @@ -8,6 +8,7 @@ Previous version: from biblio Level: none Editor: Stefan Zager, Google, szager@google.com, w3cid 91208 Editor: Emilio Cobos Álvarez , Mozilla, emilio@mozilla.com, w3cid 106537 +Editor: Traian Captan, Google, tcaptan@google.com, w3cid 137959 Former Editor: Michael Blain, Google, mpb@google.com, w3cid 73819 Abstract: This specification describes an API that can be used to understand the visibility and position of DOM elements ("targets") relative to a containing element or to the top-level viewport ("root"). The position is delivered asynchronously and is useful for understanding the visibility of elements and implementing pre-loading and deferred loading of DOM content. Group: webapps @@ -221,6 +222,7 @@ interface IntersectionObserver { constructor(IntersectionObserverCallback callback, optional IntersectionObserverInit options = {}); readonly attribute (Element or Document)? root; readonly attribute DOMString rootMargin; + readonly attribute DOMString scrollMargin; readonly attribute FrozenArray<double> thresholds; undefined observe(Element target); undefined unobserve(Element target); @@ -282,6 +284,20 @@ interface IntersectionObserver { passed to the {{IntersectionObserver}} constructor. If no {{IntersectionObserverInit/rootMargin}} was passed to the {{IntersectionObserver}} constructor, the value of this attribute is "0px 0px 0px 0px". + : scrollMargin + :: + Offsets are applied to scrollports on the path from intersection root to target, + effectively growing or shrinking the clip rects used to calculate intersections. + These offsets are only applied when handling same-origin-domain targets; + for cross-origin-domain targets they are ignored. + + On getting, return the result of serializing the elements of {{[[scrollMargin]]}} + space-separated, where pixel lengths serialize as the numeric value followed by "px", + and percentages serialize as the numeric value followed by "%". Note that + this is not guaranteed to be identical to the |options|.{{IntersectionObserverInit/scrollMargin}} + passed to the {{IntersectionObserver}} constructor. If no + {{IntersectionObserverInit/scrollMargin}} was passed to the {{IntersectionObserver}} + constructor, the value of this attribute is "0px 0px 0px 0px". : thresholds :: A list of thresholds, sorted in increasing numeric order, @@ -325,11 +341,24 @@ If a target {{Element}} is clipped by an ances intersection root, that clipping is unaffected by {{IntersectionObserver/rootMargin}}. -Note: Root intersection rectangle is not affected by +When calculating a scrollport intersection rectangle for +a same-origin-domain target, the rectangle is expanded +according to the offsets in the {{IntersectionObserver}}’s {{[[scrollMargin]]}} slot +in a manner similar to CSS's 'margin' property, +with the four values indicating the amount the top, right, bottom, and left edges, respectively, are offset by, +with positive lengths indicating an outward offset. +Percentages are resolved relative to the width of the undilated rectangle. + +Note: {{IntersectionObserver/scrollMargin}} affects the clipping of target +by all scrollable ancestors up to and including the intersection root. +Both the {{IntersectionObserver/scrollMargin}} and the {{IntersectionObserver/rootMargin}} +are applied to a scrollable intersection root's rectangle. + +Note: Root intersection rectangle and scrollport intersection rectangles are not affected by pinch zoom and will report the unadjusted viewport, consistent with the intent of pinch zooming (to act like a magnifying glass and NOT change layout.) -To parse a root margin +To parse a margin (root or scroll) from an input string |marginString|, returning either a list of 4 pixel lengths or percentages, or failure: @@ -438,6 +467,7 @@ The IntersectionObserverInit dictionary dictionary IntersectionObserverInit { (Element or Document)? root = null; DOMString rootMargin = "0px"; + DOMString scrollMargin = "0px"; (double or sequence<double>) threshold = 0; }; @@ -459,6 +489,13 @@ dictionary IntersectionObserverInit { "-10px 5px 8px" // top = -10px, right & left = 5px, bottom = 8px "-10px -5px 5px 8px" // top = -10px, right = -5px, bottom = 5px, left = 8px + : scrollMargin + :: + Similar to {{IntersectionObserverInit/rootMargin}}, + this is a string of 1-4 components, + each either an absolute length or a percentage. + + See {{IntersectionObserverInit/rootMargin}} above for the example. : threshold :: List of threshold(s) at which to trigger callback. @@ -510,8 +547,9 @@ IntersectionObserver which are initialized to empty lists and an internal \[[callback]] slot which is initialized by {{IntersectionObserver(callback, options)}}. -They also have an internal \[[rootMargin]] slot -which is a list of four pixel lengths or percentages. +They also have internal \[[rootMargin]] +and \[[scrollMargin]] slots +which are lists of four pixel lengths or percentages.

Algorithms

@@ -523,20 +561,25 @@ and an {{IntersectionObserverInit}} dictionary |options|, run these steps: 1. Let |this| be a new {{IntersectionObserver}} object 2. Set |this|'s internal {{[[callback]]}} slot to |callback|. -3. Attempt to parse a root margin +3. Attempt to parse a margin from |options|.{{IntersectionObserverInit/rootMargin}}. If a list is returned, set |this|'s internal {{[[rootMargin]]}} slot to that. Otherwise, throw a {{SyntaxError}} exception. -4. Let |thresholds| be a list equal to +4. Attempt to parse a margin + from |options|.{{IntersectionObserverInit/scrollMargin}}. + If a list is returned, + set |this|'s internal {{[[scrollMargin]]}} slot to that. + Otherwise, throw a {{SyntaxError}} exception. +5. Let |thresholds| be a list equal to |options|.{{IntersectionObserverInit/threshold}}. -5. If any value in |thresholds| is less than 0.0 or greater than +6. If any value in |thresholds| is less than 0.0 or greater than 1.0, throw a {{RangeError}} exception. -6. Sort |thresholds| in ascending order. -7. If |thresholds| is empty, append 0 to |thresholds|. -8. The {{IntersectionObserver/thresholds}} attribute getter will return +7. Sort |thresholds| in ascending order. +8. If |thresholds| is empty, append 0 to |thresholds|. +9. The {{IntersectionObserver/thresholds}} attribute getter will return this sorted |thresholds| list. -9. Return |this|. +10. Return |this|.

Observe a target Element

@@ -630,9 +673,11 @@ run these steps: of the {{document}}, and update |container| to be the browsing context container of |container|. 2. Map |intersectionRect| to the coordinate space of |container|. - 3. If |container| has a content clip or a css clip-path property, + 3. If |container| is a scroll container, apply the {{IntersectionObserver}}’s + {{[[scrollMargin]]}} to the |container|'s clip rect. + 4. If |container| has a content clip or a css clip-path property, update |intersectionRect| by applying |container|'s clip. - 4. If |container| is the root element of a browsing context, + 5. If |container| is the root element of a browsing context, update |container| to be the browsing context's {{document}}; otherwise, update |container| to be the containing block of |container|. @@ -760,7 +805,7 @@ it may provide to code running in the context of a cross-origin iframe about the geometry of the global viewport itself, which may be used to deduce the user's hardware configuration. The motivation for disabling the effects of {{IntersectionObserver/rootMargin}} - and suppressing {{IntersectionObserverEntry/rootBounds}} + and {{IntersectionObserver/scrollMargin}}, and suppressing {{IntersectionObserverEntry/rootBounds}} for cross-origin-domain targets is to prevent such probing. It should be noted that prior to {{IntersectionObserver}}, web developers