@djangocfg/layouts 1.0.6 → 1.1.0

package/src/layouts/UILayout/UIGuideLanding.tsx

@@ -0,0 +1,198 @@
+/**
+ * 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,
+} 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" },
+        ]}
+      />
+
+      {/* 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={[
+          {
+            number: "56+",
+            label: "UI Components",
+            description: "Production-ready",
+          },
+          {
+            number: "7",
+            label: "Landing Blocks",
+            description: "Pre-built sections",
+          },
+          {
+            number: "11",
+            label: "React Hooks",
+            description: "Custom utilities",
+          },
+          {
+            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"
+      />
+
+      {/* Simple Footer */}
+      <footer className="border-t py-8 sm:py-10 md:py-12 bg-background">
+        <div className="container max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex flex-col md:flex-row items-center justify-between gap-4">
+            <div className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Package className="w-4 h-4" />
+              <span>Built with Radix UI + Tailwind CSS</span>
+            </div>
+            <div className="flex items-center gap-6">
+              <button
+                onClick={handleBrowseComponents}
+                className="text-sm text-muted-foreground hover:text-foreground transition-colors"
+              >
+                Components
+              </button>
+              <button
+                onClick={handleViewBlocks}
+                className="text-sm text-muted-foreground hover:text-foreground transition-colors"
+              >
+                Blocks
+              </button>
+              <button
+                onClick={() => window.open(githubUrl, '_blank')}
+                className="text-sm text-muted-foreground hover:text-foreground transition-colors flex items-center gap-1"
+              >
+                <Github className="w-4 h-4" />
+                GitHub
+              </button>
+            </div>
+          </div>
+        </div>
+      </footer>
+    </div>
+  );
+}

package/src/layouts/UILayout/UIGuideView.tsx

@@ -0,0 +1,61 @@
+/**
+ * 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 only 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' && currentCategory !== 'overview' && (
+          <CategoryRenderer categoryId={currentCategory} />
+        )}
+      </div>
+    </UILayout>
+  );
+}
+
+export default function UIGuideView() {
+  return (
+    <ShowcaseProvider defaultCategory="overview">
+      <UIGuideContent />
+    </ShowcaseProvider>
+  );
+}

package/src/layouts/UILayout/UILayout.tsx

@@ -0,0 +1,122 @@
+/**
+ * UILayout
+ * Modern, config-driven layout for UI component documentation
+ */
+
+'use client';
+
+import React, { ReactNode } from 'react';
+import { useCopy, Sticky } from '@djangocfg/ui';
+import { Sidebar } from './components/Sidebar';
+import { Header } from './components/Header';
+import { MobileOverlay } from './components/MobileOverlay';
+import { generateAIContext } from './config';
+import { useShowcase } from './context';
+import type { ComponentCategory } from './config';
+
+export interface UILayoutProps {
+  children: ReactNode;
+  title?: string;
+  description?: string;
+  categories: ComponentCategory[];
+  currentCategory?: string;
+  onCategoryChange?: (categoryId: string) => void;
+  logo?: ReactNode;
+  projectName?: string;
+}
+
+/**
+ * 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: Mobile-first design with sidebar
+ * - 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 { isSidebarOpen, toggleSidebar, closeSidebar } = useShowcase();
+  const { copyToClipboard } = useCopy();
+
+  const handleCategoryChange = (categoryId: string) => {
+    onCategoryChange?.(categoryId);
+    closeSidebar();
+  };
+
+  const handleCopyForAI = () => {
+    const aiContext = generateAIContext();
+    copyToClipboard(aiContext);
+  };
+
+  return (
+    <div className="flex bg-background">
+      {/* Mobile Overlay - outside flex container for proper z-index stacking */}
+      <MobileOverlay
+        isOpen={isSidebarOpen}
+        onClose={closeSidebar}
+      />
+
+      {/* Sidebar with Sticky - parent must be scrollable for react-sticky-box */}
+      <div className="h-full sticky top-0">
+        <Sidebar
+          categories={categories}
+          currentCategory={currentCategory}
+          onCategoryChange={handleCategoryChange}
+          isOpen={isSidebarOpen}
+          projectName={projectName}
+          logo={logo}
+        />
+      </div>
+
+      {/* Main Content */}
+      <main className="flex-1 flex flex-col min-w-0">
+        {/* Header with Copy for AI button */}
+        <Header
+          title={title}
+          projectName={projectName}
+          logo={logo}
+          isSidebarOpen={isSidebarOpen}
+          onToggleSidebar={toggleSidebar}
+          onCopyForAI={handleCopyForAI}
+        />
+
+        {/* Content Area */}
+        <div 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>
+        </div>
+      </main>
+    </div>
+  );
+}
+
+// Legacy export for backward compatibility
+export { UILayout as ComponentShowcaseLayout };
+export type { UILayoutProps as ComponentShowcaseLayoutProps };

package/src/layouts/UILayout/components/AutoComponentDemo.tsx

@@ -0,0 +1,77 @@
+/**
+ * AutoComponentDemo
+ * Automatically renders component demos from configuration
+ */
+
+'use client';
+
+import React from 'react';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, Tabs, TabsContent, TabsList, TabsTrigger } from '@djangocfg/ui';
+import { PrettyCode } from '@djangocfg/ui/tools';
+import type { ComponentConfig } from '../config';
+
+interface AutoComponentDemoProps {
+  component: ComponentConfig;
+}
+
+/**
+ * AutoComponentDemo - Renders a component demo from config
+ * This is the single component used to display all UI components
+ */
+export function AutoComponentDemo({ component }: AutoComponentDemoProps) {
+  return (
+    <Card className="mb-6">
+      <CardHeader>
+        <CardTitle className="text-lg">{component.name}</CardTitle>
+        <CardDescription>{component.description}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Tabs defaultValue="preview" className="w-full">
+          <TabsList className="mb-4">
+            <TabsTrigger value="preview">Preview</TabsTrigger>
+            <TabsTrigger value="code">Code</TabsTrigger>
+          </TabsList>
+
+          <TabsContent value="preview" className="space-y-4">
+            <div className="p-6 border rounded-md bg-card">
+              {component.preview}
+            </div>
+          </TabsContent>
+
+          <TabsContent value="code">
+            <PrettyCode
+              data={`${component.importPath}\n\n${component.example}`}
+              language="tsx"
+              className="text-sm"
+            />
+          </TabsContent>
+        </Tabs>
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * CategorySection - Groups related component demos
+ */
+interface CategorySectionProps {
+  title: string;
+  description?: string;
+  children: React.ReactNode;
+}
+
+export function CategorySection({ title, description, children }: CategorySectionProps) {
+  return (
+    <div className="mb-12">
+      <div className="mb-6">
+        <h2 className="text-2xl font-bold tracking-tight">{title}</h2>
+        {description && (
+          <p className="text-muted-foreground mt-2">{description}</p>
+        )}
+      </div>
+      <div className="space-y-6">
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/layouts/UILayout/components/CategoryRenderer.tsx

@@ -0,0 +1,45 @@
+/**
+ * CategoryRenderer
+ * Universal renderer for any category using config data
+ */
+
+'use client';
+
+import React from 'react';
+import { getComponentsByCategory, getCategoryById } from '../config';
+import { AutoComponentDemo, CategorySection } from './AutoComponentDemo';
+
+interface CategoryRendererProps {
+  categoryId: string;
+}
+
+/**
+ * CategoryRenderer - Dynamically renders all components in a category
+ * No need for separate demo files - everything comes from config
+ */
+export function CategoryRenderer({ categoryId }: CategoryRendererProps) {
+  const category = getCategoryById(categoryId);
+  const components = getComponentsByCategory(categoryId);
+
+  if (!category || components.length === 0) {
+    return (
+      <div className="p-8 text-center text-muted-foreground">
+        <p>No components found for this category</p>
+      </div>
+    );
+  }
+
+  return (
+    <CategorySection
+      title={category.label}
+      description={category.description}
+    >
+      {components.map((component) => (
+        <AutoComponentDemo
+          key={component.name}
+          component={component}
+        />
+      ))}
+    </CategorySection>
+  );
+}

package/src/layouts/UILayout/components/Header.tsx

@@ -0,0 +1,114 @@
+/**
+ * Header Component
+ * Top header for mobile and page title with Copy for AI button
+ */
+
+'use client';
+
+import React, { useState } from 'react';
+import { Button, useIsMobile, useCopy } from '@djangocfg/ui';
+import { Menu, X, Sparkles, Check } from 'lucide-react';
+
+interface HeaderProps {
+  title?: string;
+  projectName?: string;
+  logo?: React.ReactNode;
+  isSidebarOpen?: boolean;
+  onToggleSidebar?: () => void;
+  onCopyForAI?: () => void;
+}
+
+export function Header({
+  title = 'UI Component Library',
+  projectName = 'Django CFG',
+  logo,
+  isSidebarOpen = false,
+  onToggleSidebar,
+  onCopyForAI,
+}: HeaderProps) {
+  const isMobile = useIsMobile();
+  const { copyToClipboard } = useCopy();
+  const [copied, setCopied] = useState(false);
+
+  const handleCopyForAI = async () => {
+    if (onCopyForAI) {
+      onCopyForAI();
+    }
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <>
+      {/* Mobile Header - only on mobile */}
+      {isMobile && (
+        <header className="w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+          <div className="flex h-14 items-center px-4 gap-4">
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={onToggleSidebar}
+            >
+              {isSidebarOpen ? <X className="h-5 w-5" /> : <Menu className="h-5 w-5" />}
+            </Button>
+
+            <div className="flex items-center gap-2 flex-1">
+              {logo}
+              <span className="font-semibold text-sm">{projectName}</span>
+            </div>
+
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={handleCopyForAI}
+              className="gap-2"
+            >
+              {copied ? (
+                <>
+                  <Check className="h-4 w-4" />
+                  <span className="hidden xs:inline">Copied!</span>
+                </>
+              ) : (
+                <>
+                  <Sparkles className="h-4 w-4" />
+                  <span className="hidden xs:inline">Copy for AI</span>
+                </>
+              )}
+            </Button>
+          </div>
+        </header>
+      )}
+
+      {/* Desktop Page Header - only on desktop */}
+      {!isMobile && (
+        <div className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+          <div className="flex h-14 items-center gap-4 px-6">
+            <div className="flex-1">
+              <h1 className="text-lg font-semibold">{title}</h1>
+            </div>
+
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={handleCopyForAI}
+              className="gap-2"
+            >
+              {copied ? (
+                <>
+                  <Check className="h-4 w-4" />
+                  Copied!
+                </>
+              ) : (
+                <>
+                  <Sparkles className="h-4 w-4" />
+                  Copy for AI
+                </>
+              )}
+            </Button>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/src/layouts/UILayout/components/MobileOverlay.tsx

@@ -0,0 +1,33 @@
+/**
+ * Mobile Overlay Component
+ * Backdrop overlay for mobile sidebar
+ */
+
+'use client';
+
+import React from 'react';
+import { cn } from '@djangocfg/ui/lib';
+import { useIsMobile } from '@djangocfg/ui';
+
+interface MobileOverlayProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function MobileOverlay({ isOpen, onClose }: MobileOverlayProps) {
+  const isMobile = useIsMobile();
+
+  // Only show on mobile when sidebar is open
+  if (!isMobile || !isOpen) return null;
+
+  return (
+    <div
+      className={cn(
+        "fixed inset-0 z-[150] bg-background/80 backdrop-blur-sm",
+        "animate-in fade-in duration-300"
+      )}
+      onClick={onClose}
+      aria-hidden="true"
+    />
+  );
+}