@nextsparkjs/plugin-walkme 0.1.0-beta.104

package/components/WalkmeSpotlight.tsx

@@ -0,0 +1,188 @@
+'use client'
+
+import { memo, useCallback, useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { TourStep } from '../types/walkme.types'
+import { useStepPositioning, getPlacementFromPosition } from '../lib/positioning'
+import { WalkmeOverlay } from './WalkmeOverlay'
+import { WalkmeProgress } from './WalkmeProgress'
+import { WalkmeControls } from './WalkmeControls'
+
+interface WalkmeSpotlightProps {
+  step: TourStep
+  targetElement: HTMLElement | null
+  onNext: () => void
+  onPrev: () => void
+  onSkip: () => void
+  onComplete: () => void
+  isFirst: boolean
+  isLast: boolean
+  currentIndex: number
+  totalSteps: number
+  labels?: {
+    next?: string
+    prev?: string
+    skip?: string
+    complete?: string
+    progress?: string
+  }
+}
+
+/**
+ * Spotlight/highlight that illuminates a specific element
+ * with an overlay cutout, a subtle glow ring, and a tooltip explanation.
+ * Theme-aware with CSS variables for premium dark/light mode.
+ */
+export const WalkmeSpotlight = memo(function WalkmeSpotlight({
+  step,
+  targetElement,
+  onNext,
+  onPrev,
+  onSkip,
+  onComplete,
+  isFirst,
+  isLast,
+  currentIndex,
+  totalSteps,
+  labels,
+}: WalkmeSpotlightProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  // Single source of truth for target position — shared by overlay and glow ring
+  const [targetRect, setTargetRect] = useState<DOMRect | null>(null)
+
+  const updateRect = useCallback(() => {
+    if (!targetElement) {
+      setTargetRect(null)
+      return
+    }
+    setTargetRect(targetElement.getBoundingClientRect())
+  }, [targetElement])
+
+  useEffect(() => {
+    updateRect()
+    if (!targetElement) return
+
+    const timer = setTimeout(updateRect, 100)
+    const handler = () => updateRect()
+    window.addEventListener('scroll', handler, true)
+    window.addEventListener('resize', handler)
+    return () => {
+      clearTimeout(timer)
+      window.removeEventListener('scroll', handler, true)
+      window.removeEventListener('resize', handler)
+    }
+  }, [targetElement, updateRect])
+
+  const { refs, floatingStyles, isStable } = useStepPositioning(targetElement, {
+    placement: getPlacementFromPosition(step.position ?? 'bottom'),
+    offset: 16,
+    padding: 8,
+  })
+
+  useEffect(() => {
+    if (isStable) containerRef.current?.focus()
+  }, [isStable])
+
+  if (typeof window === 'undefined') return null
+
+  return (
+    <>
+      {/* Overlay with cutout around target */}
+      <WalkmeOverlay
+        visible
+        spotlightTarget={targetElement}
+        spotlightPadding={8}
+        spotlightRect={targetRect}
+      />
+
+      {/* Glow ring around the spotlighted target */}
+      {targetRect && <SpotlightRing rect={targetRect} padding={8} />}
+
+      {/* Tooltip near the target — only render when target is resolved */}
+      {targetElement && createPortal(
+        <div
+          ref={(el) => {
+            refs.setFloating(el)
+            ;(containerRef as React.MutableRefObject<HTMLDivElement | null>).current = el
+          }}
+          data-cy="walkme-spotlight"
+          data-walkme
+          role="dialog"
+          aria-label={step.title}
+          aria-describedby={`walkme-spotlight-content-${step.id}`}
+          tabIndex={-1}
+          className="w-80 max-w-[calc(100vw-2rem)] rounded-xl p-4 outline-none"
+          style={{
+            ...floatingStyles,
+            zIndex: 9999,
+            backgroundColor: 'var(--walkme-bg, #ffffff)',
+            color: 'var(--walkme-text, #111827)',
+            border: '1px solid var(--walkme-border, #e5e7eb)',
+            boxShadow: 'var(--walkme-shadow, 0 20px 25px -5px rgba(0,0,0,.1), 0 8px 10px -6px rgba(0,0,0,.1))',
+            // Hide until floating-ui has stabilized after scroll
+            opacity: isStable ? 1 : 0,
+            transition: 'opacity 150ms ease-out',
+          }}
+        >
+          <h3 className="mb-1 text-sm font-semibold tracking-tight">{step.title}</h3>
+
+          <p
+            id={`walkme-spotlight-content-${step.id}`}
+            className="mb-3 text-sm leading-relaxed"
+            style={{ color: 'var(--walkme-text-muted, #6b7280)' }}
+          >
+            {step.content}
+          </p>
+
+          <div className="mb-3">
+            <WalkmeProgress current={currentIndex} total={totalSteps} progressTemplate={labels?.progress} />
+          </div>
+
+          <WalkmeControls
+            actions={step.actions}
+            onNext={onNext}
+            onPrev={onPrev}
+            onSkip={onSkip}
+            onComplete={onComplete}
+            isFirst={isFirst}
+            isLast={isLast}
+            labels={labels}
+          />
+        </div>,
+        document.body,
+      )}
+    </>
+  )
+})
+
+/**
+ * Subtle animated glow ring rendered around the spotlighted element.
+ * Creates a visual "pulse" that draws the eye to the highlighted area.
+ * Receives pre-computed DOMRect from parent to stay in sync with overlay.
+ */
+function SpotlightRing({
+  rect,
+  padding,
+}: {
+  rect: DOMRect
+  padding: number
+}) {
+  return createPortal(
+    <div
+      data-walkme
+      className="pointer-events-none fixed animate-in fade-in-0 duration-300"
+      style={{
+        zIndex: 9998,
+        top: rect.top - padding,
+        left: rect.left - padding,
+        width: rect.width + padding * 2,
+        height: rect.height + padding * 2,
+        borderRadius: 8,
+        boxShadow: '0 0 0 2px var(--walkme-primary, oklch(0.588 0.243 264.376)), 0 0 16px 4px var(--walkme-primary, oklch(0.588 0.243 264.376 / 0.3))',
+      }}
+      aria-hidden="true"
+    />,
+    document.body,
+  )
+}

package/components/WalkmeTooltip.tsx

@@ -0,0 +1,152 @@
+'use client'
+
+import { memo, useEffect, useRef } from 'react'
+import { createPortal } from 'react-dom'
+import type { TourStep } from '../types/walkme.types'
+import { useStepPositioning, getPlacementFromPosition } from '../lib/positioning'
+import { WalkmeProgress } from './WalkmeProgress'
+import { WalkmeControls } from './WalkmeControls'
+
+interface WalkmeTooltipProps {
+  step: TourStep
+  targetElement: HTMLElement | null
+  onNext: () => void
+  onPrev: () => void
+  onSkip: () => void
+  onComplete: () => void
+  isFirst: boolean
+  isLast: boolean
+  currentIndex: number
+  totalSteps: number
+  labels?: {
+    next?: string
+    prev?: string
+    skip?: string
+    complete?: string
+    progress?: string
+  }
+}
+
+/**
+ * Floating tooltip anchored to a target element.
+ * Uses @floating-ui/react for smart positioning.
+ * Theme-aware with CSS variables for premium dark/light mode.
+ */
+export const WalkmeTooltip = memo(function WalkmeTooltip({
+  step,
+  targetElement,
+  onNext,
+  onPrev,
+  onSkip,
+  onComplete,
+  isFirst,
+  isLast,
+  currentIndex,
+  totalSteps,
+  labels,
+}: WalkmeTooltipProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const { refs, floatingStyles, arrowRef, placement, isStable } = useStepPositioning(
+    targetElement,
+    {
+      placement: getPlacementFromPosition(step.position ?? 'auto'),
+      offset: 12,
+      padding: 8,
+    },
+  )
+
+  // Focus the tooltip when positioning has stabilized
+  useEffect(() => {
+    if (isStable) containerRef.current?.focus()
+  }, [isStable])
+
+  if (typeof window === 'undefined') return null
+  if (!targetElement) return null
+
+  return createPortal(
+    <div
+      ref={(el) => {
+        refs.setFloating(el)
+        ;(containerRef as React.MutableRefObject<HTMLDivElement | null>).current = el
+      }}
+      data-cy="walkme-tooltip"
+      data-walkme
+      role="dialog"
+      aria-label={step.title}
+      aria-describedby={`walkme-tooltip-content-${step.id}`}
+      tabIndex={-1}
+      className="w-80 max-w-[calc(100vw-2rem)] rounded-xl p-4 outline-none"
+      style={{
+        ...floatingStyles,
+        zIndex: 9999,
+        backgroundColor: 'var(--walkme-bg, #ffffff)',
+        color: 'var(--walkme-text, #111827)',
+        border: '1px solid var(--walkme-border, #e5e7eb)',
+        boxShadow: 'var(--walkme-shadow, 0 20px 25px -5px rgba(0,0,0,.1), 0 8px 10px -6px rgba(0,0,0,.1))',
+        // Hide until floating-ui has stabilized after scroll
+        opacity: isStable ? 1 : 0,
+        transition: 'opacity 150ms ease-out',
+      }}
+    >
+      {/* Arrow */}
+      <div
+        ref={arrowRef}
+        className="absolute h-2 w-2 rotate-45"
+        style={{
+          backgroundColor: 'var(--walkme-bg, #ffffff)',
+          ...getArrowBorders(placement),
+        }}
+      />
+
+      {/* Title */}
+      <h3 className="mb-1 text-sm font-semibold tracking-tight">{step.title}</h3>
+
+      {/* Content */}
+      <p
+        id={`walkme-tooltip-content-${step.id}`}
+        className="mb-3 text-sm leading-relaxed"
+        style={{ color: 'var(--walkme-text-muted, #6b7280)' }}
+      >
+        {step.content}
+      </p>
+
+      {/* Progress */}
+      <div className="mb-3">
+        <WalkmeProgress current={currentIndex} total={totalSteps} progressTemplate={labels?.progress} />
+      </div>
+
+      {/* Controls */}
+      <WalkmeControls
+        actions={step.actions}
+        onNext={onNext}
+        onPrev={onPrev}
+        onSkip={onSkip}
+        onComplete={onComplete}
+        isFirst={isFirst}
+        isLast={isLast}
+        labels={labels}
+      />
+    </div>,
+    document.body,
+  )
+})
+
+/** Build individual border-* styles to avoid mixing shorthand + individual properties */
+function getArrowBorders(placement: string): React.CSSProperties {
+  const b = '1px solid var(--walkme-border, #e5e7eb)'
+  if (placement.startsWith('bottom')) {
+    // Arrow points up — show top + left borders
+    return { top: -5, borderTop: b, borderLeft: b, borderBottom: 'none', borderRight: 'none' }
+  }
+  if (placement.startsWith('top')) {
+    // Arrow points down — show bottom + right borders
+    return { bottom: -5, borderBottom: b, borderRight: b, borderTop: 'none', borderLeft: 'none' }
+  }
+  if (placement.startsWith('left')) {
+    // Arrow points right — show right + bottom borders
+    return { right: -5, borderRight: b, borderBottom: b, borderTop: 'none', borderLeft: 'none' }
+  }
+  // Arrow points left — show top + left borders
+  return { left: -5, borderTop: b, borderLeft: b, borderBottom: 'none', borderRight: 'none' }
+}

package/examples/basic-tour.ts

@@ -0,0 +1,38 @@
+import type { Tour } from '../types/walkme.types'
+
+/**
+ * Basic single-page tour example.
+ * Shows a welcome modal, then highlights sidebar navigation and create button.
+ */
+export const basicTour: Tour = {
+  id: 'getting-started',
+  name: 'Getting Started',
+  description: 'Learn the basics of the application',
+  trigger: { type: 'onFirstVisit', delay: 1000 },
+  steps: [
+    {
+      id: 'welcome',
+      type: 'modal',
+      title: 'Welcome!',
+      content: 'Let us show you around the application. This quick tour will help you get started.',
+      actions: ['next', 'skip'],
+    },
+    {
+      id: 'sidebar',
+      type: 'tooltip',
+      target: '[data-cy="sidebar-nav"]',
+      title: 'Navigation',
+      content: 'Use the sidebar to navigate between different sections of the app.',
+      position: 'right',
+      actions: ['next', 'prev', 'skip'],
+    },
+    {
+      id: 'create-btn',
+      type: 'spotlight',
+      target: '[data-cy="create-button"]',
+      title: 'Create New Item',
+      content: 'Click here to create your first item. Give it a try!',
+      actions: ['complete', 'prev'],
+    },
+  ],
+}

package/examples/conditional-tour.ts

@@ -0,0 +1,56 @@
+import type { Tour } from '../types/walkme.types'
+
+/**
+ * Conditional tour example.
+ * Only shown to users with 'admin' role after they've completed the basic tour.
+ */
+export const adminFeaturesTour: Tour = {
+  id: 'admin-features',
+  name: 'Admin Features',
+  description: 'Tour of admin-only functionality',
+  priority: 10,
+  trigger: {
+    type: 'onRouteEnter',
+    route: '/admin/*',
+    delay: 500,
+  },
+  conditions: {
+    userRole: ['admin', 'superadmin'],
+    completedTours: ['getting-started'],
+    featureFlags: ['admin-panel-v2'],
+  },
+  steps: [
+    {
+      id: 'admin-welcome',
+      type: 'modal',
+      title: 'Admin Dashboard',
+      content: 'Welcome to the admin area. Here are the key features available to you.',
+      actions: ['next', 'skip'],
+    },
+    {
+      id: 'user-management',
+      type: 'tooltip',
+      target: '[data-cy="admin-users"]',
+      title: 'User Management',
+      content: 'Manage all user accounts, roles, and permissions from here.',
+      position: 'right',
+      actions: ['next', 'prev', 'skip'],
+    },
+    {
+      id: 'analytics',
+      type: 'spotlight',
+      target: '[data-cy="admin-analytics"]',
+      title: 'Analytics',
+      content: 'View detailed analytics and reports about app usage.',
+      actions: ['next', 'prev', 'skip'],
+    },
+    {
+      id: 'system-config',
+      type: 'beacon',
+      target: '[data-cy="admin-config"]',
+      title: 'System Configuration',
+      content: 'Advanced system settings are available here.',
+      actions: ['complete'],
+    },
+  ],
+}

package/examples/cross-window-tour.ts

@@ -0,0 +1,54 @@
+import type { Tour } from '../types/walkme.types'
+
+/**
+ * Cross-window (multi-page) tour example.
+ * Navigates between dashboard and settings pages.
+ */
+export const crossWindowTour: Tour = {
+  id: 'explore-app',
+  name: 'Explore the App',
+  description: 'Tour across multiple pages',
+  trigger: { type: 'manual' },
+  conditions: {
+    completedTours: ['getting-started'],
+  },
+  steps: [
+    {
+      id: 'dashboard-overview',
+      type: 'modal',
+      title: 'Explore the App',
+      content: "Now that you know the basics, let's explore the key areas of the app.",
+      route: '/dashboard',
+      actions: ['next', 'skip'],
+    },
+    {
+      id: 'dashboard-stats',
+      type: 'tooltip',
+      target: '[data-cy="dashboard-stats"]',
+      title: 'Your Stats',
+      content: 'Here you can see your key metrics at a glance.',
+      position: 'bottom',
+      route: '/dashboard',
+      actions: ['next', 'prev', 'skip'],
+    },
+    {
+      id: 'settings-nav',
+      type: 'tooltip',
+      target: '[data-cy="nav-settings"]',
+      title: 'Settings',
+      content: "Let's head to settings to configure your profile.",
+      position: 'right',
+      route: '/dashboard',
+      actions: ['next', 'prev', 'skip'],
+    },
+    {
+      id: 'profile-settings',
+      type: 'spotlight',
+      target: '[data-cy="profile-form"]',
+      title: 'Your Profile',
+      content: 'Complete your profile information to get the most out of the app.',
+      route: '/settings/profile',
+      actions: ['complete', 'prev'],
+    },
+  ],
+}

package/hooks/useTour.ts

@@ -0,0 +1,52 @@
+'use client'
+
+import { useWalkmeContext } from '../providers/walkme-context'
+
+/**
+ * Hook for accessing the state of a specific tour.
+ *
+ * @param tourId - The ID of the tour to track
+ *
+ * @example
+ * ```tsx
+ * const { isCompleted, progress, start } = useTour('onboarding')
+ *
+ * if (!isCompleted) {
+ *   return <button onClick={start}>Start Onboarding</button>
+ * }
+ * ```
+ */
+export function useTour(tourId: string) {
+  const ctx = useWalkmeContext()
+  const tour = ctx.state.tours[tourId] ?? null
+  const isActive = ctx.state.activeTour?.tourId === tourId
+  const isCompleted = ctx.state.completedTours.includes(tourId)
+  const isSkipped = ctx.state.skippedTours.includes(tourId)
+  const currentStep = isActive ? (ctx.state.activeTour?.currentStepIndex ?? -1) : -1
+  const totalSteps = tour?.steps.length ?? 0
+  const progress =
+    totalSteps > 0 && currentStep >= 0
+      ? Math.round(((currentStep + 1) / totalSteps) * 100)
+      : 0
+
+  return {
+    /** The full tour definition (null if not found) */
+    tour,
+    /** Whether this tour is currently active */
+    isActive,
+    /** Whether this tour has been completed */
+    isCompleted,
+    /** Whether this tour has been skipped */
+    isSkipped,
+    /** Current step index (-1 if not active) */
+    currentStep,
+    /** Total number of steps */
+    totalSteps,
+    /** Progress percentage (0-100) */
+    progress,
+    /** Start this tour */
+    start: () => ctx.startTour(tourId),
+    /** Reset this tour (remove from completed/skipped) */
+    reset: () => ctx.resetTour(tourId),
+  }
+}

package/hooks/useTourProgress.ts

@@ -0,0 +1,38 @@
+'use client'
+
+import { useWalkmeContext } from '../providers/walkme-context'
+
+/**
+ * Hook for tracking global tour completion progress.
+ *
+ * @example
+ * ```tsx
+ * const { completedTours, totalTours, percentage } = useTourProgress()
+ *
+ * return (
+ *   <div>Onboarding: {percentage}% complete ({completedTours}/{totalTours})</div>
+ * )
+ * ```
+ */
+export function useTourProgress() {
+  const ctx = useWalkmeContext()
+  const totalTours = Object.keys(ctx.state.tours).length
+  const completedTours = ctx.state.completedTours.length
+  const percentage =
+    totalTours > 0 ? Math.round((completedTours / totalTours) * 100) : 0
+
+  return {
+    /** Number of completed tours */
+    completedTours,
+    /** Total number of registered tours */
+    totalTours,
+    /** Completion percentage (0-100) */
+    percentage,
+    /** IDs of completed tours */
+    completedTourIds: ctx.state.completedTours,
+    /** IDs of skipped tours */
+    skippedTourIds: ctx.state.skippedTours,
+    /** Number of remaining tours */
+    remainingTours: totalTours - completedTours,
+  }
+}