@djangocfg/layouts 1.4.16 → 1.4.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "1.4.16",
+  "version": "1.4.17",
   "description": "Layout system and components for Unrealon applications",
   "author": {
     "name": "DjangoCFG",
@@ -63,9 +63,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.4.16",
-    "@djangocfg/og-image": "^1.4.16",
-    "@djangocfg/ui": "^1.4.16",
+    "@djangocfg/api": "^1.4.17",
+    "@djangocfg/og-image": "^1.4.17",
+    "@djangocfg/ui": "^1.4.17",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.468.0",
@@ -86,7 +86,7 @@
     "vidstack": "0.6.15"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.4.16",
+    "@djangocfg/typescript-config": "^1.4.17",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/layouts/AppLayout/layouts/PublicLayout/components/MobileDrawer.tsx

@@ -2,15 +2,21 @@
  * Mobile Drawer
  *
  * Full-screen slide-in drawer for mobile navigation
- * Refactored from _old/MainLayout - uses context only!
+ * Uses @djangocfg/ui Drawer component (Vaul-based)
  */
 
 'use client';
 
 import React from 'react';
-import { createPortal } from 'react-dom';
 import Link from 'next/link';
 import { X } from 'lucide-react';
+import {
+  Drawer,
+  DrawerContent,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerClose,
+} from '@djangocfg/ui/components';
 import { useAppContext } from '../../../context';
 import { useNavigation } from '../../../hooks';
 import { UserMenu } from '../../../components';
@@ -19,10 +25,10 @@ import { UserMenu } from '../../../components';
  * Mobile Drawer Component
  *
  * Features:
- * - Slide-in drawer from right
+ * - Slide-in drawer from right (using Vaul)
  * - UserMenu component (authenticated/guest)
  * - Navigation sections
- * - Backdrop overlay
+ * - Smooth animations via Vaul library
  *
  * All data from context!
  */
@@ -32,37 +38,6 @@ export function MobileDrawer() {
 
   const { app, publicLayout } = config;
 
-  // Track if we should render (stays true during close animation)
-  const [shouldRender, setShouldRender] = React.useState(false);
-
-  // Track animation state separately
-  const [isOpen, setIsOpen] = React.useState(false);
-
-  // Handle opening
-  React.useEffect(() => {
-    if (mobileDrawerOpen) {
-      setShouldRender(true);
-      // Trigger animation after render
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          setIsOpen(true);
-        });
-      });
-    } else {
-      // Start close animation
-      setIsOpen(false);
-      // Wait for animation to finish before unmounting
-      const timer = setTimeout(() => {
-        setShouldRender(false);
-      }, 300);
-      return () => clearTimeout(timer);
-    }
-  }, [mobileDrawerOpen]);
-
-  const handleClose = () => {
-    closeMobileDrawer();
-  };
-
   const handleNavigate = () => {
     closeMobileDrawer();
   };
@@ -78,99 +53,50 @@ export function MobileDrawer() {
     [publicLayout.navigation.menuSections]
   );
 
-  if (!shouldRender) return null;
-
-  // Portal to body to avoid z-index and positioning issues
-  if (typeof window === 'undefined') return null;
-
-  return createPortal(
-    <>
-      {/* Backdrop with fade animation */}
-      <div
-        className={`fixed inset-0 z-150 backdrop-blur-sm transition-opacity duration-300 ease-in-out lg:hidden ${
-          isOpen ? 'opacity-100' : 'opacity-0'
-        }`}
-        style={{ backgroundColor: 'rgb(0 0 0 / 0.5)' }}
-        onClick={handleClose}
-        aria-hidden="true"
-      />
-
-      {/* Menu Content with slide animation */}
-      <div
-        className={`fixed top-0 right-0 bottom-0 w-80 z-200 bg-popover border-l border-border shadow-2xl transition-transform duration-300 ease-in-out lg:hidden ${
-          isOpen ? 'translate-x-0' : 'translate-x-full'
-        }`}
-        role="dialog"
-        aria-modal="true"
-        aria-label="Mobile navigation menu"
-      >
-        <div className="flex flex-col h-full">
-          {/* Header */}
-          <div className="flex items-center justify-between p-4 border-b border-border/30">
-            <div className="flex items-center gap-3">
-              <img
-                src={app.logoPath}
-                alt={`${app.name} Logo`}
-                className="h-8 w-auto object-contain"
-              />
-              <span className="text-lg font-bold text-foreground">
-                {app.name}
-              </span>
-            </div>
-            <button
-              onClick={handleClose}
-              className="p-2 rounded-sm transition-colors hover:bg-accent/50"
-              aria-label="Close menu"
-            >
-              <X className="size-5" />
-            </button>
+  return (
+    <Drawer
+      open={mobileDrawerOpen}
+      onOpenChange={(open) => !open && closeMobileDrawer()}
+      direction="right"
+    >
+      <DrawerContent direction="right" className="w-80 lg:hidden">
+        {/* Header */}
+        <DrawerHeader className="flex flex-row items-center justify-between p-4 border-b border-border/30">
+          <div className="flex items-center gap-3">
+            <img
+              src={app.logoPath}
+              alt={`${app.name} Logo`}
+              className="h-8 w-auto object-contain"
+            />
+            <DrawerTitle className="text-lg font-bold text-foreground">
+              {app.name}
+            </DrawerTitle>
           </div>
-
-          {/* Scrollable Content */}
-          <div className="flex-1 overflow-y-auto p-4 space-y-6">
-            {/* User Menu Card */}
-            <UserMenu variant="mobile" onNavigate={handleNavigate} />
-
-            {/* Navigation Sections */}
-            <div className="space-y-6">
-              {/* Group all single-item sections into "Menu" */}
-              {singleItemSections.length > 0 && (
-                <div className="space-y-3">
-                  <h3 className="px-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
-                    Menu
-                  </h3>
-                  <div className="space-y-1">
-                    {singleItemSections.map((section) => {
-                      const item = section.items[0];
-                      if (!item) return null;
-
-                      return (
-                        <Link
-                          key={item.path}
-                          href={item.path}
-                          className={`block px-4 py-3 rounded-sm text-base font-medium transition-colors ${
-                            isActive(item.path)
-                              ? 'bg-accent text-accent-foreground'
-                              : 'text-foreground hover:bg-accent hover:text-accent-foreground'
-                          }`}
-                          onClick={handleNavigate}
-                        >
-                          {item.label}
-                        </Link>
-                      );
-                    })}
-                  </div>
-                </div>
-              )}
-
-              {/* Render multiple-items sections normally */}
-              {multipleItemsSections.map((section) => (
-                <div key={section.title} className="space-y-3">
-                  <h3 className="px-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
-                    {section.title}
-                  </h3>
-                  <div className="space-y-1">
-                    {section.items.map((item) => (
+          <DrawerClose className="p-2 rounded-sm transition-colors hover:bg-accent/50">
+            <X className="size-5" />
+            <span className="sr-only">Close menu</span>
+          </DrawerClose>
+        </DrawerHeader>
+
+        {/* Scrollable Content */}
+        <div className="flex-1 overflow-y-auto p-4 space-y-6">
+          {/* User Menu Card */}
+          <UserMenu variant="mobile" onNavigate={handleNavigate} />
+
+          {/* Navigation Sections */}
+          <div className="space-y-6">
+            {/* Group all single-item sections into "Menu" */}
+            {singleItemSections.length > 0 && (
+              <div className="space-y-3">
+                <h3 className="px-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                  Menu
+                </h3>
+                <div className="space-y-1">
+                  {singleItemSections.map((section) => {
+                    const item = section.items[0];
+                    if (!item) return null;
+
+                    return (
                       <Link
                         key={item.path}
                         href={item.path}
@@ -183,18 +109,42 @@ export function MobileDrawer() {
                       >
                         {item.label}
                       </Link>
-                    ))}
-                  </div>
+                    );
+                  })}
                 </div>
-              ))}
-            </div>
-
-            {/* Bottom spacer */}
-            <div style={{ height: '15vh' }}></div>
+              </div>
+            )}
+
+            {/* Render multiple-items sections normally */}
+            {multipleItemsSections.map((section) => (
+              <div key={section.title} className="space-y-3">
+                <h3 className="px-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                  {section.title}
+                </h3>
+                <div className="space-y-1">
+                  {section.items.map((item) => (
+                    <Link
+                      key={item.path}
+                      href={item.path}
+                      className={`block px-4 py-3 rounded-sm text-base font-medium transition-colors ${
+                        isActive(item.path)
+                          ? 'bg-accent text-accent-foreground'
+                          : 'text-foreground hover:bg-accent hover:text-accent-foreground'
+                      }`}
+                      onClick={handleNavigate}
+                    >
+                      {item.label}
+                    </Link>
+                  ))}
+                </div>
+              </div>
+            ))}
           </div>
+
+          {/* Bottom spacer */}
+          <div style={{ height: '15vh' }}></div>
         </div>
-      </div>
-    </>,
-    document.body
+      </DrawerContent>
+    </Drawer>
   );
 }

package/src/layouts/AppLayout/layouts/PublicLayout/components/Navigation.tsx

@@ -45,7 +45,7 @@ export function Navigation() {
   const { app, publicLayout } = config;
 
   return (
-    <nav className="sticky top-0 w-full border-b backdrop-blur-xl z-100 isolate" style={{ backgroundColor: 'hsl(var(--background) / 0.8)', borderColor: 'hsl(var(--border) / 0.3)' }}>
+    <nav className="sticky top-0 w-full backdrop-blur-xl z-50 isolate" style={{ backgroundColor: 'hsl(var(--background) / 0.8)', boxShadow: '0 1px 0 0 hsl(var(--border))', zIndex: 50 }}>
       <div className="w-full px-4 sm:px-6 lg:px-8">
         <div className="flex items-center justify-between py-2 min-h-[40px]">
           {/* Left side - Logo and Navigation Menu */}

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

@@ -157,6 +157,8 @@ export interface TestValidationButtonProps {
   size?: 'default' | 'sm' | 'lg' | 'icon';
   /** Additional CSS classes */
   className?: string;
+  /** Always show label (default: responsive - hidden on mobile) */
+  showLabel?: boolean;
 }
 
 /**
@@ -169,6 +171,7 @@ export function TestValidationButton({
   showInProduction = false,
   size = 'sm',
   className,
+  showLabel = false,
 }: TestValidationButtonProps) {
   const [isOpen, setIsOpen] = useState(false);
 
@@ -186,7 +189,7 @@ export function TestValidationButton({
           className={className}
         >
           <Bug className="h-4 w-4" />
-          <span className="ml-2 hidden sm:inline">Test Validation</span>
+          <span className={showLabel ? "ml-2" : "ml-2 hidden sm:inline"}>Test Validation</span>
         </Button>
       </DropdownMenuTrigger>
 

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

@@ -1,15 +1,14 @@
 /**
  * Sidebar Component
  * Navigation sidebar for component categories
- * Adaptive: desktop (static) or mobile (portal)
+ * Desktop: sticky with react-sticky-box
+ * Mobile: Drawer component (Vaul-based)
  */
 
 'use client';
 
 import React from 'react';
-import { createPortal } from 'react-dom';
-import { cn } from '@djangocfg/ui/lib';
-import { useIsMobile } from '@djangocfg/ui';
+import { useIsMobile, Sticky, Drawer, DrawerContent } from '@djangocfg/ui';
 import type { ComponentCategory } from '../../../types';
 import { SidebarContent } from './SidebarContent';
 
@@ -22,73 +21,75 @@ export interface SidebarProps {
   onCategoryChange?: (categoryId: string) => void;
   /** Is sidebar open (mobile only) */
   isOpen?: boolean;
-  /** Project name */
-  projectName?: string;
-  /** Logo component */
-  logo?: React.ReactNode;
+  /** Close sidebar callback (mobile only) */
+  onClose?: () => void;
+  /** Function to generate AI context */
+  onCopyForAI?: () => string;
 }
 
 /**
  * Sidebar Component
  * Desktop: Always visible static sidebar
- * Mobile: Portal-based sidebar with slide animation
+ * Mobile: Drawer-based sidebar with slide animation
  */
 export function Sidebar({
   categories,
   currentCategory,
   onCategoryChange,
   isOpen = false,
-  projectName = 'Django CFG',
-  logo,
+  onClose,
+  onCopyForAI,
 }: SidebarProps) {
   const isMobile = useIsMobile();
-  const [mounted, setMounted] = React.useState(false);
 
-  React.useEffect(() => {
-    setMounted(true);
-  }, []);
-
-  // Desktop sidebar - always visible, no portal
+  // Desktop sidebar - uses react-sticky-box via Sticky component
+  // Sticks to viewport top (with navbar offset) but stops at parent container boundary (footer)
+  // Parent UILayout has isolate + zIndex:0 to prevent overlapping navbar
   if (!isMobile) {
     return (
-      <aside className="w-64 border-r bg-background flex-shrink-0">
+      <div
+        className="w-64 flex-shrink-0 self-stretch bg-background"
+        style={{ boxShadow: '-1px 0 0 0 hsl(var(--border))' }}
+      >
+        <Sticky
+          offsetTop={56}
+          offsetBottom={0}
+          disableOnMobile={false}
+          className="w-64"
+        >
+          <aside
+            className="overflow-y-auto w-64 bg-background"
+            style={{ maxHeight: 'calc(100vh - 56px)' }}
+          >
+            <SidebarContent
+              categories={categories}
+              currentCategory={currentCategory}
+              onCategoryChange={onCategoryChange}
+              isMobile={false}
+              onCopyForAI={onCopyForAI}
+            />
+          </aside>
+        </Sticky>
+      </div>
+    );
+  }
+
+  // Mobile sidebar - uses Drawer component (Vaul-based)
+  return (
+    <Drawer
+      open={isOpen}
+      onOpenChange={(open) => !open && onClose?.()}
+      direction="right"
+    >
+      <DrawerContent direction="right" className="w-64">
         <SidebarContent
           categories={categories}
           currentCategory={currentCategory}
           onCategoryChange={onCategoryChange}
-          projectName={projectName}
-          logo={logo}
-          isMobile={false}
+          isMobile={true}
+          onCopyForAI={onCopyForAI}
         />
-      </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
+      </DrawerContent>
+    </Drawer>
   );
 }

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

@@ -6,10 +6,10 @@
 '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';
+import { CopyAIButton } from '../Header/CopyAIButton';
+import { TestValidationButton } from '../Header/TestValidationButton';
 
 interface SidebarContentProps {
   /** Available categories */
@@ -18,12 +18,10 @@ interface SidebarContentProps {
   currentCategory?: string;
   /** Category change callback */
   onCategoryChange?: (categoryId: string) => void;
-  /** Project name */
-  projectName?: string;
-  /** Logo component */
-  logo?: React.ReactNode;
   /** Is mobile view */
   isMobile: boolean;
+  /** Function to generate AI context */
+  onCopyForAI?: () => string;
 }
 
 /**
@@ -34,22 +32,27 @@ export function SidebarContent({
   categories,
   currentCategory,
   onCategoryChange,
-  projectName,
-  logo,
   isMobile,
+  onCopyForAI,
 }: SidebarContentProps) {
   return (
-    <div
-      className={cn(
-        'flex flex-col overflow-hidden',
-        isMobile ? 'h-full' : 'h-screen'
-      )}
-    >
-      {/* Logo - Desktop only */}
+    <div className="flex flex-col h-full overflow-hidden">
+
+      {/* Developer Tools */}
       {!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 className="border-b flex-shrink-0 px-4 py-3 flex gap-2">
+          {onCopyForAI && (
+            <CopyAIButton
+              onCopyForAI={onCopyForAI}
+              size="sm"
+              showLabel
+              className="flex-1"
+            />
+          )}
+          <TestValidationButton
+            size="sm"
+            showLabel={false}
+          />
         </div>
       )}
 
@@ -80,7 +83,11 @@ export function SidebarContent({
       </div>
 
       {/* Footer */}
-      <SidebarFooter />
+      <div className="border-t p-4 bg-muted/30">
+        <p className="text-xs text-muted-foreground">
+          Built with Tailwind CSS v4
+        </p>
+      </div>
     </div>
   );
 }

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

@@ -1,49 +1,49 @@
 /**
  * SidebarFooter Component
- * Footer section with Tailwind CSS v4 information
+ * Footer section with developer tools (Copy for AI, Test Validation)
  */
 
 'use client';
 
 import React from 'react';
+import { CopyAIButton } from '../Header/CopyAIButton';
+import { TestValidationButton } from '../Header/TestValidationButton';
+
+export interface SidebarFooterProps {
+  /** Function to generate AI context */
+  onCopyForAI?: () => string;
+}
 
 /**
  * Sidebar Footer
- * Displays Tailwind CSS v4 features and benefits
+ * Developer tools: Copy for AI and Test Validation buttons
  */
-export function SidebarFooter() {
+export function SidebarFooter({ onCopyForAI }: SidebarFooterProps) {
   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 className="border-t p-4 bg-muted/30 space-y-3">
+      {/* Developer Tools */}
+      <div className="flex flex-col gap-2">
+        {onCopyForAI && (
+          <CopyAIButton
+            onCopyForAI={onCopyForAI}
+            size="sm"
+            showLabel
+            className="w-full justify-start"
+          />
+        )}
+        <TestValidationButton
+          size="sm"
+          showLabel
+          className="w-full justify-start"
+        />
       </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" />
+      {/* Tailwind v4 info */}
+      <div className="pt-2 border-t border-border/50">
+        <p className="text-xs text-muted-foreground">
+          Built with Tailwind CSS v4
+        </p>
       </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/config/components/layout.config.tsx

@@ -113,16 +113,34 @@ export const LAYOUT_COMPONENTS: ComponentConfig[] = [
   {
     name: 'Sticky',
     category: 'layout',
-    description: 'Make content sticky on scroll',
+    description: 'Make content sticky on scroll with configurable behavior',
     importPath: "import { Sticky } from '@djangocfg/ui';",
-    example: `<Sticky offsetTop={0} disableOnMobile={false}>
+    example: `// Top sticky with react-sticky-box (respects parent container)
+<Sticky offsetTop={56} offsetBottom={0} zIndex={10}>
   <nav className="bg-background border p-4">
     Sticky Navigation
   </nav>
-</Sticky>`,
+</Sticky>
+
+// Bottom sticky with native CSS sticky
+<Sticky bottom useNativeSticky offsetBottom={0} zIndex={30}>
+  <footer className="bg-background border-t p-4">
+    Sticky Footer
+  </footer>
+</Sticky>
+
+// Props:
+// - offsetTop: number (default: 0) - top offset in pixels
+// - offsetBottom: number (default: 0) - bottom offset in pixels
+// - bottom: boolean (default: false) - stick to bottom instead of top
+// - disabled: boolean (default: false) - disable sticking
+// - disableOnMobile: boolean (default: true) - disable on mobile
+// - useNativeSticky: boolean (default: false) - use CSS sticky instead of react-sticky-box
+// - zIndex: number (default: 10) - z-index value
+// - debug: boolean (default: false) - enable debug logging`,
     preview: (
       <div className="h-[300px] overflow-auto border rounded-md relative">
-        <Sticky offsetTop={0} disableOnMobile={false}>
+        <Sticky offsetTop={0} disableOnMobile={false} zIndex={10}>
           <div className="bg-primary text-primary-foreground p-3 text-center font-semibold shadow-md">
             Sticky Header (scroll to see effect)
           </div>

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

@@ -1,11 +1,11 @@
 /**
  * Showcase Context
- * Manages navigation state for UILayout
+ * Manages navigation state for UILayout with URL hash sync
  */
 
 'use client';
 
-import React, { createContext, useContext, useState, ReactNode } from 'react';
+import React, { createContext, useContext, useState, useEffect, useCallback, ReactNode } from 'react';
 
 interface ShowcaseContextValue {
   currentCategory: string;
@@ -20,7 +20,45 @@ interface ShowcaseProviderProps {
 }
 
 export function ShowcaseProvider({ children, defaultCategory = 'overview' }: ShowcaseProviderProps) {
-  const [currentCategory, setCurrentCategory] = useState(defaultCategory);
+  // 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

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

@@ -1,30 +1,32 @@
 /**
  * UILayout
- * Modern, config-driven layout for UI component documentation
+ * 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 from 'react';
-import { Tabs, TabsList, TabsTrigger } from '@djangocfg/ui';
-import { Header } from '../components/layout/Header';
+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 - 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
+ * UILayout - Layout component with left sidebar navigation
+ * Designed to be used inside app layout (no competing header)
  *
  * @example
  * ```tsx
  * <UILayout
- *   title="UI Components"
  *   categories={CATEGORIES}
  *   currentCategory={category}
  *   onCategoryChange={setCategory}
@@ -35,68 +37,89 @@ import type { UILayoutProps } from '../types';
  */
 export function UILayout({
   children,
-  title = "UI Component Library",
   description,
   categories,
   currentCategory,
   onCategoryChange,
-  logo,
-  projectName = "Django CFG UI",
 }: UILayoutProps) {
-  const handleCopyForAI = () => {
-    return generateAIContext();
+  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 min-h-screen bg-background">
-      {/* Header with Copy for AI button */}
-      <Header
-        title={title}
-        projectName={projectName}
-        logo={logo}
-        onCopyForAI={handleCopyForAI}
-      />
+    <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}
+        />
 
-      {/* 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>
+      {/* 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,144 +1,11 @@
 /**
  * UILayoutSidebar
- * Modern layout with left sidebar navigation (instead of tabs)
- *
- * Features:
- * - Desktop: Fixed left sidebar with category navigation
- * - Mobile: Collapsible sidebar via burger menu
- * - Sticky header
- * - Responsive content area
+ * @deprecated Use UILayout instead - it now has sidebar navigation by default
  */
 
-'use client';
-
-import React, { useState } from 'react';
-import { Menu, X } from 'lucide-react';
-import { Button } from '@djangocfg/ui';
-import { useIsMobile } from '@djangocfg/ui';
-import { Header } from '../components/layout/Header';
-import { Sidebar } from '../components/layout/Sidebar';
-import { MobileOverlay } from '../components/layout/MobileOverlay';
-import { generateAIContext } from '../config';
-import type { UILayoutProps } from '../types';
+import { UILayout } from './UILayout';
 
 /**
- * UILayoutSidebar - Layout with left sidebar navigation
- *
- * Features:
- * - Config-driven sidebar categories
- * - "Copy for AI": One-click export of documentation
- * - Responsive: Mobile burger menu + overlay
- * - Type-safe: Full TypeScript support
- *
- * @example
- * ```tsx
- * <UILayoutSidebar
- *   title="UI Components"
- *   categories={CATEGORIES}
- *   currentCategory={category}
- *   onCategoryChange={setCategory}
- * >
- *   <CategoryRenderer categoryId={category} />
- * </UILayoutSidebar>
- * ```
+ * @deprecated Use UILayout instead
  */
-export function UILayoutSidebar({
-  children,
-  title = "UI Component Library",
-  description,
-  categories,
-  currentCategory,
-  onCategoryChange,
-  logo,
-  projectName = "Django CFG UI",
-}: UILayoutProps) {
-  const [isSidebarOpen, setIsSidebarOpen] = useState(false);
-  const isMobile = useIsMobile();
-
-  const handleCopyForAI = () => {
-    return generateAIContext();
-  };
-
-  const toggleSidebar = () => {
-    setIsSidebarOpen(!isSidebarOpen);
-  };
-
-  const handleCategoryChange = (categoryId: string) => {
-    onCategoryChange?.(categoryId);
-    // Auto-close sidebar on mobile after selection
-    if (isMobile) {
-      setIsSidebarOpen(false);
-    }
-  };
-
-  return (
-    <div className="flex flex-col min-h-screen bg-background">
-      {/* Header with mobile burger */}
-      <div className="sticky top-0 z-40 w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
-        <div className="flex h-14 items-center gap-4 px-4">
-          {/* Mobile burger menu */}
-          {isMobile && (
-            <Button
-              variant="ghost"
-              size="icon"
-              onClick={toggleSidebar}
-              className="shrink-0"
-              aria-label={isSidebarOpen ? "Close menu" : "Open menu"}
-            >
-              {isSidebarOpen ? (
-                <X className="h-5 w-5" />
-              ) : (
-                <Menu className="h-5 w-5" />
-              )}
-            </Button>
-          )}
-
-          {/* Header title and actions */}
-          <div className="flex-1 flex items-center justify-between">
-            <div className="flex items-center gap-2">
-              {!isMobile && logo}
-              <h1 className="text-lg font-semibold">{title}</h1>
-            </div>
-            <Header
-              title=""
-              projectName={projectName}
-              logo={null}
-              onCopyForAI={handleCopyForAI}
-            />
-          </div>
-        </div>
-      </div>
-
-      {/* Main layout: Sidebar + Content */}
-      <div className="flex flex-1 overflow-hidden">
-        {/* Sidebar */}
-        <Sidebar
-          categories={categories}
-          currentCategory={currentCategory}
-          onCategoryChange={handleCategoryChange}
-          isOpen={isSidebarOpen}
-          projectName={projectName}
-          logo={logo}
-        />
-
-        {/* Mobile overlay (backdrop) */}
-        <MobileOverlay
-          isOpen={isMobile && isSidebarOpen}
-          onClose={() => setIsSidebarOpen(false)}
-        />
-
-        {/* Main Content */}
-        <main className="flex-1 overflow-y-auto">
-          <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>
-    </div>
-  );
-}
+export const UILayoutSidebar = UILayout;