@tent-official/react-walkthrough 1.0.0

package/dist/index.mjs

@@ -0,0 +1,651 @@
+import { useRef, useEffect, useCallback, useState } from 'react';
+import { createPortal } from 'react-dom';
+import styled, { keyframes, css } from 'styled-components';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+
+// src/WalkthroughOverlay.js
+var listeners = /* @__PURE__ */ new Set();
+var globalState = {
+  activeTour: null
+};
+var notify = () => {
+  listeners.forEach((fn) => fn({ ...globalState }));
+};
+var setGlobalState = (updater) => {
+  globalState = typeof updater === "function" ? updater(globalState) : { ...globalState, ...updater };
+  notify();
+};
+var useGlobalState = () => {
+  const [state, setState] = useState(globalState);
+  useEffect(() => {
+    const handler = (s) => setState(s);
+    listeners.add(handler);
+    return () => listeners.delete(handler);
+  }, []);
+  return state;
+};
+var getStorageKey = (storageKey) => {
+  return storageKey ? `walkthrough-done:${storageKey}` : "walkthrough-done";
+};
+var getStorageData = (storageKey) => {
+  try {
+    return JSON.parse(localStorage.getItem(getStorageKey(storageKey)) || "{}");
+  } catch (e) {
+    return {};
+  }
+};
+var markDone = (storageKey, name) => {
+  const key = getStorageKey(storageKey);
+  const data = getStorageData(storageKey);
+  data[name] = true;
+  localStorage.setItem(key, JSON.stringify(data));
+  window.dispatchEvent(new Event("walkthrough-done"));
+};
+var isDone = (storageKey, name) => {
+  const data = getStorageData(storageKey);
+  return data[name] === true;
+};
+var isAnyDepDone = (storageKey, deps) => {
+  if (!deps || deps.length === 0) return true;
+  return deps.some((d) => isDone(storageKey, d));
+};
+var resetWalkthrough = ({ storageKey = "", walkthroughList = [] } = {}) => {
+  const key = getStorageKey(storageKey);
+  const data = getStorageData(storageKey);
+  walkthroughList.forEach((n) => {
+    delete data[n];
+  });
+  localStorage.setItem(key, JSON.stringify(data));
+  window.dispatchEvent(new Event("walkthrough-done"));
+};
+var easeOutCubic = (t) => {
+  return 1 - Math.pow(1 - t, 3);
+};
+var lerp = (a, b, t) => {
+  return a + (b - a) * t;
+};
+var popIn = keyframes`
+  from {
+    opacity: 0;
+    transform: translateY(10px) scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+`;
+var fadeSlideIn = keyframes`
+  from {
+    opacity: 0;
+    transform: translateX(12px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+`;
+var OverlayWrapper = styled.div`
+  position: fixed;
+  inset: 0;
+  z-index: 10001;
+  pointer-events: none;
+  width: 100vw;
+  height: 100vh;
+
+  & svg {
+    width: 100%;
+    height: 100%;
+  }
+`;
+var ClickLayer = styled.div`
+  position: fixed;
+  inset: 0;
+  z-index: 10000;
+  cursor: default;
+`;
+var PopoverContainer = styled.div`
+  position: absolute;
+  z-index: 99999;
+  background: #fff;
+  box-shadow:
+    0 12px 40px rgba(0, 0, 0, 0.18),
+    0 2px 10px rgba(0, 0, 0, 0.06);
+  animation: ${popIn} 0.28s cubic-bezier(0.34, 1.56, 0.64, 1);
+`;
+var PopoverBody = styled.div`
+  animation: ${fadeSlideIn} 0.3s ease-out;
+`;
+var PopoverTitle = styled.h3`
+  font-size: 15px;
+  font-weight: 700;
+  color: #1a1a2e;
+  margin: 0 0 10px;
+  line-height: 1.3;
+`;
+var DescriptionScrollArea = styled.div`
+  ${({ $height }) => $height && $height !== "auto" ? css`
+          max-height: ${typeof $height === "number" ? `${$height}px` : $height};
+          overflow-y: auto;
+        ` : ""}
+`;
+var DescriptionBlock = styled.div`
+  display: flex;
+  flex-direction: ${({ $direction = "row" }) => $direction};
+  font-size: 13px;
+  color: #666;
+  line-height: 1.6;
+  margin: 0 0 4px;
+
+  ${({ $direction }) => $direction === "column" ? css`
+          gap: 2px;
+        ` : css`
+          align-items: baseline;
+          gap: 4px;
+        `}
+`;
+var DescriptionTitle = styled.span`
+  font-weight: 600;
+  color: #333;
+  white-space: nowrap;
+`;
+var PopoverFooter = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-top: 16px;
+  gap: 8px;
+`;
+var StepCounter = styled.span`
+  font-size: 13px;
+  font-weight: 600;
+  color: #a1a1aa;
+`;
+var ButtonGroup = styled.div`
+  display: flex;
+  gap: 6px;
+`;
+var Button = styled.button`
+  border: none;
+  border-radius: 8px;
+  padding: 7px 16px;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.15s ease;
+  outline: none;
+
+  ${(p) => p.$variant === "skip" && css`
+      background: ${p.$skipColor || "transparent"};
+      color: ${p.$skipColor ? "#fff" : "#a1a1aa"};
+      &:hover {
+        opacity: 0.8;
+      }
+    `}
+
+  ${(p) => p.$variant === "prev" && css`
+      background: ${p.$prevColor || "#f4f4f5"};
+      color: ${p.$prevColor ? "#fff" : "#3f3f46"};
+      &:hover {
+        opacity: 0.8;
+      }
+    `}
+
+  ${(p) => p.$variant === "next" && css`
+      background: ${p.$nextColor || "#4f46e5"};
+      color: #fff;
+      box-shadow: 0 2px 8px rgba(79, 70, 229, 0.3);
+      &:hover {
+        opacity: 0.9;
+        box-shadow: 0 4px 12px rgba(79, 70, 229, 0.4);
+        transform: translateY(-1px);
+      }
+      &:active {
+        transform: translateY(0);
+      }
+    `}
+`;
+var useWalkthrough = ({
+  name,
+  storageKey = "",
+  dependsOn = [],
+  steps,
+  onWalkthroughComplete,
+  isShowSkip = true,
+  isShowPrev = true,
+  nextLabel = "Next \u2192",
+  prevLabel = "Back",
+  skipLabel = "Skip",
+  doneLabel = "Done \u2713",
+  nextColor,
+  prevColor,
+  skipColor
+}) => {
+  const started = useRef(false);
+  const onCompleteRef = useRef(onWalkthroughComplete);
+  useEffect(() => {
+    onCompleteRef.current = onWalkthroughComplete;
+  }, [onWalkthroughComplete]);
+  const start = useCallback(() => {
+    if (isDone(storageKey, name) || started.current) return;
+    started.current = true;
+    setGlobalState({
+      activeTour: {
+        name,
+        steps,
+        currentStep: 0,
+        storageKey,
+        onWalkthroughComplete: onCompleteRef.current,
+        isShowSkip,
+        isShowPrev,
+        nextLabel,
+        prevLabel,
+        skipLabel,
+        doneLabel,
+        nextColor,
+        prevColor,
+        skipColor
+      }
+    });
+  }, [
+    name,
+    steps,
+    storageKey,
+    isShowSkip,
+    isShowPrev,
+    nextLabel,
+    prevLabel,
+    skipLabel,
+    doneLabel,
+    nextColor,
+    prevColor,
+    skipColor
+  ]);
+  useEffect(() => {
+    const check = () => {
+      if (isDone(storageKey, name)) return;
+      started.current = false;
+      if (isAnyDepDone(storageKey, dependsOn) && !globalState.activeTour) {
+        start();
+      }
+    };
+    check();
+    window.addEventListener("walkthrough-done", check);
+    return () => window.removeEventListener("walkthrough-done", check);
+  }, [name, storageKey, dependsOn, start]);
+  return { start };
+};
+var useAnimatedRect = (step, transitionMs = 350) => {
+  const [displayRect, setDisplayRect] = useState(null);
+  const targetRef = useRef(null);
+  const currentRef = useRef(null);
+  const rafRef = useRef(null);
+  useEffect(() => {
+    if (!step) {
+      setDisplayRect(null);
+      currentRef.current = null;
+      targetRef.current = null;
+      return;
+    }
+    const el = document.getElementById(step.el);
+    if (!el) {
+      setDisplayRect(null);
+      return;
+    }
+    const compute = () => {
+      var _a;
+      const r = el.getBoundingClientRect();
+      const padding = (_a = step.padding) != null ? _a : 8;
+      return {
+        top: r.top - padding + window.scrollY,
+        left: r.left - padding + window.scrollX,
+        width: r.width + padding * 2,
+        height: r.height + padding * 2
+      };
+    };
+    const newTarget = compute();
+    targetRef.current = newTarget;
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    if (!currentRef.current) {
+      currentRef.current = newTarget;
+      setDisplayRect(newTarget);
+      return;
+    }
+    const from = { ...currentRef.current };
+    const to = newTarget;
+    const startTime = performance.now();
+    const tick = (now) => {
+      const elapsed = now - startTime;
+      const progress = Math.min(elapsed / transitionMs, 1);
+      const eased = easeOutCubic(progress);
+      const interpolated = {
+        top: lerp(from.top, to.top, eased),
+        left: lerp(from.left, to.left, eased),
+        width: lerp(from.width, to.width, eased),
+        height: lerp(from.height, to.height, eased)
+      };
+      currentRef.current = interpolated;
+      setDisplayRect(interpolated);
+      if (progress < 1) {
+        rafRef.current = requestAnimationFrame(tick);
+      } else {
+        currentRef.current = to;
+        setDisplayRect(to);
+      }
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    const onLayout = () => {
+      const updated = compute();
+      targetRef.current = updated;
+      currentRef.current = updated;
+      setDisplayRect(updated);
+    };
+    window.addEventListener("resize", onLayout);
+    window.addEventListener("scroll", onLayout, true);
+    return () => {
+      if (rafRef.current) cancelAnimationFrame(rafRef.current);
+      window.removeEventListener("resize", onLayout);
+      window.removeEventListener("scroll", onLayout, true);
+    };
+  }, [step]);
+  return displayRect;
+};
+var clampSize = (value, max) => {
+  if (value === "auto" || value === void 0) return "auto";
+  const num = typeof value === "string" ? parseInt(value, 10) : value;
+  const clamped = Math.min(num, max - 12);
+  return clamped;
+};
+var EDGE_MARGIN = 8;
+var computePopoverPosition = (rect, popoverW, popoverH, gap, preferred) => {
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const clampLeft = (left) => Math.max(EDGE_MARGIN, Math.min(left, vw - popoverW - EDGE_MARGIN));
+  const clampTop = (top) => Math.max(EDGE_MARGIN, Math.min(top, vh - popoverH - EDGE_MARGIN));
+  const positions = {
+    bottom: {
+      top: rect.top + rect.height + gap,
+      left: clampLeft(rect.left)
+    },
+    top: {
+      top: rect.top - popoverH - gap,
+      left: clampLeft(rect.left)
+    },
+    right: {
+      top: clampTop(rect.top),
+      left: rect.left + rect.width + gap
+    },
+    left: {
+      top: clampTop(rect.top),
+      left: rect.left - popoverW - gap
+    }
+  };
+  const fitsInViewport = (pos) => pos.top >= EDGE_MARGIN && pos.left >= EDGE_MARGIN && pos.top + popoverH <= vh - EDGE_MARGIN && pos.left + popoverW <= vw - EDGE_MARGIN;
+  if (preferred && positions[preferred] && fitsInViewport(positions[preferred])) {
+    return positions[preferred];
+  }
+  const order = ["bottom", "top", "right", "left"];
+  for (const dir of order) {
+    if (fitsInViewport(positions[dir])) {
+      return positions[dir];
+    }
+  }
+  const spaceBottom = vh - (rect.top + rect.height + gap);
+  const spaceTop = rect.top - gap;
+  const spaceRight = vw - (rect.left + rect.width + gap);
+  const spaceLeft = rect.left - gap;
+  const best = [
+    { dir: "bottom", space: spaceBottom },
+    { dir: "top", space: spaceTop },
+    { dir: "right", space: spaceRight },
+    { dir: "left", space: spaceLeft }
+  ].sort((a, b) => b.space - a.space)[0].dir;
+  const fallback = positions[best];
+  return {
+    top: Math.max(EDGE_MARGIN, Math.min(fallback.top, vh - popoverH - EDGE_MARGIN)),
+    left: Math.max(EDGE_MARGIN, Math.min(fallback.left, vw - popoverW - EDGE_MARGIN))
+  };
+};
+var WalkthroughOverlay = ({
+  $popoverPadding = 12,
+  $popoverBorderRadius = 8,
+  $popoverGap = 12,
+  $fontFamily,
+  $animationSpeed = 350
+} = {}) => {
+  var _a, _b;
+  const { activeTour } = useGlobalState();
+  const nextBtnRef = useRef(null);
+  const popoverRef = useRef(null);
+  const [popoverPos, setPopoverPos] = useState(null);
+  const [validSteps, setValidSteps] = useState([]);
+  const waitingForElsRef = useRef(false);
+  useEffect(() => {
+    if (!activeTour) {
+      setValidSteps([]);
+      waitingForElsRef.current = false;
+      return;
+    }
+    waitingForElsRef.current = true;
+    const compute = () => activeTour.steps.map((s, i) => ({ ...s, _originalIdx: i })).filter((s) => document.getElementById(s.el));
+    const found = compute();
+    if (found.length > 0) {
+      setValidSteps(found);
+      return;
+    }
+    setValidSteps([]);
+    const observer = new MutationObserver(() => {
+      const updated = compute();
+      if (updated.length > 0) {
+        waitingForElsRef.current = false;
+        setValidSteps(updated);
+        observer.disconnect();
+      }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    return () => {
+      observer.disconnect();
+      waitingForElsRef.current = false;
+    };
+  }, [activeTour]);
+  const currentOriginalIdx = (_a = activeTour == null ? void 0 : activeTour.currentStep) != null ? _a : 0;
+  const currentValidPos = validSteps.findIndex(
+    (s) => s._originalIdx === currentOriginalIdx
+  );
+  const step = currentValidPos !== -1 ? validSteps[currentValidPos] : null;
+  const rect = useAnimatedRect(step, $animationSpeed);
+  const completeTour = useCallback(() => {
+    if (!activeTour) return;
+    const { storageKey: sk, name: n, onWalkthroughComplete: cb } = activeTour;
+    setGlobalState({ activeTour: null });
+    markDone(sk, n);
+    if (cb) cb(n);
+  }, [activeTour]);
+  useEffect(() => {
+    if (!activeTour) return;
+    if (currentValidPos !== -1) return;
+    if (waitingForElsRef.current) return;
+    if (validSteps.length === 0) {
+      completeTour();
+      return;
+    }
+    const nextValid = validSteps.find(
+      (s) => s._originalIdx > currentOriginalIdx
+    );
+    if (nextValid) {
+      setGlobalState((s) => ({
+        ...s,
+        activeTour: { ...s.activeTour, currentStep: nextValid._originalIdx }
+      }));
+    } else {
+      completeTour();
+    }
+  }, [
+    activeTour,
+    currentValidPos,
+    currentOriginalIdx,
+    validSteps,
+    completeTour
+  ]);
+  useEffect(() => {
+    if (!popoverRef.current || !rect || !step) {
+      setPopoverPos(null);
+      return;
+    }
+    const targetEl = document.getElementById(step.el);
+    if (!targetEl) {
+      setPopoverPos(null);
+      return;
+    }
+    const targetRect = targetEl.getBoundingClientRect();
+    const inViewport = targetRect.bottom > 0 && targetRect.top < window.innerHeight && targetRect.right > 0 && targetRect.left < window.innerWidth;
+    if (!inViewport) {
+      setPopoverPos(null);
+      return;
+    }
+    const measured = popoverRef.current.getBoundingClientRect();
+    const pos = computePopoverPosition(
+      rect,
+      measured.width,
+      measured.height,
+      $popoverGap,
+      step.position
+    );
+    setPopoverPos(pos);
+  }, [rect, step, $popoverGap]);
+  useEffect(() => {
+    if (nextBtnRef.current) {
+      nextBtnRef.current.focus();
+    }
+  }, [activeTour == null ? void 0 : activeTour.currentStep, popoverPos]);
+  const [contentKey, setContentKey] = useState(0);
+  const prevStepRef = useRef(null);
+  useEffect(() => {
+    var _a2;
+    const idx = (_a2 = activeTour == null ? void 0 : activeTour.currentStep) != null ? _a2 : null;
+    if (idx !== prevStepRef.current) {
+      setContentKey((k) => k + 1);
+      prevStepRef.current = idx;
+    }
+  }, [activeTour == null ? void 0 : activeTour.currentStep]);
+  if (!activeTour || !step || !rect) return null;
+  const totalSteps = validSteps.length;
+  const isLast = currentValidPos === totalSteps - 1;
+  const borderRadius = (_b = step.borderRadius) != null ? _b : 10;
+  const {
+    isShowSkip = true,
+    isShowPrev = true,
+    nextLabel = "Next \u2192",
+    prevLabel = "Back",
+    skipLabel = "Skip",
+    doneLabel = "Done \u2713",
+    nextColor,
+    prevColor,
+    skipColor
+  } = activeTour;
+  const next = () => {
+    if (step.isTriggerEl) {
+      const el = document.getElementById(step.el);
+      if (el) el.click();
+    }
+    if (isLast) {
+      completeTour();
+    } else {
+      const nextStep = validSteps[currentValidPos + 1];
+      setGlobalState((s) => ({
+        ...s,
+        activeTour: { ...s.activeTour, currentStep: nextStep._originalIdx }
+      }));
+    }
+  };
+  const prev = () => {
+    if (currentValidPos > 0) {
+      const prevStep = validSteps[currentValidPos - 1];
+      setGlobalState((s) => ({
+        ...s,
+        activeTour: { ...s.activeTour, currentStep: prevStep._originalIdx }
+      }));
+    }
+  };
+  const skip = () => {
+    completeTour();
+  };
+  const popoverWidth = clampSize(step.width, window.innerWidth);
+  const popoverHeight = step.height ? clampSize(step.height, window.innerHeight) : void 0;
+  const popoverStyle = {
+    top: popoverPos ? popoverPos.top : -9999,
+    left: popoverPos ? popoverPos.left : -9999,
+    visibility: popoverPos ? "visible" : "hidden",
+    width: popoverWidth,
+    padding: $popoverPadding,
+    borderRadius: $popoverBorderRadius,
+    fontFamily: $fontFamily || '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
+  };
+  const overlay = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(ClickLayer, {}),
+    /* @__PURE__ */ jsx(OverlayWrapper, { children: /* @__PURE__ */ jsxs("svg", { children: [
+      /* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsxs("mask", { id: "wt-mask", children: [
+        /* @__PURE__ */ jsx("rect", { x: "0", y: "0", width: "100%", height: "100%", fill: "white" }),
+        /* @__PURE__ */ jsx(
+          "rect",
+          {
+            x: rect.left,
+            y: rect.top,
+            width: rect.width,
+            height: rect.height,
+            rx: borderRadius,
+            fill: "black"
+          }
+        )
+      ] }) }),
+      /* @__PURE__ */ jsx(
+        "rect",
+        {
+          x: "0",
+          y: "0",
+          width: "100%",
+          height: "100%",
+          fill: "rgba(0,0,0,0.52)",
+          mask: "url(#wt-mask)"
+        }
+      )
+    ] }) }),
+    /* @__PURE__ */ jsxs(PopoverContainer, { ref: popoverRef, style: popoverStyle, children: [
+      /* @__PURE__ */ jsxs(PopoverBody, { children: [
+        step.title && /* @__PURE__ */ jsx(PopoverTitle, { children: step.title }),
+        /* @__PURE__ */ jsx(DescriptionScrollArea, { $height: popoverHeight, children: Array.isArray(step.description) && step.description.map((d, i) => /* @__PURE__ */ jsxs(DescriptionBlock, { $direction: d.direction, children: [
+          d.title && /* @__PURE__ */ jsxs(DescriptionTitle, { children: [
+            d.title,
+            ": "
+          ] }),
+          /* @__PURE__ */ jsx("span", { children: d.description })
+        ] }, i)) })
+      ] }, contentKey),
+      /* @__PURE__ */ jsxs(PopoverFooter, { children: [
+        /* @__PURE__ */ jsxs(StepCounter, { children: [
+          currentValidPos + 1,
+          "/",
+          totalSteps
+        ] }),
+        /* @__PURE__ */ jsxs(ButtonGroup, { children: [
+          isShowSkip && /* @__PURE__ */ jsx(Button, { $variant: "skip", $skipColor: skipColor, onClick: skip, children: skipLabel }),
+          isShowPrev && currentValidPos > 0 && /* @__PURE__ */ jsx(Button, { $variant: "prev", $prevColor: prevColor, onClick: prev, children: prevLabel }),
+          /* @__PURE__ */ jsx(
+            Button,
+            {
+              ref: nextBtnRef,
+              $variant: "next",
+              $nextColor: nextColor,
+              onClick: next,
+              children: isLast ? doneLabel : nextLabel
+            }
+          )
+        ] })
+      ] })
+    ] })
+  ] });
+  return createPortal(overlay, document.body);
+};
+
+export { WalkthroughOverlay, resetWalkthrough, useWalkthrough };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map