@nextsparkjs/plugin-walkme 0.1.0-beta.104

package/lib/triggers.ts

@@ -0,0 +1,127 @@
+/**
+ * WalkMe Triggers Module
+ *
+ * Tour trigger evaluation system.
+ * Determines when a tour should be automatically activated.
+ */
+
+import type { Tour, TourTrigger } from '../types/walkme.types'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TriggerEvaluationContext {
+  /** Current page route/pathname */
+  currentRoute: string
+  /** Total number of page visits */
+  visitCount: number
+  /** ISO date string of first visit */
+  firstVisitDate: string | null
+  /** IDs of completed tours */
+  completedTourIds: string[]
+  /** Set of custom events that have been emitted */
+  customEvents: Set<string>
+}
+
+// ---------------------------------------------------------------------------
+// Main Evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate whether a tour should be triggered based on its trigger config
+ * and the current context. Does NOT check conditions (that's a separate step).
+ */
+export function shouldTriggerTour(
+  tour: Tour,
+  context: TriggerEvaluationContext,
+): boolean {
+  const { trigger } = tour
+
+  switch (trigger.type) {
+    case 'onFirstVisit':
+      return evaluateOnFirstVisit(trigger, context)
+    case 'onRouteEnter':
+      return evaluateOnRouteEnter(trigger, context)
+    case 'onEvent':
+      return evaluateOnEvent(trigger, context)
+    case 'manual':
+      return false // Manual tours are started programmatically only
+    case 'scheduled':
+      return evaluateScheduled(trigger, context)
+    default:
+      return false
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Individual Trigger Evaluators
+// ---------------------------------------------------------------------------
+
+/** First visit: triggers only when visitCount === 1 */
+export function evaluateOnFirstVisit(
+  _trigger: TourTrigger,
+  context: TriggerEvaluationContext,
+): boolean {
+  return context.visitCount === 1
+}
+
+/** Route enter: triggers when current route matches the trigger's route pattern */
+export function evaluateOnRouteEnter(
+  trigger: TourTrigger,
+  context: TriggerEvaluationContext,
+): boolean {
+  if (!trigger.route) return false
+
+  const pattern = trigger.route
+  const route = context.currentRoute
+
+  // Exact match
+  if (pattern === route) return true
+
+  // Wildcard match: /dashboard/* matches /dashboard/anything
+  if (pattern.endsWith('/*')) {
+    const prefix = pattern.slice(0, -2)
+    return route.startsWith(prefix)
+  }
+
+  // Glob match: /dashboard/** matches /dashboard/a/b/c
+  if (pattern.endsWith('/**')) {
+    const prefix = pattern.slice(0, -3)
+    return route.startsWith(prefix)
+  }
+
+  return false
+}
+
+/** Event trigger: activates when a specific custom event has been emitted */
+export function evaluateOnEvent(
+  trigger: TourTrigger,
+  context: TriggerEvaluationContext,
+): boolean {
+  if (!trigger.event) return false
+  return context.customEvents.has(trigger.event)
+}
+
+/** Scheduled trigger: activates after N visits or N days since first visit */
+export function evaluateScheduled(
+  trigger: TourTrigger,
+  context: TriggerEvaluationContext,
+): boolean {
+  // Check visit-based threshold
+  if (trigger.afterVisits !== undefined) {
+    if (context.visitCount >= trigger.afterVisits) return true
+  }
+
+  // Check day-based threshold
+  if (trigger.afterDays !== undefined && context.firstVisitDate) {
+    const firstVisit = new Date(context.firstVisitDate)
+    const now = new Date()
+    const daysSinceFirstVisit = Math.floor(
+      (now.getTime() - firstVisit.getTime()) / (1000 * 60 * 60 * 24),
+    )
+    if (daysSinceFirstVisit >= trigger.afterDays) return true
+  }
+
+  return false
+}

package/lib/validation.ts

@@ -0,0 +1,122 @@
+/**
+ * WalkMe Validation Module
+ *
+ * Zod schemas for runtime validation of tour configurations.
+ * Ensures tour definitions are well-formed before they're used.
+ */
+
+import { z } from 'zod'
+import type { Tour, TourStep as TourStepType } from '../types/walkme.types'
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+export const TourTriggerSchema = z.object({
+  type: z.enum(['onFirstVisit', 'onRouteEnter', 'onEvent', 'manual', 'scheduled']),
+  delay: z.number().min(0).optional(),
+  route: z.string().optional(),
+  event: z.string().optional(),
+  afterVisits: z.number().min(1).optional(),
+  afterDays: z.number().min(0).optional(),
+})
+
+export const TourConditionsSchema = z.object({
+  userRole: z.array(z.string()).optional(),
+  featureFlags: z.array(z.string()).optional(),
+  completedTours: z.array(z.string()).optional(),
+  notCompletedTours: z.array(z.string()).optional(),
+  custom: z.function().optional(),
+}).optional()
+
+export const TourStepSchema = z.object({
+  id: z.string().min(1),
+  type: z.enum(['tooltip', 'modal', 'spotlight', 'beacon', 'floating']),
+  title: z.string().min(1),
+  content: z.string(),
+  target: z.string().optional(),
+  route: z.string().optional(),
+  position: z.enum(['top', 'bottom', 'left', 'right', 'auto']).optional(),
+  actions: z.array(z.enum(['next', 'prev', 'skip', 'complete', 'close'])).min(1),
+  delay: z.number().min(0).optional(),
+  autoAdvance: z.number().min(0).optional(),
+  beforeShow: z.function().optional(),
+  afterShow: z.function().optional(),
+}).refine(
+  (step) => {
+    // tooltip, spotlight, and beacon require a target
+    if (['tooltip', 'spotlight', 'beacon'].includes(step.type)) {
+      return !!step.target
+    }
+    return true
+  },
+  {
+    message: 'Steps of type tooltip, spotlight, and beacon require a target selector',
+  },
+)
+
+export const TourSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  trigger: TourTriggerSchema,
+  conditions: TourConditionsSchema,
+  steps: z.array(TourStepSchema).min(1),
+  onComplete: z.function().optional(),
+  onSkip: z.function().optional(),
+  priority: z.number().optional(),
+})
+
+export const TourArraySchema = z.array(TourSchema)
+
+// ---------------------------------------------------------------------------
+// Validation Functions
+// ---------------------------------------------------------------------------
+
+/** Validate a single tour configuration */
+export function validateTour(
+  tour: unknown,
+): { valid: boolean; errors?: z.ZodError; tour?: Tour } {
+  const result = TourSchema.safeParse(tour)
+  if (result.success) {
+    // Zod's output matches our Tour type structurally; functions (onComplete,
+    // onSkip, beforeShow, afterShow, custom) are validated as z.function() but
+    // their signatures aren't preserved in the inferred type, so we cast once here.
+    return { valid: true, tour: result.data as Tour }
+  }
+  return { valid: false, errors: result.error }
+}
+
+/** Validate an array of tours, returning only the valid ones */
+export function validateTours(
+  tours: unknown[],
+): { valid: boolean; errors?: z.ZodError[]; validTours: Tour[] } {
+  const validTours: Tour[] = []
+  const errors: z.ZodError[] = []
+
+  for (const tour of tours) {
+    const result = TourSchema.safeParse(tour)
+    if (result.success) {
+      validTours.push(result.data as Tour)
+    } else {
+      errors.push(result.error)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+    validTours,
+  }
+}
+
+/** Validate a single step configuration */
+export function validateStep(
+  step: unknown,
+): { valid: boolean; errors?: z.ZodError; step?: TourStepType } {
+  const result = TourStepSchema.safeParse(step)
+  if (result.success) {
+    return { valid: true, step: result.data as TourStepType }
+  }
+  return { valid: false, errors: result.error }
+}

package/messages/en.json

@@ -0,0 +1,21 @@
+{
+  "walkme": {
+    "next": "Next",
+    "prev": "Previous",
+    "skip": "Skip tour",
+    "complete": "Complete",
+    "close": "Close",
+    "progress": "Step {current} of {total}",
+    "tourAvailable": "Tour available",
+    "beaconLabel": "Click to start guided tour",
+    "modalTitle": "Guided Tour",
+    "tooltipLabel": "Tour step",
+    "spotlightLabel": "Highlighted element",
+    "keyboardHint": "Press Arrow Right for next step, Escape to skip",
+    "tourCompleted": "Tour completed!",
+    "tourSkipped": "Tour skipped",
+    "errorTargetNotFound": "Element not found, skipping step",
+    "resumeTour": "Resume tour",
+    "restartTour": "Restart tour"
+  }
+}

package/messages/es.json

@@ -0,0 +1,21 @@
+{
+  "walkme": {
+    "next": "Siguiente",
+    "prev": "Anterior",
+    "skip": "Saltar tour",
+    "complete": "Completar",
+    "close": "Cerrar",
+    "progress": "Paso {current} de {total}",
+    "tourAvailable": "Tour disponible",
+    "beaconLabel": "Haz clic para iniciar el tour guiado",
+    "modalTitle": "Tour Guiado",
+    "tooltipLabel": "Paso del tour",
+    "spotlightLabel": "Elemento destacado",
+    "keyboardHint": "Presiona flecha derecha para siguiente paso, Escape para saltar",
+    "tourCompleted": "Tour completado!",
+    "tourSkipped": "Tour saltado",
+    "errorTargetNotFound": "Elemento no encontrado, saltando paso",
+    "resumeTour": "Reanudar tour",
+    "restartTour": "Reiniciar tour"
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@nextsparkjs/plugin-walkme",
+  "version": "0.1.0-beta.104",
+  "private": false,
+  "main": "./plugin.config.ts",
+  "requiredPlugins": [],
+  "dependencies": {},
+  "peerDependencies": {
+    "@phosphor-icons/react": "^2.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "nextspark": {
+    "type": "plugin",
+    "name": "walkme"
+  }
+}

package/plugin.config.ts

@@ -0,0 +1,26 @@
+/**
+ * WalkMe Plugin Configuration
+ *
+ * Guided tours and onboarding system for NextSpark applications.
+ * Provides declarative tour definitions, multi-step tooltips, modals,
+ * spotlights, beacons, cross-page navigation, and full persistence.
+ */
+
+import type { PluginConfig } from '@nextsparkjs/core/types/plugin'
+
+export const walkmePluginConfig: PluginConfig = {
+  name: 'walkme',
+  displayName: 'WalkMe',
+  version: '1.0.0',
+  description: 'Guided tours and onboarding system for NextSpark applications',
+  enabled: true,
+  dependencies: [],
+  api: {},
+  hooks: {
+    onLoad: async () => {
+      console.log('[WalkMe Plugin] Loaded - guided tours system ready')
+    },
+  },
+}
+
+export default walkmePluginConfig

package/providers/walkme-context.ts

@@ -0,0 +1,17 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+import type { WalkmeContextValue } from '../types/walkme.types'
+
+export const WalkmeContext = createContext<WalkmeContextValue | null>(null)
+
+export function useWalkmeContext(): WalkmeContextValue {
+  const context = useContext(WalkmeContext)
+  if (!context) {
+    throw new Error(
+      'useWalkmeContext must be used within a <WalkmeProvider>. ' +
+        'Wrap your app or page with <WalkmeProvider tours={[...]}> to use WalkMe hooks.',
+    )
+  }
+  return context
+}

package/tests/lib/conditions.test.ts

@@ -0,0 +1,172 @@
+import type { ConditionContext, TourConditions } from '../../types/walkme.types'
+import {
+  evaluateConditions,
+  evaluateRoleCondition,
+  evaluateFeatureFlagCondition,
+  evaluateCompletedToursCondition,
+  evaluateNotCompletedCondition,
+} from '../../lib/conditions'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function createContext(overrides: Partial<ConditionContext> = {}): ConditionContext {
+  return {
+    userRole: 'user',
+    featureFlags: [],
+    completedTourIds: [],
+    visitCount: 1,
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// evaluateConditions (integration)
+// ---------------------------------------------------------------------------
+
+describe('evaluateConditions', () => {
+  it('returns true when conditions is undefined', () => {
+    expect(evaluateConditions(undefined, createContext())).toBe(true)
+  })
+
+  it('returns true when conditions is empty object', () => {
+    expect(evaluateConditions({}, createContext())).toBe(true)
+  })
+
+  it('returns true when all conditions pass', () => {
+    const conditions: TourConditions = {
+      userRole: ['admin', 'superadmin'],
+      featureFlags: ['feature-a'],
+      completedTours: ['onboarding'],
+    }
+    const ctx = createContext({
+      userRole: 'admin',
+      featureFlags: ['feature-a', 'feature-b'],
+      completedTourIds: ['onboarding'],
+    })
+    expect(evaluateConditions(conditions, ctx)).toBe(true)
+  })
+
+  it('returns false when role check fails (AND logic)', () => {
+    const conditions: TourConditions = {
+      userRole: ['admin'],
+      featureFlags: ['feature-a'],
+    }
+    const ctx = createContext({
+      userRole: 'user',
+      featureFlags: ['feature-a'],
+    })
+    expect(evaluateConditions(conditions, ctx)).toBe(false)
+  })
+
+  it('returns false when feature flag check fails', () => {
+    const conditions: TourConditions = {
+      featureFlags: ['feature-x'],
+    }
+    const ctx = createContext({ featureFlags: ['feature-y'] })
+    expect(evaluateConditions(conditions, ctx)).toBe(false)
+  })
+
+  it('returns false when completedTours check fails', () => {
+    const conditions: TourConditions = {
+      completedTours: ['required-tour'],
+    }
+    const ctx = createContext({ completedTourIds: [] })
+    expect(evaluateConditions(conditions, ctx)).toBe(false)
+  })
+
+  it('returns false when notCompletedTours check fails', () => {
+    const conditions: TourConditions = {
+      notCompletedTours: ['excluded-tour'],
+    }
+    const ctx = createContext({ completedTourIds: ['excluded-tour'] })
+    expect(evaluateConditions(conditions, ctx)).toBe(false)
+  })
+
+  it('evaluates custom condition function', () => {
+    const conditions: TourConditions = {
+      custom: (ctx) => ctx.visitCount > 3,
+    }
+    expect(evaluateConditions(conditions, createContext({ visitCount: 5 }))).toBe(true)
+    expect(evaluateConditions(conditions, createContext({ visitCount: 1 }))).toBe(false)
+  })
+
+  it('skips empty arrays in conditions', () => {
+    const conditions: TourConditions = {
+      userRole: [],
+      featureFlags: [],
+      completedTours: [],
+      notCompletedTours: [],
+    }
+    expect(evaluateConditions(conditions, createContext())).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// evaluateRoleCondition
+// ---------------------------------------------------------------------------
+
+describe('evaluateRoleCondition', () => {
+  it('returns true when user role is in allowed list', () => {
+    expect(evaluateRoleCondition(['admin', 'editor'], 'admin')).toBe(true)
+  })
+
+  it('returns false when user role is not in allowed list', () => {
+    expect(evaluateRoleCondition(['admin', 'editor'], 'user')).toBe(false)
+  })
+
+  it('returns false when user role is undefined', () => {
+    expect(evaluateRoleCondition(['admin'], undefined)).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// evaluateFeatureFlagCondition
+// ---------------------------------------------------------------------------
+
+describe('evaluateFeatureFlagCondition', () => {
+  it('returns true when all required flags are active', () => {
+    expect(evaluateFeatureFlagCondition(['a', 'b'], ['a', 'b', 'c'])).toBe(true)
+  })
+
+  it('returns false when a required flag is missing', () => {
+    expect(evaluateFeatureFlagCondition(['a', 'b'], ['a'])).toBe(false)
+  })
+
+  it('returns true when required flags is empty', () => {
+    expect(evaluateFeatureFlagCondition([], ['a'])).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// evaluateCompletedToursCondition
+// ---------------------------------------------------------------------------
+
+describe('evaluateCompletedToursCondition', () => {
+  it('returns true when all required tours are completed', () => {
+    expect(evaluateCompletedToursCondition(['t1', 't2'], ['t1', 't2', 't3'])).toBe(true)
+  })
+
+  it('returns false when a required tour is not completed', () => {
+    expect(evaluateCompletedToursCondition(['t1', 't2'], ['t1'])).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// evaluateNotCompletedCondition
+// ---------------------------------------------------------------------------
+
+describe('evaluateNotCompletedCondition', () => {
+  it('returns true when none of the excluded tours are completed', () => {
+    expect(evaluateNotCompletedCondition(['t1', 't2'], ['t3'])).toBe(true)
+  })
+
+  it('returns false when any excluded tour is completed', () => {
+    expect(evaluateNotCompletedCondition(['t1', 't2'], ['t2'])).toBe(false)
+  })
+
+  it('returns true when excluded list is empty', () => {
+    expect(evaluateNotCompletedCondition([], ['t1'])).toBe(true)
+  })
+})