view-anchor 0.2.2 → 1.0.0-beta.0

package/dist/view-anchor.js

@@ -1,143 +1,17 @@
 import { watchAbort } from './abort.js';
-const ZERO = { x: 0, y: 0, width: 0, height: 0 };
 // Replaces a disposed instance's publish callback so a retained handle does
 // not keep the caller's original callback (and whatever it captured) alive.
 const NOOP_PUBLISH = () => false;
-// Round to integer pixels. Width and height are clamped to >= 0 (0 represents
-// a collapsed rect). Coordinates (x, y) can be negative when an element is
-// scrolled out of view; clamping them to 0 would pin the view to the screen edge.
+// Default holdSelector: omitting the option keeps tracking presses on a role=separator splitter.
+export const DEFAULT_HOLD_SELECTOR = '[role="separator"]';
+// Round to integer pixels. Width and height are clamped to >= 0; x and y can be
+// negative, so a view scrolled out of sight is not pinned to the screen edge.
 const clampRect = (r) => ({
     x: Math.round(r.x),
     y: Math.round(r.y),
     width: Math.max(0, Math.round(r.width)),
     height: Math.max(0, Math.round(r.height)),
 });
-/**
- * Bind a native view or external surface to the geometry of `target`.
- *
- * - `present === true`: measures `target.getBoundingClientRect()` and publishes
- *   immediately, then re-measures synchronously on ResizeObserver and window resize.
- * - `present === false`: publishes a zero rect ({ x: 0, y: 0, width: 0, height: 0 })
- *   and stops observing.
- * - `update(opts)`: re-applies options immediately.
- * - `dispose()`: stops observing and prevents any further publishes.
- *
- * Synchronous publishing: measurement and publishing occur directly in the
- * observer tick. Applying geometry outside the DOM may already be delayed;
- * adding requestAnimationFrame would add another frame of visual lag during drag
- * operations. High-frequency updates are deduplicated against the last accepted rect.
- */
-export function createViewAnchor(target, opts) {
-    let present = opts.present;
-    let publish = opts.publish;
-    let observer = null;
-    // Local, clearable alias for the `target` parameter so dispose() can drop
-    // the strong reference without widening the public parameter's type.
-    let targetRef = target;
-    // Last rect sent to publish. Reset on apply() so state changes (such as zoom)
-    // force a re-publish even if the geometry did not change.
-    let lastPublished = null;
-    let publicationRevision = 0;
-    let disposed = false;
-    const measure = () => {
-        const r = targetRef.getBoundingClientRect();
-        // Drop ticks with non-finite values (NaN / Infinity are not usable geometry).
-        if (!Number.isFinite(r.left) ||
-            !Number.isFinite(r.top) ||
-            !Number.isFinite(r.width) ||
-            !Number.isFinite(r.height))
-            return null;
-        return clampRect({ x: r.left, y: r.top, width: r.width, height: r.height });
-    };
-    const sameRect = (a, b) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
-    const publishCandidate = (candidate) => {
-        const previous = lastPublished;
-        const attempt = ++publicationRevision;
-        lastPublished = candidate;
-        try {
-            const accepted = publish(candidate) !== false;
-            // A reentrant dispose() during publish() already cleared lastPublished;
-            // do not resurrect the pre-dispose value over that terminal state.
-            if (!accepted && publicationRevision === attempt && !disposed)
-                lastPublished = previous;
-            return accepted;
-        }
-        catch (error) {
-            if (publicationRevision === attempt && !disposed)
-                lastPublished = previous;
-            throw error;
-        }
-    };
-    // Measure and publish synchronously on each observer tick.
-    // Drops duplicate rects to coalesce same-frame resize events.
-    const emit = () => {
-        if (disposed || !present)
-            return;
-        const m = measure();
-        if (!m)
-            return;
-        if (lastPublished && sameRect(lastPublished, m))
-            return;
-        publishCandidate(m);
-    };
-    const startObserving = () => {
-        if (observer)
-            return;
-        observer = new ResizeObserver(emit);
-        observer.observe(targetRef);
-        window.addEventListener('resize', emit);
-    };
-    const stopObserving = () => {
-        if (observer) {
-            observer.disconnect();
-            observer = null;
-        }
-        window.removeEventListener('resize', emit);
-    };
-    // Apply current options synchronously. Reset lastPublished so state changes
-    // always re-publish even if dimensions have not changed.
-    const apply = () => {
-        lastPublished = null;
-        if (present) {
-            startObserving();
-            const measured = measure();
-            if (measured)
-                publishCandidate(measured);
-        }
-        else {
-            stopObserving();
-            publishCandidate(ZERO);
-        }
-    };
-    let removeAbortListener = () => { };
-    const dispose = () => {
-        if (disposed)
-            return;
-        disposed = true;
-        removeAbortListener();
-        removeAbortListener = () => { };
-        stopObserving();
-        targetRef = null;
-        publish = NOOP_PUBLISH;
-        lastPublished = null;
-    };
-    if (opts.signal?.aborted)
-        dispose();
-    else {
-        removeAbortListener = watchAbort(opts.signal, dispose);
-        apply();
-    }
-    return {
-        update(next) {
-            if (disposed)
-                return;
-            publish = next.publish;
-            present = next.present;
-            apply();
-        },
-        dispose,
-    };
-}
 /**
  * Read target's current rect and return { visible: true, bounds }.
  * Does not infer visibility from dimensions.
@@ -161,19 +35,31 @@ const samePlacement = (a, b) => {
     return true;
 };
 /**
- * Explicit-visibility variant of createViewAnchor.
+ * Bind a native view or external surface to the geometry of `target`.
+ *
+ * When `visible === true`, publishes { visible: true, bounds } immediately,
+ * then re-measures synchronously on ResizeObserver and window resize.
+ * When `visible === false`, publishes { visible: false } and stops observing.
+ * Publishes are deduplicated against the last accepted Placement by default
+ * (see the `dedupe` option).
  */
-export function createPlacementAnchor(target, opts) {
+export function createViewAnchor(target, opts) {
+    // A non-empty holdSelector must be a syntactically valid CSS selector
+    // (matches() throws SyntaxError otherwise). Validate before any state is
+    // created so a bad selector never partially applies.
+    if (opts.holdSelector)
+        target.matches(opts.holdSelector);
     let visible = opts.visible;
     let publish = opts.publish;
-    let guardDisplayNone = opts.guardDisplayNone ?? false;
+    let treatZeroAreaAsHidden = opts.treatZeroAreaAsHidden ?? false;
     let followScroll = opts.followScroll ?? false;
     let followGeometry = opts.followGeometry ?? false;
-    // Local, clearable alias for the `target` parameter so dispose() can drop
-    // the strong reference without widening the public parameter's type.
+    let holdSelector = opts.holdSelector === undefined ? DEFAULT_HOLD_SELECTOR : opts.holdSelector;
+    let dedupe = opts.dedupe ?? true;
+    // Clearable alias so dispose() can drop the reference.
     let targetRef = target;
     let observer = null;
-    let io = null;
+    let intersectionObserver = null;
     let scrollListening = false;
     let geometryListening = false;
     const capture = { capture: true };
@@ -181,20 +67,25 @@ export function createPlacementAnchor(target, opts) {
     let lastPublished = null;
     let publicationRevision = 0;
     let disposed = false;
-    // --- Windowed RAF geometry sentinel state ---
-    // The sentinel polls per frame during active movement and auto-closes once
+    // --- Frame following (followGeometry) state ---
+    // Frame following polls per frame during active movement and auto-closes once
     // geometry settles. While closed, no frame is scheduled (zero idle overhead).
     let rafId = null;
     let steadyFrames = 0;
     const STEADY_CLOSE_FRAMES = 2;
     const MAX_HIDDEN_FOLLOW_FRAMES = 30;
     const MAX_INVALID_FOLLOW_FRAMES = 30;
+    let hiddenFrames = 0;
     let invalidFrames = 0;
-    // True while a [role="separator"] splitter drag is held.
-    let pointerHeld = false;
-    let activePointerId = null;
-    let sentinelDeadline = null;
-    const computePlacement = () => {
+    // Pointer ids currently matching holdSelector and held down. Non-empty
+    // keeps frame following open regardless of deadline or steady frames.
+    const heldPointerIds = new Set();
+    // The rect measured on the previous followed frame, independent of whether
+    // publish() accepted it. Drives the steady/moving decision so a publish()
+    // that keeps rejecting an unchanged measurement cannot keep resetting it.
+    let lastFramePlacement = null;
+    let followDeadline = null;
+    const measureTarget = () => {
         const p = measurePlacement(targetRef);
         if (p.visible &&
             (!Number.isFinite(p.bounds.x) ||
@@ -202,12 +93,12 @@ export function createPlacementAnchor(target, opts) {
                 !Number.isFinite(p.bounds.width) ||
                 !Number.isFinite(p.bounds.height)))
             return null;
-        if (guardDisplayNone && p.visible && (p.bounds.width === 0 || p.bounds.height === 0)) {
+        if (treatZeroAreaAsHidden && p.visible && (p.bounds.width === 0 || p.bounds.height === 0)) {
             return { visible: false };
         }
         return p;
     };
-    const publishCandidate = (candidate) => {
+    const publishPlacement = (candidate) => {
         const previous = lastPublished;
         const attempt = ++publicationRevision;
         lastPublished = candidate;
@@ -225,140 +116,151 @@ export function createPlacementAnchor(target, opts) {
             throw error;
         }
     };
-    const emit = () => {
+    const measureAndPublish = () => {
         if (disposed || !visible)
             return;
-        const p = computePlacement();
+        const p = measureTarget();
         if (!p)
             return;
-        if (lastPublished && samePlacement(lastPublished, p))
+        if (dedupe && lastPublished && samePlacement(lastPublished, p))
             return;
-        publishCandidate(p);
+        publishPlacement(p);
     };
-    const shouldCloseOnHiddenPoll = () => {
-        if (lastPublished?.visible === false)
-            return true;
-        return steadyFrames++ >= MAX_HIDDEN_FOLLOW_FRAMES;
+    // Polls again next frame if following is still wanted after this frame's work.
+    const scheduleFollowFrame = () => {
+        if (!disposed && visible && followGeometry)
+            rafId = requestAnimationFrame(followFrame);
+        else
+            followDeadline = null;
     };
-    const sentinelFrame = () => {
+    const followFrame = () => {
         rafId = null;
-        if (disposed || !visible) {
-            sentinelDeadline = null;
+        if (disposed ||
+            !visible ||
+            (heldPointerIds.size === 0 && followDeadline !== null && performance.now() >= followDeadline)) {
+            followDeadline = null;
             return;
         }
-        if (sentinelDeadline !== null && performance.now() >= sentinelDeadline) {
-            sentinelDeadline = null;
-            return;
-        }
-        const p = computePlacement();
+        const p = measureTarget();
         if (!p) {
-            if (invalidFrames++ >= MAX_INVALID_FOLLOW_FRAMES) {
-                sentinelDeadline = null;
-                return;
-            }
-            if (!disposed && visible && followGeometry) {
-                rafId = requestAnimationFrame(sentinelFrame);
-            }
-            else {
-                sentinelDeadline = null;
-            }
+            if (++invalidFrames >= MAX_INVALID_FOLLOW_FRAMES)
+                followDeadline = null;
+            else
+                scheduleFollowFrame();
             return;
         }
         invalidFrames = 0;
         if (!p.visible) {
-            if (shouldCloseOnHiddenPoll()) {
-                sentinelDeadline = null;
-                return;
-            }
-            if (!disposed && visible && followGeometry) {
-                rafId = requestAnimationFrame(sentinelFrame);
+            // Hidden frames are never published here; stop once hidden is already
+            // published or the target stays hidden past its budget.
+            if (lastPublished?.visible === false || ++hiddenFrames >= MAX_HIDDEN_FOLLOW_FRAMES) {
+                followDeadline = null;
             }
             else {
-                sentinelDeadline = null;
+                scheduleFollowFrame();
             }
             return;
         }
-        if (lastPublished && samePlacement(lastPublished, p)) {
-            steadyFrames++;
-            if (steadyFrames >= STEADY_CLOSE_FRAMES && !pointerHeld) {
-                sentinelDeadline = null;
+        // Steadiness is judged against what was measured last frame, not against
+        // what publish() accepted: a candidate that publish() keeps rejecting
+        // must not keep looking "different" forever just because publishPlacement
+        // rolls lastPublished back on rejection, which would spin the frame loop.
+        const steadyFrame = lastFramePlacement !== null && samePlacement(lastFramePlacement, p);
+        lastFramePlacement = p;
+        if (!dedupe || !lastPublished || !samePlacement(lastPublished, p))
+            publishPlacement(p);
+        if (steadyFrame) {
+            if (++steadyFrames >= STEADY_CLOSE_FRAMES && heldPointerIds.size === 0) {
+                followDeadline = null;
                 return;
             }
         }
         else {
-            publishCandidate(p);
             steadyFrames = 0;
+            hiddenFrames = 0;
         }
-        if (!disposed && visible && followGeometry) {
-            rafId = requestAnimationFrame(sentinelFrame);
-        }
-        else {
-            sentinelDeadline = null;
-        }
+        scheduleFollowFrame();
     };
-    const openSentinel = () => {
+    const startFrameFollow = () => {
         if (!followGeometry || disposed)
             return;
         steadyFrames = 0;
+        hiddenFrames = 0;
+        // Seed from the last accepted placement so the first post-open frame
+        // doesn't look unsteady on an unchanged rect.
+        lastFramePlacement = lastPublished;
         if (rafId === null) {
             invalidFrames = 0;
-            rafId = requestAnimationFrame(sentinelFrame);
+            rafId = requestAnimationFrame(followFrame);
         }
     };
-    const closeSentinel = () => {
+    const stopFrameFollow = () => {
         if (rafId !== null) {
             cancelAnimationFrame(rafId);
             rafId = null;
         }
         steadyFrames = 0;
+        hiddenFrames = 0;
         invalidFrames = 0;
-        sentinelDeadline = null;
-        pointerHeld = false;
-        activePointerId = null;
+        lastFramePlacement = lastPublished;
+        followDeadline = null;
+        heldPointerIds.clear();
     };
     const onScroll = () => {
         if (followGeometry)
-            openSentinel();
+            startFrameFollow();
         else
-            emit();
+            measureAndPublish();
     };
     const onPointerDown = (e) => {
         const t = e.target;
-        if (t && t.closest && t.closest('[role="separator"]')) {
-            if (!pointerHeld)
-                activePointerId = e.pointerId;
-            pointerHeld = true;
-            openSentinel();
+        if (holdSelector && t && t.closest && t.closest(holdSelector)) {
+            // The first of possibly several concurrently-held pointers drops any
+            // pulse() deadline: a held press has no time limit.
+            if (heldPointerIds.size === 0)
+                followDeadline = null;
+            heldPointerIds.add(e.pointerId);
+            startFrameFollow();
         }
     };
-    const releasePointer = (e) => {
-        if (!pointerHeld)
+    // pointerId undefined means "release everything" (window blur, or an event
+    // that never carried a pointerId, matching the single-pointer tests that
+    // dispatch plain Events). Otherwise only that one id's hold ends, and the
+    // frame following only leaves its held (no-deadline) state once none remain.
+    const releasePointer = (pointerId) => {
+        if (heldPointerIds.size === 0)
             return;
-        if (e && activePointerId !== e.pointerId)
+        if (pointerId !== undefined && !heldPointerIds.delete(pointerId))
             return;
-        pointerHeld = false;
-        activePointerId = null;
-        openSentinel();
+        if (pointerId === undefined)
+            heldPointerIds.clear();
+        if (heldPointerIds.size > 0)
+            return;
+        followDeadline = null;
+        startFrameFollow();
     };
     const onPointerUp = (e) => {
-        releasePointer(e);
+        releasePointer(e.pointerId);
     };
     const onPointerCancel = (e) => {
-        releasePointer(e);
+        releasePointer(e.pointerId);
     };
     const onWindowBlur = () => {
         releasePointer();
     };
     const startOptionalObserving = () => {
-        if (guardDisplayNone && !io && typeof IntersectionObserver !== 'undefined') {
-            io = new IntersectionObserver(emit);
-            io.observe(targetRef);
+        if (treatZeroAreaAsHidden &&
+            !intersectionObserver &&
+            typeof IntersectionObserver !== 'undefined') {
+            intersectionObserver = new IntersectionObserver(measureAndPublish);
+            intersectionObserver.observe(targetRef);
         }
         if (followScroll && !scrollListening) {
             window.addEventListener('scroll', onScroll, passiveCapture);
             scrollListening = true;
         }
-        if (followGeometry && !geometryListening) {
+        // Mounted only while both followGeometry and holdSelector are set.
+        if (followGeometry && holdSelector && !geometryListening) {
             window.addEventListener('pointerdown', onPointerDown, capture);
             window.addEventListener('pointerup', onPointerUp, capture);
             window.addEventListener('pointercancel', onPointerCancel, capture);
@@ -366,48 +268,50 @@ export function createPlacementAnchor(target, opts) {
             geometryListening = true;
         }
     };
-    const stopOptionalObserving = () => {
-        if (io && !guardDisplayNone) {
-            io.disconnect();
-            io = null;
-        }
-        if (scrollListening && !followScroll) {
-            window.removeEventListener('scroll', onScroll, passiveCapture);
-            scrollListening = false;
-        }
-        if (geometryListening && !followGeometry) {
-            window.removeEventListener('pointerdown', onPointerDown, capture);
-            window.removeEventListener('pointerup', onPointerUp, capture);
-            window.removeEventListener('pointercancel', onPointerCancel, capture);
-            window.removeEventListener('blur', onWindowBlur);
-            geometryListening = false;
-            closeSentinel();
-        }
+    const stopIntersection = () => {
+        if (!intersectionObserver)
+            return;
+        intersectionObserver.disconnect();
+        intersectionObserver = null;
     };
-    const stopAllOptionalObserving = () => {
-        if (io) {
-            io.disconnect();
-            io = null;
-        }
-        if (scrollListening) {
-            window.removeEventListener('scroll', onScroll, passiveCapture);
-            scrollListening = false;
-        }
-        if (geometryListening) {
-            window.removeEventListener('pointerdown', onPointerDown, capture);
-            window.removeEventListener('pointerup', onPointerUp, capture);
-            window.removeEventListener('pointercancel', onPointerCancel, capture);
-            window.removeEventListener('blur', onWindowBlur);
-            geometryListening = false;
+    const stopScroll = () => {
+        if (!scrollListening)
+            return;
+        window.removeEventListener('scroll', onScroll, passiveCapture);
+        scrollListening = false;
+    };
+    const stopGeometryListeners = () => {
+        if (!geometryListening)
+            return;
+        window.removeEventListener('pointerdown', onPointerDown, capture);
+        window.removeEventListener('pointerup', onPointerUp, capture);
+        window.removeEventListener('pointercancel', onPointerCancel, capture);
+        window.removeEventListener('blur', onWindowBlur);
+        geometryListening = false;
+    };
+    // Detaches only the optional observers whose flag has been turned off.
+    const stopDisabledObserving = () => {
+        if (!treatZeroAreaAsHidden)
+            stopIntersection();
+        if (!followScroll)
+            stopScroll();
+        // The pointer listeners are only useful while both flags hold; drop them
+        // (and any held-pointer state they were tracking) as soon as either lapses.
+        if ((!followGeometry || !holdSelector) && geometryListening) {
+            stopGeometryListeners();
+            heldPointerIds.clear();
         }
-        closeSentinel();
+        // Independent of whether the listeners were mounted: turning followGeometry
+        // off must always stop frame following, not just when holdSelector was set.
+        if (!followGeometry)
+            stopFrameFollow();
     };
     const startObserving = () => {
         if (observer)
             return;
-        observer = new ResizeObserver(emit);
+        observer = new ResizeObserver(measureAndPublish);
         observer.observe(targetRef);
-        window.addEventListener('resize', emit);
+        window.addEventListener('resize', measureAndPublish);
         startOptionalObserving();
     };
     const stopObserving = () => {
@@ -415,21 +319,24 @@ export function createPlacementAnchor(target, opts) {
             observer.disconnect();
             observer = null;
         }
-        window.removeEventListener('resize', emit);
-        stopAllOptionalObserving();
+        window.removeEventListener('resize', measureAndPublish);
+        stopIntersection();
+        stopScroll();
+        stopGeometryListeners();
+        stopFrameFollow();
     };
-    const apply = () => {
+    const applyOptions = () => {
         lastPublished = null;
         if (visible) {
             startObserving();
-            const placement = computePlacement();
+            const placement = measureTarget();
             if (placement)
-                publishCandidate(placement);
+                publishPlacement(placement);
         }
         else {
             stopObserving();
             const hidden = { visible: false };
-            publishCandidate(hidden);
+            publishPlacement(hidden);
         }
     };
     let removeAbortListener = () => { };
@@ -448,24 +355,38 @@ export function createPlacementAnchor(target, opts) {
         dispose();
     else {
         removeAbortListener = watchAbort(opts.signal, dispose);
-        apply();
+        // A throwing first publish must not leave the observer/listeners it just
+        // started (startObserving() runs before the first publishPlacement())
+        // mounted on a handle the caller never got to dispose.
+        try {
+            applyOptions();
+        }
+        catch (error) {
+            dispose();
+            throw error;
+        }
     }
     return {
         update(next) {
             if (disposed)
                 return;
+            // Validate before touching any state so a bad selector throws
+            // atomically and the previous holdSelector stays in effect.
+            if (next.holdSelector)
+                targetRef.matches(next.holdSelector);
             publish = next.publish;
             visible = next.visible;
-            // Omitting a flag preserves its current value so callers that only
-            // pass { visible, publish } don't inadvertently disable enabled flags.
-            guardDisplayNone = next.guardDisplayNone ?? guardDisplayNone;
-            followScroll = next.followScroll ?? followScroll;
-            followGeometry = next.followGeometry ?? followGeometry;
+            // Full configuration: omitted flags reset to defaults.
+            treatZeroAreaAsHidden = next.treatZeroAreaAsHidden ?? false;
+            followScroll = next.followScroll ?? false;
+            followGeometry = next.followGeometry ?? false;
+            holdSelector = next.holdSelector === undefined ? DEFAULT_HOLD_SELECTOR : next.holdSelector;
+            dedupe = next.dedupe ?? true;
             if (visible && observer) {
-                stopOptionalObserving();
+                stopDisabledObserving();
                 startOptionalObserving();
             }
-            apply();
+            applyOptions();
         },
         dispose,
         pulse(durationMs) {
@@ -473,9 +394,9 @@ export function createPlacementAnchor(target, opts) {
                 return;
             if (durationMs !== undefined && durationMs > 0) {
                 const next = performance.now() + durationMs;
-                sentinelDeadline = sentinelDeadline === null ? next : Math.max(sentinelDeadline, next);
+                followDeadline = followDeadline === null ? next : Math.max(followDeadline, next);
             }
-            openSentinel();
+            startFrameFollow();
         },
     };
 }