@djangocfg/ui-tools 2.1.162 → 2.1.164

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.162",
+  "version": "2.1.164",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -57,6 +57,11 @@
       "import": "./src/tools/Uploader/index.ts",
       "require": "./src/tools/Uploader/index.ts"
     },
+    "./tour": {
+      "types": "./src/tools/Tour/index.ts",
+      "import": "./src/tools/Tour/index.ts",
+      "require": "./src/tools/Tour/index.ts"
+    },
     "./styles": "./src/styles/index.css"
   },
   "files": [
@@ -73,8 +78,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.162",
-    "@djangocfg/ui-core": "^2.1.162",
+    "@djangocfg/i18n": "^2.1.164",
+    "@djangocfg/ui-core": "^2.1.164",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -107,10 +112,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.162",
+    "@djangocfg/i18n": "^2.1.164",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.162",
-    "@djangocfg/ui-core": "^2.1.162",
+    "@djangocfg/typescript-config": "^2.1.164",
+    "@djangocfg/ui-core": "^2.1.164",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/tools/Tour/README.md

@@ -0,0 +1,373 @@
+# 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/Tour.story.tsx

@@ -0,0 +1,279 @@
+'use client';
+
+import { useState } from 'react';
+import { defineStory, useSelect } from '@djangocfg/playground';
+import { Button, Card, CardContent, CardHeader, CardTitle } from '@djangocfg/ui-core/components';
+import { Tour, useTour } from './index';
+import type { Tour as TourConfig } from './types';
+
+export default defineStory({
+  title: 'Tools/Tour',
+  component: Tour,
+  description: 'Onboarding tours with spotlight highlighting and keyboard navigation.',
+});
+
+// Demo tours
+const demoTours: TourConfig[] = [
+  {
+    id: 'basic',
+    steps: [
+      {
+        id: 'welcome',
+        target: '[data-tour-step-id="header"]',
+        title: 'Welcome to the Demo',
+        content: 'This tour will show you the main features of this page.',
+        position: 'bottom',
+      },
+      {
+        id: 'sidebar',
+        target: '[data-tour-step-id="sidebar"]',
+        title: 'Navigation Sidebar',
+        content: 'Use this sidebar to navigate between different sections.',
+        position: 'right',
+      },
+      {
+        id: 'content',
+        target: '[data-tour-step-id="main-content"]',
+        title: 'Main Content Area',
+        content: 'This is where all your content will be displayed.',
+        position: 'top',
+      },
+      {
+        id: 'actions',
+        target: '[data-tour-step-id="action-button"]',
+        title: 'Quick Actions',
+        content: 'Click here to perform quick actions.',
+        position: 'left',
+      },
+    ],
+  },
+  {
+    id: 'cards',
+    defaults: {
+      spotlightPadding: 12,
+    },
+    steps: [
+      {
+        id: 'step-1',
+        target: '[data-tour-step-id="card-1"]',
+        title: 'First Card',
+        content: 'This card shows important information.',
+        position: 'bottom',
+      },
+      {
+        id: 'step-2',
+        target: '[data-tour-step-id="card-2"]',
+        title: 'Second Card',
+        content: 'Another important card with different data.',
+        position: 'bottom',
+      },
+      {
+        id: 'step-3',
+        target: '[data-tour-step-id="card-3"]',
+        title: 'Third Card',
+        content: 'The last card in this row.',
+        position: 'bottom',
+        nextLabel: 'Complete Tour',
+      },
+    ],
+  },
+];
+
+// Demo component with tour targets
+function DemoLayout() {
+  const { start, isActive, currentStepIndex, totalSteps } = useTour();
+
+  return (
+    <div className="min-h-[500px] rounded-lg bg-muted/30 p-4">
+      {/* Header */}
+      <header
+        data-tour-step-id="header"
+        className="mb-4 rounded-lg bg-primary p-4 text-primary-foreground"
+      >
+        <div className="flex items-center justify-between">
+          <h1 className="text-xl font-bold">Tour Demo</h1>
+          <div className="flex gap-2">
+            <Button
+              variant="secondary"
+              size="sm"
+              onClick={() => start('basic')}
+              disabled={isActive}
+            >
+              Basic Tour
+            </Button>
+            <Button
+              variant="secondary"
+              size="sm"
+              onClick={() => start('cards')}
+              disabled={isActive}
+            >
+              Cards Tour
+            </Button>
+          </div>
+        </div>
+      </header>
+
+      <div className="flex gap-4">
+        {/* Sidebar */}
+        <aside
+          data-tour-step-id="sidebar"
+          className="w-48 rounded-lg bg-card p-4 shadow"
+        >
+          <nav className="space-y-2">
+            <div className="rounded bg-muted p-2 text-sm">Dashboard</div>
+            <div className="rounded p-2 text-sm hover:bg-muted">Settings</div>
+            <div className="rounded p-2 text-sm hover:bg-muted">Profile</div>
+            <div className="rounded p-2 text-sm hover:bg-muted">Help</div>
+          </nav>
+        </aside>
+
+        {/* Main content */}
+        <main className="flex-1 space-y-4">
+          <div
+            data-tour-step-id="main-content"
+            className="rounded-lg bg-card p-6 shadow"
+          >
+            <h2 className="mb-4 text-lg font-semibold">Main Content</h2>
+            <p className="text-muted-foreground">
+              This is the main content area.
+              {isActive && (
+                <span className="ml-2 text-primary">
+                  (Step {currentStepIndex + 1} of {totalSteps})
+                </span>
+              )}
+            </p>
+
+            <Button data-tour-step-id="action-button" className="mt-4">
+              Quick Action
+            </Button>
+          </div>
+
+          {/* Cards row */}
+          <div className="grid grid-cols-3 gap-4">
+            <Card data-tour-step-id="card-1">
+              <CardHeader>
+                <CardTitle className="text-base">Card 1</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <p className="text-sm text-muted-foreground">First card content.</p>
+              </CardContent>
+            </Card>
+
+            <Card data-tour-step-id="card-2">
+              <CardHeader>
+                <CardTitle className="text-base">Card 2</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <p className="text-sm text-muted-foreground">Second card content.</p>
+              </CardContent>
+            </Card>
+
+            <Card data-tour-step-id="card-3">
+              <CardHeader>
+                <CardTitle className="text-base">Card 3</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <p className="text-sm text-muted-foreground">Third card content.</p>
+              </CardContent>
+            </Card>
+          </div>
+        </main>
+      </div>
+    </div>
+  );
+}
+
+export const Interactive = () => {
+  const [progressVariant] = useSelect('progressVariant', {
+    options: ['dots', 'bar', 'fraction', 'none'] as const,
+    defaultValue: 'dots',
+    label: 'Progress Variant',
+  });
+
+  return (
+    <Tour
+      tours={demoTours}
+      progressVariant={progressVariant}
+      onStart={(id) => console.log('Tour started:', id)}
+      onComplete={(id) => console.log('Tour completed:', id)}
+      onSkip={(id, step) => console.log('Tour skipped:', id, 'at step', step)}
+      onStepChange={(index, step, direction) =>
+        console.log('Step:', index, step.id, direction)
+      }
+    >
+      <DemoLayout />
+    </Tour>
+  );
+};
+
+export const WithProgressBar = () => (
+  <Tour tours={demoTours} progressVariant="bar">
+    <DemoLayout />
+  </Tour>
+);
+
+export const WithFraction = () => (
+  <Tour tours={demoTours} progressVariant="fraction">
+    <DemoLayout />
+  </Tour>
+);
+
+export const NoSpotlight = () => (
+  <Tour tours={demoTours} spotlight={false}>
+    <DemoLayout />
+  </Tour>
+);
+
+export const CloseOnOverlayClick = () => (
+  <Tour tours={demoTours} closeOnOverlayClick>
+    <DemoLayout />
+  </Tour>
+);
+
+export const NoSkipButton = () => (
+  <Tour tours={demoTours} showSkipButton={false}>
+    <DemoLayout />
+  </Tour>
+);
+
+export const WithArrow = () => (
+  <Tour tours={demoTours} showArrow>
+    <DemoLayout />
+  </Tour>
+);
+
+export const WithBlur = () => (
+  <Tour tours={demoTours} spotlightBlur={4} spotlightOpacity={0.3}>
+    <DemoLayout />
+  </Tour>
+);
+
+export const WithArrowAndBlur = () => (
+  <Tour tours={demoTours} showArrow spotlightBlur={3} spotlightOpacity={0.4}>
+    <DemoLayout />
+  </Tour>
+);
+
+export const WithPulseRing = () => (
+  <Tour tours={demoTours} pulseRing>
+    <DemoLayout />
+  </Tour>
+);
+
+export const NoAnimation = () => (
+  <Tour tours={demoTours} animated={false}>
+    <DemoLayout />
+  </Tour>
+);
+
+export const FullFeatured = () => (
+  <Tour
+    tours={demoTours}
+    showArrow
+    spotlightBlur={2}
+    spotlightOpacity={0.4}
+    pulseRing
+  >
+    <DemoLayout />
+  </Tour>
+);

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

@@ -0,0 +1,12 @@
+'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>;
+}