@korsolutions/guidon 1.0.15 → 1.0.17

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,31 +252,26 @@ 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
+   * Configure multiple named tours with optional global theme.
    * @example
    * Guidon.configureTours({
-   *   explore: { steps: [...], onComplete: () => {} },
-   *   profile: { steps: [...] },
+   *   theme: { primaryColor: '#007AFF' },
+   *   tours: {
+   *     explore: { id: 'explore', steps: [...] },
+   *     profile: { id: 'profile', steps: [...] },
+   *   },
    * });
    */
-  configureTours: (tours: GuidonTours) => {
-    useGuidonStore.getState().configureTours(tours);
+  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);
   },
 
@@ -360,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;
@@ -428,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 = () =>
@@ -439,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];
@@ -453,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

@@ -186,10 +186,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 */
@@ -221,62 +219,10 @@ export interface GuidonTargetProps {
 export type GuidonTours = Record<string, GuidonConfig>;
 
 /**
- * Single tour configuration for use within GuidonToursConfig
+ * Single tour configuration for use within GuidonToursConfig.
+ * Identical to GuidonConfig - use this alias for semantic clarity in multi-tour setups.
  */
-export interface GuidonTourDefinition {
-  /** Unique identifier for this tour (should match the key) */
-  id: string;
-  /** Steps in the tour */
-  steps: Array<{
-    /** Unique identifier for this step */
-    id: string;
-    /**
-     * ID of the target element to highlight.
-     * Omit for floating tooltip (centered, no spotlight).
-     */
-    targetId?: string;
-    /** Title displayed in the tooltip */
-    title: string;
-    /** Description/content displayed in the tooltip */
-    description: string;
-    /**
-     * Preferred position of the tooltip relative to target
-     * @default 'auto'
-     */
-    tooltipPosition?: TooltipPosition;
-    /**
-     * Position for floating tooltips (when no targetId)
-     * @default 'center'
-     */
-    floatingPosition?: FloatingPosition;
-    /** Custom React content to render in the tooltip */
-    customContent?: ReactNode;
-    /** Called when this step becomes active */
-    onStepEnter?: () => void;
-    /** Called when leaving this step */
-    onStepExit?: () => void;
-    /** Message shown while waiting for target element to mount */
-    waitingMessage?: string;
-    /**
-     * Auto-skip timeout in ms if target doesn't mount.
-     * Set to 0 to disable.
-     */
-    waitTimeout?: number;
-  }>;
-  /**
-   * Theme customization for this specific tour.
-   * Overrides the global theme if provided.
-   */
-  theme?: GuidonTheme;
-  /** Animation duration in milliseconds (overrides global) */
-  animationDuration?: number;
-  /** Called when the tour is completed (user finishes all steps) */
-  onComplete?: () => void;
-  /** Called when the tour is skipped */
-  onSkip?: () => void;
-  /** Called when the step changes */
-  onStepChange?: (stepIndex: number, step: GuidonStep) => void;
-}
+export type GuidonTourDefinition = GuidonConfig;
 
 /**
  * Configuration object for defining multiple tours with shared settings.
@@ -331,7 +277,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;
@@ -355,15 +301,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 */