@korsolutions/guidon 1.0.0

package/README.md

@@ -0,0 +1,334 @@
+# guidon
+
+A cross-platform walkthrough/onboarding component library for React Native with web support. Features spotlight effects, customizable tooltips, and flexible persistence options.
+
+## Installation
+
+```bash
+yarn add @guidon
+# or
+npm install @guidon
+```
+
+### Peer Dependencies
+
+Make sure you have these dependencies installed:
+
+```bash
+yarn add react react-native react-native-reanimated react-native-safe-area-context react-native-svg zustand
+```
+
+## Quick Start
+
+### 1. Define Your Guidon Steps
+
+```tsx
+import type { GuidonConfig } from '@guidon';
+
+const exploreGuidonConfig: GuidonConfig = {
+  id: 'explore-guidon',
+  steps: [
+    {
+      id: 'welcome',
+      targetId: 'search-button',
+      title: 'Welcome!',
+      description: 'Let us show you around the app.',
+      tooltipPosition: 'bottom',
+    },
+    {
+      id: 'filters',
+      targetId: 'filter-button',
+      title: 'Filters',
+      description: 'Use filters to find exactly what you need.',
+      tooltipPosition: 'bottom',
+    },
+    {
+      id: 'card-actions',
+      targetId: 'card-dismiss',
+      title: 'Card Actions',
+      description: 'Swipe left to dismiss or tap the X button.',
+      tooltipPosition: 'top',
+    },
+  ],
+  theme: {
+    primaryColor: '#007AFF',
+    backdropOpacity: 0.75,
+  },
+  onComplete: () => {
+    console.log('Guidon completed!');
+  },
+};
+```
+
+### 2. Wrap Your Screen with GuidonProvider
+
+```tsx
+import { GuidonProvider } from 'guidon';
+
+function ExploreScreen() {
+  return (
+    <GuidonProvider
+      config={exploreGuidonConfig}
+      autoStart={true}
+    >
+      <YourScreenContent />
+    </GuidonProvider>
+  );
+}
+```
+
+### 3. Mark Target Elements with GuidonTarget
+
+```tsx
+import { GuidonTarget } from 'guidon';
+
+function SearchButton() {
+  return (
+    <GuidonTarget targetId="search-button">
+      <TouchableOpacity onPress={handleSearch}>
+        <SearchIcon />
+      </TouchableOpacity>
+    </GuidonTarget>
+  );
+}
+```
+
+## Persistence
+
+The library supports flexible persistence through adapters. You can save guidon progress to local storage, AsyncStorage, or your backend API.
+
+### Using Built-in Adapters
+
+```tsx
+import {
+  GuidonProvider,
+  createLocalStorageAdapter,
+  createAsyncStorageAdapter,
+} from 'guidon';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// For web (localStorage)
+const webAdapter = createLocalStorageAdapter();
+
+// For React Native (AsyncStorage)
+const nativeAdapter = createAsyncStorageAdapter(AsyncStorage);
+
+function App() {
+  return (
+    <GuidonProvider
+      config={config}
+      persistenceAdapter={nativeAdapter}
+    >
+      <YourApp />
+    </GuidonProvider>
+  );
+}
+```
+
+### Creating a Custom API Adapter
+
+```tsx
+import { createApiAdapter } from 'guidon';
+
+const apiAdapter = createApiAdapter({
+  loadProgress: async (guidonId) => {
+    const response = await fetch(`/api/guidon/${guidonId}`);
+    if (!response.ok) return null;
+    return response.json();
+  },
+  saveProgress: async (progress) => {
+    await fetch(`/api/guidon/${progress.guidonId}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(progress),
+    });
+  },
+  clearProgress: async (guidonId) => {
+    await fetch(`/api/guidon/${guidonId}`, {
+      method: 'DELETE',
+    });
+  },
+});
+```
+
+### Combining Multiple Adapters
+
+```tsx
+import { createCompositeAdapter, createLocalStorageAdapter } from 'guidon';
+
+// Save to both local storage and API
+const compositeAdapter = createCompositeAdapter([
+  createLocalStorageAdapter(),
+  apiAdapter,
+]);
+```
+
+## API Reference
+
+### GuidonProvider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `GuidonConfig` | required | Configuration for the guidon |
+| `autoStart` | `boolean` | `true` | Whether to auto-start when mounted |
+| `shouldStart` | `() => boolean \| Promise<boolean>` | - | Custom condition for starting |
+| `persistenceAdapter` | `GuidonPersistenceAdapter` | - | Adapter for saving progress |
+| `portalComponent` | `React.ComponentType` | - | Custom portal for overlay rendering |
+| `renderTooltip` | `(props) => ReactNode` | - | Custom tooltip renderer |
+| `tooltipLabels` | `object` | - | Customize button labels |
+| `onBackdropPress` | `() => void` | - | Called when backdrop is pressed |
+
+### GuidonConfig
+
+```tsx
+interface GuidonConfig {
+  id: string;                    // Unique identifier
+  steps: GuidonStep[];      // Array of steps
+  theme?: GuidonTheme;      // Theme customization
+  animationDuration?: number;    // Animation duration (ms)
+  onComplete?: () => void;       // Called on completion
+  onSkip?: () => void;           // Called when skipped
+  onStepChange?: (index, step) => void; // Called on step change
+}
+```
+
+### GuidonStep
+
+```tsx
+interface GuidonStep {
+  id: string;                    // Unique step identifier
+  targetId: string;              // ID of the target element
+  title: string;                 // Tooltip title
+  description: string;           // Tooltip description
+  tooltipPosition?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+  customContent?: ReactNode;     // Additional content in tooltip
+  onStepEnter?: () => void;      // Called when step becomes active
+  onStepExit?: () => void;       // Called when leaving step
+}
+```
+
+### GuidonTheme
+
+```tsx
+interface GuidonTheme {
+  backdropColor?: string;         // Overlay color (default: '#000000')
+  backdropOpacity?: number;       // Overlay opacity (default: 0.75)
+  tooltipBackgroundColor?: string;
+  tooltipBorderColor?: string;
+  tooltipBorderRadius?: number;
+  titleColor?: string;
+  descriptionColor?: string;
+  primaryColor?: string;          // Button color
+  mutedColor?: string;            // Secondary text color
+  spotlightBorderRadius?: number; // Spotlight cutout radius
+  spotlightPadding?: number;      // Padding around spotlight
+}
+```
+
+## Controlling the Guidon
+
+### Using the Context Hook
+
+```tsx
+import { useGuidonContext } from 'guidon';
+
+function ReplayButton() {
+  const { replay, isCompleted } = useGuidonContext();
+
+  if (!isCompleted) return null;
+
+  return (
+    <Button onPress={replay}>
+      Replay Tutorial
+    </Button>
+  );
+}
+```
+
+### Using the Guidon API (Outside React)
+
+```tsx
+import { Guidon } from 'guidon';
+
+// Start programmatically
+Guidon.start();
+
+// Skip to a specific step
+Guidon.goToStep(2);
+
+// Complete the guidon
+Guidon.complete();
+
+// Reset and replay
+Guidon.reset();
+Guidon.start();
+```
+
+### Using Hook Selectors
+
+```tsx
+import {
+  useGuidonActive,
+  useGuidonStep,
+  useGuidonProgress,
+} from 'guidon';
+
+function GuidonStatus() {
+  const isActive = useGuidonActive();
+  const currentStep = useGuidonStep();
+  const { currentStep: stepNum, totalSteps, percentage } = useGuidonProgress();
+
+  if (!isActive) return null;
+
+  return (
+    <Text>
+      Step {stepNum} of {totalSteps} ({percentage}%)
+    </Text>
+  );
+}
+```
+
+## Custom Tooltip Rendering
+
+```tsx
+<GuidonProvider
+  config={config}
+  renderTooltip={({ step, currentIndex, totalSteps, onNext, onPrevious, onSkip }) => (
+    <View style={styles.customTooltip}>
+      <Text style={styles.title}>{step.title}</Text>
+      <Text>{step.description}</Text>
+      <View style={styles.buttons}>
+        <Button onPress={onSkip}>Skip</Button>
+        {currentIndex > 0 && <Button onPress={onPrevious}>Back</Button>}
+        <Button onPress={onNext}>
+          {currentIndex === totalSteps - 1 ? 'Done' : 'Next'}
+        </Button>
+      </View>
+    </View>
+  )}
+>
+```
+
+## Conditional Starting
+
+```tsx
+<GuidonProvider
+  config={config}
+  autoStart={true}
+  shouldStart={async () => {
+    // Check if user is new
+    const user = await getUser();
+    return user.isFirstLogin;
+  }}
+>
+```
+
+## Platform Support
+
+- iOS
+- Android
+- Web (React Native Web)
+
+## License
+
+MIT

package/dist/index-D_JFvCIg.d.mts

@@ -0,0 +1,314 @@
+import { ReactNode } from 'react';
+
+/**
+ * Position of tooltip relative to the highlighted element
+ */
+type TooltipPosition = 'top' | 'bottom' | 'left' | 'right' | 'auto';
+/**
+ * Defines the measurements of a target element
+ */
+interface TargetMeasurements {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A single step in the guidon
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+interface GuidonTooltipLabels {
+    next?: string;
+    previous?: string;
+    skip?: string;
+    finish?: string;
+    stepOf?: (current: number, total: number) => string;
+}
+/**
+ * Props for custom tooltip renderer
+ */
+interface GuidonTooltipRenderProps {
+    step: GuidonStep;
+    currentIndex: number;
+    totalSteps: number;
+    onNext: () => void;
+    onPrevious: () => void;
+    onSkip: () => void;
+}
+/**
+ * Props for the GuidonProvider component
+ */
+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
+ */
+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
+ */
+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
+ */
+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;
+}
+type GuidonStore = GuidonState & GuidonActions;
+
+/**
+ * No-op adapter that doesn't persist anything
+ * Useful for testing or when persistence is not needed
+ */
+declare const createNoopAdapter: () => GuidonPersistenceAdapter;
+/**
+ * Memory adapter that stores progress in memory
+ * Data is lost when the app is closed
+ */
+declare const createMemoryAdapter: () => GuidonPersistenceAdapter;
+/**
+ * localStorage adapter for web
+ * Only works in browser environments
+ */
+declare const createLocalStorageAdapter: (keyPrefix?: string) => GuidonPersistenceAdapter;
+/**
+ * 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);
+ */
+declare const createAsyncStorageAdapter: (asyncStorage: {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+    getAllKeys: () => Promise<readonly string[]>;
+    multiGet: (keys: readonly string[]) => Promise<readonly [string, string | null][]>;
+}, keyPrefix?: string) => GuidonPersistenceAdapter;
+/**
+ * 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),
+ *     });
+ *   },
+ * });
+ */
+declare const createApiAdapter: (handlers: Partial<GuidonPersistenceAdapter>) => GuidonPersistenceAdapter;
+/**
+ * Combine multiple adapters (e.g., save to both local and API)
+ * Loads from the first adapter that returns data
+ * Saves to all adapters
+ */
+declare const createCompositeAdapter: (adapters: GuidonPersistenceAdapter[]) => GuidonPersistenceAdapter;
+
+/**
+ * Hook to manage guidon's walkthrough progress with a persistence adapter
+ */
+declare function useGuidonPersistence(adapter: GuidonPersistenceAdapter | undefined, guidonId: string): {
+    progress: GuidonProgress | null;
+    isLoading: boolean;
+    error: string | null;
+    isCompleted: boolean;
+    hasStarted: boolean;
+    saveProgress: (newProgress: Omit<GuidonProgress, "guidonId">) => Promise<void>;
+    clearProgress: () => Promise<void>;
+    markCompleted: () => Promise<void>;
+    markStepViewed: (stepIndex: number) => Promise<void>;
+};
+/**
+ * Hook to check if a guidon should be shown
+ */
+declare function useShouldShowGuidon(adapter: GuidonPersistenceAdapter | undefined, guidonId: string, options?: {
+    /** Show even if completed (for replay) */
+    forceShow?: boolean;
+    /** Additional condition to check */
+    additionalCondition?: () => boolean | Promise<boolean>;
+}): {
+    shouldShow: boolean;
+    isChecking: boolean;
+    isCompleted: boolean;
+};
+
+export { type GuidonTargetProps as G, type TargetMeasurements as T, type GuidonTheme as a, type GuidonStep as b, type GuidonProviderProps as c, type GuidonStore as d, type GuidonConfig as e, type GuidonProgress as f, type GuidonPersistenceAdapter as g, type GuidonTooltipLabels as h, type GuidonTooltipRenderProps as i, type TooltipPosition as j, type GuidonState as k, type GuidonActions as l, createNoopAdapter as m, createMemoryAdapter as n, createLocalStorageAdapter as o, createAsyncStorageAdapter as p, createApiAdapter as q, createCompositeAdapter as r, useShouldShowGuidon as s, useGuidonPersistence as u };