@pablo2410/shared-ui 0.19.1 → 0.21.0

package/dist/tour/index.d.ts

@@ -0,0 +1,198 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Shared types for the Opi onboarding tour engine.
+ *
+ * Deliberately minimal for the lightweight ship (2026-09-11): a linear list
+ * of steps, one per granted service, shown as an overlay on the Portal
+ * Service Hub. No cross-origin resume, no setup-task step kind yet — those
+ * belong to the heavier enterprise-setup-concierge track, which is scoped
+ * and content-authored separately before it gets an engine.
+ */
+type TourStepKind = "intro" | "service" | "outro";
+/**
+ * Where a "service"-kind step should highlight a live element on the page,
+ * instead of rendering as a centered modal. Spotlighting is a rendering mode
+ * of a service step, not a distinct step kind — intro/outro never spotlight
+ * anything, and a service step authored without this still renders as the
+ * original centered modal.
+ *
+ * Deliberately same-origin only: the consumer's own DOM must contain an
+ * element carrying `data-tour-target="<selector>"`. A cross-origin tour (a
+ * subdomain spotlighting its own features) mints its own selector values —
+ * this type doesn't know or care which app is consuming it.
+ */
+interface TourSpotlightTarget {
+    /** Matches a `data-tour-target` attribute value in the consumer's DOM. */
+    selector: string;
+    /** Where to place the explanation panel relative to the highlighted
+     *  element. "auto" (default) picks based on available viewport space,
+     *  falling back bottom -> top -> right -> left. */
+    placement?: "top" | "bottom" | "left" | "right" | "auto";
+}
+interface TourStep {
+    /** Stable id — used for progress persistence and analytics, not display. */
+    id: string;
+    kind: TourStepKind;
+    /** Short label shown in the step dots / progress indicator. */
+    label: string;
+    /** Scripted fallback narration — always renders first; an AI narration
+     *  pass (via ai.askOpi) may replace it once it resolves. Never blocks. */
+    fallbackText: string;
+    /** 2-4 bullets shown under the narration. Empty for intro/outro steps.
+     *  Superseded by `features` when both are present — kept for back-compat
+     *  with any step that hasn't been upgraded to the richer shape. */
+    highlights?: string[];
+    /** Named feature call-outs, richer than a flat bullet — rendered instead
+     *  of `highlights` when present. Each `name` is also the natural spotlight
+     *  target label a later in-app tour (inside the service itself) can reuse. */
+    features?: {
+        name: string;
+        detail: string;
+    }[];
+    /** The one action this step offers, if any. */
+    action?: {
+        label: string;
+        /** Absolute URL (cross-origin service) or in-app path. */
+        href: string;
+        external?: boolean;
+    };
+    /** Which catalog service slug this step is about, for narration context / readiness lookups. Absent for intro/outro. */
+    serviceSlug?: string;
+    /** Highlight a live element on the page instead of a centered modal. See
+     *  TourSpotlightTarget's own doc comment. Absent = today's centered modal. */
+    spotlight?: TourSpotlightTarget;
+}
+type TourStatus = "unseen" | "in-progress" | "done" | "dismissed";
+interface TourProgress {
+    status: TourStatus;
+    /** id of the step the user was last on. */
+    lastStepId: string | null;
+    updatedAt: string;
+}
+
+interface TourShellSkin {
+    accent: string;
+    overlayBg: string;
+    panelBg: string;
+    panelBorder: string;
+    mutedText: string;
+    bodyText: string;
+    softText: string;
+}
+interface TourShellProps {
+    step: TourStep;
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    onNext: () => void;
+    onBack: () => void;
+    onDismiss: () => void;
+    /** Narration to render — pass the live AI reply once resolved; while
+     *  pending or on failure, pass `step.fallbackText` so the tour never
+     *  shows a blank state. */
+    narration: string;
+    /** True while an AI narration pass is in flight — shows a subtle pulse, never blocks Next. */
+    narrationPending?: boolean;
+    /** Rendered below the narration/highlights — e.g. a docked OpiAskBar. */
+    children?: ReactNode;
+    skin?: TourShellSkin;
+    /** Orb / avatar mark shown in the header — pass OpiOrb from the consumer. */
+    orb?: ReactNode;
+}
+/**
+ * Full-viewport dismissible overlay with a centered panel. Esc and the
+ * backdrop both dismiss; focus is trapped to the panel while open.
+ */
+declare function TourShell({ step, index, total, isFirst, isLast, onNext, onBack, onDismiss, narration, narrationPending, children, skin, orb, }: TourShellProps): React.JSX.Element;
+
+interface UseTourOptions {
+    /** Called whenever the current step changes (not on initial mount). */
+    onStepChange?: (step: TourStep, index: number) => void;
+    /** Called once when the user reaches the last step and advances past it. */
+    onComplete?: () => void;
+    /** Called when the user dismisses the tour before completion. */
+    onDismiss?: () => void;
+    /** Step id to resume on, if the tour was already in progress. */
+    initialStepId?: string | null;
+}
+interface UseTourResult {
+    step: TourStep;
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    back: () => void;
+    goto: (stepId: string) => void;
+    dismiss: () => void;
+}
+declare function useTour(steps: TourStep[], opts?: UseTourOptions): UseTourResult;
+
+/**
+ * Pure geometry behind the spotlight rendering mode — no React, no DOM
+ * access, just numbers in and numbers out. Factored out so it's testable
+ * without jsdom (this package has none — see tourMachine.ts for the same
+ * split/precedent on the step-index state machine).
+ *
+ * TourShell is the consumer: given a target element's measured rect (from
+ * useSpotlight.ts) and the current viewport size, it needs to know (a) the
+ * four backdrop-frame rectangles that surround the target without ever
+ * covering it, and (b) where to place the explanation panel so it doesn't
+ * overflow the viewport, honoring a preferred placement when there's room.
+ */
+interface Rect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+type Placement = "top" | "bottom" | "left" | "right" | "auto";
+/** The four backdrop segments that frame a target rect without covering it.
+ *  Each is a plain rect in viewport (fixed-position) coordinates. A segment
+ *  with zero width or height (e.g. the target touches a viewport edge) is
+ *  still returned — the caller can skip rendering a degenerate rect, but
+ *  the geometry itself doesn't special-case it. */
+interface SpotlightFrame {
+    top: Rect;
+    bottom: Rect;
+    left: Rect;
+    right: Rect;
+}
+/** Frames `target` within a `viewport` sized 0,0 to width,height. */
+declare function computeSpotlightFrame(target: Rect, viewport: Size): SpotlightFrame;
+type ConcretePlacement = Exclude<Placement, "auto">;
+interface PanelPosition {
+    top: number;
+    left: number;
+    placement: ConcretePlacement;
+}
+/**
+ * Where to place a panel of `panelSize` next to `target`, preferring
+ * `placement` but falling back through the other three sides (then finally
+ * clamping into the viewport) if the preferred side doesn't have room.
+ */
+declare function computePanelPosition(target: Rect, panelSize: Size, viewport: Size, placement?: Placement): PanelPosition;
+
+interface UseSpotlightResult {
+    /** The target's current viewport-relative rect, or null while unresolved. */
+    rect: Rect | null;
+    /** False if no element in the DOM currently carries this selector —
+     *  callers must fall back to the non-spotlight rendering path, never
+     *  throw or render a spotlight around nothing. */
+    found: boolean;
+}
+/**
+ * @param selector The `data-tour-target` attribute value to look for
+ *   (e.g. "service-card-policy-deployment"). Pass `null` to disable
+ *   resolution entirely (e.g. the current step has no spotlight).
+ */
+declare function useSpotlight(selector: string | null): UseSpotlightResult;
+
+export { type PanelPosition, type Placement, type Rect, type Size, type SpotlightFrame, type TourProgress, TourShell, type TourShellProps, type TourShellSkin, type TourSpotlightTarget, type TourStatus, type TourStep, type TourStepKind, type UseSpotlightResult, type UseTourOptions, type UseTourResult, computePanelPosition, computeSpotlightFrame, useSpotlight, useTour };

package/dist/tour/index.js

@@ -0,0 +1,443 @@
+// src/tour/TourShell.tsx
+import { useEffect, useRef } from "react";
+import {
+  X,
+  ChevronLeft,
+  ChevronRight,
+  ArrowRight,
+  ExternalLink
+} from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var defaultSkin = {
+  accent: "#8C34E9",
+  overlayBg: "rgba(10,14,26,0.72)",
+  panelBg: "#0e1624",
+  panelBorder: "1px solid #1e2738",
+  mutedText: "#596475",
+  bodyText: "#c0c6d0",
+  softText: "#8890a0"
+};
+function TourShell({
+  step,
+  index,
+  total,
+  isFirst,
+  isLast,
+  onNext,
+  onBack,
+  onDismiss,
+  narration,
+  narrationPending,
+  children,
+  skin = defaultSkin,
+  orb
+}) {
+  const panelRef = useRef(null);
+  useEffect(() => {
+    const onKeyDown = (e) => {
+      if (e.key === "Escape") onDismiss();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [onDismiss]);
+  useEffect(() => {
+    panelRef.current?.focus();
+  }, [step.id]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: "fixed inset-0 z-50 flex items-center justify-center p-4",
+      style: { background: skin.overlayBg },
+      onClick: (e) => {
+        if (e.target === e.currentTarget) onDismiss();
+      },
+      children: /* @__PURE__ */ jsxs(
+        "div",
+        {
+          ref: panelRef,
+          tabIndex: -1,
+          role: "dialog",
+          "aria-modal": "true",
+          "aria-label": step.label,
+          className: "w-full max-w-md rounded-xl overflow-hidden flex flex-col max-h-[85vh] outline-none",
+          style: { background: skin.panelBg, border: skin.panelBorder },
+          children: [
+            /* @__PURE__ */ jsxs(
+              "div",
+              {
+                className: "flex items-center justify-between gap-3 px-5 py-4 shrink-0",
+                style: {
+                  background: "linear-gradient(135deg, #2a1450 0%, #1a0e33 100%)"
+                },
+                children: [
+                  /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2.5 min-w-0", children: [
+                    orb,
+                    /* @__PURE__ */ jsx("span", { className: "text-sm font-bold text-white truncate", children: step.label })
+                  ] }),
+                  /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      onClick: onDismiss,
+                      className: "p-1 rounded hover:bg-white/10 transition-colors shrink-0",
+                      title: "Skip tour",
+                      children: /* @__PURE__ */ jsx(X, { size: 16, className: "text-white/70" })
+                    }
+                  )
+                ]
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "div",
+              {
+                className: "flex items-center gap-1.5 px-5 py-3 shrink-0",
+                style: { borderBottom: skin.panelBorder },
+                children: Array.from({ length: total }, (_, i) => /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: "h-1.5 rounded-full transition-all",
+                    style: {
+                      width: i === index ? 20 : 8,
+                      background: i === index ? skin.accent : skin.mutedText,
+                      opacity: i === index ? 1 : 0.4
+                    }
+                  },
+                  i
+                ))
+              }
+            ),
+            /* @__PURE__ */ jsxs("div", { className: "overflow-y-auto px-5 py-4 space-y-4", children: [
+              /* @__PURE__ */ jsx(
+                "p",
+                {
+                  className: "text-[13px] leading-relaxed transition-opacity",
+                  style: {
+                    color: skin.bodyText,
+                    opacity: narrationPending ? 0.7 : 1
+                  },
+                  children: narration
+                }
+              ),
+              step.highlights && step.highlights.length > 0 && /* @__PURE__ */ jsx("ul", { className: "space-y-1.5", children: step.highlights.map((h, i) => /* @__PURE__ */ jsxs(
+                "li",
+                {
+                  className: "text-[12.5px] leading-relaxed pl-3 relative",
+                  style: { color: skin.softText },
+                  children: [
+                    /* @__PURE__ */ jsx(
+                      "span",
+                      {
+                        className: "absolute left-0",
+                        style: { color: skin.mutedText },
+                        children: "\u2022"
+                      }
+                    ),
+                    h
+                  ]
+                },
+                i
+              )) }),
+              step.action && /* @__PURE__ */ jsxs(
+                "a",
+                {
+                  href: step.action.href,
+                  target: step.action.external ? "_blank" : void 0,
+                  rel: step.action.external ? "noopener noreferrer" : void 0,
+                  className: "inline-flex items-center gap-1.5 px-3.5 py-2 rounded-lg text-[13px] font-semibold transition-opacity hover:opacity-90",
+                  style: { background: `${skin.accent}20`, color: skin.accent },
+                  children: [
+                    step.action.label,
+                    step.action.external ? /* @__PURE__ */ jsx(ExternalLink, { size: 13 }) : /* @__PURE__ */ jsx(ArrowRight, { size: 13 })
+                  ]
+                }
+              ),
+              children
+            ] }),
+            /* @__PURE__ */ jsxs(
+              "div",
+              {
+                className: "flex items-center justify-between gap-2 px-5 py-3.5 shrink-0",
+                style: { borderTop: skin.panelBorder },
+                children: [
+                  /* @__PURE__ */ jsx(
+                    "button",
+                    {
+                      onClick: onDismiss,
+                      className: "text-[12px] font-medium transition-colors hover:underline",
+                      style: { color: skin.mutedText },
+                      children: "Skip tour"
+                    }
+                  ),
+                  /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+                    !isFirst && /* @__PURE__ */ jsxs(
+                      "button",
+                      {
+                        onClick: onBack,
+                        className: "flex items-center gap-1 px-3 py-1.5 rounded-md text-[12.5px] font-medium transition-colors",
+                        style: { color: skin.bodyText, border: skin.panelBorder },
+                        children: [
+                          /* @__PURE__ */ jsx(ChevronLeft, { size: 13 }),
+                          "Back"
+                        ]
+                      }
+                    ),
+                    /* @__PURE__ */ jsxs(
+                      "button",
+                      {
+                        onClick: onNext,
+                        className: "flex items-center gap-1 px-3.5 py-1.5 rounded-md text-[12.5px] font-bold text-white transition-opacity hover:opacity-90",
+                        style: {
+                          background: "linear-gradient(135deg, #8C34E9 0%, #5B1FA6 100%)"
+                        },
+                        children: [
+                          isLast ? "Done" : "Next",
+                          !isLast && /* @__PURE__ */ jsx(ChevronRight, { size: 13 })
+                        ]
+                      }
+                    )
+                  ] })
+                ]
+              }
+            )
+          ]
+        }
+      )
+    }
+  );
+}
+
+// src/tour/useTour.ts
+import { useCallback, useState } from "react";
+
+// src/tour/tourMachine.ts
+function resolveInitialIndex(steps, initialStepId) {
+  if (!initialStepId) return 0;
+  const found = steps.findIndex((s) => s.id === initialStepId);
+  return found === -1 ? 0 : found;
+}
+function nextIndex(steps, current) {
+  if (current >= steps.length - 1) {
+    return { index: current, completed: true };
+  }
+  return { index: current + 1, completed: false };
+}
+function backIndex(current) {
+  return Math.max(0, current - 1);
+}
+function gotoIndex(steps, stepId, current) {
+  const target = steps.findIndex((s) => s.id === stepId);
+  return target === -1 ? current : target;
+}
+
+// src/tour/useTour.ts
+function useTour(steps, opts = {}) {
+  if (steps.length === 0) {
+    throw new Error("useTour requires at least one step");
+  }
+  const [index, setIndex] = useState(
+    () => resolveInitialIndex(steps, opts.initialStepId)
+  );
+  const next = useCallback(() => {
+    const result = nextIndex(steps, index);
+    if (result.completed) {
+      opts.onComplete?.();
+      return;
+    }
+    setIndex(result.index);
+    opts.onStepChange?.(steps[result.index], result.index);
+  }, [index, steps]);
+  const back = useCallback(() => {
+    const target = backIndex(index);
+    if (target === index) return;
+    setIndex(target);
+    opts.onStepChange?.(steps[target], target);
+  }, [index, steps]);
+  const goto = useCallback(
+    (stepId) => {
+      const target = gotoIndex(steps, stepId, index);
+      if (target === index) return;
+      setIndex(target);
+      opts.onStepChange?.(steps[target], target);
+    },
+    [steps, index]
+  );
+  const dismiss = useCallback(() => {
+    opts.onDismiss?.();
+  }, []);
+  return {
+    step: steps[index],
+    index,
+    total: steps.length,
+    isFirst: index === 0,
+    isLast: index === steps.length - 1,
+    next,
+    back,
+    goto,
+    dismiss
+  };
+}
+
+// src/tour/useSpotlight.ts
+import { useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
+var RESIZE_DEBOUNCE_MS = 100;
+function useSpotlight(selector) {
+  const [rect, setRect] = useState2(null);
+  const [found, setFound] = useState2(false);
+  const scrolledForSelector = useRef2(null);
+  useEffect2(() => {
+    if (!selector) {
+      setRect(null);
+      setFound(false);
+      return;
+    }
+    let resizeTimer;
+    let cancelled = false;
+    const measure = () => {
+      if (cancelled) return;
+      const el = document.querySelector(
+        `[data-tour-target="${selector}"]`
+      );
+      if (!el) {
+        setRect(null);
+        setFound(false);
+        return;
+      }
+      const domRect = el.getBoundingClientRect();
+      setRect({
+        top: domRect.top,
+        left: domRect.left,
+        width: domRect.width,
+        height: domRect.height
+      });
+      setFound(true);
+      if (scrolledForSelector.current !== selector) {
+        scrolledForSelector.current = selector;
+        el.scrollIntoView({ block: "center", behavior: "smooth" });
+      }
+    };
+    measure();
+    const initialFrame = requestAnimationFrame(measure);
+    const onResize = () => {
+      if (resizeTimer) clearTimeout(resizeTimer);
+      resizeTimer = setTimeout(measure, RESIZE_DEBOUNCE_MS);
+    };
+    const onScroll = () => measure();
+    window.addEventListener("resize", onResize);
+    window.addEventListener("scroll", onScroll, { capture: true });
+    const observer = new MutationObserver(measure);
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true
+    });
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(initialFrame);
+      if (resizeTimer) clearTimeout(resizeTimer);
+      window.removeEventListener("resize", onResize);
+      window.removeEventListener("scroll", onScroll, { capture: true });
+      observer?.disconnect();
+    };
+  }, [selector]);
+  return { rect, found };
+}
+
+// src/tour/spotlightMath.ts
+function computeSpotlightFrame(target, viewport) {
+  const targetBottom = target.top + target.height;
+  const targetRight = target.left + target.width;
+  return {
+    // Full-width strip above the target.
+    top: {
+      top: 0,
+      left: 0,
+      width: viewport.width,
+      height: Math.max(0, target.top)
+    },
+    // Full-width strip below the target.
+    bottom: {
+      top: targetBottom,
+      left: 0,
+      width: viewport.width,
+      height: Math.max(0, viewport.height - targetBottom)
+    },
+    // Strip to the left of the target, spanning only the target's own row
+    // (the top/bottom strips already cover the rest of those rows).
+    left: {
+      top: target.top,
+      left: 0,
+      width: Math.max(0, target.left),
+      height: target.height
+    },
+    // Strip to the right of the target, same row-only span as `left`.
+    right: {
+      top: target.top,
+      left: targetRight,
+      width: Math.max(0, viewport.width - targetRight),
+      height: target.height
+    }
+  };
+}
+var FALLBACK_ORDER = {
+  bottom: ["bottom", "top", "right", "left"],
+  top: ["top", "bottom", "right", "left"],
+  right: ["right", "left", "bottom", "top"],
+  left: ["left", "right", "bottom", "top"]
+};
+var AUTO_ORDER = FALLBACK_ORDER.bottom;
+var PANEL_GAP = 12;
+function computePanelPosition(target, panelSize, viewport, placement = "auto") {
+  const order = placement === "auto" ? AUTO_ORDER : FALLBACK_ORDER[placement];
+  for (const candidate of order) {
+    const pos2 = placeAt(candidate, target, panelSize);
+    if (fits(pos2, panelSize, viewport)) {
+      return { ...pos2, placement: candidate };
+    }
+  }
+  const fallback = order[0];
+  const pos = placeAt(fallback, target, panelSize);
+  return {
+    top: clamp(pos.top, 0, Math.max(0, viewport.height - panelSize.height)),
+    left: clamp(pos.left, 0, Math.max(0, viewport.width - panelSize.width)),
+    placement: fallback
+  };
+}
+function placeAt(side, target, panelSize) {
+  const targetCenterX = target.left + target.width / 2;
+  const targetCenterY = target.top + target.height / 2;
+  switch (side) {
+    case "bottom":
+      return {
+        top: target.top + target.height + PANEL_GAP,
+        left: targetCenterX - panelSize.width / 2
+      };
+    case "top":
+      return {
+        top: target.top - panelSize.height - PANEL_GAP,
+        left: targetCenterX - panelSize.width / 2
+      };
+    case "right":
+      return {
+        top: targetCenterY - panelSize.height / 2,
+        left: target.left + target.width + PANEL_GAP
+      };
+    case "left":
+      return {
+        top: targetCenterY - panelSize.height / 2,
+        left: target.left - panelSize.width - PANEL_GAP
+      };
+  }
+}
+function fits(pos, panelSize, viewport) {
+  return pos.top >= 0 && pos.left >= 0 && pos.top + panelSize.height <= viewport.height && pos.left + panelSize.width <= viewport.width;
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+export {
+  TourShell,
+  computePanelPosition,
+  computeSpotlightFrame,
+  useSpotlight,
+  useTour
+};
+//# sourceMappingURL=index.js.map