@djangocfg/layouts 1.2.16 → 1.2.18

package/src/layouts/UILayout/components/layout/Sidebar/Sidebar.tsx

@@ -0,0 +1,94 @@
+/**
+ * Sidebar Component
+ * Navigation sidebar for component categories
+ * Adaptive: desktop (static) or mobile (portal)
+ */
+
+'use client';
+
+import React from 'react';
+import { createPortal } from 'react-dom';
+import { cn } from '@djangocfg/ui/lib';
+import { useIsMobile } from '@djangocfg/ui';
+import type { ComponentCategory } from '../../../types';
+import { SidebarContent } from './SidebarContent';
+
+export interface SidebarProps {
+  /** Available categories */
+  categories: ComponentCategory[];
+  /** Current selected category */
+  currentCategory?: string;
+  /** Category change callback */
+  onCategoryChange?: (categoryId: string) => void;
+  /** Is sidebar open (mobile only) */
+  isOpen?: boolean;
+  /** Project name */
+  projectName?: string;
+  /** Logo component */
+  logo?: React.ReactNode;
+}
+
+/**
+ * Sidebar Component
+ * Desktop: Always visible static sidebar
+ * Mobile: Portal-based sidebar with slide animation
+ */
+export function Sidebar({
+  categories,
+  currentCategory,
+  onCategoryChange,
+  isOpen = false,
+  projectName = 'Django CFG',
+  logo,
+}: SidebarProps) {
+  const isMobile = useIsMobile();
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  // Desktop sidebar - always visible, no portal
+  if (!isMobile) {
+    return (
+      <aside className="w-64 border-r bg-background flex-shrink-0">
+        <SidebarContent
+          categories={categories}
+          currentCategory={currentCategory}
+          onCategoryChange={onCategoryChange}
+          projectName={projectName}
+          logo={logo}
+          isMobile={false}
+        />
+      </aside>
+    );
+  }
+
+  // Mobile sidebar - use portal when open
+  if (!isOpen || !mounted) {
+    return null;
+  }
+
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  return createPortal(
+    <aside
+      className={cn(
+        'fixed inset-y-0 left-0 w-64 z-[200] bg-background border-r shadow-lg transition-transform duration-300',
+        isOpen ? 'translate-x-0' : '-translate-x-full'
+      )}
+    >
+      <SidebarContent
+        categories={categories}
+        currentCategory={currentCategory}
+        onCategoryChange={onCategoryChange}
+        projectName={projectName}
+        logo={logo}
+        isMobile={true}
+      />
+    </aside>,
+    document.body
+  );
+}

package/src/layouts/UILayout/components/layout/Sidebar/SidebarCategory.tsx

@@ -0,0 +1,54 @@
+/**
+ * SidebarCategory Component
+ * Single category item in sidebar navigation
+ */
+
+'use client';
+
+import React from 'react';
+import { cn } from '@djangocfg/ui/lib';
+import type { ComponentCategory } from '../../../types';
+import { CountBadge } from '../../shared/Badge';
+
+interface SidebarCategoryProps {
+  /** Category data */
+  category: ComponentCategory;
+  /** Is this category active */
+  active?: boolean;
+  /** Click handler */
+  onClick?: () => void;
+}
+
+/**
+ * Sidebar Category Item
+ * Displays a category with icon, label, and optional count badge
+ */
+export function SidebarCategory({
+  category,
+  active = false,
+  onClick,
+}: SidebarCategoryProps) {
+  return (
+    <button
+      onClick={onClick}
+      className={cn(
+        'w-full flex items-center gap-3 px-3 py-2 rounded-md text-sm font-medium transition-colors',
+        active
+          ? 'bg-primary text-primary-foreground'
+          : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+      )}
+      title={category.description}
+    >
+      {/* Icon */}
+      <span className="flex-shrink-0">{category.icon}</span>
+
+      {/* Label */}
+      <span className="flex-1 text-left break-words">{category.label}</span>
+
+      {/* Count Badge */}
+      {category.count !== undefined && (
+        <CountBadge count={category.count} active={active} />
+      )}
+    </button>
+  );
+}

package/src/layouts/UILayout/components/layout/Sidebar/SidebarContent.tsx

@@ -0,0 +1,86 @@
+/**
+ * SidebarContent Component
+ * Main content of the sidebar (logo, navigation, footer)
+ */
+
+'use client';
+
+import React from 'react';
+import { cn } from '@djangocfg/ui/lib';
+import type { ComponentCategory } from '../../../types';
+import { SidebarCategory } from './SidebarCategory';
+import { SidebarFooter } from './SidebarFooter';
+
+interface SidebarContentProps {
+  /** Available categories */
+  categories: ComponentCategory[];
+  /** Current selected category */
+  currentCategory?: string;
+  /** Category change callback */
+  onCategoryChange?: (categoryId: string) => void;
+  /** Project name */
+  projectName?: string;
+  /** Logo component */
+  logo?: React.ReactNode;
+  /** Is mobile view */
+  isMobile: boolean;
+}
+
+/**
+ * Sidebar Content
+ * Contains logo (desktop only), navigation, and footer
+ */
+export function SidebarContent({
+  categories,
+  currentCategory,
+  onCategoryChange,
+  projectName,
+  logo,
+  isMobile,
+}: SidebarContentProps) {
+  return (
+    <div
+      className={cn(
+        'flex flex-col overflow-hidden',
+        isMobile ? 'h-full' : 'h-screen'
+      )}
+    >
+      {/* Logo - Desktop only */}
+      {!isMobile && (
+        <div className="flex h-14 items-center border-b px-6 gap-2 flex-shrink-0">
+          {logo}
+          <span className="font-semibold text-sm">{projectName}</span>
+        </div>
+      )}
+
+      {/* Navigation */}
+      <div className="flex-1 overflow-y-auto scrollbar-thin">
+        <div className="p-4">
+          <nav>
+            {/* Section Header */}
+            <div className="mb-4">
+              <h3 className="mb-2 px-2 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+                Component Categories
+              </h3>
+            </div>
+
+            {/* Categories List */}
+            <div className="space-y-1">
+              {categories.map((category) => (
+                <SidebarCategory
+                  key={category.id}
+                  category={category}
+                  active={currentCategory === category.id}
+                  onClick={() => onCategoryChange?.(category.id)}
+                />
+              ))}
+            </div>
+          </nav>
+        </div>
+      </div>
+
+      {/* Footer */}
+      <SidebarFooter />
+    </div>
+  );
+}

package/src/layouts/UILayout/components/layout/Sidebar/SidebarFooter.tsx

@@ -0,0 +1,49 @@
+/**
+ * SidebarFooter Component
+ * Footer section with Tailwind CSS v4 information
+ */
+
+'use client';
+
+import React from 'react';
+
+/**
+ * Sidebar Footer
+ * Displays Tailwind CSS v4 features and benefits
+ */
+export function SidebarFooter() {
+  return (
+    <div className="border-t p-4 bg-muted/30">
+      {/* Header */}
+      <div className="mb-3">
+        <h4 className="text-xs font-semibold text-foreground uppercase tracking-wider mb-2">
+          Tailwind CSS v4
+        </h4>
+        <p className="text-xs text-muted-foreground leading-relaxed mb-3">
+          This UI library uses Tailwind CSS v4 with CSS-first configuration
+        </p>
+      </div>
+
+      {/* Features List */}
+      <div className="space-y-2 text-xs">
+        <FeatureItem text="CSS-first @theme configuration" />
+        <FeatureItem text="10x faster build times" />
+        <FeatureItem text="Modern CSS features (color-mix, @property)" />
+        <FeatureItem text="Responsive: px-4 sm:px-6 lg:px-8" />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Feature Item
+ * Single feature in the footer list
+ */
+function FeatureItem({ text }: { text: string }) {
+  return (
+    <div className="flex items-start gap-2">
+      <span className="text-primary mt-0.5">✓</span>
+      <span className="text-muted-foreground">{text}</span>
+    </div>
+  );
+}

package/src/layouts/UILayout/components/layout/Sidebar/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Sidebar Components
+ */
+
+export { Sidebar } from './Sidebar';
+export type { SidebarProps } from './Sidebar';
+export { SidebarContent } from './SidebarContent';
+export { SidebarCategory } from './SidebarCategory';
+export { SidebarFooter } from './SidebarFooter';

package/src/layouts/UILayout/components/layout/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Layout Components
+ * Structural components for UILayout
+ */
+
+export * from './Header';
+export * from './Sidebar';
+export * from './MobileOverlay';

package/src/layouts/UILayout/components/shared/Badge/CountBadge.tsx

@@ -0,0 +1,38 @@
+/**
+ * CountBadge Component
+ * Badge for displaying count numbers
+ */
+
+'use client';
+
+import React from 'react';
+import { cn } from '@djangocfg/ui/lib';
+
+interface CountBadgeProps {
+  /** Count to display */
+  count: number;
+  /** Is active/selected */
+  active?: boolean;
+  /** Custom class name */
+  className?: string;
+}
+
+/**
+ * Count Badge
+ * Displays a count number with optional active state
+ */
+export function CountBadge({ count, active = false, className }: CountBadgeProps) {
+  return (
+    <span
+      className={cn(
+        'text-xs px-2 py-0.5 rounded-full flex-shrink-0',
+        active
+          ? 'bg-primary-foreground/20 text-primary-foreground'
+          : 'bg-muted text-muted-foreground',
+        className
+      )}
+    >
+      {count}
+    </span>
+  );
+}

package/src/layouts/UILayout/components/shared/Badge/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Badge Components
+ */
+
+export { CountBadge } from './CountBadge';

package/src/layouts/UILayout/components/shared/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,48 @@
+/**
+ * CodeBlock Component
+ * Displays code with syntax highlighting and copy button
+ */
+
+'use client';
+
+import React from 'react';
+import { cn } from '@djangocfg/ui/lib';
+import { CopyButton } from './CopyButton';
+
+interface CodeBlockProps {
+  /** Code to display */
+  code: string;
+  /** Programming language */
+  language?: string;
+  /** Show copy button */
+  showCopy?: boolean;
+  /** Custom class name */
+  className?: string;
+}
+
+/**
+ * Code Block
+ * Displays formatted code with optional copy functionality
+ */
+export function CodeBlock({
+  code,
+  language = 'tsx',
+  showCopy = true,
+  className,
+}: CodeBlockProps) {
+  return (
+    <div className={cn('relative group', className)}>
+      {/* Copy Button */}
+      {showCopy && (
+        <div className="absolute right-2 top-2 opacity-0 group-hover:opacity-100 transition-opacity">
+          <CopyButton code={code} />
+        </div>
+      )}
+
+      {/* Code Display */}
+      <pre className="bg-muted/50 rounded-lg p-4 overflow-x-auto">
+        <code className={`language-${language} text-sm`}>{code}</code>
+      </pre>
+    </div>
+  );
+}

package/src/layouts/UILayout/components/shared/CodeBlock/CopyButton.tsx

@@ -0,0 +1,49 @@
+/**
+ * CopyButton Component
+ * Button for copying code to clipboard
+ */
+
+'use client';
+
+import React, { useState } from 'react';
+import { Button } from '@djangocfg/ui';
+import { Copy, Check } from 'lucide-react';
+import { useCopy } from '@djangocfg/ui';
+
+interface CopyButtonProps {
+  /** Code to copy */
+  code: string;
+  /** Button size */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+/**
+ * Copy Button
+ * Shows check icon after successful copy
+ */
+export function CopyButton({ code, size = 'sm' }: CopyButtonProps) {
+  const [copied, setCopied] = useState(false);
+  const { copyToClipboard } = useCopy();
+
+  const handleCopy = async () => {
+    await copyToClipboard(code);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <Button
+      variant="ghost"
+      size={size}
+      onClick={handleCopy}
+      className="h-8 w-8 p-0"
+      aria-label="Copy code"
+    >
+      {copied ? (
+        <Check className="h-4 w-4 text-green-500" />
+      ) : (
+        <Copy className="h-4 w-4" />
+      )}
+    </Button>
+  );
+}

package/src/layouts/UILayout/components/shared/CodeBlock/index.ts

@@ -0,0 +1,6 @@
+/**
+ * CodeBlock Components
+ */
+
+export { CodeBlock } from './CodeBlock';
+export { CopyButton } from './CopyButton';

package/src/layouts/UILayout/components/shared/Section/Section.tsx

@@ -0,0 +1,63 @@
+/**
+ * Section Component
+ * Reusable section with title and optional description
+ */
+
+'use client';
+
+import React, { ReactNode } from 'react';
+import { cn } from '@djangocfg/ui/lib';
+
+interface SectionProps {
+  /** Section title */
+  title?: string;
+  /** Section description */
+  description?: string;
+  /** Section content */
+  children: ReactNode;
+  /** Custom class name */
+  className?: string;
+  /** Title class name */
+  titleClassName?: string;
+  /** Content class name */
+  contentClassName?: string;
+}
+
+/**
+ * Section Component
+ * Displays a section with optional title and description
+ */
+export function Section({
+  title,
+  description,
+  children,
+  className,
+  titleClassName,
+  contentClassName,
+}: SectionProps) {
+  return (
+    <section className={cn('space-y-4', className)}>
+      {/* Header */}
+      {(title || description) && (
+        <div className="space-y-1">
+          {title && (
+            <h2
+              className={cn(
+                'text-2xl font-bold tracking-tight',
+                titleClassName
+              )}
+            >
+              {title}
+            </h2>
+          )}
+          {description && (
+            <p className="text-sm text-muted-foreground">{description}</p>
+          )}
+        </div>
+      )}
+
+      {/* Content */}
+      <div className={contentClassName}>{children}</div>
+    </section>
+  );
+}

package/src/layouts/UILayout/components/shared/Section/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Section Components
+ */
+
+export { Section } from './Section';

package/src/layouts/UILayout/components/shared/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared Components
+ * Reusable UI components
+ */
+
+export * from './Badge';
+export * from './CodeBlock';
+export * from './Section';

package/src/layouts/UILayout/config/components/navigation.config.tsx

@@ -29,6 +29,7 @@ import {
   PaginationNext,
   PaginationPrevious,
   SSRPagination,
+  StaticPagination,
 } from '@djangocfg/ui';
 import type { ComponentConfig } from './types';
 
@@ -291,4 +292,32 @@ export const NAVIGATION_COMPONENTS: ComponentConfig[] = [
       />
     ),
   },
+  {
+    name: 'StaticPagination',
+    category: 'navigation',
+    description: 'Client-side pagination component for static builds with callback support',
+    importPath: `import { StaticPagination } from '@djangocfg/ui';`,
+    example: `const [currentPage, setCurrentPage] = useState(1);
+
+<StaticPagination
+  currentPage={currentPage}
+  totalPages={10}
+  totalItems={100}
+  itemsPerPage={10}
+  hasNextPage={currentPage < 10}
+  hasPreviousPage={currentPage > 1}
+  onPageChange={(page) => setCurrentPage(page)}
+/>`,
+    preview: (
+      <StaticPagination
+        currentPage={2}
+        totalPages={10}
+        totalItems={100}
+        itemsPerPage={10}
+        hasNextPage={true}
+        hasPreviousPage={true}
+        onPageChange={(page) => console.log('Page changed to:', page)}
+      />
+    ),
+  },
 ];

package/src/layouts/UILayout/{UIGuideLanding.tsx → core/UIGuideLanding.tsx}

@@ -27,7 +27,7 @@ import {
   StatsSection,
   CTASection,
 } from '@djangocfg/ui/blocks';
-import { useShowcase } from './context';
+import { useShowcase } from '../context';
 
 interface UIGuideLandingProps {
   githubUrl?: string;

package/src/layouts/UILayout/{UIGuideView.tsx → core/UIGuideView.tsx}

@@ -8,11 +8,11 @@
 
 import React from 'react';
 import { UILayout } from './UILayout';
-import { CATEGORIES } from './config';
-import { ShowcaseProvider, useShowcase } from './context';
+import { CATEGORIES } from '../config';
+import { ShowcaseProvider, useShowcase } from '../context';
 import { UIGuideLanding } from './UIGuideLanding';
-import { CategoryRenderer } from './components/CategoryRenderer';
-import { TailwindGuideRenderer } from './components/TailwindGuideRenderer';
+import { CategoryRenderer } from '../components/CategoryRenderer';
+import { TailwindGuideRenderer } from '../components/TailwindGuideRenderer';
 
 function UIGuideContent() {
   const { currentCategory, setCurrentCategory } = useShowcase();

package/src/layouts/UILayout/{UILayout.tsx → core/UILayout.tsx}

@@ -5,25 +5,14 @@
 
 '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';
+import React from 'react';
+import { Sidebar } from '../components/layout/Sidebar';
+import { Header } from '../components/layout/Header';
+import { MobileOverlay } from '../components/layout/MobileOverlay';
+import { generateAIContext } from '../config';
+import { useShowcase } from '../context';
+import type { UILayoutProps } from '../types';
 
-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
@@ -57,7 +46,6 @@ export function UILayout({
   projectName = "Django CFG UI",
 }: UILayoutProps) {
   const { isSidebarOpen, toggleSidebar, closeSidebar } = useShowcase();
-  const { copyToClipboard } = useCopy();
 
   const handleCategoryChange = (categoryId: string) => {
     onCategoryChange?.(categoryId);
@@ -65,8 +53,7 @@ export function UILayout({
   };
 
   const handleCopyForAI = () => {
-    const aiContext = generateAIContext();
-    copyToClipboard(aiContext);
+    return generateAIContext();
   };
 
   return (
@@ -116,7 +103,3 @@ export function UILayout({
     </div>
   );
 }
-
-// Legacy export for backward compatibility
-export { UILayout as ComponentShowcaseLayout };
-export type { UILayoutProps as ComponentShowcaseLayoutProps };

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 { useSidebarState } from './useSidebarState';
+export { useAIExport } from './useAIExport';
+export { useCategoryNavigation } from './useCategoryNavigation';
+export { useComponentSearch } from './useComponentSearch';