@djangocfg/ui-tools 2.1.412 → 2.1.413

package/src/tools/overlay/SelectionToolbar/index.ts

@@ -0,0 +1,37 @@
+'use client';
+
+/**
+ * SelectionToolbar
+ *
+ * Toolbar that appears when text is selected within its container.
+ * Useful for text formatting, sharing, or quick actions on selection.
+ *
+ * @example
+ * import { SelectionToolbar, SelectionToolbarContent, SelectionToolbarAction } from '@djangocfg/ui-tools/selection-toolbar';
+ *
+ * <SelectionToolbar>
+ *   <div>Some selectable text...</div>
+ *   <SelectionToolbarContent>
+ *     <SelectionToolbarAction onClick={handleCopy}>Copy</SelectionToolbarAction>
+ *     <SelectionToolbarAction onClick={handleShare}>Share</SelectionToolbarAction>
+ *   </SelectionToolbarContent>
+ * </SelectionToolbar>
+ */
+
+export {
+  SelectionToolbar,
+  SelectionToolbarContent,
+  SelectionToolbarAction,
+} from './parts';
+
+export {
+  SelectionToolbarProvider,
+  useSelectionToolbarContext,
+} from './context';
+
+export type {
+  SelectionToolbarProps,
+  SelectionToolbarContentProps,
+  SelectionToolbarActionProps,
+  SelectionToolbarContextValue,
+} from './types';

package/src/tools/overlay/SelectionToolbar/lazy.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+/**
+ * Lazy-loaded SelectionToolbar Component
+ */
+
+import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import type {
+  SelectionToolbarProps,
+  SelectionToolbarContentProps,
+  SelectionToolbarActionProps,
+} from './types';
+
+export type {
+  SelectionToolbarProps,
+  SelectionToolbarContentProps,
+  SelectionToolbarActionProps,
+} from './types';
+
+export const LazySelectionToolbar = createLazyComponent<SelectionToolbarProps>(
+  () => import('./parts/SelectionToolbar').then((m) => ({ default: m.SelectionToolbar })),
+  {
+    displayName: 'LazySelectionToolbar',
+    fallback: <LoadingFallback minHeight={100} showText={false} />,
+  }
+);
+
+export const LazySelectionToolbarContent = createLazyComponent<SelectionToolbarContentProps>(
+  () => import('./parts/SelectionToolbar').then((m) => ({ default: m.SelectionToolbarContent })),
+  {
+    displayName: 'LazySelectionToolbarContent',
+    fallback: null,
+  }
+);
+
+export const LazySelectionToolbarAction = createLazyComponent<SelectionToolbarActionProps>(
+  () => import('./parts/SelectionToolbar').then((m) => ({ default: m.SelectionToolbarAction })),
+  {
+    displayName: 'LazySelectionToolbarAction',
+    fallback: null,
+  }
+);

package/src/tools/overlay/SelectionToolbar/parts/SelectionToolbar.tsx

@@ -0,0 +1,162 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { SelectionToolbarProvider, useSelectionToolbarContext } from '../context';
+import type {
+  SelectionToolbarProps,
+  SelectionToolbarContentProps,
+  SelectionToolbarActionProps,
+} from '../types';
+
+export function SelectionToolbar({
+  children,
+  minSelectionLength = 1,
+  onSelectionChange,
+}: SelectionToolbarProps) {
+  const [isVisible, setIsVisible] = React.useState(false);
+  const [selectedText, setSelectedText] = React.useState('');
+  const [selectionRect, setSelectionRect] = React.useState<DOMRect | null>(null);
+  const containerRef = React.useRef<HTMLDivElement>(null);
+
+  const hide = React.useCallback(() => {
+    setIsVisible(false);
+    setSelectedText('');
+    setSelectionRect(null);
+    window.getSelection()?.removeAllRanges();
+  }, []);
+
+  React.useEffect(() => {
+    const handleSelectionChange = () => {
+      const selection = window.getSelection();
+      if (!selection || selection.isCollapsed) {
+        setIsVisible(false);
+        return;
+      }
+
+      const text = selection.toString().trim();
+      if (text.length < minSelectionLength) {
+        setIsVisible(false);
+        return;
+      }
+
+      const range = selection.getRangeAt(0);
+      const rect = range.getBoundingClientRect();
+
+      // Only show if selection is within our container
+      const container = containerRef.current;
+      if (container) {
+        const containerRect = container.getBoundingClientRect();
+        const isInside =
+          rect.top >= containerRect.top &&
+          rect.bottom <= containerRect.bottom &&
+          rect.left >= containerRect.left &&
+          rect.right <= containerRect.right;
+        if (!isInside) {
+          setIsVisible(false);
+          return;
+        }
+      }
+
+      setSelectedText(text);
+      setSelectionRect(rect);
+      setIsVisible(true);
+      onSelectionChange?.(text);
+    };
+
+    document.addEventListener('selectionchange', handleSelectionChange);
+    return () => document.removeEventListener('selectionchange', handleSelectionChange);
+  }, [minSelectionLength, onSelectionChange]);
+
+  // Hide on click outside
+  React.useEffect(() => {
+    const handlePointerDown = (e: PointerEvent) => {
+      const target = e.target as Node;
+      const toolbarEl = containerRef.current?.querySelector('[data-slot="selection-toolbar-content"]');
+      if (toolbarEl && !toolbarEl.contains(target)) {
+        // Don't hide if clicking within the text container (let selectionchange handle it)
+        if (!containerRef.current?.contains(target)) {
+          hide();
+        }
+      }
+    };
+    document.addEventListener('pointerdown', handlePointerDown);
+    return () => document.removeEventListener('pointerdown', handlePointerDown);
+  }, [hide]);
+
+  const value = React.useMemo(
+    () => ({ isVisible, selectedText, selectionRect, hide }),
+    [isVisible, selectedText, selectionRect, hide]
+  );
+
+  return (
+    <SelectionToolbarProvider value={value}>
+      <div ref={containerRef} data-slot="selection-toolbar" className="relative">
+        {children}
+      </div>
+    </SelectionToolbarProvider>
+  );
+}
+SelectionToolbar.displayName = 'SelectionToolbar';
+
+export function SelectionToolbarContent({
+  children,
+  className,
+  offset = 8,
+}: SelectionToolbarContentProps) {
+  const { isVisible, selectionRect } = useSelectionToolbarContext();
+  const style = React.useMemo<React.CSSProperties>(() => {
+    if (!selectionRect) return { display: 'none' };
+    const top = selectionRect.top - offset;
+    const left = selectionRect.left + selectionRect.width / 2;
+    return {
+      position: 'fixed',
+      top: `${top}px`,
+      left: `${left}px`,
+      transform: 'translate(-50%, -100%)',
+      zIndex: 700,
+      pointerEvents: isVisible ? 'auto' : 'none',
+      opacity: isVisible ? 1 : 0,
+      transition: 'opacity 150ms ease',
+    };
+  }, [selectionRect, offset, isVisible]);
+
+  return (
+    <div
+      data-slot="selection-toolbar-content"
+      style={style}
+      className={cn(
+        'flex items-center gap-1 rounded-lg border border-border bg-background p-1 shadow-lg',
+        className
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+SelectionToolbarContent.displayName = 'SelectionToolbarContent';
+
+export function SelectionToolbarAction({
+  children,
+  className,
+  label,
+  ...props
+}: SelectionToolbarActionProps) {
+  return (
+    <button
+      type="button"
+      data-slot="selection-toolbar-action"
+      className={cn(
+        'inline-flex items-center justify-center rounded-md px-2.5 py-1.5',
+        'text-xs font-medium text-foreground hover:bg-muted transition-colors',
+        'disabled:opacity-50 disabled:pointer-events-none',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {label && <span className="ml-1">{label}</span>}
+    </button>
+  );
+}
+SelectionToolbarAction.displayName = 'SelectionToolbarAction';

package/src/tools/overlay/SelectionToolbar/parts/index.ts

@@ -0,0 +1,7 @@
+'use client';
+
+export {
+  SelectionToolbar,
+  SelectionToolbarContent,
+  SelectionToolbarAction,
+} from './SelectionToolbar';

package/src/tools/overlay/SelectionToolbar/types.ts

@@ -0,0 +1,31 @@
+'use client';
+
+import type * as React from 'react';
+
+export interface SelectionToolbarContextValue {
+  isVisible: boolean;
+  selectedText: string;
+  selectionRect: DOMRect | null;
+  hide: () => void;
+}
+
+export interface SelectionToolbarProps {
+  children: React.ReactNode;
+  /** Minimum characters to show toolbar */
+  minSelectionLength?: number;
+  /** Called when selection changes */
+  onSelectionChange?: (text: string) => void;
+}
+
+export interface SelectionToolbarContentProps {
+  children: React.ReactNode;
+  className?: string;
+  /** Offset from selection (px) */
+  offset?: number;
+}
+
+export interface SelectionToolbarActionProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  children: React.ReactNode;
+  /** Icon or label */
+  label?: string;
+}

package/src/tools/overlay/Tour/context/TourContext.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import * as React from 'react';
+import type { TourContextValue } from '../types';
+
+const TourContext = React.createContext<TourContextValue | null>(null);
+
+export function TourProvider({
+  children,
+  value,
+}: {
+  children: React.ReactNode;
+  value: TourContextValue;
+}) {
+  return (
+    <TourContext.Provider value={value}>
+      {children}
+    </TourContext.Provider>
+  );
+}
+
+export function useTourContext() {
+  const context = React.useContext(TourContext);
+  if (!context) {
+    throw new Error(
+      'useTourContext must be used within a TourProvider'
+    );
+  }
+  return context;
+}

package/src/tools/overlay/Tour/context/index.ts

@@ -0,0 +1,6 @@
+'use client';
+
+export {
+  TourProvider,
+  useTourContext,
+} from './TourContext';

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

@@ -0,0 +1,40 @@
+'use client';
+
+/**
+ * Tour
+ *
+ * Guided product tour with steps and popovers. Highlights elements
+ * and shows contextual information to onboard users.
+ *
+ * @example
+ * import { Tour, TourPopover, TourNavigation } from '@djangocfg/ui-tools/tour';
+ *
+ * const steps = [
+ *   { id: 'step1', target: '#header', title: 'Welcome', description: 'This is the header' },
+ *   { id: 'step2', target: '#sidebar', title: 'Navigation', description: 'Find your way around' },
+ * ];
+ *
+ * <Tour steps={steps} defaultOpen>
+ *   <TourPopover />
+ * </Tour>
+ */
+
+export {
+  Tour,
+  TourPopover,
+  TourSpotlight,
+  TourNavigation,
+} from './parts';
+
+export {
+  TourProvider,
+  useTourContext,
+} from './context';
+
+export type {
+  TourProps,
+  TourStep,
+  TourPopoverProps,
+  TourNavigationProps,
+  TourContextValue,
+} from './types';

package/src/tools/overlay/Tour/lazy.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+/**
+ * Lazy-loaded Tour Component
+ */
+
+import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import type {
+  TourProps,
+  TourPopoverProps,
+  TourNavigationProps,
+} from './types';
+
+export type {
+  TourProps,
+  TourPopoverProps,
+  TourNavigationProps,
+} from './types';
+
+export const LazyTour = createLazyComponent<TourProps>(
+  () => import('./parts/Tour').then((m) => ({ default: m.Tour })),
+  {
+    displayName: 'LazyTour',
+    fallback: <LoadingFallback minHeight={100} showText={false} />,
+  }
+);
+
+export const LazyTourPopover = createLazyComponent<TourPopoverProps>(
+  () => import('./parts/Tour').then((m) => ({ default: m.TourPopover })),
+  {
+    displayName: 'LazyTourPopover',
+    fallback: null,
+  }
+);
+
+export const LazyTourNavigation = createLazyComponent<TourNavigationProps>(
+  () => import('./parts/Tour').then((m) => ({ default: m.TourNavigation })),
+  {
+    displayName: 'LazyTourNavigation',
+    fallback: null,
+  }
+);

package/src/tools/overlay/Tour/parts/Tour.tsx

@@ -0,0 +1,278 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { Button } from '@djangocfg/ui-core/components';
+import {
+  Popover,
+  PopoverContent,
+  PopoverAnchor,
+} from '@djangocfg/ui-core/components';
+import { TourProvider, useTourContext } from '../context';
+import type {
+  TourProps,
+  TourPopoverProps,
+  TourNavigationProps,
+} from '../types';
+
+export function Tour({
+  children,
+  steps,
+  onComplete,
+  onDismiss,
+  defaultOpen = false,
+}: TourProps) {
+  const [isOpen, setIsOpen] = React.useState(defaultOpen);
+  const [currentStep, setCurrentStep] = React.useState(0);
+
+  const totalSteps = steps.length;
+
+  const goToStep = React.useCallback((index: number) => {
+    if (index >= 0 && index < steps.length) {
+      setCurrentStep(index);
+    }
+  }, [steps.length]);
+
+  const nextStep = React.useCallback(() => {
+    if (currentStep < totalSteps - 1) {
+      setCurrentStep((prev) => prev + 1);
+    } else {
+      setIsOpen(false);
+      onComplete?.();
+    }
+  }, [currentStep, totalSteps, onComplete]);
+
+  const prevStep = React.useCallback(() => {
+    setCurrentStep((prev) => Math.max(0, prev - 1));
+  }, []);
+
+  const close = React.useCallback(() => {
+    setIsOpen(false);
+    onDismiss?.();
+  }, [onDismiss]);
+
+  const open = React.useCallback(() => {
+    setCurrentStep(0);
+    setIsOpen(true);
+  }, []);
+
+  const value = React.useMemo(
+    () => ({
+      isOpen,
+      currentStep,
+      steps,
+      totalSteps,
+      goToStep,
+      nextStep,
+      prevStep,
+      close,
+      open,
+    }),
+    [isOpen, currentStep, steps, totalSteps, goToStep, nextStep, prevStep, close, open]
+  );
+
+  return (
+    <TourProvider value={value}>
+      <div data-slot="tour">{children}</div>
+    </TourProvider>
+  );
+}
+Tour.displayName = 'Tour';
+
+export function TourPopover({ className }: TourPopoverProps) {
+  const { isOpen, currentStep, steps, close } = useTourContext();
+  const step = steps[currentStep];
+  const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
+
+  React.useEffect(() => {
+    if (!step) return;
+    const el = document.querySelector(step.target) as HTMLElement | null;
+    setAnchorEl(el);
+  }, [step]);
+
+  if (!isOpen || !step || !anchorEl) return null;
+
+  return (
+    <Popover open={isOpen} onOpenChange={(open) => !open && close()}>
+      <PopoverAnchor virtualRef={{ current: anchorEl }} />
+      <PopoverContent
+        data-slot="tour-popover"
+        side={step.placement ?? 'bottom'}
+        align="center"
+        className={cn('w-80 p-4', className)}
+      >
+        <TourPopoverContent />
+      </PopoverContent>
+    </Popover>
+  );
+}
+TourPopover.displayName = 'TourPopover';
+
+const DEFAULT_SPOTLIGHT_PADDING = 8;
+
+interface TourSpotlightProps {
+  className?: string;
+  /** Pixels of breathing room around the target rectangle. Default: 8. */
+  padding?: number;
+  /** Background colour of the dimmed area. Default: `rgba(0,0,0,0.6)`. */
+  background?: string;
+  /** Show a ring around the highlighted target. Default: true. */
+  ring?: boolean;
+  /** Close the tour when clicking outside the spotlight. Default: false. */
+  closeOnClick?: boolean;
+}
+
+/**
+ * Spotlight overlay — full-viewport dim with a hole cut around the
+ * current step's target element. Mount once alongside `<TourPopover />`.
+ */
+export function TourSpotlight({
+  className,
+  padding = DEFAULT_SPOTLIGHT_PADDING,
+  background = 'rgba(0, 0, 0, 0.6)',
+  ring = true,
+  closeOnClick = false,
+}: TourSpotlightProps) {
+  const { isOpen, currentStep, steps, close } = useTourContext();
+  const step = steps[currentStep];
+  const [rect, setRect] = React.useState<DOMRect | null>(null);
+
+  React.useEffect(() => {
+    if (!isOpen || !step) {
+      setRect(null);
+      return;
+    }
+    const el = document.querySelector(step.target) as HTMLElement | null;
+    if (!el) {
+      setRect(null);
+      return;
+    }
+
+    const measure = () => setRect(el.getBoundingClientRect());
+    measure();
+
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    window.addEventListener('resize', measure);
+    window.addEventListener('scroll', measure, true);
+    return () => {
+      ro.disconnect();
+      window.removeEventListener('resize', measure);
+      window.removeEventListener('scroll', measure, true);
+    };
+  }, [isOpen, step]);
+
+  if (!isOpen || !rect) return null;
+
+  const x = Math.max(0, rect.left - padding);
+  const y = Math.max(0, rect.top - padding);
+  const w = rect.width + padding * 2;
+  const h = rect.height + padding * 2;
+
+  // Polygon mask: outer rectangle (viewport) minus inner rectangle (target).
+  // Traced as a single polygon — the inner cut-out is reached via a thin
+  // bridge along the left edge so the shape stays self-closing.
+  const clipPath = `polygon(
+    0% 0%,
+    0% 100%,
+    ${x}px 100%,
+    ${x}px ${y}px,
+    ${x + w}px ${y}px,
+    ${x + w}px ${y + h}px,
+    ${x}px ${y + h}px,
+    ${x}px 100%,
+    100% 100%,
+    100% 0%
+  )`;
+
+  return (
+    <>
+      <div
+        data-slot="tour-spotlight"
+        aria-hidden="true"
+        onClick={closeOnClick ? close : undefined}
+        className={cn(
+          'fixed inset-0 z-40 transition-[clip-path] duration-200',
+          closeOnClick && 'cursor-pointer',
+          className,
+        )}
+        style={{ background, clipPath }}
+      />
+      {ring && (
+        <div
+          data-slot="tour-spotlight-ring"
+          aria-hidden="true"
+          className="pointer-events-none fixed z-40 rounded-md ring-2 ring-primary/70 ring-offset-2 ring-offset-background transition-all duration-200"
+          style={{ left: x, top: y, width: w, height: h }}
+        />
+      )}
+    </>
+  );
+}
+TourSpotlight.displayName = 'TourSpotlight';
+
+function TourPopoverContent() {
+  const { currentStep, steps, totalSteps, nextStep, prevStep, close } = useTourContext();
+  const step = steps[currentStep];
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-start justify-between gap-2">
+        <div>
+          <h4 className="font-semibold text-sm">{step.title}</h4>
+          {step.description && (
+            <p className="text-muted-foreground text-sm mt-1">{step.description}</p>
+          )}
+        </div>
+        <button
+          type="button"
+          onClick={close}
+          className="text-muted-foreground hover:text-foreground transition-colors"
+          aria-label="Close tour"
+        >
+          <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+          </svg>
+        </button>
+      </div>
+
+      <TourNavigation />
+    </div>
+  );
+}
+
+export function TourNavigation({ className }: TourNavigationProps) {
+  const { currentStep, totalSteps, nextStep, prevStep, close } = useTourContext();
+  const isLast = currentStep === totalSteps - 1;
+
+  return (
+    <div
+      data-slot="tour-navigation"
+      className={cn('flex items-center justify-between pt-2 border-t border-border', className)}
+    >
+      <div className="flex gap-1">
+        {Array.from({ length: totalSteps }).map((_, i) => (
+          <div
+            key={i}
+            data-active={i === currentStep ? 'true' : undefined}
+            className={cn(
+              'h-1.5 w-1.5 rounded-full transition-colors',
+              i === currentStep ? 'bg-primary' : 'bg-muted-foreground/30'
+            )}
+          />
+        ))}
+      </div>
+      <div className="flex items-center gap-2">
+        {currentStep > 0 && (
+          <Button variant="ghost" size="sm" onClick={prevStep}>
+            Back
+          </Button>
+        )}
+        <Button size="sm" onClick={nextStep}>
+          {isLast ? 'Finish' : 'Next'}
+        </Button>
+      </div>
+    </div>
+  );
+}
+TourNavigation.displayName = 'TourNavigation';

package/src/tools/overlay/Tour/parts/index.ts

@@ -0,0 +1,8 @@
+'use client';
+
+export {
+  Tour,
+  TourPopover,
+  TourSpotlight,
+  TourNavigation,
+} from './Tour';