@marianmeres/stuic 3.11.0 → 3.12.0

package/AGENTS.md

@@ -24,7 +24,7 @@
 ```
 src/lib/
 ├── components/     # 39 UI components
-├── actions/        # 12 Svelte actions
+├── actions/        # 13 Svelte actions
 ├── utils/          # 42 utility functions
 ├── themes/         # 26 theme definitions (.ts) + generated CSS (css/)
 ├── icons/          # Icon re-exports
@@ -74,7 +74,7 @@ src/lib/
 ### Domain Docs
 - [Components](./docs/domains/components.md) — 38 components, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
-- [Actions](./docs/domains/actions.md) — 12 Svelte directives
+- [Actions](./docs/domains/actions.md) — 13 Svelte directives
 - [Utils](./docs/domains/utils.md) — 42 utility functions
 
 ### Reference

package/API.md

@@ -831,6 +831,66 @@ Anchored popover positioning.
 </button>
 ```
 
+### `spotlight`
+
+Spotlight/coach mark overlay that highlights a target element by dimming everything else behind a backdrop with a cutout hole. Includes built-in annotation support positioned next to the target.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Whether the spotlight is enabled |
+| `content` | `THC \| null` | `undefined` | Annotation content (string, {html}, {component, props}, snippet) |
+| `position` | `SpotlightPosition` | `"bottom"` | Annotation placement relative to target |
+| `padding` | `number` | `8` | Padding around target in the cutout (px) |
+| `borderRadius` | `number` | `8` | Border radius of the cutout hole (px) |
+| `class` | `string` | `undefined` | Custom class for annotation |
+| `classBackdrop` | `string` | `undefined` | Custom class for backdrop |
+| `offset` | `string` | `"0.5rem"` | Annotation offset from target (CSS value) |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
+| `closeOnBackdropClick` | `boolean` | `true` | Close on backdrop click |
+| `scrollIntoView` | `boolean` | `true` | Scroll target into view before showing |
+| `open` | `boolean` | `undefined` | Reactive programmatic control |
+| `id` | `string` | `undefined` | ID for registry-based control |
+| `onShow` | `() => void` | `undefined` | Callback when spotlight opens |
+| `onHide` | `() => void` | `undefined` | Callback when spotlight hides |
+
+**Registry functions:**
+
+- `showSpotlight(id)` — Show a spotlight by ID
+- `hideSpotlight(id)` — Hide a spotlight by ID
+- `isSpotlightOpen(id)` — Check if a spotlight is open
+
+```svelte
+<script>
+  import { spotlight, showSpotlight } from "@marianmeres/stuic";
+</script>
+
+<!-- Attach to target, control via registry -->
+<div
+  use:spotlight={() => ({
+    content: "Check out this feature!",
+    position: "bottom",
+    id: "intro",
+  })}
+>
+  Target
+</div>
+
+<button onclick={() => showSpotlight("intro")}>Show</button>
+
+<!-- Or control via reactive open prop -->
+<div
+  use:spotlight={() => ({
+    content: { html: "<p>Step 1 of 3</p>" },
+    open: tourStep === 1,
+    onHide: () => { tourStep = 0; },
+  })}
+>
+  Tour Target
+</div>
+```
+
 ### `tooltip`
 
 Tooltip display from `aria-label`.
@@ -1298,6 +1358,7 @@ Each component defines customization tokens. Override globally in `:root {}` or
 | Tooltip | `--stuic-tooltip-*` | `bg`, `text` |
 | Popover | `--stuic-popover-*` | `bg`, `text`, `border` |
 | Skeleton | `--stuic-skeleton-*` | `bg`, `bg-highlight`, `duration` |
+| Spotlight | `--stuic-spotlight-*` | `backdrop-bg`, `annotation-bg`, `annotation-text`, `annotation-border` |
 | Cart | `--stuic-cart-*` | `gap`, `item-padding`, `item-radius`, `item-border-color`, `item-bg`, `thumbnail-size`, `quantity-border-color`, `remove-color`, `summary-border-color`, `compact-max-height`, `transition` |
 | Checkout | `--stuic-checkout-*` | `input-border`, `input-bg`, `input-focus-ring`, `input-radius`, `card-border`, `card-bg`, `card-radius`, `step-gap`, `progress-*`, `summary-*`, `guest-*`, `login-*`, `address-*`, `delivery-*`, `review-*`, `confirmation-*` |
 

package/dist/actions/index.d.ts

@@ -6,6 +6,7 @@ export * from "./highlight-dragover.svelte.js";
 export * from "./on-submit-validity-check.svelte.js";
 export * from "./popover/popover.svelte.js";
 export * from "./resizable-width.svelte.js";
+export * from "./spotlight/spotlight.svelte.js";
 export * from "./tooltip/tooltip.svelte.js";
 export * from "./trim.svelte.js";
 export * from "./typeahead.svelte.js";

package/dist/actions/index.js

@@ -6,6 +6,7 @@ export * from "./highlight-dragover.svelte.js";
 export * from "./on-submit-validity-check.svelte.js";
 export * from "./popover/popover.svelte.js";
 export * from "./resizable-width.svelte.js";
+export * from "./spotlight/spotlight.svelte.js";
 export * from "./tooltip/tooltip.svelte.js";
 export * from "./trim.svelte.js";
 export * from "./typeahead.svelte.js";

package/dist/actions/spotlight/SpotlightContent.svelte

@@ -0,0 +1,15 @@
+<script lang="ts" module>
+	import type { THC } from "../../components/Thc/Thc.svelte";
+
+	export interface Props {
+		thc: THC;
+	}
+</script>
+
+<script lang="ts">
+	import Thc from "../../components/Thc/Thc.svelte";
+
+	let { thc }: Props = $props();
+</script>
+
+<Thc {thc} />

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

@@ -0,0 +1,7 @@
+import type { THC } from "../../components/Thc/Thc.svelte";
+export interface Props {
+    thc: THC;
+}
+declare const SpotlightContent: import("svelte").Component<Props, {}, "">;
+type SpotlightContent = ReturnType<typeof SpotlightContent>;
+export default SpotlightContent;

package/dist/actions/spotlight/index.css

@@ -0,0 +1,55 @@
+/* Spotlight action tokens */
+/* Note: style props will not work as with regular components, because spotlight elements are created outside of the anchor DOM tree */
+:root {
+	--stuic-spotlight-backdrop-bg: rgba(0, 0, 0, 0.5);
+	--stuic-spotlight-annotation-bg: var(--stuic-color-surface);
+	--stuic-spotlight-annotation-text: var(--stuic-color-foreground);
+	--stuic-spotlight-annotation-border: var(--stuic-color-border);
+}
+
+/* Backdrop overlay with clip-path hole */
+.stuic-spotlight-backdrop {
+	opacity: 0;
+	transition-property: opacity;
+	&.spot-visible {
+		opacity: 1;
+	}
+}
+
+/* Annotation element (positioned via CSS Anchor Positioning) */
+.stuic-spotlight-annotation {
+	position: fixed;
+	display: none;
+	opacity: 0;
+	transition-property: opacity;
+}
+
+@supports (anchor-name: --anchor) {
+	.stuic-spotlight-annotation {
+		position-try-order: most-width;
+		position-try-fallbacks:
+			flip-block, flip-inline, flip-block flip-inline;
+
+		&.spot-block {
+			display: block;
+			opacity: 0;
+			&.spot-visible {
+				opacity: 1;
+			}
+		}
+	}
+}
+
+/* Fallback annotation (no CSS Anchor Positioning) */
+.stuic-spotlight-annotation-fallback {
+	display: none;
+	opacity: 0;
+	transition-property: opacity;
+	&.spot-block {
+		display: block;
+		opacity: 0;
+		&.spot-visible {
+			opacity: 1;
+		}
+	}
+}

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

@@ -0,0 +1,111 @@
+import type { THC } from "../../components/Thc/Thc.svelte";
+/**
+ * Show a spotlight by its registered ID.
+ *
+ * @param id - The spotlight ID to show
+ *
+ * @example
+ * ```ts
+ * showSpotlight('onboarding-step-1');
+ * ```
+ */
+export declare function showSpotlight(id: string): void;
+/**
+ * Hide a spotlight by its registered ID.
+ *
+ * @param id - The spotlight ID to hide
+ */
+export declare function hideSpotlight(id: string): void;
+/**
+ * Check if a spotlight is currently open by its registered ID.
+ *
+ * @param id - The spotlight ID to check
+ * @returns true if the spotlight is open, false otherwise
+ */
+export declare function isSpotlightOpen(id: string): boolean;
+/**
+ * Valid positions for annotation placement relative to the spotlight target.
+ */
+export type SpotlightPosition = "top" | "top-left" | "top-right" | "top-span-left" | "top-span-right" | "bottom" | "bottom-left" | "bottom-right" | "bottom-span-left" | "bottom-span-right" | "left" | "right";
+/**
+ * Options for the spotlight action.
+ */
+export interface SpotlightOptions {
+    /** Whether the spotlight is enabled */
+    enabled?: boolean;
+    /** Annotation content (THC format: string, {text}, {html}, {component, props}, {snippet}, or Snippet) */
+    content?: THC | null;
+    /** Preferred position of the annotation relative to the target */
+    position?: SpotlightPosition;
+    /** Padding around the target in the cutout (px) */
+    padding?: number;
+    /** Border radius of the cutout hole (px) */
+    borderRadius?: number;
+    /** Custom class for the annotation container */
+    class?: string;
+    /** Custom class for the backdrop overlay */
+    classBackdrop?: string;
+    /** Offset/margin of the annotation from the target (CSS value, e.g., "0.5rem") */
+    offset?: string;
+    /** Close on Escape key */
+    closeOnEscape?: boolean;
+    /** Close on click on the backdrop (outside the target hole) */
+    closeOnBackdropClick?: boolean;
+    /** Scroll target into view before showing */
+    scrollIntoView?: boolean;
+    /** Callback when spotlight opens */
+    onShow?: () => void;
+    /** Callback when spotlight hides */
+    onHide?: () => void;
+    /** Programmatically control open state (reactive) */
+    open?: boolean;
+    /** Unique ID for registry-based programmatic control */
+    id?: string;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * A Svelte action that highlights a target element with a spotlight effect.
+ *
+ * Creates a dimmed backdrop overlay with a cutout hole around the target element,
+ * optionally showing annotation content positioned next to it. Useful for onboarding
+ * tutorials, feature tours, and drawing attention to specific UI elements.
+ *
+ * The cutout uses `clip-path` with an SVG path, so pointer events in the hole area
+ * pass through to the target element naturally.
+ *
+ * @param targetEl - The element to spotlight
+ * @param fn - Function returning spotlight options (reactive)
+ *
+ * @example
+ * ```svelte
+ * <!-- Basic usage with programmatic control -->
+ * <button
+ *   use:spotlight={() => ({
+ *     content: "Click here to get started!",
+ *     position: "bottom",
+ *     id: "intro-step-1",
+ *   })}
+ * >
+ *   Get Started
+ * </button>
+ *
+ * <button onclick={() => showSpotlight('intro-step-1')}>
+ *   Start Tour
+ * </button>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Reactive open control -->
+ * <div use:spotlight={() => ({
+ *   content: { component: TourStep, props: { step: 1 } },
+ *   position: "right",
+ *   open: showTour,
+ *   onHide: () => showTour = false,
+ * })}>
+ *   Target content
+ * </div>
+ * ```
+ */
+export declare function spotlight(targetEl: HTMLElement, fn?: () => SpotlightOptions): void;

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

@@ -0,0 +1,491 @@
+import { mount, unmount } from "svelte";
+import { twMerge } from "../../utils/tw-merge.js";
+import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
+import { BodyScroll } from "../../utils/body-scroll-locker.js";
+import SpotlightContent from "./SpotlightContent.svelte";
+//
+const TRANSITION = 200;
+// Reactive state tracking which spotlights are open by ID
+const spotlightOpenStates = $state({});
+// Registry of spotlights by ID for programmatic control
+const spotlightRegistry = new Map();
+/**
+ * Show a spotlight by its registered ID.
+ *
+ * @param id - The spotlight ID to show
+ *
+ * @example
+ * ```ts
+ * showSpotlight('onboarding-step-1');
+ * ```
+ */
+export function showSpotlight(id) {
+    spotlightRegistry.get(id)?.show();
+}
+/**
+ * Hide a spotlight by its registered ID.
+ *
+ * @param id - The spotlight ID to hide
+ */
+export function hideSpotlight(id) {
+    spotlightRegistry.get(id)?.hide();
+}
+/**
+ * Check if a spotlight is currently open by its registered ID.
+ *
+ * @param id - The spotlight ID to check
+ * @returns true if the spotlight is open, false otherwise
+ */
+export function isSpotlightOpen(id) {
+    return spotlightOpenStates[id] ?? false;
+}
+/**
+ * Checks if the browser supports CSS Anchor Positioning for annotation placement.
+ */
+function isAnchorPositioningSupported() {
+    return (CSS.supports("anchor-name", "--anchor") &&
+        CSS.supports("position-area", "top") &&
+        CSS.supports("position-try", "top") &&
+        CSS.supports("position-try-fallbacks", "top"));
+}
+const POSITION_MAP = {
+    top: "top",
+    "top-left": "top left",
+    "top-right": "top right",
+    "top-span-left": "top span-left",
+    "top-span-right": "top span-right",
+    bottom: "bottom",
+    "bottom-left": "bottom left",
+    "bottom-right": "bottom right",
+    "bottom-span-left": "bottom span-left",
+    "bottom-span-right": "bottom span-right",
+    left: "left",
+    right: "right",
+};
+const _classAnnotation = `
+	bg-(--stuic-spotlight-annotation-bg) text-(--stuic-spotlight-annotation-text)
+	shadow-lg rounded-md
+	border border-(--stuic-spotlight-annotation-border)
+	z-50
+`;
+/**
+ * Builds the clip-path value for the backdrop overlay with a rounded-rectangle hole.
+ */
+function buildClipPath(rect, padding, borderRadius) {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const x = rect.left - padding;
+    const y = rect.top - padding;
+    const w = rect.width + padding * 2;
+    const h = rect.height + padding * 2;
+    const r = Math.min(borderRadius, w / 2, h / 2);
+    if (r <= 0) {
+        // Simple rectangular hole (no rounding)
+        return `polygon(evenodd, 0 0, ${vw}px 0, ${vw}px ${vh}px, 0 ${vh}px, 0 0, ${x}px ${y}px, ${x}px ${y + h}px, ${x + w}px ${y + h}px, ${x + w}px ${y}px, ${x}px ${y}px)`;
+    }
+    // Rounded rectangular hole using SVG path syntax
+    return `path(evenodd, "M 0 0 L ${vw} 0 L ${vw} ${vh} L 0 ${vh} Z M ${x + r} ${y} L ${x + w - r} ${y} A ${r} ${r} 0 0 1 ${x + w} ${y + r} L ${x + w} ${y + h - r} A ${r} ${r} 0 0 1 ${x + w - r} ${y + h} L ${x + r} ${y + h} A ${r} ${r} 0 0 1 ${x} ${y + h - r} L ${x} ${y + r} A ${r} ${r} 0 0 1 ${x + r} ${y} Z")`;
+}
+/**
+ * Checks if content is simple (string/html) vs complex (component/snippet).
+ */
+function isSimpleContent(content) {
+    if (!content)
+        return true;
+    if (typeof content === "string")
+        return true;
+    if (typeof content === "object") {
+        if ("text" in content || "html" in content)
+            return true;
+    }
+    return false;
+}
+/**
+ * Extracts string content for simple THC types.
+ */
+function getStringContent(content) {
+    if (!content)
+        return "";
+    if (typeof content === "string")
+        return content;
+    if (typeof content === "object") {
+        if ("html" in content)
+            return content.html;
+        if ("text" in content)
+            return content.text;
+    }
+    return "";
+}
+/**
+ * A Svelte action that highlights a target element with a spotlight effect.
+ *
+ * Creates a dimmed backdrop overlay with a cutout hole around the target element,
+ * optionally showing annotation content positioned next to it. Useful for onboarding
+ * tutorials, feature tours, and drawing attention to specific UI elements.
+ *
+ * The cutout uses `clip-path` with an SVG path, so pointer events in the hole area
+ * pass through to the target element naturally.
+ *
+ * @param targetEl - The element to spotlight
+ * @param fn - Function returning spotlight options (reactive)
+ *
+ * @example
+ * ```svelte
+ * <!-- Basic usage with programmatic control -->
+ * <button
+ *   use:spotlight={() => ({
+ *     content: "Click here to get started!",
+ *     position: "bottom",
+ *     id: "intro-step-1",
+ *   })}
+ * >
+ *   Get Started
+ * </button>
+ *
+ * <button onclick={() => showSpotlight('intro-step-1')}>
+ *   Start Tour
+ * </button>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Reactive open control -->
+ * <div use:spotlight={() => ({
+ *   content: { component: TourStep, props: { step: 1 } },
+ *   position: "right",
+ *   open: showTour,
+ *   onHide: () => showTour = false,
+ * })}>
+ *   Target content
+ * </div>
+ * ```
+ */
+export function spotlight(targetEl, fn) {
+    const isSupported = isAnchorPositioningSupported();
+    // State
+    let backdropEl = null;
+    let annotationEl = null;
+    let anchorEl = null; // invisible anchor for CSS Anchor Positioning
+    let mountedComponent = null;
+    let isVisible = false;
+    let do_debug = false;
+    let prevOpen = undefined;
+    let resizeObserver = null;
+    // Unique identifiers
+    const rnd = Math.random().toString(36).slice(2);
+    const anchorName = `--anchor-spotlight-${rnd}`;
+    // Current options
+    let currentOptions = {};
+    const debug = (...args) => {
+        if (do_debug)
+            console.debug("[spotlight]", rnd, ...args);
+    };
+    function onEscape(e) {
+        if (e.key === "Escape") {
+            e.preventDefault();
+            e.stopPropagation();
+            e.stopImmediatePropagation();
+            hide();
+        }
+    }
+    function onBackdropClick(e) {
+        // Only close if clicking the backdrop itself (not the annotation or the hole)
+        if (e.target === backdropEl) {
+            hide();
+        }
+    }
+    /**
+     * Update the clip-path hole position to match the current target rect.
+     */
+    function updateHolePosition() {
+        if (!backdropEl || !isVisible)
+            return;
+        const rect = targetEl.getBoundingClientRect();
+        const padding = currentOptions.padding ?? 8;
+        const borderRadius = currentOptions.borderRadius ?? 8;
+        debug("updateHolePosition()", rect);
+        backdropEl.style.clipPath = buildClipPath(rect, padding, borderRadius);
+        // Update the invisible anchor element position
+        if (anchorEl) {
+            anchorEl.style.left = `${rect.left - padding}px`;
+            anchorEl.style.top = `${rect.top - padding}px`;
+            anchorEl.style.width = `${rect.width + padding * 2}px`;
+            anchorEl.style.height = `${rect.height + padding * 2}px`;
+        }
+        // Update fallback annotation position
+        if (annotationEl && !isSupported) {
+            positionAnnotationFallback(rect, padding);
+        }
+    }
+    /**
+     * Position annotation without CSS Anchor Positioning (fallback).
+     */
+    function positionAnnotationFallback(rect, padding) {
+        if (!annotationEl)
+            return;
+        const pos = currentOptions.position || "bottom";
+        const offset = 8; // px fallback offset
+        const x = rect.left - padding;
+        const y = rect.top - padding;
+        const w = rect.width + padding * 2;
+        const h = rect.height + padding * 2;
+        // Reset position
+        annotationEl.style.left = "";
+        annotationEl.style.top = "";
+        annotationEl.style.right = "";
+        annotationEl.style.bottom = "";
+        if (pos.startsWith("top")) {
+            annotationEl.style.left = `${x}px`;
+            annotationEl.style.bottom = `${window.innerHeight - y + offset}px`;
+        }
+        else if (pos.startsWith("bottom")) {
+            annotationEl.style.left = `${x}px`;
+            annotationEl.style.top = `${y + h + offset}px`;
+        }
+        else if (pos === "left") {
+            annotationEl.style.right = `${window.innerWidth - x + offset}px`;
+            annotationEl.style.top = `${y}px`;
+        }
+        else if (pos === "right") {
+            annotationEl.style.left = `${x + w + offset}px`;
+            annotationEl.style.top = `${y}px`;
+        }
+    }
+    function renderContent() {
+        if (!annotationEl || !currentOptions.content)
+            return;
+        debug("renderContent()");
+        if (mountedComponent) {
+            unmount(mountedComponent);
+            mountedComponent = null;
+        }
+        annotationEl.innerHTML = "";
+        const content = currentOptions.content;
+        if (isSimpleContent(content)) {
+            annotationEl.innerHTML = getStringContent(content);
+        }
+        else {
+            mountedComponent = mount(SpotlightContent, {
+                target: annotationEl,
+                props: { thc: content },
+            });
+        }
+    }
+    function show() {
+        debug("show()", {
+            enabled: currentOptions.enabled,
+            content: currentOptions.content,
+        });
+        if (!currentOptions.enabled)
+            return;
+        if (isVisible)
+            return;
+        isVisible = true;
+        if (currentOptions.id) {
+            spotlightOpenStates[currentOptions.id] = true;
+        }
+        const padding = currentOptions.padding ?? 8;
+        const borderRadius = currentOptions.borderRadius ?? 8;
+        const offsetValue = currentOptions.offset || "0.5rem";
+        // Optionally scroll target into view
+        if (currentOptions.scrollIntoView !== false) {
+            targetEl.scrollIntoView({ behavior: "smooth", block: "center" });
+        }
+        // Wait for potential scroll to settle before measuring
+        requestAnimationFrame(() => {
+            if (!isVisible)
+                return; // may have been hidden in the meantime
+            const rect = targetEl.getBoundingClientRect();
+            // 1. Create backdrop overlay
+            backdropEl = document.createElement("div");
+            backdropEl.style.cssText = `
+				position: fixed;
+				inset: 0;
+				z-index: 50;
+				background: var(--stuic-spotlight-backdrop-bg);
+				transition-duration: ${TRANSITION}ms;
+			`;
+            backdropEl.classList.add(...twMerge("stuic-spotlight-backdrop", currentOptions.classBackdrop).split(/\s/));
+            backdropEl.style.clipPath = buildClipPath(rect, padding, borderRadius);
+            document.body.appendChild(backdropEl);
+            // 2. Create invisible anchor element for CSS Anchor Positioning
+            anchorEl = document.createElement("div");
+            anchorEl.style.cssText = `
+				position: fixed;
+				left: ${rect.left - padding}px;
+				top: ${rect.top - padding}px;
+				width: ${rect.width + padding * 2}px;
+				height: ${rect.height + padding * 2}px;
+				pointer-events: none;
+				z-index: -1;
+			`;
+            addAnchorName(anchorEl, anchorName);
+            document.body.appendChild(anchorEl);
+            // 3. Create annotation element (if content provided)
+            if (currentOptions.content) {
+                annotationEl = document.createElement("div");
+                annotationEl.setAttribute("role", "dialog");
+                if (isSupported) {
+                    annotationEl.style.cssText = `
+						position: fixed;
+						position-anchor: ${anchorName};
+						position-area: ${POSITION_MAP[currentOptions.position || "bottom"] || "bottom"};
+						transition-duration: ${TRANSITION}ms;
+						margin: ${offsetValue};
+						z-index: 50;
+					`;
+                    annotationEl.classList.add(...twMerge("stuic-spotlight-annotation", _classAnnotation, currentOptions.class).split(/\s/));
+                }
+                else {
+                    // Fallback positioning
+                    annotationEl.style.cssText = `
+						position: fixed;
+						transition-duration: ${TRANSITION}ms;
+						z-index: 50;
+						max-width: 90vw;
+					`;
+                    annotationEl.classList.add(...twMerge("stuic-spotlight-annotation-fallback", _classAnnotation, currentOptions.class).split(/\s/));
+                    positionAnnotationFallback(rect, padding);
+                }
+                document.body.appendChild(annotationEl);
+                renderContent();
+            }
+            // 4. Lock body scroll
+            BodyScroll.lock();
+            // 5. Transition in
+            requestAnimationFrame(() => {
+                backdropEl?.classList.add("spot-visible");
+                if (annotationEl) {
+                    annotationEl.classList.add("spot-block");
+                    requestAnimationFrame(() => {
+                        annotationEl?.classList.add("spot-visible");
+                    });
+                }
+                currentOptions.onShow?.();
+            });
+            // 6. Event listeners
+            if (currentOptions.closeOnEscape !== false) {
+                document.addEventListener("keydown", onEscape);
+            }
+            if (currentOptions.closeOnBackdropClick !== false) {
+                backdropEl.addEventListener("click", onBackdropClick);
+            }
+            // 7. Watch for target position changes
+            resizeObserver = new ResizeObserver(updateHolePosition);
+            resizeObserver.observe(targetEl);
+            window.addEventListener("resize", updateHolePosition);
+            window.addEventListener("scroll", updateHolePosition, true);
+        });
+    }
+    function hide() {
+        debug("hide()");
+        if (!isVisible)
+            return;
+        isVisible = false;
+        if (currentOptions.id) {
+            spotlightOpenStates[currentOptions.id] = false;
+        }
+        // Remove event listeners
+        document.removeEventListener("keydown", onEscape);
+        window.removeEventListener("resize", updateHolePosition);
+        window.removeEventListener("scroll", updateHolePosition, true);
+        resizeObserver?.disconnect();
+        resizeObserver = null;
+        // Unlock body scroll
+        BodyScroll.unlock();
+        // Transition out
+        backdropEl?.classList.remove("spot-visible");
+        annotationEl?.classList.remove("spot-visible");
+        setTimeout(() => {
+            if (mountedComponent) {
+                unmount(mountedComponent);
+                mountedComponent = null;
+            }
+            if (anchorEl) {
+                removeAnchorName(anchorEl, anchorName);
+                anchorEl.remove();
+                anchorEl = null;
+            }
+            backdropEl?.remove();
+            annotationEl?.remove();
+            backdropEl = null;
+            annotationEl = null;
+            currentOptions.onHide?.();
+        }, TRANSITION);
+    }
+    // Reactive params effect
+    $effect(() => {
+        const opts = fn?.() || {};
+        currentOptions = {
+            enabled: opts.enabled ?? true,
+            content: opts.content,
+            position: opts.position || "bottom",
+            padding: opts.padding ?? 8,
+            borderRadius: opts.borderRadius ?? 8,
+            class: opts.class,
+            classBackdrop: opts.classBackdrop,
+            offset: opts.offset,
+            closeOnEscape: opts.closeOnEscape ?? true,
+            closeOnBackdropClick: opts.closeOnBackdropClick ?? true,
+            scrollIntoView: opts.scrollIntoView ?? true,
+            onShow: opts.onShow,
+            onHide: opts.onHide,
+            debug: opts.debug,
+            id: opts.id,
+        };
+        do_debug = !!opts.debug;
+        // Register in global registry if id provided
+        if (opts.id) {
+            spotlightRegistry.set(opts.id, { show, hide });
+        }
+        // Update if visible
+        if (isVisible) {
+            updateHolePosition();
+            if (annotationEl && isSupported) {
+                annotationEl.style.setProperty("position-area", POSITION_MAP[currentOptions.position || "bottom"] || "bottom");
+            }
+            if (currentOptions.content) {
+                renderContent();
+            }
+        }
+        // Handle programmatic open/close
+        const openValue = opts.open;
+        if (openValue !== undefined && openValue !== prevOpen) {
+            if (openValue && !isVisible) {
+                show();
+            }
+            else if (!openValue && isVisible) {
+                hide();
+            }
+        }
+        prevOpen = openValue;
+    });
+    // Cleanup effect
+    $effect(() => {
+        return () => {
+            // Cleanup on unmount
+            if (mountedComponent) {
+                unmount(mountedComponent);
+                mountedComponent = null;
+            }
+            if (isVisible) {
+                BodyScroll.unlock();
+            }
+            if (anchorEl) {
+                removeAnchorName(anchorEl, anchorName);
+                anchorEl.remove();
+            }
+            backdropEl?.remove();
+            annotationEl?.remove();
+            resizeObserver?.disconnect();
+            document.removeEventListener("keydown", onEscape);
+            window.removeEventListener("resize", updateHolePosition);
+            window.removeEventListener("scroll", updateHolePosition, true);
+            // Unregister from registry
+            if (currentOptions.id) {
+                spotlightRegistry.delete(currentOptions.id);
+                delete spotlightOpenStates[currentOptions.id];
+            }
+        };
+    });
+}

package/dist/index.css

@@ -57,6 +57,7 @@ In practice:
 
 /* Action CSS */
 @import "./actions/popover/index.css";
+@import "./actions/spotlight/index.css";
 @import "./actions/tooltip/index.css";
 
 /* Base styles for STUIC components */

package/docs/domains/actions.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-12 Svelte actions (directives) for reusable DOM behavior.
+13 Svelte actions (directives) for reusable DOM behavior.
 
 ---
 
@@ -21,6 +21,7 @@
 | `typeahead` | Advanced autocomplete behavior | `typeahead.svelte.ts` |
 | `onSubmitValidityCheck` | Form submit validation | `on-submit-validity-check.svelte.ts` |
 | `popover` | Popover positioning | `popover/` |
+| `spotlight` | Spotlight/coach mark overlay with cutout hole | `spotlight/` |
 | `tooltip` | Tooltip positioning and display | `tooltip/` |
 
 ---
@@ -76,6 +77,22 @@ Actions using `$effect()` accept a function returning options:
 </div>
 ```
 
+### Spotlight
+
+```svelte
+<div
+  use:spotlight={() => ({
+    content: "Check out this feature!",
+    position: "bottom",
+    id: "intro-step-1",
+  })}
+>
+  Target Element
+</div>
+
+<button onclick={() => showSpotlight('intro-step-1')}>Start Tour</button>
+```
+
 ### Tooltip
 
 ```svelte
@@ -121,4 +138,5 @@ export function focusTrap(el: HTMLElement, options?: Options) {
 | src/lib/actions/index.ts | All action exports |
 | src/lib/actions/validate.svelte.ts | Complex action example |
 | src/lib/actions/focus-trap.ts | Traditional action pattern |
+| src/lib/actions/spotlight/ | Spotlight/coach mark action |
 | src/lib/actions/tooltip/ | Multi-file action example |

package/package.json

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