@korsolutions/guidon 1.0.0

package/src/persistence/adapters.ts

@@ -0,0 +1,224 @@
+import type { GuidonPersistenceAdapter, GuidonProgress } from '../types';
+
+const STORAGE_KEY_PREFIX = '@guidon:';
+
+/**
+ * No-op adapter that doesn't persist anything
+ * Useful for testing or when persistence is not needed
+ */
+export const createNoopAdapter = (): GuidonPersistenceAdapter => ({
+  loadProgress: async () => null,
+  saveProgress: async () => {},
+  loadAllProgress: async () => ({}),
+  clearProgress: async () => {},
+});
+
+/**
+ * Memory adapter that stores progress in memory
+ * Data is lost when the app is closed
+ */
+export const createMemoryAdapter = (): GuidonPersistenceAdapter => {
+  const store: Record<string, GuidonProgress> = {};
+
+  return {
+    loadProgress: async (guidonId) => store[guidonId] ?? null,
+    saveProgress: async (progress) => {
+      store[progress.guidonId] = progress;
+    },
+    loadAllProgress: async () => ({ ...store }),
+    clearProgress: async (guidonId) => {
+      delete store[guidonId];
+    },
+  };
+};
+
+/**
+ * localStorage adapter for web
+ * Only works in browser environments
+ */
+export const createLocalStorageAdapter = (
+  keyPrefix: string = STORAGE_KEY_PREFIX
+): GuidonPersistenceAdapter => ({
+  loadProgress: async (guidonId) => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+      return null;
+    }
+    try {
+      const data = localStorage.getItem(`${keyPrefix}${guidonId}`);
+      return data ? JSON.parse(data) : null;
+    } catch {
+      return null;
+    }
+  },
+  saveProgress: async (progress) => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+      return;
+    }
+    try {
+      localStorage.setItem(
+        `${keyPrefix}${progress.guidonId}`,
+        JSON.stringify(progress)
+      );
+    } catch {
+      // Silently fail if storage is full
+    }
+  },
+  loadAllProgress: async () => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+      return {};
+    }
+    const result: Record<string, GuidonProgress> = {};
+    try {
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key?.startsWith(keyPrefix)) {
+          const data = localStorage.getItem(key);
+          if (data) {
+            const progress = JSON.parse(data) as GuidonProgress;
+            result[progress.guidonId] = progress;
+          }
+        }
+      }
+    } catch {
+      // Silently fail
+    }
+    return result;
+  },
+  clearProgress: async (guidonId) => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+      return;
+    }
+    try {
+      localStorage.removeItem(`${keyPrefix}${guidonId}`);
+    } catch {
+      // Silently fail
+    }
+  },
+});
+
+/**
+ * AsyncStorage adapter for React Native
+ * Requires @react-native-async-storage/async-storage to be installed
+ *
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * const adapter = createAsyncStorageAdapter(AsyncStorage);
+ */
+export const createAsyncStorageAdapter = (
+  asyncStorage: {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+    getAllKeys: () => Promise<readonly string[]>;
+    multiGet: (keys: readonly string[]) => Promise<readonly [string, string | null][]>;
+  },
+  keyPrefix: string = STORAGE_KEY_PREFIX
+): GuidonPersistenceAdapter => ({
+  loadProgress: async (guidonId) => {
+    try {
+      const data = await asyncStorage.getItem(`${keyPrefix}${guidonId}`);
+      return data ? JSON.parse(data) : null;
+    } catch {
+      return null;
+    }
+  },
+  saveProgress: async (progress) => {
+    try {
+      await asyncStorage.setItem(
+        `${keyPrefix}${progress.guidonId}`,
+        JSON.stringify(progress)
+      );
+    } catch {
+      // Silently fail
+    }
+  },
+  loadAllProgress: async () => {
+    const result: Record<string, GuidonProgress> = {};
+    try {
+      const allKeys = await asyncStorage.getAllKeys();
+      const relevantKeys = allKeys.filter((key) => key.startsWith(keyPrefix));
+      const pairs = await asyncStorage.multiGet(relevantKeys);
+      for (const [, value] of pairs) {
+        if (value) {
+          const progress = JSON.parse(value) as GuidonProgress;
+          result[progress.guidonId] = progress;
+        }
+      }
+    } catch {
+      // Silently fail
+    }
+    return result;
+  },
+  clearProgress: async (guidonId) => {
+    try {
+      await asyncStorage.removeItem(`${keyPrefix}${guidonId}`);
+    } catch {
+      // Silently fail
+    }
+  },
+});
+
+/**
+ * Create a custom API adapter for backend persistence
+ * This is a factory function that creates an adapter based on your API endpoints
+ *
+ * @example
+ * const adapter = createApiAdapter({
+ *   loadProgress: async (guidonId) => {
+ *     const response = await fetch(`/api/guidon/${guidonId}`);
+ *     return response.json();
+ *   },
+ *   saveProgress: async (progress) => {
+ *     await fetch(`/api/guidon/${progress.guidonId}`, {
+ *       method: 'POST',
+ *       body: JSON.stringify(progress),
+ *     });
+ *   },
+ * });
+ */
+export const createApiAdapter = (
+  handlers: Partial<GuidonPersistenceAdapter>
+): GuidonPersistenceAdapter => {
+  const noopAdapter = createNoopAdapter();
+  return {
+    loadProgress: handlers.loadProgress ?? noopAdapter.loadProgress,
+    saveProgress: handlers.saveProgress ?? noopAdapter.saveProgress,
+    loadAllProgress: handlers.loadAllProgress ?? noopAdapter.loadAllProgress,
+    clearProgress: handlers.clearProgress ?? noopAdapter.clearProgress,
+  };
+};
+
+/**
+ * Combine multiple adapters (e.g., save to both local and API)
+ * Loads from the first adapter that returns data
+ * Saves to all adapters
+ */
+export const createCompositeAdapter = (
+  adapters: GuidonPersistenceAdapter[]
+): GuidonPersistenceAdapter => ({
+  loadProgress: async (guidonId) => {
+    for (const adapter of adapters) {
+      const progress = await adapter.loadProgress(guidonId);
+      if (progress) return progress;
+    }
+    return null;
+  },
+  saveProgress: async (progress) => {
+    await Promise.all(adapters.map((adapter) => adapter.saveProgress(progress)));
+  },
+  loadAllProgress: async () => {
+    const result: Record<string, GuidonProgress> = {};
+    for (const adapter of adapters) {
+      if (adapter.loadAllProgress) {
+        const data = await adapter.loadAllProgress();
+        Object.assign(result, data);
+      }
+    }
+    return result;
+  },
+  clearProgress: async (guidonId) => {
+    await Promise.all(
+      adapters.map((adapter) => adapter.clearProgress?.(guidonId))
+    );
+  },
+});

package/src/persistence/hooks.ts

@@ -0,0 +1,179 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { GuidonPersistenceAdapter, GuidonProgress } from '../types';
+
+/**
+ * Hook to manage guidon's walkthrough progress with a persistence adapter
+ */
+export function useGuidonPersistence(
+  adapter: GuidonPersistenceAdapter | undefined,
+  guidonId: string
+) {
+  const [progress, setProgress] = useState<GuidonProgress | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Load progress on mount
+  useEffect(() => {
+    if (!adapter) {
+      setIsLoading(false);
+      return;
+    }
+
+    let mounted = true;
+
+    const loadProgress = async () => {
+      try {
+        setIsLoading(true);
+        setError(null);
+        const data = await adapter.loadProgress(guidonId);
+        if (mounted) {
+          setProgress(data);
+        }
+      } catch (err) {
+        if (mounted) {
+          setError(err instanceof Error ? err.message : 'Failed to load progress');
+        }
+      } finally {
+        if (mounted) {
+          setIsLoading(false);
+        }
+      }
+    };
+
+    loadProgress();
+
+    return () => {
+      mounted = false;
+    };
+  }, [adapter, guidonId]);
+
+  const saveProgress = useCallback(
+    async (newProgress: Omit<GuidonProgress, 'guidonId'>) => {
+      if (!adapter) return;
+
+      const fullProgress: GuidonProgress = {
+        ...newProgress,
+        guidonId,
+      };
+
+      try {
+        setError(null);
+        await adapter.saveProgress(fullProgress);
+        setProgress(fullProgress);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to save progress');
+        throw err;
+      }
+    },
+    [adapter, guidonId]
+  );
+
+  const clearProgress = useCallback(async () => {
+    if (!adapter?.clearProgress) return;
+
+    try {
+      setError(null);
+      await adapter.clearProgress(guidonId);
+      setProgress(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to clear progress');
+      throw err;
+    }
+  }, [adapter, guidonId]);
+
+  const markCompleted = useCallback(async () => {
+    const currentCount = progress?.completionCount ?? 0;
+    await saveProgress({
+      completed: true,
+      completedAt: new Date().toISOString(),
+      completionCount: currentCount + 1,
+    });
+  }, [saveProgress, progress?.completionCount]);
+
+  const markStepViewed = useCallback(
+    async (stepIndex: number) => {
+      await saveProgress({
+        completed: progress?.completed ?? false,
+        lastStepIndex: stepIndex,
+        completedAt: progress?.completedAt,
+        completionCount: progress?.completionCount,
+      });
+    },
+    [saveProgress, progress]
+  );
+
+  return {
+    progress,
+    isLoading,
+    error,
+    isCompleted: progress?.completed ?? false,
+    hasStarted: progress !== null,
+    saveProgress,
+    clearProgress,
+    markCompleted,
+    markStepViewed,
+  };
+}
+
+/**
+ * Hook to check if a guidon should be shown
+ */
+export function useShouldShowGuidon(
+  adapter: GuidonPersistenceAdapter | undefined,
+  guidonId: string,
+  options?: {
+    /** Show even if completed (for replay) */
+    forceShow?: boolean;
+    /** Additional condition to check */
+    additionalCondition?: () => boolean | Promise<boolean>;
+  }
+) {
+  const { progress, isLoading } = useGuidonPersistence(adapter, guidonId);
+  const [shouldShow, setShouldShow] = useState(false);
+  const [isChecking, setIsChecking] = useState(true);
+
+  useEffect(() => {
+    if (isLoading) return;
+
+    const checkCondition = async () => {
+      setIsChecking(true);
+
+      // If forceShow is true, always show
+      if (options?.forceShow) {
+        setShouldShow(true);
+        setIsChecking(false);
+        return;
+      }
+
+      // If already completed, don't show
+      if (progress?.completed) {
+        setShouldShow(false);
+        setIsChecking(false);
+        return;
+      }
+
+      // Check additional condition if provided
+      if (options?.additionalCondition) {
+        try {
+          const result = await options.additionalCondition();
+          setShouldShow(result);
+        } catch {
+          setShouldShow(true); // Default to showing on error
+        }
+      } else {
+        // Default: show if not completed
+        setShouldShow(true);
+      }
+
+      setIsChecking(false);
+    };
+
+    checkCondition();
+  }, [isLoading, progress?.completed, options?.forceShow, options?.additionalCondition]);
+
+  return {
+    shouldShow,
+    isChecking: isLoading || isChecking,
+    isCompleted: progress?.completed ?? false,
+  };
+}

package/src/persistence/index.ts

@@ -0,0 +1,2 @@
+export * from './adapters';
+export * from './hooks';

package/src/store.ts

@@ -0,0 +1,268 @@
+import { create } from "zustand";
+import type {
+  GuidonConfig,
+  GuidonStore,
+  TargetMeasurements,
+} from "./types";
+
+const initialState = {
+  config: null,
+  isActive: false,
+  currentStepIndex: 0,
+  isCompleted: false,
+  targetMeasurements: {},
+  isLoading: false,
+  error: null,
+};
+
+export const useGuidonStore = create<GuidonStore>((set, get) => ({
+  ...initialState,
+
+  configure: (config: GuidonConfig) => {
+    set({ config, currentStepIndex: 0, isCompleted: false });
+  },
+
+  start: () => {
+    const { config } = get();
+    if (!config || config.steps.length === 0) return;
+
+    set({ isActive: true, currentStepIndex: 0, isCompleted: false });
+
+    // Call onStepEnter for the first step
+    const firstStep = config.steps[0];
+    firstStep.onStepEnter?.();
+    config.onStepChange?.(0, firstStep);
+  },
+
+  next: () => {
+    const { config, currentStepIndex, isActive } = get();
+    if (!config || !isActive) return;
+
+    const currentStep = config.steps[currentStepIndex];
+    currentStep?.onStepExit?.();
+
+    if (currentStepIndex < config.steps.length - 1) {
+      const nextIndex = currentStepIndex + 1;
+      const nextStep = config.steps[nextIndex];
+
+      set({ currentStepIndex: nextIndex });
+
+      nextStep.onStepEnter?.();
+      config.onStepChange?.(nextIndex, nextStep);
+    } else {
+      // Last step completed
+      get().complete();
+    }
+  },
+
+  previous: () => {
+    const { config, currentStepIndex, isActive } = get();
+    if (!config || !isActive || currentStepIndex === 0) return;
+
+    const currentStep = config.steps[currentStepIndex];
+    currentStep?.onStepExit?.();
+
+    const prevIndex = currentStepIndex - 1;
+    const prevStep = config.steps[prevIndex];
+
+    set({ currentStepIndex: prevIndex });
+
+    prevStep.onStepEnter?.();
+    config.onStepChange?.(prevIndex, prevStep);
+  },
+
+  goToStep: (index: number) => {
+    const { config, currentStepIndex, isActive } = get();
+    if (!config || !isActive) return;
+    if (index < 0 || index >= config.steps.length) return;
+
+    const currentStep = config.steps[currentStepIndex];
+    currentStep?.onStepExit?.();
+
+    const targetStep = config.steps[index];
+
+    set({ currentStepIndex: index });
+
+    targetStep.onStepEnter?.();
+    config.onStepChange?.(index, targetStep);
+  },
+
+  skip: () => {
+    const { config, currentStepIndex } = get();
+    if (!config) return;
+
+    const currentStep = config.steps[currentStepIndex];
+    currentStep?.onStepExit?.();
+
+    set({ isActive: false, isCompleted: false });
+    config.onSkip?.();
+  },
+
+  complete: () => {
+    const { config, currentStepIndex } = get();
+    if (!config) return;
+
+    const currentStep = config.steps[currentStepIndex];
+    currentStep?.onStepExit?.();
+
+    set({ isActive: false, isCompleted: true });
+    config.onComplete?.();
+  },
+
+  reset: () => {
+    set(initialState);
+  },
+
+  registerTarget: (targetId: string, measurements: TargetMeasurements) => {
+    set((state: GuidonStore) => ({
+      targetMeasurements: {
+        ...state.targetMeasurements,
+        [targetId]: measurements,
+      },
+    }));
+  },
+
+  unregisterTarget: (targetId: string) => {
+    set((state: GuidonStore) => {
+      const { [targetId]: _, ...rest } = state.targetMeasurements;
+      return { targetMeasurements: rest };
+    });
+  },
+
+  setLoading: (isLoading: boolean) => {
+    set({ isLoading });
+  },
+
+  setError: (error: string | null) => {
+    set({ error });
+  },
+}));
+
+/**
+ * Guidon API for external control
+ * Can be used outside of React components
+ */
+export const Guidon = {
+  /**
+   * Configure the walkthrough with steps and options
+   */
+  configure: (config: GuidonConfig) => {
+    useGuidonStore.getState().configure(config);
+  },
+
+  /**
+   * Start the walkthrough
+   */
+  start: () => {
+    useGuidonStore.getState().start();
+  },
+
+  /**
+   * Go to the next step
+   */
+  next: () => {
+    useGuidonStore.getState().next();
+  },
+
+  /**
+   * Go to the previous step
+   */
+  previous: () => {
+    useGuidonStore.getState().previous();
+  },
+
+  /**
+   * Go to a specific step by index
+   */
+  goToStep: (index: number) => {
+    useGuidonStore.getState().goToStep(index);
+  },
+
+  /**
+   * Skip the walkthrough
+   */
+  skip: () => {
+    useGuidonStore.getState().skip();
+  },
+
+  /**
+   * Complete the walkthrough
+   */
+  complete: () => {
+    useGuidonStore.getState().complete();
+  },
+
+  /**
+   * Reset the walkthrough to initial state
+   */
+  reset: () => {
+    useGuidonStore.getState().reset();
+  },
+
+  /**
+   * Check if the walkthrough is currently active
+   */
+  isActive: () => {
+    return useGuidonStore.getState().isActive;
+  },
+
+  /**
+   * Check if the walkthrough has been completed
+   */
+  isCompleted: () => {
+    return useGuidonStore.getState().isCompleted;
+  },
+
+  /**
+   * Get the current step index
+   */
+  getCurrentStepIndex: () => {
+    return useGuidonStore.getState().currentStepIndex;
+  },
+
+  /**
+   * Get the current step
+   */
+  getCurrentStep: () => {
+    const state = useGuidonStore.getState();
+    return state.config?.steps[state.currentStepIndex] ?? null;
+  },
+
+  /**
+   * Get all steps
+   */
+  getSteps: () => {
+    return useGuidonStore.getState().config?.steps ?? [];
+  },
+
+  /**
+   * Subscribe to store changes
+   */
+  subscribe: useGuidonStore.subscribe,
+};
+
+/**
+ * Hook selectors for common use cases
+ */
+export const useGuidonActive = () =>
+  useGuidonStore((state: GuidonStore) => state.isActive);
+
+export const useGuidonStep = () =>
+  useGuidonStore((state: GuidonStore) => {
+    if (!state.config || !state.isActive) return null;
+    return state.config.steps[state.currentStepIndex];
+  });
+
+export const useGuidonProgress = () =>
+  useGuidonStore((state: GuidonStore) => ({
+    currentStep: state.currentStepIndex + 1,
+    totalSteps: state.config?.steps.length ?? 0,
+    percentage: state.config
+      ? ((state.currentStepIndex + 1) / state.config.steps.length) * 100
+      : 0,
+  }));
+
+export const useTargetMeasurements = (targetId: string) =>
+  useGuidonStore(
+    (state: GuidonStore) => state.targetMeasurements[targetId],
+  );