@djangocfg/layouts 1.4.27 → 1.4.28

package/src/layouts/UILayout/config/tailwind.config.ts

@@ -1,131 +0,0 @@
-/**
- * Tailwind CSS v4 Configuration & Guidelines
- * Documentation for Tailwind CSS v4 best practices
- */
-
-export interface TailwindGuide {
-  version: string;
-  keyChanges: string[];
-  bestPractices: string[];
-  migrationSteps: string[];
-  examples: {
-    title: string;
-    description: string;
-    code: string;
-  }[];
-}
-
-export const TAILWIND_GUIDE: TailwindGuide = {
-  version: "4.0",
-
-  keyChanges: [
-    "CSS-First Configuration: Theme is now defined using CSS custom properties in an @theme block instead of JavaScript",
-    "New Import Syntax: Use @import \"tailwindcss\" instead of @tailwind directives",
-    "Simplified PostCSS Setup: Use @tailwindcss/postcss plugin",
-    "Performance Improvements: 10x faster build times, significantly smaller CSS bundles",
-    "Modern Browser Support: Optimized for Safari 16.4+, Chrome 111+, Firefox 128+"
-  ],
-
-  bestPractices: [
-    "Use standard Tailwind classes only: py-16 sm:py-20 md:py-24 lg:py-32",
-    "Responsive patterns: px-4 sm:px-6 lg:px-8",
-    "Container pattern: container max-w-7xl mx-auto",
-    "IMPORTANT: Arbitrary values like h-[80px], z-[100] may NOT work in v4 - define tokens in @theme instead",
-    "For fixed sizes: Use inline styles style={{ width: '80px', height: '80px' }} - always reliable",
-    "Spacing utilities (h-20, p-4, etc.) require --spacing-* variables defined in @theme block",
-    "Z-index utilities (z-50, z-100) require --z-* variables defined in @theme block",
-    "OPACITY MODIFIERS: bg-background/80 does NOT work with HSL colors in v4! Use inline styles: style={{ backgroundColor: 'hsl(var(--background) / 0.8)' }}",
-    "Border opacity: border-border/30 does NOT work - use style={{ borderColor: 'hsl(var(--border) / 0.3)' }}",
-    "Import order is critical: theme variables MUST come before @import 'tailwindcss'",
-    "Use aspect-square for maintaining 1:1 ratio (circles, squares)",
-    "Use overflow-hidden with rounded-full for perfect circles",
-    "Avoid custom utilities like: section-padding, animate-*, shadow-brand",
-    "Mobile-first approach with breakpoints: sm: (640px), md: (768px), lg: (1024px), xl: (1280px)",
-    "Use CSS variables: var(--color-primary), var(--font-family-sans)"
-  ],
-
-  migrationSteps: [
-    "Update dependencies: npm install tailwindcss@latest postcss@latest",
-    "Replace JavaScript config with CSS @theme block",
-    "Update import directives: @import \"tailwindcss\"",
-    "Configure PostCSS: use @tailwindcss/postcss plugin",
-    "Test and refactor: remove custom utilities and use standard Tailwind classes"
-  ],
-
-  examples: [
-    {
-      title: "CSS-First Configuration",
-      description: "Define theme using CSS custom properties",
-      code: `@import "tailwindcss";
-
-@theme {
-  --color-primary: #3b82f6;
-  --color-secondary: #8b5cf6;
-  --font-family-sans: ui-sans-serif, system-ui, sans-serif;
-  --spacing-20: 5rem; /* Required for h-20, w-20 to work */
-}`
-    },
-    {
-      title: "Responsive Spacing",
-      description: "Mobile-first responsive padding and spacing",
-      code: `<section className="py-16 sm:py-20 md:py-24 lg:py-32">
-  <div className="container max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
-    <h1 className="text-4xl sm:text-5xl md:text-6xl lg:text-7xl">
-      Title
-    </h1>
-  </div>
-</section>`
-    },
-    {
-      title: "Fixed Sizes with Inline Styles",
-      description: "Most reliable way to set exact dimensions in v4",
-      code: `<Avatar
-  className="aspect-square rounded-full overflow-hidden ring-1 ring-foreground/20"
-  style={{ width: '80px', height: '80px' }}
->
-  <AvatarImage src={avatar} alt="User" />
-</Avatar>`
-    },
-    {
-      title: "Component Styling",
-      description: "Standard Tailwind classes for components",
-      code: `<button className="px-6 py-3 bg-primary text-primary-foreground rounded-md shadow-lg hover:shadow-xl transition-all duration-300">
-  Click me
-</button>`
-    },
-    {
-      title: "Z-Index Theme Tokens",
-      description: "Define z-index values in @theme for z-50, z-100 to work",
-      code: `@theme {
-  --z-0: 0;
-  --z-10: 10;
-  --z-20: 20;
-  --z-30: 30;
-  --z-40: 40;
-  --z-50: 50;
-  --z-100: 100;
-  --z-auto: auto;
-}
-
-/* Now z-50, z-100 classes work */
-<nav className="sticky top-0 z-100">...</nav>`
-    },
-    {
-      title: "Opacity with HSL Colors (BROKEN in v4)",
-      description: "bg-background/80 does NOT work with HSL - use inline styles",
-      code: `/* ❌ BROKEN - does not work in Tailwind v4 */
-<nav className="bg-background/80 border-border/30">
-
-/* ✅ WORKING - use inline styles for opacity */
-<nav
-  className="sticky top-0 z-100 backdrop-blur-xl"
-  style={{
-    backgroundColor: 'hsl(var(--background) / 0.8)',
-    borderColor: 'hsl(var(--border) / 0.3)'
-  }}
->
-  ...
-</nav>`
-    }
-  ]
-};

package/src/layouts/UILayout/constants.ts

@@ -1,23 +0,0 @@
-/**
- * Constants for UILayout
- */
-
-export const MOBILE_BREAKPOINT = 768; // px
-export const SIDEBAR_WIDTH = 256; // px (w-64)
-export const HEADER_HEIGHT = 56; // px (h-14)
-
-export const ANIMATION_DURATION = {
-  fast: 150,
-  normal: 300,
-  slow: 500,
-} as const;
-
-export const Z_INDEX = {
-  sidebar: 30,
-  overlay: 20,
-  header: 40,
-  dropdown: 50,
-} as const;
-
-export const DEFAULT_PROJECT_NAME = 'Django CFG UI';
-export const DEFAULT_DESCRIPTION = 'Explore our comprehensive collection of 56+ React components built with Radix UI and Tailwind CSS';

package/src/layouts/UILayout/context/ShowcaseContext.tsx

@@ -1,81 +0,0 @@
-/**
- * Showcase Context
- * Manages navigation state for UILayout with URL hash sync
- */
-
-'use client';
-
-import React, { createContext, useContext, useState, useEffect, useCallback, ReactNode } from 'react';
-
-interface ShowcaseContextValue {
-  currentCategory: string;
-  setCurrentCategory: (category: string) => void;
-}
-
-const ShowcaseContext = createContext<ShowcaseContextValue | undefined>(undefined);
-
-interface ShowcaseProviderProps {
-  children: ReactNode;
-  defaultCategory?: string;
-}
-
-export function ShowcaseProvider({ children, defaultCategory = 'overview' }: ShowcaseProviderProps) {
-  // Initialize from URL hash or default
-  const [currentCategory, setCurrentCategoryState] = useState(() => {
-    if (typeof window !== 'undefined') {
-      const hash = window.location.hash.slice(1); // Remove #
-      return hash || defaultCategory;
-    }
-    return defaultCategory;
-  });
-
-  // Update URL hash when category changes
-  const setCurrentCategory = useCallback((category: string) => {
-    setCurrentCategoryState(category);
-    // Update URL hash without triggering navigation
-    if (typeof window !== 'undefined') {
-      const newUrl = category === defaultCategory
-        ? window.location.pathname
-        : `${window.location.pathname}#${category}`;
-      window.history.replaceState(null, '', newUrl);
-    }
-  }, [defaultCategory]);
-
-  // Listen for hash changes (back/forward browser buttons)
-  useEffect(() => {
-    const handleHashChange = () => {
-      const hash = window.location.hash.slice(1);
-      setCurrentCategoryState(hash || defaultCategory);
-    };
-
-    window.addEventListener('hashchange', handleHashChange);
-    return () => window.removeEventListener('hashchange', handleHashChange);
-  }, [defaultCategory]);
-
-  // Handle initial hash on mount (for SSR hydration)
-  useEffect(() => {
-    const hash = window.location.hash.slice(1);
-    if (hash && hash !== currentCategory) {
-      setCurrentCategoryState(hash);
-    }
-  }, []);
-
-  return (
-    <ShowcaseContext.Provider
-      value={{
-        currentCategory,
-        setCurrentCategory,
-      }}
-    >
-      {children}
-    </ShowcaseContext.Provider>
-  );
-}
-
-export function useShowcase() {
-  const context = useContext(ShowcaseContext);
-  if (!context) {
-    throw new Error('useShowcase must be used within ShowcaseProvider');
-  }
-  return context;
-}

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

@@ -1 +0,0 @@
-export { ShowcaseProvider, useShowcase } from './ShowcaseContext';

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

@@ -1,18 +0,0 @@
-/**
- * UI Guide App
- *
- * Complete UI Guide application with UILayout
- * Uses config-driven approach with context for navigation
- */
-
-'use client';
-
-import React from 'react';
-import UIGuideView from './UIGuideView';
-
-export function UIGuideApp() {
-  // UIGuideView now includes UIGuideLanding as 'overview' category
-  // and uses ShowcaseProvider context for navigation
-  // All component data comes from centralized config
-  return <UIGuideView />;
-}

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

@@ -1,33 +0,0 @@
-/**
- * UI Guide App - Dynamic Import Wrapper
- *
- * Lazy loads the heavy UILayout library (~1.5MB with Mermaid, PrettyCode, etc.)
- * Only loads when UI documentation page is accessed
- */
-
-'use client';
-
-import dynamic from 'next/dynamic';
-import React from 'react';
-
-// Dynamic import with loading state
-const UIGuideAppClient = dynamic(() => import('./UIGuideApp.client').then(mod => ({ default: mod.UIGuideApp })), {
-  ssr: false,
-  loading: () => (
-    <div className="min-h-screen bg-background flex items-center justify-center">
-      <div className="text-center space-y-4">
-        <div className="flex justify-center">
-          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary"></div>
-        </div>
-        <div className="space-y-2">
-          <h2 className="text-xl font-semibold text-foreground">Loading UI Guide</h2>
-          <p className="text-sm text-muted-foreground">Preparing component showcase...</p>
-        </div>
-      </div>
-    </div>
-  ),
-});
-
-export function UIGuideApp() {
-  return <UIGuideAppClient />;
-}

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

@@ -1,172 +0,0 @@
-/**
- * UI Guide Landing Page
- *
- * Beautiful landing page for Django CFG UI Library
- * Uses ready blocks from @djangocfg/ui/blocks
- */
-
-'use client';
-
-import React from 'react';
-import {
-  Package,
-  Sparkles,
-  Zap,
-  Shield,
-  Palette,
-  Code2,
-  Blocks,
-  Github,
-  BookOpen,
-  Layout,
-  CheckCircle2,
-} from 'lucide-react';
-import {
-  SuperHero,
-  FeatureSection,
-  StatsSection,
-  CTASection,
-} from '@djangocfg/ui/blocks';
-import { useShowcase } from '../context';
-
-interface UIGuideLandingProps {
-  githubUrl?: string;
-}
-
-export function UIGuideLanding({
-  githubUrl = 'https://github.com'
-}: UIGuideLandingProps) {
-  const { setCurrentCategory } = useShowcase();
-
-  const handleBrowseComponents = () => {
-    setCurrentCategory('forms');
-  };
-
-  const handleViewBlocks = () => {
-    setCurrentCategory('blocks');
-  };
-  return (
-    <div className="min-h-screen">
-      {/* Hero Section using SuperHero block */}
-      <SuperHero
-        badge={{
-          icon: <Sparkles className="w-4 h-4" />,
-          text: "56+ Components · 7 Blocks · 11 Hooks"
-        }}
-        title="Django CFG"
-        titleGradient="UI Library"
-        subtitle="Modern React component library built with Next.js 15, Radix UI, and Tailwind CSS 4"
-        features={[
-          { icon: <span>⚛️</span>, text: "React 19" },
-          { icon: <span>📘</span>, text: "TypeScript" },
-          { icon: <span>🎨</span>, text: "Tailwind CSS 4" },
-          { icon: <span>🌙</span>, text: "Dark Mode" },
-        ]}
-        primaryAction={{
-          label: "Explore Components",
-          onClick: handleBrowseComponents
-        }}
-        secondaryAction={{
-          label: "View Blocks",
-          onClick: handleViewBlocks,
-          icon: <BookOpen className="w-5 h-5" />
-        }}
-        stats={[
-          { number: "56+", label: "Components" },
-          { number: "7", label: "Blocks" },
-          { number: "11", label: "Hooks" },
-          { number: "100%", label: "Type Safe" },
-        ]}
-        showBackgroundSwitcher={true}
-      />
-
-      {/* Features Section using FeatureSection block */}
-      <FeatureSection
-        title="Everything You Need"
-        subtitle="A comprehensive component library with all the building blocks for modern web applications"
-        columns={3}
-        background="card"
-        features={[
-          {
-            icon: <Package className="w-6 h-6" />,
-            title: "56+ Components",
-            description: "From basic buttons to complex data tables, we've got you covered with production-ready components",
-          },
-          {
-            icon: <Blocks className="w-6 h-6" />,
-            title: "Landing Page Blocks",
-            description: "Pre-built sections like Hero, Features, CTA, Testimonials to ship landing pages faster",
-          },
-          {
-            icon: <Zap className="w-6 h-6" />,
-            title: "Lightning Fast",
-            description: "Optimized for performance with React 19 and Next.js 15 for blazing fast user experiences",
-          },
-          {
-            icon: <Shield className="w-6 h-6" />,
-            title: "Fully Accessible",
-            description: "Built on Radix UI primitives ensuring WCAG compliance and keyboard navigation support",
-          },
-          {
-            icon: <Palette className="w-6 h-6" />,
-            title: "Themeable",
-            description: "Dark mode built-in with CSS variables. Customize colors, spacing, and typography easily",
-          },
-          {
-            icon: <Code2 className="w-6 h-6" />,
-            title: "TypeScript First",
-            description: "Fully typed with TypeScript for better DX, autocomplete, and fewer runtime errors",
-          },
-        ]}
-      />
-
-      {/* Stats Section using StatsSection block */}
-      <StatsSection
-        title="Built for Scale"
-        subtitle="Everything you need to build modern web applications"
-        columns={4}
-        stats={[
-          {
-            icon: <Layout className="w-6 h-6" />,
-            number: "56+",
-            label: "UI Components",
-            description: "Production-ready",
-          },
-          {
-            icon: <Blocks className="w-6 h-6" />,
-            number: "7",
-            label: "Landing Blocks",
-            description: "Pre-built sections",
-          },
-          {
-            icon: <Code2 className="w-6 h-6" />,
-            number: "11",
-            label: "React Hooks",
-            description: "Custom utilities",
-          },
-          {
-            icon: <CheckCircle2 className="w-6 h-6" />,
-            number: "100%",
-            label: "Type Safe",
-            description: "Full TypeScript",
-          },
-        ]}
-      />
-
-      {/* CTA Section using CTASection block */}
-      <CTASection
-        title="Ready to Build Something Amazing?"
-        subtitle="Start exploring our component library and ship your next project faster with pre-built, accessible components"
-        primaryCTA={{
-          label: "Browse Components",
-          onClick: handleBrowseComponents
-        }}
-        secondaryCTA={{
-          label: "View Blocks",
-          onClick: handleViewBlocks
-        }}
-        background="gradient"
-      />
-    </div>
-  );
-}

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

@@ -1,61 +0,0 @@
-/**
- * UI Guide View
- * Main view for showcasing all UI components from @djangocfg/ui package
- * Uses config-driven approach - all data comes from centralized config
- */
-
-'use client';
-
-import React from 'react';
-import { UILayout } from './UILayout';
-import { CATEGORIES } from '../config';
-import { ShowcaseProvider, useShowcase } from '../context';
-import { UIGuideLanding } from './UIGuideLanding';
-import { CategoryRenderer } from '../components/CategoryRenderer';
-import { TailwindGuideRenderer } from '../components/TailwindGuideRenderer';
-
-function UIGuideContent() {
-  const { currentCategory, setCurrentCategory } = useShowcase();
-
-  // For overview, show landing page without layout
-  if (currentCategory === 'overview') {
-    return <UIGuideLanding />;
-  }
-
-  // Logo component
-  const logo = (
-    <div className="h-8 w-8 rounded-md bg-primary flex items-center justify-center text-primary-foreground font-bold text-sm">
-      DC
-    </div>
-  );
-
-  return (
-    <UILayout
-      title="UI Component Library"
-      description="Explore our comprehensive collection of 56+ React components built with Radix UI and Tailwind CSS"
-      categories={CATEGORIES}
-      currentCategory={currentCategory}
-      onCategoryChange={setCurrentCategory}
-      logo={logo}
-      projectName="Django CFG UI"
-    >
-      <div className="space-y-8">
-        {/* Tailwind 4 Guide */}
-        {currentCategory === 'tailwind4' && <TailwindGuideRenderer />}
-
-        {/* All other categories use CategoryRenderer */}
-        {currentCategory !== 'tailwind4' && (
-          <CategoryRenderer categoryId={currentCategory} />
-        )}
-      </div>
-    </UILayout>
-  );
-}
-
-export default function UIGuideView() {
-  return (
-    <ShowcaseProvider defaultCategory="overview">
-      <UIGuideContent />
-    </ShowcaseProvider>
-  );
-}

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

@@ -1,125 +0,0 @@
-/**
- * UILayout
- * Config-driven layout with left sidebar navigation
- *
- * Features:
- * - Desktop: Fixed left sidebar with category navigation
- * - Mobile: Collapsible sidebar via burger menu
- * - No header - designed to be used inside app layout with global navbar
- * - Type-safe: Full TypeScript support
- */
-
-'use client';
-
-import React, { useState, useRef } from 'react';
-import { Menu, X } from 'lucide-react';
-import { Button, Sticky } from '@djangocfg/ui';
-import { useIsMobile } from '@djangocfg/ui';
-import { Sidebar } from '../components/layout/Sidebar';
-import { generateAIContext } from '../config';
-import type { UILayoutProps } from '../types';
-
-
-/**
- * UILayout - Layout component with left sidebar navigation
- * Designed to be used inside app layout (no competing header)
- *
- * @example
- * ```tsx
- * <UILayout
- *   categories={CATEGORIES}
- *   currentCategory={category}
- *   onCategoryChange={setCategory}
- * >
- *   <CategoryRenderer categoryId={category} />
- * </UILayout>
- * ```
- */
-export function UILayout({
-  children,
-  description,
-  categories,
-  currentCategory,
-  onCategoryChange,
-}: UILayoutProps) {
-  const [isSidebarOpen, setIsSidebarOpen] = useState(false);
-  const isMobile = useIsMobile();
-  const mainRef = useRef<HTMLElement>(null);
-
-  const toggleSidebar = () => {
-    setIsSidebarOpen(!isSidebarOpen);
-  };
-
-  const handleCategoryChange = (categoryId: string) => {
-    onCategoryChange?.(categoryId);
-    // Scroll to top when category changes
-    // Try main element first, then window
-    if (mainRef.current) {
-      mainRef.current.scrollTo({ top: 0, behavior: 'smooth' });
-    }
-    window.scrollTo({ top: 0, behavior: 'smooth' });
-    // Auto-close sidebar on mobile after selection
-    if (isMobile) {
-      setIsSidebarOpen(false);
-    }
-  };
-
-  // Get current category name for mobile header
-  const currentCategoryName = categories.find(c => c.id === currentCategory)?.label || 'Components';
-
-  return (
-    <div className="flex flex-col flex-1 bg-background isolate" style={{ zIndex: 0 }}>
-      <div className="flex flex-1 relative">
-        {/* Main Content */}
-        <main ref={mainRef} className="flex-1 overflow-y-auto">
-          <div className="max-w-7xl mx-auto p-6">
-            {description && (
-              <p className="text-sm text-muted-foreground mb-6">
-                {description}
-              </p>
-            )}
-            {children}
-          </div>
-        </main>
-
-        {/* Sidebar - now on the right */}
-        <Sidebar
-          categories={categories}
-          currentCategory={currentCategory}
-          onCategoryChange={handleCategoryChange}
-          isOpen={isSidebarOpen}
-          onClose={() => setIsSidebarOpen(false)}
-          onCopyForAI={generateAIContext}
-        />
-
-      </div>
-
-      {/* Mobile Bottom Bar - sticky at bottom to avoid conflict with PublicLayout navbar */}
-      {isMobile && (
-        <Sticky
-          bottom
-          useNativeSticky
-          offsetBottom={0}
-          disableOnMobile={false}
-          zIndex={30}
-          className="flex items-center justify-between gap-3 px-4 py-3 border-t bg-background"
-        >
-          <span className="font-medium text-sm truncate">{currentCategoryName}</span>
-          <Button
-            variant="outline"
-            size="icon"
-            onClick={toggleSidebar}
-            aria-label={isSidebarOpen ? "Close menu" : "Open menu"}
-            className="shrink-0"
-          >
-            {isSidebarOpen ? (
-              <X className="h-5 w-5" />
-            ) : (
-              <Menu className="h-5 w-5" />
-            )}
-          </Button>
-        </Sticky>
-      )}
-    </div>
-  );
-}

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

@@ -1,11 +0,0 @@
-/**
- * UILayoutSidebar
- * @deprecated Use UILayout instead - it now has sidebar navigation by default
- */
-
-import { UILayout } from './UILayout';
-
-/**
- * @deprecated Use UILayout instead
- */
-export const UILayoutSidebar = UILayout;

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

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

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

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