@djangocfg/ui-tools 2.1.404 → 2.1.408

package/src/tools/Tour/components/TourProgress.tsx

@@ -1,88 +0,0 @@
-'use client';
-
-import { useMemo } from 'react';
-import { cn } from '@djangocfg/ui-core/lib';
-import { Progress } from '@djangocfg/ui-core/components';
-import { useT } from '@djangocfg/i18n';
-import type { TourProgressProps } from '../types';
-
-/**
- * Progress indicator for tour steps.
- * Supports dots, bar, fraction, and none variants.
- */
-export function TourProgress({
-  current,
-  total,
-  variant = 'dots',
-  onDotClick,
-  className,
-}: TourProgressProps) {
-  const t = useT();
-
-  // Early return for hidden states
-  if (variant === 'none' || total <= 1) return null;
-
-  // Prepare data
-  const currentStep = current + 1;
-  const progressPercent = (currentStep / total) * 100;
-  const stepLabel = t('tools.tour.stepOf', { current: currentStep, total });
-  const isClickable = !!onDotClick;
-
-  // Prepare dots data
-  const dots = useMemo(() => {
-    if (variant !== 'dots') return [];
-
-    return Array.from({ length: total }, (_, index) => ({
-      index,
-      isActive: index === current,
-      label: t('tools.tour.stepOf', { current: index + 1, total }),
-      className: cn(
-        'h-2 w-2 rounded-full transition-all',
-        index === current ? 'bg-primary scale-110' : 'bg-muted hover:bg-muted-foreground/50',
-        isClickable && 'cursor-pointer'
-      ),
-    }));
-  }, [variant, total, current, isClickable, t]);
-
-  // Render bar variant
-  if (variant === 'bar') {
-    return (
-      <Progress
-        value={progressPercent}
-        className={cn('h-1', className)}
-        aria-label={stepLabel}
-      />
-    );
-  }
-
-  // Render fraction variant
-  if (variant === 'fraction') {
-    const fractionClassName = cn('text-sm text-muted-foreground tabular-nums', className);
-
-    return (
-      <div className={fractionClassName} aria-label={stepLabel}>
-        {currentStep} / {total}
-      </div>
-    );
-  }
-
-  // Render dots variant (default)
-  const dotsContainerClassName = cn('flex items-center justify-center gap-1.5', className);
-
-  return (
-    <div className={dotsContainerClassName} role="tablist" aria-label={stepLabel}>
-      {dots.map((dot) => (
-        <button
-          key={dot.index}
-          type="button"
-          role="tab"
-          aria-selected={dot.isActive}
-          aria-label={dot.label}
-          className={dot.className}
-          onClick={() => onDotClick?.(dot.index)}
-          disabled={!isClickable}
-        />
-      ))}
-    </div>
-  );
-}

package/src/tools/Tour/components/TourSpotlight.tsx

@@ -1,199 +0,0 @@
-'use client';
-
-import { useMemo } from 'react';
-import { cn } from '@djangocfg/ui-core/lib';
-import type { TourSpotlightProps } from '../types';
-
-// CSS for SVG animations (injected once)
-const SPOTLIGHT_STYLES = `
-  @keyframes tour-spotlight-pulse {
-    0%, 100% { opacity: 1; }
-    50% { opacity: 0.5; }
-  }
-  @keyframes tour-spotlight-ring {
-    0% { transform: scale(1); opacity: 0.8; }
-    100% { transform: scale(1.15); opacity: 0; }
-  }
-  .tour-spotlight-rect {
-    transition: x 300ms ease-out, y 300ms ease-out, width 300ms ease-out, height 300ms ease-out;
-  }
-  .tour-spotlight-border {
-    transition: x 300ms ease-out, y 300ms ease-out, width 300ms ease-out, height 300ms ease-out;
-  }
-  .tour-spotlight-pulse {
-    animation: tour-spotlight-pulse 2s ease-in-out infinite;
-  }
-`;
-
-/**
- * SVG-based spotlight overlay that highlights target elements.
- * Uses mask technique to create cutouts for targets.
- * Supports animations, backdrop blur, and pulse ring effects.
- */
-export function TourSpotlight({
-  targets,
-  opacity = 0.5,
-  blur = 0,
-  animated = true,
-  pulseRing = false,
-  className,
-  onClick,
-  allowInteraction = false,
-}: TourSpotlightProps) {
-  // Early return for no targets
-  if (targets.length === 0) return null;
-
-  // Prepare flags
-  const hasBlur = blur > 0;
-
-  // Prepare target rects with computed values
-  const computedTargets = useMemo(() => {
-    return targets.map((target, index) => {
-      const x = target.rect.x - target.padding;
-      const y = target.rect.y - target.padding;
-      const width = target.rect.width + target.padding * 2;
-      const height = target.rect.height + target.padding * 2;
-      const rx = target.radius + 2;
-      const centerX = target.rect.x + target.rect.width / 2;
-      const centerY = target.rect.y + target.rect.height / 2;
-
-      return {
-        key: index,
-        x,
-        y,
-        width,
-        height,
-        rx,
-        ry: rx,
-        transformOrigin: `${centerX}px ${centerY}px`,
-      };
-    });
-  }, [targets]);
-
-  // Prepare styles
-  const svgClassName = cn('absolute inset-0 h-full w-full', className);
-  const svgStyle = { pointerEvents: allowInteraction ? 'none' as const : 'auto' as const };
-
-  const blurStyle = useMemo(() => {
-    if (!hasBlur) return undefined;
-    return {
-      backdropFilter: `blur(${blur}px)`,
-      WebkitBackdropFilter: `blur(${blur}px)`,
-      mask: 'url(#tour-spotlight-mask-blur)',
-      WebkitMask: 'url(#tour-spotlight-mask-blur)',
-      pointerEvents: 'none' as const,
-    };
-  }, [hasBlur, blur]);
-
-  const rectAnimatedClass = animated ? 'tour-spotlight-rect' : undefined;
-  const overlayClass = animated ? 'transition-opacity duration-300' : undefined;
-
-  return (
-    <>
-      {/* Inject styles for animations */}
-      <style dangerouslySetInnerHTML={{ __html: SPOTLIGHT_STYLES }} />
-
-      {/* Backdrop blur layer (separate from SVG for better performance) */}
-      {hasBlur && (
-        <div
-          className="absolute inset-0 transition-all duration-300"
-          style={blurStyle}
-          aria-hidden="true"
-        />
-      )}
-
-      <svg
-        className={svgClassName}
-        style={svgStyle}
-        onClick={onClick}
-        aria-hidden="true"
-      >
-        <defs>
-          <mask id="tour-spotlight-mask">
-            {/* White background - visible area */}
-            <rect fill="white" width="100%" height="100%" />
-            {/* Black cutouts - transparent area for targets */}
-            {computedTargets.map((target) => (
-              <rect
-                key={target.key}
-                fill="black"
-                className={rectAnimatedClass}
-                x={target.x}
-                y={target.y}
-                width={target.width}
-                height={target.height}
-                rx={target.rx}
-                ry={target.ry}
-              />
-            ))}
-          </mask>
-
-          {/* Separate mask for blur */}
-          {hasBlur && (
-            <mask id="tour-spotlight-mask-blur">
-              <rect fill="white" width="100%" height="100%" />
-              {computedTargets.map((target) => (
-                <rect
-                  key={target.key}
-                  fill="black"
-                  className={rectAnimatedClass}
-                  x={target.x}
-                  y={target.y}
-                  width={target.width}
-                  height={target.height}
-                  rx={target.rx}
-                  ry={target.ry}
-                />
-              ))}
-            </mask>
-          )}
-        </defs>
-
-        {/* Overlay with mask */}
-        <rect
-          fill="black"
-          fillOpacity={opacity}
-          width="100%"
-          height="100%"
-          mask="url(#tour-spotlight-mask)"
-          className={overlayClass}
-        />
-
-        {/* Pulse ring effect */}
-        {pulseRing && computedTargets.map((target) => (
-          <rect
-            key={`pulse-${target.key}`}
-            className="fill-none stroke-primary stroke-2"
-            style={{
-              transformOrigin: target.transformOrigin,
-              animation: 'tour-spotlight-ring 1.5s ease-out infinite',
-            }}
-            x={target.x}
-            y={target.y}
-            width={target.width}
-            height={target.height}
-            rx={target.rx}
-            ry={target.ry}
-          />
-        ))}
-
-        {/* Border around targets */}
-        {computedTargets.map((target) => (
-          <rect
-            key={`border-${target.key}`}
-            className={cn(
-              'fill-none stroke-primary stroke-2',
-              animated && 'tour-spotlight-border'
-            )}
-            x={target.x}
-            y={target.y}
-            width={target.width}
-            height={target.height}
-            rx={target.rx}
-            ry={target.ry}
-          />
-        ))}
-      </svg>
-    </>
-  );
-}

package/src/tools/Tour/components/index.ts

@@ -1,5 +0,0 @@
-export { TourSpotlight } from './TourSpotlight';
-export { TourProgress } from './TourProgress';
-export { TourNavigation } from './TourNavigation';
-export { TourContent } from './TourContent';
-export { Tour } from './Tour';

package/src/tools/Tour/context/TourContext.ts

@@ -1,19 +0,0 @@
-'use client';
-
-import { createContext, useContext } from 'react';
-import type { TourState, TourStep, UseTourReturn } from '../types';
-
-export interface TourContextValue extends UseTourReturn {
-  state: TourState;
-  steps: TourStep[];
-}
-
-export const TourContext = createContext<TourContextValue | null>(null);
-
-export function useTourContext(): TourContextValue {
-  const context = useContext(TourContext);
-  if (!context) {
-    throw new Error('useTourContext must be used within a TourProvider');
-  }
-  return context;
-}

package/src/tools/Tour/context/TourProvider.tsx

@@ -1,292 +0,0 @@
-'use client';
-
-import { useState, useCallback, useMemo, useEffect } from 'react';
-import { createPortal } from 'react-dom';
-import { TourContext, type TourContextValue } from './TourContext';
-import { TourSpotlight } from '../components/TourSpotlight';
-import { TourContent } from '../components/TourContent';
-import { useStepTarget } from '../hooks/useStepTarget';
-import { useKeyboardNavigation } from '../hooks/useKeyboardNavigation';
-import { logger } from '../utils/logger';
-import type { TourProviderProps, TourState, TourStep } from '../types';
-
-/**
- * Tour context provider.
- * Manages tour state and renders overlay.
- */
-export function TourProvider({
-  tours,
-  children,
-  spotlight = true,
-  spotlightOpacity = 0.5,
-  spotlightBlur = 0,
-  animated = true,
-  pulseRing = false,
-  showArrow = false,
-  keyboardNavigation = true,
-  closeOnOverlayClick = false,
-  closeOnEscape = true,
-  scrollToTarget = true,
-  scrollBehavior = 'smooth',
-  progressVariant = 'dots',
-  showSkipButton = true,
-  skipLabel,
-  finishLabel,
-  portalContainer,
-  zIndex = 50,
-  onStart,
-  onComplete,
-  onSkip,
-  onStepChange,
-  onBeforeStepChange,
-}: TourProviderProps) {
-  const [state, setState] = useState<TourState>({
-    isActive: false,
-    activeTourId: null,
-    currentStepIndex: 0,
-    isTransitioning: false,
-    direction: 'forward',
-  });
-
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-    setMounted(true);
-  }, []);
-
-  // Get active tour and current step
-  const activeTour = useMemo(
-    () => tours.find((t) => t.id === state.activeTourId),
-    [tours, state.activeTourId]
-  );
-
-  const steps = useMemo(() => {
-    if (!activeTour) return [];
-    // Apply tour defaults to each step
-    return activeTour.steps.map((step) => ({
-      ...activeTour.defaults,
-      ...step,
-    }));
-  }, [activeTour]);
-
-  const currentStep = steps[state.currentStepIndex] as TourStep | undefined;
-
-  // Track target elements
-  const { targets, isReady } = useStepTarget(currentStep?.target, currentStep?.id, {
-    scrollToTarget,
-    scrollBehavior,
-    spotlightPadding: currentStep?.spotlightPadding ?? 8,
-  });
-
-  // Start tour
-  const start = useCallback(
-    (tourId: string, startIndex = 0) => {
-      const tour = tours.find((t) => t.id === tourId);
-      if (!tour) {
-        logger.warn(`Tour "${tourId}" not found`);
-        return;
-      }
-      if (tour.steps.length === 0) {
-        logger.warn(`Tour "${tourId}" has no steps`);
-        return;
-      }
-
-      logger.info(`Starting tour "${tourId}"`);
-      setState({
-        isActive: true,
-        activeTourId: tourId,
-        currentStepIndex: Math.min(startIndex, tour.steps.length - 1),
-        isTransitioning: false,
-        direction: 'forward',
-      });
-      onStart?.(tourId);
-    },
-    [tours, onStart]
-  );
-
-  // Close tour
-  const close = useCallback(() => {
-    if (state.activeTourId) {
-      logger.info(`Tour "${state.activeTourId}" closed at step ${state.currentStepIndex}`);
-      onSkip?.(state.activeTourId, state.currentStepIndex);
-    }
-    setState({
-      isActive: false,
-      activeTourId: null,
-      currentStepIndex: 0,
-      isTransitioning: false,
-      direction: 'forward',
-    });
-  }, [state.activeTourId, state.currentStepIndex, onSkip]);
-
-  // Next step
-  const next = useCallback(async () => {
-    if (!activeTour) return;
-
-    const nextIndex = state.currentStepIndex + 1;
-
-    // Complete tour if at last step
-    if (nextIndex >= steps.length) {
-      logger.info(`Tour "${state.activeTourId}" completed`);
-      onComplete?.(state.activeTourId!);
-      setState({
-        isActive: false,
-        activeTourId: null,
-        currentStepIndex: 0,
-        isTransitioning: false,
-        direction: 'forward',
-      });
-      return;
-    }
-
-    // Check if can proceed
-    const canProceed = (await onBeforeStepChange?.(state.currentStepIndex, nextIndex)) ?? true;
-    if (!canProceed) return;
-
-    // Call step onHide callback
-    currentStep?.onHide?.();
-
-    setState((prev) => ({
-      ...prev,
-      currentStepIndex: nextIndex,
-      direction: 'forward',
-    }));
-
-    const nextStep = steps[nextIndex];
-    onStepChange?.(nextIndex, nextStep, 'forward');
-    nextStep?.onShow?.();
-  }, [activeTour, state, steps, currentStep, onComplete, onBeforeStepChange, onStepChange]);
-
-  // Previous step
-  const previous = useCallback(async () => {
-    if (state.currentStepIndex <= 0) return;
-
-    const prevIndex = state.currentStepIndex - 1;
-
-    const canProceed = (await onBeforeStepChange?.(state.currentStepIndex, prevIndex)) ?? true;
-    if (!canProceed) return;
-
-    currentStep?.onHide?.();
-
-    setState((prev) => ({
-      ...prev,
-      currentStepIndex: prevIndex,
-      direction: 'backward',
-    }));
-
-    const prevStep = steps[prevIndex];
-    onStepChange?.(prevIndex, prevStep, 'backward');
-    prevStep?.onShow?.();
-  }, [state.currentStepIndex, steps, currentStep, onBeforeStepChange, onStepChange]);
-
-  // Go to specific step
-  const goTo = useCallback(
-    async (index: number) => {
-      if (!activeTour || index < 0 || index >= steps.length) return;
-      if (index === state.currentStepIndex) return;
-
-      const canProceed = (await onBeforeStepChange?.(state.currentStepIndex, index)) ?? true;
-      if (!canProceed) return;
-
-      currentStep?.onHide?.();
-
-      const direction = index > state.currentStepIndex ? 'forward' : 'backward';
-      setState((prev) => ({
-        ...prev,
-        currentStepIndex: index,
-        direction,
-      }));
-
-      const targetStep = steps[index];
-      onStepChange?.(index, targetStep, direction);
-      targetStep?.onShow?.();
-    },
-    [activeTour, steps, state.currentStepIndex, currentStep, onBeforeStepChange, onStepChange]
-  );
-
-  // Keyboard navigation
-  useKeyboardNavigation({
-    enabled: keyboardNavigation && state.isActive,
-    onNext: next,
-    onPrevious: previous,
-    onClose: closeOnEscape ? close : undefined,
-  });
-
-  // Lock body scroll when tour is active
-  useEffect(() => {
-    if (state.isActive) {
-      const originalOverflow = document.body.style.overflow;
-      document.body.style.overflow = 'hidden';
-      return () => {
-        document.body.style.overflow = originalOverflow;
-      };
-    }
-  }, [state.isActive]);
-
-  // Context value
-  const contextValue: TourContextValue = useMemo(
-    () => ({
-      state,
-      steps,
-      currentStep: currentStep ?? null,
-      start,
-      next,
-      previous,
-      goTo,
-      close,
-      isActive: state.isActive,
-      activeTourId: state.activeTourId,
-      currentStepIndex: state.currentStepIndex,
-      totalSteps: steps.length,
-      isFirstStep: state.currentStepIndex === 0,
-      isLastStep: state.currentStepIndex === steps.length - 1,
-      progress: steps.length > 0 ? (state.currentStepIndex + 1) / steps.length : 0,
-    }),
-    [state, steps, currentStep, start, next, previous, goTo, close]
-  );
-
-  // Overlay content
-  const overlay = state.isActive && currentStep && isReady && targets.length > 0 && (
-    <div
-      className="fixed inset-0"
-      style={{ zIndex }}
-      role="presentation"
-      aria-hidden="true"
-    >
-      {spotlight && !currentStep.disableSpotlight && (
-        <TourSpotlight
-          targets={targets}
-          opacity={spotlightOpacity}
-          blur={spotlightBlur}
-          animated={animated}
-          pulseRing={pulseRing}
-          onClick={closeOnOverlayClick ? close : undefined}
-          allowInteraction={currentStep.allowTargetInteraction}
-        />
-      )}
-
-      <TourContent
-        step={currentStep}
-        targetRect={targets[0].rect}
-        currentIndex={state.currentStepIndex}
-        totalSteps={steps.length}
-        onNext={next}
-        onPrevious={previous}
-        onClose={close}
-        progressVariant={progressVariant}
-        showSkipButton={showSkipButton}
-        showArrow={showArrow}
-        skipLabel={skipLabel}
-        finishLabel={finishLabel}
-        onGoTo={goTo}
-      />
-    </div>
-  );
-
-  return (
-    <TourContext.Provider value={contextValue}>
-      {children}
-      {mounted && createPortal(overlay, portalContainer ?? document.body)}
-    </TourContext.Provider>
-  );
-}

package/src/tools/Tour/context/index.ts

@@ -1,2 +0,0 @@
-export { TourProvider } from './TourProvider';
-export { TourContext, useTourContext, type TourContextValue } from './TourContext';

package/src/tools/Tour/hooks/index.ts

@@ -1,3 +0,0 @@
-export { useTour } from './useTour';
-export { useStepTarget } from './useStepTarget';
-export { useKeyboardNavigation } from './useKeyboardNavigation';

package/src/tools/Tour/hooks/useKeyboardNavigation.ts

@@ -1,59 +0,0 @@
-'use client';
-
-import { useEffect } from 'react';
-
-interface UseKeyboardNavigationOptions {
-  enabled: boolean;
-  onNext?: () => void;
-  onPrevious?: () => void;
-  onClose?: () => void;
-}
-
-/**
- * Hook for keyboard navigation in tours.
- * - ArrowRight/ArrowDown: Next step
- * - ArrowLeft/ArrowUp: Previous step
- * - Escape: Close tour
- */
-export function useKeyboardNavigation({
-  enabled,
-  onNext,
-  onPrevious,
-  onClose,
-}: UseKeyboardNavigationOptions): void {
-  useEffect(() => {
-    if (!enabled) return;
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      // Ignore if user is typing in an input
-      const target = event.target as HTMLElement;
-      if (
-        target.tagName === 'INPUT' ||
-        target.tagName === 'TEXTAREA' ||
-        target.isContentEditable
-      ) {
-        return;
-      }
-
-      switch (event.key) {
-        case 'ArrowRight':
-        case 'ArrowDown':
-          event.preventDefault();
-          onNext?.();
-          break;
-        case 'ArrowLeft':
-        case 'ArrowUp':
-          event.preventDefault();
-          onPrevious?.();
-          break;
-        case 'Escape':
-          event.preventDefault();
-          onClose?.();
-          break;
-      }
-    };
-
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [enabled, onNext, onPrevious, onClose]);
-}