@geomak/ui 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -928,34 +928,87 @@ interface ContextMenuPosition {
 }
 
 interface WizardStep {
-    /** Ref to the DOM element to highlight */
-    stepRef: React$1.RefObject<HTMLElement>;
+    /** Ref to the DOM element to highlight for this step. */
+    stepRef: React$1.RefObject<HTMLElement | null>;
+    /** Tooltip body content. */
     description: React$1.ReactNode;
-    /** 'natural' | 'center' — controls tooltip position relative to target */
-    positioning?: 'natural' | 'center';
+    /**
+     * Tooltip placement relative to the highlighted element.
+     * - `'right'`  (default) — to the right of the highlight
+     * - `'left'`             — to the left of the highlight
+     * - `'top'`              — above the highlight
+     * - `'bottom'`           — below the highlight
+     */
+    placement?: 'right' | 'left' | 'top' | 'bottom';
+    /** Optional heading for the step's tooltip. */
+    title?: React$1.ReactNode;
 }
 interface WizardProps {
+    /** The wrapped subtree — refs in `steps` point into this tree. */
     children: React$1.ReactNode;
+    /** Ordered list of steps to walk the user through. */
     steps: WizardStep[];
-    /** localStorage key used to remember dismissal (default: 'oxygen_wizard') */
-    storageKey?: string;
+    /**
+     * `localStorage` key used to remember dismissal. When the user clicks
+     * "Done" (or "Skip" when dismissible), this key is set so the wizard
+     * won't reopen on subsequent mounts.
+     *
+     * Pass `null` to disable persistence entirely (useful for tests or
+     * tours that should always run).
+     *
+     * Default: `'oxygen.wizard.completed'`.
+     */
+    storageKey?: string | null;
+    /** Show a "Skip tour" button + Esc-to-dismiss. Default `true`. */
+    dismissible?: boolean;
+    /** Called when the user reaches the final step's "Done" button. */
+    onComplete?: () => void;
+    /** Called when the user skips (or presses Esc) before completing. */
+    onSkip?: () => void;
 }
 /**
- * Guided-tour overlay wizard.
+ * Guided-tour overlay that walks the user through a sequence of UI elements.
+ *
+ * Highlights each step's target element with an outlined "spotlight", shows a
+ * tooltip with the description, and provides Prev / Next / Done navigation.
+ * The wrapped tree is rendered unchanged; the overlay sits on top of it via a
+ * portal so it always covers the real viewport regardless of where Wizard
+ * lives in the React tree.
  *
- * Highlights a DOM element via a border, then shows a floating tooltip
- * adjacent to it. Remembers dismissal via localStorage.
+ * **What's improved over the previous version**
+ * - `localStorage` access is SSR-safe and try/catch-guarded (Safari private
+ *   mode, quota exceeded, no-storage browsers all degrade silently).
+ * - No more `classList.add(...)` on consumer-owned DOM. The spotlight is a
+ *   portaled outline rectangle that tracks the target's bbox via
+ *   `ResizeObserver` + scroll/resize listeners. The consumer's DOM is never
+ *   mutated, so unmounting Wizard mid-tour leaves no orphan classes.
+ * - Focus trap inside the tooltip — Tab and Shift+Tab cycle through the
+ *   tooltip's buttons. Esc dismisses (when `dismissible`).
+ * - Backdrop blocks click-through on the rest of the page so the user can't
+ *   stumble into unrelated UI mid-tour. The highlighted target itself stays
+ *   click-blocked too (use the "Next" button to advance).
+ * - Position recalculates on scroll / resize / target size changes via
+ *   `ResizeObserver`.
+ * - All `dark-cornflower-blue` / `prussian-blue` / `bg-white` swapped for
+ *   semantic tokens — both light and dark modes work out of the box.
  *
  * @example
- * const step1Ref = useRef<HTMLDivElement>(null)
- * const steps = [
- *   { stepRef: step1Ref, description: 'Click here to start.', positioning: 'natural' },
- * ]
- * <Wizard steps={steps}>
- *   <div ref={step1Ref}>...</div>
+ * ```tsx
+ * const dashRef = useRef<HTMLDivElement>(null)
+ * const sidebarRef = useRef<HTMLElement>(null)
+ *
+ * <Wizard
+ *   steps={[
+ *     { stepRef: dashRef,    title: 'Dashboard', description: 'Your fleet at a glance.' },
+ *     { stepRef: sidebarRef, title: 'Navigation', description: 'Jump between sections here.', placement: 'right' },
+ *   ]}
+ *   onComplete={() => track('onboarding_complete')}
+ * >
+ *   <Layout dashRef={dashRef} sidebarRef={sidebarRef} />
  * </Wizard>
+ * ```
  */
-declare function Wizard({ children, steps, storageKey }: WizardProps): react_jsx_runtime.JSX.Element;
+declare function Wizard({ children, steps, storageKey, dismissible, onComplete, onSkip, }: WizardProps): react_jsx_runtime.JSX.Element;
 
 /** ─────────────────── types ─────────────────── */
 /**

package/dist/index.d.ts

@@ -928,34 +928,87 @@ interface ContextMenuPosition {
 }
 
 interface WizardStep {
-    /** Ref to the DOM element to highlight */
-    stepRef: React$1.RefObject<HTMLElement>;
+    /** Ref to the DOM element to highlight for this step. */
+    stepRef: React$1.RefObject<HTMLElement | null>;
+    /** Tooltip body content. */
     description: React$1.ReactNode;
-    /** 'natural' | 'center' — controls tooltip position relative to target */
-    positioning?: 'natural' | 'center';
+    /**
+     * Tooltip placement relative to the highlighted element.
+     * - `'right'`  (default) — to the right of the highlight
+     * - `'left'`             — to the left of the highlight
+     * - `'top'`              — above the highlight
+     * - `'bottom'`           — below the highlight
+     */
+    placement?: 'right' | 'left' | 'top' | 'bottom';
+    /** Optional heading for the step's tooltip. */
+    title?: React$1.ReactNode;
 }
 interface WizardProps {
+    /** The wrapped subtree — refs in `steps` point into this tree. */
     children: React$1.ReactNode;
+    /** Ordered list of steps to walk the user through. */
     steps: WizardStep[];
-    /** localStorage key used to remember dismissal (default: 'oxygen_wizard') */
-    storageKey?: string;
+    /**
+     * `localStorage` key used to remember dismissal. When the user clicks
+     * "Done" (or "Skip" when dismissible), this key is set so the wizard
+     * won't reopen on subsequent mounts.
+     *
+     * Pass `null` to disable persistence entirely (useful for tests or
+     * tours that should always run).
+     *
+     * Default: `'oxygen.wizard.completed'`.
+     */
+    storageKey?: string | null;
+    /** Show a "Skip tour" button + Esc-to-dismiss. Default `true`. */
+    dismissible?: boolean;
+    /** Called when the user reaches the final step's "Done" button. */
+    onComplete?: () => void;
+    /** Called when the user skips (or presses Esc) before completing. */
+    onSkip?: () => void;
 }
 /**
- * Guided-tour overlay wizard.
+ * Guided-tour overlay that walks the user through a sequence of UI elements.
+ *
+ * Highlights each step's target element with an outlined "spotlight", shows a
+ * tooltip with the description, and provides Prev / Next / Done navigation.
+ * The wrapped tree is rendered unchanged; the overlay sits on top of it via a
+ * portal so it always covers the real viewport regardless of where Wizard
+ * lives in the React tree.
  *
- * Highlights a DOM element via a border, then shows a floating tooltip
- * adjacent to it. Remembers dismissal via localStorage.
+ * **What's improved over the previous version**
+ * - `localStorage` access is SSR-safe and try/catch-guarded (Safari private
+ *   mode, quota exceeded, no-storage browsers all degrade silently).
+ * - No more `classList.add(...)` on consumer-owned DOM. The spotlight is a
+ *   portaled outline rectangle that tracks the target's bbox via
+ *   `ResizeObserver` + scroll/resize listeners. The consumer's DOM is never
+ *   mutated, so unmounting Wizard mid-tour leaves no orphan classes.
+ * - Focus trap inside the tooltip — Tab and Shift+Tab cycle through the
+ *   tooltip's buttons. Esc dismisses (when `dismissible`).
+ * - Backdrop blocks click-through on the rest of the page so the user can't
+ *   stumble into unrelated UI mid-tour. The highlighted target itself stays
+ *   click-blocked too (use the "Next" button to advance).
+ * - Position recalculates on scroll / resize / target size changes via
+ *   `ResizeObserver`.
+ * - All `dark-cornflower-blue` / `prussian-blue` / `bg-white` swapped for
+ *   semantic tokens — both light and dark modes work out of the box.
  *
  * @example
- * const step1Ref = useRef<HTMLDivElement>(null)
- * const steps = [
- *   { stepRef: step1Ref, description: 'Click here to start.', positioning: 'natural' },
- * ]
- * <Wizard steps={steps}>
- *   <div ref={step1Ref}>...</div>
+ * ```tsx
+ * const dashRef = useRef<HTMLDivElement>(null)
+ * const sidebarRef = useRef<HTMLElement>(null)
+ *
+ * <Wizard
+ *   steps={[
+ *     { stepRef: dashRef,    title: 'Dashboard', description: 'Your fleet at a glance.' },
+ *     { stepRef: sidebarRef, title: 'Navigation', description: 'Jump between sections here.', placement: 'right' },
+ *   ]}
+ *   onComplete={() => track('onboarding_complete')}
+ * >
+ *   <Layout dashRef={dashRef} sidebarRef={sidebarRef} />
  * </Wizard>
+ * ```
  */
-declare function Wizard({ children, steps, storageKey }: WizardProps): react_jsx_runtime.JSX.Element;
+declare function Wizard({ children, steps, storageKey, dismissible, onComplete, onSkip, }: WizardProps): react_jsx_runtime.JSX.Element;
 
 /** ─────────────────── types ─────────────────── */
 /**

package/dist/index.js

@@ -1,7 +1,7 @@
 import { colors_default } from './chunk-GKXP6OJJ.js';
 export { colors_default as COLORS, PALETTE as palette, semanticTokens, vars } from './chunk-GKXP6OJJ.js';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import React8, { createContext, useState, useEffect, useMemo, useContext, useRef, useCallback, useId } from 'react';
+import React8, { createContext, useState, useEffect, useMemo, useContext, useRef, useId, useCallback, useLayoutEffect } from 'react';
 import { createPortal } from 'react-dom';
 import * as Dialog from '@radix-ui/react-dialog';
 import { useReducedMotion, AnimatePresence, motion } from 'framer-motion';
@@ -1432,70 +1432,208 @@ function ContextMenuLabel({ icon, value }) {
 function ChevronRight2() {
   return /* @__PURE__ */ jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, className: "h-4 w-4 flex-shrink-0", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M9 5l7 7-7 7" }) });
 }
-function Wizard({ children, steps, storageKey = "po_wizard" }) {
-  const wizardRef = useRef(null);
-  const [activeStep, setActiveStep] = useState(0);
-  const [targetBbox, setTargetBbox] = useState(null);
-  const HIGHLIGHTED = useMemo(
-    () => ["border", "border-4", "border-prussian-blue", "pointer-events-none"],
-    []
-  );
-  const closeWizard = useCallback(() => {
-    steps[activeStep]?.stepRef.current?.classList.remove(...HIGHLIGHTED);
-    if (wizardRef.current) wizardRef.current.style.display = "none";
-  }, [HIGHLIGHTED, steps, activeStep]);
-  useEffect(() => {
-    const visited = JSON.parse(localStorage.getItem(storageKey) ?? "false");
-    if (visited) {
-      closeWizard();
+function readDismissed(key) {
+  if (key === null) return false;
+  if (typeof window === "undefined") return false;
+  try {
+    return window.localStorage.getItem(key) === "true";
+  } catch {
+    return false;
+  }
+}
+function writeDismissed(key) {
+  if (key === null) return;
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, "true");
+  } catch {
+  }
+}
+function useTargetBbox(ref) {
+  const [bbox, setBbox] = useState(null);
+  useLayoutEffect(() => {
+    const el = ref?.current;
+    if (!el) {
+      setBbox(null);
       return;
     }
-    const el = steps[activeStep]?.stepRef.current;
-    if (el) {
-      setTargetBbox(el.getBoundingClientRect());
-      el.classList.add(...HIGHLIGHTED);
-    }
-  }, [closeWizard, steps, activeStep, HIGHLIGHTED, storageKey]);
-  const onStepChange = () => {
-    if (steps[activeStep + 1]) {
-      steps[activeStep].stepRef.current?.classList.remove(...HIGHLIGHTED);
-      const nextEl = steps[activeStep + 1].stepRef.current;
-      if (nextEl) setTargetBbox(nextEl.getBoundingClientRect());
-      setActiveStep(activeStep + 1);
-    } else {
-      localStorage.setItem(storageKey, "true");
-      closeWizard();
-    }
-  };
-  const step = steps[activeStep];
-  const left = step && targetBbox ? step.positioning === "natural" ? isNaN(targetBbox.width + 20) ? 0 : targetBbox.width + 20 : isNaN(targetBbox.width / 2) ? 0 : targetBbox.width / 2 : "auto";
-  const top = step && targetBbox ? step.positioning === "natural" ? isNaN(targetBbox.y + 10) ? 0 : targetBbox.y + 10 : isNaN(targetBbox.height / 2) ? 0 : targetBbox.height / 2 : "auto";
-  return /* @__PURE__ */ jsxs("div", { className: "h-full p-1 rounded-lg w-full", children: [
-    /* @__PURE__ */ jsx("div", { className: "absolute", ref: wizardRef, children: /* @__PURE__ */ jsxs(
-      "div",
-      {
-        style: { left, top },
-        className: "absolute bg-white rounded-lg p-2 w-[220px] z-50 text-prussian-blue drop-shadow-md transition-all duration-300",
-        children: [
-          step?.description,
-          /* @__PURE__ */ jsxs("div", { className: "flex justify-end", children: [
-            /* @__PURE__ */ jsxs("span", { className: "flex h-3 w-3 relative left-14 top-4", children: [
-              /* @__PURE__ */ jsx("span", { className: "animate-ping absolute inline-flex h-3 w-3 rounded-full bg-dark-cornflower-blue opacity-75" }),
-              /* @__PURE__ */ jsx("span", { className: "relative inline-flex rounded-full h-3 w-3 bg-dark-cornflower-blue" })
-            ] }),
-            /* @__PURE__ */ jsx(
-              Button,
-              {
-                onClick: onStepChange,
-                content: activeStep === steps.length - 1 ? "Close" : "Next",
-                style: { width: 55, padding: "5px 10px", margin: "0" }
-              }
-            )
-          ] })
-        ]
+    const update = () => setBbox(el.getBoundingClientRect());
+    update();
+    window.addEventListener("scroll", update, true);
+    window.addEventListener("resize", update);
+    const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(update) : null;
+    ro?.observe(el);
+    return () => {
+      window.removeEventListener("scroll", update, true);
+      window.removeEventListener("resize", update);
+      ro?.disconnect();
+    };
+  }, [ref]);
+  return bbox;
+}
+var TOOLTIP_WIDTH = 280;
+var TOOLTIP_GAP = 12;
+function tooltipStyleFor(bbox, placement) {
+  const pl = placement ?? "right";
+  if (pl === "right") return { left: bbox.right + TOOLTIP_GAP, top: bbox.top + bbox.height / 2, transform: "translateY(-50%)", width: TOOLTIP_WIDTH };
+  if (pl === "left") return { left: bbox.left - TOOLTIP_WIDTH - TOOLTIP_GAP, top: bbox.top + bbox.height / 2, transform: "translateY(-50%)", width: TOOLTIP_WIDTH };
+  if (pl === "bottom") return { left: bbox.left + bbox.width / 2, top: bbox.bottom + TOOLTIP_GAP, transform: "translateX(-50%)", width: TOOLTIP_WIDTH };
+  return { left: bbox.left + bbox.width / 2, top: bbox.top - TOOLTIP_GAP, transform: "translate(-50%, -100%)", width: TOOLTIP_WIDTH };
+}
+function useFocusTrap(containerRef, active) {
+  useEffect(() => {
+    if (!active) return;
+    const el = containerRef.current;
+    if (!el) return;
+    const t = setTimeout(() => {
+      const first = el.querySelector('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
+      first?.focus();
+    }, 0);
+    const onKey = (e) => {
+      if (e.key !== "Tab") return;
+      const focusables = el.querySelectorAll(
+        'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+      );
+      if (focusables.length === 0) 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", onKey);
+    return () => {
+      clearTimeout(t);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [containerRef, active]);
+}
+function Wizard({
+  children,
+  steps,
+  storageKey = "oxygen.wizard.completed",
+  dismissible = true,
+  onComplete,
+  onSkip
+}) {
+  const tooltipRef = useRef(null);
+  const tooltipTitleId = useId();
+  const tooltipBodyId = useId();
+  const [open, setOpen] = useState(() => steps.length > 0 && !readDismissed(storageKey));
+  const [activeIndex, setActiveIndex] = useState(0);
+  const step = steps[activeIndex];
+  const bbox = useTargetBbox(step?.stepRef);
+  useFocusTrap(tooltipRef, open);
+  useEffect(() => {
+    if (!open || !dismissible) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        handleSkip();
       }
-    ) }),
-    children
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, dismissible]);
+  const handleSkip = useCallback(() => {
+    writeDismissed(storageKey);
+    setOpen(false);
+    onSkip?.();
+  }, [storageKey, onSkip]);
+  const handleComplete = useCallback(() => {
+    writeDismissed(storageKey);
+    setOpen(false);
+    onComplete?.();
+  }, [storageKey, onComplete]);
+  const handleNext = () => {
+    if (activeIndex < steps.length - 1) setActiveIndex((i) => i + 1);
+    else handleComplete();
+  };
+  const handlePrev = () => {
+    if (activeIndex > 0) setActiveIndex((i) => i - 1);
+  };
+  const highlightStyle = bbox ? {
+    left: bbox.left - 4,
+    top: bbox.top - 4,
+    width: bbox.width + 8,
+    height: bbox.height + 8
+  } : { display: "none" };
+  const tooltipStyle = bbox ? tooltipStyleFor(bbox, step?.placement) : { display: "none" };
+  const isLast = activeIndex === steps.length - 1;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    children,
+    open && step && /* @__PURE__ */ jsxs(Portal, { children: [
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: "fixed inset-0 z-[7000000] bg-foreground/40 backdrop-blur-[1px] pointer-events-auto",
+          "aria-hidden": "true"
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: "fixed z-[7000001] pointer-events-none rounded-md ring-2 ring-accent ring-offset-2 ring-offset-background transition-all duration-200",
+          style: highlightStyle,
+          "aria-hidden": "true"
+        }
+      ),
+      /* @__PURE__ */ jsxs(
+        "div",
+        {
+          ref: tooltipRef,
+          role: "dialog",
+          "aria-modal": "true",
+          "aria-labelledby": step.title ? tooltipTitleId : void 0,
+          "aria-describedby": tooltipBodyId,
+          className: "fixed z-[7000002] rounded-lg bg-surface text-foreground border border-border shadow-xl p-4 pointer-events-auto",
+          style: tooltipStyle,
+          children: [
+            step.title && /* @__PURE__ */ jsx("h3", { id: tooltipTitleId, className: "text-sm font-semibold text-foreground mb-1", children: step.title }),
+            /* @__PURE__ */ jsx("div", { id: tooltipBodyId, className: "text-sm text-foreground-secondary leading-relaxed", children: step.description }),
+            /* @__PURE__ */ jsxs("div", { className: "mt-4 flex items-center justify-between", children: [
+              /* @__PURE__ */ jsxs("span", { className: "text-xs text-foreground-muted tabular-nums", children: [
+                activeIndex + 1,
+                " / ",
+                steps.length
+              ] }),
+              /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+                dismissible && !isLast && /* @__PURE__ */ jsx(
+                  Button,
+                  {
+                    variant: "ghost",
+                    size: "sm",
+                    content: "Skip",
+                    onClick: handleSkip
+                  }
+                ),
+                activeIndex > 0 && /* @__PURE__ */ jsx(
+                  Button,
+                  {
+                    variant: "secondary",
+                    size: "sm",
+                    content: "Back",
+                    onClick: handlePrev
+                  }
+                ),
+                /* @__PURE__ */ jsx(
+                  Button,
+                  {
+                    size: "sm",
+                    content: isLast ? "Done" : "Next",
+                    onClick: handleNext
+                  }
+                )
+              ] })
+            ] })
+          ]
+        }
+      )
+    ] })
   ] });
 }
 var SearchInput = React8.forwardRef(function SearchInput2({