@logickernel/frame 0.1.0

package/README.md

@@ -0,0 +1,461 @@
+# @logickernel/frame
+
+Shared navigation and layout components for microfrontends and core applications.
+
+## Overview
+
+This library provides reusable navigation and layout components that can be shared across multiple microfrontends. The library supports both props-based and API-based navigation configuration with role-based filtering.
+
+## Features
+
+- **Shared Layout Components**: AppSidebar, NavMain, NavUser, TeamSwitcher
+- **Dual Navigation Modes**: 
+  - Props-based: Pass navigation items as props
+  - API-based: Fetch navigation from API with role-based filtering
+- **Role-Based Filtering**: Server-side filtering of navigation items based on user roles
+- **Type-Safe**: Full TypeScript support with exported types
+- **Framework Agnostic**: Works with any React framework (Next.js, Remix, etc.)
+
+## Installation
+
+```bash
+npm install @logickernel/frame
+# or
+yarn add @logickernel/frame
+# or
+pnpm add @logickernel/frame
+```
+
+### Peer Dependencies
+
+This library requires the following peer dependencies to be installed in your project:
+
+```bash
+npm install react react-dom lucide-react
+npm install @radix-ui/react-avatar @radix-ui/react-collapsible @radix-ui/react-dropdown-menu @radix-ui/react-slot @radix-ui/react-tooltip
+```
+
+**For Next.js users**, you'll also need:
+```bash
+npm install next next-auth
+```
+
+### UI Components Requirement
+
+This library uses shadcn/ui components that must be available in your application. You need to have the following components installed and accessible via the `@/components/ui/*` path alias:
+
+- `@/components/ui/sidebar`
+- `@/components/ui/avatar`
+- `@/components/ui/dropdown-menu`
+- `@/components/ui/collapsible`
+
+To install these components, use shadcn/ui:
+
+```bash
+npx shadcn@latest add sidebar avatar dropdown-menu collapsible
+```
+
+Make sure your `tsconfig.json` has the path alias configured:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+## Usage
+
+### Framework Adapter
+
+The library is framework-agnostic and requires a framework adapter to be provided. For Next.js applications, use the provided adapter:
+
+```typescript
+import { AppSidebar, createNextJSAdapter } from "@logickernel/frame"
+import type { User, Organization } from "@logickernel/frame"
+
+// Create the adapter (do this once, can be reused)
+const adapter = createNextJSAdapter()
+```
+
+For other frameworks, you'll need to implement the `FrameworkAdapter` interface (see Types section).
+
+### Props Mode vs API Mode
+
+The component automatically detects which mode to use:
+
+- **Props Mode**: Provide `data` → organizations and navigation come from props
+- **API Mode**: Omit `data` → organizations and navigation come from the API
+
+### Props Mode
+
+Pass a `data` object containing organizations and navigation items. The `{organizationId}` placeholder in URLs is automatically replaced.
+
+```typescript
+import { AppSidebar, createNextJSAdapter } 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",
+  image: null,
+}
+
+const data: SidebarData = {
+  organizations: [
+    { id: "org-1", name: "Acme Corp", plan: "Pro" },
+    { id: "org-2", name: "Another Org", plan: "Free" },
+  ],
+  navigationItems: [
+    { title: "Organization", icon: GalleryVerticalEnd },
+    { title: "Home", url: "/app/{organizationId}/home", icon: Home },
+    { title: "Members", url: "/app/{organizationId}/members", icon: Users },
+  ],
+}
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <AppSidebar user={user} adapter={adapter} data={data} />
+      <main>{children}</main>
+    </>
+  )
+}
+```
+
+### API Mode
+
+Omit `data` — the component fetches organizations and navigation from the API.
+
+```typescript
+import { AppSidebar, createNextJSAdapter } from "@logickernel/frame"
+
+const adapter = createNextJSAdapter()
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <AppSidebar
+        user={user}
+        adapter={adapter}
+        // apiBaseUrl="/api" // Optional, defaults to "/api"
+      />
+      <main>{children}</main>
+    </>
+  )
+}
+```
+
+The API endpoint (`/api/navigation/[organization_id]`) should:
+- Authenticate the user via shared cookies
+- Fetch user roles in the organization
+- Filter navigation items based on role requirements
+- Return filtered navigation items and optionally organizations
+
+**Expected API Response:**
+```json
+{
+  "items": [
+    {
+      "title": "Organization",
+      "icon": "GalleryVerticalEnd"
+    },
+    {
+      "title": "Home",
+      "url": "/app/{organizationId}/home",
+      "icon": "Home"
+    }
+  ],
+  "organizationId": "org-1",
+  "organizations": [
+    {
+      "id": "org-1",
+      "name": "Acme Corp",
+      "plan": "Pro"
+    },
+    {
+      "id": "org-2",
+      "name": "Another Org",
+      "plan": "Free"
+    }
+  ]
+}
+```
+
+**Note:** In API mode, the `organizations` field is **required** in the API response. The API determines which organizations the user belongs to. The `logo` field in organizations is optional - if omitted, a default icon will be used.
+
+## Components
+
+### AppSidebar
+
+Main sidebar component that combines TeamSwitcher, NavMain, and NavUser.
+
+**Props:**
+- `user: User` - User information (name, email, image)
+- `adapter: FrameworkAdapter` - Framework adapter (use `createNextJSAdapter()` for Next.js)
+- `data?: SidebarData` - Sidebar data with organizations and navigation items (props mode)
+- `organizationId?: string` - Current organization ID (optional, extracted from pathname)
+- `apiBaseUrl?: string` - Custom API base URL (API mode only, defaults to "/api")
+- All other props from `Sidebar` component
+
+**Mode Detection:**
+- If `data` is provided → Props Mode
+- If `data` is omitted → API Mode
+
+### NavMain
+
+Renders navigation menu items with support for groups and nested items.
+
+**Props:**
+- `items: NavigationItem[]` - Array of navigation items
+- `adapter: FrameworkAdapter` - Framework adapter
+
+### NavUser
+
+User profile dropdown with sign-out functionality.
+
+**Props:**
+- `user: User` - User information
+- `adapter: FrameworkAdapter` - Framework adapter
+
+### TeamSwitcher
+
+Organization switcher dropdown.
+
+**Props:**
+- `teams: Organization[]` - List of organizations
+- `organizationId?: string` - Current organization ID
+- `adapter: FrameworkAdapter` - Framework adapter
+
+## Hooks
+
+### useNavigation
+
+Hook to fetch navigation items and organizations from API.
+
+```typescript
+import { useNavigation } from "@logickernel/frame"
+
+const { items, organizations, loading, error } = useNavigation({
+  organizationId: "org-1",
+  apiBaseUrl: "/api",
+  enabled: true,
+})
+```
+
+**Options:**
+- `organizationId?: string` - Organization ID to fetch navigation for
+- `apiBaseUrl?: string` - API base URL (default: "/api")
+- `enabled?: boolean` - Enable/disable fetching (default: true)
+
+**Returns:**
+- `items: NavigationItem[]` - Navigation items
+- `organizations: Organization[]` - Organizations (if provided by API)
+- `loading: boolean` - Loading state
+- `error: Error | null` - Error state
+
+## Types
+
+### NavigationItem
+
+```typescript
+interface NavigationItem {
+  title: string
+  url?: string
+  icon?: string | LucideIcon
+  isActive?: boolean
+  items?: {
+    title: string
+    url: string
+  }[]
+}
+```
+
+### User
+
+```typescript
+interface User {
+  name: string | null
+  email: string
+  image: string | null
+}
+```
+
+### Organization
+
+```typescript
+interface Organization {
+  id: string
+  name: string
+  logo?: LucideIcon | React.ComponentType<{ className?: string }>
+  plan?: string
+}
+```
+
+### SidebarData
+
+```typescript
+interface SidebarData {
+  organizations: Organization[]
+  navigationItems: NavigationItem[]
+}
+```
+
+### NavigationConfig
+
+```typescript
+interface NavigationConfig {
+  items: NavigationItem[]
+  organizationId?: string
+}
+```
+
+### FrameworkAdapter
+
+```typescript
+interface FrameworkAdapter {
+  usePathname: () => string
+  useRouter: () => Router
+  Link: ComponentType<LinkProps>
+  signOut?: (options?: { redirect?: boolean }) => Promise<void>
+}
+```
+
+### Router
+
+```typescript
+interface Router {
+  push: (path: string) => void
+  refresh?: () => void
+}
+```
+
+### LinkProps
+
+```typescript
+interface LinkProps {
+  href: string
+  children: ReactNode
+  className?: string
+}
+```
+
+## Utilities
+
+### getIconComponent
+
+Utility to convert icon name strings to Lucide React icon components.
+
+```typescript
+import { getIconComponent } from "@logickernel/frame"
+
+const Icon = getIconComponent("Home") // Returns Home icon component
+```
+
+## Adapters
+
+### createNextJSAdapter
+
+Creates a Next.js adapter for the framework. Use this when using the library in a Next.js application.
+
+```typescript
+import { createNextJSAdapter } from "@logickernel/frame"
+
+const adapter = createNextJSAdapter()
+```
+
+**Note**: This requires `next` and `next-auth` to be installed.
+
+### Custom Adapters
+
+For other frameworks, implement the `FrameworkAdapter` interface:
+
+```typescript
+import type { FrameworkAdapter } from "@logickernel/frame"
+
+const myAdapter: FrameworkAdapter = {
+  usePathname: () => {
+    // Return current pathname
+    return window.location.pathname
+  },
+  useRouter: () => ({
+    push: (path: string) => {
+      // Navigate to path
+      window.history.pushState({}, "", path)
+    },
+    refresh: () => {
+      // Refresh the page
+      window.location.reload()
+    },
+  }),
+  Link: ({ href, children, className }) => (
+    <a href={href} className={className}>
+      {children}
+    </a>
+  ),
+  signOut: async () => {
+    // Handle sign out
+  },
+}
+```
+
+## Role-Based Filtering
+
+Navigation items can specify `requiredRoles` in the service layer configuration. Items are filtered server-side based on the user's roles in the organization.
+
+Example API-side configuration:
+```typescript
+{
+  title: "Settings",
+  url: "/app/{organizationId}/settings",
+  icon: "Settings",
+  requiredRoles: ["organization.owner", "organization.editor"]
+}
+```
+
+## Cross-Origin Setup (Microfrontends)
+
+If your microfrontends are on different domains, configure CORS in your navigation API:
+
+```typescript
+// In your navigation API route
+const response = NextResponse.json(data)
+response.headers.set("Access-Control-Allow-Origin", "https://microfrontend.example.com")
+response.headers.set("Access-Control-Allow-Credentials", "true")
+return response
+```
+
+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"
+/>
+```
+
+## Development
+
+```bash
+# Build the library
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Type check
+npm run type-check
+```
+
+## License
+
+MIT

package/dist/adapters/nextjs.js

@@ -0,0 +1,31 @@
+'use strict';
+
+var Link = require('next/link');
+var navigation = require('next/navigation');
+var react = require('next-auth/react');
+var jsxRuntime = require('react/jsx-runtime');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Link__default = /*#__PURE__*/_interopDefault(Link);
+
+// src/adapters/nextjs.tsx
+function createNextJSAdapter() {
+  const NextJSLink = ({ href, children, className }) => /* @__PURE__ */ jsxRuntime.jsx(Link__default.default, { href, className, children });
+  return {
+    usePathname: navigation.usePathname,
+    useRouter: () => {
+      const router = navigation.useRouter();
+      return {
+        push: (path) => router.push(path),
+        refresh: () => router.refresh()
+      };
+    },
+    Link: NextJSLink,
+    signOut: react.signOut
+  };
+}
+
+exports.createNextJSAdapter = createNextJSAdapter;
+//# sourceMappingURL=nextjs.js.map
+//# sourceMappingURL=nextjs.js.map

package/dist/adapters/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/nextjs.tsx"],"names":["jsx","Link","usePathname","useRouter","signOut"],"mappings":";;;;;;;;;;;;AAiBO,SAAS,mBAAA,GAAwC;AACtD,EAAA,MAAM,UAAA,GAA6C,CAAC,EAAE,IAAA,EAAM,QAAA,EAAU,SAAA,EAAU,qBAC9EA,cAAA,CAACC,qBAAA,EAAA,EAAK,IAAA,EAAY,SAAA,EACf,QAAA,EACH,CAAA;AAGF,EAAA,OAAO;AAAA,iBACLC,sBAAA;AAAA,IACA,WAAW,MAAM;AACf,MAAA,MAAM,SAASC,oBAAA,EAAU;AACzB,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,CAAC,IAAA,KAAiB,MAAA,CAAO,KAAK,IAAI,CAAA;AAAA,QACxC,OAAA,EAAS,MAAM,MAAA,CAAO,OAAA;AAAQ,OAChC;AAAA,IACF,CAAA;AAAA,IACA,IAAA,EAAM,UAAA;AAAA,aACNC;AAAA,GACF;AACF","file":"nextjs.js","sourcesContent":["/**\n * Next.js adapter for @logickernel/frame\n * Provides Next.js-specific implementations of FrameworkAdapter\n */\n\nimport * as React from \"react\"\nimport Link from \"next/link\"\nimport { usePathname, useRouter } from \"next/navigation\"\nimport { signOut } from \"next-auth/react\"\nimport type { FrameworkAdapter, LinkProps } from \"../types\"\n\n/**\n * Creates a Next.js adapter for the framework\n * Use this when using @logickernel/frame in a Next.js application\n * \n * Note: This requires Next.js and next-auth to be installed\n */\nexport function createNextJSAdapter(): FrameworkAdapter {\n  const NextJSLink: React.ComponentType<LinkProps> = ({ href, children, className }) => (\n    <Link href={href} className={className}>\n      {children}\n    </Link>\n  )\n\n  return {\n    usePathname,\n    useRouter: () => {\n      const router = useRouter()\n      return {\n        push: (path: string) => router.push(path),\n        refresh: () => router.refresh(),\n      }\n    },\n    Link: NextJSLink,\n    signOut: signOut as FrameworkAdapter[\"signOut\"],\n  }\n}\n\n"]}

package/dist/adapters/nextjs.mjs

@@ -0,0 +1,25 @@
+import Link from 'next/link';
+import { usePathname, useRouter } from 'next/navigation';
+import { signOut } from 'next-auth/react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/adapters/nextjs.tsx
+function createNextJSAdapter() {
+  const NextJSLink = ({ href, children, className }) => /* @__PURE__ */ jsx(Link, { href, className, children });
+  return {
+    usePathname,
+    useRouter: () => {
+      const router = useRouter();
+      return {
+        push: (path) => router.push(path),
+        refresh: () => router.refresh()
+      };
+    },
+    Link: NextJSLink,
+    signOut
+  };
+}
+
+export { createNextJSAdapter };
+//# sourceMappingURL=nextjs.mjs.map
+//# sourceMappingURL=nextjs.mjs.map

package/dist/adapters/nextjs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/nextjs.tsx"],"names":[],"mappings":";;;;;;AAiBO,SAAS,mBAAA,GAAwC;AACtD,EAAA,MAAM,UAAA,GAA6C,CAAC,EAAE,IAAA,EAAM,QAAA,EAAU,SAAA,EAAU,qBAC9E,GAAA,CAAC,IAAA,EAAA,EAAK,IAAA,EAAY,SAAA,EACf,QAAA,EACH,CAAA;AAGF,EAAA,OAAO;AAAA,IACL,WAAA;AAAA,IACA,WAAW,MAAM;AACf,MAAA,MAAM,SAAS,SAAA,EAAU;AACzB,MAAA,OAAO;AAAA,QACL,IAAA,EAAM,CAAC,IAAA,KAAiB,MAAA,CAAO,KAAK,IAAI,CAAA;AAAA,QACxC,OAAA,EAAS,MAAM,MAAA,CAAO,OAAA;AAAQ,OAChC;AAAA,IACF,CAAA;AAAA,IACA,IAAA,EAAM,UAAA;AAAA,IACN;AAAA,GACF;AACF","file":"nextjs.mjs","sourcesContent":["/**\n * Next.js adapter for @logickernel/frame\n * Provides Next.js-specific implementations of FrameworkAdapter\n */\n\nimport * as React from \"react\"\nimport Link from \"next/link\"\nimport { usePathname, useRouter } from \"next/navigation\"\nimport { signOut } from \"next-auth/react\"\nimport type { FrameworkAdapter, LinkProps } from \"../types\"\n\n/**\n * Creates a Next.js adapter for the framework\n * Use this when using @logickernel/frame in a Next.js application\n * \n * Note: This requires Next.js and next-auth to be installed\n */\nexport function createNextJSAdapter(): FrameworkAdapter {\n  const NextJSLink: React.ComponentType<LinkProps> = ({ href, children, className }) => (\n    <Link href={href} className={className}>\n      {children}\n    </Link>\n  )\n\n  return {\n    usePathname,\n    useRouter: () => {\n      const router = useRouter()\n      return {\n        push: (path: string) => router.push(path),\n        refresh: () => router.refresh(),\n      }\n    },\n    Link: NextJSLink,\n    signOut: signOut as FrameworkAdapter[\"signOut\"],\n  }\n}\n\n"]}