@djangocfg/ui-tools 2.1.404 → 2.1.408

package/src/tools/Tour/README.md

@@ -1,373 +0,0 @@
-# Tour
-
-Smart, decomposed onboarding Tour component with spotlight highlighting, animations, and i18n support.
-
-## Installation
-
-```bash
-pnpm add @djangocfg/ui-tools
-```
-
-## Basic Usage
-
-```tsx
-import { Tour, useTour } from '@djangocfg/ui-tools/tour';
-
-const tours = [
-  {
-    id: 'onboarding',
-    steps: [
-      {
-        id: 'welcome',
-        target: '[data-tour-step-id="header"]',
-        title: 'Welcome',
-        content: 'Let us show you around!',
-        position: 'bottom',
-      },
-      {
-        id: 'sidebar',
-        target: '#sidebar',
-        title: 'Navigation',
-        content: 'Use the sidebar to navigate.',
-        position: 'right',
-      },
-    ],
-  },
-];
-
-function App() {
-  return (
-    <Tour
-      tours={tours}
-      onComplete={(tourId) => console.log('Tour completed:', tourId)}
-    >
-      <Layout />
-    </Tour>
-  );
-}
-
-function StartButton() {
-  const { start } = useTour();
-  return <button onClick={() => start('onboarding')}>Start Tour</button>;
-}
-```
-
-## Components
-
-### Tour
-
-All-in-one wrapper combining TourProvider with overlay rendering.
-
-```tsx
-<Tour
-  tours={tours}                    // Array of tour configs
-  spotlight={true}                 // Enable spotlight (default: true)
-  spotlightOpacity={0.5}          // Overlay opacity (default: 0.5)
-  spotlightBlur={0}               // Backdrop blur in px (default: 0)
-  animated={true}                 // Enable animations (default: true)
-  pulseRing={false}               // Pulsing ring around target (default: false)
-  showArrow={false}               // Show arrow to target (default: false)
-  keyboardNavigation={true}       // Arrow keys navigation (default: true)
-  closeOnEscape={true}            // Close on Escape (default: true)
-  closeOnOverlayClick={false}     // Close on overlay click (default: false)
-  scrollToTarget={true}           // Scroll target into view (default: true)
-  progressVariant="dots"          // 'dots' | 'bar' | 'fraction' | 'none'
-  showSkipButton={true}           // Show skip button (default: true)
-  onStart={(tourId) => {}}
-  onComplete={(tourId) => {}}
-  onSkip={(tourId, stepIndex) => {}}
-  onStepChange={(index, step, direction) => {}}
->
-  {children}
-</Tour>
-```
-
-### Custom Composition
-
-```tsx
-import {
-  TourProvider,
-  TourSpotlight,
-  TourContent,
-  TourProgress,
-  TourNavigation,
-  useTour,
-} from '@djangocfg/ui-tools/tour';
-
-function CustomTourOverlay() {
-  const { currentStep, currentStepIndex, totalSteps, next, previous, close } = useTour();
-  // ... render custom UI
-}
-
-<TourProvider tours={tours}>
-  <App />
-  <CustomTourOverlay />
-</TourProvider>
-```
-
-## Step Configuration
-
-```tsx
-interface TourStep {
-  id: string;                    // Unique identifier
-  target?: string;               // CSS selector or data-tour-step-id
-  title: ReactNode;              // Step title
-  content: ReactNode;            // Step content
-  position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
-  offset?: number;               // Popover offset (default: 12)
-  align?: 'start' | 'center' | 'end';
-
-  // Multi-page tours
-  nextRoute?: string;            // Navigate on Next
-  previousRoute?: string;        // Navigate on Previous
-
-  // Labels (overrides i18n)
-  nextLabel?: ReactNode;
-  previousLabel?: ReactNode;
-
-  // Spotlight
-  disableSpotlight?: boolean;
-  spotlightPadding?: number;     // Padding around target (default: 8)
-  spotlightRadius?: number;      // Border radius (default: 4)
-  allowTargetInteraction?: boolean;
-
-  // Auto-advance
-  autoAdvance?: number;          // Auto-advance after ms
-
-  // Custom actions
-  actions?: TourAction[];
-
-  // Callbacks
-  onBeforeShow?: () => boolean | Promise<boolean>;
-  onShow?: () => void;
-  onHide?: () => void;
-}
-```
-
-## Targeting Elements
-
-### Option 1: CSS Selector
-
-```tsx
-{
-  id: 'step-1',
-  target: '#my-button',  // or '.my-class', '[data-id="123"]'
-  title: 'Click here',
-  content: '...',
-}
-```
-
-### Option 2: data-tour-step-id Attribute
-
-```tsx
-// In your component
-<header data-tour-step-id="header">...</header>
-
-// In tour config
-{
-  id: 'header',  // matches data-tour-step-id
-  title: 'Welcome',
-  content: '...',
-}
-```
-
-## Hooks
-
-### useTour
-
-```tsx
-const {
-  start,           // (tourId, startIndex?) => void
-  next,            // () => void
-  previous,        // () => void
-  goTo,            // (index) => void
-  close,           // () => void
-  isActive,        // boolean
-  activeTourId,    // string | null
-  currentStep,     // TourStep | null
-  currentStepIndex,// number
-  totalSteps,      // number
-  isFirstStep,     // boolean
-  isLastStep,      // boolean
-  progress,        // number (0-1)
-} = useTour();
-```
-
-## Keyboard Navigation
-
-When enabled (default):
-- `ArrowRight` / `ArrowDown`: Next step
-- `ArrowLeft` / `ArrowUp`: Previous step
-- `Escape`: Close tour
-
-## Multi-page Tours
-
-```tsx
-const tours = [{
-  id: 'walkthrough',
-  steps: [
-    {
-      id: 'home',
-      target: '#hero',
-      title: 'Welcome',
-      content: 'Start here.',
-      nextRoute: '/dashboard',  // Navigate on Next
-    },
-    {
-      id: 'dashboard',
-      target: '#stats',
-      title: 'Dashboard',
-      content: 'View your metrics.',
-      previousRoute: '/',       // Navigate on Previous
-    },
-  ],
-}];
-```
-
-## Callbacks
-
-```tsx
-<Tour
-  tours={tours}
-  onStart={(tourId) => {
-    analytics.track('tour_started', { tourId });
-  }}
-  onComplete={(tourId) => {
-    localStorage.setItem(`tour_${tourId}_completed`, 'true');
-  }}
-  onSkip={(tourId, stepIndex) => {
-    analytics.track('tour_skipped', { tourId, stepIndex });
-  }}
-  onStepChange={(index, step, direction) => {
-    analytics.track('tour_step', { stepId: step.id, direction });
-  }}
-  onBeforeStepChange={async (currentIndex, nextIndex) => {
-    // Return false to prevent navigation
-    return true;
-  }}
->
-```
-
-## Progress Variants
-
-- `dots` - Clickable dots (default)
-- `bar` - Progress bar
-- `fraction` - "1 / 5" text
-- `none` - No progress indicator
-
-## Visual Options
-
-### Arrow
-
-Shows an arrow pointing from the popover to the target element:
-
-```tsx
-<Tour tours={tours} showArrow>
-  {children}
-</Tour>
-```
-
-### Backdrop Blur
-
-Blurs the background outside the spotlight for enhanced focus:
-
-```tsx
-<Tour tours={tours} spotlightBlur={4} spotlightOpacity={0.3}>
-  {children}
-</Tour>
-```
-
-### Pulse Ring
-
-Animated pulsing ring around the target to draw attention:
-
-```tsx
-<Tour tours={tours} pulseRing>
-  {children}
-</Tour>
-```
-
-### Disable Animations
-
-Turn off all spotlight transition animations:
-
-```tsx
-<Tour tours={tours} animated={false}>
-  {children}
-</Tour>
-```
-
-### Full Featured
-
-Combine all visual enhancements:
-
-```tsx
-<Tour
-  tours={tours}
-  showArrow
-  spotlightBlur={2}
-  spotlightOpacity={0.4}
-  pulseRing
->
-  {children}
-</Tour>
-```
-
-## Internationalization (i18n)
-
-Tour uses `@djangocfg/i18n` for translations. Default labels come from `tools.tour.*` keys:
-
-- `tools.tour.next` - "Next"
-- `tools.tour.previous` - "Back"
-- `tools.tour.skip` - "Skip"
-- `tools.tour.finish` - "Finish"
-- `tools.tour.close` - "Close"
-- `tools.tour.stepOf` - "Step {current} of {total}"
-
-To customize, either:
-
-1. **Override via props** (per-step or global):
-```tsx
-<Tour
-  tours={tours}
-  skipLabel="Exit tour"
-  finishLabel="Done!"
->
-```
-
-2. **Provide custom translations** via I18nProvider:
-```tsx
-import { I18nProvider, mergeTranslations, en } from '@djangocfg/i18n';
-
-const customEn = mergeTranslations(en, {
-  tools: {
-    tour: {
-      next: 'Continue',
-      skip: 'Exit',
-    }
-  }
-});
-
-<I18nProvider locale="en" translations={customEn}>
-  <Tour tours={tours}>
-    <App />
-  </Tour>
-</I18nProvider>
-```
-
-## Features
-
-- Spotlight highlighting with SVG mask
-- Optional backdrop blur for enhanced focus
-- Arrow pointing from popover to target
-- Smooth animations between steps
-- Pulse ring effect for attention
-- Keyboard navigation
-- Multi-step and multi-page tours
-- Progress indicators (dots, bar, fraction)
-- Auto-scroll to target
-- Lifecycle callbacks
-- Custom positioning
-- Skip/close functionality
-- ARIA accessibility
-- Full i18n support

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

@@ -1,12 +0,0 @@
-'use client';
-
-import { TourProvider } from '../context/TourProvider';
-import type { TourProps } from '../types';
-
-/**
- * All-in-one Tour component.
- * Combines TourProvider with children for simple usage.
- */
-export function Tour({ children, ...providerProps }: TourProps) {
-  return <TourProvider {...providerProps}>{children}</TourProvider>;
-}

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

@@ -1,171 +0,0 @@
-'use client';
-
-import { useMemo } from 'react';
-import { X } from 'lucide-react';
-import { cn } from '@djangocfg/ui-core/lib';
-import {
-  Popover,
-  PopoverAnchor,
-  PopoverContent,
-  PopoverArrow,
-  Button,
-} from '@djangocfg/ui-core/components';
-import { TourProgress } from './TourProgress';
-import { TourNavigation } from './TourNavigation';
-import type { TourContentProps, TourPosition } from '../types';
-
-/**
- * Map TourPosition to Radix Popover side.
- */
-function mapPositionToSide(
-  position: TourPosition | undefined
-): 'top' | 'bottom' | 'left' | 'right' {
-  if (!position || position === 'auto') return 'bottom';
-  return position;
-}
-
-/**
- * Tour step content popover.
- * Uses Radix Popover with virtual anchor for positioning.
- */
-export function TourContent({
-  step,
-  targetRect,
-  currentIndex,
-  totalSteps,
-  onNext,
-  onPrevious,
-  onClose,
-  progressVariant = 'dots',
-  showSkipButton = true,
-  showArrow = false,
-  skipLabel,
-  finishLabel,
-  onGoTo,
-  className,
-}: TourContentProps) {
-  // Prepare virtual ref for Popover anchor
-  const virtualRef = useMemo(
-    () => ({
-      current: {
-        getBoundingClientRect: () => targetRect,
-      },
-    }),
-    [targetRect]
-  );
-
-  // Prepare positioning
-  const side = mapPositionToSide(step.position);
-  const sideOffset = step.offset ?? 12;
-  const align = step.align ?? 'center';
-  const alignOffset = step.alignOffset ?? 0;
-
-  // Prepare step state
-  const isFirstStep = currentIndex === 0;
-  const isLastStep = currentIndex === totalSteps - 1;
-
-  // Prepare styles
-  const popoverContentClassName = cn('z-[51] w-72', step.className, className);
-
-  // Prepare custom actions
-  const hasCustomActions = step.actions && step.actions.length > 0;
-  const customActions = useMemo(() => {
-    if (!step.actions) return [];
-
-    return step.actions.map((action, index) => ({
-      key: index,
-      label: action.label,
-      onClick: action.onClick,
-      className: cn(
-        'text-sm font-medium underline-offset-4 hover:underline',
-        action.variant === 'destructive' && 'text-destructive'
-      ),
-    }));
-  }, [step.actions]);
-
-  // Event handlers
-  const preventAutoFocus = (e: Event) => e.preventDefault();
-
-  return (
-    <Popover open>
-      <PopoverAnchor virtualRef={virtualRef as React.RefObject<Element>} />
-      <PopoverContent
-        side={side}
-        sideOffset={sideOffset}
-        align={align}
-        alignOffset={alignOffset}
-        avoidCollisions
-        collisionPadding={16}
-        className={popoverContentClassName}
-        onOpenAutoFocus={preventAutoFocus}
-        onCloseAutoFocus={preventAutoFocus}
-        role="dialog"
-        aria-labelledby="tour-title"
-        aria-describedby="tour-description"
-      >
-        {showArrow && <PopoverArrow className="fill-popover" />}
-
-        {/* Header with close button */}
-        <div className="flex items-start justify-between gap-2 pb-2">
-          <h3 id="tour-title" className="text-base font-semibold leading-none tracking-tight">
-            {step.title}
-          </h3>
-          {showSkipButton && (
-            <Button
-              variant="ghost"
-              size="icon"
-              className="h-6 w-6 shrink-0 -mt-1 -mr-2"
-              onClick={onClose}
-            >
-              <X className="h-4 w-4" />
-            </Button>
-          )}
-        </div>
-
-        {/* Content */}
-        <p id="tour-description" className="text-sm text-muted-foreground">
-          {step.content}
-        </p>
-
-        {/* Footer */}
-        <div className="mt-4 flex flex-col gap-3">
-          <TourProgress
-            current={currentIndex}
-            total={totalSteps}
-            variant={progressVariant}
-            onDotClick={onGoTo}
-          />
-
-          <TourNavigation
-            onNext={onNext}
-            onPrevious={onPrevious}
-            isFirstStep={isFirstStep}
-            isLastStep={isLastStep}
-            nextLabel={step.nextLabel}
-            previousLabel={step.previousLabel}
-            finishLabel={finishLabel}
-            nextRoute={step.nextRoute}
-            previousRoute={step.previousRoute}
-            className="w-full"
-          />
-
-          {/* Custom actions */}
-          {hasCustomActions && (
-            <div className="flex w-full flex-wrap gap-2">
-              {customActions.map((action) => (
-                <button
-                  key={action.key}
-                  type="button"
-                  onClick={action.onClick}
-                  className={action.className}
-                >
-                  {action.label}
-                </button>
-              ))}
-            </div>
-          )}
-        </div>
-      </PopoverContent>
-    </Popover>
-  );
-}

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

@@ -1,77 +0,0 @@
-'use client';
-
-import { useCallback, useMemo } from 'react';
-import { cn } from '@djangocfg/ui-core/lib';
-import { Button } from '@djangocfg/ui-core/components';
-import { ChevronLeft, ChevronRight } from 'lucide-react';
-import { useT } from '@djangocfg/i18n';
-import type { TourNavigationProps } from '../types';
-
-/**
- * Navigation buttons for tour steps.
- * For multi-page tours, use nextRoute/previousRoute with your router.
- * Skip button is now in TourContent header as × icon.
- */
-export function TourNavigation({
-  onNext,
-  onPrevious,
-  isFirstStep,
-  isLastStep,
-  nextLabel,
-  previousLabel,
-  finishLabel,
-  nextRoute,
-  previousRoute,
-  className,
-}: TourNavigationProps) {
-  const t = useT();
-
-  // Prepare labels
-  const labels = useMemo(() => {
-    const defaultNext = isLastStep ? t('tools.tour.finish') : t('tools.tour.next');
-    return {
-      next: nextLabel ?? finishLabel ?? defaultNext,
-      previous: previousLabel ?? t('tools.tour.previous'),
-    };
-  }, [isLastStep, nextLabel, finishLabel, previousLabel, t]);
-
-  // Prepare visibility flags
-  const showPrevious = !isFirstStep;
-  const showNextArrow = !isLastStep;
-
-  // Handlers
-  const handleNext = useCallback(() => {
-    if (nextRoute && typeof window !== 'undefined') {
-      window.location.href = nextRoute;
-    }
-    onNext();
-  }, [nextRoute, onNext]);
-
-  const handlePrevious = useCallback(() => {
-    if (previousRoute && typeof window !== 'undefined') {
-      window.location.href = previousRoute;
-    }
-    onPrevious();
-  }, [previousRoute, onPrevious]);
-
-  // Styles
-  const containerClassName = cn('flex items-center gap-2', className);
-
-  return (
-    <div className={containerClassName}>
-      {showPrevious ? (
-        <Button variant="ghost" size="sm" onClick={handlePrevious} className="flex-1 gap-1">
-          <ChevronLeft className="h-4 w-4 shrink-0" />
-          <span className="truncate">{labels.previous}</span>
-        </Button>
-      ) : (
-        <div className="flex-1" />
-      )}
-
-      <Button size="sm" onClick={handleNext} className="flex-1 gap-1">
-        <span className="truncate">{labels.next}</span>
-        {showNextArrow && <ChevronRight className="h-4 w-4 shrink-0" />}
-      </Button>
-    </div>
-  );
-}