@korsolutions/guidon 1.0.14 → 1.0.15

package/src/types.ts

@@ -221,82 +221,103 @@ export interface GuidonTargetProps {
 export type GuidonTours = Record<string, GuidonConfig>;
 
 /**
- * Helper type for defining tours with full autocomplete.
- * Use with `satisfies` for best DX:
+ * Single tour configuration for use within GuidonToursConfig
+ */
+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;
+}
+
+/**
+ * Configuration object for defining multiple tours with shared settings.
  *
  * @example
  * ```tsx
- * const tours = {
- *   welcome: {
- *     id: "welcome",
- *     steps: [
- *       { id: "step-1", title: "Welcome", description: "..." },
- *       { id: "step-2", targetId: "my-button", title: "Click here", description: "..." },
- *     ],
- *     onComplete: () => console.log("Done!"),
- *   },
- *   explore: {
- *     id: "explore",
- *     steps: [...],
+ * const config = {
+ *   theme: { backdropOpacity: 0.8, primaryColor: '#007AFF' },
+ *   tours: {
+ *     welcome: {
+ *       id: "welcome",
+ *       steps: [{ id: "s1", title: "Welcome", description: "..." }],
+ *     },
+ *     explore: {
+ *       id: "explore",
+ *       steps: [...],
+ *       theme: { primaryColor: '#FF0000' }, // Override for this tour
+ *     },
  *   },
  * } satisfies GuidonToursConfig;
  *
- * Guidon.configureTours(tours);
+ * Guidon.configureTours(config);
  * ```
  */
-export type GuidonToursConfig = {
-  [tourId: string]: {
-    /** 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 will be 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 tour */
-    theme?: GuidonTheme;
-    /** Animation duration in milliseconds */
-    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 interface GuidonToursConfig {
+  /**
+   * Global theme applied to all tours.
+   * Individual tours can override with their own theme.
+   * @default { backdropOpacity: 0.7 }
+   */
+  theme?: GuidonTheme;
+  /**
+   * Global animation duration applied to all tours.
+   * Individual tours can override.
+   */
+  animationDuration?: number;
+  /**
+   * Map of tour IDs to tour configurations
+   */
+  tours: Record<string, GuidonTourDefinition>;
+}
 
 /**
  * Internal store state
@@ -304,6 +325,10 @@ export type GuidonToursConfig = {
 export interface GuidonState {
   /** Collection of all configured tours */
   tours: GuidonTours;
+  /** Global theme applied to all tours */
+  globalTheme?: GuidonTheme;
+  /** Global animation duration applied to all tours */
+  globalAnimationDuration?: number;
   /** ID of the currently active tour */
   activeTourId: string | null;
   /** Currently active guidon config (derived from tours + activeTourId, or legacy single config) */
@@ -332,8 +357,11 @@ export interface GuidonState {
 export interface GuidonActions {
   /** Configure a single guidon (legacy API, still supported) */
   configure: (config: GuidonConfig) => void;
-  /** Configure multiple named tours */
-  configureTours: (tours: GuidonTours) => 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;
   /** Stop the current tour without completing it */