@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/OpenapiViewer/components/DocsLayout/schemaFields.ts

@@ -1,121 +0,0 @@
-/**
- * Flatten a JSON Schema node into a flat list of (name, type, required,
- * description) rows, ready to feed into the existing parameter table.
- *
- * Rules:
- *   - ``type: object``  → one row per property.
- *   - ``type: array``   → recurse into items; prefix each row with ``[].``
- *                         so the caller sees "[].username string" etc.
- *   - Nested objects    → dot-joined path: ``category.name``. We expand
- *                         one level; deeper graphs get a single summary
- *                         row ("category.* (object)") to keep the table
- *                         readable.
- *
- * This is a presentation helper — not a full form generator. It powers
- * the read-only fields table shown in the docs longread.
- */
-
-type JsonSchemaNode = Record<string, unknown> & {
-    type?: string;
-    properties?: Record<string, JsonSchemaNode>;
-    required?: string[];
-    items?: JsonSchemaNode;
-    enum?: unknown[];
-    description?: string;
-    format?: string;
-};
-
-export interface SchemaField {
-    name: string;
-    type: string;
-    required: boolean;
-    description?: string;
-}
-
-const MAX_DEPTH = 2;
-
-function describeType(node: JsonSchemaNode): string {
-    if (!node.type && node.properties) return 'object';
-    const base = node.type || 'any';
-    if (base === 'array') {
-        const itemType = node.items ? describeType(node.items) : 'any';
-        return `array<${itemType}>`;
-    }
-    if (Array.isArray(node.enum) && node.enum.length > 0) {
-        return `${base} enum`;
-    }
-    if (node.format) return `${base} (${node.format})`;
-    return base;
-}
-
-export function schemaToFields(
-    schema: JsonSchemaNode | undefined,
-    prefix = '',
-    depth = 0,
-): SchemaField[] {
-    if (!schema || depth > MAX_DEPTH) return [];
-
-    // Unwrap arrays: show the inner item's fields, prefixed with ``[]``.
-    if (schema.type === 'array') {
-        if (!schema.items) {
-            return [{ name: prefix || '[]', type: 'array', required: false }];
-        }
-        const inner = schemaToFields(schema.items, prefix ? `${prefix}[]` : '[]', depth);
-        if (inner.length === 0) {
-            return [
-                {
-                    name: prefix || '[]',
-                    type: describeType(schema),
-                    required: false,
-                    description: schema.description,
-                },
-            ];
-        }
-        return inner;
-    }
-
-    // Primitives and unknown — single row.
-    if (schema.type !== 'object' && !schema.properties) {
-        return [
-            {
-                name: prefix || '(body)',
-                type: describeType(schema),
-                required: false,
-                description: schema.description,
-            },
-        ];
-    }
-
-    // Objects — one row per property, recurse for nested objects/arrays.
-    const required = new Set(schema.required ?? []);
-    const rows: SchemaField[] = [];
-    const props = schema.properties ?? {};
-    for (const [key, node] of Object.entries(props)) {
-        const fullName = prefix ? `${prefix}.${key}` : key;
-        const isRequired = required.has(key);
-
-        const isNestedExpandable =
-            (node.type === 'object' && node.properties) ||
-            (node.type === 'array' && node.items);
-
-        if (isNestedExpandable && depth < MAX_DEPTH) {
-            // Leaf summary row for the parent itself (so the user sees
-            // its description) + recurse for inner fields.
-            rows.push({
-                name: fullName,
-                type: describeType(node),
-                required: isRequired,
-                description: node.description,
-            });
-            rows.push(...schemaToFields(node, fullName, depth + 1));
-        } else {
-            rows.push({
-                name: fullName,
-                type: describeType(node),
-                required: isRequired,
-                description: node.description,
-            });
-        }
-    }
-    return rows;
-}

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