@paul-portfolio/react 0.6.0 → 0.7.0

package/dist/GuidedTour.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from 'react';
+export type GuidedTourStep = {
+    /** Id of the element to spotlight. Omit for a centred card (an intro step). */
+    target?: string;
+    title: string;
+    body: ReactNode;
+};
+type GuidedTourLabels = {
+    back?: string;
+    next?: string;
+    skip?: string;
+    finish?: string;
+};
+type GuidedTourProps = {
+    open: boolean;
+    steps: GuidedTourStep[];
+    /** Skipped, dismissed (Escape), or finished — the tour should close. */
+    onClose: () => void;
+    /** Reached the end and pressed the finish control. Fires before `onClose`. */
+    onFinish?: () => void;
+    /** Accessible name for the dialog. */
+    'aria-label'?: string;
+    /** Override the control labels. */
+    labels?: GuidedTourLabels;
+    className?: string;
+};
+/**
+ * A click-through guided tour. It walks `steps` one at a time, dimming the page
+ * and spotlighting each step's target element (measured live, so it tracks
+ * scroll and resize), with a card that pins near the target or centres when a
+ * step has none. Portals to the body, traps focus, and closes on Escape — the
+ * same shell as Modal. Purely presentational: the host owns `open` and decides
+ * what a finish or skip does.
+ */
+export declare function GuidedTour({ open, steps, onClose, onFinish, 'aria-label': ariaLabel, labels, className, }: GuidedTourProps): import("react").ReactPortal | null;
+export {};

package/dist/GuidedTour.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
+import { cx } from './cx';
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+/** Keep the card on screen: pin it under the spotlight, or centre it. */
+function cardStyle(rect) {
+    if (!rect || typeof window === 'undefined') {
+        return { position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%, -50%)' };
+    }
+    return {
+        position: 'fixed',
+        top: Math.min(rect.bottom + 12, window.innerHeight - 220),
+        left: Math.max(12, Math.min(rect.left, window.innerWidth - 340)),
+    };
+}
+/**
+ * A click-through guided tour. It walks `steps` one at a time, dimming the page
+ * and spotlighting each step's target element (measured live, so it tracks
+ * scroll and resize), with a card that pins near the target or centres when a
+ * step has none. Portals to the body, traps focus, and closes on Escape — the
+ * same shell as Modal. Purely presentational: the host owns `open` and decides
+ * what a finish or skip does.
+ */
+export function GuidedTour({ open, steps, onClose, onFinish, 'aria-label': ariaLabel = 'Guided tour', labels, className, }) {
+    const [index, setIndex] = useState(0);
+    const [rect, setRect] = useState(null);
+    const cardRef = useRef(null);
+    const current = steps[index];
+    const isLast = index === steps.length - 1;
+    // Start each opening at the first step. Deferred so the effect never sets
+    // state synchronously (the codebase's rule for motion-driven components).
+    useEffect(() => {
+        if (!open)
+            return;
+        const raf = requestAnimationFrame(() => setIndex(0));
+        return () => cancelAnimationFrame(raf);
+    }, [open]);
+    // Measure the current target and keep the spotlight on it through scroll and
+    // resize. Non-target steps (and a closed tour) clear the rect.
+    useEffect(() => {
+        if (!open)
+            return;
+        const target = current?.target;
+        const measure = () => {
+            const el = target ? document.getElementById(target) : null;
+            if (el) {
+                el.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+                setRect(el.getBoundingClientRect());
+            }
+            else {
+                setRect(null);
+            }
+        };
+        const raf = requestAnimationFrame(measure);
+        window.addEventListener('resize', measure);
+        window.addEventListener('scroll', measure, true);
+        return () => {
+            cancelAnimationFrame(raf);
+            window.removeEventListener('resize', measure);
+            window.removeEventListener('scroll', measure, true);
+        };
+    }, [open, current?.target]);
+    // Focus the card on open, restore focus on close, and trap Tab + handle
+    // Escape while it's up.
+    useEffect(() => {
+        if (!open)
+            return;
+        const previouslyFocused = document.activeElement;
+        const raf = requestAnimationFrame(() => cardRef.current?.focus());
+        function handleKey(e) {
+            if (e.key === 'Escape') {
+                onClose();
+                return;
+            }
+            const card = cardRef.current;
+            if (e.key !== 'Tab' || !card)
+                return;
+            const focusables = Array.from(card.querySelectorAll(FOCUSABLE));
+            if (focusables.length === 0) {
+                e.preventDefault();
+                return;
+            }
+            const first = focusables[0];
+            const last = focusables[focusables.length - 1];
+            if (e.shiftKey && document.activeElement === first) {
+                e.preventDefault();
+                last.focus();
+            }
+            else if (!e.shiftKey && document.activeElement === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        }
+        document.addEventListener('keydown', handleKey);
+        return () => {
+            cancelAnimationFrame(raf);
+            document.removeEventListener('keydown', handleKey);
+            previouslyFocused?.focus?.();
+        };
+    }, [open, onClose]);
+    if (!open || !current)
+        return null;
+    const back = () => setIndex((i) => Math.max(0, i - 1));
+    const next = () => {
+        if (isLast) {
+            onFinish?.();
+            onClose();
+        }
+        else {
+            setIndex((i) => i + 1);
+        }
+    };
+    const spotlight = rect
+        ? {
+            top: rect.top - 6,
+            left: rect.left - 6,
+            width: rect.width + 12,
+            height: rect.height + 12,
+        }
+        : undefined;
+    return createPortal(_jsxs("div", { className: "tour", role: "presentation", children: [spotlight ? (_jsx("div", { className: "tour__spotlight", style: spotlight, "aria-hidden": true })) : (_jsx("div", { className: "tour__backdrop", "aria-hidden": true })), _jsxs("div", { ref: cardRef, role: "dialog", "aria-modal": "true", "aria-label": ariaLabel, tabIndex: -1, style: cardStyle(rect), className: cx('tour__card', className), children: [_jsxs("p", { className: "tour__step", children: ["Step ", index + 1, " of ", steps.length] }), _jsx("h2", { className: "tour__title", children: current.title }), _jsx("div", { className: "tour__body", children: current.body }), _jsxs("div", { className: "tour__actions", children: [_jsx("button", { type: "button", className: "tour__skip", onClick: onClose, children: labels?.skip ?? 'Skip' }), index > 0 && (_jsx("button", { type: "button", className: "tour__back", onClick: back, children: labels?.back ?? 'Back' })), _jsx("button", { type: "button", className: "tour__next", onClick: next, children: isLast ? labels?.finish ?? 'Finish' : labels?.next ?? 'Next' })] })] })] }), document.body);
+}

package/dist/index.d.ts

@@ -42,5 +42,6 @@ export { Combobox, type ComboboxOption } from './Combobox';
 export { ToastProvider, useToast, type ToastOptions, type ToastVariant, } from './Toast';
 export { TokenUsageMeter } from './TokenUsageMeter';
 export { VisuallyHidden } from './VisuallyHidden';
+export { GuidedTour, type GuidedTourStep } from './GuidedTour';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';
 export { cx } from './cx';

package/dist/index.js

@@ -42,5 +42,6 @@ export { Combobox } from './Combobox';
 export { ToastProvider, useToast, } from './Toast';
 export { TokenUsageMeter } from './TokenUsageMeter';
 export { VisuallyHidden } from './VisuallyHidden';
+export { GuidedTour } from './GuidedTour';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';
 export { cx } from './cx';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paul-portfolio/react",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "React components for the Paul Design System",
   "license": "MIT",
   "repository": {