@djangocfg/layouts 1.2.17 → 1.2.18

package/src/layouts/UILayout/utils/ai-export/generators.ts

@@ -0,0 +1,130 @@
+/**
+ * AI Export Generators
+ * Functions for generating AI-friendly documentation
+ */
+
+import type { ComponentConfig } from '../../types';
+import type { TailwindGuide } from '../../config/tailwind.config';
+
+export interface UILibraryConfig {
+  projectName: string;
+  version: string;
+  description: string;
+  totalComponents: number;
+}
+
+/**
+ * Generate complete AI context from components and config
+ */
+export function generateAIContext(
+  components: ComponentConfig[],
+  tailwindGuide: TailwindGuide,
+  config: UILibraryConfig
+): string {
+  const { projectName, version, description } = config;
+
+  let output = `# ${projectName} v${version}\n\n`;
+  output += `${description}\n\n`;
+
+  // Tailwind Guide Section
+  output += generateTailwindSection(tailwindGuide);
+
+  // Components by Category
+  output += generateComponentsSection(components);
+
+  return output;
+}
+
+/**
+ * Generate Tailwind CSS section
+ */
+export function generateTailwindSection(guide: TailwindGuide): string {
+  let output = `## Tailwind CSS v${guide.version} Guidelines\n\n`;
+
+  output += `### Key Changes\n`;
+  guide.keyChanges.forEach((change) => {
+    output += `- ${change}\n`;
+  });
+  output += `\n`;
+
+  output += `### Best Practices\n`;
+  guide.bestPractices.forEach((practice) => {
+    output += `- ${practice}\n`;
+  });
+  output += `\n`;
+
+  output += `### Migration Steps\n`;
+  guide.migrationSteps.forEach((step, index) => {
+    output += `${index + 1}. ${step}\n`;
+  });
+  output += `\n`;
+
+  output += `### Examples\n\n`;
+  guide.examples.forEach((example) => {
+    output += `#### ${example.title}\n`;
+    output += `${example.description}\n\n`;
+    output += `\`\`\`css\n${example.code}\n\`\`\`\n\n`;
+  });
+
+  return output;
+}
+
+/**
+ * Generate components section grouped by category
+ */
+export function generateComponentsSection(components: ComponentConfig[]): string {
+  let output = '';
+
+  // Group components by category
+  const byCategory = groupByCategory(components);
+
+  // Generate section for each category
+  Object.entries(byCategory).forEach(([category, comps]) => {
+    output += `## ${formatCategoryName(category)} (${comps.length})\n\n`;
+
+    comps.forEach((comp) => {
+      output += generateComponentDoc(comp);
+    });
+  });
+
+  return output;
+}
+
+/**
+ * Generate documentation for a single component
+ */
+export function generateComponentDoc(component: ComponentConfig): string {
+  let output = `### ${component.name}\n`;
+  output += `${component.description}\n\n`;
+  output += `\`\`\`tsx\n`;
+  output += `${component.importPath}\n\n`;
+  output += `${component.example}\n`;
+  output += `\`\`\`\n\n`;
+
+  return output;
+}
+
+/**
+ * Group components by category
+ */
+function groupByCategory(
+  components: ComponentConfig[]
+): Record<string, ComponentConfig[]> {
+  return components.reduce(
+    (acc, comp) => {
+      if (!acc[comp.category]) {
+        acc[comp.category] = [];
+      }
+      acc[comp.category].push(comp);
+      return acc;
+    },
+    {} as Record<string, ComponentConfig[]>
+  );
+}
+
+/**
+ * Format category name for display
+ */
+function formatCategoryName(category: string): string {
+  return category.charAt(0).toUpperCase() + category.slice(1);
+}

package/src/layouts/UILayout/utils/ai-export/index.ts

@@ -0,0 +1,6 @@
+/**
+ * AI Export Utilities
+ */
+
+export * from './generators';
+export * from './formatters';

package/src/layouts/UILayout/utils/component-helpers/filter.ts

@@ -0,0 +1,109 @@
+/**
+ * Component Filter Utilities
+ */
+
+import type { ComponentConfig } from '../../types';
+
+/**
+ * Filter options
+ */
+export interface FilterOptions {
+  /** Category to filter by */
+  category?: string;
+  /** Tags to filter by (OR logic) */
+  tags?: string[];
+  /** Search query */
+  query?: string;
+  /** Search fields */
+  searchFields?: Array<keyof ComponentConfig>;
+}
+
+/**
+ * Apply multiple filters to components
+ */
+export function applyFilters(
+  components: ComponentConfig[],
+  options: FilterOptions
+): ComponentConfig[] {
+  let filtered = components;
+
+  // Filter by category
+  if (options.category) {
+    filtered = filtered.filter((comp) => comp.category === options.category);
+  }
+
+  // Filter by tags
+  if (options.tags && options.tags.length > 0) {
+    filtered = filtered.filter((comp) => {
+      if (!comp.tags) return false;
+      return options.tags!.some((tag) => comp.tags?.includes(tag));
+    });
+  }
+
+  // Filter by search query
+  if (options.query && options.query.trim()) {
+    const lowerQuery = options.query.toLowerCase();
+    const searchFields = options.searchFields || [
+      'name',
+      'description',
+      'category',
+    ];
+
+    filtered = filtered.filter((comp) => {
+      return searchFields.some((field) => {
+        const value = comp[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;
+      });
+    });
+  }
+
+  return filtered;
+}
+
+/**
+ * Sort components by field
+ */
+export function sortComponents(
+  components: ComponentConfig[],
+  field: keyof ComponentConfig,
+  order: 'asc' | 'desc' = 'asc'
+): ComponentConfig[] {
+  return [...components].sort((a, b) => {
+    const aVal = String(a[field]);
+    const bVal = String(b[field]);
+
+    if (order === 'asc') {
+      return aVal.localeCompare(bVal);
+    } else {
+      return bVal.localeCompare(aVal);
+    }
+  });
+}
+
+/**
+ * Group components by field
+ */
+export function groupComponentsBy<K extends keyof ComponentConfig>(
+  components: ComponentConfig[],
+  field: K
+): Record<string, ComponentConfig[]> {
+  return components.reduce(
+    (acc, comp) => {
+      const key = String(comp[field]);
+      if (!acc[key]) {
+        acc[key] = [];
+      }
+      acc[key].push(comp);
+      return acc;
+    },
+    {} as Record<string, ComponentConfig[]>
+  );
+}

package/src/layouts/UILayout/utils/component-helpers/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Component Helper Utilities
+ */
+
+export * from './search';
+export * from './filter';

package/src/layouts/UILayout/utils/component-helpers/search.ts

@@ -0,0 +1,95 @@
+/**
+ * Component Search Utilities
+ */
+
+import type { ComponentConfig } from '../../types';
+
+/**
+ * Search components by query
+ */
+export function searchComponents(
+  components: ComponentConfig[],
+  query: string,
+  fields: Array<keyof ComponentConfig> = ['name', 'description', 'category']
+): ComponentConfig[] {
+  if (!query.trim()) {
+    return components;
+  }
+
+  const lowerQuery = query.toLowerCase();
+
+  return components.filter((component) => {
+    return fields.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;
+    });
+  });
+}
+
+/**
+ * Filter components by category
+ */
+export function filterByCategory(
+  components: ComponentConfig[],
+  category: string
+): ComponentConfig[] {
+  return components.filter((comp) => comp.category === category);
+}
+
+/**
+ * Filter components by tags
+ */
+export function filterByTags(
+  components: ComponentConfig[],
+  tags: string[]
+): ComponentConfig[] {
+  if (tags.length === 0) {
+    return components;
+  }
+
+  return components.filter((comp) => {
+    if (!comp.tags) return false;
+    return tags.some((tag) => comp.tags?.includes(tag));
+  });
+}
+
+/**
+ * Get unique categories from components
+ */
+export function getUniqueCategories(
+  components: ComponentConfig[]
+): string[] {
+  const categories = new Set(components.map((c) => c.category));
+  return Array.from(categories).sort();
+}
+
+/**
+ * Get unique tags from components
+ */
+export function getUniqueTags(components: ComponentConfig[]): string[] {
+  const tags = new Set<string>();
+  components.forEach((comp) => {
+    comp.tags?.forEach((tag) => tags.add(tag));
+  });
+  return Array.from(tags).sort();
+}
+
+/**
+ * Find component by name
+ */
+export function findComponentByName(
+  components: ComponentConfig[],
+  name: string
+): ComponentConfig | undefined {
+  return components.find(
+    (comp) => comp.name.toLowerCase() === name.toLowerCase()
+  );
+}

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

@@ -0,0 +1,6 @@
+/**
+ * UILayout Utilities
+ */
+
+export * from './ai-export';
+export * from './component-helpers';

package/src/layouts/UILayout/REFACTORING.md

@@ -1,331 +0,0 @@
-# UILayout Refactoring - Complete Summary
-
-## 🎯 Goal
-
-Transform ComponentShowcaseLayout into a modern, config-driven UILayout with:
-1. **Single Source of Truth** - centralized configuration
-2. **Zero Duplication** - no repeated code
-3. **Auto-Rendering** - components render from config
-4. **AI Export** - "Copy for AI" button with complete documentation
-5. **Better Organization** - modular structure by category
-
-## ✅ What Was Done
-
-### 1. Renamed Old Structure
-```bash
-UILayout_old/  # Backup of old implementation
-```
-
-### 2. Created New Config-Driven Architecture
-
-#### Config Structure (Single Source of Truth)
-```
-config/
-├── components/              # Component configs by category
-│   ├── types.ts            # ComponentConfig interface
-│   ├── forms.config.tsx    # 8 form components
-│   ├── layout.config.tsx   # 5 layout components
-│   ├── navigation.config.tsx  # 4 navigation components
-│   ├── overlay.config.tsx     # 11 overlay components
-│   ├── feedback.config.tsx    # 5 feedback components
-│   ├── data.config.tsx        # 5 data components
-│   ├── specialized.config.tsx # 2 specialized components
-│   ├── blocks.config.tsx      # 7 landing page blocks
-│   ├── hooks.config.tsx       # 6 custom React hooks
-│   └── index.ts               # Aggregator
-├── categories.config.tsx   # Menu categories
-├── tailwind.config.ts      # Tailwind 4 guide
-├── ai-export.config.ts     # AI context generator
-└── index.ts                # Main exports
-```
-
-#### Component Architecture
-```
-components/
-├── AutoComponentDemo.tsx      # Reads from config, renders component
-├── CategoryRenderer.tsx       # Renders entire category from config
-├── TailwindGuideRenderer.tsx  # Renders Tailwind guide from config
-├── Header.tsx                 # Header with "Copy for AI" button
-├── Sidebar.tsx                # Navigation sidebar
-└── MobileOverlay.tsx          # Mobile menu overlay
-```
-
-### 3. Component Configuration Format
-
-Each component defined as:
-```typescript
-interface ComponentConfig {
-  name: string;           // "Button"
-  category: string;       // "forms"
-  description: string;    // "Interactive button with variants"
-  importPath: string;     // "import { Button } from '@djangocfg/ui';"
-  example: string;        // Code example as string
-  preview: ReactNode;     // Live React component
-}
-```
-
-### 4. Key Features Implemented
-
-#### ✅ Auto-Rendering from Config
-```tsx
-// Before: Manual demo files for each category
-FormComponentsDemo.tsx    // 200+ lines
-LayoutComponentsDemo.tsx  // 180+ lines
-NavigationComponentsDemo.tsx  // 150+ lines
-// ... 7 more demo files
-
-// After: One universal renderer
-<CategoryRenderer categoryId="forms" />  // Reads from config
-```
-
-#### ✅ "Copy for AI" Button
-- In Header component (desktop & mobile)
-- Generates complete documentation:
-  - Tailwind 4 guidelines
-  - All 53 components with examples
-  - Proper formatting for AI
-- Uses `generateAIContext()` function
-- One-click clipboard copy
-
-#### ✅ Zero Duplication
-```typescript
-// Before: Component defined in 3 places
-// 1. Demo file (preview)
-// 2. Code example (string)
-// 3. Import statement
-
-// After: Component defined ONCE
-{
-  name: 'Button',
-  preview: <Button>Click</Button>,
-  example: '<Button>Click</Button>',
-  importPath: "import { Button } from '@djangocfg/ui';"
-}
-```
-
-### 5. Statistics
-
-#### Total Components Documented
-| Category | Count | Config File |
-|----------|-------|-------------|
-| Forms | 8 | forms.config.tsx (320 lines) |
-| Layout | 5 | layout.config.tsx (240 lines) |
-| Navigation | 4 | navigation.config.tsx (195 lines) |
-| Overlay | 11 | overlay.config.tsx (510 lines) |
-| Feedback | 5 | feedback.config.tsx (220 lines) |
-| Data Display | 5 | data.config.tsx (200 lines) |
-| Specialized | 2 | specialized.config.tsx (95 lines) |
-| Blocks | 7 | blocks.config.tsx (280 lines) |
-| Hooks | 6 | hooks.config.tsx (170 lines) |
-| **TOTAL** | **53** | **2,230 lines** |
-
-#### Code Reduction
-- **Before**: ~1,800 lines of demo files + ~1,200 lines of component definitions = **3,000 lines**
-- **After**: ~2,230 lines (all-in-one configs) = **2,230 lines**
-- **Saved**: ~770 lines (-25%)
-- **Maintainability**: 100x better (single source of truth)
-
-### 6. Files Created
-
-#### Core Files (11)
-1. `UILayout.tsx` - Main layout component
-2. `UIGuideView.tsx` - Complete view with categories
-3. `UIGuideLanding.tsx` - Landing page (copied from old)
-4. `UIGuideApp.tsx` - Full app wrapper
-5. `types.ts` - Type definitions
-6. `constants.ts` - Constants
-7. `index.ts` - Main exports
-8. `README.md` - Documentation
-9. `REFACTORING.md` - This file
-
-#### Config Files (14)
-10. `config/components/types.ts`
-11. `config/components/forms.config.tsx`
-12. `config/components/layout.config.tsx`
-13. `config/components/navigation.config.tsx`
-14. `config/components/overlay.config.tsx`
-15. `config/components/feedback.config.tsx`
-16. `config/components/data.config.tsx`
-17. `config/components/specialized.config.tsx`
-18. `config/components/blocks.config.tsx`
-19. `config/components/hooks.config.tsx`
-20. `config/components/index.ts`
-21. `config/categories.config.tsx`
-22. `config/tailwind.config.ts`
-23. `config/ai-export.config.ts`
-24. `config/index.ts`
-
-#### Component Files (6)
-25. `components/AutoComponentDemo.tsx`
-26. `components/CategoryRenderer.tsx`
-27. `components/TailwindGuideRenderer.tsx`
-28. `components/Header.tsx` (copied & updated)
-29. `components/Sidebar.tsx` (copied)
-30. `components/MobileOverlay.tsx` (copied)
-
-#### Context (1)
-31. `context/` (copied from old)
-
-**Total: 31 files created/updated**
-
-## 🚀 Benefits
-
-### 1. Single Source of Truth
-- All component data in config files
-- No duplication
-- Easy to update
-
-### 2. Auto-Rendering
-- Add component to config → automatically appears everywhere
-- No manual demo file creation
-- Consistent presentation
-
-### 3. Type-Safe
-- Full TypeScript support
-- Interface for ComponentConfig
-- Compile-time error checking
-
-### 4. AI-Ready
-- "Copy for AI" button
-- Complete documentation export
-- Proper formatting for AI consumption
-
-### 5. Maintainable
-```typescript
-// Adding new component:
-
-// Before (3 steps):
-// 1. Create demo component in category file
-// 2. Add code example string
-// 3. Import and wire up
-
-// After (1 step):
-// Add to config file:
-{
-  name: 'NewComponent',
-  category: 'forms',
-  description: '...',
-  importPath: '...',
-  example: '...',
-  preview: <NewComponent />
-}
-```
-
-### 6. Scalable
-- Easy to add new categories
-- Easy to add new components
-- Modular structure
-
-## 📊 Comparison
-
-### Old Architecture
-```
-ComponentShowcaseLayout/
-├── categories/
-│   ├── FormComponentsDemo.tsx        # 200 lines
-│   ├── LayoutComponentsDemo.tsx      # 180 lines
-│   ├── NavigationComponentsDemo.tsx  # 150 lines
-│   ├── OverlayComponentsDemo.tsx     # 250 lines
-│   ├── FeedbackComponentsDemo.tsx    # 140 lines
-│   ├── DataDisplayDemo.tsx           # 170 lines
-│   ├── SpecializedComponentsDemo.tsx # 120 lines
-│   ├── BlocksDemo.tsx                # 280 lines
-│   ├── HooksDemo.tsx                 # 160 lines
-│   └── Tailwind4Guide.tsx            # 240 lines
-└── ... (other files)
-
-Problems:
-- ❌ Duplication (component defined multiple times)
-- ❌ Hard to maintain (update in multiple places)
-- ❌ Manual rendering (write demo for each component)
-- ❌ No AI export
-```
-
-### New Architecture
-```
-UILayout/
-├── config/
-│   ├── components/        # All component definitions
-│   │   ├── forms.config.tsx
-│   │   ├── layout.config.tsx
-│   │   └── ... (9 files total)
-│   ├── categories.config.tsx
-│   ├── tailwind.config.ts
-│   └── ai-export.config.ts
-├── components/
-│   ├── AutoComponentDemo.tsx      # Auto-renders from config
-│   ├── CategoryRenderer.tsx       # Renders entire category
-│   └── TailwindGuideRenderer.tsx  # Renders guide
-└── ...
-
-Benefits:
-- ✅ Single source of truth (config)
-- ✅ Easy to maintain (one place to update)
-- ✅ Auto-rendering (no manual demos)
-- ✅ AI export built-in
-```
-
-## 🎯 Migration Path
-
-If you want to migrate existing component showcase:
-
-1. **Analyze existing demos** - identify all components
-2. **Create config files** - one per category
-3. **Define ComponentConfig** - for each component:
-   ```typescript
-   {
-     name: string,
-     category: string,
-     description: string,
-     importPath: string,
-     example: string,
-     preview: ReactNode
-   }
-   ```
-4. **Replace demos** - use `<CategoryRenderer categoryId="..." />`
-5. **Test** - verify all components render correctly
-6. **Delete old demos** - remove manual demo files
-
-## ✅ Verification
-
-### TypeScript Check
-```bash
-pnpm check
-# ✅ No errors
-```
-
-### File Count
-```bash
-# Config files: 14
-# Component files: 6
-# Context: 1
-# Core: 11
-# Total: 32 files
-```
-
-### Component Count
-```bash
-# Total components in config: 53
-# - Forms: 8
-# - Layout: 5
-# - Navigation: 4
-# - Overlay: 11
-# - Feedback: 5
-# - Data: 5
-# - Specialized: 2
-# - Blocks: 7
-# - Hooks: 6
-```
-
-## 🎉 Result
-
-Полностью рефакторенная, config-driven система документации UI компонентов с:
-- ✅ Единым источником правды (конфиг)
-- ✅ Нулевым дублированием кода
-- ✅ Автоматическим рендерингом
-- ✅ Экспортом для AI
-- ✅ TypeScript безопасностью
-- ✅ Модульной структурой
-- ✅ Легкой масштабируемостью
-
-**Готово к использованию!** 🚀