@djangocfg/ui-tools 2.1.407 → 2.1.409

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]);
-}

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

@@ -1,121 +0,0 @@
-'use client';
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-import { findTargetElements, getElementBorderRadius } from '../utils/dom';
-import { scrollToElement } from '../utils/scrollIntoView';
-import type { SpotlightTarget } from '../types';
-
-interface UseStepTargetOptions {
-  scrollToTarget?: boolean;
-  scrollBehavior?: ScrollBehavior;
-  spotlightPadding?: number;
-}
-
-interface UseStepTargetReturn {
-  targets: SpotlightTarget[];
-  isReady: boolean;
-}
-
-/**
- * Hook to track target elements for current tour step.
- * Handles scroll, resize, and DOM mutations.
- */
-export function useStepTarget(
-  target: string | undefined,
-  stepId: string | undefined,
-  options: UseStepTargetOptions = {}
-): UseStepTargetReturn {
-  const {
-    scrollToTarget = true,
-    scrollBehavior = 'smooth',
-    spotlightPadding = 8,
-  } = options;
-
-  const [targets, setTargets] = useState<SpotlightTarget[]>([]);
-  const [isReady, setIsReady] = useState(false);
-  const hasScrolledRef = useRef(false);
-  const updateTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const updateTargets = useCallback(() => {
-    if (!stepId) {
-      setTargets([]);
-      setIsReady(false);
-      return;
-    }
-
-    const elements = findTargetElements(target, stepId);
-    if (elements.length === 0) {
-      setTargets([]);
-      setIsReady(false);
-      return;
-    }
-
-    const newTargets: SpotlightTarget[] = elements.map((element) => ({
-      element,
-      rect: element.getBoundingClientRect(),
-      padding: spotlightPadding,
-      radius: getElementBorderRadius(element),
-    }));
-
-    setTargets(newTargets);
-    setIsReady(true);
-
-    // Scroll to first target on initial render
-    if (scrollToTarget && !hasScrolledRef.current && elements[0]) {
-      scrollToElement(elements[0], scrollBehavior);
-      hasScrolledRef.current = true;
-    }
-  }, [target, stepId, scrollToTarget, scrollBehavior, spotlightPadding]);
-
-  // Debounced update for performance
-  const debouncedUpdate = useCallback(() => {
-    if (updateTimeoutRef.current) {
-      clearTimeout(updateTimeoutRef.current);
-    }
-    updateTimeoutRef.current = setTimeout(updateTargets, 16);
-  }, [updateTargets]);
-
-  // Reset scroll flag when step changes
-  useEffect(() => {
-    hasScrolledRef.current = false;
-  }, [stepId]);
-
-  // Initial update and event listeners
-  useEffect(() => {
-    if (!stepId) return;
-
-    // Initial update
-    updateTargets();
-
-    // Resize listener
-    window.addEventListener('resize', debouncedUpdate);
-
-    // Scroll listener (capture phase to catch all scrolls)
-    window.addEventListener('scroll', debouncedUpdate, true);
-
-    // Mutation observer for DOM changes
-    const observer = new MutationObserver(debouncedUpdate);
-    observer.observe(document.body, {
-      childList: true,
-      subtree: true,
-      attributes: true,
-      attributeFilter: ['style', 'class'],
-    });
-
-    // ResizeObserver for element size changes
-    const resizeObserver = new ResizeObserver(debouncedUpdate);
-    resizeObserver.observe(document.body);
-
-    return () => {
-      window.removeEventListener('resize', debouncedUpdate);
-      window.removeEventListener('scroll', debouncedUpdate, true);
-      observer.disconnect();
-      resizeObserver.disconnect();
-      if (updateTimeoutRef.current) {
-        clearTimeout(updateTimeoutRef.current);
-      }
-    };
-  }, [stepId, updateTargets, debouncedUpdate]);
-
-  return { targets, isReady };
-}

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

@@ -1,42 +0,0 @@
-'use client';
-
-import { useTourContext } from '../context/TourContext';
-import type { UseTourReturn } from '../types';
-
-/**
- * Hook to control the tour.
- * Must be used within a TourProvider.
- */
-export function useTour(): UseTourReturn {
-  const {
-    start,
-    next,
-    previous,
-    goTo,
-    close,
-    isActive,
-    activeTourId,
-    currentStep,
-    currentStepIndex,
-    totalSteps,
-    isFirstStep,
-    isLastStep,
-    progress,
-  } = useTourContext();
-
-  return {
-    start,
-    next,
-    previous,
-    goTo,
-    close,
-    isActive,
-    activeTourId,
-    currentStep,
-    currentStepIndex,
-    totalSteps,
-    isFirstStep,
-    isLastStep,
-    progress,
-  };
-}

package/src/tools/Tour/index.ts

@@ -1,38 +0,0 @@
-// Components
-export { Tour } from './components/Tour';
-export { TourSpotlight } from './components/TourSpotlight';
-export { TourProgress } from './components/TourProgress';
-export { TourNavigation } from './components/TourNavigation';
-export { TourContent } from './components/TourContent';
-
-// Context
-export { TourProvider } from './context';
-
-// Hooks
-export { useTour } from './hooks/useTour';
-export { useStepTarget } from './hooks/useStepTarget';
-export { useKeyboardNavigation } from './hooks/useKeyboardNavigation';
-
-// Utils
-export { findTargetElements, isElementInViewport } from './utils/dom';
-export { scrollToElement } from './utils/scrollIntoView';
-
-// Types
-export type {
-  Tour as TourConfig,
-  TourStep,
-  TourAction,
-  TourState,
-  TourPosition,
-  TourAlign,
-  ProgressVariant,
-  TourCallbacks,
-  TourProviderProps,
-  TourProps,
-  TourContentProps,
-  TourSpotlightProps,
-  TourProgressProps,
-  TourNavigationProps,
-  SpotlightTarget,
-  UseTourReturn,
-} from './types';

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

@@ -1,224 +0,0 @@
-import type { ReactNode } from 'react';
-
-// Position & Alignment
-export type TourPosition = 'top' | 'bottom' | 'left' | 'right' | 'auto';
-export type TourAlign = 'start' | 'center' | 'end';
-export type ProgressVariant = 'dots' | 'bar' | 'fraction' | 'none';
-
-// Step Action
-export interface TourAction {
-  label: ReactNode;
-  onClick: () => void;
-  variant?: 'default' | 'outline' | 'ghost' | 'destructive';
-}
-
-// Step Definition
-export interface TourStep {
-  /** Unique step identifier */
-  id: string;
-  /** CSS selector or data-tour-step-id value to find target element */
-  target?: string;
-  /** Step title */
-  title: ReactNode;
-  /** Step description/content */
-  content: ReactNode;
-  /** Popover position relative to target */
-  position?: TourPosition;
-  /** Offset from target in pixels */
-  offset?: number;
-  /** Alignment along the position axis */
-  align?: TourAlign;
-  /** Alignment offset in pixels */
-  alignOffset?: number;
-  /** Custom class for this step's popover */
-  className?: string;
-  /** Route to navigate on Next (for multi-page tours) */
-  nextRoute?: string;
-  /** Route to navigate on Previous */
-  previousRoute?: string;
-  /** Custom Next button label */
-  nextLabel?: ReactNode;
-  /** Custom Previous button label */
-  previousLabel?: ReactNode;
-  /** Disable spotlight for this step */
-  disableSpotlight?: boolean;
-  /** Spotlight padding around target */
-  spotlightPadding?: number;
-  /** Custom spotlight border radius */
-  spotlightRadius?: number;
-  /** Allow interaction with target while step is active */
-  allowTargetInteraction?: boolean;
-  /** Auto-advance after delay (ms) */
-  autoAdvance?: number;
-  /** Custom action buttons */
-  actions?: TourAction[];
-  /** Called before step shows, return false to skip */
-  onBeforeShow?: () => boolean | Promise<boolean>;
-  /** Called after step renders */
-  onShow?: () => void;
-  /** Called before step hides */
-  onHide?: () => void;
-}
-
-// Tour Definition
-export interface Tour {
-  id: string;
-  steps: TourStep[];
-  /** Tour-level defaults for steps */
-  defaults?: Partial<TourStep>;
-}
-
-// State
-export interface TourState {
-  isActive: boolean;
-  activeTourId: string | null;
-  currentStepIndex: number;
-  isTransitioning: boolean;
-  direction: 'forward' | 'backward';
-}
-
-// Callbacks
-export interface TourCallbacks {
-  /** Called when tour starts */
-  onStart?: (tourId: string) => void;
-  /** Called when tour completes (last step finished) */
-  onComplete?: (tourId: string) => void;
-  /** Called when tour is skipped/closed early */
-  onSkip?: (tourId: string, stepIndex: number) => void;
-  /** Called on step change */
-  onStepChange?: (stepIndex: number, step: TourStep, direction: 'forward' | 'backward') => void;
-  /** Called before step transition, return false to cancel */
-  onBeforeStepChange?: (currentIndex: number, nextIndex: number) => boolean | Promise<boolean>;
-}
-
-// Provider Props
-export interface TourProviderProps extends TourCallbacks {
-  tours: Tour[];
-  children: ReactNode;
-  /** Enable spotlight (default: true) */
-  spotlight?: boolean;
-  /** Spotlight opacity 0-1 (default: 0.5) */
-  spotlightOpacity?: number;
-  /** Spotlight blur amount in pixels (default: 0) */
-  spotlightBlur?: number;
-  /** Enable spotlight animations (default: true) */
-  animated?: boolean;
-  /** Show pulsing ring around target (default: false) */
-  pulseRing?: boolean;
-  /** Show arrow pointing to target (default: false) */
-  showArrow?: boolean;
-  /** Enable keyboard navigation (default: true) */
-  keyboardNavigation?: boolean;
-  /** Close on overlay click (default: false) */
-  closeOnOverlayClick?: boolean;
-  /** Close on Escape key (default: true) */
-  closeOnEscape?: boolean;
-  /** Scroll target into view (default: true) */
-  scrollToTarget?: boolean;
-  /** Scroll behavior (default: 'smooth') */
-  scrollBehavior?: ScrollBehavior;
-  /** Progress indicator variant (default: 'dots') */
-  progressVariant?: ProgressVariant;
-  /** Show skip button (default: true) */
-  showSkipButton?: boolean;
-  /** Custom skip button label */
-  skipLabel?: ReactNode;
-  /** Custom finish button label */
-  finishLabel?: ReactNode;
-  /** Portal container (default: document.body) */
-  portalContainer?: HTMLElement;
-  /** Z-index for overlay (default: 50) */
-  zIndex?: number;
-}
-
-// Hook Return
-export interface UseTourReturn {
-  /** Start a tour by ID */
-  start: (tourId: string, startIndex?: number) => void;
-  /** Go to next step */
-  next: () => void;
-  /** Go to previous step */
-  previous: () => void;
-  /** Go to specific step */
-  goTo: (index: number) => void;
-  /** Close/skip tour */
-  close: () => void;
-  /** Is tour currently active */
-  isActive: boolean;
-  /** Currently active tour ID */
-  activeTourId: string | null;
-  /** Current step object */
-  currentStep: TourStep | null;
-  /** Current step index */
-  currentStepIndex: number;
-  /** Total number of steps */
-  totalSteps: number;
-  /** Is first step */
-  isFirstStep: boolean;
-  /** Is last step */
-  isLastStep: boolean;
-  /** Progress 0-1 */
-  progress: number;
-}
-
-// Spotlight Target
-export interface SpotlightTarget {
-  element: HTMLElement;
-  rect: DOMRect;
-  padding: number;
-  radius: number;
-}
-
-// Component Props
-export interface TourSpotlightProps {
-  targets: SpotlightTarget[];
-  opacity?: number;
-  blur?: number;
-  animated?: boolean;
-  pulseRing?: boolean;
-  className?: string;
-  onClick?: () => void;
-  allowInteraction?: boolean;
-}
-
-export interface TourProgressProps {
-  current: number;
-  total: number;
-  variant?: ProgressVariant;
-  onDotClick?: (index: number) => void;
-  className?: string;
-}
-
-export interface TourNavigationProps {
-  onNext: () => void;
-  onPrevious: () => void;
-  isFirstStep: boolean;
-  isLastStep: boolean;
-  nextLabel?: ReactNode;
-  previousLabel?: ReactNode;
-  finishLabel?: ReactNode;
-  nextRoute?: string;
-  previousRoute?: string;
-  className?: string;
-}
-
-export interface TourContentProps {
-  step: TourStep;
-  targetRect: DOMRect;
-  currentIndex: number;
-  totalSteps: number;
-  onNext: () => void;
-  onPrevious: () => void;
-  onClose: () => void;
-  progressVariant?: ProgressVariant;
-  showSkipButton?: boolean;
-  showArrow?: boolean;
-  skipLabel?: ReactNode;
-  finishLabel?: ReactNode;
-  onGoTo?: (index: number) => void;
-  className?: string;
-}
-
-export interface TourProps extends Omit<TourProviderProps, 'children'> {
-  children?: ReactNode;
-}

package/src/tools/Tour/utils/dom.ts

@@ -1,98 +0,0 @@
-import { emitRuntimeError } from '@djangocfg/ui-core/utils';
-
-import { logger } from './logger';
-
-/**
- * Safely escape string for use in CSS attribute selector
- */
-function escapeCSS(str: string): string {
-  return str.replace(/["\\]/g, '\\$&');
-}
-
-/**
- * Find target elements for a tour step.
- * Supports CSS selectors and data-tour-step-id attribute.
- */
-export function findTargetElements(
-  target: string | undefined,
-  stepId: string
-): HTMLElement[] {
-  if (!target) {
-    // Fallback to data-tour-step-id attribute
-    try {
-      const escapedStepId = escapeCSS(stepId);
-      const elements = document.querySelectorAll<HTMLElement>(
-        `[data-tour-step-id="${escapedStepId}"], [data-tour-step-id*="${escapedStepId}"]`
-      );
-      return filterValidElements(Array.from(elements));
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      logger.error(`Tour: Invalid stepId selector "${stepId}"`, { error: err.message, stepId });
-      emitRuntimeError('Tour', `Invalid stepId: ${stepId}`, err);
-      return [];
-    }
-  }
-
-  // Try as CSS selector first
-  try {
-    const elements = document.querySelectorAll<HTMLElement>(target);
-    const valid = filterValidElements(Array.from(elements));
-    if (valid.length > 0) return valid;
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    logger.warn(`Tour: Invalid target selector "${target}"`, { error: err.message, target, stepId });
-    emitRuntimeError('Tour', `Invalid selector: ${target}`, err);
-    return [];
-  }
-
-  // Fallback to data attribute
-  try {
-    const escapedTarget = escapeCSS(target);
-    const elements = document.querySelectorAll<HTMLElement>(
-      `[data-tour-step-id="${escapedTarget}"], [data-tour-step-id*="${escapedTarget}"]`
-    );
-    return filterValidElements(Array.from(elements));
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    logger.error(`Tour: Invalid fallback selector for "${target}"`, { error: err.message, target, stepId });
-    emitRuntimeError('Tour', `Invalid fallback selector: ${target}`, err);
-    return [];
-  }
-}
-
-/**
- * Filter out elements that are not visible or have zero dimensions.
- */
-function filterValidElements(elements: HTMLElement[]): HTMLElement[] {
-  return elements.filter((el) => {
-    const rect = el.getBoundingClientRect();
-    // Skip elements with zero dimensions
-    if (rect.width === 0 && rect.height === 0) return false;
-    // Skip hidden elements
-    const style = window.getComputedStyle(el);
-    if (style.display === 'none' || style.visibility === 'hidden') return false;
-    return true;
-  });
-}
-
-/**
- * Get computed border radius from element.
- */
-export function getElementBorderRadius(element: HTMLElement): number {
-  const style = window.getComputedStyle(element);
-  const radius = parseFloat(style.borderRadius) || 0;
-  return Math.min(radius, 20); // Cap at 20px for reasonable spotlight
-}
-
-/**
- * Check if element is in viewport.
- */
-export function isElementInViewport(element: HTMLElement): boolean {
-  const rect = element.getBoundingClientRect();
-  return (
-    rect.top >= 0 &&
-    rect.left >= 0 &&
-    rect.bottom <= window.innerHeight &&
-    rect.right <= window.innerWidth
-  );
-}

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

@@ -1,3 +0,0 @@
-export { logger } from './logger';
-export { findTargetElements, getElementBorderRadius, isElementInViewport } from './dom';
-export { scrollToElement, waitForScroll } from './scrollIntoView';

package/src/tools/Tour/utils/logger.ts

@@ -1,3 +0,0 @@
-import { createLogger } from '@djangocfg/ui-core/lib';
-
-export const logger = createLogger('Tour');

package/src/tools/Tour/utils/scrollIntoView.ts

@@ -1,24 +0,0 @@
-import { isElementInViewport } from './dom';
-
-/**
- * Scroll element into view if not already visible.
- */
-export function scrollToElement(
-  element: HTMLElement,
-  behavior: ScrollBehavior = 'smooth'
-): void {
-  if (isElementInViewport(element)) return;
-
-  element.scrollIntoView({
-    behavior,
-    block: 'center',
-    inline: 'center',
-  });
-}
-
-/**
- * Wait for scroll to complete (approximate).
- */
-export function waitForScroll(duration = 300): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, duration));
-}