@kt-components/layout-header-sidebar 1.0.0 → 1.0.1

package/README.md

@@ -1,59 +1,226 @@
 # KT Components Layout Header Sidebar
 
-Reusable Header and Sidebar layout components for Next.js applications, pre-styled with Tailwind CSS.
+Reusable Header and Sidebar layout components designed for Next.js applications, pre-styled with Tailwind CSS. Perfect for government or enterprise back-office applications.
+
+## 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+
-- TailwindCSS 3 (or just use the pre-built styles)
+- 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
+## Setup (Important!)
 
-Enable the styles in your project. Add this line to your **root layout** file (e.g., `app/layout.tsx` or `pages/_app.tsx`):
+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
+## Usage Guide
 
-### Header with Notifications
+### 1. Basic Layout Setup
 
-Now supports a built-in notification dropdown.
+Combine `Header` and `SharedSidebar` to create a standard dashboard layout.
 
 ```tsx
-import { Header, NotificationItem } from '@kt-components/layout-header-sidebar';
+// 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();
 
-function App() {
+    // 1. Define User Data
     const user = {
-        firstName: 'สมชาย',
-        lastName: 'ใจดี',
-        pictureUrl: 'https://example.com/avatar.jpg'
+        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>
+    );
+}
 ```
 
-### Sidebar Component
+### 2. Using Notifications
+
+The Header component accepts a `notifications` array to display a dropdown.
 
 ```tsx
-import { SharedSidebar, MenuItem } from '@kt-components/layout-header-sidebar';
-// ...
+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} 
+/>
 ```
 
-### Toggle Sidebar Programmatically
+### 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;
+}
 ```
 
-## Props
+## License
 
-See TypeScript definitions for full prop list.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kt-components/layout-header-sidebar",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "Reusable Header and Sidebar components for React/Next.js projects",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",