@korsolutions/guidon 1.0.3 → 1.0.6

package/src/hooks/useGuidonRef.ts

@@ -1,7 +1,7 @@
-import { useCallback, useEffect, useRef, type RefObject } from 'react';
-import { Platform } from 'react-native';
-import { useGuidonStore } from '../store';
-import type { TargetMeasurements, GuidonStore, GuidonStep } from '../types';
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+import { Platform } from "react-native";
+import { useGuidonStore } from "../store";
+import type { TargetMeasurements, GuidonStore, GuidonStep } from "../types";
 
 /**
  * Element type that can be measured
@@ -10,7 +10,7 @@ import type { TargetMeasurements, GuidonStore, GuidonStep } from '../types';
 type MeasurableElement = {
   getBoundingClientRect?: () => DOMRect;
   measureInWindow?: (
-    callback: (x: number, y: number, width: number, height: number) => void
+    callback: (x: number, y: number, width: number, height: number) => void,
   ) => void;
 };
 
@@ -38,21 +38,21 @@ type MeasurableElement = {
  * ```
  */
 export function useGuidonRef<T extends MeasurableElement>(
-  targetId: string
+  targetId: string,
 ): RefObject<T | null> {
   const ref = useRef<T>(null);
   const measurementFrameRef = useRef<number | null>(null);
 
   const registerTarget = useGuidonStore(
-    (state: GuidonStore) => state.registerTarget
+    (state: GuidonStore) => state.registerTarget,
   );
   const unregisterTarget = useGuidonStore(
-    (state: GuidonStore) => state.unregisterTarget
+    (state: GuidonStore) => state.unregisterTarget,
   );
   const isActive = useGuidonStore((state: GuidonStore) => state.isActive);
   const config = useGuidonStore((state: GuidonStore) => state.config);
   const currentStepIndex = useGuidonStore(
-    (state: GuidonStore) => state.currentStepIndex
+    (state: GuidonStore) => state.currentStepIndex,
   );
 
   // Check if this target is needed anywhere in the walkthrough
@@ -67,10 +67,10 @@ export function useGuidonRef<T extends MeasurableElement>(
   const measureElement = useCallback(() => {
     if (!ref.current || !isTargetNeeded) return;
 
-    if (Platform.OS === 'web') {
+    if (Platform.OS === "web") {
       // Web measurement using getBoundingClientRect
       const element = ref.current as unknown as HTMLElement;
-      if (element && typeof element.getBoundingClientRect === 'function') {
+      if (element && typeof element.getBoundingClientRect === "function") {
         const rect = element.getBoundingClientRect();
         const measurements: TargetMeasurements = {
           x: rect.left + window.scrollX,
@@ -84,11 +84,11 @@ export function useGuidonRef<T extends MeasurableElement>(
       // Native measurement using measureInWindow
       const nativeRef = ref.current as unknown as {
         measureInWindow: (
-          cb: (x: number, y: number, w: number, h: number) => void
+          cb: (x: number, y: number, w: number, h: number) => void,
         ) => void;
       };
 
-      if (nativeRef && typeof nativeRef.measureInWindow === 'function') {
+      if (nativeRef && typeof nativeRef.measureInWindow === "function") {
         nativeRef.measureInWindow((x, y, width, height) => {
           if (width > 0 && height > 0) {
             const measurements: TargetMeasurements = { x, y, width, height };
@@ -128,18 +128,18 @@ export function useGuidonRef<T extends MeasurableElement>(
 
   // Web: handle scroll and resize
   useEffect(() => {
-    if (Platform.OS !== 'web' || !isTargetNeeded) return;
+    if (Platform.OS !== "web" || !isTargetNeeded) return;
 
     const handleScrollOrResize = () => {
       measureElement();
     };
 
-    window.addEventListener('scroll', handleScrollOrResize, true);
-    window.addEventListener('resize', handleScrollOrResize);
+    window.addEventListener("scroll", handleScrollOrResize, true);
+    window.addEventListener("resize", handleScrollOrResize);
 
     return () => {
-      window.removeEventListener('scroll', handleScrollOrResize, true);
-      window.removeEventListener('resize', handleScrollOrResize);
+      window.removeEventListener("scroll", handleScrollOrResize, true);
+      window.removeEventListener("resize", handleScrollOrResize);
     };
   }, [isTargetNeeded, measureElement]);
 
@@ -152,3 +152,124 @@ export function useGuidonRef<T extends MeasurableElement>(
 
   return ref;
 }
+
+export function useGuidon() {
+  const register = useGuidonRegister();
+  return { register };
+}
+
+export function useGuidonRegister() {
+  const elementsRef = useRef<Map<string, MeasurableElement>>(new Map());
+  const rafRef = useRef<Map<string, number>>(new Map());
+
+  const registerTarget = useGuidonStore(
+    (state: GuidonStore) => state.registerTarget,
+  );
+  const unregisterTarget = useGuidonStore(
+    (state: GuidonStore) => state.unregisterTarget,
+  );
+  const isActive = useGuidonStore((state) => state.isActive);
+  const config = useGuidonStore((state) => state.config);
+  const currentStepIndex = useGuidonStore((state) => state.currentStepIndex);
+
+  const measure = useCallback(
+    (targetId: string, node: MeasurableElement | null) => {
+      if (!node || !isActive || !config) return;
+
+      const isTargetUsed = config.steps.some(
+        (step) => step.targetId === targetId,
+      );
+
+      if (!isTargetUsed) return;
+
+      if (Platform.OS === "web") {
+        const el = node as unknown as HTMLElement;
+
+        if (!el?.getBoundingClientRect) return;
+
+        const rect = el.getBoundingClientRect();
+
+        registerTarget(targetId, {
+          x: rect.left + window.scrollX,
+          y: rect.top + window.scrollY,
+          width: rect.width,
+          height: rect.height,
+        });
+
+        return;
+      }
+
+      const native = node as unknown as {
+        measureInWindow?: (
+          cb: (x: number, y: number, w: number, h: number) => void,
+        ) => void;
+      };
+
+      native?.measureInWindow?.((x, y, width, height) => {
+        if (width > 0 && height > 0) {
+          registerTarget(targetId, { x, y, width, height });
+        }
+      });
+    },
+    [isActive, config, registerTarget],
+  );
+
+  const register = useCallback(
+    (targetId: string) => {
+      return (node: MeasurableElement | null) => {
+        if (node) {
+          elementsRef.current.set(targetId, node);
+
+          const raf = requestAnimationFrame(() => {
+            measure(targetId, node);
+          });
+
+          rafRef.current.set(targetId, raf);
+          return;
+        }
+        elementsRef.current.delete(targetId);
+        unregisterTarget(targetId);
+
+        const raf = rafRef.current.get(targetId);
+        if (raf) cancelAnimationFrame(raf);
+      };
+    },
+    [measure, unregisterTarget],
+  );
+
+  useEffect(() => {
+    if (!isActive || !config) return;
+
+    const step = config.steps[currentStepIndex];
+    if (!step?.targetId) return;
+
+    const targetId = step.targetId;
+
+    const node = elementsRef.current.get(targetId);
+    if (!node) return;
+
+    requestAnimationFrame(() => {
+      measure(targetId, node);
+    });
+  }, [currentStepIndex, isActive, config, measure]);
+
+  useEffect(() => {
+    if (Platform.OS !== "web" || !isActive) return;
+
+    const handler = () => {
+      elementsRef.current.forEach((node, id) => {
+        measure(id, node);
+      });
+    };
+
+    window.addEventListener("scroll", handler, true);
+    window.addEventListener("resize", handler);
+
+    return () => {
+      window.removeEventListener("scroll", handler, true);
+      window.removeEventListener("resize", handler);
+    };
+  }, [isActive, measure]);
+
+  return register;
+}

package/src/index.ts

@@ -8,7 +8,7 @@ export {
 } from "./components";
 
 // Hooks
-export { useGuidonRef } from "./hooks";
+export { useGuidonRef, useGuidon } from "./hooks";
 
 // Store and API
 export {
@@ -51,7 +51,4 @@ export {
   createCompositeAdapter,
 } from "./persistence/adapters";
 
-export {
-  useGuidonPersistence,
-  useShouldShowGuidon,
-} from "./persistence/hooks";
+export { useGuidonPersistence, useShouldShowGuidon } from "./persistence/hooks";

package/src/store.ts

@@ -1,10 +1,6 @@
 import { create } from "zustand";
 import { useShallow } from "zustand/react/shallow";
-import type {
-  GuidonConfig,
-  GuidonStore,
-  TargetMeasurements,
-} from "./types";
+import type { GuidonConfig, GuidonStore, TargetMeasurements } from "./types";
 
 const initialState = {
   config: null,
@@ -27,8 +23,20 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
 
   start: () => {
     const { config } = get();
-    if (!config || config.steps.length === 0) return;
+    console.log("[Guidon] start() called", {
+      hasConfig: !!config,
+      stepCount: config?.steps.length ?? 0,
+    });
+
+    if (!config || config.steps.length === 0) {
+      console.log("[Guidon] start() early return - no config or no steps");
+      return;
+    }
 
+    console.log(
+      "[Guidon] starting walkthrough with steps:",
+      config.steps.map((s) => s.id),
+    );
     set({ isActive: true, currentStepIndex: 0, isCompleted: false });
 
     // Call onStepEnter for the first step
@@ -41,22 +49,45 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
 
   next: () => {
     const { config, currentStepIndex, isActive } = get();
-    if (!config || !isActive) return;
+    console.log("[Guidon] next() called", {
+      hasConfig: !!config,
+      currentStepIndex,
+      isActive,
+      totalSteps: config?.steps.length ?? 0,
+    });
+
+    if (!config || !isActive) {
+      console.log("[Guidon] next() early return - config or isActive is falsy");
+      return;
+    }
 
     const currentStep = config.steps[currentStepIndex];
+    console.log("[Guidon] current step:", currentStep?.id ?? "undefined");
     currentStep?.onStepExit?.();
 
     if (currentStepIndex < config.steps.length - 1) {
       const nextIndex = currentStepIndex + 1;
       const nextStep = config.steps[nextIndex];
 
+      console.log(
+        "[Guidon] advancing to step",
+        nextIndex,
+        nextStep?.id ?? "undefined",
+      );
       set({ currentStepIndex: nextIndex });
 
       nextStep?.onStepEnter?.();
       if (nextStep) {
+        console.log(
+          "[Guidon] advancing to step",
+          nextIndex,
+          nextStep?.id ?? "undefined",
+        );
+
         config.onStepChange?.(nextIndex, nextStep);
       }
     } else {
+      console.log("[Guidon] last step reached, completing walkthrough");
       // Last step completed
       get().complete();
     }
@@ -278,13 +309,11 @@ export const useGuidonProgress = () =>
       percentage: state.config
         ? ((state.currentStepIndex + 1) / state.config.steps.length) * 100
         : 0,
-    }))
+    })),
   );
 
 export const useTargetMeasurements = (targetId: string) =>
-  useGuidonStore(
-    (state: GuidonStore) => state.targetMeasurements[targetId],
-  );
+  useGuidonStore((state: GuidonStore) => state.targetMeasurements[targetId]);
 
 /**
  * Hook to check if the guidon is waiting for a target element to mount
@@ -308,7 +337,7 @@ export const useWaitingState = () =>
         targetId: hasMeasurements ? null : targetId,
         message: currentStep?.waitingMessage ?? null,
       };
-    })
+    }),
   );
 
 /**