@paul-portfolio/react 0.7.0 → 0.8.1

package/dist/GuidedTour.d.ts

@@ -4,6 +4,13 @@ export type GuidedTourStep = {
     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;

package/dist/GuidedTour.js

@@ -36,6 +36,14 @@ export function GuidedTour({ open, steps, onClose, onFinish, 'aria-label': ariaL
         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(() => {
@@ -99,16 +107,24 @@ export function GuidedTour({ open, steps, onClose, onFinish, 'aria-label': ariaL
             previouslyFocused?.focus?.();
         };
     }, [open, onClose]);
-    if (!open || !current)
+    // No document on the server, and the overlay portals to it — render nothing
+    // there rather than reaching createPortal(document.body). A host that opens
+    // the tour during SSR then gets a clean no-op instead of a crash.
+    if (!open || !current || typeof document === 'undefined')
         return null;
-    const back = () => setIndex((i) => Math.max(0, i - 1));
+    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 {
-            setIndex((i) => i + 1);
+            go(index + 1);
         }
     };
     const spotlight = rect

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/package.json

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