@paul-portfolio/react 0.6.0 → 0.8.0

package/dist/GuidedTour.d.ts

@@ -0,0 +1,43 @@
+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;
+    /**
+     * Run when this step becomes active — switch a tab, scroll a panel into view,
+     * anything the step needs set up before its target is measured. Fired from the
+     * navigation handler, so a tab switch has rendered before the spotlight reads
+     * the target's box.
+     */
+    onEnter?: () => void;
+};
+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,136 @@
+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]);
+    // Fire the first step's onEnter as the tour opens (later steps fire from the
+    // navigation handler). Runs the consumer's callback, never this component's
+    // own setState, so it's clear of the set-state-in-effect rule.
+    useEffect(() => {
+        if (open)
+            steps[0]?.onEnter?.();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [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 go = (target) => {
+        const clamped = Math.max(0, Math.min(steps.length - 1, target));
+        steps[clamped]?.onEnter?.();
+        setIndex(clamped);
+    };
+    const back = () => go(index - 1);
+    const next = () => {
+        if (isLast) {
+            onFinish?.();
+            onClose();
+        }
+        else {
+            go(index + 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/Modal.js

@@ -15,28 +15,54 @@ const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), selec
 export function Modal({ open, onClose, title, className, children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-describedby': ariaDescribedby, }) {
     const titleId = useId();
     const dialogRef = useRef(null);
-    // Move focus into the dialog on open and restore it on close, and trap Tab
-    // so keyboard focus can't wander behind the modal.
+    // Read the latest onClose from a ref so the keydown listener below never has
+    // to be torn down and re-added when onClose changes identity.
+    const onCloseRef = useRef(onClose);
+    useEffect(() => {
+        onCloseRef.current = onClose;
+    }, [onClose]);
+    // On open: focus into the dialog, trap Tab, lock body scroll, and hide the
+    // rest of the page from assistive tech. All of it is undone on close. The
+    // effect depends only on `open` — never on onClose — so a parent re-render
+    // (e.g. a polling query) can't re-run it and steal focus from an input.
     useEffect(() => {
         if (!open)
             return;
         const previouslyFocused = document.activeElement;
         const dialog = dialogRef.current;
-        dialog?.focus();
+        // Lock body scroll, padding out the scrollbar's width so the page behind
+        // doesn't shift as it disappears.
+        const originalOverflow = document.body.style.overflow;
+        const originalPaddingRight = document.body.style.paddingRight;
+        const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+        document.body.style.overflow = 'hidden';
+        if (scrollbarWidth > 0) {
+            document.body.style.paddingRight = `${scrollbarWidth}px`;
+        }
+        // Hide the background from assistive tech, without clobbering an
+        // aria-hidden that was already there.
+        const hidden = Array.from(document.body.children).filter((el) => el !== dialog && !el.contains(dialog) && !el.hasAttribute('aria-hidden'));
+        for (const el of hidden)
+            el.setAttribute('aria-hidden', 'true');
+        // Focus the first focusable element, or the dialog itself if it has none.
+        const focusables = dialog
+            ? Array.from(dialog.querySelectorAll(FOCUSABLE))
+            : [];
+        (focusables[0] ?? dialog)?.focus();
         function handleKey(e) {
             if (e.key === 'Escape') {
-                onClose();
+                onCloseRef.current();
                 return;
             }
             if (e.key !== 'Tab' || !dialog)
                 return;
-            const focusables = Array.from(dialog.querySelectorAll(FOCUSABLE));
-            if (focusables.length === 0) {
+            const tabbable = Array.from(dialog.querySelectorAll(FOCUSABLE));
+            if (tabbable.length === 0) {
                 e.preventDefault();
                 return;
             }
-            const first = focusables[0];
-            const last = focusables[focusables.length - 1];
+            const first = tabbable[0];
+            const last = tabbable[tabbable.length - 1];
             if (e.shiftKey && document.activeElement === first) {
                 e.preventDefault();
                 last.focus();
@@ -49,9 +75,13 @@ export function Modal({ open, onClose, title, className, children, 'aria-label':
         document.addEventListener('keydown', handleKey);
         return () => {
             document.removeEventListener('keydown', handleKey);
+            document.body.style.overflow = originalOverflow;
+            document.body.style.paddingRight = originalPaddingRight;
+            for (const el of hidden)
+                el.removeAttribute('aria-hidden');
             previouslyFocused?.focus?.();
         };
-    }, [open, onClose]);
+    }, [open]);
     if (!open)
         return null;
     const labelledby = ariaLabelledby ?? (title ? titleId : undefined);

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.8.0",
   "description": "React components for the Paul Design System",
   "license": "MIT",
   "repository": {