@korsolutions/guidon 1.0.0

package/src/types.ts

@@ -0,0 +1,242 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Position of tooltip relative to the highlighted element
+ */
+export type TooltipPosition = 'top' | 'bottom' | 'left' | 'right' | 'auto';
+
+/**
+ * Defines the measurements of a target element
+ */
+export interface TargetMeasurements {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * A single step in the guidon
+ */
+export interface GuidonStep {
+  /** Unique identifier for this step */
+  id: string;
+  /** ID of the target element to highlight */
+  targetId: string;
+  /** Title displayed in the tooltip */
+  title: string;
+  /** Description/content displayed in the tooltip */
+  description: string;
+  /** Preferred position of the tooltip */
+  tooltipPosition?: TooltipPosition;
+  /** Custom content to render in the tooltip */
+  customContent?: ReactNode;
+  /** Called when this step becomes active */
+  onStepEnter?: () => void;
+  /** Called when leaving this step */
+  onStepExit?: () => void;
+}
+
+/**
+ * Theme configuration for guidon styling
+ */
+export interface GuidonTheme {
+  /** Color of the backdrop overlay */
+  backdropColor?: string;
+  /** Opacity of the backdrop (0-1) */
+  backdropOpacity?: number;
+  /** Background color of the tooltip */
+  tooltipBackgroundColor?: string;
+  /** Border color of the tooltip */
+  tooltipBorderColor?: string;
+  /** Border radius of the tooltip */
+  tooltipBorderRadius?: number;
+  /** Color of the title text */
+  titleColor?: string;
+  /** Color of the description text */
+  descriptionColor?: string;
+  /** Primary/accent color (buttons, progress) */
+  primaryColor?: string;
+  /** Muted/secondary color */
+  mutedColor?: string;
+  /** Border radius of the spotlight cutout */
+  spotlightBorderRadius?: number;
+  /** Padding around the highlighted element */
+  spotlightPadding?: number;
+}
+
+/**
+ * State of a specific guidon tour
+ */
+export interface GuidonProgress {
+  /** Unique identifier for the guidon */
+  guidonId: string;
+  /** Whether this guidon has been completed */
+  completed: boolean;
+  /** Index of the last viewed step (for resuming) */
+  lastStepIndex?: number;
+  /** Timestamp of completion */
+  completedAt?: string;
+  /** Number of times this guidon has been completed */
+  completionCount?: number;
+}
+
+/**
+ * Persistence adapter interface for saving/loading guidon progress
+ * Implement this interface to connect the guidon to your backend
+ */
+export interface GuidonPersistenceAdapter {
+  /**
+   * Load the progress for a specific guidon
+   * @param guidonId - Unique identifier for the guidon
+   * @returns The progress data or null if not found
+   */
+  loadProgress: (guidonId: string) => Promise<GuidonProgress | null>;
+
+  /**
+   * Save the progress for a specific guidon
+   * @param progress - The progress data to save
+   */
+  saveProgress: (progress: GuidonProgress) => Promise<void>;
+
+  /**
+   * Load all guidon progress (optional, for bulk operations)
+   * @returns Map of guidon IDs to progress data
+   */
+  loadAllProgress?: () => Promise<Record<string, GuidonProgress>>;
+
+  /**
+   * Clear progress for a specific guidon (for replay functionality)
+   * @param guidonId - Unique identifier for the guidon
+   */
+  clearProgress?: (guidonId: string) => Promise<void>;
+}
+
+/**
+ * Configuration for a guidon
+ */
+export interface GuidonConfig {
+  /** Unique identifier for this guidon */
+  id: string;
+  /** Steps in the guidon */
+  steps: GuidonStep[];
+  /** Theme customization */
+  theme?: GuidonTheme;
+  /** Animation duration in milliseconds */
+  animationDuration?: number;
+  /** Called when the guidon is completed */
+  onComplete?: () => void;
+  /** Called when the guidon is skipped */
+  onSkip?: () => void;
+  /** Called when the step changes */
+  onStepChange?: (stepIndex: number, step: GuidonStep) => void;
+}
+
+/**
+ * Labels for tooltip buttons
+ */
+export interface GuidonTooltipLabels {
+  next?: string;
+  previous?: string;
+  skip?: string;
+  finish?: string;
+  stepOf?: (current: number, total: number) => string;
+}
+
+/**
+ * Props for custom tooltip renderer
+ */
+export interface GuidonTooltipRenderProps {
+  step: GuidonStep;
+  currentIndex: number;
+  totalSteps: number;
+  onNext: () => void;
+  onPrevious: () => void;
+  onSkip: () => void;
+}
+
+/**
+ * Props for the GuidonProvider component
+ */
+export interface GuidonProviderProps {
+  children: ReactNode;
+  /** Configuration for the guidon */
+  config: GuidonConfig;
+  /** Whether to auto-start when the component mounts */
+  autoStart?: boolean;
+  /** Condition function to determine if guidon should start */
+  shouldStart?: () => boolean | Promise<boolean>;
+  /** Persistence adapter for saving/loading progress */
+  persistenceAdapter?: GuidonPersistenceAdapter;
+  /** Custom portal component for rendering overlay */
+  portalComponent?: React.ComponentType<{ children: ReactNode }>;
+  /** Custom tooltip renderer */
+  renderTooltip?: (props: GuidonTooltipRenderProps) => ReactNode;
+  /** Customize tooltip labels */
+  tooltipLabels?: GuidonTooltipLabels;
+  /** Called when backdrop is pressed */
+  onBackdropPress?: () => void;
+}
+
+/**
+ * Props for the GuidonTarget component
+ */
+export interface GuidonTargetProps {
+  children: ReactNode;
+  /** Target ID that matches a step's targetId */
+  targetId: string;
+  /** Whether this target is currently active (for conditional rendering) */
+  active?: boolean;
+}
+
+/**
+ * Internal store state
+ */
+export interface GuidonState {
+  /** Currently active guidon config */
+  config: GuidonConfig | null;
+  /** Whether the guidon is currently active */
+  isActive: boolean;
+  /** Current step index */
+  currentStepIndex: number;
+  /** Whether the guidon has been completed */
+  isCompleted: boolean;
+  /** Map of target IDs to their measurements */
+  targetMeasurements: Record<string, TargetMeasurements>;
+  /** Loading state for persistence operations */
+  isLoading: boolean;
+  /** Error from persistence operations */
+  error: string | null;
+}
+
+/**
+ * Internal store actions
+ */
+export interface GuidonActions {
+  /** Configure the guidon */
+  configure: (config: GuidonConfig) => void;
+  /** Start the guidon */
+  start: () => void;
+  /** Go to the next step */
+  next: () => void;
+  /** Go to the previous step */
+  previous: () => void;
+  /** Go to a specific step */
+  goToStep: (index: number) => void;
+  /** Skip the guidon */
+  skip: () => void;
+  /** Complete the guidon */
+  complete: () => void;
+  /** Reset the guidon state */
+  reset: () => void;
+  /** Register a target's measurements */
+  registerTarget: (targetId: string, measurements: TargetMeasurements) => void;
+  /** Unregister a target */
+  unregisterTarget: (targetId: string) => void;
+  /** Set loading state */
+  setLoading: (isLoading: boolean) => void;
+  /** Set error state */
+  setError: (error: string | null) => void;
+}
+
+export type GuidonStore = GuidonState & GuidonActions;