@marianmeres/stuic 3.69.0 → 3.70.0

package/API.md

@@ -1398,6 +1398,7 @@ Spotlight/coach mark overlay that highlights a target element by dimming everyth
 | `scrollIntoView`       | `boolean`           | `true`      | Scroll target into view before showing                           |
 | `open`                 | `boolean`           | `undefined` | Reactive programmatic control                                    |
 | `id`                   | `string`            | `undefined` | ID for registry-based control                                    |
+| `autoTrack`            | `boolean`           | `true`      | Per-frame rAF compare-loop that keeps the spotlight glued to its target through layout shifts caused by sibling/ancestor movement (not just resize/scroll). Set to `false` to opt out. |
 | `onShow`               | `() => void`        | `undefined` | Callback when spotlight opens                                    |
 | `onHide`               | `() => void`        | `undefined` | Callback when spotlight hides                                    |
 
@@ -1405,6 +1406,7 @@ Spotlight/coach mark overlay that highlights a target element by dimming everyth
 
 - `showSpotlight(id)` — Show a spotlight by ID
 - `hideSpotlight(id)` — Hide a spotlight by ID
+- `repositionSpotlight(id)` — Force re-measure and reposition the spotlight (use after layout shifts `autoTrack` can't observe, or when `autoTrack: false`)
 - `isSpotlightOpen(id)` — Check if a spotlight is open
 
 ```svelte
@@ -1468,7 +1470,9 @@ Multi-step onboarding tour built on the spotlight primitive. Define steps centra
 | `onSkip`          | `() => void`                  | —         | Called when tour is skipped                          |
 | `onStepChange`    | `(step, index) => void`       | —         | Called on every step change                          |
 
-**Returns:** `{ start(), stop(), next(), prev(), skip(), reset(), active, currentStep, currentIndex }`
+**Returns:** `{ start(), stop(), next(), prev(), skip(), reset(), reposition(), active, currentStep, currentIndex }`
+
+`reposition()` forces the active step's spotlight to re-measure its target and re-apply the cutout/anchor. Useful after a layout shift the spotlight's auto-tracking can't observe (or when a step opted out of it).
 
 **`TourStepDef`:**
 

package/dist/actions/onboarding/onboarding.svelte.d.ts

@@ -151,11 +151,13 @@ export declare function createTour(options: TourOptions): {
     prev: () => void;
     skip: () => Promise<void>;
     reset: () => void;
+    reposition: () => void;
     _register: (id: string, el: HTMLElement) => void;
     _unregister: (id: string) => void;
     _registerAction: (id: string) => void;
     _isCurrentStep: (id: string) => boolean;
     _getShellContent: (id: string) => THC;
+    _getSpotlightId: (stepId: string) => string;
 };
 export type TourInstance = ReturnType<typeof createTour>;
 /**

package/dist/actions/onboarding/onboarding.svelte.js

@@ -1,4 +1,4 @@
-import { spotlight } from "../spotlight/spotlight.svelte.js";
+import { spotlight, repositionSpotlight } from "../spotlight/spotlight.svelte.js";
 import OnboardingShell, {} from "./OnboardingShell.svelte";
 import { StorageAbstraction } from "../../utils/storage-abstraction.js";
 /**
@@ -30,6 +30,10 @@ export function createTour(options) {
     let currentIndex = $state(-1);
     const active = $derived(currentIndex >= 0);
     const currentStep = $derived(options.steps[currentIndex] ?? null);
+    // Unique prefix so each tour instance's spotlights are individually
+    // addressable via the spotlight registry (e.g. for `tour.reposition()`).
+    const tourId = Math.random().toString(36).slice(2);
+    const _getSpotlightId = (stepId) => `__stuic-tour-${tourId}-${stepId}`;
     // Optional persistence store
     const store = options.storageKey
         ? new StorageAbstraction(options.storage ?? "local")
@@ -79,6 +83,7 @@ export function createTour(options) {
         // spotlight() creates inner $effects; Svelte cleans them up
         // when this outer effect re-runs (step change) or is destroyed (tour end)
         spotlight(el, () => ({
+            id: _getSpotlightId(step.id),
             open: true,
             content: _getShellContent(step.id),
             position: step.position ?? "bottom",
@@ -246,6 +251,17 @@ export function createTour(options) {
     function reset() {
         store?.remove(options.storageKey);
     }
+    /**
+     * Force the current step's spotlight to re-measure its target and
+     * reposition. Useful after layout shifts that the spotlight's own
+     * auto-tracking can't observe, or when auto-tracking is disabled.
+     */
+    function reposition() {
+        const step = currentStep;
+        if (!step)
+            return;
+        repositionSpotlight(_getSpotlightId(step.id));
+    }
     return {
         get active() {
             return active;
@@ -264,12 +280,14 @@ export function createTour(options) {
         prev,
         skip,
         reset,
+        reposition,
         // Internal — used by tourStep action
         _register,
         _unregister,
         _registerAction,
         _isCurrentStep,
         _getShellContent,
+        _getSpotlightId,
     };
 }
 /**
@@ -289,12 +307,14 @@ export function tourStep(el, args) {
         return;
     tour._registerAction(id);
     tour._register(id, el);
+    const spotlightId = tour._getSpotlightId(id);
     spotlight(el, () => {
         const isActive = tour._isCurrentStep(id);
         if (!isActive) {
-            return { open: false };
+            return { id: spotlightId, open: false };
         }
         return {
+            id: spotlightId,
             open: true,
             content: tour._getShellContent(id),
             position: tour.currentStep?.position ?? "bottom",

package/dist/actions/spotlight/spotlight.svelte.d.ts

@@ -1,4 +1,12 @@
 import type { THC } from "../../components/Thc/Thc.svelte";
+/**
+ * Imperative handle for a registered spotlight.
+ */
+export interface SpotlightControl {
+    show: () => void;
+    hide: () => void;
+    reposition: () => void;
+}
 /**
  * Show a spotlight by its registered ID.
  *
@@ -16,6 +24,20 @@ export declare function showSpotlight(id: string): void;
  * @param id - The spotlight ID to hide
  */
 export declare function hideSpotlight(id: string): void;
+/**
+ * Force a registered spotlight to re-measure its target and reposition the
+ * clip-path hole, anchor, and annotation. Useful after layout shifts that
+ * auto-tracking cannot observe (or when `autoTrack` is disabled).
+ *
+ * @param id - The spotlight ID to reposition
+ *
+ * @example
+ * ```ts
+ * // after toggling a collapsible sibling
+ * requestAnimationFrame(() => repositionSpotlight('onboarding-step-1'));
+ * ```
+ */
+export declare function repositionSpotlight(id: string): void;
 /**
  * Check if a spotlight is currently open by its registered ID.
  *
@@ -61,6 +83,19 @@ export interface SpotlightOptions {
     open?: boolean;
     /** Unique ID for registry-based programmatic control */
     id?: string;
+    /**
+     * Keep the spotlight glued to its target by running a per-frame
+     * `requestAnimationFrame` compare-loop while visible. Catches layout
+     * shifts that `ResizeObserver` + window resize/scroll miss — e.g. a
+     * sibling collapsing in a flex/grid row and pushing the target sideways.
+     *
+     * The loop reads `getBoundingClientRect()` once per frame and only calls
+     * the internal reposition when the rect actually changed, so cost while
+     * idle is negligible. Set to `false` to keep the old behavior.
+     *
+     * Default: `true`.
+     */
+    autoTrack?: boolean;
     /** Debug mode */
     debug?: boolean;
 }

package/dist/actions/spotlight/spotlight.svelte.js

@@ -30,6 +30,22 @@ export function showSpotlight(id) {
 export function hideSpotlight(id) {
     spotlightRegistry.get(id)?.hide();
 }
+/**
+ * Force a registered spotlight to re-measure its target and reposition the
+ * clip-path hole, anchor, and annotation. Useful after layout shifts that
+ * auto-tracking cannot observe (or when `autoTrack` is disabled).
+ *
+ * @param id - The spotlight ID to reposition
+ *
+ * @example
+ * ```ts
+ * // after toggling a collapsible sibling
+ * requestAnimationFrame(() => repositionSpotlight('onboarding-step-1'));
+ * ```
+ */
+export function repositionSpotlight(id) {
+    spotlightRegistry.get(id)?.reposition();
+}
 /**
  * Check if a spotlight is currently open by its registered ID.
  *
@@ -171,6 +187,8 @@ export function spotlight(targetEl, fn) {
     let do_debug = false;
     let prevOpen = undefined;
     let resizeObserver = null;
+    let rafId = null;
+    let lastRect = null;
     // Unique identifiers
     const rnd = Math.random().toString(36).slice(2);
     const anchorName = `--anchor-spotlight-${rnd}`;
@@ -217,6 +235,42 @@ export function spotlight(targetEl, fn) {
             positionAnnotationFallback(rect, padding);
         }
     }
+    /**
+     * Per-frame loop that re-measures the target and reposition the hole/anchor
+     * if the rect diverges from the last-seen rect. This catches movement that
+     * `ResizeObserver` (size only) and window resize/scroll (viewport only) miss
+     * — e.g. a sibling element collapsing in a flex/grid row and pushing the
+     * target sideways.
+     */
+    function trackFrame() {
+        if (!isVisible) {
+            rafId = null;
+            return;
+        }
+        const r = targetEl.getBoundingClientRect();
+        if (!lastRect ||
+            r.left !== lastRect.left ||
+            r.top !== lastRect.top ||
+            r.width !== lastRect.width ||
+            r.height !== lastRect.height) {
+            lastRect = r;
+            updateHolePosition();
+        }
+        rafId = requestAnimationFrame(trackFrame);
+    }
+    function startAutoTrack() {
+        if (rafId != null)
+            return;
+        lastRect = targetEl.getBoundingClientRect();
+        rafId = requestAnimationFrame(trackFrame);
+    }
+    function stopAutoTrack() {
+        if (rafId != null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+        lastRect = null;
+    }
     /**
      * Position annotation without CSS Anchor Positioning (fallback).
      */
@@ -375,6 +429,11 @@ export function spotlight(targetEl, fn) {
             resizeObserver.observe(targetEl);
             window.addEventListener("resize", updateHolePosition);
             window.addEventListener("scroll", updateHolePosition, true);
+            // 8. Per-frame compare-loop to catch layout shifts (sibling collapses,
+            //    animated ancestors, etc.) that the observers above don't see.
+            if (currentOptions.autoTrack !== false) {
+                startAutoTrack();
+            }
         });
     }
     function hide() {
@@ -391,6 +450,7 @@ export function spotlight(targetEl, fn) {
         window.removeEventListener("scroll", updateHolePosition, true);
         resizeObserver?.disconnect();
         resizeObserver = null;
+        stopAutoTrack();
         // Unlock body scroll
         BodyScroll.unlock();
         // Transition out
@@ -428,6 +488,7 @@ export function spotlight(targetEl, fn) {
             closeOnEscape: opts.closeOnEscape ?? true,
             closeOnBackdropClick: opts.closeOnBackdropClick ?? true,
             scrollIntoView: opts.scrollIntoView ?? true,
+            autoTrack: opts.autoTrack ?? true,
             onShow: opts.onShow,
             onHide: opts.onHide,
             debug: opts.debug,
@@ -436,7 +497,11 @@ export function spotlight(targetEl, fn) {
         do_debug = !!opts.debug;
         // Register in global registry if id provided
         if (opts.id) {
-            spotlightRegistry.set(opts.id, { show, hide });
+            spotlightRegistry.set(opts.id, {
+                show,
+                hide,
+                reposition: updateHolePosition,
+            });
         }
         // Update if visible
         if (isVisible) {
@@ -478,6 +543,7 @@ export function spotlight(targetEl, fn) {
             backdropEl?.remove();
             annotationEl?.remove();
             resizeObserver?.disconnect();
+            stopAutoTrack();
             document.removeEventListener("keydown", onEscape);
             window.removeEventListener("resize", updateHolePosition);
             window.removeEventListener("scroll", updateHolePosition, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "3.69.0",
+  "version": "3.70.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",