@anymux/ui-kit 0.1.0

package/src/layout/README.md

@@ -0,0 +1,307 @@
+# ExplorerLayout Component
+
+A fully-typed, responsive layout component designed for editor-style interfaces like file browsers, code editors, and similar applications.
+
+## Features
+
+- **Fully Responsive**: Automatically adapts to different screen sizes with configurable breakpoints
+- **Flexible Configuration**: Config-object API for easy customization of all sections
+- **Smooth Transitions**: CSS transitions for sidebar width changes and responsive behavior
+- **Mobile-First**: Mobile overlay behavior with hamburger toggle on small screens
+- **TypeScript**: Fully typed with comprehensive type definitions
+- **Tailwind Integration**: Uses Tailwind CSS classes with conditional styling
+
+## API
+
+### `ExplorerSections` Configuration Object
+
+```typescript
+interface ExplorerSections {
+  header?: ReactNode;
+  footer?: ReactNode;
+  sidebar?: {
+    content: ReactNode;
+    toolbar?: ReactNode;
+    width?: number;            // px, default 224
+  };
+  main: {
+    content: ReactNode;
+    toolbar?: ReactNode;
+  };
+  responsive?: {
+    breakpoint?: number;       // px, default 768
+    sidebarCollapsed?: boolean;
+  };
+}
+```
+
+### `ExplorerLayoutProps`
+
+```typescript
+interface ExplorerLayoutProps {
+  sections: ExplorerSections;
+  className?: string;
+}
+```
+
+## Layout Structure
+
+```
+┌─────────────────────────────────────┐
+│              Header                 │ (optional)
+├──────────┬──────────────────────────┤
+│          │     Main Toolbar         │ (optional)
+│ Sidebar  ├──────────────────────────┤
+│ Toolbar  │                          │
+├──────────┤     Main Content         │ (required)
+│          │                          │
+│ Sidebar  │                          │
+│ Content  │                          │
+│          │                          │
+├──────────┴──────────────────────────┤
+│               Footer                │ (optional)
+└─────────────────────────────────────┘
+```
+
+## Responsive Behavior
+
+- **Desktop (≥ breakpoint)**: Two-column layout with fixed sidebar
+- **Mobile (< breakpoint)**: Single column with overlay sidebar
+- **Mobile Toggle**: ☰ button appears in top-left corner for sidebar toggle
+- **Backdrop**: Click outside sidebar to close on mobile
+
+## Basic Usage
+
+```tsx
+import { ExplorerLayout, type ExplorerSections } from '@anymux/fs-ui';
+import { useState } from 'react';
+
+const sections: ExplorerSections = {
+  header: <div className="p-4">My App Header</div>,
+  sidebar: {
+    content: <div className="p-4">Navigation content</div>,
+    toolbar: <div className="p-2">Sidebar toolbar</div>,
+    width: 280,
+  },
+  main: {
+    content: <div className="p-4">Main content area</div>,
+    toolbar: <div className="p-2">Main toolbar</div>,
+  },
+  footer: <div className="p-2">Status bar</div>,
+};
+
+// With internal collapse state (automatic)
+export const MyApp = () => (
+  <div className="h-screen">
+    <ExplorerLayout sections={sections} />
+  </div>
+);
+
+// With external collapse state (controlled)
+export const MyControlledApp = () => {
+  const [collapsed, setCollapsed] = useState(false);
+  
+  return (
+    <div className="h-screen">
+      <ExplorerLayout 
+        sections={sections}
+        isSidebarCollapsed={collapsed}
+        setSidebarCollapsed={setCollapsed}
+      />
+    </div>
+  );
+};
+```
+
+## Advanced Examples
+
+### Code Editor Layout
+
+```tsx
+const editorSections: ExplorerSections = {
+  header: (
+    <div className="p-4 flex items-center justify-between border-b">
+      <h1 className="text-lg font-semibold">Code Editor</h1>
+      <div className="flex gap-2">
+        <Button size="sm">File</Button>
+        <Button size="sm">Edit</Button>
+        <Button size="sm">View</Button>
+      </div>
+    </div>
+  ),
+  sidebar: {
+    content: <FileExplorer />,
+    toolbar: (
+      <div className="p-2 flex items-center justify-between">
+        <span className="text-sm font-medium">Explorer</span>
+        <Button variant="ghost" size="sm">+</Button>
+      </div>
+    ),
+    width: 320,
+  },
+  main: {
+    content: <CodeEditor />,
+    toolbar: (
+      <div className="p-2 flex items-center justify-between">
+        <span className="text-sm">src/App.tsx</span>
+        <div className="flex gap-1">
+          <Button variant="ghost" size="sm">Save</Button>
+          <Button variant="ghost" size="sm">Format</Button>
+        </div>
+      </div>
+    ),
+  },
+  footer: (
+    <div className="p-2 flex items-center justify-between text-xs bg-muted">
+      <span>Ln 42, Col 15</span>
+      <span>TypeScript • UTF-8</span>
+    </div>
+  ),
+  responsive: {
+    breakpoint: 768,
+  },
+};
+```
+
+### Minimal Layout (No Header/Footer)
+
+```tsx
+const minimalSections: ExplorerSections = {
+  sidebar: {
+    content: <NavigationMenu />,
+    width: 240,
+  },
+  main: {
+    content: <MainContent />,
+  },
+  responsive: {
+    breakpoint: 640,
+    sidebarCollapsed: false,
+  },
+};
+```
+
+### No Sidebar Layout
+
+```tsx
+const noSidebarSections: ExplorerSections = {
+  header: <AppHeader />,
+  main: {
+    content: <FullWidthContent />,
+    toolbar: <ContentToolbar />,
+  },
+  footer: <AppFooter />,
+};
+```
+
+## Styling Guidelines
+
+### Full Height Containers
+
+Always ensure the parent container has full height:
+
+```tsx
+// ✅ Correct
+<div className="h-screen">
+  <ExplorerLayout sections={sections} />
+</div>
+
+// ❌ Incorrect - layout won't fill screen
+<div>
+  <ExplorerLayout sections={sections} />
+</div>
+```
+
+### Content Overflow
+
+For scrollable content areas, use `overflow-auto` or `overflow-hidden`:
+
+```tsx
+const sections: ExplorerSections = {
+  sidebar: {
+    content: (
+      <div className="h-full overflow-auto p-4">
+        {/* Long list of items */}
+      </div>
+    ),
+  },
+  main: {
+    content: (
+      <div className="h-full overflow-auto p-4">
+        {/* Scrollable main content */}
+      </div>
+    ),
+  },
+};
+```
+
+## Configuration Tips
+
+### Responsive Breakpoints
+
+Choose breakpoints based on your content:
+
+- **Small layouts**: 640px (mobile-first)
+- **Standard layouts**: 768px (tablet breakpoint)
+- **Wide layouts**: 1024px (desktop-first)
+
+### Sidebar Widths
+
+Recommended sidebar widths:
+
+- **Navigation only**: 200-240px
+- **File explorer**: 280-320px
+- **Tool panels**: 320-400px
+- **Wide content**: 400-500px
+
+### Performance Considerations
+
+- Use `React.memo()` for expensive sidebar/main content
+- Implement virtualization for large lists
+- Minimize re-renders by memoizing section configurations
+
+## Testing
+
+The component includes a comprehensive demo at:
+`/explorer-layout-samples`
+
+Test different:
+- Screen sizes and responsive behavior
+- Section combinations (with/without header, footer, sidebar)
+- Content types and overflow scenarios
+- Mobile overlay functionality
+
+## Migration from FileBrowser
+
+If migrating from the FileBrowser component:
+
+```tsx
+// Before (FileBrowser pattern)
+<div className="flex h-full">
+  <div className="w-80 border-r">
+    <SidebarContent />
+  </div>
+  <div className="flex-1">
+    <MainContent />
+  </div>
+</div>
+
+// After (ExplorerLayout)
+const sections: ExplorerSections = {
+  sidebar: {
+    content: <SidebarContent />,
+    width: 320,
+  },
+  main: {
+    content: <MainContent />,
+  },
+};
+
+<ExplorerLayout sections={sections} />
+```
+
+## Browser Support
+
+- Modern browsers with CSS Grid and Flexbox support
+- Mobile browsers with touch events
+- Responsive design works on all screen sizes 

package/src/layout/components/ExplorerLayout/ExplorerLayout.tsx

@@ -0,0 +1,178 @@
+import React, { ReactNode, useState, useEffect, useCallback } from 'react';
+import { observer } from 'mobx-react-lite';
+import { cn } from '../../../lib/utils';
+import { Button } from '@anymux/ui/components/button';
+import { ChevronLeft, ChevronRight, PanelLeftClose, PanelLeft } from 'lucide-react';
+
+export interface ExplorerSections {
+  header?: ReactNode;
+  footer?: ReactNode;
+  sidebar?: {
+    content: ReactNode;
+    toolbar?: ReactNode;
+    width?: number; // px, default 280
+  };
+  main: {
+    content: ReactNode;
+    toolbar?: ReactNode;
+  };
+}
+
+export interface ExplorerLayoutProps {
+  sections: ExplorerSections;
+  className?: string;
+  isSidebarCollapsed?: boolean;
+  setSidebarCollapsed?: (collapsed: boolean) => void;
+}
+
+const MOBILE_BREAKPOINT = 768;
+
+export const ExplorerLayout: React.FC<ExplorerLayoutProps> = observer(({
+  sections,
+  className,
+  isSidebarCollapsed: externalCollapsed,
+  setSidebarCollapsed: externalSetCollapsed
+}) => {
+  const [internalCollapsed, setInternalCollapsed] = useState(false);
+  const [isMobile, setIsMobile] = useState(false);
+  const [mobileOpen, setMobileOpen] = useState(false);
+
+  const isCollapsed = externalCollapsed ?? internalCollapsed;
+  const setCollapsed = externalSetCollapsed ?? setInternalCollapsed;
+
+  const sidebarWidth = sections.sidebar?.width ?? 280;
+
+  useEffect(() => {
+    const checkMobile = () => {
+      const mobile = window.innerWidth < MOBILE_BREAKPOINT;
+      setIsMobile(mobile);
+      if (mobile) {
+        setMobileOpen(false);
+      }
+    };
+    checkMobile();
+    window.addEventListener('resize', checkMobile);
+    return () => window.removeEventListener('resize', checkMobile);
+  }, []);
+
+  const handleOverlayClick = useCallback(() => {
+    setMobileOpen(false);
+  }, []);
+
+  const showSidebar = sections.sidebar && (isMobile ? mobileOpen : !isCollapsed);
+
+  return (
+    <div className={cn("flex flex-col h-full w-full bg-background", className)}>
+      {/* Header Section */}
+      {sections.header && (
+        <div className="flex-shrink-0 border-b bg-background">
+          {sections.header}
+        </div>
+      )}
+
+      {/* Main content - dual panel layout */}
+      <div className="flex flex-1 min-h-0 relative">
+        {/* Mobile overlay */}
+        {isMobile && mobileOpen && (
+          <div
+            className="absolute inset-0 bg-black/30 z-30"
+            onClick={handleOverlayClick}
+          />
+        )}
+
+        {/* Left Panel - Sidebar */}
+        {sections.sidebar && (isMobile ? mobileOpen : true) && (
+          <div
+            className={cn(
+              "bg-background flex flex-col flex-shrink-0 transition-all duration-200 ease-in-out",
+              isMobile
+                ? "absolute inset-y-0 left-0 z-40 border-r shadow-lg"
+                : cn(
+                    "border-r relative",
+                    isCollapsed && "overflow-hidden"
+                  )
+            )}
+            style={{
+              width: isMobile
+                ? Math.min(sidebarWidth, 300)
+                : (isCollapsed ? 0 : sidebarWidth)
+            }}
+          >
+            {/* Sidebar Toolbar */}
+            {!isCollapsed && (
+              <div className="px-2 border-b bg-muted/10 flex-shrink-0 flex items-center h-10 gap-1">
+                <div className="flex-1 min-w-0">
+                  {sections.sidebar.toolbar}
+                </div>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className="h-6 w-6 flex-shrink-0"
+                  onClick={() => {
+                    if (isMobile) {
+                      setMobileOpen(false);
+                    } else {
+                      setCollapsed(true);
+                    }
+                  }}
+                  title="Collapse sidebar"
+                >
+                  <PanelLeftClose className="h-4 w-4" />
+                </Button>
+              </div>
+            )}
+
+            {/* Sidebar Content */}
+            <div className="flex-1 min-h-0 overflow-auto">
+              {sections.sidebar.content}
+            </div>
+          </div>
+        )}
+
+        {/* Right Panel - Main Content */}
+        <div className="flex-1 flex flex-col min-w-0">
+          {/* Main Toolbar */}
+          {sections.main.toolbar && (
+            <div className="px-2 border-b bg-muted/10 flex items-center justify-between flex-shrink-0 h-10">
+              <div className="flex items-center gap-2 flex-1 min-w-0">
+                {/* Mobile sidebar toggle + collapsed sidebar toggle */}
+                {sections.sidebar && (isMobile || isCollapsed) && !(isMobile && mobileOpen) && (
+                  <Button
+                    variant="ghost"
+                    size="icon"
+                    className="h-6 w-6 flex-shrink-0"
+                    onClick={() => {
+                      if (isMobile) {
+                        setMobileOpen(true);
+                      } else {
+                        setCollapsed(false);
+                      }
+                    }}
+                    title="Show sidebar"
+                  >
+                    <PanelLeft className="h-4 w-4" />
+                  </Button>
+                )}
+                {sections.main.toolbar}
+              </div>
+            </div>
+          )}
+
+          {/* Main Content */}
+          <div className="flex-1 min-h-0 overflow-hidden">
+            {sections.main.content}
+          </div>
+        </div>
+      </div>
+
+      {/* Footer Section */}
+      {sections.footer && (
+        <div className="flex-shrink-0 border-t bg-background">
+          {sections.footer}
+        </div>
+      )}
+    </div>
+  );
+});
+
+ExplorerLayout.displayName = 'ExplorerLayout';

package/src/layout/examples/SimpleExample.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { ExplorerLayout, type ExplorerSections } from '../';
+import { Button } from '@anymux/ui/components/button';
+
+// AICODE-NOTE: Minimal example showing ExplorerLayout basic usage
+export const SimpleExample: React.FC = () => {
+  const sections: ExplorerSections = {
+    header: (
+      <div className="p-4 flex items-center justify-between border-b">
+        <h1 className="text-lg font-semibold">My App</h1>
+        <Button variant="outline" size="sm">Settings</Button>
+      </div>
+    ),
+    sidebar: {
+      content: (
+        <div className="p-4">
+          <h3 className="font-medium mb-2">Navigation</h3>
+          <div className="space-y-1">
+            <div className="p-2 rounded hover:bg-muted cursor-pointer">📁 Files</div>
+            <div className="p-2 rounded hover:bg-muted cursor-pointer">🔍 Search</div>
+            <div className="p-2 rounded hover:bg-muted cursor-pointer">⚙️ Settings</div>
+          </div>
+        </div>
+      ),
+      toolbar: (
+        <div className="p-2 border-b">
+          <span className="text-sm font-medium">Explorer</span>
+        </div>
+      ),
+      width: 240,
+    },
+    main: {
+      content: (
+        <div className="p-8 text-center">
+          <h2 className="text-xl font-semibold mb-4">Welcome to ExplorerLayout</h2>
+          <p className="text-muted-foreground">
+            This is the main content area. It automatically adapts to different screen sizes.
+          </p>
+        </div>
+      ),
+      toolbar: (
+        <div className="p-2 border-b flex items-center justify-between">
+          <span className="text-sm font-medium">Main Content</span>
+          <Button variant="ghost" size="sm">Action</Button>
+        </div>
+      ),
+    },
+    footer: (
+      <div className="p-2 border-t text-center text-sm text-muted-foreground">
+        Ready
+      </div>
+    ),
+  };
+
+  return (
+    <div className="h-screen w-screen">
+      <ExplorerLayout sections={sections} />
+    </div>
+  );
+}; 

package/src/layout/index.ts

@@ -0,0 +1,6 @@
+// AICODE-NOTE: Main exports for EditorLayout module
+export { ExplorerLayout } from './components/ExplorerLayout/ExplorerLayout';
+export type { ExplorerLayoutProps, ExplorerSections } from './components/ExplorerLayout/ExplorerLayout';
+
+// Examples
+export { SimpleExample as ExplorerLayoutSimpleExample } from './examples/SimpleExample'; 

package/src/lib/utils.ts

@@ -0,0 +1 @@
+export { cn } from '@anymux/ui/lib/utils';