@djangocfg/layouts 1.2.17 → 1.2.19

package/src/layouts/UILayout/core/UILayout.tsx

@@ -0,0 +1,102 @@
+/**
+ * UILayout
+ * Modern, config-driven layout for UI component documentation
+ */
+
+'use client';
+
+import React from 'react';
+import { Tabs, TabsList, TabsTrigger } from '@djangocfg/ui';
+import { Header } from '../components/layout/Header';
+import { generateAIContext } from '../config';
+import type { UILayoutProps } from '../types';
+
+
+/**
+ * UILayout - Main layout component for UI documentation
+ *
+ * Features:
+ * - Config-driven: All component data comes from centralized config
+ * - "Copy for AI": One-click export of all documentation
+ * - Responsive: Auto-converts to mobile sheet menu on mobile
+ * - Type-safe: Full TypeScript support
+ *
+ * @example
+ * ```tsx
+ * <UILayout
+ *   title="UI Components"
+ *   categories={CATEGORIES}
+ *   currentCategory={category}
+ *   onCategoryChange={setCategory}
+ * >
+ *   <CategoryRenderer categoryId={category} />
+ * </UILayout>
+ * ```
+ */
+export function UILayout({
+  children,
+  title = "UI Component Library",
+  description,
+  categories,
+  currentCategory,
+  onCategoryChange,
+  logo,
+  projectName = "Django CFG UI",
+}: UILayoutProps) {
+  const handleCopyForAI = () => {
+    return generateAIContext();
+  };
+
+  return (
+    <div className="flex flex-col min-h-screen bg-background">
+      {/* Header with Copy for AI button */}
+      <Header
+        title={title}
+        projectName={projectName}
+        logo={logo}
+        onCopyForAI={handleCopyForAI}
+      />
+
+      {/* Category Navigation Tabs */}
+      <div className="container mx-auto max-w-7xl px-4 sm:px-6 lg:px-8 py-3">
+        <Tabs
+          value={currentCategory}
+          onValueChange={onCategoryChange}
+          mobileSheet
+          mobileTitleText="UI Library"
+          mobileSheetTitle="Categories"
+          sticky
+        >
+          <TabsList fullWidth className="h-auto flex-wrap">
+            {categories.map((category) => (
+              <TabsTrigger
+                key={category.id}
+                value={category.id}
+                flexEqual
+                className="gap-2 whitespace-nowrap"
+              >
+                {category.icon}
+                <span>{category.label}</span>
+                {category.count !== undefined && (
+                  <span className="ml-1 text-xs opacity-60">({category.count})</span>
+                )}
+              </TabsTrigger>
+            ))}
+          </TabsList>
+        </Tabs>
+      </div>
+
+      {/* Main Content */}
+      <main className="flex-1">
+        <div className="container max-w-7xl mx-auto p-6">
+          {description && (
+            <p className="text-sm text-muted-foreground mb-6">
+              {description}
+            </p>
+          )}
+          {children}
+        </div>
+      </main>
+    </div>
+  );
+}

package/src/layouts/UILayout/core/index.ts

@@ -0,0 +1,9 @@
+/**
+ * UILayout Core Components
+ * Main layout components
+ */
+
+export { UILayout } from './UILayout';
+export { UIGuideApp } from './UIGuideApp';
+export { default as UIGuideView } from './UIGuideView';
+export { UIGuideLanding } from './UIGuideLanding';

package/src/layouts/UILayout/hooks/index.ts

@@ -0,0 +1,9 @@
+/**
+ * UILayout Hooks
+ * Custom hooks for UILayout functionality
+ */
+
+export { useAIExport } from './useAIExport';
+export { useCategoryNavigation } from './useCategoryNavigation';
+export { useComponentSearch } from './useComponentSearch';
+export { useSidebarState } from './useSidebarState';

package/src/layouts/UILayout/hooks/useAIExport.ts

@@ -0,0 +1,78 @@
+/**
+ * useAIExport Hook
+ * Handles AI context export with copy to clipboard
+ */
+
+'use client';
+
+import { useState, useCallback } from 'react';
+import { useCopy } from '@djangocfg/ui';
+
+interface UseAIExportOptions {
+  /** Function to generate AI context */
+  generateContext?: () => string;
+  /** Success callback */
+  onSuccess?: () => void;
+  /** Error callback */
+  onError?: (error: Error) => void;
+  /** Duration to show "copied" state (ms) */
+  copiedDuration?: number;
+}
+
+interface UseAIExportReturn {
+  /** Is currently in "copied" state */
+  copied: boolean;
+  /** Export function */
+  exportForAI: () => Promise<void>;
+  /** Reset copied state */
+  reset: () => void;
+}
+
+/**
+ * Hook for AI export functionality
+ * Handles copying AI context to clipboard with visual feedback
+ */
+export function useAIExport(options: UseAIExportOptions = {}): UseAIExportReturn {
+  const {
+    generateContext,
+    onSuccess,
+    onError,
+    copiedDuration = 2000,
+  } = options;
+
+  const [copied, setCopied] = useState(false);
+  const { copyToClipboard } = useCopy();
+
+  const exportForAI = useCallback(async () => {
+    try {
+      // Generate context
+      const context = generateContext?.() || '';
+
+      // Copy to clipboard
+      await copyToClipboard(context);
+
+      // Set copied state
+      setCopied(true);
+
+      // Reset after duration
+      setTimeout(() => {
+        setCopied(false);
+      }, copiedDuration);
+
+      // Success callback
+      onSuccess?.();
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  }, [generateContext, copyToClipboard, copiedDuration, onSuccess, onError]);
+
+  const reset = useCallback(() => {
+    setCopied(false);
+  }, []);
+
+  return {
+    copied,
+    exportForAI,
+    reset,
+  };
+}

package/src/layouts/UILayout/hooks/useCategoryNavigation.ts

@@ -0,0 +1,92 @@
+/**
+ * useCategoryNavigation Hook
+ * Manages category navigation with history
+ */
+
+'use client';
+
+import { useState, useCallback, useMemo } from 'react';
+import type { NavigationState } from '../types';
+
+interface UseCategoryNavigationOptions {
+  /** Initial category */
+  initialCategory?: string;
+  /** On category change callback */
+  onCategoryChange?: (categoryId: string) => void;
+}
+
+interface UseCategoryNavigationReturn extends NavigationState {
+  /** Navigate to a category */
+  navigateTo: (categoryId: string) => void;
+  /** Go back in history */
+  goBack: () => void;
+  /** Go forward in history */
+  goForward: () => void;
+}
+
+/**
+ * Hook for category navigation with history support
+ */
+export function useCategoryNavigation(
+  options: UseCategoryNavigationOptions = {}
+): UseCategoryNavigationReturn {
+  const { initialCategory = 'overview', onCategoryChange } = options;
+
+  const [currentCategory, setCurrentCategory] = useState(initialCategory);
+  const [history, setHistory] = useState<string[]>([initialCategory]);
+  const [historyIndex, setHistoryIndex] = useState(0);
+
+  const canGoBack = useMemo(() => historyIndex > 0, [historyIndex]);
+  const canGoForward = useMemo(
+    () => historyIndex < history.length - 1,
+    [historyIndex, history.length]
+  );
+
+  const navigateTo = useCallback(
+    (categoryId: string) => {
+      if (categoryId === currentCategory) return;
+
+      // Remove forward history if we're not at the end
+      const newHistory = history.slice(0, historyIndex + 1);
+      newHistory.push(categoryId);
+
+      setHistory(newHistory);
+      setHistoryIndex(newHistory.length - 1);
+      setCurrentCategory(categoryId);
+      onCategoryChange?.(categoryId);
+    },
+    [currentCategory, history, historyIndex, onCategoryChange]
+  );
+
+  const goBack = useCallback(() => {
+    if (!canGoBack) return;
+
+    const newIndex = historyIndex - 1;
+    const categoryId = history[newIndex];
+
+    setHistoryIndex(newIndex);
+    setCurrentCategory(categoryId);
+    onCategoryChange?.(categoryId);
+  }, [canGoBack, historyIndex, history, onCategoryChange]);
+
+  const goForward = useCallback(() => {
+    if (!canGoForward) return;
+
+    const newIndex = historyIndex + 1;
+    const categoryId = history[newIndex];
+
+    setHistoryIndex(newIndex);
+    setCurrentCategory(categoryId);
+    onCategoryChange?.(categoryId);
+  }, [canGoForward, historyIndex, history, onCategoryChange]);
+
+  return {
+    currentCategory,
+    history,
+    canGoBack,
+    canGoForward,
+    navigateTo,
+    goBack,
+    goForward,
+  };
+}

package/src/layouts/UILayout/hooks/useComponentSearch.ts

@@ -0,0 +1,81 @@
+/**
+ * useComponentSearch Hook
+ * Search and filter components
+ */
+
+'use client';
+
+import { useState, useCallback, useMemo } from 'react';
+import type { ComponentConfig } from '../types';
+
+interface UseComponentSearchOptions {
+  /** All available components */
+  components: ComponentConfig[];
+  /** Search in these fields */
+  searchFields?: Array<keyof ComponentConfig>;
+}
+
+interface UseComponentSearchReturn {
+  /** Search query */
+  query: string;
+  /** Set search query */
+  setQuery: (query: string) => void;
+  /** Filtered results */
+  results: ComponentConfig[];
+  /** Clear search */
+  clear: () => void;
+  /** Is searching */
+  isSearching: boolean;
+}
+
+/**
+ * Hook for searching components
+ * Supports fuzzy search across multiple fields
+ */
+export function useComponentSearch(
+  options: UseComponentSearchOptions
+): UseComponentSearchReturn {
+  const {
+    components,
+    searchFields = ['name', 'description', 'category'],
+  } = options;
+
+  const [query, setQuery] = useState('');
+
+  const results = useMemo(() => {
+    if (!query.trim()) {
+      return components;
+    }
+
+    const lowerQuery = query.toLowerCase();
+
+    return components.filter((component) => {
+      return searchFields.some((field) => {
+        const value = component[field];
+        if (typeof value === 'string') {
+          return value.toLowerCase().includes(lowerQuery);
+        }
+        if (Array.isArray(value)) {
+          return value.some((item) =>
+            String(item).toLowerCase().includes(lowerQuery)
+          );
+        }
+        return false;
+      });
+    });
+  }, [query, components, searchFields]);
+
+  const clear = useCallback(() => {
+    setQuery('');
+  }, []);
+
+  const isSearching = useMemo(() => query.trim().length > 0, [query]);
+
+  return {
+    query,
+    setQuery,
+    results,
+    clear,
+    isSearching,
+  };
+}

package/src/layouts/UILayout/hooks/useSidebarState.ts

@@ -0,0 +1,36 @@
+/**
+ * useSidebarState Hook
+ * Manages sidebar open/close state
+ */
+
+'use client';
+
+import { useState, useCallback } from 'react';
+import type { SidebarState } from '../types';
+
+/**
+ * Hook for managing sidebar state
+ * Provides open/close/toggle functionality
+ */
+export function useSidebarState(): SidebarState {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const toggle = useCallback(() => {
+    setIsOpen(prev => !prev);
+  }, []);
+
+  const open = useCallback(() => {
+    setIsOpen(true);
+  }, []);
+
+  const close = useCallback(() => {
+    setIsOpen(false);
+  }, []);
+
+  return {
+    isOpen,
+    toggle,
+    open,
+    close,
+  };
+}

package/src/layouts/UILayout/index.ts

@@ -1,29 +1,90 @@
 /**
  * UILayout Module Exports
- * Config-driven UI documentation layout
+ * Декомпозированная, модульная архитектура для UI документации
  */
 
-// Main Layout Component
-export { UILayout, ComponentShowcaseLayout } from './UILayout';
-export type { UILayoutProps, ComponentShowcaseLayoutProps } from './UILayout';
+// ============================================================================
+// CORE COMPONENTS
+// ============================================================================
 
-// Context for navigation management
-export { ShowcaseProvider, useShowcase } from './context';
+export {
+  UILayout,
+  UIGuideApp,
+  UIGuideView,
+  UIGuideLanding,
+} from './core';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export type {
+  // Component types
+  ComponentConfig,
+  ComponentCategory,
+  // Layout types
+  UILayoutProps,
+  LayoutConfig,
+  UILayoutConfig,
+  // Navigation types
+  NavigationState,
+  SidebarState,
+} from './types';
 
-// UI Guide View (specific implementation for Django CFG UI)
-export { default as UIGuideView } from './UIGuideView';
-export { UIGuideLanding } from './UIGuideLanding';
-export { UIGuideApp } from './UIGuideApp';
+// ============================================================================
+// HOOKS
+// ============================================================================
 
-// Components
-export { AutoComponentDemo, CategorySection } from './components/AutoComponentDemo';
-export { CategoryRenderer } from './components/CategoryRenderer';
-export { TailwindGuideRenderer } from './components/TailwindGuideRenderer';
-export { Sidebar } from './components/Sidebar';
-export { Header } from './components/Header';
-export { MobileOverlay } from './components/MobileOverlay';
+export {
+  useSidebarState,
+  useAIExport,
+  useCategoryNavigation,
+  useComponentSearch,
+} from './hooks';
+
+// ============================================================================
+// COMPONENTS
+// ============================================================================
+
+// Layout components
+export {
+  Header,
+  HeaderMobile,
+  HeaderDesktop,
+  CopyAIButton,
+  Sidebar,
+  SidebarContent,
+  SidebarCategory,
+  SidebarFooter,
+  MobileOverlay,
+} from './components/layout';
+
+export type {
+  HeaderProps,
+  SidebarProps,
+  MobileOverlayProps,
+} from './components/layout';
+
+// Shared components
+export {
+  CountBadge,
+  CodeBlock,
+  CopyButton,
+  Section,
+} from './components/shared';
+
+// Content components
+export {
+  AutoComponentDemo,
+  CategorySection,
+  CategoryRenderer,
+  TailwindGuideRenderer,
+} from './components';
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
 
-// Configuration (Single Source of Truth)
 export {
   // All components
   COMPONENTS_CONFIG,
@@ -52,13 +113,51 @@ export {
   generateAIContext,
 } from './config';
 
-// Types
 export type {
-  ComponentConfig,
-  ComponentCategory,
   TailwindGuide,
   UILibraryConfig,
 } from './config';
 
-// Constants
+// ============================================================================
+// UTILITIES
+// ============================================================================
+
+export {
+  // AI Export utilities
+  generateAIContext as generateAIContextNew,
+  generateTailwindSection,
+  generateComponentsSection,
+  generateComponentDoc,
+  formatComponentAsMarkdown,
+  formatComponentsAsMarkdownList,
+  formatImports,
+  formatCodeBlock,
+  formatSectionHeader,
+  formatList,
+  // Component helpers
+  searchComponents,
+  filterByCategory,
+  filterByTags,
+  getUniqueCategories,
+  getUniqueTags,
+  findComponentByName,
+  applyFilters,
+  sortComponents,
+  groupComponentsBy,
+} from './utils';
+
+export type {
+  FilterOptions,
+} from './utils/component-helpers/filter';
+
+// ============================================================================
+// CONTEXT
+// ============================================================================
+
+export { ShowcaseProvider, useShowcase } from './context';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
 export * from './constants';

package/src/layouts/UILayout/types/component.ts

@@ -0,0 +1,45 @@
+/**
+ * Component Configuration Types
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * Component Configuration
+ * Defines metadata and content for a single component
+ */
+export interface ComponentConfig {
+  /** Component name (e.g., "Button") */
+  name: string;
+  /** Category ID this component belongs to */
+  category: string;
+  /** Short description of the component */
+  description: string;
+  /** Import statement (e.g., "import { Button } from '@djangocfg/ui';") */
+  importPath: string;
+  /** Code example as string */
+  example: string;
+  /** Live preview component */
+  preview: ReactNode;
+  /** Optional tags for filtering */
+  tags?: string[];
+  /** Optional dependencies */
+  dependencies?: string[];
+}
+
+/**
+ * Component Category
+ * Defines a category in the sidebar navigation
+ */
+export interface ComponentCategory {
+  /** Unique category ID */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Icon component */
+  icon: ReactNode;
+  /** Number of components in this category */
+  count?: number;
+  /** Category description */
+  description?: string;
+}

package/src/layouts/UILayout/types/index.ts

@@ -0,0 +1,23 @@
+/**
+ * UILayout Types
+ * Centralized type definitions
+ */
+
+// Component types
+export type {
+  ComponentConfig,
+  ComponentCategory,
+} from './component';
+
+// Layout types
+export type {
+  UILayoutProps,
+  LayoutConfig,
+  UILayoutConfig,
+} from './layout';
+
+// Navigation types
+export type {
+  NavigationState,
+  SidebarState,
+} from './navigation';

package/src/layouts/UILayout/types/layout.ts

@@ -0,0 +1,57 @@
+/**
+ * Layout Configuration Types
+ */
+
+import type { ReactNode } from 'react';
+import type { ComponentCategory } from './component';
+
+/**
+ * UILayout Props
+ * Main layout component props
+ */
+export interface UILayoutProps {
+  /** Content to render in the main area */
+  children: ReactNode;
+  /** Page title */
+  title?: string;
+  /** Page description */
+  description?: string;
+  /** Available categories */
+  categories: ComponentCategory[];
+  /** Current selected category */
+  currentCategory?: string;
+  /** Callback when category changes */
+  onCategoryChange?: (categoryId: string) => void;
+  /** Logo component */
+  logo?: ReactNode;
+  /** Project name */
+  projectName?: string;
+}
+
+/**
+ * Layout Configuration
+ * Defines layout dimensions and behavior
+ */
+export interface LayoutConfig {
+  /** Header height in pixels */
+  headerHeight?: number;
+  /** Container max width */
+  containerMaxWidth?: string;
+  /** Enable sticky header */
+  stickyHeader?: boolean;
+}
+
+/**
+ * UILayout Configuration
+ * Complete configuration for UILayout
+ */
+export interface UILayoutConfig {
+  /** Layout configuration */
+  layout?: LayoutConfig;
+  /** Default category to show */
+  defaultCategory?: string;
+  /** Enable search */
+  enableSearch?: boolean;
+  /** Enable breadcrumbs */
+  enableBreadcrumbs?: boolean;
+}