npm package: @kt-components/layout-header-sidebar
Description: Reusable Header and Sidebar components for React/Next.js projects
Author: Jakprim
Latest version: 1.0.9

# Gov Components Layout Header Sidebar

Reusable Header and Sidebar layout components designed for Next.js applications, pre-styled with Tailwind CSS. Perfect for government

## Features

- **Responsive Sidebar**: Automatically collapses on mobile, togglable on desktop.
- **Notification System**: Built-in notification bell with dropdown list.
- **User Profile**: Display user avatar, name, and role.
- **Tailwind CSS**: Beautifully styled using Tailwind utility classes.
- **TypeScript**: Fully typed for excellent developer experience.

## Requirements

- React 18+
- Next.js 13+ (App Router recommended)
- TailwindCSS 3 (Optional, styles are bundled)

## Installation

Install the package via npm:

```bash
npm install @kt-components/layout-header-sidebar
```

## Setup (Important!)

You **must** import the CSS file to make the components look right. Add this line to your **root layout** file (usually `app/layout.tsx`):

```tsx
// app/layout.tsx
import "@kt-components/layout-header-sidebar/dist/styles.css";
// ... other imports
```

If you are using Next.js Transpile Packages (to avoid build errors with local packages), add this to `next.config.js`:

```js
const nextConfig = {
  transpilePackages: ['@kt-components/layout-header-sidebar'],
};
```

## Usage Guide

### 1. Basic Layout Setup

Combine `Header` and `SharedSidebar` to create a standard dashboard layout.

```tsx
// app/page.tsx
'use client';

import { Header, SharedSidebar, toggleSidebar, MenuItem } from '@kt-components/layout-header-sidebar';
import { useRouter } from 'next/navigation';

export default function Dashboard() {
    const router = useRouter();

    // 1. Define User Data
    const user = {
        firstName: 'John',
        lastName: 'Doe',
        pictureUrl: 'https://example.com/avatar.jpg',
        role: 'ADMIN' // Optional role badge
    };

    // 2. Define Menu Items
    const menuItems: MenuItem[] = [
        {
            id: 'dashboard',
            title: 'Dashboard',
            path: '/dashboard',
            icon: <span>📊</span> // Can be any React Node (SVG, Icon component)
        },
        {
            id: 'settings',
            title: 'Settings',
            path: '/settings',
            icon: <span>⚙️</span>
        }
    ];

    return (
        <div className="min-h-screen bg-gray-50">
            {/* Header Component */}
            <Header 
                user={user} 
                sidebarId="main-sidebar" // Must match sidebarId in SharedSidebar
            />

            {/* Sidebar Component */}
            <SharedSidebar
                user={user}
                menuItems={menuItems}
                sidebarId="main-sidebar"
                profilePath="/profile" 
                roleLabel="Administrator"
                roleColor="purple" // teal, purple, orange, blue, green
                onNavigate={(path) => router.push(path)}
                onLogout={() => console.log('User logged out')}
            />

            {/* Main Content Area */}
            <main className="lg:pl-64 pt-20 p-8 transition-all duration-300">
                <h1>Welcome to Dashboard</h1>
            </main>
        </div>
    );
}
```

### 2. Using Notifications

The Header component accepts a `notifications` array to display a dropdown.

```tsx
import { Header, NotificationItem } from '@kt-components/layout-header-sidebar';

const notifications: NotificationItem[] = [
    {
        id: 1,
        title: 'System Update',
        description: 'System maintenance scheduled at midnight.',
        date: '10 mins ago',
        type: 'info', // 'info' | 'success' | 'reminder'
        isRead: false
    },
    {
        id: 2,
        title: 'Task Completed',
        description: 'Your export task has finished successfully.',
        date: '1 hour ago',
        type: 'success',
        isRead: true
    }
];

// In your render:
<Header 
    user={user} 
    notifications={notifications} 
/>
```

### 3. Toggling Sidebar Programmatically

You can control the sidebar state from anywhere in your app using the `toggleSidebar` utility.

```tsx
import { toggleSidebar } from '@kt-components/layout-header-sidebar';

// Toggle default sidebar ('sidebar', 'sidebar-overlay')
<button onClick={() => toggleSidebar()}>Menu</button>

// Toggle specific sidebar ID
<button onClick={() => toggleSidebar('main-sidebar')}>Menu</button>
```

## API Reference

### `<Header />`

Top navigation bar showing user profile, notification bell, and hamburger menu (mobile).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `user` | `User` | - | User information object. |
| `notifications` | `NotificationItem[]` | `[]` | List of items for notification dropdown. |
| `sidebarId` | `string` | `'sidebar'` | ID used to toggle the sidebar. |
| `overlayId` | `string` | `'sidebar-overlay'` | ID used to toggle the overlay. |
| `notificationBell` | `ReactNode` | - | Custom component to replace the bell icon. |

### `<SharedSidebar />`

Responsive sidebar navigation with user profile section.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `user` | `User` | - | User information object. |
| `menuItems` | `MenuItem[]` | `[]` | Array of navigation items. |
| `onNavigate` | `(path: string) => void` | - | Callback when a menu item is clicked. |
| `onLogout` | `() => void` | - | Callback when logout button is clicked. |
| `roleLabel` | `string` | - | Text to display below user name (e.g. "Admin"). |
| `roleColor` | `string` | `'orange'` | Badge color (`teal`, `blue`, `orange`, `purple`, `green`). |
| `profilePath` | `string` | - | URL path for the user profile page. |
| `sidebarId` | `string` | `'sidebar'` | DOM ID for the sidebar container. |
| `overlayId` | `string` | `'sidebar-overlay'` | DOM ID for the backdrop overlay. |

### Type Definitions

**User**
```ts
interface User {
    firstName?: string;
    lastName?: string;
    pictureUrl?: string;
}
```

**MenuItem**
```ts
interface MenuItem {
    id: string;
    title: string;
    path: string;
    icon?: React.ReactNode;
}
```

**NotificationItem**
```ts
interface NotificationItem {
    id: string | number;
    title: string;
    description: string;
    date: string;
    type: 'reminder' | 'success' | 'info';
    isRead?: boolean;
}
```

## License

MIT