@glowhop/core-tour 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @glowhop/core-tour
 
+## 1.0.2
+
+### Patch Changes
+
+- 5aa8cdf: Fix two mobile overlay defects.
+  
+  The backdrop no longer stops short of the bottom of the screen. Its `viewBox` is
+  now measured from the element's own box instead of `documentElement.clientHeight`,
+  which a retracting mobile URL bar moves out of step with the box a fixed element
+  is sized against; `preserveAspectRatio="xMinYMin slice"` makes any residual mismatch
+  overdraw rather than letterbox, and the element is sized to `100lvh` where that
+  unit exists so it always spans the visible area.
+  
+  The cutout now animates on WebKit. Safari — and therefore every browser on iOS —
+  cannot animate `d` through the Web Animations API, so the rectangle is
+  interpolated frame by frame and the path regenerated from it, clocked by the
+  eased progress of the animation already running on the same element, instead of
+  snapping to each target.
+
+## 1.0.1
+
+### Patch Changes
+
+- 358c4b1: Draw the overlay backdrop on WebKit. The cutout geometry was only written to the CSS `d` property, which Safari does not implement — so on macOS Safari and on every iOS browser (Chrome and Firefox included, both WebKit) the backdrop never drew and tours ran with a popover but no dimming. The `d` attribute is now the source of truth, with the CSS property mirrored where it exists so the cutout still morphs between steps.
+  
+  Measure the viewport as the layout viewport (`documentElement.clientWidth/clientHeight`) instead of `innerWidth`/`innerHeight`. The latter reports the visual viewport, which shrinks with a mobile URL bar and includes a classic desktop scrollbar; the resulting mismatch with the overlay's own `100%`-sized box scaled and centred the backdrop, leaving undimmed bands and a cutout offset from its target. The same measurement backs popover clamping and the pointer's in-viewport checks.
+
 ## 1.0.0
 
 ### Major Changes

package/adapter.js

@@ -15,7 +15,8 @@ var OVERLAY_IDLE_STYLE = {
 var OVERLAY_IDLE_ATTRIBUTES = {
   "aria-hidden": "true",
   "data-glow-tour-allow-interaction": "false",
-  inert: "true"
+  inert: "true",
+  preserveAspectRatio: "xMinYMin slice"
 };
 var OVERLAY_PATH_IDLE_ATTRIBUTES = {
   cursor: "auto",

package/elements/idle-presentation.d.ts

@@ -17,11 +17,22 @@
 export type CssStyleRecord = Readonly<Record<string, string>>;
 /** Idle inline style for the overlay `<svg>` element. */
 export declare const OVERLAY_IDLE_STYLE: CssStyleRecord;
-/** Idle attributes for the overlay `<svg>` element. */
+/**
+ * Idle attributes for the overlay `<svg>` element.
+ *
+ * `preserveAspectRatio` is the load-bearing one: the default (`xMidYMid meet`)
+ * letterboxes the backdrop the moment the `viewBox` and the element's own box
+ * disagree, which is exactly what a mobile URL bar causes as it retracts —
+ * undimmed bands above and below the overlay. `slice` overdraws instead, so a
+ * `viewBox` that is momentarily stale costs a few scaled pixels rather than a
+ * hole in the backdrop, and `xMinYMin` anchors that overdraw at the origin the
+ * cutout coordinates are measured from.
+ */
 export declare const OVERLAY_IDLE_ATTRIBUTES: {
     readonly "aria-hidden": "true";
     readonly "data-glow-tour-allow-interaction": "false";
     readonly inert: "true";
+    readonly preserveAspectRatio: "xMinYMin slice";
 };
 /**
  * Idle attributes for the overlay's cutout `<path>`. Genuinely load-bearing,

package/elements/overlay.d.ts

@@ -1,16 +1,66 @@
 import GlowTourElement, { type TourElementStep } from "./base";
 export default class OverlayElement extends GlowTourElement {
     private currentTransition;
+    private geometryTween;
+    /** Where the cutout is now — the tween's starting point on the next move. */
+    private cutout;
     private visualState;
+    private cssPathDSupported;
     setInteractionAllowed(allowed: boolean): void;
     moveToTarget(nextPosition: DOMRect, step: TourElementStep): Promise<void>;
     animateTo(position: DOMRect, step: TourElementStep): Promise<void>;
     _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
+    /** The backdrop with a hole punched around `position`, as a CSS `d` value. */
+    private _cutoutPath;
     initializeProps(): void;
     private _getPathElement;
     protected _release(): void;
     updatePosition(nextPosition: DOMRect, step: TourElementStep, animateChanges?: boolean, onTransition?: (transition: Promise<void>) => void): void;
+    /**
+     * Pins the `viewBox` to the element's own box, so one SVG unit is one CSS
+     * pixel and the cutout lands where `getBoundingClientRect()` said it should.
+     */
+    private syncViewBox;
     cancelAnimations(): void;
+    /**
+     * Starts an animation whose keyframes carry the cutout geometry.
+     *
+     * WebKit ignores `d` both as a CSS property and as an animatable value, so
+     * there the geometry is stripped from the keyframes — the engine animates
+     * fill and opacity — and {@link _startGeometryTween} moves the shape instead.
+     * When it cannot, the target shape is committed up front, which is the old
+     * snap-and-be-correct behaviour.
+     */
+    private _startPathAnimation;
+    /**
+     * Morphs the cutout by hand, one frame at a time, the way driver.js moves its
+     * stage: the rectangle is interpolated and the path regenerated from it.
+     *
+     * The clock is the animation that is already running on the same element, so
+     * the shape, the backdrop and anything else the engine is easing stay in step
+     * without this having to re-implement a timing function. Its progress reads
+     * `null` once it is over, which is the tween's cue to land and stop.
+     *
+     * @returns Whether the tween took ownership of the geometry. `false` leaves
+     *   the caller to commit the final shape.
+     */
+    private _startGeometryTween;
+    /** Drops the running cutout tween, leaving the shape wherever it got to. */
+    private _stopGeometryTween;
+    /**
+     * Whether this document implements the CSS `d` property. Safari/WebKit — and
+     * therefore every browser on iOS, Chrome included — does not: an inline
+     * `d: path(...)` is dropped on the floor and the backdrop never draws.
+     */
+    private supportsCssPathD;
+    /**
+     * Writes the cutout geometry. The `d` attribute is the source of truth since
+     * every engine honours it; the CSS property is mirrored where it exists,
+     * because that is what makes the shape animatable and what wins the cascade.
+     */
+    private writePathD;
+    /** The current geometry, as the `path("...")` CSS value the keyframes use. */
+    private readPathD;
     private applyStyles;
     private commitAndCancelCurrentTransition;
     private getCurrentRenderedStyles;

package/index.js

@@ -424,12 +424,24 @@ function isNode(value, context) {
   return typeof Node === "function" && value instanceof Node;
 }
 function viewportDimensions(context) {
+  const root = ownerDocument(context)?.documentElement;
+  const width = root?.clientWidth;
+  const height = root?.clientHeight;
+  if (typeof width === "number" && width > 0 && typeof height === "number" && height > 0) {
+    return { width, height };
+  }
   const currentWindow = ownerWindow(context);
   return {
     width: currentWindow?.innerWidth ?? 1024,
     height: currentWindow?.innerHeight ?? 768
   };
 }
+function paintedBoxDimensions(element) {
+  const rect = element?.getBoundingClientRect?.();
+  if (rect && rect.width > 0 && rect.height > 0)
+    return { height: rect.height, width: rect.width };
+  return viewportDimensions(element);
+}
 function isInViewport(rect, context) {
   const viewport = viewportDimensions(context);
   return rect.left >= 0 && rect.top >= 0 && rect.right <= viewport.width && rect.bottom <= viewport.height;
@@ -600,7 +612,8 @@ var OVERLAY_IDLE_STYLE = {
 var OVERLAY_IDLE_ATTRIBUTES = {
   "aria-hidden": "true",
   "data-glow-tour-allow-interaction": "false",
-  inert: "true"
+  inert: "true",
+  preserveAspectRatio: "xMinYMin slice"
 };
 var POINTER_IDLE_STYLE = {
   left: "0px",
@@ -634,7 +647,10 @@ var DEFAULT_OVERLAY_RADIUS = 8;
 
 class OverlayElement extends GlowTourElement {
   currentTransition = null;
+  geometryTween = null;
+  cutout = null;
   visualState = null;
+  cssPathDSupported = null;
   setInteractionAllowed(allowed) {
     this.element.style.setProperty("pointer-events", allowed ? "none" : "auto");
     this.element.setAttribute("data-glow-tour-allow-interaction", String(allowed));
@@ -648,12 +664,11 @@ class OverlayElement extends GlowTourElement {
     }
     const keyframe = this.getRenderedTargetStyles(path, this._getNextStyles(nextPosition, step));
     this.visualState = nextVisualState;
-    if (!path.style.getPropertyValue("d")) {
-      for (const [property, value] of Object.entries(keyframe)) {
-        if (property !== "opacity" && value != null) {
-          path.style.setProperty(property, String(value));
-        }
-      }
+    const previousCutout = this.cutout;
+    this.cutout = nextPosition;
+    if (!this.readPathD(path)) {
+      const { opacity: _initialOpacity, ...geometry } = keyframe;
+      this.applyStyles(path, geometry);
       const opacity = keyframe.opacity == null ? "0.7" : String(keyframe.opacity);
       path.style.setProperty("opacity", "0");
       const animation2 = this._startAnimation([{ opacity: "0" }, { opacity }], {
@@ -665,14 +680,14 @@ class OverlayElement extends GlowTourElement {
       return;
     }
     const baseStyle = {
-      d: path.style.getPropertyValue("d") ?? "",
+      d: this.readPathD(path),
       fill: path.style.getPropertyValue("fill") ?? "",
       opacity: path.style.getPropertyValue("opacity") ?? "0"
     };
-    const animation = this._startAnimation([baseStyle, keyframe], {
+    const animation = this._startPathAnimation([baseStyle, keyframe], {
       ...this._getAnimationOptions(),
       fill: "none"
-    }, path);
+    }, path, previousCutout, nextPosition, step);
     if (!animation || await this._waitForAnimation(animation))
       this.applyStyles(path, keyframe);
   }
@@ -681,12 +696,14 @@ class OverlayElement extends GlowTourElement {
     if (!path)
       return;
     this.commitAndCancelCurrentTransition(path);
+    const previousCutout = this.cutout;
+    this.cutout = position;
     const from = this.getCurrentRenderedStyles(path);
     const finalStyles = this.getRenderedTargetStyles(path, this._getNextStyles(position, step));
-    const animation = this._startAnimation([from, finalStyles], {
+    const animation = this._startPathAnimation([from, finalStyles], {
       ...this._getAnimationOptions(),
       fill: "none"
-    }, path);
+    }, path, previousCutout, position, step);
     if (!animation) {
       this.applyStyles(path, finalStyles);
       return;
@@ -703,39 +720,43 @@ class OverlayElement extends GlowTourElement {
     }
   }
   _getNextStyles(position, step) {
-    const { padding, radius, color, opacity } = step.overlay || {};
-    const path = roundedRectPath(position, viewportDimensions(this.element), {
-      padding: padding ?? DEFAULT_OVERLAY_PADDING,
-      radius: radius ?? DEFAULT_OVERLAY_RADIUS
-    }, this.element);
     return {
-      d: `path("${path}")`,
-      fill: color,
-      opacity: opacity != null ? String(opacity) : 0.7
+      d: this._cutoutPath(position, step),
+      fill: step.overlay?.color,
+      opacity: step.overlay?.opacity != null ? String(step.overlay.opacity) : 0.7
     };
   }
+  _cutoutPath(position, step) {
+    return `path("${roundedRectPath(position, paintedBoxDimensions(this.element), {
+      padding: step.overlay?.padding ?? DEFAULT_OVERLAY_PADDING,
+      radius: step.overlay?.radius ?? DEFAULT_OVERLAY_RADIUS
+    }, this.element)}")`;
+  }
   initializeProps() {
     const el = this.getElement();
     if (!el) {
       return;
     }
-    const viewport = viewportDimensions(el);
     for (const [property, value] of Object.entries(OVERLAY_IDLE_STYLE)) {
       el.style.setProperty(property, value);
     }
     for (const [name, value] of Object.entries(OVERLAY_IDLE_ATTRIBUTES)) {
       el.setAttribute(name, value);
     }
-    el.setAttribute("viewBox", `0 0 ${viewport.width} ${viewport.height}`);
+    el.style.setProperty("height", "100lvh");
+    this.syncViewBox();
   }
   _getPathElement() {
     return this.element.querySelector("path");
   }
   _release() {
     this.currentTransition = null;
+    this._stopGeometryTween();
     this.visualState = null;
+    this.cutout = null;
     const path = this._getPathElement();
-    path?.style.removeProperty("d");
+    if (path)
+      this.writePathD(path, null);
     path?.style.removeProperty("fill");
     path?.style.setProperty("opacity", "0");
     this.element.style.setProperty("pointer-events", "none");
@@ -753,10 +774,15 @@ class OverlayElement extends GlowTourElement {
         onTransition(transition);
       else
         transition.catch(() => {});
-    } else
+    } else {
       this.applyStyles(path, this.getRenderedTargetStyles(path, this._getNextStyles(nextPosition, step)));
+      this.cutout = nextPosition;
+    }
     this.visualState = nextVisualState;
-    const viewport = viewportDimensions(this.element);
+    this.syncViewBox();
+  }
+  syncViewBox() {
+    const viewport = paintedBoxDimensions(this.element);
     const viewBox = `0 0 ${viewport.width} ${viewport.height}`;
     if (this.element.getAttribute("viewBox") !== viewBox) {
       this.element.setAttribute("viewBox", viewBox);
@@ -764,11 +790,80 @@ class OverlayElement extends GlowTourElement {
   }
   cancelAnimations() {
     this.currentTransition = null;
+    this._stopGeometryTween();
     super.cancelAnimations();
   }
+  _startPathAnimation(keyframes, options, path, from, position, step) {
+    this._stopGeometryTween();
+    if (this.supportsCssPathD())
+      return this._startAnimation(keyframes, options, path);
+    const animation = this._startAnimation(keyframes.map(({ d: _geometry, ...rest }) => rest), options, path);
+    const geometry = keyframes[keyframes.length - 1]?.d;
+    if (geometry != null && !(animation && from && this._startGeometryTween(path, from, position, step, animation)))
+      this.writePathD(path, String(geometry));
+    return animation;
+  }
+  _startGeometryTween(path, from, to, step, animation) {
+    const request = ownerWindow(this.element)?.requestAnimationFrame;
+    const effect = animation.effect;
+    if (typeof request !== "function" || typeof effect?.getComputedTiming !== "function")
+      return false;
+    const tween = {};
+    const draw = () => {
+      if (this.geometryTween !== tween)
+        return;
+      const progress = effect.getComputedTiming().progress;
+      const done = typeof progress !== "number";
+      this.cutout = betweenRects(from, to, done ? 1 : progress);
+      this.writePathD(path, this._cutoutPath(this.cutout, step));
+      if (done)
+        this.geometryTween = null;
+      else
+        request(draw);
+    };
+    this.geometryTween = tween;
+    request(draw);
+    return true;
+  }
+  _stopGeometryTween() {
+    this.geometryTween = null;
+  }
+  supportsCssPathD() {
+    if (this.cssPathDSupported === null) {
+      const currentWindow = ownerWindow(this.element);
+      try {
+        this.cssPathDSupported = currentWindow?.CSS?.supports?.("d", 'path("M0 0")') === true;
+      } catch {
+        this.cssPathDSupported = false;
+      }
+    }
+    return this.cssPathDSupported;
+  }
+  writePathD(path, value) {
+    if (value == null || value === "") {
+      path.style.removeProperty("d");
+      path.removeAttribute("d");
+      return;
+    }
+    path.style.setProperty("d", value);
+    path.setAttribute("d", pathDataFromCssValue(value));
+  }
+  readPathD(path) {
+    const inline = path.style.getPropertyValue("d");
+    if (inline)
+      return inline;
+    const attribute = path.getAttribute("d");
+    return attribute ? `path("${attribute}")` : "";
+  }
   applyStyles(path, styles) {
     for (const [property, value] of Object.entries(styles)) {
-      if (value == null) {
+      if (property === "d") {
+        const next = value == null ? null : String(value);
+        if (this.readPathD(path) !== (next ?? "")) {
+          this._stopGeometryTween();
+          this.writePathD(path, next);
+        }
+      } else if (value == null) {
         if (path.style.getPropertyValue(property))
           path.style.removeProperty(property);
       } else if (path.style.getPropertyValue(property) !== String(value)) {
@@ -780,6 +875,7 @@ class OverlayElement extends GlowTourElement {
     const animation = this.currentTransition;
     if (!animation)
       return;
+    this._stopGeometryTween();
     this.applyStyles(path, this.getCurrentRenderedStyles(path));
     this.currentTransition = null;
     this._cancelAnimation(animation);
@@ -787,7 +883,7 @@ class OverlayElement extends GlowTourElement {
   getCurrentRenderedStyles(path) {
     const computed = computedStyle(path);
     return {
-      d: computed?.getPropertyValue("d") || path.style.getPropertyValue("d"),
+      d: computed?.getPropertyValue("d") || this.readPathD(path),
       fill: computed?.getPropertyValue("fill") || path.style.getPropertyValue("fill"),
       opacity: computed?.getPropertyValue("opacity") || path.style.getPropertyValue("opacity")
     };
@@ -822,6 +918,7 @@ class OverlayElement extends GlowTourElement {
       return Promise.resolve();
     }
     const finalStyles = this.getRenderedTargetStyles(path, this._getNextStyles(position, step));
+    this.cutout = position;
     const opacity = String(finalStyles.opacity ?? "0.7");
     this.applyStyles(path, { ...finalStyles, opacity: "0" });
     const animation = this._startAnimation([{ opacity: "0" }, { opacity }], {
@@ -836,17 +933,30 @@ class OverlayElement extends GlowTourElement {
     if (!path) {
       return Promise.resolve();
     }
+    this._stopGeometryTween();
     const animation = this._startAnimation({
       opacity: "0"
     }, { ...this._getAnimationOptions(), fill: "none" }, path);
     if (animation && !await this._waitForAnimation(animation))
       return;
-    path.style.removeProperty("d");
+    this.writePathD(path, null);
+    this.cutout = null;
     path.style.removeProperty("fill");
     path.style.setProperty("opacity", "0");
     this.element.style.setProperty("pointer-events", "none");
   }
 }
+function betweenRects(from, to, progress) {
+  return {
+    height: from.height + (to.height - from.height) * progress,
+    left: from.left + (to.left - from.left) * progress,
+    top: from.top + (to.top - from.top) * progress,
+    width: from.width + (to.width - from.width) * progress
+  };
+}
+function pathDataFromCssValue(value) {
+  return value.replace(/^path\(\s*(["'])([\s\S]*)\1\s*\)$/, "$2");
+}
 function computedStyle(element) {
   const document2 = element.ownerDocument;
   const currentWindow = document2 && "defaultView" in document2 ? document2.defaultView : ownerWindow(element);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glowhop/core-tour",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Framework-agnostic tour controller and DOM runtime for GlowTour.js.",
   "license": "MIT",
   "homepage": "https://github.com/Glowhop/GlowTour.js#readme",

package/utils/utils.d.ts

@@ -4,10 +4,41 @@ export declare function ownerDocument(element?: Node | null): Document | null;
 export declare function isHTMLElement(value: unknown, context?: Node | null): value is HTMLElement;
 export declare function isElement(value: unknown, context?: Node | null): value is Element;
 export declare function isNode(value: unknown, context?: Node | null): value is Node;
+/**
+ * The layout viewport, in CSS pixels — the box every `position: fixed` tour
+ * element is sized and positioned against, and the frame that
+ * `getBoundingClientRect()` reports coordinates in.
+ *
+ * Deliberately not `innerWidth`/`innerHeight`: those measure the *visual*
+ * viewport, which on mobile shrinks and grows with the browser's URL bar and on
+ * desktop includes the classic scrollbar. Either gap skews the overlay's
+ * `viewBox` against its own `100%`-sized box, and the default
+ * `preserveAspectRatio` then scales and centres the backdrop — leaving undimmed
+ * bands and a cutout that no longer lines up with its target.
+ */
 export declare function viewportDimensions(context?: Node | null): {
     width: number;
     height: number;
 };
+/**
+ * The box the overlay `<svg>` is actually painted into, in CSS pixels.
+ *
+ * The overlay is `position: fixed` and sized to `100%`, and its `viewBox` has
+ * to match that box exactly. Any mismatch makes the SVG scale its contents, and
+ * `preserveAspectRatio` then either letterboxes the backdrop — the undimmed
+ * bands mobile browsers show once a retracting URL bar moves the layout
+ * viewport out of step with the initial containing block, which is what sizes
+ * the element — or slices the cutout away from its target.
+ *
+ * Measuring the element sidesteps the question of which of the two each engine
+ * resizes: whatever box it gave the overlay is the box the overlay draws in.
+ * {@link viewportDimensions} stays the fallback for an element that has no box
+ * yet — detached nodes, server-rendered markup, test doubles.
+ */
+export declare function paintedBoxDimensions(element?: Element | null): {
+    width: number;
+    height: number;
+};
 export declare function isInViewport(rect: {
     left: number;
     top: number;
@@ -15,7 +46,9 @@ export declare function isInViewport(rect: {
     bottom: number;
 }, context?: Node | null): boolean;
 export declare function roundByDPR(value: number, context?: Node | null): number;
-export declare function roundedRectPath(rect: DOMRect, viewport: {
+/** The only part of a `DOMRect` the cutout geometry reads. */
+export type RectGeometry = Pick<DOMRect, "height" | "left" | "top" | "width">;
+export declare function roundedRectPath(rect: RectGeometry, viewport: {
     width: number;
     height: number;
 }, options: {