help-layer 1.1.0 → 1.3.0

package/src/floating.floatingui.js

@@ -0,0 +1,71 @@
+/**
+ * Alternate positioning backend built on Floating UI (@floating-ui/dom).
+ *
+ * This is the original implementation, kept verbatim so the library can switch back to Floating UI at
+ * any time. To revert:
+ *   1. in floating.js, change the re-export to `export * from './floating.floatingui.js';`
+ *   2. move `@floating-ui/dom` from devDependencies back to dependencies
+ *   3. restore the `@floating-ui/*` entries in the demo import maps (demo/index.html, demo/stress.html)
+ * The default backend is the dependency-free ./floating.self.js. The reference helpers
+ * (isFixedReference / isReferenceHidden / makeVirtualElement) are shared via ./reference.js, so both
+ * backends expose an identical public surface.
+ *
+ * Floating UI in a nutshell:
+ * - computePosition(reference, floating, options) returns the optimal (x,y) for "this moment".
+ * - autoUpdate(reference, floating, update) re-runs update on scroll/resize/element-size changes
+ *   (internally via ResizeObserver, etc.); the returned cleanup stops watching.
+ */
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
+
+import { isFixedReference, isReferenceHidden, makeVirtualElement } from './reference.js';
+
+// Re-export the shared reference helpers so this backend's surface matches floating.self.js exactly.
+export { isFixedReference, isReferenceHidden, makeVirtualElement };
+
+function place(el, x, y) {
+  el.style.left = `${x}px`;
+  el.style.top = `${y}px`;
+}
+
+/**
+ * Place the popup below the target, and at screen edges use flip / shift to avoid clipping.
+ * @param {Element|object} reference
+ * @param {HTMLElement} popupEl
+ * @param {import('./types.js').Placement} [placement] initial placement. Default 'bottom-start'
+ * @returns {{ update: () => void, cleanup: () => void }}
+ */
+export function anchorPopup(reference, popupEl, placement = 'bottom-start') {
+  // The reference is the clicked marker. If it's fixed (anchored to a fixed target), the popup must be
+  // fixed too or it jitters on scroll. Set position every open so reopening on a normal marker restores
+  // absolute. Inline !important beats the stylesheet's `position: absolute !important`.
+  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
+  popupEl.style.setProperty('position', strategy, 'important');
+  const update = () => {
+    computePosition(reference, popupEl, {
+      placement,
+      strategy,
+      middleware: [offset(8), flip({ padding: 8 }), shift({ padding: 8 })],
+    }).then(({ x, y }) => {
+      place(popupEl, x, y);
+    // Swallow per-frame rejections so a stray rejection doesn't reach the host's unhandledrejection
+    // handler (e.g. Sentry); this runs every animation frame, so logging would also flood the console.
+    }).catch(() => {});
+  };
+  // animationFrame: true so the popup tracks smoothly: its reference is the marker element, which the
+  // markers.js loop moves per frame, so the popup must re-evaluate per frame to stay glued.
+  const cleanup = autoUpdate(reference, popupEl, update, { animationFrame: true });
+  return { update, cleanup };
+}
+
+/**
+ * Watch a reference element's position/size changes and call onUpdate on every change.
+ * (Used to keep the blocking layer's clip-path hole following the toggle.) autoUpdate requires a
+ * floating element, so floatingEl is passed as a dummy that onUpdate doesn't actually position.
+ * @param {Element} referenceEl
+ * @param {HTMLElement} floatingEl
+ * @param {() => void} onUpdate
+ * @returns {() => void} cleanup
+ */
+export function watchReference(referenceEl, floatingEl, onUpdate) {
+  return autoUpdate(referenceEl, floatingEl, onUpdate);
+}

package/src/floating.js

@@ -1,170 +1,11 @@
 /**
- * A thin wrapper around Floating UI (@floating-ui/dom).
- * Use of Floating UI is confined to this one file; other modules only call the
- * purpose-specific functions (anchorMarker / anchorPopup / watchReference /
- * makeVirtualElement). That way, if Floating UI is ever swapped out, the blast
- * radius stays limited to here.
+ * Positioning seam. Every other module imports positioning from here (anchorPopup / watchReference /
+ * makeVirtualElement / isFixedReference / isReferenceHidden), so the backend can be swapped in one
+ * place without touching consumers.
  *
- * Floating UI in a nutshell (note for readers unfamiliar with the DOM):
- * - computePosition(reference, floating, options) computes the optimal placement
- *   coordinates (x,y) for "this exact moment" and returns them (one-shot).
- * - autoUpdate(reference, floating, update) watches scroll, resize, and element-size
- *   changes (internally using ResizeObserver, etc.) and calls update on every change.
- *   Calling the returned cleanup stops watching. This is what makes the element "stick"
- *   to its target.
+ * Default: ./floating.self.js — dependency-free.
+ * To switch back to Floating UI, change the line below to:
+ *   export * from './floating.floatingui.js';
+ * and move `@floating-ui/dom` from devDependencies back to dependencies (see that file's header).
  */
-import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
-
-import { docRectToViewportRect } from './geometry.js';
-
-/**
- * Create a "virtual reference element" for free-placement items not bound to an element.
- * When getDocRect() returns document coordinates, this converts them to viewport
- * coordinates according to the current scroll. Because autoUpdate re-evaluates on every
- * scroll, the element sticks to the given coordinate while scrolling along with the page.
- * @param {() => {top:number,left:number,width?:number,height?:number}} getDocRect
- */
-export function makeVirtualElement(getDocRect) {
-  return {
-    // Tell autoUpdate that this element's ancestor is body (= scroll is watched up to window).
-    // Without this the virtual element isn't scroll-watched and won't follow page scroll.
-    contextElement: document.body,
-    getBoundingClientRect() {
-      return docRectToViewportRect(getDocRect(), { x: window.scrollX, y: window.scrollY });
-    },
-  };
-}
-
-function place(el, x, y) {
-  el.style.left = `${x}px`;
-  el.style.top = `${y}px`;
-}
-
-/**
- * Whether the reference lives in a `position: fixed` subtree. Such a reference stays put in the
- * viewport while the page scrolls, so an absolutely-positioned floating element (which scrolls with
- * the document) would have to be re-corrected every frame and visibly jitters. For these we switch the
- * floating element to Floating UI's `fixed` strategy (and position:fixed) so both live in the same
- * viewport space and stay glued without per-frame correction.
- *
- * Virtual elements (free placements) aren't in the DOM and already track scroll via their getRect, so
- * they report false. Walks across shadow boundaries via the host so Shadow DOM targets are handled too.
- * @param {Element|object} reference
- */
-export function isFixedReference(reference) {
-  if (!(reference instanceof Element)) {
-    return false;
-  }
-  let node = reference;
-  while (node) {
-    if (getComputedStyle(node).position === 'fixed') {
-      return true;
-    }
-    const parent = node.parentElement;
-    if (parent) {
-      node = parent;
-    } else {
-      const root = node.getRootNode();
-      node = root instanceof ShadowRoot ? root.host : null;
-    }
-  }
-  return false;
-}
-
-// Half of the default marker size (22px). The amount used to overlap the marker onto the
-// target's corner with an "inset". (If the marker-size CSS variable is changed, the resulting
-// drift is left as existing behavior = not compensated for here.)
-const MARKER_INSET = 11;
-
-/**
- * Derive the offset for overlapping the marker onto the target's corner from the placement.
- * mainAxis is always negative (bites inward past the target's edge). crossAxis flips sign by
- * alignment direction: `-end` (right/bottom-aligned) is negative to go inward, `-start`
- * (left/top-aligned) is positive to go inward.
- * @param {string} placement
- */
-function markerOffset(placement) {
-  const isStart = placement.endsWith('-start');
-  return { mainAxis: -MARKER_INSET, crossAxis: isStart ? MARKER_INSET : -MARKER_INSET };
-}
-
-/**
- * Overlap the marker onto a corner of the target (element or virtual element), stick it there, and keep it following.
- * @param {Element|object} reference
- * @param {HTMLElement} markerEl
- * @param {() => void} [onPlaced] called every time placement is finalized (used to trigger the overlap-avoidance pass, etc.)
- * @param {import('@floating-ui/dom').Placement} [placement] corner to overlap (top-end/top-start/bottom-end/bottom-start). Default 'top-end'
- * @returns {() => void} cleanup
- */
-export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end') {
-  // Match the floating element's strategy to the reference: a fixed reference needs a fixed marker, or
-  // it jitters while scrolling (see isFixedReference). Inline !important beats the stylesheet's
-  // `position: absolute !important`.
-  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
-  if (strategy === 'fixed') {
-    markerEl.style.setProperty('position', 'fixed', 'important');
-  }
-  const update = () => {
-    computePosition(reference, markerEl, {
-      placement,
-      strategy,
-      middleware: [offset(markerOffset(placement))],
-    }).then(({ x, y }) => {
-      place(markerEl, x, y);
-      if (onPlaced) {
-        onPlaced();
-      }
-    // Swallow silently: this runs every animation frame, so logging would flood the console, and a
-    // stray rejection must not surface in the host app's unhandledrejection handler (e.g. Sentry).
-    }).catch(() => {});
-  };
-  // animationFrame: true syncs repositioning to the rAF loop. With the default (scroll/resize
-  // events only), computePosition resolves asynchronously, so left/top is written the frame after
-  // the browser already painted the scroll — the marker lags a frame and visibly jitters.
-  return autoUpdate(reference, markerEl, update, { animationFrame: true });
-}
-
-/**
- * Place the popup below the target, and at screen edges use flip (flip to the opposite side) /
- * shift (nudge) to avoid clipping. Only follows while visible.
- * @param {Element|object} reference
- * @param {HTMLElement} popupEl
- * @param {import('@floating-ui/dom').Placement} [placement] initial placement (Floating UI placement). Default 'bottom-start'
- * @returns {{ update: () => void, cleanup: () => void }}
- *   calling update repositions immediately (used for reference-side transform moves that autoUpdate doesn't pick up, etc.).
- */
-export function anchorPopup(reference, popupEl, placement = 'bottom-start') {
-  // The reference is the clicked marker. If it's fixed (anchored to a fixed target), the popup must be
-  // fixed too or it jitters on scroll. Set position every open so reopening on a normal marker restores
-  // absolute. Inline !important beats the stylesheet's `position: absolute !important`.
-  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
-  popupEl.style.setProperty('position', strategy, 'important');
-  const update = () => {
-    computePosition(reference, popupEl, {
-      placement,
-      strategy,
-      middleware: [offset(8), flip({ padding: 8 }), shift({ padding: 8 })],
-    }).then(({ x, y }) => {
-      place(popupEl, x, y);
-    // Same rationale as anchorMarker: swallow per-frame rejections so they don't reach the host.
-    }).catch(() => {});
-  };
-  // animationFrame: true for the same smooth-tracking reason as anchorMarker. The reference here is
-  // the marker element, which itself moves per frame, so the popup must track per frame to stay glued.
-  const cleanup = autoUpdate(reference, popupEl, update, { animationFrame: true });
-  return { update, cleanup };
-}
-
-/**
- * Watch a reference element's position/size changes and call onUpdate on every change.
- * (Used for non-placement purposes, e.g. keeping the blocking layer's clip-path hole following the toggle position.)
- * autoUpdate requires a floating element, so floatingEl is just passed as a dummy that
- * onUpdate doesn't actually position.
- * @param {Element} referenceEl
- * @param {HTMLElement} floatingEl
- * @param {() => void} onUpdate
- * @returns {() => void} cleanup
- */
-export function watchReference(referenceEl, floatingEl, onUpdate) {
-  return autoUpdate(referenceEl, floatingEl, onUpdate);
-}
+export * from './floating.self.js';

package/src/floating.self.js

@@ -0,0 +1,109 @@
+/**
+ * Default positioning backend — dependency-free (no Floating UI).
+ *
+ * Markers position themselves in markers.js; this module only handles the single shared popup and the
+ * blocking layer's toggle-following clip-path. It re-implements the small slice of Floating UI the
+ * library used: place-on-a-side + offset + flip + shift (see computePopupPosition in geometry.js), and
+ * an autoUpdate-style tracker (track) built on the same per-frame rAF pattern markers.js uses.
+ *
+ * The reference helpers (isFixedReference / isReferenceHidden / makeVirtualElement) live in
+ * reference.js and are re-exported so this backend and floating.floatingui.js have an identical
+ * surface — the two are interchangeable via the one-line seam in floating.js.
+ */
+import { computePopupPosition, viewportToAbsolute } from './geometry.js';
+import { isFixedReference, isReferenceHidden, makeVirtualElement } from './reference.js';
+
+export { isFixedReference, isReferenceHidden, makeVirtualElement };
+
+function place(el, x, y) {
+  el.style.left = `${x}px`;
+  el.style.top = `${y}px`;
+}
+
+function sameRect(a, b) {
+  return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
+}
+
+/**
+ * Keep calling onChange while the reference moves/resizes: once synchronously now (like Floating UI's
+ * initial autoUpdate run), then on every animation frame in which the reference's rect changed. The
+ * popup's reference is the marker, which markers.js moves per frame, so per-frame tracking keeps the
+ * popup glued; an unchanged rect costs only one getBoundingClientRect and no work.
+ * @param {Element|object} reference
+ * @param {() => void} onChange
+ * @returns {() => void} cleanup
+ */
+function track(reference, onChange) {
+  onChange(); // initial placement, synchronous
+  let prev = reference.getBoundingClientRect();
+  let stopped = false;
+  let frame = requestAnimationFrame(function loop() {
+    if (stopped) {
+      return;
+    }
+    const rect = reference.getBoundingClientRect();
+    if (!sameRect(rect, prev)) {
+      onChange();
+    }
+    prev = rect;
+    frame = requestAnimationFrame(loop);
+  });
+  // A viewport resize can change the popup's flip/shift even when the reference itself doesn't move
+  // (e.g. a popup shifted near the right edge while its marker stays put). The rect-change loop above
+  // wouldn't catch that, so listen for resize explicitly — matching the Floating UI backend, whose
+  // autoUpdate also reacts to ancestor/window resize.
+  const onResize = () => onChange();
+  window.addEventListener('resize', onResize);
+  return () => {
+    stopped = true;
+    cancelAnimationFrame(frame);
+    window.removeEventListener('resize', onResize);
+  };
+}
+
+/**
+ * Place the popup on a side of the target with a gap, flipping/shifting at screen edges to stay
+ * visible, and keep it following while open.
+ * @param {Element|object} reference
+ * @param {HTMLElement} popupEl
+ * @param {import('./types.js').Placement} [placement] initial placement. Default 'bottom-start'
+ * @returns {{ update: () => void, cleanup: () => void }}
+ */
+export function anchorPopup(reference, popupEl, placement = 'bottom-start') {
+  // Match the strategy to the reference: a fixed reference needs a fixed popup or it jitters on
+  // scroll. Set it every open so reopening on a normal marker restores absolute. Inline !important
+  // beats the stylesheet's `position: absolute !important`.
+  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
+  popupEl.style.setProperty('position', strategy, 'important');
+
+  const update = () => {
+    const refRect = reference.getBoundingClientRect();
+    const popupSize = { width: popupEl.offsetWidth, height: popupEl.offsetHeight };
+    const viewport = { width: window.innerWidth, height: window.innerHeight };
+    const { left, top } = computePopupPosition(refRect, popupSize, viewport, { placement });
+    if (strategy === 'fixed') {
+      place(popupEl, left, top); // fixed: viewport coordinates are used as-is
+    } else {
+      // absolute: convert viewport coords to body-relative (same scroll-invariant trick as markers).
+      const body = document.body;
+      const abs = viewportToAbsolute(left, top, body.getBoundingClientRect(), body.clientLeft, body.clientTop);
+      place(popupEl, abs.left, abs.top);
+    }
+  };
+
+  const cleanup = track(reference, update);
+  return { update, cleanup };
+}
+
+/**
+ * Watch a reference element's position/size changes and call onUpdate on every change.
+ * (Used to keep the blocking layer's clip-path hole following the toggle.) floatingEl is accepted for
+ * signature parity with the Floating UI backend but isn't used here.
+ * @param {Element} referenceEl
+ * @param {HTMLElement} _floatingEl unused (kept for backend parity)
+ * @param {() => void} onUpdate
+ * @returns {() => void} cleanup
+ */
+export function watchReference(referenceEl, _floatingEl, onUpdate) {
+  return track(referenceEl, onUpdate);
+}

package/src/geometry.js

@@ -1,8 +1,8 @@
 /**
  * Pure geometry calculations. Takes no DOM elements, only numbers already read off.
  *
- * Clamping things that overflow the viewport is handled by Floating UI's shift()
- * middleware. toDocumentPosition is used for the virtual-element math of free placement, etc.
+ * Clamping things that overflow the viewport is handled by computePopupPosition's shift step
+ * below. toDocumentPosition is used for the virtual-element math of free placement, etc.
  */
 
 /**
@@ -18,8 +18,8 @@ export function toDocumentPosition(rect, scroll) {
 
 /**
  * Convert a document-coordinate rect into a viewport-coordinate rect by subtracting
- * the current scroll offset. This is what the getBoundingClientRect of a Floating UI
- * virtual reference element (a free-placement marker) returns.
+ * the current scroll offset. This is what the getBoundingClientRect of a virtual
+ * reference element (a free-placement marker) returns.
  * @param {{top:number,left:number,width?:number,height?:number}} docRect
  * @param {{x:number,y:number}} scroll
  */
@@ -39,3 +39,167 @@ export function docRectToViewportRect(docRect, scroll) {
     height,
   };
 }
+
+// Half of the default marker size (24px). The marker bites this far inward past the target's edge so
+// it overlaps the corner with an "inset". (If the marker-size CSS variable is changed, the marker
+// size is read at runtime in markers.js, but this inset stays fixed = existing behavior.)
+export const MARKER_INSET = 12;
+
+/**
+ * Compute a marker's top-left in viewport coordinates so it overlaps a corner of the reference rect,
+ * replicating what Floating UI's computePosition(placement) + offset(markerOffset) produced before.
+ *
+ * placement is "<side>" or "<side>-<align>" where side is top/bottom/left/right and align is
+ * start/end (omitted = centered). The marker is a square of the given size. mainAxis bites INSET
+ * inward (overlapping the target edge); crossAxis nudges INSET inward from the aligned edge.
+ * @param {{top:number,left:number,width:number,height:number}} refRect viewport rect of the target
+ * @param {number} size marker width/height (square)
+ * @param {string} placement a placement string (see Placement in types.js; default 'top-end')
+ * @returns {{left:number, top:number}} viewport coordinates of the marker's top-left corner
+ */
+export function markerViewportTopLeft(refRect, size, placement = 'top-end') {
+  const [side, align] = placement.split('-');
+  const isStart = align === 'start';
+  // crossAxis: -end (right/bottom-aligned) goes inward negative; -start goes inward positive.
+  const cross = isStart ? MARKER_INSET : -MARKER_INSET;
+
+  let left;
+  let top;
+  if (side === 'top' || side === 'bottom') {
+    // Vertical placement: main axis is Y, cross axis is X.
+    top = side === 'top'
+      ? refRect.top - size + MARKER_INSET // above, then bite down into the target
+      : refRect.top + refRect.height - MARKER_INSET; // below, then bite up
+    if (align === 'start') {
+      left = refRect.left;
+    } else if (align === 'end') {
+      left = refRect.left + refRect.width - size;
+    } else {
+      left = refRect.left + refRect.width / 2 - size / 2;
+    }
+    left += cross;
+  } else {
+    // Horizontal placement (left/right): main axis is X, cross axis is Y.
+    left = side === 'left'
+      ? refRect.left - size + MARKER_INSET
+      : refRect.left + refRect.width - MARKER_INSET;
+    if (align === 'start') {
+      top = refRect.top;
+    } else if (align === 'end') {
+      top = refRect.top + refRect.height - size;
+    } else {
+      top = refRect.top + refRect.height / 2 - size / 2;
+    }
+    top += cross;
+  }
+  return { left, top };
+}
+
+/**
+ * Convert a viewport coordinate into the left/top to set on a `position:absolute` element whose
+ * offsetParent is `document.body`. Both the marker's reference rect and the body rect come from
+ * getBoundingClientRect (viewport space), so their difference is scroll-invariant — which is exactly
+ * why the marker stays anchored to its target as the page scrolls. clientLeft/clientTop subtract the
+ * body's border so the offset is measured from the body's padding-box origin (the absolute origin).
+ * For `position:fixed` markers no conversion is needed (viewport coordinates are used as-is).
+ * @param {number} vx viewport x
+ * @param {number} vy viewport y
+ * @param {{left:number, top:number}} bodyRect document.body's getBoundingClientRect
+ * @param {number} clientLeft document.body.clientLeft (left border width)
+ * @param {number} clientTop document.body.clientTop (top border width)
+ * @returns {{left:number, top:number}}
+ */
+export function viewportToAbsolute(vx, vy, bodyRect, clientLeft, clientTop) {
+  return {
+    left: vx - bodyRect.left - clientLeft,
+    top: vy - bodyRect.top - clientTop,
+  };
+}
+
+const clamp = (value, min, max) => Math.min(Math.max(value, min), Math.max(min, max));
+
+/**
+ * Compute the popup's top-left in viewport coordinates, replicating the small subset of Floating UI
+ * we relied on: place on a side of the reference with a gap (offset), flip to the opposite side when
+ * the preferred side doesn't fit (main axis), and shift along the cross axis to keep it inside the
+ * viewport (with padding). This covers the popup's case — a single element over document.body whose
+ * clipping boundary is the viewport — and is intentionally simpler than Floating UI (no nested
+ * clipping ancestors / transforms / RTL).
+ *
+ * placement is "<side>" or "<side>-<align>" (side: top/bottom/left/right; align: start/end, omitted = center).
+ * @param {{top:number,left:number,width:number,height:number}} refRect viewport rect of the reference
+ * @param {{width:number,height:number}} popupSize the popup's measured size
+ * @param {{width:number,height:number}} viewport innerWidth/innerHeight
+ * @param {object} [opts]
+ * @param {string} [opts.placement] default 'bottom-start'
+ * @param {number} [opts.offset] gap between reference and popup along the main axis (default 8)
+ * @param {number} [opts.padding] minimum gap kept from the viewport edges (default 8)
+ * @returns {{left:number, top:number, placement:string}} resolved viewport coords + the side actually used
+ */
+export function computePopupPosition(refRect, popupSize, viewport, opts = {}) {
+  const placement = opts.placement ?? 'bottom-start';
+  const offset = opts.offset ?? 8;
+  const padding = opts.padding ?? 8;
+  const [side, align] = placement.split('-');
+  const vertical = side === 'top' || side === 'bottom';
+
+  // Main-axis position for a given side (top/left coordinate that places the popup on that side).
+  const mainPos = (s) => {
+    if (s === 'bottom') {
+      return refRect.top + refRect.height + offset;
+    }
+    if (s === 'top') {
+      return refRect.top - popupSize.height - offset;
+    }
+    if (s === 'right') {
+      return refRect.left + refRect.width + offset;
+    }
+    return refRect.left - popupSize.width - offset; // left
+  };
+
+  // Available space (for the popup) on a side, after keeping `padding` from the viewport edge.
+  const spaceFor = (s) => {
+    if (s === 'bottom') {
+      return viewport.height - padding - (refRect.top + refRect.height + offset);
+    }
+    if (s === 'top') {
+      return refRect.top - offset - padding;
+    }
+    if (s === 'right') {
+      return viewport.width - padding - (refRect.left + refRect.width + offset);
+    }
+    return refRect.left - offset - padding; // left
+  };
+
+  // Flip (main axis): if the preferred side can't fit the popup, use whichever side has more room.
+  const opposite = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' }[side];
+  const need = vertical ? popupSize.height : popupSize.width;
+  const chosen = spaceFor(side) >= need || spaceFor(side) >= spaceFor(opposite) ? side : opposite;
+
+  // Cross-axis position from the alignment.
+  const crossPos = (extentRef, extentPopup, start) => {
+    if (align === 'start') {
+      return start;
+    }
+    if (align === 'end') {
+      return start + extentRef - extentPopup;
+    }
+    return start + extentRef / 2 - extentPopup / 2;
+  };
+
+  let left;
+  let top;
+  if (vertical) {
+    top = mainPos(chosen);
+    left = crossPos(refRect.width, popupSize.width, refRect.left);
+    // Shift along x to keep the popup within the viewport.
+    left = clamp(left, padding, viewport.width - popupSize.width - padding);
+  } else {
+    left = mainPos(chosen);
+    top = crossPos(refRect.height, popupSize.height, refRect.top);
+    // Shift along y to keep the popup within the viewport.
+    top = clamp(top, padding, viewport.height - popupSize.height - padding);
+  }
+
+  return { left, top, placement: align ? `${chosen}-${align}` : chosen };
+}

package/src/index.js

@@ -20,8 +20,8 @@ import { createToggleController } from './toggle.js';
  *   Return a Node to display it; if nothing is returned, fall back to safe text display (the title is always record.title).
  *   ⚠️ The return value is inserted as-is without sanitization. If it contains untrusted data, neutralize it on the caller side (XSS prevention)
  * @param {string} [options.markerLabel] - character shown on the marker (default '?')
- * @param {import('@floating-ui/dom').Placement} [options.markerPlacement] - corner to overlap the marker onto (default 'top-end')
- * @param {import('@floating-ui/dom').Placement} [options.popupPlacement] - initial popup placement (default 'bottom-start')
+ * @param {import('./types.js').Placement} [options.markerPlacement] - corner to overlap the marker onto (default 'top-end')
+ * @param {import('./types.js').Placement} [options.popupPlacement] - initial popup placement (default 'bottom-start')
  * @param {string} [options.nonce] - nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
  * @returns {{
  *   enable(): void,