@julscodes/react-spotlight-tour 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR_NAME_HERE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# react-spotlight-tour
+
+A lightweight, dependency-free React component for building step-by-step
+spotlight product tours / onboarding walkthroughs. Highlights a target
+element on the page and shows a card with a title, description, optional
+image/video, and Next / Previous / Finish controls.
+
+> **Note:** `react-spotlight-tour` is a placeholder package name. Rename it
+> in `package.json` (and update the GitHub URLs) before publishing, since the
+> name must be unique on the npm registry.
+
+## Install
+
+```bash
+npm install react-spotlight-tour
+```
+
+`react` and `react-dom` (>=16.8, for hooks support) are peer dependencies and
+must already be present in your project.
+
+## Usage
+
+```tsx
+import { Tutorial } from "react-spotlight-tour";
+
+function App() {
+  return (
+    <>
+      <button id="new-project-btn">New project</button>
+      <div id="sidebar">...</div>
+
+      <Tutorial
+        steps={[
+          {
+            followId: "new-project-btn",
+            title: "Create a project",
+            description: "Click here to start a new project.",
+          },
+          {
+            followId: "sidebar",
+            title: "Your workspace",
+            description: "Everything you build lives here.",
+            src: "/onboarding/sidebar.png",
+          },
+          {
+            title: "You're all set!",
+            description: "That's it — have fun exploring.",
+          },
+        ]}
+        onClose={() => console.log("tour finished or dismissed")}
+      />
+    </>
+  );
+}
+```
+
+Each step card automatically positions itself next to the element referenced
+by `followId` (falling back to a centered card if omitted or the element
+can't be found), and repositions on scroll/resize.
+
+## API
+
+### `<Tutorial />`
+
+| Prop          | Type         | Default | Description                                      |
+| ------------- | ------------ | ------- | ------------------------------------------------- |
+| `steps`       | `Step[]`     | —       | Required. The ordered list of steps to walk through. |
+| `defaultOpen` | `boolean`    | `true`  | Whether the tour starts open.                     |
+| `onClose`     | `() => void` | —       | Called when the tour is finished or dismissed.    |
+
+### `Step`
+
+| Field         | Type     | Description                                                        |
+| ------------- | -------- | -------------------------------------------------------------------- |
+| `followId`    | `string` | Optional `id` of the element to spotlight. Card centers if omitted.  |
+| `title`       | `string` | Step title.                                                           |
+| `description` | `string` | Step body text.                                                       |
+| `src`         | `string` | Optional image or video URL. `.mp4` renders as `<video>`, else `<img>`. |
+
+## Styling
+
+Base styles are imported automatically when you import from the package. If
+your setup (e.g. certain Next.js configurations) doesn't apply CSS imported
+from `node_modules` automatically, import the stylesheet explicitly once in
+your app's entry point:
+
+```ts
+import "react-spotlight-tour/styles.css";
+```
+
+Look, feel, and colors are controlled by CSS custom properties defined on
+`:root` (e.g. `--tutorial-primary`, `--tutorial-bg`, `--tutorial-radius`) —
+override them in your own CSS to theme the component.
+
+## Development
+
+```bash
+npm install
+npm run build   # emits dist/esm, dist/cjs, dist/types
+```
+
+## Publishing to npm
+
+1. Update `name`, `version`, `author`, `repository`/`homepage`/`bugs` URLs in
+   `package.json`, and the copyright line in `LICENSE`.
+2. Make sure the chosen package name is free:
+   ```bash
+   npm view react-spotlight-tour
+   ```
+   (a 404 means it's available; pick a new name or scope it, e.g.
+   `@yourusername/react-spotlight-tour`, if it's taken).
+3. Log in to npm (one-time):
+   ```bash
+   npm login
+   ```
+4. From the package root, do a dry run to confirm exactly what will be
+   published:
+   ```bash
+   npm publish --dry-run
+   ```
+5. Publish for real (this also runs `npm run build` automatically via the
+   `prepublishOnly` script):
+   ```bash
+   npm publish
+   # if using a scoped name and want it public:
+   npm publish --access public
+   ```
+6. For future updates, bump the version before publishing again:
+   ```bash
+   npm version patch   # or minor / major
+   npm publish
+   ```
+
+## License
+
+MIT

package/dist/cjs/StepCard.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = StepCard;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const utils_1 = require("./utils");
+function StepCard({ step, index, total, onNext, onPrevious, onFinish, }) {
+    const cardRef = (0, react_1.useRef)(null);
+    const [position, setPosition] = (0, react_1.useState)(null);
+    const updatePosition = (0, react_1.useCallback)(() => {
+        if (!cardRef.current)
+            return;
+        const pos = (0, utils_1.calculateCardPosition)(step.followId, cardRef.current);
+        setPosition(pos);
+    }, [step.followId]);
+    (0, react_1.useLayoutEffect)(() => {
+        updatePosition();
+        window.addEventListener("resize", updatePosition);
+        window.addEventListener("scroll", updatePosition, true);
+        return () => {
+            window.removeEventListener("resize", updatePosition);
+            window.removeEventListener("scroll", updatePosition, true);
+        };
+    }, [updatePosition]);
+    return ((0, jsx_runtime_1.jsxs)("div", { ref: cardRef, className: "tutorial-card", style: {
+            top: position ? position.top : "50%",
+            left: position ? position.left : "50%",
+            transform: position ? undefined : "translate(-50%, -50%)",
+        }, children: [step.src &&
+                ((0, utils_1.isVideo)(step.src) ? ((0, jsx_runtime_1.jsx)("video", { className: "tutorial-media", src: step.src, autoPlay: true, muted: true, loop: true, playsInline: true })) : ((0, jsx_runtime_1.jsx)("img", { className: "tutorial-media", src: step.src, alt: step.title }))), (0, jsx_runtime_1.jsxs)("div", { className: "tutorial-content", children: [(0, jsx_runtime_1.jsx)("h2", { className: "tutorial-title", children: step.title }), (0, jsx_runtime_1.jsx)("p", { className: "tutorial-description", children: step.description }), (0, jsx_runtime_1.jsxs)("div", { className: "tutorial-actions", children: [(0, jsx_runtime_1.jsx)("button", { className: "tutorial-button tutorial-button-secondary", disabled: index === 0, onClick: onPrevious, children: "Previous" }), index === total - 1 ? ((0, jsx_runtime_1.jsx)("button", { className: "tutorial-button tutorial-button-primary", onClick: onFinish, children: "Finish" })) : ((0, jsx_runtime_1.jsx)("button", { className: "tutorial-button tutorial-button-primary", onClick: onNext, children: "Next" }))] }), (0, jsx_runtime_1.jsx)("div", { className: "tutorial-progress", children: Array.from({ length: total }).map((_, i) => ((0, jsx_runtime_1.jsx)("span", { className: `tutorial-dot ${i === index ? "active" : ""}` }, i))) })] })] }));
+}

package/dist/cjs/Tutorial.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = Tutorial;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const StepCard_1 = __importDefault(require("./StepCard"));
+const utils_1 = require("./utils");
+function Tutorial({ steps, defaultOpen = true, onClose, }) {
+    const [open, setOpen] = (0, react_1.useState)(defaultOpen);
+    const [currentStepIndex, setCurrentStepIndex] = (0, react_1.useState)(0);
+    const highlightedElement = (0, react_1.useRef)(null);
+    const currentStep = steps[currentStepIndex];
+    /**
+     * Remove highlight from previous element.
+     */
+    const removeCurrentHighlight = (0, react_1.useCallback)(() => {
+        (0, utils_1.clearHighlight)(highlightedElement.current);
+        highlightedElement.current = null;
+    }, []);
+    /**
+     * Close tutorial.
+     */
+    const closeTutorial = (0, react_1.useCallback)(() => {
+        removeCurrentHighlight();
+        (0, utils_1.disableOverlay)();
+        setOpen(false);
+        onClose === null || onClose === void 0 ? void 0 : onClose();
+    }, [onClose, removeCurrentHighlight]);
+    /**
+     * Apply spotlight whenever the current step changes.
+     */
+    (0, react_1.useEffect)(() => {
+        if (!open || !currentStep)
+            return;
+        (0, utils_1.enableOverlay)();
+        removeCurrentHighlight();
+        highlightedElement.current = (0, utils_1.highlightElement)(currentStep.followId);
+        return () => {
+            removeCurrentHighlight();
+        };
+    }, [open, currentStep, removeCurrentHighlight]);
+    /**
+     * Cleanup on unmount.
+     */
+    (0, react_1.useEffect)(() => {
+        return () => {
+            removeCurrentHighlight();
+            (0, utils_1.disableOverlay)();
+        };
+    }, [removeCurrentHighlight]);
+    const nextStep = () => {
+        if (currentStepIndex === steps.length - 1) {
+            closeTutorial();
+            return;
+        }
+        setCurrentStepIndex((current) => current + 1);
+    };
+    const previousStep = () => {
+        setCurrentStepIndex((current) => Math.max(current - 1, 0));
+    };
+    if (!open)
+        return null;
+    if (steps.length === 0)
+        return null;
+    return ((0, jsx_runtime_1.jsx)("div", { className: "tutorial-container", "aria-hidden": false, role: "dialog", "aria-modal": "true", children: (0, jsx_runtime_1.jsx)(StepCard_1.default, { step: currentStep, index: currentStepIndex, total: steps.length, onNext: nextStep, onPrevious: previousStep, onFinish: closeTutorial }) }));
+}

package/dist/cjs/index.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tutorial = void 0;
+// @ts-ignore: CSS import handled by bundler
+require("./styles.css");
+var Tutorial_1 = require("./Tutorial");
+Object.defineProperty(exports, "Tutorial", { enumerable: true, get: function () { return __importDefault(Tutorial_1).default; } });

package/dist/cjs/styles.css

@@ -0,0 +1,234 @@
+:root {
+  --tutorial-z-overlay: 9998;
+  --tutorial-z-highlight: 9999;
+  --tutorial-z-card: 10000;
+
+  --tutorial-overlay: rgba(0, 0, 0, 0.72);
+
+  --tutorial-bg: #292929;
+  --tutorial-text: #ffffff;
+  --tutorial-muted: #c6c6c6;
+
+  --tutorial-primary: #2563eb;
+  --tutorial-primary-hover: #1d4ed8;
+
+  --tutorial-secondary: #4b5563;
+  --tutorial-secondary-hover: #374151;
+
+  --tutorial-radius: 12px;
+  --tutorial-shadow: 0 18px 40px rgba(0, 0, 0, 0.35);
+
+  --tutorial-border: #3d3d3d;
+
+  --tutorial-width: 360px;
+
+  --tutorial-transition: 0.2s ease;
+}
+
+/* ========================================================= */
+/* Overlay                                                   */
+/* ========================================================= */
+
+.tutorial-container {
+  position: fixed;
+  inset: 0;
+  z-index: var(--tutorial-z-card);
+  pointer-events: none;
+}
+
+/* ========================================================= */
+/* Card                                                      */
+/* ========================================================= */
+
+.tutorial-card {
+  position: absolute;
+
+  width: var(--tutorial-width);
+  max-width: calc(100vw - 32px);
+
+  overflow: hidden;
+
+  border-radius: var(--tutorial-radius);
+
+  background: var(--tutorial-bg);
+
+  color: var(--tutorial-text);
+
+  border: 1px solid var(--tutorial-border);
+
+  box-shadow: var(--tutorial-shadow);
+
+  pointer-events: auto;
+
+  box-sizing: border-box;
+}
+
+/* ========================================================= */
+/* Media                                                     */
+/* ========================================================= */
+
+.tutorial-media {
+  display: block;
+
+  width: 100%;
+  height: 190px;
+
+  object-fit: cover;
+
+  background: #000;
+}
+
+/* ========================================================= */
+/* Content                                                   */
+/* ========================================================= */
+
+.tutorial-content {
+  padding: 20px;
+}
+
+.tutorial-title {
+  margin: 0;
+
+  font-size: 22px;
+
+  font-weight: 700;
+
+  line-height: 1.3;
+}
+
+.tutorial-description {
+  margin-top: 12px;
+
+  margin-bottom: 0;
+
+  color: var(--tutorial-muted);
+
+  line-height: 1.55;
+
+  font-size: 15px;
+}
+
+/* ========================================================= */
+/* Progress                                                  */
+/* ========================================================= */
+
+.tutorial-progress {
+  display: flex;
+
+  justify-content: center;
+
+  align-items: center;
+
+  gap: 8px;
+
+  margin-top: 24px;
+}
+
+.tutorial-dot {
+  width: 5px;
+
+  height: 5px;
+
+  border-radius: 999px;
+
+  background: #666;
+
+  transition:
+    background var(--tutorial-transition),
+    transform var(--tutorial-transition);
+}
+
+.tutorial-dot.active {
+  background: white;
+
+  transform: scale(1.2);
+}
+
+/* ========================================================= */
+/* Buttons                                                   */
+/* ========================================================= */
+
+.tutorial-actions {
+  display: flex;
+
+  justify-content: space-between;
+
+  align-items: center;
+
+  margin-top: 28px;
+
+  gap: 12px;
+}
+
+.tutorial-button {
+  appearance: none;
+
+  border: none;
+
+  outline: none;
+
+  cursor: pointer;
+
+  padding: 10px 18px;
+
+  border-radius: 8px;
+
+  color: white;
+
+  font-size: 14px;
+
+  font-weight: 600;
+
+  transition:
+    background var(--tutorial-transition),
+    opacity var(--tutorial-transition),
+    transform var(--tutorial-transition);
+}
+
+.tutorial-button:hover:not(:disabled) {
+  transform: translateY(-1px);
+}
+
+.tutorial-button:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.tutorial-button:disabled {
+  cursor: not-allowed;
+
+  opacity: 0.45;
+}
+
+.tutorial-button-primary {
+  background: var(--tutorial-primary);
+}
+
+.tutorial-button-primary:hover:not(:disabled) {
+  background: var(--tutorial-primary-hover);
+}
+
+.tutorial-button-secondary {
+  background: var(--tutorial-secondary);
+}
+
+.tutorial-button-secondary:hover:not(:disabled) {
+  background: var(--tutorial-secondary-hover);
+}
+
+/* ========================================================= */
+/* Responsive                                                */
+/* ========================================================= */
+
+@media (max-width: 500px) {
+  .tutorial-card {
+    width: calc(100vw - 24px);
+  }
+
+  .tutorial-actions {
+    flex-direction: column;
+  }
+
+  .tutorial-button {
+    width: 100%;
+  }
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/utils.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HIGHLIGHT_CLASS = exports.STYLE_ID = exports.BODY_CLASS = void 0;
+exports.ensureGlobalStyles = ensureGlobalStyles;
+exports.enableOverlay = enableOverlay;
+exports.disableOverlay = disableOverlay;
+exports.highlightElement = highlightElement;
+exports.clearHighlight = clearHighlight;
+exports.isVideo = isVideo;
+exports.calculateCardPosition = calculateCardPosition;
+exports.BODY_CLASS = "__tutorial_overlay__";
+exports.STYLE_ID = "__tutorial_overlay_style__";
+exports.HIGHLIGHT_CLASS = "__tutorial_highlight__";
+/**
+ * Inject the package styles into the document only once.
+ */
+function ensureGlobalStyles() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(exports.STYLE_ID))
+        return;
+    const style = document.createElement("style");
+    style.id = exports.STYLE_ID;
+    style.innerHTML = `
+    body.${exports.BODY_CLASS}::after{
+      content:"";
+      position:fixed;
+      inset:0;
+      background:rgba(0,0,0,.72);
+      z-index:9998;
+      pointer-events:none;
+    }
+
+    .${exports.HIGHLIGHT_CLASS}{
+      position:relative !important;
+      z-index:9999 !important;
+      border-radius:10px;
+      box-shadow:0 0 0 9999px rgba(0,0,0,.72);
+      transition:box-shadow .25s ease;
+    }
+  `;
+    document.head.appendChild(style);
+}
+/**
+ * Enables the page overlay.
+ */
+function enableOverlay() {
+    if (typeof document === "undefined")
+        return;
+    ensureGlobalStyles();
+    document.body.classList.add(exports.BODY_CLASS);
+}
+/**
+ * Removes the page overlay.
+ */
+function disableOverlay() {
+    if (typeof document === "undefined")
+        return;
+    document.body.classList.remove(exports.BODY_CLASS);
+}
+/**
+ * Adds the spotlight effect to an element.
+ */
+function highlightElement(followId) {
+    if (typeof document === "undefined")
+        return null;
+    if (!followId)
+        return null;
+    const element = document.getElementById(followId);
+    if (!element)
+        return null;
+    element.classList.add(exports.HIGHLIGHT_CLASS);
+    return element;
+}
+/**
+ * Removes the spotlight from an element.
+ */
+function clearHighlight(element) {
+    if (!element)
+        return;
+    element.classList.remove(exports.HIGHLIGHT_CLASS);
+}
+/**
+ * Determines whether a source should render as a video.
+ */
+function isVideo(src) {
+    if (!src)
+        return false;
+    return src.endsWith(".mp4") || src.includes(".mp4");
+}
+/**
+ * Calculates where the tutorial card should appear.
+ */
+function calculateCardPosition(followId, card) {
+    if (!followId)
+        return null;
+    const target = document.getElementById(followId);
+    if (!target)
+        return null;
+    const rect = target.getBoundingClientRect();
+    const cardRect = card.getBoundingClientRect();
+    const GAP = 18;
+    const PADDING = 16;
+    let left = rect.right + GAP;
+    let top = rect.top;
+    // Overflow right
+    if (left + cardRect.width > window.innerWidth - PADDING) {
+        left = rect.left - cardRect.width - GAP;
+    }
+    // Overflow left
+    if (left < PADDING) {
+        left = PADDING;
+    }
+    // Overflow bottom
+    if (top + cardRect.height > window.innerHeight - PADDING) {
+        top = window.innerHeight - cardRect.height - PADDING;
+    }
+    // Overflow top
+    if (top < PADDING) {
+        top = PADDING;
+    }
+    return {
+        top,
+        left,
+    };
+}

package/dist/esm/StepCard.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import { calculateCardPosition, isVideo } from "./utils";
+export default function StepCard({ step, index, total, onNext, onPrevious, onFinish, }) {
+    const cardRef = useRef(null);
+    const [position, setPosition] = useState(null);
+    const updatePosition = useCallback(() => {
+        if (!cardRef.current)
+            return;
+        const pos = calculateCardPosition(step.followId, cardRef.current);
+        setPosition(pos);
+    }, [step.followId]);
+    useLayoutEffect(() => {
+        updatePosition();
+        window.addEventListener("resize", updatePosition);
+        window.addEventListener("scroll", updatePosition, true);
+        return () => {
+            window.removeEventListener("resize", updatePosition);
+            window.removeEventListener("scroll", updatePosition, true);
+        };
+    }, [updatePosition]);
+    return (_jsxs("div", { ref: cardRef, className: "tutorial-card", style: {
+            top: position ? position.top : "50%",
+            left: position ? position.left : "50%",
+            transform: position ? undefined : "translate(-50%, -50%)",
+        }, children: [step.src &&
+                (isVideo(step.src) ? (_jsx("video", { className: "tutorial-media", src: step.src, autoPlay: true, muted: true, loop: true, playsInline: true })) : (_jsx("img", { className: "tutorial-media", src: step.src, alt: step.title }))), _jsxs("div", { className: "tutorial-content", children: [_jsx("h2", { className: "tutorial-title", children: step.title }), _jsx("p", { className: "tutorial-description", children: step.description }), _jsxs("div", { className: "tutorial-actions", children: [_jsx("button", { className: "tutorial-button tutorial-button-secondary", disabled: index === 0, onClick: onPrevious, children: "Previous" }), index === total - 1 ? (_jsx("button", { className: "tutorial-button tutorial-button-primary", onClick: onFinish, children: "Finish" })) : (_jsx("button", { className: "tutorial-button tutorial-button-primary", onClick: onNext, children: "Next" }))] }), _jsx("div", { className: "tutorial-progress", children: Array.from({ length: total }).map((_, i) => (_jsx("span", { className: `tutorial-dot ${i === index ? "active" : ""}` }, i))) })] })] }));
+}

package/dist/esm/Tutorial.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import StepCard from "./StepCard";
+import { clearHighlight, disableOverlay, enableOverlay, highlightElement, } from "./utils";
+export default function Tutorial({ steps, defaultOpen = true, onClose, }) {
+    const [open, setOpen] = useState(defaultOpen);
+    const [currentStepIndex, setCurrentStepIndex] = useState(0);
+    const highlightedElement = useRef(null);
+    const currentStep = steps[currentStepIndex];
+    /**
+     * Remove highlight from previous element.
+     */
+    const removeCurrentHighlight = useCallback(() => {
+        clearHighlight(highlightedElement.current);
+        highlightedElement.current = null;
+    }, []);
+    /**
+     * Close tutorial.
+     */
+    const closeTutorial = useCallback(() => {
+        removeCurrentHighlight();
+        disableOverlay();
+        setOpen(false);
+        onClose === null || onClose === void 0 ? void 0 : onClose();
+    }, [onClose, removeCurrentHighlight]);
+    /**
+     * Apply spotlight whenever the current step changes.
+     */
+    useEffect(() => {
+        if (!open || !currentStep)
+            return;
+        enableOverlay();
+        removeCurrentHighlight();
+        highlightedElement.current = highlightElement(currentStep.followId);
+        return () => {
+            removeCurrentHighlight();
+        };
+    }, [open, currentStep, removeCurrentHighlight]);
+    /**
+     * Cleanup on unmount.
+     */
+    useEffect(() => {
+        return () => {
+            removeCurrentHighlight();
+            disableOverlay();
+        };
+    }, [removeCurrentHighlight]);
+    const nextStep = () => {
+        if (currentStepIndex === steps.length - 1) {
+            closeTutorial();
+            return;
+        }
+        setCurrentStepIndex((current) => current + 1);
+    };
+    const previousStep = () => {
+        setCurrentStepIndex((current) => Math.max(current - 1, 0));
+    };
+    if (!open)
+        return null;
+    if (steps.length === 0)
+        return null;
+    return (_jsx("div", { className: "tutorial-container", "aria-hidden": false, role: "dialog", "aria-modal": "true", children: _jsx(StepCard, { step: currentStep, index: currentStepIndex, total: steps.length, onNext: nextStep, onPrevious: previousStep, onFinish: closeTutorial }) }));
+}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+// @ts-ignore: CSS import handled by bundler
+import "./styles.css";
+export { default as Tutorial } from "./Tutorial";

package/dist/esm/styles.css

@@ -0,0 +1,234 @@
+:root {
+  --tutorial-z-overlay: 9998;
+  --tutorial-z-highlight: 9999;
+  --tutorial-z-card: 10000;
+
+  --tutorial-overlay: rgba(0, 0, 0, 0.72);
+
+  --tutorial-bg: #292929;
+  --tutorial-text: #ffffff;
+  --tutorial-muted: #c6c6c6;
+
+  --tutorial-primary: #2563eb;
+  --tutorial-primary-hover: #1d4ed8;
+
+  --tutorial-secondary: #4b5563;
+  --tutorial-secondary-hover: #374151;
+
+  --tutorial-radius: 12px;
+  --tutorial-shadow: 0 18px 40px rgba(0, 0, 0, 0.35);
+
+  --tutorial-border: #3d3d3d;
+
+  --tutorial-width: 360px;
+
+  --tutorial-transition: 0.2s ease;
+}
+
+/* ========================================================= */
+/* Overlay                                                   */
+/* ========================================================= */
+
+.tutorial-container {
+  position: fixed;
+  inset: 0;
+  z-index: var(--tutorial-z-card);
+  pointer-events: none;
+}
+
+/* ========================================================= */
+/* Card                                                      */
+/* ========================================================= */
+
+.tutorial-card {
+  position: absolute;
+
+  width: var(--tutorial-width);
+  max-width: calc(100vw - 32px);
+
+  overflow: hidden;
+
+  border-radius: var(--tutorial-radius);
+
+  background: var(--tutorial-bg);
+
+  color: var(--tutorial-text);
+
+  border: 1px solid var(--tutorial-border);
+
+  box-shadow: var(--tutorial-shadow);
+
+  pointer-events: auto;
+
+  box-sizing: border-box;
+}
+
+/* ========================================================= */
+/* Media                                                     */
+/* ========================================================= */
+
+.tutorial-media {
+  display: block;
+
+  width: 100%;
+  height: 190px;
+
+  object-fit: cover;
+
+  background: #000;
+}
+
+/* ========================================================= */
+/* Content                                                   */
+/* ========================================================= */
+
+.tutorial-content {
+  padding: 20px;
+}
+
+.tutorial-title {
+  margin: 0;
+
+  font-size: 22px;
+
+  font-weight: 700;
+
+  line-height: 1.3;
+}
+
+.tutorial-description {
+  margin-top: 12px;
+
+  margin-bottom: 0;
+
+  color: var(--tutorial-muted);
+
+  line-height: 1.55;
+
+  font-size: 15px;
+}
+
+/* ========================================================= */
+/* Progress                                                  */
+/* ========================================================= */
+
+.tutorial-progress {
+  display: flex;
+
+  justify-content: center;
+
+  align-items: center;
+
+  gap: 8px;
+
+  margin-top: 24px;
+}
+
+.tutorial-dot {
+  width: 5px;
+
+  height: 5px;
+
+  border-radius: 999px;
+
+  background: #666;
+
+  transition:
+    background var(--tutorial-transition),
+    transform var(--tutorial-transition);
+}
+
+.tutorial-dot.active {
+  background: white;
+
+  transform: scale(1.2);
+}
+
+/* ========================================================= */
+/* Buttons                                                   */
+/* ========================================================= */
+
+.tutorial-actions {
+  display: flex;
+
+  justify-content: space-between;
+
+  align-items: center;
+
+  margin-top: 28px;
+
+  gap: 12px;
+}
+
+.tutorial-button {
+  appearance: none;
+
+  border: none;
+
+  outline: none;
+
+  cursor: pointer;
+
+  padding: 10px 18px;
+
+  border-radius: 8px;
+
+  color: white;
+
+  font-size: 14px;
+
+  font-weight: 600;
+
+  transition:
+    background var(--tutorial-transition),
+    opacity var(--tutorial-transition),
+    transform var(--tutorial-transition);
+}
+
+.tutorial-button:hover:not(:disabled) {
+  transform: translateY(-1px);
+}
+
+.tutorial-button:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.tutorial-button:disabled {
+  cursor: not-allowed;
+
+  opacity: 0.45;
+}
+
+.tutorial-button-primary {
+  background: var(--tutorial-primary);
+}
+
+.tutorial-button-primary:hover:not(:disabled) {
+  background: var(--tutorial-primary-hover);
+}
+
+.tutorial-button-secondary {
+  background: var(--tutorial-secondary);
+}
+
+.tutorial-button-secondary:hover:not(:disabled) {
+  background: var(--tutorial-secondary-hover);
+}
+
+/* ========================================================= */
+/* Responsive                                                */
+/* ========================================================= */
+
+@media (max-width: 500px) {
+  .tutorial-card {
+    width: calc(100vw - 24px);
+  }
+
+  .tutorial-actions {
+    flex-direction: column;
+  }
+
+  .tutorial-button {
+    width: 100%;
+  }
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utils.js

@@ -0,0 +1,116 @@
+export const BODY_CLASS = "__tutorial_overlay__";
+export const STYLE_ID = "__tutorial_overlay_style__";
+export const HIGHLIGHT_CLASS = "__tutorial_highlight__";
+/**
+ * Inject the package styles into the document only once.
+ */
+export function ensureGlobalStyles() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(STYLE_ID))
+        return;
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.innerHTML = `
+    body.${BODY_CLASS}::after{
+      content:"";
+      position:fixed;
+      inset:0;
+      background:rgba(0,0,0,.72);
+      z-index:9998;
+      pointer-events:none;
+    }
+
+    .${HIGHLIGHT_CLASS}{
+      position:relative !important;
+      z-index:9999 !important;
+      border-radius:10px;
+      box-shadow:0 0 0 9999px rgba(0,0,0,.72);
+      transition:box-shadow .25s ease;
+    }
+  `;
+    document.head.appendChild(style);
+}
+/**
+ * Enables the page overlay.
+ */
+export function enableOverlay() {
+    if (typeof document === "undefined")
+        return;
+    ensureGlobalStyles();
+    document.body.classList.add(BODY_CLASS);
+}
+/**
+ * Removes the page overlay.
+ */
+export function disableOverlay() {
+    if (typeof document === "undefined")
+        return;
+    document.body.classList.remove(BODY_CLASS);
+}
+/**
+ * Adds the spotlight effect to an element.
+ */
+export function highlightElement(followId) {
+    if (typeof document === "undefined")
+        return null;
+    if (!followId)
+        return null;
+    const element = document.getElementById(followId);
+    if (!element)
+        return null;
+    element.classList.add(HIGHLIGHT_CLASS);
+    return element;
+}
+/**
+ * Removes the spotlight from an element.
+ */
+export function clearHighlight(element) {
+    if (!element)
+        return;
+    element.classList.remove(HIGHLIGHT_CLASS);
+}
+/**
+ * Determines whether a source should render as a video.
+ */
+export function isVideo(src) {
+    if (!src)
+        return false;
+    return src.endsWith(".mp4") || src.includes(".mp4");
+}
+/**
+ * Calculates where the tutorial card should appear.
+ */
+export function calculateCardPosition(followId, card) {
+    if (!followId)
+        return null;
+    const target = document.getElementById(followId);
+    if (!target)
+        return null;
+    const rect = target.getBoundingClientRect();
+    const cardRect = card.getBoundingClientRect();
+    const GAP = 18;
+    const PADDING = 16;
+    let left = rect.right + GAP;
+    let top = rect.top;
+    // Overflow right
+    if (left + cardRect.width > window.innerWidth - PADDING) {
+        left = rect.left - cardRect.width - GAP;
+    }
+    // Overflow left
+    if (left < PADDING) {
+        left = PADDING;
+    }
+    // Overflow bottom
+    if (top + cardRect.height > window.innerHeight - PADDING) {
+        top = window.innerHeight - cardRect.height - PADDING;
+    }
+    // Overflow top
+    if (top < PADDING) {
+        top = PADDING;
+    }
+    return {
+        top,
+        left,
+    };
+}

package/dist/types/StepCard.d.ts

@@ -0,0 +1,2 @@
+import { StepCardProps } from "./types";
+export default function StepCard({ step, index, total, onNext, onPrevious, onFinish, }: StepCardProps): import("react").JSX.Element;

package/dist/types/Tutorial.d.ts

@@ -0,0 +1,2 @@
+import { TutorialProps } from "./types";
+export default function Tutorial({ steps, defaultOpen, onClose, }: TutorialProps): import("react").JSX.Element | null;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+import "./styles.css";
+export { default as Tutorial } from "./Tutorial";
+export type { Step, TutorialProps, StepCardProps, Position } from "./types";

package/dist/types/types.d.ts

@@ -0,0 +1,48 @@
+export interface Step {
+    /**
+     * ID of the element that should be highlighted.
+     * If omitted, the step card will be centered.
+     */
+    followId?: string;
+    /**
+     * Step title.
+     */
+    title: string;
+    /**
+     * Step description.
+     */
+    description: string;
+    /**
+     * Optional image or video.
+     * .mp4 files are rendered as <video>,
+     * everything else as <img>.
+     */
+    src?: string;
+}
+export interface TutorialProps {
+    /**
+     * Tutorial steps.
+     */
+    steps: Step[];
+    /**
+     * Whether the tutorial starts opened.
+     * @default true
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the tutorial finishes.
+     */
+    onClose?: () => void;
+}
+export interface StepCardProps {
+    step: Step;
+    index: number;
+    total: number;
+    onNext(): void;
+    onPrevious(): void;
+    onFinish(): void;
+}
+export interface Position {
+    top: number;
+    left: number;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,32 @@
+import { Position } from "./types";
+export declare const BODY_CLASS = "__tutorial_overlay__";
+export declare const STYLE_ID = "__tutorial_overlay_style__";
+export declare const HIGHLIGHT_CLASS = "__tutorial_highlight__";
+/**
+ * Inject the package styles into the document only once.
+ */
+export declare function ensureGlobalStyles(): void;
+/**
+ * Enables the page overlay.
+ */
+export declare function enableOverlay(): void;
+/**
+ * Removes the page overlay.
+ */
+export declare function disableOverlay(): void;
+/**
+ * Adds the spotlight effect to an element.
+ */
+export declare function highlightElement(followId?: string): HTMLElement | null;
+/**
+ * Removes the spotlight from an element.
+ */
+export declare function clearHighlight(element: HTMLElement | null): void;
+/**
+ * Determines whether a source should render as a video.
+ */
+export declare function isVideo(src?: string): boolean;
+/**
+ * Calculates where the tutorial card should appear.
+ */
+export declare function calculateCardPosition(followId: string | undefined, card: HTMLDivElement): Position | null;

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@julscodes/react-spotlight-tour",
+  "version": "0.1.0",
+  "description": "A lightweight, dependency-free React component for building step-by-step spotlight product tours / onboarding walkthroughs.",
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "tour",
+    "onboarding",
+    "walkthrough",
+    "spotlight",
+    "tooltip",
+    "product-tour",
+    "tutorial"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julscodes/react-spotlight-tour.git"
+  },
+  "homepage": "https://github.com/julscodes/react-spotlight-tour#readme",
+  "bugs": {
+    "url": "https://github.com/julscodes/react-spotlight-tour/issues"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./styles.css": {
+      "import": "./dist/esm/styles.css",
+      "require": "./dist/cjs/styles.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "copy:css": "node scripts/copy-css.js",
+    "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:types && npm run copy:css",
+    "prepublishOnly": "npm run build"
+  }
+}