@djangocfg/ui-tools 2.1.411 → 2.1.413

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

@@ -0,0 +1,6 @@
+'use client';
+
+export {
+  ResponsiveDialogProvider,
+  useResponsiveDialogContext,
+} from './ResponsiveDialogContext';

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

@@ -0,0 +1,48 @@
+'use client';
+
+/**
+ * ResponsiveDialog
+ *
+ * Dialog on desktop, Drawer on mobile. Automatically switches based on viewport.
+ * Wraps ui-core's Dialog and Drawer primitives with a unified API.
+ *
+ * @example
+ * import { ResponsiveDialog, ResponsiveDialogContent, ResponsiveDialogHeader, ResponsiveDialogTitle, ResponsiveDialogDescription, ResponsiveDialogFooter } from '@djangocfg/ui-tools/responsive-dialog';
+ *
+ * <ResponsiveDialog open={open} onOpenChange={setOpen}>
+ *   <ResponsiveDialogContent>
+ *     <ResponsiveDialogHeader>
+ *       <ResponsiveDialogTitle>Title</ResponsiveDialogTitle>
+ *       <ResponsiveDialogDescription>Description</ResponsiveDialogDescription>
+ *     </ResponsiveDialogHeader>
+ *     <div>Content</div>
+ *     <ResponsiveDialogFooter>
+ *       <Button>Close</Button>
+ *     </ResponsiveDialogFooter>
+ *   </ResponsiveDialogContent>
+ * </ResponsiveDialog>
+ */
+
+export {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+  ResponsiveDialogDescription,
+  ResponsiveDialogFooter,
+} from './parts';
+
+export {
+  ResponsiveDialogProvider,
+  useResponsiveDialogContext,
+} from './context';
+
+export type {
+  ResponsiveDialogProps,
+  ResponsiveDialogContentProps,
+  ResponsiveDialogHeaderProps,
+  ResponsiveDialogTitleProps,
+  ResponsiveDialogDescriptionProps,
+  ResponsiveDialogFooterProps,
+  ResponsiveDialogContextValue,
+} from './types';

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

@@ -0,0 +1,90 @@
+'use client';
+
+/**
+ * Lazy-loaded ResponsiveDialog Component
+ *
+ * ResponsiveDialog is lightweight but lazy-loaded for consistency
+ * with other ui-tools components.
+ *
+ * @example
+ * import { LazyResponsiveDialog, LazyResponsiveDialogContent } from '@djangocfg/ui-tools/responsive-dialog';
+ */
+
+import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import type {
+  ResponsiveDialogProps,
+  ResponsiveDialogContentProps,
+  ResponsiveDialogHeaderProps,
+  ResponsiveDialogTitleProps,
+  ResponsiveDialogDescriptionProps,
+  ResponsiveDialogFooterProps,
+} from './types';
+
+export type {
+  ResponsiveDialogProps,
+  ResponsiveDialogContentProps,
+  ResponsiveDialogHeaderProps,
+  ResponsiveDialogTitleProps,
+  ResponsiveDialogDescriptionProps,
+  ResponsiveDialogFooterProps,
+} from './types';
+
+export const LazyResponsiveDialog = createLazyComponent<
+  ResponsiveDialogProps
+>(
+  () => import('./parts/ResponsiveDialog').then((m) => ({ default: m.ResponsiveDialog })),
+  {
+    displayName: 'LazyResponsiveDialog',
+    fallback: <LoadingFallback minHeight={100} showText={false} />,
+  }
+);
+
+export const LazyResponsiveDialogContent = createLazyComponent<
+  ResponsiveDialogContentProps
+>(
+  () => import('./parts/ResponsiveDialog').then((m) => ({ default: m.ResponsiveDialogContent })),
+  {
+    displayName: 'LazyResponsiveDialogContent',
+    fallback: null,
+  }
+);
+
+export const LazyResponsiveDialogHeader = createLazyComponent<
+  ResponsiveDialogHeaderProps
+>(
+  () => import('./parts/ResponsiveDialog').then((m) => ({ default: m.ResponsiveDialogHeader })),
+  {
+    displayName: 'LazyResponsiveDialogHeader',
+    fallback: null,
+  }
+);
+
+export const LazyResponsiveDialogTitle = createLazyComponent<
+  ResponsiveDialogTitleProps
+>(
+  () => import('./parts/ResponsiveDialog').then((m) => ({ default: m.ResponsiveDialogTitle })),
+  {
+    displayName: 'LazyResponsiveDialogTitle',
+    fallback: null,
+  }
+);
+
+export const LazyResponsiveDialogDescription = createLazyComponent<
+  ResponsiveDialogDescriptionProps
+>(
+  () => import('./parts/ResponsiveDialog').then((m) => ({ default: m.ResponsiveDialogDescription })),
+  {
+    displayName: 'LazyResponsiveDialogDescription',
+    fallback: null,
+  }
+);
+
+export const LazyResponsiveDialogFooter = createLazyComponent<
+  ResponsiveDialogFooterProps
+>(
+  () => import('./parts/ResponsiveDialog').then((m) => ({ default: m.ResponsiveDialogFooter })),
+  {
+    displayName: 'LazyResponsiveDialogFooter',
+    fallback: null,
+  }
+);

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

@@ -0,0 +1,87 @@
+'use client';
+
+import * as React from 'react';
+import { useIsMobile } from '@djangocfg/ui-core/hooks';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Drawer,
+  DrawerContent,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerTitle,
+} from '@djangocfg/ui-core/components';
+import { ResponsiveDialogProvider, useResponsiveDialogContext } from '../context';
+import type {
+  ResponsiveDialogProps,
+  ResponsiveDialogContentProps,
+  ResponsiveDialogHeaderProps,
+  ResponsiveDialogTitleProps,
+  ResponsiveDialogDescriptionProps,
+  ResponsiveDialogFooterProps,
+} from '../types';
+
+export function ResponsiveDialog({ open, onOpenChange, children }: ResponsiveDialogProps) {
+  const isMobile = useIsMobile();
+
+  const Root = isMobile ? Drawer : Dialog;
+
+  return (
+    <ResponsiveDialogProvider value={{ isMobile }}>
+      <Root open={open} onOpenChange={onOpenChange}>
+        {children}
+      </Root>
+    </ResponsiveDialogProvider>
+  );
+}
+ResponsiveDialog.displayName = 'ResponsiveDialog';
+
+export function ResponsiveDialogContent({ children, className }: ResponsiveDialogContentProps) {
+  const { isMobile } = useResponsiveDialogContext();
+  if (isMobile) {
+    return <DrawerContent className={className} height="auto">{children}</DrawerContent>;
+  }
+  return <DialogContent className={className}>{children}</DialogContent>;
+}
+ResponsiveDialogContent.displayName = 'ResponsiveDialogContent';
+
+export function ResponsiveDialogHeader({ className, ...props }: ResponsiveDialogHeaderProps) {
+  const { isMobile } = useResponsiveDialogContext();
+  if (isMobile) {
+    return <DrawerHeader className={className} {...props} />;
+  }
+  return <DialogHeader className={className} {...props} />;
+}
+ResponsiveDialogHeader.displayName = 'ResponsiveDialogHeader';
+
+export function ResponsiveDialogTitle({ className, ...props }: ResponsiveDialogTitleProps) {
+  const { isMobile } = useResponsiveDialogContext();
+  if (isMobile) {
+    return <DrawerTitle className={className} {...props} />;
+  }
+  return <DialogTitle className={className} {...props} />;
+}
+ResponsiveDialogTitle.displayName = 'ResponsiveDialogTitle';
+
+export function ResponsiveDialogDescription({ className, ...props }: ResponsiveDialogDescriptionProps) {
+  const { isMobile } = useResponsiveDialogContext();
+  if (isMobile) {
+    return <DrawerDescription className={className} {...props} />;
+  }
+  return <DialogDescription className={className} {...props} />;
+}
+ResponsiveDialogDescription.displayName = 'ResponsiveDialogDescription';
+
+export function ResponsiveDialogFooter({ className, ...props }: ResponsiveDialogFooterProps) {
+  const { isMobile } = useResponsiveDialogContext();
+  if (isMobile) {
+    return <DrawerFooter className={className} {...props} />;
+  }
+  return <DialogFooter className={className} {...props} />;
+}
+ResponsiveDialogFooter.displayName = 'ResponsiveDialogFooter';

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

@@ -0,0 +1,10 @@
+'use client';
+
+export {
+  ResponsiveDialog,
+  ResponsiveDialogContent,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+  ResponsiveDialogDescription,
+  ResponsiveDialogFooter,
+} from './ResponsiveDialog';

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

@@ -0,0 +1,26 @@
+'use client';
+
+import type * as React from 'react';
+
+export interface ResponsiveDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  children: React.ReactNode;
+}
+
+export interface ResponsiveDialogContentProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface ResponsiveDialogHeaderProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+export interface ResponsiveDialogTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {}
+
+export interface ResponsiveDialogDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {}
+
+export interface ResponsiveDialogFooterProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+export interface ResponsiveDialogContextValue {
+  isMobile: boolean;
+}

package/src/tools/overlay/ScrollSpy/context/ScrollSpyContext.tsx

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

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

@@ -0,0 +1,6 @@
+'use client';
+
+export {
+  ScrollSpyProvider,
+  useScrollSpyContext,
+} from './ScrollSpyContext';

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

@@ -0,0 +1,40 @@
+'use client';
+
+/**
+ * ScrollSpy
+ *
+ * Navigation that highlights the active section based on scroll position.
+ * Uses IntersectionObserver for efficient viewport detection.
+ *
+ * @example
+ * import { ScrollSpy, ScrollSpyNav, ScrollSpyNavItem, ScrollSpySection } from '@djangocfg/ui-tools/scroll-spy';
+ *
+ * <ScrollSpy>
+ *   <ScrollSpyNav>
+ *     <ScrollSpyNavItem sectionId="intro">Intro</ScrollSpyNavItem>
+ *     <ScrollSpyNavItem sectionId="details">Details</ScrollSpyNavItem>
+ *   </ScrollSpyNav>
+ *   <ScrollSpySection id="intro" label="Intro">...</ScrollSpySection>
+ *   <ScrollSpySection id="details" label="Details">...</ScrollSpySection>
+ * </ScrollSpy>
+ */
+
+export {
+  ScrollSpy,
+  ScrollSpyNav,
+  ScrollSpyNavItem,
+  ScrollSpySection,
+} from './parts';
+
+export {
+  ScrollSpyProvider,
+  useScrollSpyContext,
+} from './context';
+
+export type {
+  ScrollSpyProps,
+  ScrollSpyNavProps,
+  ScrollSpyNavItemProps,
+  ScrollSpySectionProps,
+  ScrollSpyContextValue,
+} from './types';

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

@@ -0,0 +1,52 @@
+'use client';
+
+/**
+ * Lazy-loaded ScrollSpy Component
+ */
+
+import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import type {
+  ScrollSpyProps,
+  ScrollSpyNavProps,
+  ScrollSpyNavItemProps,
+  ScrollSpySectionProps,
+} from './types';
+
+export type {
+  ScrollSpyProps,
+  ScrollSpyNavProps,
+  ScrollSpyNavItemProps,
+  ScrollSpySectionProps,
+} from './types';
+
+export const LazyScrollSpy = createLazyComponent<ScrollSpyProps>(
+  () => import('./parts/ScrollSpy').then((m) => ({ default: m.ScrollSpy })),
+  {
+    displayName: 'LazyScrollSpy',
+    fallback: <LoadingFallback minHeight={100} showText={false} />,
+  }
+);
+
+export const LazyScrollSpyNav = createLazyComponent<ScrollSpyNavProps>(
+  () => import('./parts/ScrollSpy').then((m) => ({ default: m.ScrollSpyNav })),
+  {
+    displayName: 'LazyScrollSpyNav',
+    fallback: null,
+  }
+);
+
+export const LazyScrollSpyNavItem = createLazyComponent<ScrollSpyNavItemProps>(
+  () => import('./parts/ScrollSpy').then((m) => ({ default: m.ScrollSpyNavItem })),
+  {
+    displayName: 'LazyScrollSpyNavItem',
+    fallback: null,
+  }
+);
+
+export const LazyScrollSpySection = createLazyComponent<ScrollSpySectionProps>(
+  () => import('./parts/ScrollSpy').then((m) => ({ default: m.ScrollSpySection })),
+  {
+    displayName: 'LazyScrollSpySection',
+    fallback: null,
+  }
+);

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

@@ -0,0 +1,184 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { ScrollSpyProvider, useScrollSpyContext } from '../context';
+import type {
+  ScrollSpyProps,
+  ScrollSpyNavProps,
+  ScrollSpyNavItemProps,
+  ScrollSpySectionProps,
+} from '../types';
+
+export function ScrollSpy({
+  children,
+  offset = 0,
+  rootMargin = '0px 0px -80% 0px',
+  onActiveChange,
+}: ScrollSpyProps) {
+  const [activeId, setActiveId] = React.useState<string | null>(null);
+  const sectionsRef = React.useRef<Map<string, string>>(new Map());
+  const observerRef = React.useRef<IntersectionObserver | null>(null);
+
+  const registerSection = React.useCallback((id: string, label: string) => {
+    sectionsRef.current.set(id, label);
+  }, []);
+
+  const unregisterSection = React.useCallback((id: string) => {
+    sectionsRef.current.delete(id);
+  }, []);
+
+  const handleSetActiveId = React.useCallback(
+    (id: string) => {
+      setActiveId(id);
+      onActiveChange?.(id);
+    },
+    [onActiveChange]
+  );
+
+  React.useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries
+          .filter((e) => e.isIntersecting)
+          .sort((a, b) => b.intersectionRatio - a.intersectionRatio);
+        if (visible.length > 0) {
+          handleSetActiveId(visible[0].target.id);
+        }
+      },
+      {
+        rootMargin,
+        threshold: [0, 0.25, 0.5, 0.75, 1],
+      }
+    );
+    observerRef.current = observer;
+
+    // Observe all registered section elements
+    const sectionIds = Array.from(sectionsRef.current.keys());
+    sectionIds.forEach((id) => {
+      const el = document.getElementById(id);
+      if (el) observer.observe(el);
+    });
+
+    return () => observer.disconnect();
+  }, [rootMargin, handleSetActiveId]);
+
+  // Re-observe when sections change
+  React.useEffect(() => {
+    const observer = observerRef.current;
+    if (!observer) return;
+
+    observer.disconnect();
+    const sectionIds = Array.from(sectionsRef.current.keys());
+    sectionIds.forEach((id) => {
+      const el = document.getElementById(id);
+      if (el) observer.observe(el);
+    });
+  });
+
+  const sections = React.useMemo(
+    () =>
+      Array.from(sectionsRef.current.entries()).map(([id, label]) => ({
+        id,
+        label,
+      })),
+    [activeId] // recompute when active changes to keep in sync
+  );
+
+  const value = React.useMemo(
+    () => ({
+      activeId,
+      sections,
+      registerSection,
+      unregisterSection,
+      setActiveId: handleSetActiveId,
+    }),
+    [activeId, sections, registerSection, unregisterSection, handleSetActiveId]
+  );
+
+  return <ScrollSpyProvider value={value}>{children}</ScrollSpyProvider>;
+}
+ScrollSpy.displayName = 'ScrollSpy';
+
+export function ScrollSpyNav({ children, className, ...props }: ScrollSpyNavProps) {
+  return (
+    <nav
+      data-slot="scroll-spy-nav"
+      className={cn('flex flex-col gap-1', className)}
+      {...props}
+    >
+      {children}
+    </nav>
+  );
+}
+ScrollSpyNav.displayName = 'ScrollSpyNav';
+
+export function ScrollSpyNavItem({
+  sectionId,
+  children,
+  className,
+  onClick,
+  ...props
+}: ScrollSpyNavItemProps) {
+  const { activeId } = useScrollSpyContext();
+  const isActive = activeId === sectionId;
+
+  const handleClick = React.useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>) => {
+      e.preventDefault();
+      const el = document.getElementById(sectionId);
+      if (el) {
+        el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      }
+      onClick?.(e);
+    },
+    [sectionId, onClick]
+  );
+
+  return (
+    <a
+      href={`#${sectionId}`}
+      data-slot="scroll-spy-nav-item"
+      data-active={isActive ? 'true' : undefined}
+      onClick={handleClick}
+      className={cn(
+        'relative rounded-md px-3 py-1.5 text-sm transition-colors',
+        'text-muted-foreground hover:text-foreground hover:bg-muted/50',
+        isActive &&
+          'font-medium text-foreground bg-muted before:absolute before:left-0 before:top-1.5 before:bottom-1.5 before:w-0.5 before:rounded-full before:bg-primary'
+      )}
+      {...props}
+    >
+      {children}
+    </a>
+  );
+}
+ScrollSpyNavItem.displayName = 'ScrollSpyNavItem';
+
+export function ScrollSpySection({
+  id,
+  label,
+  children,
+  className,
+  ...props
+}: ScrollSpySectionProps) {
+  const { registerSection, unregisterSection } = useScrollSpyContext();
+
+  React.useEffect(() => {
+    registerSection(id, label);
+    return () => unregisterSection(id);
+  }, [id, label, registerSection, unregisterSection]);
+
+  return (
+    <div
+      id={id}
+      data-slot="scroll-spy-section"
+      data-section-id={id}
+      className={cn('scroll-mt-20', className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+ScrollSpySection.displayName = 'ScrollSpySection';

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

@@ -0,0 +1,8 @@
+'use client';
+
+export {
+  ScrollSpy,
+  ScrollSpyNav,
+  ScrollSpyNavItem,
+  ScrollSpySection,
+} from './ScrollSpy';

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

@@ -0,0 +1,41 @@
+'use client';
+
+import type * as React from 'react';
+
+export interface ScrollSpySection {
+  id: string;
+  label: string;
+}
+
+export interface ScrollSpyContextValue {
+  activeId: string | null;
+  sections: ScrollSpySection[];
+  registerSection: (id: string, label: string) => void;
+  unregisterSection: (id: string) => void;
+  setActiveId: (id: string) => void;
+}
+
+export interface ScrollSpyProps {
+  children: React.ReactNode;
+  /** Offset from top when calculating active section (px) */
+  offset?: number;
+  /** Root margin for IntersectionObserver */
+  rootMargin?: string;
+  /** Called when active section changes */
+  onActiveChange?: (id: string | null) => void;
+}
+
+export interface ScrollSpyNavProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+}
+
+export interface ScrollSpyNavItemProps extends React.HTMLAttributes<HTMLAnchorElement> {
+  sectionId: string;
+  children: React.ReactNode;
+}
+
+export interface ScrollSpySectionProps extends React.HTMLAttributes<HTMLDivElement> {
+  id: string;
+  label: string;
+  children: React.ReactNode;
+}

package/src/tools/overlay/SelectionToolbar/context/SelectionToolbarContext.tsx

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

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

@@ -0,0 +1,6 @@
+'use client';
+
+export {
+  SelectionToolbarProvider,
+  useSelectionToolbarContext,
+} from './SelectionToolbarContext';