@nextsparkjs/plugin-walkme 0.1.0-beta.104

package/components/WalkmeBeacon.tsx

@@ -0,0 +1,64 @@
+'use client'
+
+import { memo } from 'react'
+import { createPortal } from 'react-dom'
+import type { TourStep } from '../types/walkme.types'
+import { useStepPositioning } from '../lib/positioning'
+
+interface WalkmeBeaconProps {
+  step: TourStep
+  targetElement: HTMLElement | null
+  onClick: () => void
+  labels?: {
+    tourAvailable?: string
+  }
+}
+
+/**
+ * Pulsing beacon/hotspot indicator near a target element.
+ * Clicking it starts or advances the tour.
+ */
+export const WalkmeBeacon = memo(function WalkmeBeacon({
+  step,
+  targetElement,
+  onClick,
+  labels,
+}: WalkmeBeaconProps) {
+  const { refs, floatingStyles } = useStepPositioning(targetElement, {
+    placement: 'top-end',
+    offset: 4,
+    padding: 8,
+  })
+
+  if (typeof window === 'undefined') return null
+
+  return createPortal(
+    <button
+      ref={refs.setFloating}
+      data-cy="walkme-beacon"
+      data-walkme
+      onClick={onClick}
+      type="button"
+      role="button"
+      aria-label={step.title || labels?.tourAvailable || 'Tour available'}
+      tabIndex={0}
+      className="cursor-pointer relative flex h-6 w-6 items-center justify-center rounded-full outline-none"
+      style={{
+        ...floatingStyles,
+        zIndex: 9999,
+      }}
+    >
+      {/* Pulse ring */}
+      <span
+        className="absolute inset-0 animate-ping rounded-full opacity-75"
+        style={{ backgroundColor: 'var(--walkme-beacon-color, #3b82f6)' }}
+      />
+      {/* Core dot */}
+      <span
+        className="relative h-3 w-3 rounded-full"
+        style={{ backgroundColor: 'var(--walkme-beacon-color, #3b82f6)' }}
+      />
+    </button>,
+    document.body,
+  )
+})

package/components/WalkmeControls.tsx

@@ -0,0 +1,111 @@
+'use client'
+
+import { memo } from 'react'
+import type { StepAction } from '../types/walkme.types'
+
+interface WalkmeControlsProps {
+  actions: StepAction[]
+  onNext: () => void
+  onPrev: () => void
+  onSkip: () => void
+  onComplete: () => void
+  isFirst: boolean
+  isLast: boolean
+  labels?: {
+    next?: string
+    prev?: string
+    skip?: string
+    complete?: string
+  }
+}
+
+/**
+ * Navigation button group for tour steps.
+ * Premium styling with hover/active states and proper spacing.
+ */
+export const WalkmeControls = memo(function WalkmeControls({
+  actions,
+  onNext,
+  onPrev,
+  onSkip,
+  onComplete,
+  isFirst,
+  isLast,
+  labels,
+}: WalkmeControlsProps) {
+  const showPrev = actions.includes('prev') && !isFirst
+  const showNext = actions.includes('next') && !isLast
+  const showSkip = actions.includes('skip')
+  const showComplete =
+    actions.includes('complete') || (isLast && actions.includes('next'))
+
+  return (
+    <div
+      data-cy="walkme-controls"
+      data-walkme
+      className="flex items-center justify-between gap-2"
+    >
+      <div className="flex gap-2">
+        {showSkip && (
+          <button
+            data-cy="walkme-btn-skip"
+            onClick={onSkip}
+            type="button"
+            className="cursor-pointer rounded-lg px-3 py-1.5 text-sm transition-all duration-150 hover:opacity-80 active:scale-95"
+            style={{
+              color: 'var(--walkme-text-muted, #6b7280)',
+              backgroundColor: 'transparent',
+            }}
+          >
+            {labels?.skip ?? 'Skip'}
+          </button>
+        )}
+      </div>
+
+      <div className="flex gap-2">
+        {showPrev && (
+          <button
+            data-cy="walkme-btn-prev"
+            onClick={onPrev}
+            type="button"
+            className="cursor-pointer rounded-lg px-3.5 py-1.5 text-sm font-medium transition-all duration-150 hover:opacity-90 active:scale-95"
+            style={{
+              color: 'var(--walkme-text, #111827)',
+              backgroundColor: 'var(--walkme-border, #e5e7eb)',
+            }}
+          >
+            {labels?.prev ?? 'Previous'}
+          </button>
+        )}
+
+        {showNext && (
+          <button
+            data-cy="walkme-btn-next"
+            onClick={onNext}
+            type="button"
+            className="cursor-pointer rounded-lg px-4 py-1.5 text-sm font-semibold text-white transition-all duration-150 hover:brightness-110 active:scale-95"
+            style={{
+              backgroundColor: 'var(--walkme-primary, #3b82f6)',
+            }}
+          >
+            {labels?.next ?? 'Next'}
+          </button>
+        )}
+
+        {showComplete && (
+          <button
+            data-cy="walkme-btn-complete"
+            onClick={onComplete}
+            type="button"
+            className="cursor-pointer rounded-lg px-4 py-1.5 text-sm font-semibold text-white transition-all duration-150 hover:brightness-110 active:scale-95"
+            style={{
+              backgroundColor: 'var(--walkme-primary, #3b82f6)',
+            }}
+          >
+            {labels?.complete ?? 'Complete'}
+          </button>
+        )}
+      </div>
+    </div>
+  )
+})

package/components/WalkmeModal.tsx

@@ -0,0 +1,144 @@
+'use client'
+
+import { memo, useEffect, useRef } from 'react'
+import { createPortal } from 'react-dom'
+import { X } from '@phosphor-icons/react'
+import type { TourStep } from '../types/walkme.types'
+import { WalkmeProgress } from './WalkmeProgress'
+import { WalkmeControls } from './WalkmeControls'
+
+interface WalkmeModalProps {
+  step: TourStep
+  onNext: () => void
+  onPrev: () => void
+  onSkip: () => void
+  onComplete: () => void
+  isFirst: boolean
+  isLast: boolean
+  currentIndex: number
+  totalSteps: number
+  labels?: {
+    close?: string
+    next?: string
+    prev?: string
+    skip?: string
+    complete?: string
+    progress?: string
+  }
+}
+
+/**
+ * Centered modal dialog for tour steps.
+ * Includes focus trap and keyboard handling.
+ * Uses theme-aware CSS variables for premium dark/light mode support.
+ */
+export const WalkmeModal = memo(function WalkmeModal({
+  step,
+  onNext,
+  onPrev,
+  onSkip,
+  onComplete,
+  isFirst,
+  isLast,
+  currentIndex,
+  totalSteps,
+  labels,
+}: WalkmeModalProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  // Focus trap: keep focus within the modal
+  useEffect(() => {
+    containerRef.current?.focus()
+
+    const handleTab = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab' || !containerRef.current) return
+
+      const focusable = containerRef.current.querySelectorAll<HTMLElement>(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+      )
+      if (focusable.length === 0) return
+
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+
+    document.addEventListener('keydown', handleTab)
+    return () => document.removeEventListener('keydown', handleTab)
+  }, [step.id])
+
+  if (typeof window === 'undefined') return null
+
+  return createPortal(
+    <div
+      ref={containerRef}
+      data-cy="walkme-modal"
+      data-walkme
+      role="dialog"
+      aria-modal="true"
+      aria-label={step.title}
+      aria-describedby={`walkme-modal-content-${step.id}`}
+      tabIndex={-1}
+      className="fixed left-1/2 top-1/2 w-[28rem] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 rounded-2xl p-6 outline-none animate-in fade-in-0 zoom-in-95 duration-300"
+      style={{
+        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))',
+      }}
+    >
+      {/* Close button */}
+      <button
+        data-cy="walkme-btn-close"
+        onClick={onSkip}
+        type="button"
+        className="cursor-pointer absolute right-3 top-3 rounded-lg p-1.5 transition-all duration-150 hover:scale-110 hover:bg-black/5 active:scale-95"
+        style={{
+          color: 'var(--walkme-text-muted, #6b7280)',
+          backgroundColor: 'transparent',
+        }}
+        aria-label={labels?.close ?? 'Close'}
+      >
+        <X size={16} weight="bold" />
+      </button>
+
+      {/* Title */}
+      <h2 className="mb-2 pr-8 text-lg font-semibold tracking-tight">{step.title}</h2>
+
+      {/* Content */}
+      <p
+        id={`walkme-modal-content-${step.id}`}
+        className="mb-5 text-sm leading-relaxed"
+        style={{ color: 'var(--walkme-text-muted, #6b7280)' }}
+      >
+        {step.content}
+      </p>
+
+      {/* Progress */}
+      <div className="mb-4">
+        <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,
+  )
+})

package/components/WalkmeOverlay.tsx

@@ -0,0 +1,107 @@
+'use client'
+
+import { memo, useEffect, useState, useCallback } from 'react'
+import { createPortal } from 'react-dom'
+
+interface WalkmeOverlayProps {
+  visible: boolean
+  onClick?: () => void
+  spotlightTarget?: HTMLElement | null
+  spotlightPadding?: number
+  /** Pre-computed target rect — when provided, skip internal scroll/resize tracking */
+  spotlightRect?: DOMRect | null
+}
+
+/**
+ * Full-screen dark backdrop overlay.
+ * Supports an optional spotlight cutout to highlight a target element.
+ * Dynamically tracks target position on scroll/resize.
+ */
+export const WalkmeOverlay = memo(function WalkmeOverlay({
+  visible,
+  onClick,
+  spotlightTarget,
+  spotlightPadding = 8,
+  spotlightRect: externalRect,
+}: WalkmeOverlayProps) {
+  const [internalClipPath, setInternalClipPath] = useState<string | undefined>(undefined)
+
+  // When parent provides a pre-computed rect, derive clip-path from it directly
+  const externalClipPath = externalRect
+    ? getSpotlightClipPathFromRect(externalRect, spotlightPadding)
+    : undefined
+
+  const recalculate = useCallback(() => {
+    if (!spotlightTarget) {
+      setInternalClipPath(undefined)
+      return
+    }
+    setInternalClipPath(getSpotlightClipPathFromRect(spotlightTarget.getBoundingClientRect(), spotlightPadding))
+  }, [spotlightTarget, spotlightPadding])
+
+  // Self-tracking mode: only active when no external rect is provided
+  useEffect(() => {
+    if (externalRect !== undefined) return
+    recalculate()
+  }, [recalculate, externalRect])
+
+  useEffect(() => {
+    if (externalRect !== undefined) return // skip self-tracking when parent provides rect
+    if (!spotlightTarget) return
+
+    const initialTimer = setTimeout(recalculate, 100)
+
+    const handler = () => recalculate()
+    window.addEventListener('scroll', handler, true)
+    window.addEventListener('resize', handler)
+
+    return () => {
+      clearTimeout(initialTimer)
+      window.removeEventListener('scroll', handler, true)
+      window.removeEventListener('resize', handler)
+    }
+  }, [spotlightTarget, recalculate, externalRect])
+
+  const clipPath = externalRect !== undefined ? externalClipPath : internalClipPath
+
+  if (typeof window === 'undefined') return null
+  if (!visible) return null
+
+  return createPortal(
+    <div
+      data-cy="walkme-overlay"
+      data-walkme
+      onClick={onClick}
+      className="fixed inset-0 transition-opacity duration-300 ease-in-out"
+      style={{
+        zIndex: 9998,
+        backgroundColor: 'var(--walkme-overlay-bg, rgba(0, 0, 0, 0.65))',
+        backdropFilter: 'blur(4px)',
+        WebkitBackdropFilter: 'blur(4px)',
+        clipPath,
+      }}
+      aria-hidden="true"
+    />,
+    document.body,
+  )
+})
+
+/** Generate a clip-path that cuts out a rectangle from a DOMRect */
+function getSpotlightClipPathFromRect(
+  rect: DOMRect,
+  padding: number,
+): string {
+  const top = Math.max(0, rect.top - padding)
+  const left = Math.max(0, rect.left - padding)
+  const bottom = Math.min(window.innerHeight, rect.bottom + padding)
+  const right = Math.min(window.innerWidth, rect.right + padding)
+
+  // polygon that covers everything EXCEPT the target area
+  return `polygon(
+    0% 0%, 0% 100%,
+    ${left}px 100%, ${left}px ${top}px,
+    ${right}px ${top}px, ${right}px ${bottom}px,
+    ${left}px ${bottom}px, ${left}px 100%,
+    100% 100%, 100% 0%
+  )`
+}

package/components/WalkmeProgress.tsx

@@ -0,0 +1,53 @@
+'use client'
+
+import { memo } from 'react'
+
+interface WalkmeProgressProps {
+  current: number
+  total: number
+  /** Template string for progress label, e.g. "Step {current} of {total}" */
+  progressTemplate?: string
+}
+
+/**
+ * Progress bar indicator showing current step within a tour.
+ * Uses theme-aware CSS variables with smooth transitions.
+ */
+export const WalkmeProgress = memo(function WalkmeProgress({
+  current,
+  total,
+  progressTemplate,
+}: WalkmeProgressProps) {
+  const percentage = total > 0 ? Math.round(((current + 1) / total) * 100) : 0
+  const progressLabel = (progressTemplate ?? 'Step {current} of {total}')
+    .replace('{current}', String(current + 1))
+    .replace('{total}', String(total))
+
+  return (
+    <div data-cy="walkme-progress" data-walkme className="flex items-center gap-3">
+      <div
+        className="h-1 flex-1 overflow-hidden rounded-full"
+        style={{ backgroundColor: 'var(--walkme-border, #e5e7eb)' }}
+        role="progressbar"
+        aria-valuenow={current + 1}
+        aria-valuemin={1}
+        aria-valuemax={total}
+        aria-label={progressLabel}
+      >
+        <div
+          className="h-full rounded-full transition-all duration-500 ease-out"
+          style={{
+            width: `${percentage}%`,
+            backgroundColor: 'var(--walkme-primary, #3b82f6)',
+          }}
+        />
+      </div>
+      <span
+        className="text-xs tabular-nums whitespace-nowrap"
+        style={{ color: 'var(--walkme-text-muted, #6b7280)' }}
+      >
+        {current + 1} / {total}
+      </span>
+    </div>
+  )
+})