@nextsparkjs/plugin-walkme 0.1.0-beta.104

package/hooks/useTourState.ts

@@ -0,0 +1,146 @@
+'use client'
+
+import { useReducer, useEffect, useRef, useCallback } from 'react'
+import type { Tour, WalkmeState, WalkmeAction } from '../types/walkme.types'
+import { createInitialState, walkmeReducer } from '../lib/core'
+import { createStorageAdapter } from '../lib/storage'
+
+interface UseTourStateOptions {
+  persistState: boolean
+  debug: boolean
+  userId?: string
+}
+
+/**
+ * Internal hook that manages the core WalkMe state machine.
+ * Handles useReducer, localStorage persistence, and initial state loading.
+ */
+export function useTourState(tours: Tour[], options: UseTourStateOptions) {
+  const { persistState, debug, userId } = options
+  const [state, dispatch] = useReducer(walkmeReducer, createInitialState())
+  const storageRef = useRef(createStorageAdapter(userId))
+  const initialized = useRef(false)
+  const prevUserIdRef = useRef(userId)
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // Re-create storage adapter when userId changes (e.g. session loads async)
+  useEffect(() => {
+    if (prevUserIdRef.current === userId) return
+    prevUserIdRef.current = userId
+    storageRef.current = createStorageAdapter(userId)
+
+    // Re-restore persisted state from the new user-scoped storage
+    if (persistState) {
+      const saved = storageRef.current.load()
+      if (saved) {
+        dispatch({
+          type: 'RESTORE_STATE',
+          completedTours: saved.completedTours,
+          skippedTours: saved.skippedTours,
+          tourHistory: saved.tourHistory,
+          activeTour: saved.activeTour,
+        })
+      } else {
+        // New user with no state — reset to clean slate
+        dispatch({ type: 'RESET_ALL' })
+      }
+    }
+  }, [userId, persistState])
+
+  // Initialize tours and restore persisted state on mount
+  useEffect(() => {
+    if (initialized.current) return
+    initialized.current = true
+
+    // Initialize with tour definitions
+    dispatch({ type: 'INITIALIZE', tours })
+
+    if (debug) {
+      dispatch({ type: 'SET_DEBUG', enabled: true })
+    }
+
+    // Restore persisted state
+    if (persistState) {
+      const storage = storageRef.current
+      const saved = storage.load()
+
+      if (saved) {
+        storage.incrementVisitCount()
+
+        dispatch({
+          type: 'RESTORE_STATE',
+          completedTours: saved.completedTours,
+          skippedTours: saved.skippedTours,
+          tourHistory: saved.tourHistory,
+          activeTour: saved.activeTour,
+        })
+      } else {
+        // First visit - initialize storage
+        storage.incrementVisitCount()
+        storage.setFirstVisitDate(new Date().toISOString())
+      }
+    }
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Re-register tour definitions when they change after initialization.
+  // This handles the case where tours arrive asynchronously (e.g. after API fetch)
+  // and the provider was already mounted with an empty tours array.
+  useEffect(() => {
+    if (!initialized.current) return
+    if (tours.length === 0) return
+    dispatch({ type: 'UPDATE_TOURS', tours })
+  }, [tours]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Persist state changes to localStorage (debounced)
+  useEffect(() => {
+    if (!persistState || !state.initialized) return
+
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current)
+    }
+
+    debounceRef.current = setTimeout(() => {
+      const storage = storageRef.current
+      const existing = storage.load()
+
+      storage.save({
+        version: 1,
+        completedTours: state.completedTours,
+        skippedTours: state.skippedTours,
+        activeTour: state.activeTour,
+        tourHistory: state.tourHistory,
+        visitCount: existing?.visitCount ?? 1,
+        firstVisitDate: existing?.firstVisitDate ?? new Date().toISOString(),
+      })
+    }, 100)
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current)
+      }
+    }
+  }, [
+    persistState,
+    state.initialized,
+    state.completedTours,
+    state.skippedTours,
+    state.activeTour,
+    state.tourHistory,
+  ])
+
+  const stableDispatch = useCallback(
+    (action: WalkmeAction) => {
+      if (debug) {
+        console.log('[WalkMe]', action.type, action)
+      }
+      dispatch(action)
+    },
+    [debug],
+  )
+
+  return {
+    state,
+    dispatch: stableDispatch,
+    storage: storageRef.current,
+  }
+}

package/hooks/useWalkme.ts

@@ -0,0 +1,52 @@
+'use client'
+
+import { useWalkmeContext } from '../providers/walkme-context'
+import { getActiveTour, getActiveStep } from '../lib/core'
+
+/**
+ * Main public hook for controlling WalkMe tours.
+ *
+ * @example
+ * ```tsx
+ * const { startTour, isActive, nextStep } = useWalkme()
+ *
+ * return (
+ *   <button onClick={() => startTour('onboarding')}>
+ *     Start Tour
+ *   </button>
+ * )
+ * ```
+ */
+export function useWalkme() {
+  const ctx = useWalkmeContext()
+
+  return {
+    // Tour control
+    startTour: ctx.startTour,
+    pauseTour: ctx.pauseTour,
+    resumeTour: ctx.resumeTour,
+    skipTour: ctx.skipTour,
+    completeTour: ctx.completeTour,
+    resetTour: ctx.resetTour,
+    resetAllTours: ctx.resetAllTours,
+
+    // Step navigation
+    nextStep: ctx.nextStep,
+    prevStep: ctx.prevStep,
+    goToStep: ctx.goToStep,
+
+    // State queries
+    isActive: ctx.state.activeTour !== null,
+    activeTourId: ctx.state.activeTour?.tourId ?? null,
+    currentStepIndex: ctx.state.activeTour?.currentStepIndex ?? 0,
+
+    // Tour info helpers
+    getActiveTour: () => getActiveTour(ctx.state),
+    getActiveStep: () => getActiveStep(ctx.state),
+    isTourCompleted: ctx.isTourCompleted,
+    isTourActive: ctx.isTourActive,
+
+    // Custom events (for onEvent triggers)
+    emitEvent: ctx.emitEvent,
+  }
+}

package/jest.config.cjs

@@ -0,0 +1,27 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts', '**/*.test.tsx'],
+  moduleNameMapper: {
+    '^~/(.*)$': '<rootDir>/$1',
+  },
+  setupFilesAfterEnv: ['<rootDir>/tests/setup.ts'],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: '<rootDir>/tests/tsconfig.json',
+    }],
+  },
+  transformIgnorePatterns: [
+    '/node_modules/(?!(@floating-ui)/)',
+  ],
+  collectCoverageFrom: [
+    'lib/**/*.{ts,tsx}',
+    'hooks/**/*.{ts,tsx}',
+    '!**/*.d.ts',
+    '!**/index.ts',
+  ],
+  coverageDirectory: 'coverage',
+  verbose: true,
+}

package/lib/conditions.ts

@@ -0,0 +1,113 @@
+/**
+ * WalkMe Conditions Module
+ *
+ * Conditional display evaluation for tours.
+ * All specified conditions must pass (AND logic).
+ */
+
+import type { TourConditions, ConditionContext } from '../types/walkme.types'
+
+// ---------------------------------------------------------------------------
+// Main Evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate all conditions for a tour.
+ * Returns true if no conditions are specified or all conditions pass.
+ * Uses AND logic: every specified condition must be satisfied.
+ */
+export function evaluateConditions(
+  conditions: TourConditions | undefined,
+  context: ConditionContext,
+): boolean {
+  if (!conditions) return true
+
+  // Check user role
+  if (conditions.userRole && conditions.userRole.length > 0) {
+    if (!evaluateRoleCondition(conditions.userRole, context.userRole)) {
+      return false
+    }
+  }
+
+  // Check feature flags
+  if (conditions.featureFlags && conditions.featureFlags.length > 0) {
+    if (
+      !evaluateFeatureFlagCondition(
+        conditions.featureFlags,
+        context.featureFlags ?? [],
+      )
+    ) {
+      return false
+    }
+  }
+
+  // Check completed tours
+  if (conditions.completedTours && conditions.completedTours.length > 0) {
+    if (
+      !evaluateCompletedToursCondition(
+        conditions.completedTours,
+        context.completedTourIds,
+      )
+    ) {
+      return false
+    }
+  }
+
+  // Check not-completed tours
+  if (conditions.notCompletedTours && conditions.notCompletedTours.length > 0) {
+    if (
+      !evaluateNotCompletedCondition(
+        conditions.notCompletedTours,
+        context.completedTourIds,
+      )
+    ) {
+      return false
+    }
+  }
+
+  // Check custom condition
+  if (conditions.custom) {
+    if (!conditions.custom(context)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Individual Condition Evaluators
+// ---------------------------------------------------------------------------
+
+/** User role must be in the allowed list */
+export function evaluateRoleCondition(
+  roles: string[],
+  userRole: string | undefined,
+): boolean {
+  if (!userRole) return false
+  return roles.includes(userRole)
+}
+
+/** All specified feature flags must be active */
+export function evaluateFeatureFlagCondition(
+  requiredFlags: string[],
+  activeFlags: string[],
+): boolean {
+  return requiredFlags.every((flag) => activeFlags.includes(flag))
+}
+
+/** All specified tours must be completed */
+export function evaluateCompletedToursCondition(
+  requiredTours: string[],
+  completedTourIds: string[],
+): boolean {
+  return requiredTours.every((tourId) => completedTourIds.includes(tourId))
+}
+
+/** None of the specified tours should be completed */
+export function evaluateNotCompletedCondition(
+  excludedTours: string[],
+  completedTourIds: string[],
+): boolean {
+  return !excludedTours.some((tourId) => completedTourIds.includes(tourId))
+}

package/lib/core.ts

@@ -0,0 +1,323 @@
+/**
+ * WalkMe Core Engine
+ *
+ * Pure-function state machine for managing guided tour state.
+ * All functions are side-effect free and testable without React.
+ */
+
+import type {
+  Tour,
+  TourStep,
+  TourState,
+  WalkmeState,
+  WalkmeAction,
+} from '../types/walkme.types'
+
+// ---------------------------------------------------------------------------
+// Initial State
+// ---------------------------------------------------------------------------
+
+/** Creates a fresh initial WalkmeState */
+export function createInitialState(): WalkmeState {
+  return {
+    tours: {},
+    activeTour: null,
+    completedTours: [],
+    skippedTours: [],
+    tourHistory: {},
+    initialized: false,
+    debug: false,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+/** Main reducer for the WalkMe state machine */
+export function walkmeReducer(state: WalkmeState, action: WalkmeAction): WalkmeState {
+  switch (action.type) {
+    case 'INITIALIZE': {
+      const tours: Record<string, Tour> = {}
+      for (const tour of action.tours) {
+        tours[tour.id] = tour
+      }
+      return { ...state, tours, initialized: true }
+    }
+
+    case 'UPDATE_TOURS': {
+      const tours: Record<string, Tour> = { ...state.tours }
+      for (const tour of action.tours) {
+        tours[tour.id] = tour
+      }
+      return { ...state, tours }
+    }
+
+    case 'START_TOUR': {
+      if (state.activeTour) {
+        if (state.debug) {
+          console.warn(
+            `[WalkMe] Cannot start tour "${action.tourId}" — tour "${state.activeTour.tourId}" is already active. Complete or skip it first.`,
+          )
+        }
+        return state
+      }
+      const tour = state.tours[action.tourId]
+      if (!tour) return state
+      if (tour.steps.length === 0) return state
+
+      const tourState: TourState = {
+        tourId: action.tourId,
+        status: 'active',
+        currentStepIndex: 0,
+        startedAt: new Date().toISOString(),
+      }
+
+      return {
+        ...state,
+        activeTour: tourState,
+        tourHistory: { ...state.tourHistory, [action.tourId]: tourState },
+      }
+    }
+
+    case 'NEXT_STEP': {
+      if (!state.activeTour || state.activeTour.status !== 'active') return state
+      const tour = state.tours[state.activeTour.tourId]
+      if (!tour) return state
+
+      const nextIndex = state.activeTour.currentStepIndex + 1
+
+      // If we've passed the last step, complete the tour
+      if (nextIndex >= tour.steps.length) {
+        return completeTourState(state)
+      }
+
+      const updatedTour: TourState = {
+        ...state.activeTour,
+        currentStepIndex: nextIndex,
+      }
+
+      return {
+        ...state,
+        activeTour: updatedTour,
+        tourHistory: { ...state.tourHistory, [updatedTour.tourId]: updatedTour },
+      }
+    }
+
+    case 'PREV_STEP': {
+      if (!state.activeTour || state.activeTour.status !== 'active') return state
+      if (state.activeTour.currentStepIndex <= 0) return state
+
+      const updatedTour: TourState = {
+        ...state.activeTour,
+        currentStepIndex: state.activeTour.currentStepIndex - 1,
+      }
+
+      return {
+        ...state,
+        activeTour: updatedTour,
+        tourHistory: { ...state.tourHistory, [updatedTour.tourId]: updatedTour },
+      }
+    }
+
+    case 'NAVIGATE_TO_STEP': {
+      if (!state.activeTour || state.activeTour.status !== 'active') return state
+      const tour = state.tours[state.activeTour.tourId]
+      if (!tour) return state
+      if (action.stepIndex < 0 || action.stepIndex >= tour.steps.length) return state
+
+      const updatedTour: TourState = {
+        ...state.activeTour,
+        currentStepIndex: action.stepIndex,
+      }
+
+      return {
+        ...state,
+        activeTour: updatedTour,
+        tourHistory: { ...state.tourHistory, [updatedTour.tourId]: updatedTour },
+      }
+    }
+
+    case 'SKIP_TOUR': {
+      if (!state.activeTour) return state
+
+      const tourId = state.activeTour.tourId
+      const skippedState: TourState = {
+        ...state.activeTour,
+        status: 'skipped',
+        skippedAt: new Date().toISOString(),
+      }
+
+      return {
+        ...state,
+        activeTour: null,
+        skippedTours: state.skippedTours.includes(tourId)
+          ? state.skippedTours
+          : [...state.skippedTours, tourId],
+        tourHistory: { ...state.tourHistory, [tourId]: skippedState },
+      }
+    }
+
+    case 'COMPLETE_TOUR': {
+      if (!state.activeTour) return state
+      return completeTourState(state)
+    }
+
+    case 'PAUSE_TOUR': {
+      if (!state.activeTour || state.activeTour.status !== 'active') return state
+
+      const paused: TourState = {
+        ...state.activeTour,
+        status: 'paused',
+      }
+
+      return {
+        ...state,
+        activeTour: paused,
+        tourHistory: { ...state.tourHistory, [paused.tourId]: paused },
+      }
+    }
+
+    case 'RESUME_TOUR': {
+      if (!state.activeTour || state.activeTour.status !== 'paused') return state
+
+      const resumed: TourState = {
+        ...state.activeTour,
+        status: 'active',
+      }
+
+      return {
+        ...state,
+        activeTour: resumed,
+        tourHistory: { ...state.tourHistory, [resumed.tourId]: resumed },
+      }
+    }
+
+    case 'RESET_TOUR': {
+      const { [action.tourId]: _, ...remainingHistory } = state.tourHistory
+
+      return {
+        ...state,
+        activeTour:
+          state.activeTour?.tourId === action.tourId ? null : state.activeTour,
+        completedTours: state.completedTours.filter((id) => id !== action.tourId),
+        skippedTours: state.skippedTours.filter((id) => id !== action.tourId),
+        tourHistory: remainingHistory,
+      }
+    }
+
+    case 'RESET_ALL': {
+      return {
+        ...state,
+        activeTour: null,
+        completedTours: [],
+        skippedTours: [],
+        tourHistory: {},
+      }
+    }
+
+    case 'SET_DEBUG': {
+      return { ...state, debug: action.enabled }
+    }
+
+    case 'RESTORE_STATE': {
+      return {
+        ...state,
+        completedTours: action.completedTours,
+        skippedTours: action.skippedTours,
+        tourHistory: action.tourHistory,
+        activeTour: action.activeTour,
+      }
+    }
+
+    default:
+      return state
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function completeTourState(state: WalkmeState): WalkmeState {
+  if (!state.activeTour) return state
+
+  const tourId = state.activeTour.tourId
+  const completedState: TourState = {
+    ...state.activeTour,
+    status: 'completed',
+    completedAt: new Date().toISOString(),
+  }
+
+  return {
+    ...state,
+    activeTour: null,
+    completedTours: state.completedTours.includes(tourId)
+      ? state.completedTours
+      : [...state.completedTours, tourId],
+    tourHistory: { ...state.tourHistory, [tourId]: completedState },
+  }
+}
+
+/** Check if a tour can be started */
+export function canStartTour(state: WalkmeState, tourId: string): boolean {
+  if (state.activeTour) return false
+  const tour = state.tours[tourId]
+  if (!tour) return false
+  if (tour.steps.length === 0) return false
+  return true
+}
+
+/** Get the full Tour object for the currently active tour */
+export function getActiveTour(state: WalkmeState): Tour | null {
+  if (!state.activeTour) return null
+  return state.tours[state.activeTour.tourId] ?? null
+}
+
+/** Get the current TourStep for the active tour */
+export function getActiveStep(state: WalkmeState): TourStep | null {
+  const tour = getActiveTour(state)
+  if (!tour || !state.activeTour) return null
+  return tour.steps[state.activeTour.currentStepIndex] ?? null
+}
+
+/** Check if the current step is the first step */
+export function isFirstStep(state: WalkmeState): boolean {
+  if (!state.activeTour) return false
+  return state.activeTour.currentStepIndex === 0
+}
+
+/** Check if the current step is the last step */
+export function isLastStep(state: WalkmeState): boolean {
+  if (!state.activeTour) return false
+  const tour = state.tours[state.activeTour.tourId]
+  if (!tour) return false
+  return state.activeTour.currentStepIndex === tour.steps.length - 1
+}
+
+/** Get progress for a specific tour */
+export function getTourProgress(
+  state: WalkmeState,
+  tourId: string,
+): { current: number; total: number; percentage: number } {
+  const tour = state.tours[tourId]
+  if (!tour) return { current: 0, total: 0, percentage: 0 }
+
+  const total = tour.steps.length
+  const isActive = state.activeTour?.tourId === tourId
+  const current = isActive ? state.activeTour!.currentStepIndex + 1 : 0
+  const percentage = total > 0 ? Math.round((current / total) * 100) : 0
+
+  return { current, total, percentage }
+}
+
+/** Get global progress across all tours */
+export function getGlobalProgress(
+  state: WalkmeState,
+): { completed: number; total: number; percentage: number } {
+  const total = Object.keys(state.tours).length
+  const completed = state.completedTours.length
+  const percentage = total > 0 ? Math.round((completed / total) * 100) : 0
+
+  return { completed, total, percentage }
+}