@logickernel/frame 0.7.0 → 0.8.2

package/README.md

@@ -72,17 +72,30 @@ Make sure your `tsconfig.json` has the path alias configured:
 
 ### Framework Adapter
 
-The library is framework-agnostic and requires a framework adapter to be provided. For Next.js applications, use the provided adapter:
+The library is framework-agnostic and requires a framework adapter to be provided. For Next.js applications, use the provided adapter hook:
 
 ```typescript
-import { AppSidebar, createNextJSAdapter } from "@logickernel/frame"
-import type { User, Organization } from "@logickernel/frame"
+"use client" // Required: adapter hook must be used in a Client Component
 
-// Create the adapter (do this once, can be reused)
-const adapter = createNextJSAdapter()
+import { AppLayout, useNextJSAdapter } from "@logickernel/frame"
+import type { User, SidebarData } from "@logickernel/frame"
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  // Create the adapter using the hook (must be called in a Client Component)
+  const adapter = useNextJSAdapter()
+  
+  return (
+    <AppLayout adapter={adapter} user={user} data={sidebarData}>
+      {children}
+    </AppLayout>
+  )
+}
 ```
 
-For other frameworks, you'll need to implement the `FrameworkAdapter` interface (see Types section).
+**Important:** 
+- The `adapter` prop is now **required** (previously optional)
+- `useNextJSAdapter()` must be called in a **Client Component** (add `"use client"` directive)
+- For other frameworks, you'll need to implement the `FrameworkAdapter` interface (see Types section)
 
 ### Props Mode vs API Mode
 
@@ -96,12 +109,12 @@ The component automatically detects which mode to use:
 Pass a `data` object containing organizations and navigation items. The `{organizationId}` placeholder in URLs is automatically replaced.
 
 ```typescript
-import { AppSidebar, createNextJSAdapter } from "@logickernel/frame"
+"use client" // Required: adapter hook must be used in a Client Component
+
+import { AppLayout, useNextJSAdapter } from "@logickernel/frame"
 import { Home, Users, GalleryVerticalEnd } from "lucide-react"
 import type { SidebarData, User } from "@logickernel/frame"
 
-const adapter = createNextJSAdapter()
-
 const user: User = {
   name: "John Doe",
   email: "john@example.com",
@@ -121,11 +134,12 @@ const data: SidebarData = {
 }
 
 export default function Layout({ children }: { children: React.ReactNode }) {
+  const adapter = useNextJSAdapter()
+  
   return (
-    <>
-      <AppSidebar user={user} adapter={adapter} data={data} />
-      <main>{children}</main>
-    </>
+    <AppLayout adapter={adapter} user={user} data={data}>
+      {children}
+    </AppLayout>
   )
 }
 ```
@@ -135,31 +149,24 @@ export default function Layout({ children }: { children: React.ReactNode }) {
 **Important:** Always import sidebar components (`SidebarProvider`, `SidebarTrigger`, `SidebarInset`, etc.) from `@logickernel/frame`, not from your local `@/components/ui/sidebar`. This ensures all components share the same React Context.
 
 ```typescript
+"use client" // Required: adapter hook must be used in a Client Component
+
 import {
-  AppSidebar,
-  SidebarProvider,
-  SidebarTrigger,
-  SidebarInset,
-  createNextJSAdapter,
+  AppLayout,
+  useNextJSAdapter,
 } from "@logickernel/frame"
 import type { User, SidebarData } from "@logickernel/frame"
 
-const adapter = createNextJSAdapter()
 const user: User = { name: "John Doe", email: "john@example.com", image: null }
 const data: SidebarData = { /* ... */ }
 
 export default function Layout({ children }: { children: React.ReactNode }) {
+  const adapter = useNextJSAdapter()
+  
   return (
-    <SidebarProvider>
-      <AppSidebar user={user} adapter={adapter} data={data} />
-      <SidebarInset>
-        <header className="flex h-16 shrink-0 items-center gap-2 border-b px-4">
-          <SidebarTrigger />
-          <h1>My App</h1>
-        </header>
-        <main className="flex flex-1 flex-col gap-4 p-4">{children}</main>
-      </SidebarInset>
-    </SidebarProvider>
+    <AppLayout adapter={adapter} user={user} data={data}>
+      {children}
+    </AppLayout>
   )
 }
 ```
@@ -177,11 +184,12 @@ export default function Layout({ children }: { children: React.ReactNode }) {
 Omit `data` — the component fetches organizations and navigation from the API.
 
 ```typescript
-import { AppSidebar, createNextJSAdapter } from "@logickernel/frame"
+"use client" // Required: adapter hook must be used in a Client Component
 
-const adapter = createNextJSAdapter()
+import { AppLayout, useNextJSAdapter } from "@logickernel/frame"
 
 export default function Layout({ children }: { children: React.ReactNode }) {
+  const adapter = useNextJSAdapter()
   return (
     <>
       <AppSidebar
@@ -479,9 +487,7 @@ For cross-origin requests, use the full API URL:
 ```typescript
 <AppSidebar
   user={user}
-  organizations={organizations}
   organizationId={orgId}
-  useApiNavigation={true}
   apiBaseUrl="https://kernel.example.com/api"
 />
 ```

package/dist/index.d.mts

@@ -88,8 +88,8 @@ interface FrameworkAdapter {
  */
 interface AppSidebarProps$1 {
     user: User;
-    /** Optional adapter - if not provided, Next.js defaults will be used */
-    adapter?: FrameworkAdapter;
+    /** Framework adapter - required for framework-agnostic operation */
+    adapter: FrameworkAdapter;
     /** Sidebar data containing organizations and navigation items (props mode) */
     data?: SidebarData;
     /** Current organization ID (optional, can be extracted from pathname) */
@@ -103,20 +103,14 @@ interface AppSidebarProps$1 {
 interface AppLayoutProps {
     /** User data for sidebar */
     user: User;
-    /** Optional adapter - if not provided, Next.js defaults will be used */
-    adapter?: FrameworkAdapter;
+    /** Framework adapter - required for framework-agnostic operation */
+    adapter: FrameworkAdapter;
     /** Sidebar data containing organizations and navigation items (props mode) */
     data?: SidebarData;
     /** Current organization ID (optional, can be extracted from pathname) */
     organizationId?: string;
     /** Custom API base URL (API mode only, defaults to "/api" which constructs "/api/navigation/{organizationId}") */
     apiBaseUrl?: string;
-    /** Enable API mode - library will fetch navigation from API */
-    useApiNavigation?: boolean;
-    /** Custom header content (breadcrumbs, actions, etc.) */
-    headerContent?: ReactNode;
-    /** Show/hide default header (default: true) */
-    showHeader?: boolean;
     /** Children to render in the main content area */
     children: ReactNode;
 }
@@ -151,8 +145,8 @@ declare const SidebarInset: React$1.ForwardRefExoticComponent<Omit<React$1.Detai
  */
 interface AppSidebarProps extends React$1.ComponentProps<typeof Sidebar> {
     user: User;
-    /** Optional adapter - if not provided, Next.js defaults will be used */
-    adapter?: FrameworkAdapter;
+    /** Framework adapter - required for framework-agnostic operation */
+    adapter: FrameworkAdapter;
     /** Sidebar data containing organizations and navigation items (props mode) */
     data?: SidebarData;
     /** Current organization ID (optional, can be extracted from pathname) */
@@ -160,7 +154,7 @@ interface AppSidebarProps extends React$1.ComponentProps<typeof Sidebar> {
     /** Custom API base URL (API mode only, defaults to "/api") */
     apiBaseUrl?: string;
 }
-declare function AppSidebar({ user, adapter: externalAdapter, data, organizationId, apiBaseUrl, ...props }: AppSidebarProps): react_jsx_runtime.JSX.Element;
+declare function AppSidebar({ user, adapter, data, organizationId, apiBaseUrl, ...props }: AppSidebarProps): react_jsx_runtime.JSX.Element;
 
 /**
  * High-level layout component that handles the entire sidebar + content layout structure.
@@ -168,18 +162,45 @@ declare function AppSidebar({ user, adapter: externalAdapter, data, organization
  * This component wraps AppSidebar and SidebarInset in SidebarProvider and provides
  * a default header with sidebar trigger. It handles all layout concerns internally.
  *
+ * Navigation mode is determined automatically:
+ * - If `data` prop is provided, uses props mode
+ * - If `data` is not provided, automatically uses API mode (fetches from API)
+ *
  * @example
  * ```tsx
- * <AppLayout
- *   user={user}
- *   useApiNavigation={true}
- *   headerContent={<Breadcrumb>...</Breadcrumb>}
- * >
- *   {children}
- * </AppLayout>
+ * // In Next.js
+ * import { useNextJSAdapter } from "@logickernel/frame"
+ *
+ * function Layout({ children }) {
+ *   const adapter = useNextJSAdapter()
+ *   return (
+ *     <AppLayout adapter={adapter} user={user} data={sidebarData}>
+ *       {children}
+ *     </AppLayout>
+ *   )
+ * }
+ *
+ * // In React Router
+ * import { useLocation, useNavigate } from "react-router-dom"
+ *
+ * function Layout({ children }) {
+ *   const location = useLocation()
+ *   const navigate = useNavigate()
+ *   const adapter = useMemo(() => ({
+ *     usePathname: () => location.pathname,
+ *     useRouter: () => ({ push: navigate }),
+ *     Link: ({ href, children }) => <Link to={href}>{children}</Link>,
+ *   }), [location.pathname, navigate])
+ *
+ *   return (
+ *     <AppLayout adapter={adapter} user={user} data={sidebarData}>
+ *       {children}
+ *     </AppLayout>
+ *   )
+ * }
  * ```
  */
-declare function AppLayout({ user, adapter, data, organizationId, apiBaseUrl, useApiNavigation, headerContent, showHeader, children, }: AppLayoutProps): react_jsx_runtime.JSX.Element;
+declare function AppLayout({ user, adapter, data, organizationId, apiBaseUrl, children, }: AppLayoutProps): react_jsx_runtime.JSX.Element;
 
 interface NavMainProps {
     items: NavigationItem[];
@@ -233,16 +254,24 @@ declare function useNavigation({ organizationId, apiBaseUrl, enabled, }?: UseNav
 declare function getIconComponent(icon?: string | LucideIcon): LucideIcon | undefined;
 
 /**
- * Next.js adapter for @logickernel/frame
- * Provides Next.js-specific implementations of FrameworkAdapter
- */
-
-/**
- * Creates a Next.js adapter for the framework
+ * Creates a Next.js adapter hook for the framework
  * Use this when using @logickernel/frame in a Next.js application
  *
  * Note: This requires Next.js and next-auth to be installed
+ * This hook MUST be called in a Client Component ("use client")
+ *
+ * @example
+ * ```tsx
+ * "use client"
+ *
+ * import { AppLayout, useNextJSAdapter } from "@logickernel/frame"
+ *
+ * function MyLayout({ children }) {
+ *   const adapter = useNextJSAdapter()
+ *   return <AppLayout adapter={adapter} user={user}>{children}</AppLayout>
+ * }
+ * ```
  */
-declare function createNextJSAdapter(): FrameworkAdapter;
+declare function useNextJSAdapter(): FrameworkAdapter;
 
-export { AppLayout, type AppLayoutProps, AppSidebar, type AppSidebarProps$1 as AppSidebarProps, type FrameworkAdapter, type LinkProps, NavMain, NavUser, type NavigationConfig, type NavigationItem, type Organization, type Router, type SidebarData, SidebarInset, SidebarProvider, SidebarTrigger, TeamSwitcher, type User, createNextJSAdapter, getIconComponent, useNavigation, useSidebar };
+export { AppLayout, type AppLayoutProps, AppSidebar, type AppSidebarProps$1 as AppSidebarProps, type FrameworkAdapter, type LinkProps, NavMain, NavUser, type NavigationConfig, type NavigationItem, type Organization, type Router, type SidebarData, SidebarInset, SidebarProvider, SidebarTrigger, TeamSwitcher, type User, getIconComponent, useNavigation, useNextJSAdapter, useSidebar };

package/dist/index.d.ts

@@ -88,8 +88,8 @@ interface FrameworkAdapter {
  */
 interface AppSidebarProps$1 {
     user: User;
-    /** Optional adapter - if not provided, Next.js defaults will be used */
-    adapter?: FrameworkAdapter;
+    /** Framework adapter - required for framework-agnostic operation */
+    adapter: FrameworkAdapter;
     /** Sidebar data containing organizations and navigation items (props mode) */
     data?: SidebarData;
     /** Current organization ID (optional, can be extracted from pathname) */
@@ -103,20 +103,14 @@ interface AppSidebarProps$1 {
 interface AppLayoutProps {
     /** User data for sidebar */
     user: User;
-    /** Optional adapter - if not provided, Next.js defaults will be used */
-    adapter?: FrameworkAdapter;
+    /** Framework adapter - required for framework-agnostic operation */
+    adapter: FrameworkAdapter;
     /** Sidebar data containing organizations and navigation items (props mode) */
     data?: SidebarData;
     /** Current organization ID (optional, can be extracted from pathname) */
     organizationId?: string;
     /** Custom API base URL (API mode only, defaults to "/api" which constructs "/api/navigation/{organizationId}") */
     apiBaseUrl?: string;
-    /** Enable API mode - library will fetch navigation from API */
-    useApiNavigation?: boolean;
-    /** Custom header content (breadcrumbs, actions, etc.) */
-    headerContent?: ReactNode;
-    /** Show/hide default header (default: true) */
-    showHeader?: boolean;
     /** Children to render in the main content area */
     children: ReactNode;
 }
@@ -151,8 +145,8 @@ declare const SidebarInset: React$1.ForwardRefExoticComponent<Omit<React$1.Detai
  */
 interface AppSidebarProps extends React$1.ComponentProps<typeof Sidebar> {
     user: User;
-    /** Optional adapter - if not provided, Next.js defaults will be used */
-    adapter?: FrameworkAdapter;
+    /** Framework adapter - required for framework-agnostic operation */
+    adapter: FrameworkAdapter;
     /** Sidebar data containing organizations and navigation items (props mode) */
     data?: SidebarData;
     /** Current organization ID (optional, can be extracted from pathname) */
@@ -160,7 +154,7 @@ interface AppSidebarProps extends React$1.ComponentProps<typeof Sidebar> {
     /** Custom API base URL (API mode only, defaults to "/api") */
     apiBaseUrl?: string;
 }
-declare function AppSidebar({ user, adapter: externalAdapter, data, organizationId, apiBaseUrl, ...props }: AppSidebarProps): react_jsx_runtime.JSX.Element;
+declare function AppSidebar({ user, adapter, data, organizationId, apiBaseUrl, ...props }: AppSidebarProps): react_jsx_runtime.JSX.Element;
 
 /**
  * High-level layout component that handles the entire sidebar + content layout structure.
@@ -168,18 +162,45 @@ declare function AppSidebar({ user, adapter: externalAdapter, data, organization
  * This component wraps AppSidebar and SidebarInset in SidebarProvider and provides
  * a default header with sidebar trigger. It handles all layout concerns internally.
  *
+ * Navigation mode is determined automatically:
+ * - If `data` prop is provided, uses props mode
+ * - If `data` is not provided, automatically uses API mode (fetches from API)
+ *
  * @example
  * ```tsx
- * <AppLayout
- *   user={user}
- *   useApiNavigation={true}
- *   headerContent={<Breadcrumb>...</Breadcrumb>}
- * >
- *   {children}
- * </AppLayout>
+ * // In Next.js
+ * import { useNextJSAdapter } from "@logickernel/frame"
+ *
+ * function Layout({ children }) {
+ *   const adapter = useNextJSAdapter()
+ *   return (
+ *     <AppLayout adapter={adapter} user={user} data={sidebarData}>
+ *       {children}
+ *     </AppLayout>
+ *   )
+ * }
+ *
+ * // In React Router
+ * import { useLocation, useNavigate } from "react-router-dom"
+ *
+ * function Layout({ children }) {
+ *   const location = useLocation()
+ *   const navigate = useNavigate()
+ *   const adapter = useMemo(() => ({
+ *     usePathname: () => location.pathname,
+ *     useRouter: () => ({ push: navigate }),
+ *     Link: ({ href, children }) => <Link to={href}>{children}</Link>,
+ *   }), [location.pathname, navigate])
+ *
+ *   return (
+ *     <AppLayout adapter={adapter} user={user} data={sidebarData}>
+ *       {children}
+ *     </AppLayout>
+ *   )
+ * }
  * ```
  */
-declare function AppLayout({ user, adapter, data, organizationId, apiBaseUrl, useApiNavigation, headerContent, showHeader, children, }: AppLayoutProps): react_jsx_runtime.JSX.Element;
+declare function AppLayout({ user, adapter, data, organizationId, apiBaseUrl, children, }: AppLayoutProps): react_jsx_runtime.JSX.Element;
 
 interface NavMainProps {
     items: NavigationItem[];
@@ -233,16 +254,24 @@ declare function useNavigation({ organizationId, apiBaseUrl, enabled, }?: UseNav
 declare function getIconComponent(icon?: string | LucideIcon): LucideIcon | undefined;
 
 /**
- * Next.js adapter for @logickernel/frame
- * Provides Next.js-specific implementations of FrameworkAdapter
- */
-
-/**
- * Creates a Next.js adapter for the framework
+ * Creates a Next.js adapter hook for the framework
  * Use this when using @logickernel/frame in a Next.js application
  *
  * Note: This requires Next.js and next-auth to be installed
+ * This hook MUST be called in a Client Component ("use client")
+ *
+ * @example
+ * ```tsx
+ * "use client"
+ *
+ * import { AppLayout, useNextJSAdapter } from "@logickernel/frame"
+ *
+ * function MyLayout({ children }) {
+ *   const adapter = useNextJSAdapter()
+ *   return <AppLayout adapter={adapter} user={user}>{children}</AppLayout>
+ * }
+ * ```
  */
-declare function createNextJSAdapter(): FrameworkAdapter;
+declare function useNextJSAdapter(): FrameworkAdapter;
 
-export { AppLayout, type AppLayoutProps, AppSidebar, type AppSidebarProps$1 as AppSidebarProps, type FrameworkAdapter, type LinkProps, NavMain, NavUser, type NavigationConfig, type NavigationItem, type Organization, type Router, type SidebarData, SidebarInset, SidebarProvider, SidebarTrigger, TeamSwitcher, type User, createNextJSAdapter, getIconComponent, useNavigation, useSidebar };
+export { AppLayout, type AppLayoutProps, AppSidebar, type AppSidebarProps$1 as AppSidebarProps, type FrameworkAdapter, type LinkProps, NavMain, NavUser, type NavigationConfig, type NavigationItem, type Organization, type Router, type SidebarData, SidebarInset, SidebarProvider, SidebarTrigger, TeamSwitcher, type User, getIconComponent, useNavigation, useNextJSAdapter, useSidebar };