@nextsparkjs/plugin-walkme 0.1.0-beta.104

package/lib/plugin-env.ts

@@ -0,0 +1,87 @@
+/**
+ * WalkMe Plugin Environment Configuration
+ *
+ * Uses centralized plugin environment loader from core.
+ * Provides type-safe access to WalkMe configuration.
+ */
+
+import { getPluginEnv } from '@nextsparkjs/core/lib/plugins/env-loader'
+
+interface WalkmePluginEnvConfig {
+  WALKME_ENABLED?: string
+  WALKME_DEBUG?: string
+  WALKME_AUTO_START?: string
+  WALKME_AUTO_START_DELAY?: string
+  WALKME_PERSIST_STATE?: string
+  WALKME_ANALYTICS_ENABLED?: string
+}
+
+class PluginEnvironment {
+  private static instance: PluginEnvironment
+  private config: WalkmePluginEnvConfig = {}
+  private loaded = false
+
+  private constructor() {
+    this.loadEnvironment()
+  }
+
+  public static getInstance(): PluginEnvironment {
+    if (!PluginEnvironment.instance) {
+      PluginEnvironment.instance = new PluginEnvironment()
+    }
+    return PluginEnvironment.instance
+  }
+
+  private loadEnvironment(forceReload: boolean = false): void {
+    if (this.loaded && !forceReload) return
+
+    try {
+      const env = getPluginEnv('walkme')
+
+      this.config = {
+        WALKME_ENABLED: env.WALKME_ENABLED || 'true',
+        WALKME_DEBUG: env.WALKME_DEBUG || 'false',
+        WALKME_AUTO_START: env.WALKME_AUTO_START || 'true',
+        WALKME_AUTO_START_DELAY: env.WALKME_AUTO_START_DELAY || '1000',
+        WALKME_PERSIST_STATE: env.WALKME_PERSIST_STATE || 'true',
+        WALKME_ANALYTICS_ENABLED: env.WALKME_ANALYTICS_ENABLED || 'false',
+      }
+
+      this.loaded = true
+    } catch (error) {
+      console.error('[WalkMe Plugin] Failed to load environment:', error)
+      this.loaded = true
+    }
+  }
+
+  public isPluginEnabled(): boolean {
+    return this.config.WALKME_ENABLED !== 'false'
+  }
+
+  public isDebugEnabled(): boolean {
+    return this.config.WALKME_DEBUG === 'true'
+  }
+
+  public isAutoStartEnabled(): boolean {
+    return this.config.WALKME_AUTO_START === 'true'
+  }
+
+  public getAutoStartDelay(): number {
+    return parseInt(this.config.WALKME_AUTO_START_DELAY || '1000', 10)
+  }
+
+  public isPersistStateEnabled(): boolean {
+    return this.config.WALKME_PERSIST_STATE !== 'false'
+  }
+
+  public isAnalyticsEnabled(): boolean {
+    return this.config.WALKME_ANALYTICS_ENABLED === 'true'
+  }
+
+  public reload(): void {
+    this.loaded = false
+    this.loadEnvironment(true)
+  }
+}
+
+export const pluginEnv = PluginEnvironment.getInstance()

package/lib/positioning.ts

@@ -0,0 +1,172 @@
+/**
+ * WalkMe Positioning Module
+ *
+ * Wrapper around @floating-ui/react for smart element positioning.
+ * Handles auto-flip, scroll tracking, viewport containment, and arrow placement.
+ */
+
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import {
+  useFloating,
+  autoUpdate,
+  offset,
+  flip,
+  shift,
+  arrow,
+  type Placement,
+} from '@floating-ui/react'
+import type { StepPosition } from '../types/walkme.types'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PositionConfig {
+  placement: Placement
+  offset?: number
+  padding?: number
+  fallbackPlacements?: Placement[]
+}
+
+export interface StepPositioningResult {
+  refs: {
+    setReference: (el: HTMLElement | null) => void
+    setFloating: (el: HTMLElement | null) => void
+  }
+  floatingStyles: React.CSSProperties
+  placement: Placement
+  isPositioned: boolean
+  arrowRef: React.RefObject<HTMLDivElement | null>
+  middlewareData: Record<string, unknown>
+  /** Force a position recalculation (useful after scroll/resize settles) */
+  update: () => void
+  /** Whether floating-ui has had time to stabilize after scroll */
+  isStable: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/** Map StepPosition to @floating-ui Placement */
+export function getPlacementFromPosition(position: StepPosition): Placement {
+  switch (position) {
+    case 'top':
+      return 'top'
+    case 'bottom':
+      return 'bottom'
+    case 'left':
+      return 'left'
+    case 'right':
+      return 'right'
+    case 'auto':
+    default:
+      return 'bottom'
+  }
+}
+
+/** Get current viewport information */
+export function getViewportInfo(): {
+  width: number
+  height: number
+  scrollX: number
+  scrollY: number
+} {
+  if (typeof window === 'undefined') {
+    return { width: 0, height: 0, scrollX: 0, scrollY: 0 }
+  }
+  return {
+    width: window.innerWidth,
+    height: window.innerHeight,
+    scrollX: window.scrollX,
+    scrollY: window.scrollY,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Hook for positioning a floating step element relative to a target.
+ * Wraps @floating-ui/react with sensible defaults for WalkMe steps.
+ *
+ * IMPORTANT: Does NOT pass targetElement directly to useFloating's
+ * `elements.reference`. Instead, sets the reference imperatively after
+ * a short delay so that any scrollIntoView triggered by the provider
+ * has fully settled. This prevents stale position computation on
+ * backward navigation.
+ */
+export function useStepPositioning(
+  targetElement: HTMLElement | null,
+  config: PositionConfig,
+): StepPositioningResult {
+  const arrowRef = useRef<HTMLDivElement>(null)
+  const [isStable, setIsStable] = useState(false)
+
+  const { refs, floatingStyles, placement, isPositioned, middlewareData, update } =
+    useFloating({
+      placement: config.placement,
+      // DO NOT set elements.reference here — we set it imperatively below
+      // so floating-ui computes position AFTER scroll has settled.
+      whileElementsMounted: autoUpdate,
+      middleware: [
+        offset(config.offset ?? 8),
+        flip({
+          fallbackPlacements: config.fallbackPlacements,
+          padding: config.padding ?? 8,
+        }),
+        shift({ padding: config.padding ?? 8 }),
+        arrow({ element: arrowRef }),
+      ],
+    })
+
+  // Set reference imperatively after scroll settles
+  useEffect(() => {
+    setIsStable(false)
+
+    if (!targetElement) {
+      refs.setReference(null)
+      return
+    }
+
+    // Double rAF ensures any scrollIntoView (even 'instant') has
+    // fully reflowed the layout before we hand the element to floating-ui.
+    let cancelled = false
+    const rafIds = { outer: 0, inner: 0, stable: 0 }
+
+    rafIds.outer = requestAnimationFrame(() => {
+      rafIds.inner = requestAnimationFrame(() => {
+        if (cancelled) return
+        refs.setReference(targetElement)
+        // One more rAF for floating-ui to compute, then mark stable
+        rafIds.stable = requestAnimationFrame(() => {
+          if (!cancelled) setIsStable(true)
+        })
+      })
+    })
+
+    return () => {
+      cancelled = true
+      cancelAnimationFrame(rafIds.outer)
+      cancelAnimationFrame(rafIds.inner)
+      cancelAnimationFrame(rafIds.stable)
+    }
+  }, [targetElement, refs])
+
+  return {
+    refs: {
+      setReference: refs.setReference,
+      setFloating: refs.setFloating,
+    },
+    floatingStyles,
+    placement,
+    isPositioned,
+    arrowRef,
+    middlewareData,
+    update,
+    isStable,
+  }
+}

package/lib/storage.ts

@@ -0,0 +1,203 @@
+/**
+ * WalkMe Storage Module
+ *
+ * localStorage persistence adapter for tour state.
+ * Handles save/load, schema versioning, and graceful SSR fallbacks.
+ */
+
+import type { TourState, StorageSchema } from '../types/walkme.types'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const STORAGE_KEY_PREFIX = 'walkme-state'
+const STORAGE_VERSION = 1
+
+/** Build the localStorage key, optionally scoped to a userId */
+function getStorageKey(userId?: string): string {
+  return userId ? `${STORAGE_KEY_PREFIX}-${userId}` : STORAGE_KEY_PREFIX
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface StorageAdapter {
+  load(): StorageSchema | null
+  save(state: StorageSchema): void
+  reset(): void
+  resetTour(tourId: string): void
+  getCompletedTours(): string[]
+  getSkippedTours(): string[]
+  getVisitCount(): number
+  incrementVisitCount(): void
+  getFirstVisitDate(): string | null
+  setFirstVisitDate(date: string): void
+  getActiveTour(): TourState | null
+  setActiveTour(tour: TourState | null): void
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/** Check if localStorage is available */
+export function isStorageAvailable(): boolean {
+  if (typeof window === 'undefined') return false
+  try {
+    const testKey = '__walkme_test__'
+    window.localStorage.setItem(testKey, '1')
+    window.localStorage.removeItem(testKey)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Create a default empty storage schema */
+function createDefaultSchema(): StorageSchema {
+  return {
+    version: STORAGE_VERSION,
+    completedTours: [],
+    skippedTours: [],
+    activeTour: null,
+    tourHistory: {},
+    visitCount: 0,
+    firstVisitDate: new Date().toISOString(),
+  }
+}
+
+/** Migrate storage data from older versions */
+export function migrateStorage(data: unknown): StorageSchema {
+  if (!data || typeof data !== 'object') {
+    return createDefaultSchema()
+  }
+
+  const record = data as Record<string, unknown>
+
+  // Version 1 (current) - no migration needed, just validate shape
+  return {
+    version: STORAGE_VERSION,
+    completedTours: Array.isArray(record.completedTours)
+      ? (record.completedTours as string[])
+      : [],
+    skippedTours: Array.isArray(record.skippedTours)
+      ? (record.skippedTours as string[])
+      : [],
+    activeTour: record.activeTour as TourState | null ?? null,
+    tourHistory:
+      (record.tourHistory as Record<string, TourState>) ?? {},
+    visitCount:
+      typeof record.visitCount === 'number' ? record.visitCount : 0,
+    firstVisitDate:
+      typeof record.firstVisitDate === 'string'
+        ? record.firstVisitDate
+        : new Date().toISOString(),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/** Create a storage adapter backed by localStorage, optionally scoped to a user */
+export function createStorageAdapter(userId?: string): StorageAdapter {
+  const available = isStorageAvailable()
+  const storageKey = getStorageKey(userId)
+
+  function read(): StorageSchema {
+    if (!available) return createDefaultSchema()
+
+    try {
+      const raw = window.localStorage.getItem(storageKey)
+      if (!raw) return createDefaultSchema()
+
+      const parsed = JSON.parse(raw)
+      return migrateStorage(parsed)
+    } catch {
+      return createDefaultSchema()
+    }
+  }
+
+  function write(schema: StorageSchema): void {
+    if (!available) return
+
+    try {
+      window.localStorage.setItem(storageKey, JSON.stringify(schema))
+    } catch {
+      // Storage full or unavailable - silently ignore
+    }
+  }
+
+  return {
+    load(): StorageSchema | null {
+      if (!available) return null
+      return read()
+    },
+
+    save(state: StorageSchema): void {
+      write(state)
+    },
+
+    reset(): void {
+      if (!available) return
+      try {
+        window.localStorage.removeItem(storageKey)
+      } catch {
+        // Ignore
+      }
+    },
+
+    resetTour(tourId: string): void {
+      const state = read()
+      state.completedTours = state.completedTours.filter((id) => id !== tourId)
+      state.skippedTours = state.skippedTours.filter((id) => id !== tourId)
+      const { [tourId]: _, ...remainingHistory } = state.tourHistory
+      state.tourHistory = remainingHistory
+      if (state.activeTour?.tourId === tourId) {
+        state.activeTour = null
+      }
+      write(state)
+    },
+
+    getCompletedTours(): string[] {
+      return read().completedTours
+    },
+
+    getSkippedTours(): string[] {
+      return read().skippedTours
+    },
+
+    getVisitCount(): number {
+      return read().visitCount
+    },
+
+    incrementVisitCount(): void {
+      const state = read()
+      state.visitCount += 1
+      write(state)
+    },
+
+    getFirstVisitDate(): string | null {
+      const state = read()
+      return state.firstVisitDate || null
+    },
+
+    setFirstVisitDate(date: string): void {
+      const state = read()
+      state.firstVisitDate = date
+      write(state)
+    },
+
+    getActiveTour(): TourState | null {
+      return read().activeTour
+    },
+
+    setActiveTour(tour: TourState | null): void {
+      const state = read()
+      state.activeTour = tour
+      write(state)
+    },
+  }
+}

package/lib/targeting.ts

@@ -0,0 +1,186 @@
+/**
+ * WalkMe Targeting Module
+ *
+ * DOM element targeting utilities for finding, waiting for,
+ * and interacting with target elements for tour steps.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TargetResult {
+  element: HTMLElement | null
+  found: boolean
+  selector: string
+  method: 'css' | 'data-walkme' | 'data-cy'
+}
+
+export interface WaitForTargetOptions {
+  /** Maximum time to wait in ms (default: 5000) */
+  timeout?: number
+  /** Polling interval in ms (default: 200) */
+  interval?: number
+}
+
+// ---------------------------------------------------------------------------
+// Element Finding
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a target element using various selector strategies.
+ *
+ * Supports:
+ * 1. CSS selectors: `#id`, `.class`, `[attribute="value"]`
+ * 2. Data-walkme attribute shorthand: if selector has no CSS special chars,
+ *    tries `[data-walkme-target="selector"]` first
+ * 3. Data-cy attribute: `[data-cy="value"]`
+ */
+export function findTarget(selector: string): TargetResult {
+  if (typeof window === 'undefined') {
+    return { element: null, found: false, selector, method: 'css' }
+  }
+
+  // Try data-walkme-target first if selector looks like a plain name
+  if (/^[a-zA-Z0-9_-]+$/.test(selector)) {
+    const walkmeEl = document.querySelector<HTMLElement>(
+      `[data-walkme-target="${selector}"]`,
+    )
+    if (walkmeEl) {
+      return { element: walkmeEl, found: true, selector, method: 'data-walkme' }
+    }
+  }
+
+  // Try as CSS selector
+  try {
+    const el = document.querySelector<HTMLElement>(selector)
+    if (el) {
+      const method = selector.includes('data-cy') ? 'data-cy' : 'css'
+      return { element: el, found: true, selector, method }
+    }
+  } catch {
+    // Invalid selector - return not found
+  }
+
+  return { element: null, found: false, selector, method: 'css' }
+}
+
+/**
+ * Wait for a target element to appear in the DOM.
+ * Uses MutationObserver for efficient watching.
+ */
+export function waitForTarget(
+  selector: string,
+  options: WaitForTargetOptions = {},
+): Promise<TargetResult> {
+  const { timeout = 5000, interval = 200 } = options
+
+  return new Promise((resolve) => {
+    // Try immediately first
+    const immediate = findTarget(selector)
+    if (immediate.found) {
+      resolve(immediate)
+      return
+    }
+
+    if (typeof window === 'undefined') {
+      resolve({ element: null, found: false, selector, method: 'css' })
+      return
+    }
+
+    let resolved = false
+    let observer: MutationObserver | null = null
+    let timeoutId: ReturnType<typeof setTimeout> | null = null
+    let intervalId: ReturnType<typeof setInterval> | null = null
+
+    const cleanup = () => {
+      resolved = true
+      observer?.disconnect()
+      if (timeoutId) clearTimeout(timeoutId)
+      if (intervalId) clearInterval(intervalId)
+    }
+
+    // Set up timeout
+    timeoutId = setTimeout(() => {
+      if (!resolved) {
+        cleanup()
+        resolve({ element: null, found: false, selector, method: 'css' })
+      }
+    }, timeout)
+
+    // Poll as a fallback (MutationObserver doesn't catch everything)
+    intervalId = setInterval(() => {
+      if (resolved) return
+      const result = findTarget(selector)
+      if (result.found) {
+        cleanup()
+        resolve(result)
+      }
+    }, interval)
+
+    // MutationObserver for immediate detection
+    observer = new MutationObserver(() => {
+      if (resolved) return
+      const result = findTarget(selector)
+      if (result.found) {
+        cleanup()
+        resolve(result)
+      }
+    })
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-walkme-target', 'data-cy', 'id', 'class'],
+    })
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Element Utilities
+// ---------------------------------------------------------------------------
+
+/** Check if an element is visible (not hidden by CSS) */
+export function isElementVisible(element: HTMLElement): boolean {
+  if (typeof window === 'undefined') return false
+
+  const style = window.getComputedStyle(element)
+  return (
+    style.display !== 'none' &&
+    style.visibility !== 'hidden' &&
+    style.opacity !== '0' &&
+    element.offsetParent !== null
+  )
+}
+
+/** Check if an element is within the current viewport */
+export function isElementInViewport(element: HTMLElement): boolean {
+  if (typeof window === 'undefined') return false
+
+  const rect = element.getBoundingClientRect()
+  return (
+    rect.top >= 0 &&
+    rect.left >= 0 &&
+    rect.bottom <= window.innerHeight &&
+    rect.right <= window.innerWidth
+  )
+}
+
+/** Scroll the viewport to make an element visible */
+export function scrollToElement(
+  element: HTMLElement,
+  options: { behavior?: ScrollBehavior; block?: ScrollLogicalPosition } = {},
+): void {
+  if (typeof window === 'undefined') return
+
+  element.scrollIntoView({
+    behavior: options.behavior ?? 'instant',
+    block: options.block ?? 'center',
+  })
+}
+
+/** Get the bounding rect of an element */
+export function getElementRect(element: HTMLElement): DOMRect {
+  return element.getBoundingClientRect()
+}