@korsolutions/guidon 1.0.16 → 1.0.18

package/src/store.ts

@@ -1,6 +1,13 @@
 import { create } from "zustand";
 import { useShallow } from "zustand/react/shallow";
-import type { GuidonConfig, GuidonStore, GuidonTours, GuidonToursConfig, GuidonTheme, TargetMeasurements } from "./types";
+import type {
+  GuidonConfig,
+  GuidonStore,
+  GuidonTheme,
+  GuidonTours,
+  GuidonToursConfig,
+  TargetMeasurements,
+} from "./types";
 
 const initialState = {
   tours: {} as GuidonTours,
@@ -21,67 +28,44 @@ const initialState = {
 export const useGuidonStore = create<GuidonStore>((set, get) => ({
   ...initialState,
 
-  configure: (config: GuidonConfig) => {
-    const { config: existingConfig } = get();
-
-    // Skip if same config reference (prevents re-renders from resetting)
-    if (existingConfig === config) {
-      return;
-    }
-
-    console.log("[Guidon] configure() called - resetting to step 0");
-    set({ config, currentStepIndex: 0, isCompleted: false });
-  },
-
-  configureTours: (config: GuidonToursConfig | GuidonTours) => {
-    // Support both new GuidonToursConfig format and legacy GuidonTours format
-    const isNewFormat = 'tours' in config && typeof config.tours === 'object';
-
-    const tours = isNewFormat
-      ? (config as GuidonToursConfig).tours
-      : config as GuidonTours;
-    const globalTheme = isNewFormat
-      ? (config as GuidonToursConfig).theme
-      : undefined;
-    const globalAnimationDuration = isNewFormat
-      ? (config as GuidonToursConfig).animationDuration
-      : undefined;
-
+  configureTours: (config: GuidonToursConfig) => {
     const { tours: existingTours } = get();
 
     // Skip if same tours reference (prevents re-renders from resetting)
-    if (existingTours === tours) {
+    if (existingTours === config.tours) {
       return;
     }
 
-    console.log("[Guidon] configureTours() called with tours:", Object.keys(tours));
-    set({ tours, globalTheme, globalAnimationDuration });
+    console.log(
+      "[Guidon] configureTours() called with tours:",
+      Object.keys(config.tours),
+    );
+    set({
+      tours: config.tours,
+      globalTheme: config.theme,
+      globalAnimationDuration: config.animationDuration,
+    });
   },
 
-  start: (tourId?: string) => {
-    const { tours, config: legacyConfig, globalTheme, globalAnimationDuration } = get();
+  start: (tourId: string) => {
+    const { tours, globalTheme, globalAnimationDuration } = get();
 
-    // If tourId provided, use that tour from the tours collection
-    let config: GuidonConfig | null = null;
-    if (tourId) {
-      const tourConfig = tours[tourId] ?? null;
-      if (!tourConfig) {
-        console.log(`[Guidon] start() - tour "${tourId}" not found`);
-        return;
-      }
-      // Merge global theme/duration with tour-specific settings
-      config = {
-        ...tourConfig,
-        theme: { ...globalTheme, ...tourConfig.theme },
-        animationDuration: tourConfig.animationDuration ?? globalAnimationDuration,
-      };
-    } else {
-      // Fall back to legacy single config
-      config = legacyConfig;
+    const tourConfig = tours[tourId] ?? null;
+    if (!tourConfig) {
+      console.log(`[Guidon] start() - tour "${tourId}" not found`);
+      return;
     }
 
+    // Merge global theme/duration with tour-specific settings
+    const config: GuidonConfig = {
+      ...tourConfig,
+      theme: { ...globalTheme, ...tourConfig.theme },
+      animationDuration:
+        tourConfig.animationDuration ?? globalAnimationDuration,
+    };
+
     console.log("[Guidon] start() called", {
-      tourId: tourId ?? "legacy",
+      tourId,
       hasConfig: !!config,
       stepCount: config?.steps.length ?? 0,
     });
@@ -100,7 +84,7 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
       activeTourId: tourId ?? null,
       isActive: true,
       currentStepIndex: 0,
-      isCompleted: false
+      isCompleted: false,
     });
 
     // Call onStepEnter for the first step
@@ -268,17 +252,8 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
  */
 export const Guidon = {
   /**
-   * Configure a single walkthrough (legacy API)
-   */
-  configure: (config: GuidonConfig) => {
-    useGuidonStore.getState().configure(config);
-  },
-
-  /**
-   * Configure multiple named tours.
-   * Accepts either GuidonToursConfig (with global theme) or legacy GuidonTours format.
+   * Configure multiple named tours with optional global theme.
    * @example
-   * // New format with global theme
    * Guidon.configureTours({
    *   theme: { primaryColor: '#007AFF' },
    *   tours: {
@@ -286,24 +261,17 @@ export const Guidon = {
    *     profile: { id: 'profile', steps: [...] },
    *   },
    * });
-   *
-   * // Legacy format (still supported)
-   * Guidon.configureTours({
-   *   explore: { id: 'explore', steps: [...] },
-   *   profile: { id: 'profile', steps: [...] },
-   * });
    */
-  configureTours: (config: GuidonToursConfig | GuidonTours) => {
+  configureTours: (config: GuidonToursConfig) => {
     useGuidonStore.getState().configureTours(config);
   },
 
   /**
-   * Start a tour by ID, or the legacy single config if no ID provided
+   * Start a tour by ID
    * @example
    * Guidon.start('explore'); // Start the 'explore' tour
-   * Guidon.start(); // Start legacy single config
    */
-  start: (tourId?: string) => {
+  start: (tourId: string) => {
     useGuidonStore.getState().start(tourId);
   },
 
@@ -371,7 +339,7 @@ export const Guidon = {
   },
 
   /**
-   * Get the currently active tour ID (null if using legacy single config)
+   * Get the currently active tour ID
    */
   getActiveTourId: () => {
     return useGuidonStore.getState().activeTourId;
@@ -439,7 +407,7 @@ export const useTargetMeasurements = (targetId: string) =>
   useGuidonStore((state: GuidonStore) => state.targetMeasurements[targetId]);
 
 /**
- * Hook to check if the guidon is waiting for a target element to mount
+ * Hook to check if the Guidon is waiting for a target element to mount
  * Returns null if not active, not waiting, or if it's a floating step
  */
 export const useWaitingState = () =>
@@ -450,7 +418,7 @@ export const useWaitingState = () =>
       const currentStep = state.config.steps[state.currentStepIndex];
       const targetId = currentStep?.targetId;
 
-      // Floating step (no targetId) - not waiting
+      // Floating step therefore not waiting
       if (!targetId) return null;
 
       const hasMeasurements = !!state.targetMeasurements[targetId];
@@ -464,7 +432,8 @@ export const useWaitingState = () =>
   );
 
 /**
- * Hook to check if the current step is a floating step (no target element)
+ * Hook to check if the current step is a floating step,
+ * i.e. has no targetId and is centered on device
  */
 export const useIsFloatingStep = () =>
   useGuidonStore((state: GuidonStore) => {

package/src/types.ts

@@ -59,6 +59,27 @@ export interface GuidonStep {
   waitingMessage?: string;
   /** Timeout in ms before auto-skipping this step (0 = no timeout) */
   waitTimeout?: number;
+  /**
+   * Whether to scroll the target element into view when this step becomes active.
+   * On web: uses native scrollIntoView()
+   * On mobile: requires a registered scroll container
+   * @default true
+   */
+  scrollIntoView?: boolean;
+}
+
+/**
+ * Scroll behavior configuration
+ */
+export interface GuidonScrollOptions {
+  /** Scroll behavior: 'smooth' for animated, 'instant' for immediate */
+  behavior?: 'smooth' | 'instant';
+  /** Vertical alignment of target in viewport */
+  block?: 'start' | 'center' | 'end' | 'nearest';
+  /** Horizontal alignment of target in viewport */
+  inline?: 'start' | 'center' | 'end' | 'nearest';
+  /** Extra padding when scrolling (ensures element isn't at edge) */
+  padding?: number;
 }
 
 /**
@@ -87,6 +108,8 @@ export interface GuidonTheme {
   spotlightBorderRadius?: number;
   /** Padding around the highlighted element */
   spotlightPadding?: number;
+  /** Global scroll options when navigating to steps */
+  scrollOptions?: GuidonScrollOptions;
 }
 
 /**
@@ -186,10 +209,8 @@ export interface GuidonTooltipRenderProps {
  */
 export interface GuidonProviderProps {
   children: ReactNode;
-  /** Configuration for the guidon (optional when using configureTours) */
-  config?: GuidonConfig;
-  /** Whether to auto-start when the component mounts */
-  autoStart?: boolean;
+  /** Tour ID to auto-start when the provider mounts */
+  autoStart?: string;
   /** Condition function to determine if guidon should start */
   shouldStart?: () => boolean | Promise<boolean>;
   /** Persistence adapter for saving/loading progress */
@@ -279,7 +300,7 @@ export interface GuidonState {
   globalAnimationDuration?: number;
   /** ID of the currently active tour */
   activeTourId: string | null;
-  /** Currently active guidon config (derived from tours + activeTourId, or legacy single config) */
+  /** Currently active guidon config (derived from tours + activeTourId) */
   config: GuidonConfig | null;
   /** Whether the guidon is currently active */
   isActive: boolean;
@@ -303,15 +324,10 @@ export interface GuidonState {
  * Internal store actions
  */
 export interface GuidonActions {
-  /** Configure a single guidon (legacy API, still supported) */
-  configure: (config: GuidonConfig) => void;
-  /**
-   * Configure multiple named tours.
-   * Accepts either GuidonToursConfig (with global theme) or legacy GuidonTours format.
-   */
-  configureTours: (config: GuidonToursConfig | GuidonTours) => void;
-  /** Start a tour by ID, or the legacy single config if no ID provided */
-  start: (tourId?: string) => void;
+  /** Configure multiple named tours with global theme support */
+  configureTours: (config: GuidonToursConfig) => void;
+  /** Start a tour by ID */
+  start: (tourId: string) => void;
   /** Stop the current tour without completing it */
   stop: () => void;
   /** Go to the next step */

package/dist/commonjs/babel.config.js

@@ -1,15 +0,0 @@
-"use strict";
-
-module.exports = function (api) {
-  api.cache(true);
-  return {
-    presets: ["module:react-native-builder-bob/babel-preset"],
-    plugins: [[require.resolve("babel-plugin-module-resolver"), {
-      root: ["./src"],
-      alias: {
-        "@": "./src"
-      }
-    }]]
-  };
-};
-//# sourceMappingURL=babel.config.js.map

package/dist/commonjs/babel.config.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["module","exports","api","cache","presets","plugins","require","resolve","root","alias"],"sourceRoot":"../../src","sources":["babel.config.js"],"mappings":";;AAAAA,MAAM,CAACC,OAAO,GAAG,UAAUC,GAAG,EAAE;EAC9BA,GAAG,CAACC,KAAK,CAAC,IAAI,CAAC;EAEf,OAAO;IACLC,OAAO,EAAE,CAAC,8CAA8C,CAAC;IACzDC,OAAO,EAAE,CACP,CACEC,OAAO,CAACC,OAAO,CAAC,8BAA8B,CAAC,EAC/C;MACEC,IAAI,EAAE,CAAC,OAAO,CAAC;MACfC,KAAK,EAAE;QACL,GAAG,EAAE;MACP;IACF,CAAC,CACF;EAEL,CAAC;AACH,CAAC","ignoreList":[]}

package/dist/commonjs/bob.config.js

@@ -1,11 +0,0 @@
-"use strict";
-
-module.exports = {
-  source: "src",
-  output: "dist",
-  targets: [["module", {
-    esm: true,
-    configFile: true
-  }], "typescript"]
-};
-//# sourceMappingURL=bob.config.js.map

package/dist/commonjs/bob.config.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["module","exports","source","output","targets","esm","configFile"],"sourceRoot":"../../src","sources":["bob.config.js"],"mappings":";;AAAAA,MAAM,CAACC,OAAO,GAAG;EACfC,MAAM,EAAE,KAAK;EACbC,MAAM,EAAE,MAAM;EACdC,OAAO,EAAE,CACP,CACE,QAAQ,EACR;IACEC,GAAG,EAAE,IAAI;IACTC,UAAU,EAAE;EACd,CAAC,CACF,EACD,YAAY;AAEhB,CAAC","ignoreList":[]}

package/dist/commonjs/tsconfig.json

@@ -1,32 +0,0 @@
-{
-  "compilerOptions": {
-    "customConditions": ["dev-source", "react-native", "react-native-strict-api"],
-    "allowJs": true,
-    "esModuleInterop": true,
-    "jsx": "react-native",
-    "lib": ["DOM", "ESNext"],
-    "module": "preserve",
-    "moduleDetection": "force",
-    "moduleResolution": "bundler",
-    "noEmit": true,
-    "resolveJsonModule": true,
-    "skipLibCheck": true,
-    "target": "ESNext",
-    "strict": true,
-    "verbatimModuleSyntax": true,
-    "allowUnreachableCode": false,
-    "allowUnusedLabels": false,
-    "forceConsistentCasingInFileNames": true,
-    "noFallthroughCasesInSwitch": true,
-    "noImplicitReturns": true,
-    "noImplicitUseStrict": false,
-    "noStrictGenericChecks": false,
-    "noUncheckedIndexedAccess": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "exclude": ["node_modules", "dist"]
-}

package/dist/module/babel.config.js

@@ -1,15 +0,0 @@
-"use strict";
-
-module.exports = function (api) {
-  api.cache(true);
-  return {
-    presets: ["module:react-native-builder-bob/babel-preset"],
-    plugins: [[require.resolve("babel-plugin-module-resolver"), {
-      root: ["./src"],
-      alias: {
-        "@": "./src"
-      }
-    }]]
-  };
-};
-//# sourceMappingURL=babel.config.js.map

package/dist/module/babel.config.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["module","exports","api","cache","presets","plugins","require","resolve","root","alias"],"sourceRoot":"../../src","sources":["babel.config.js"],"mappings":";;AAAAA,MAAM,CAACC,OAAO,GAAG,UAAUC,GAAG,EAAE;EAC9BA,GAAG,CAACC,KAAK,CAAC,IAAI,CAAC;EAEf,OAAO;IACLC,OAAO,EAAE,CAAC,8CAA8C,CAAC;IACzDC,OAAO,EAAE,CACP,CACEC,OAAO,CAACC,OAAO,CAAC,8BAA8B,CAAC,EAC/C;MACEC,IAAI,EAAE,CAAC,OAAO,CAAC;MACfC,KAAK,EAAE;QACL,GAAG,EAAE;MACP;IACF,CAAC,CACF;EAEL,CAAC;AACH,CAAC","ignoreList":[]}

package/dist/module/bob.config.js

@@ -1,11 +0,0 @@
-"use strict";
-
-module.exports = {
-  source: "src",
-  output: "dist",
-  targets: [["module", {
-    esm: true,
-    configFile: true
-  }], "typescript"]
-};
-//# sourceMappingURL=bob.config.js.map

package/dist/module/bob.config.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["module","exports","source","output","targets","esm","configFile"],"sourceRoot":"../../src","sources":["bob.config.js"],"mappings":";;AAAAA,MAAM,CAACC,OAAO,GAAG;EACfC,MAAM,EAAE,KAAK;EACbC,MAAM,EAAE,MAAM;EACdC,OAAO,EAAE,CACP,CACE,QAAQ,EACR;IACEC,GAAG,EAAE,IAAI;IACTC,UAAU,EAAE;EACd,CAAC,CACF,EACD,YAAY;AAEhB,CAAC","ignoreList":[]}

package/dist/module/tsconfig.json

@@ -1,32 +0,0 @@
-{
-  "compilerOptions": {
-    "customConditions": ["dev-source", "react-native", "react-native-strict-api"],
-    "allowJs": true,
-    "esModuleInterop": true,
-    "jsx": "react-native",
-    "lib": ["DOM", "ESNext"],
-    "module": "preserve",
-    "moduleDetection": "force",
-    "moduleResolution": "bundler",
-    "noEmit": true,
-    "resolveJsonModule": true,
-    "skipLibCheck": true,
-    "target": "ESNext",
-    "strict": true,
-    "verbatimModuleSyntax": true,
-    "allowUnreachableCode": false,
-    "allowUnusedLabels": false,
-    "forceConsistentCasingInFileNames": true,
-    "noFallthroughCasesInSwitch": true,
-    "noImplicitReturns": true,
-    "noImplicitUseStrict": false,
-    "noStrictGenericChecks": false,
-    "noUncheckedIndexedAccess": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "exclude": ["node_modules", "dist"]
-}

package/src/babel.config.js

@@ -1,18 +0,0 @@
-module.exports = function (api) {
-  api.cache(true);
-
-  return {
-    presets: ["module:react-native-builder-bob/babel-preset"],
-    plugins: [
-      [
-        require.resolve("babel-plugin-module-resolver"),
-        {
-          root: ["./src"],
-          alias: {
-            "@": "./src",
-          },
-        },
-      ],
-    ],
-  };
-};

package/src/bob.config.js

@@ -1,14 +0,0 @@
-module.exports = {
-  source: "src",
-  output: "dist",
-  targets: [
-    [
-      "module",
-      {
-        esm: true,
-        configFile: true,
-      },
-    ],
-    "typescript",
-  ],
-};

package/src/tsconfig.json

@@ -1,32 +0,0 @@
-{
-  "compilerOptions": {
-    "customConditions": ["dev-source", "react-native", "react-native-strict-api"],
-    "allowJs": true,
-    "esModuleInterop": true,
-    "jsx": "react-native",
-    "lib": ["DOM", "ESNext"],
-    "module": "preserve",
-    "moduleDetection": "force",
-    "moduleResolution": "bundler",
-    "noEmit": true,
-    "resolveJsonModule": true,
-    "skipLibCheck": true,
-    "target": "ESNext",
-    "strict": true,
-    "verbatimModuleSyntax": true,
-    "allowUnreachableCode": false,
-    "allowUnusedLabels": false,
-    "forceConsistentCasingInFileNames": true,
-    "noFallthroughCasesInSwitch": true,
-    "noImplicitReturns": true,
-    "noImplicitUseStrict": false,
-    "noStrictGenericChecks": false,
-    "noUncheckedIndexedAccess": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "exclude": ["node_modules", "dist"]
-}