@logickernel/bridge 0.5.0 → 0.7.0

package/README.md

@@ -180,6 +180,168 @@ export const middlewareConfig = {
 }
 ```
 
+#### Layout Components
+
+The bridge library provides ready-to-use layout components with built-in navigation connected to the Core of the Kernel.
+
+```typescript
+// app/app/layout.tsx (or your app layout)
+"use client"
+
+import { AppLayout, type User } from "@logickernel/bridge/next/components"
+import { useSession } from "next-auth/react"
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  const { data: session } = useSession()
+  
+  if (!session?.user) {
+    return <>{children}</>
+  }
+
+  const user: User = {
+    name: session.user.name || null,
+    email: session.user.email || "",
+    image: session.user.image || null,
+  }
+
+  return (
+    <AppLayout
+      user={user}
+      organizationId={organizationId} // Optional: Current organization ID
+      apiBaseUrl={apiBaseUrl}         // Optional: API base URL for navigation
+    >
+      {children}
+    </AppLayout>
+  )
+}
+```
+
+**For Server Components:**
+
+```typescript
+// app/app/layout.tsx
+import { AppLayout, type User } from "@logickernel/bridge/next/components"
+import { redirect } from "next/navigation"
+import { auth } from "@/lib/next-auth" // or your NextAuth setup
+
+export default async function Layout({
+  children,
+  params,
+}: {
+  children: React.ReactNode
+  params: Promise<{ organization_id?: string }>
+}) {
+  const session = await auth()
+  
+  if (!session?.user) {
+    redirect("/auth/signin")
+  }
+
+  const { organization_id } = await params
+
+  const user: User = {
+    name: session.user.name || null,
+    email: session.user.email || "",
+    image: session.user.image || null,
+  }
+
+  return (
+    <AppLayout
+      user={user}
+      organizationId={organization_id}
+      apiBaseUrl={process.env.AUTH_URL}
+    >
+      {children}
+    </AppLayout>
+  )
+}
+```
+
+**Note:** You can also use `getSession()` from `@logickernel/bridge/next` instead of NextAuth's `auth()` function. Both will work, but NextAuth's `auth()` is recommended if you're using NextAuth v5.
+
+**Features:**
+- ✅ Built-in sidebar navigation with organization switcher
+- ✅ User menu with sign-out
+- ✅ Responsive design (mobile/desktop)
+- ✅ Automatic navigation loading from your API
+- ✅ No component passing required - UI components are included in the library
+- ✅ Consistent UI across all microfrontends using the bridge
+
+The `AppLayout` component automatically:
+- Loads navigation items from `/api/navigation/[organization_id]` endpoint
+- Displays organizations the user belongs to
+- Handles organization switching
+- Provides user profile menu with sign-out
+
+**Required API Endpoint:**
+
+The navigation requires an endpoint at `/api/navigation/[organization_id]` that returns:
+```typescript
+{
+  items: NavigationItem[],
+  organizations: NavigationOrganization[]
+}
+```
+
+**Type Definitions:**
+```typescript
+interface NavigationItem {
+  title: string
+  url?: string        // If missing, item is treated as a section label
+  icon?: string       // Icon name (mapped using getIconComponent)
+  isActive?: boolean  // Whether the item should be highlighted
+  items?: {           // Sub-items for collapsible navigation
+    title: string
+    url: string
+  }[]
+}
+
+interface NavigationOrganization {
+  id: string
+  name: string
+  logo?: string       // Icon name for the organization logo
+  plan?: string       // Optional plan/badge text
+}
+```
+
+**Example Response:**
+```json
+{
+  "items": [
+    {
+      "title": "Dashboard",
+      "url": "/app/{organizationId}/home",
+      "icon": "LayoutDashboard"
+    },
+    {
+      "title": "Team",
+      "icon": "Users"  // Section label (no URL)
+    },
+    {
+      "title": "Members",
+      "url": "/app/{organizationId}/members",
+      "icon": "User",
+      "items": [
+        {
+          "title": "All Members",
+          "url": "/app/{organizationId}/members"
+        }
+      ]
+    }
+  ],
+  "organizations": [
+    {
+      "id": "org-123",
+      "name": "Acme Corp",
+      "logo": "Building",
+      "plan": "Pro"
+    }
+  ]
+}
+```
+
+**Note:** The `{organizationId}` placeholder in URLs will be automatically replaced with the current organization ID. The endpoint should be protected and only return data the current user has access to.
+
 ## API Reference
 
 ### Core Exports (`@logickernel/bridge`)
@@ -210,6 +372,28 @@ export const middlewareConfig = {
 | `hasRequiredRole(orgId, roles)` | Check if user has required roles (user ID determined from session token) |
 | `createProxyHandler(options)` | Create a middleware/proxy handler |
 
+### Layout Components (`@logickernel/bridge/next/components`)
+
+| Export | Description |
+|--------|-------------|
+| `AppLayout` | Main layout component with sidebar navigation |
+| `AppSidebar` | Sidebar component (used internally by AppLayout) |
+| `NavMain` | Main navigation component (used internally) |
+| `NavUser` | User menu component (used internally) |
+| `TeamSwitcher` | Organization switcher component (used internally) |
+| `useNavigation` | Hook to fetch navigation items from API |
+| `getIconComponent` | Utility to get icon component from icon name |
+
+**AppLayout Props:**
+```typescript
+interface AppLayoutProps {
+  user: User                    // User information (name, email, image)
+  organizationId?: string       // Optional: Current organization ID
+  apiBaseUrl?: string           // Optional: API base URL for navigation
+  children: React.ReactNode     // Page content
+}
+```
+
 ### Types
 
 ```typescript
@@ -231,6 +415,12 @@ import type {
   PageAuthOptions,
   PageAuthResult,
 } from "@logickernel/bridge/next"
+
+import type {
+  User,
+  NavigationItem,
+  NavigationOrganization,
+} from "@logickernel/bridge/next/components"
 ```
 
 ## Architecture
@@ -249,7 +439,15 @@ bridge/
 │       ├── session.ts # Session utilities
 │       ├── api.ts    # API route utilities
 │       ├── page.ts   # Page utilities
-│       └── proxy.ts  # Middleware/proxy utilities
+│       ├── proxy.ts  # Middleware/proxy utilities
+│       └── components/
+│           ├── app-layout.tsx    # Main layout component
+│           ├── app-sidebar.tsx   # Sidebar component
+│           ├── nav-main.tsx      # Navigation component
+│           ├── nav-user.tsx      # User menu component
+│           ├── team-switcher.tsx # Organization switcher
+│           ├── use-navigation.ts # Navigation hook
+│           └── ui/               # Internal UI components (shadcn)
 ```
 
 ## Development