@korsolutions/guidon 1.0.0 → 1.0.2

package/dist/commonjs/index.js

@@ -0,0 +1,143 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "Guidon", {
+  enumerable: true,
+  get: function () {
+    return _store.Guidon;
+  }
+});
+Object.defineProperty(exports, "GuidonOverlay", {
+  enumerable: true,
+  get: function () {
+    return _index.GuidonOverlay;
+  }
+});
+Object.defineProperty(exports, "GuidonProvider", {
+  enumerable: true,
+  get: function () {
+    return _index.GuidonProvider;
+  }
+});
+Object.defineProperty(exports, "GuidonTarget", {
+  enumerable: true,
+  get: function () {
+    return _index.GuidonTarget;
+  }
+});
+Object.defineProperty(exports, "GuidonTooltip", {
+  enumerable: true,
+  get: function () {
+    return _index.GuidonTooltip;
+  }
+});
+Object.defineProperty(exports, "createApiAdapter", {
+  enumerable: true,
+  get: function () {
+    return _adapters.createApiAdapter;
+  }
+});
+Object.defineProperty(exports, "createAsyncStorageAdapter", {
+  enumerable: true,
+  get: function () {
+    return _adapters.createAsyncStorageAdapter;
+  }
+});
+Object.defineProperty(exports, "createCompositeAdapter", {
+  enumerable: true,
+  get: function () {
+    return _adapters.createCompositeAdapter;
+  }
+});
+Object.defineProperty(exports, "createLocalStorageAdapter", {
+  enumerable: true,
+  get: function () {
+    return _adapters.createLocalStorageAdapter;
+  }
+});
+Object.defineProperty(exports, "createMemoryAdapter", {
+  enumerable: true,
+  get: function () {
+    return _adapters.createMemoryAdapter;
+  }
+});
+Object.defineProperty(exports, "createNoopAdapter", {
+  enumerable: true,
+  get: function () {
+    return _adapters.createNoopAdapter;
+  }
+});
+Object.defineProperty(exports, "useGuidonActive", {
+  enumerable: true,
+  get: function () {
+    return _store.useGuidonActive;
+  }
+});
+Object.defineProperty(exports, "useGuidonContext", {
+  enumerable: true,
+  get: function () {
+    return _index.useGuidonContext;
+  }
+});
+Object.defineProperty(exports, "useGuidonPersistence", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useGuidonPersistence;
+  }
+});
+Object.defineProperty(exports, "useGuidonProgress", {
+  enumerable: true,
+  get: function () {
+    return _store.useGuidonProgress;
+  }
+});
+Object.defineProperty(exports, "useGuidonRef", {
+  enumerable: true,
+  get: function () {
+    return _index2.useGuidonRef;
+  }
+});
+Object.defineProperty(exports, "useGuidonStep", {
+  enumerable: true,
+  get: function () {
+    return _store.useGuidonStep;
+  }
+});
+Object.defineProperty(exports, "useGuidonStore", {
+  enumerable: true,
+  get: function () {
+    return _store.useGuidonStore;
+  }
+});
+Object.defineProperty(exports, "useIsFloatingStep", {
+  enumerable: true,
+  get: function () {
+    return _store.useIsFloatingStep;
+  }
+});
+Object.defineProperty(exports, "useShouldShowGuidon", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useShouldShowGuidon;
+  }
+});
+Object.defineProperty(exports, "useTargetMeasurements", {
+  enumerable: true,
+  get: function () {
+    return _store.useTargetMeasurements;
+  }
+});
+Object.defineProperty(exports, "useWaitingState", {
+  enumerable: true,
+  get: function () {
+    return _store.useWaitingState;
+  }
+});
+var _index = require("./components/index.js");
+var _index2 = require("./hooks/index.js");
+var _store = require("./store.js");
+var _adapters = require("./persistence/adapters.js");
+var _hooks = require("./persistence/hooks.js");
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_index","require","_index2","_store","_adapters","_hooks"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,IAAAA,MAAA,GAAAC,OAAA;AASA,IAAAC,OAAA,GAAAD,OAAA;AAGA,IAAAE,MAAA,GAAAF,OAAA;AA+BA,IAAAG,SAAA,GAAAH,OAAA;AASA,IAAAI,MAAA,GAAAJ,OAAA","ignoreList":[]}

package/dist/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/commonjs/persistence/adapters.js

@@ -0,0 +1,213 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createNoopAdapter = exports.createMemoryAdapter = exports.createLocalStorageAdapter = exports.createCompositeAdapter = exports.createAsyncStorageAdapter = exports.createApiAdapter = void 0;
+const STORAGE_KEY_PREFIX = '@guidon:';
+
+/**
+ * No-op adapter that doesn't persist anything
+ * Useful for testing or when persistence is not needed
+ */
+const createNoopAdapter = () => ({
+  loadProgress: async () => null,
+  saveProgress: async () => {},
+  loadAllProgress: async () => ({}),
+  clearProgress: async () => {}
+});
+
+/**
+ * Memory adapter that stores progress in memory
+ * Data is lost when the app is closed
+ */
+exports.createNoopAdapter = createNoopAdapter;
+const createMemoryAdapter = () => {
+  const store = {};
+  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
+ */
+exports.createMemoryAdapter = createMemoryAdapter;
+const createLocalStorageAdapter = (keyPrefix = STORAGE_KEY_PREFIX) => ({
+  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 = {};
+    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);
+            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);
+ */
+exports.createLocalStorageAdapter = createLocalStorageAdapter;
+const createAsyncStorageAdapter = (asyncStorage, keyPrefix = STORAGE_KEY_PREFIX) => ({
+  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 = {};
+    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);
+          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),
+ *     });
+ *   },
+ * });
+ */
+exports.createAsyncStorageAdapter = createAsyncStorageAdapter;
+const createApiAdapter = handlers => {
+  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
+ */
+exports.createApiAdapter = createApiAdapter;
+const createCompositeAdapter = adapters => ({
+  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 = {};
+    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)));
+  }
+});
+exports.createCompositeAdapter = createCompositeAdapter;
+//# sourceMappingURL=adapters.js.map

package/dist/commonjs/persistence/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["STORAGE_KEY_PREFIX","createNoopAdapter","loadProgress","saveProgress","loadAllProgress","clearProgress","exports","createMemoryAdapter","store","guidonId","progress","createLocalStorageAdapter","keyPrefix","window","localStorage","data","getItem","JSON","parse","setItem","stringify","result","i","length","key","startsWith","removeItem","createAsyncStorageAdapter","asyncStorage","allKeys","getAllKeys","relevantKeys","filter","pairs","multiGet","value","createApiAdapter","handlers","noopAdapter","createCompositeAdapter","adapters","adapter","Promise","all","map","Object","assign"],"sourceRoot":"../../../src","sources":["persistence/adapters.ts"],"mappings":"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","ignoreList":[]}

package/dist/commonjs/persistence/hooks.js

@@ -0,0 +1,153 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useGuidonPersistence = useGuidonPersistence;
+exports.useShouldShowGuidon = useShouldShowGuidon;
+var _react = require("react");
+/**
+ * Hook to manage guidon's walkthrough progress with a persistence adapter
+ */
+function useGuidonPersistence(adapter, guidonId) {
+  const [progress, setProgress] = (0, _react.useState)(null);
+  const [isLoading, setIsLoading] = (0, _react.useState)(true);
+  const [error, setError] = (0, _react.useState)(null);
+
+  // Load progress on mount
+  (0, _react.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 = (0, _react.useCallback)(async newProgress => {
+    if (!adapter) return;
+    const fullProgress = {
+      ...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 = (0, _react.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 = (0, _react.useCallback)(async () => {
+    const currentCount = progress?.completionCount ?? 0;
+    await saveProgress({
+      completed: true,
+      completedAt: new Date().toISOString(),
+      completionCount: currentCount + 1
+    });
+  }, [saveProgress, progress?.completionCount]);
+  const markStepViewed = (0, _react.useCallback)(async stepIndex => {
+    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
+ */
+function useShouldShowGuidon(adapter, guidonId, options) {
+  const {
+    progress,
+    isLoading
+  } = useGuidonPersistence(adapter, guidonId);
+  const [shouldShow, setShouldShow] = (0, _react.useState)(false);
+  const [isChecking, setIsChecking] = (0, _react.useState)(true);
+  (0, _react.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
+  };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/commonjs/persistence/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","useGuidonPersistence","adapter","guidonId","progress","setProgress","useState","isLoading","setIsLoading","error","setError","useEffect","mounted","loadProgress","data","err","Error","message","saveProgress","useCallback","newProgress","fullProgress","clearProgress","markCompleted","currentCount","completionCount","completed","completedAt","Date","toISOString","markStepViewed","stepIndex","lastStepIndex","isCompleted","hasStarted","useShouldShowGuidon","options","shouldShow","setShouldShow","isChecking","setIsChecking","checkCondition","forceShow","additionalCondition","result"],"sourceRoot":"../../../src","sources":["persistence/hooks.ts"],"mappings":"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","ignoreList":[]}

package/dist/commonjs/persistence/index.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _adapters = require("./adapters.js");
+Object.keys(_adapters).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _adapters[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _adapters[key];
+    }
+  });
+});
+var _hooks = require("./hooks.js");
+Object.keys(_hooks).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _hooks[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _hooks[key];
+    }
+  });
+});
+//# sourceMappingURL=index.js.map

package/dist/commonjs/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_adapters","require","Object","keys","forEach","key","exports","defineProperty","enumerable","get","_hooks"],"sourceRoot":"../../../src","sources":["persistence/index.ts"],"mappings":";;;;;AAAA,IAAAA,SAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,SAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAL,SAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAT,SAAA,CAAAK,GAAA;IAAA;EAAA;AAAA;AACA,IAAAK,MAAA,GAAAT,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAO,MAAA,EAAAN,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAK,MAAA,CAAAL,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAC,MAAA,CAAAL,GAAA;IAAA;EAAA;AAAA","ignoreList":[]}