npm package: @samirify/layouts
Description: A modern, customizable React layout component library
Author: Samir Ibrahim
Latest version: 1.0.1-alpha.1

# @samirify/layouts

A modern, customizable React layout component library with support for multiple themes and styling frameworks.

## Features

- 🎨 **Multiple Themes**: Default, Tailwind CSS, and Bootstrap styling options
- 🌓 **Dark Mode**: Built-in light/dark mode support
- 🌍 **RTL Support**: Full right-to-left language support
- 📱 **Responsive**: Mobile-friendly with collapsible sidebar
- ⚙️ **Settings Panel**: Slide-in settings panel from the right
- 🧩 **Modular Components**: Use individual components or the complete layout
- 📦 **TypeScript**: Full TypeScript support with comprehensive type definitions
- 🎯 **Customizable**: Extensive configuration options for headers, sidebars, and footers
- ✅ **Well-tested**: Comprehensive test coverage

## Installation

```bash
npm install @samirify/layouts
```

### Optional Dependencies

Depending on which theme you want to use, install the corresponding CSS framework:

```bash
# For Tailwind theme
npm install tailwindcss @tailwindcss/forms

# For Bootstrap theme
npm install bootstrap
```

## Quick Start

```tsx
import React from 'react';
import Layout from '@samirify/layouts';
import '@samirify/layouts/css';

function App() {
  const menuItems = [
    { id: '1', label: 'Dashboard', icon: '📊', path: '/dashboard', isActive: true },
    { id: '2', label: 'Contacts', icon: '👥', path: '/contacts' },
    { id: '3', label: 'Companies', icon: '🏢', path: '/companies' },
  ];

  return (
    <Layout
      theme="default"
      mode="light"
      sidebar={{
        title: 'My CRM',
        menuItems: menuItems,
      }}
      header={{
        title: 'Dashboard',
      }}
      user={{
        name: 'John Doe',
        email: 'john@example.com',
      }}
      onLogout={() => console.log('Logout clicked')}
    >
      <h1>Welcome to Your CRM</h1>
      <p>This is your main content area.</p>
    </Layout>
  );
}

export default App;
```

## Themes

### Default Theme

Uses custom SCSS styling for maximum flexibility:

```tsx
import Layout from '@samirify/layouts';
import '@samirify/layouts/css';

<Layout theme="default" {...props}>
  {/* Your content */}
</Layout>
```

### Tailwind Theme

Optimized for Tailwind CSS projects:

```tsx
import Layout from '@samirify/layouts';
import '@samirify/layouts/css';

<Layout theme="tailwind" {...props}>
  {/* Your content */}
</Layout>
```

### Bootstrap Theme

Perfect for Bootstrap projects:

```tsx
import Layout from '@samirify/layouts';
import '@samirify/layouts/css';
import 'bootstrap/dist/css/bootstrap.min.css';

<Layout theme="bootstrap" {...props}>
  {/* Your content */}
</Layout>
```

### Auto-Detection

The layout can automatically detect which CSS framework you're using:

```tsx
<Layout theme="auto" {...props}>
  {/* Your content */}
</Layout>
```

## Props

### LayoutProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `theme` | `'default' \| 'tailwind' \| 'bootstrap' \| 'auto'` | `'auto'` | Layout theme/template to use |
| `mode` | `'light' \| 'dark'` | `'light'` | Light or dark mode |
| `direction` | `'ltr' \| 'rtl'` | `'ltr'` | Text direction (left-to-right or right-to-left) |
| `type` | `'default' \| 'sidebar-left' \| 'sidebar-right' \| 'top-nav'` | `'default'` | Layout type/variant |
| `children` | `React.ReactNode` | - | Main content to render |
| `header` | `HeaderConfig` | - | Header configuration |
| `sidebar` | `SidebarConfig` | - | Sidebar configuration |
| `footer` | `FooterConfig` | - | Footer configuration |
| `settings` | `SettingsConfig` | - | Settings panel configuration |
| `user` | `UserInfo` | - | User information |
| `onLogout` | `() => void` | - | Logout handler |
| `showSettings` | `boolean` | `true` | Whether to show the settings button |
| `showLogout` | `boolean` | `true` | Whether to show the logout button |
| `loading` | `boolean` | `false` | Loading state |

### SidebarConfig

```tsx
interface SidebarConfig {
  logo?: React.ReactNode | string;
  title?: string;
  menuItems: MenuItem[];
  footer?: React.ReactNode;
  collapsible?: boolean;
  collapsed?: boolean;
  onToggleCollapse?: (collapsed: boolean) => void;
}
```

### MenuItem

```tsx
interface MenuItem {
  id: string;
  label: string;
  icon?: React.ReactNode | string;
  path?: string;
  onClick?: () => void;
  badge?: string | number;
  children?: MenuItem[];
  isActive?: boolean;
  disabled?: boolean;
}
```

### HeaderConfig

```tsx
interface HeaderConfig {
  logo?: React.ReactNode | string;
  title?: string;
  showSearch?: boolean;
  searchPlaceholder?: string;
  onSearch?: (query: string) => void;
  actions?: React.ReactNode[];
  showNotifications?: boolean;
  notificationCount?: number;
  onNotificationClick?: () => void;
}
```

## Advanced Usage

### With Search Functionality

```tsx
<Layout
  header={{
    title: 'Dashboard',
    showSearch: true,
    searchPlaceholder: 'Search records...',
    onSearch: (query) => console.log('Search:', query),
  }}
  {...otherProps}
>
  {/* Content */}
</Layout>
```

### With Nested Menu Items

```tsx
const menuItems = [
  { id: '1', label: 'Dashboard', icon: '📊', path: '/dashboard' },
  {
    id: '2',
    label: 'Settings',
    icon: '⚙️',
    children: [
      { id: '2-1', label: 'Profile', path: '/settings/profile' },
      { id: '2-2', label: 'Team', path: '/settings/team' },
      { id: '2-3', label: 'Billing', path: '/settings/billing' },
    ],
  },
];

<Layout sidebar={{ menuItems }} {...otherProps}>
  {/* Content */}
</Layout>
```

### With Settings Panel

```tsx
const settingsSections = [
  {
    id: 'appearance',
    title: 'Appearance',
    icon: '🎨',
    content: <div>{/* Your settings UI */}</div>,
  },
  {
    id: 'notifications',
    title: 'Notifications',
    icon: '🔔',
    content: <div>{/* Your settings UI */}</div>,
  },
];

<Layout
  settings={{
    title: 'Settings',
    sections: settingsSections,
  }}
  {...otherProps}
>
  {/* Content */}
</Layout>
```

### With Footer

```tsx
<Layout
  footer={{
    copyright: '© 2024 Your Company. All rights reserved.',
    links: [
      { label: 'Privacy', href: '/privacy' },
      { label: 'Terms', href: '/terms' },
      { label: 'Help', href: '/help' },
    ],
  }}
  {...otherProps}
>
  {/* Content */}
</Layout>
```

### With RTL Support

Perfect for Arabic, Hebrew, and other right-to-left languages:

```tsx
<Layout
  direction="rtl"
  sidebar={{
    title: 'لوحة التحكم',
    menuItems: [
      { id: '1', label: 'الرئيسية', icon: '📊', path: '/dashboard' },
      { id: '2', label: 'جهات الاتصال', icon: '👥', path: '/contacts' },
    ],
  }}
  {...otherProps}
>
  {/* Content */}
</Layout>
```

## Custom Styling

### Using SCSS

You can import and customize the SCSS variables:

```scss
// Override variables before importing
$primary-color: #your-color;
$sidebar-width: 18rem;

@import '@samirify/layouts/scss';
```

### Available SCSS Files

```tsx
// Main stylesheet
import '@samirify/layouts/scss';

// Variables only
import '@samirify/layouts/scss/variables';

// Global styles only
import '@samirify/layouts/scss/global';

// Tailwind-specific styles
import '@samirify/layouts/scss/tailwind';

// Bootstrap-specific styles
import '@samirify/layouts/scss/bootstrap';
```

## Individual Components

You can also use individual components separately:

```tsx
import { Header, Sidebar, ContentArea, Footer, SettingsPanel } from '@samirify/layouts';

function MyCustomLayout() {
  return (
    <div className="my-layout">
      <Header config={{ title: 'My App' }} />
      <Sidebar config={{ menuItems: [...] }} />
      <ContentArea>
        {/* Your content */}
      </ContentArea>
      <Footer config={{ copyright: '© 2024' }} />
      <SettingsPanel config={{ title: 'Settings' }} isOpen={true} />
    </div>
  );
}
```

## TypeScript

The package includes comprehensive TypeScript definitions. Import types as needed:

```tsx
import type {
  LayoutProps,
  MenuItem,
  HeaderConfig,
  SidebarConfig,
  FooterConfig,
  SettingsConfig,
  UserInfo,
} from '@samirify/layouts';
```

## Examples

Check out the included examples:

```tsx
import { BasicExample, TailwindExample, BootstrapExample } from '@samirify/layouts';
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

## License

MIT © [Samir Ibrahim](https://github.com/samirify)

## Links

- [GitHub Repository](https://github.com/samirify/crm)
- [Issue Tracker](https://github.com/samirify/crm/issues)
- [NPM Package](https://www.npmjs.com/package/@samirify/layouts)

## Support

For questions and support, please open an issue on GitHub.