@djangocfg/ui-tools 2.1.404 → 2.1.408

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

package/src/tools/VideoPlayer/components/VideoControls.tsx

@@ -1,138 +0,0 @@
-/**
- * Custom Video Controls for Vidstack Player
- */
-
-'use client';
-
-import { Maximize, Minimize, Pause, Play, Volume2, VolumeX } from 'lucide-react';
-import React from 'react';
-
-import { cn } from '@djangocfg/ui-core/lib';
-import { useMediaRemote, useMediaStore } from '@vidstack/react';
-
-import type { MediaPlayerInstance } from '@vidstack/react';
-interface VideoControlsProps {
-  player: React.RefObject<MediaPlayerInstance | null>;
-  className?: string;
-}
-
-export function VideoControls({ player, className }: VideoControlsProps) {
-  const store = useMediaStore(player);
-  const remote = useMediaRemote();
-
-  const isPaused = store.paused;
-  const isMuted = store.muted;
-  const isFullscreen = store.fullscreen;
-  const currentTime = store.currentTime;
-  const duration = store.duration;
-  const volume = store.volume;
-
-  const formatTime = (seconds: number): string => {
-    if (!seconds || seconds < 0) return '0:00';
-    const minutes = Math.floor(seconds / 60);
-    const secs = Math.floor(seconds % 60);
-    return `${minutes}:${secs.toString().padStart(2, '0')}`;
-  };
-
-  const handleProgressClick = (e: React.MouseEvent<HTMLDivElement>) => {
-    if (!duration) return;
-    const rect = e.currentTarget.getBoundingClientRect();
-    const clickX = e.clientX - rect.left;
-    const percentage = clickX / rect.width;
-    const newTime = percentage * duration;
-    remote.seek(newTime);
-  };
-
-  const handleVolumeChange = (e: React.MouseEvent<HTMLDivElement>) => {
-    const rect = e.currentTarget.getBoundingClientRect();
-    const clickX = e.clientX - rect.left;
-    const percentage = Math.max(0, Math.min(1, clickX / rect.width));
-    remote.changeVolume(percentage);
-    if (percentage > 0 && isMuted) {
-      remote.toggleMuted();
-    }
-  };
-
-  const progress = duration > 0 ? (currentTime / duration) * 100 : 0;
-
-  return (
-    <div
-      className={cn(
-        "absolute inset-0 flex flex-col justify-end transition-opacity duration-300",
-        "bg-gradient-to-t from-black/80 via-black/20 to-transparent",
-        "opacity-0 group-hover:opacity-100 focus-within:opacity-100",
-        "pointer-events-none group-hover:pointer-events-auto",
-        className
-      )}
-    >
-      {/* Progress Bar */}
-      <div className="px-4 pb-2 pointer-events-auto">
-        <div
-          className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all group"
-          onClick={handleProgressClick}
-        >
-          <div
-            className="h-full bg-primary rounded-full transition-all relative group-hover:bg-primary/90"
-            style={{ width: `${progress}%` }}
-          >
-            <div className="absolute right-0 top-1/2 -translate-y-1/2 w-3 h-3 bg-white rounded-full opacity-0 group-hover:opacity-100 transition-opacity" />
-          </div>
-        </div>
-      </div>
-
-      {/* Control Bar */}
-      <div className="flex items-center gap-4 px-4 pb-4 pointer-events-auto">
-        {/* Play/Pause */}
-        <button
-          onClick={() => remote.togglePaused()}
-          className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
-        >
-          {isPaused ? <Play className="h-6 w-6" /> : <Pause className="h-6 w-6" />}
-        </button>
-
-        {/* Time */}
-        <div className="text-white text-sm font-medium">
-          {formatTime(currentTime)} / {formatTime(duration)}
-        </div>
-
-        <div className="flex-1" />
-
-        {/* Volume Control */}
-        <div className="flex items-center gap-2 group/volume">
-          <button
-            onClick={() => remote.toggleMuted()}
-            className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
-          >
-            {isMuted || volume === 0 ? (
-              <VolumeX className="h-5 w-5" />
-            ) : (
-              <Volume2 className="h-5 w-5" />
-            )}
-          </button>
-
-          <div
-            className="w-0 group-hover/volume:w-20 transition-all overflow-hidden"
-          >
-            <div
-              className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all"
-              onClick={handleVolumeChange}
-            >
-              <div
-                className="h-full bg-white rounded-full transition-all"
-                style={{ width: `${volume * 100}%` }}
-              />
-            </div>
-          </div>
-        </div>
-
-        {/* Fullscreen */}
-        <button
-          onClick={() => isFullscreen ? remote.exitFullscreen() : remote.enterFullscreen()}
-          className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
-        >
-          {isFullscreen ? <Minimize className="h-5 w-5" /> : <Maximize className="h-5 w-5" />}
-        </button>
-      </div>
-    </div>
-  );
-}