@xyz/navigation 1.1.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @xyz/navigation
 
-A flexible, context-aware navigation module for Nuxt 4 with zero performance overhead.
+A flexible, context-aware navigation module for Nuxt 4 with zero performance overhead and zero boilerplate.
 
 [![npm version](https://img.shields.io/npm/v/@xyz/navigation.svg)](https://www.npmjs.com/package/@xyz/navigation)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -11,8 +11,10 @@ A flexible, context-aware navigation module for Nuxt 4 with zero performance ove
 - 🔐 **Role-Based Filtering** - Show/hide items based on user roles
 - 🚩 **Feature Flags** - Conditional navigation based on enabled features
 - ⚡ **Zero Performance Overhead** - SSR-safe with reactive computed properties
-- 🎨 **Framework-Agnostic** - Works with any UI library (Nuxt UI, Tailwind, custom)
-- 🔧 **Flexible Configuration** - Inline or external config file
+- 🌍 **Auto Translation** - Automatic i18n integration with zero config
+- 🎨 **Normalized Structure** - Consistent API for all navigation sections
+- ✨ **Active States** - Automatic route matching and active states
+- 🔧 **Runtime Functions** - Use composables directly in config
 - 📘 **Full TypeScript Support** - Complete type safety and inference
 
 ## Installation
@@ -27,85 +29,50 @@ yarn add @xyz/navigation
 
 ## Quick Start
 
-### 1. Add Module to nuxt.config.ts
+### 1. Install & Enable
 
 ```typescript
+// nuxt.config.ts
 export default defineNuxtConfig({
-  modules: ['@xyz/navigation']
+  modules: ['@xyz/navigation']  // That's it!
 })
 ```
 
-### 2. Configure Navigation
+### 2. Create Unified Config
 
-**Option A: Inline Configuration** (Recommended for small configs)
-
-```typescript
-export default defineNuxtConfig({
-  modules: ['@xyz/navigation'],
-  
-  navigation: {
-    items: {
-      sections: {
-        main: [
-          { label: 'Dashboard', to: '{org}', icon: 'i-heroicons-home' },
-          { label: 'Projects', to: '{org}/projects' },
-          { label: 'Team', to: '{org}/team', features: ['team'] }
-        ]
-      }
-    },
-    
-    contextProvider: () => ({
-      user: useAuthUser(),
-      activeOrganization: useActiveOrg(),
-      features: useFeatureFlags()
-    })
-  }
-})
-```
-
-**Option B: External File** (Recommended for larger configs)
-
-Create `navigation.config.ts` at your project root:
+**navigation.config.ts** - Everything in one place:
 
 ```typescript
 export default {
+  // Module Options (optional, auto-detected)
+  translationResolver: () => useI18n().t,  // Auto-detects $t if using @nuxtjs/i18n
+  
+  // Navigation Sections
   sections: {
+    // Flat section (auto-normalized)
     main: [
-      {
-        label: 'Dashboard',
-        to: '{org}',
-        icon: 'i-heroicons-home'
-      },
-      {
-        label: 'Projects',
-        to: '{org}/projects',
-        icon: 'i-heroicons-folder'
-      },
-      {
-        label: 'Team',
-        to: '{org}/team',
-        icon: 'i-heroicons-user-group',
-        features: ['team'] // Only shown if 'team' feature is enabled
-      },
-      {
-        label: 'Settings',
-        to: '{org}/settings',
-        icon: 'i-heroicons-cog-6-tooth',
-        children: [
-          { label: 'General', to: '{org}/settings/general' },
-          { 
-            label: 'Billing', 
-            to: '{org}/settings/billing',
-            roles: ['admin', 'owner']  // Only for admins/owners
-          }
-        ]
-      }
+      { label: 'nav.dashboard', to: '/app', icon: 'i-lucide-home' },
+      { label: 'nav.projects', to: '/projects', icon: 'i-lucide-folder' }
     ],
     
-    profile: [
-      { label: 'My Profile', to: '/profile' },
-      { label: 'Preferences', to: '/preferences' }
-    ]
+    // Nested section with header
+    organization: {
+      header: (ctx) => ({
+        title: ctx.activeOrganization?.name ?? 'Personal',
+        avatar: { 
+          // ✅ Use composables in config - functions execute at runtime!
+          src: toAbsoluteUrl(ctx.activeOrganization?.logo || ''),
+          icon: 'i-lucide-building-2' 
+        }
+      }),
+      items: [
+        { label: 'nav.overview', to: '{org}' },
+        { label: 'nav.team', to: '{org}/team', features: ['team'] }
+      ],
+      children: [
+        { label: 'nav.settings', to: '{org}/settings' }
+      ]
+    }
   }
 }
 ```
@@ -113,422 +80,540 @@ export default {
 ### 3. Use in Components
 
 ```vue
-<script setup lang="ts">
+<script setup>
 import navigationConfig from '~/navigation.config'
 
 const { sections } = useNavigation(navigationConfig)
+// sections.value = { main: {...}, organization: {...} }
 </script>
 
 <template>
   <nav>
-    <NuxtLink
-      v-for="item in sections.main"
-      :key="item.label"
-      :to="item.to"
-      :class="{ 'active': item.active }"  <!-- Active state auto-computed! -->
-    >
-      {{ item.label }}
-    </NuxtLink>
+    <!-- All sections have normalized structure -->
+    <UNavigationMenu :items="sections.value.main.items" />
+    
+    <!-- Headers with runtime-resolved data -->
+    <div v-if="sections.value.organization.header">
+      <UAvatar :src="sections.value.organization.header.avatar.src" />
+      <h2>{{ sections.value.organization.header.title }}</h2>
+    </div>
+    
+    <!-- Items with auto-computed active states -->
+    <UNavigationMenu :items="sections.value.organization.items" />
   </nav>
 </template>
 ```
 
-## ✨ New in v1.1
+> **Note:** Labels are auto-translated if using `@nuxtjs/i18n` or a custom `translationResolver`.
+
+> **Note:** Labels are auto-translated if using `@nuxtjs/i18n` or a custom `translationResolver`.
+
+## Unified Configuration
 
-### Nested Section Structure
+**navigation.config.ts** is your single source of truth for both module options and navigation data.
 
-Organize navigation with logical grouping:
+### All-in-One Config
 
 ```typescript
+// navigation.config.ts
 export default {
+  // Module Options (build-time, optional)
+  translationResolver: () => useTranslations().t,
+  contextProvider: () => ({
+    user: useAuthUser(),
+    activeOrganization: useActiveOrg(),
+    features: useFeatureFlags()
+  }),
+  templates: {
+    workspace: (ctx) => ctx.workspaceSlug || 'default'
+  },
+  
+  // Navigation Sections (runtime)
   sections: {
-    // Flat sections (backward compatible)
     main: [...],
-    
-    // Nested sections with header, items, children, footer
+    organization: {...}
+  }
+}
+```
+
+### Override in nuxt.config.ts
+
+**nuxt.config.ts** can override individual module options:
+
+```typescript
+export default defineNuxtConfig({
+  navigation: {
+    translationResolver: () => customResolver()  // Overrides navigation.config.ts
+  }
+})
+```
+
+**Priority:** `nuxt.config.ts` > `navigation.config.ts` module options > `navigation.config.ts` sections
+
+## Core Concepts
+
+### Section Normalization
+
+All sections return a consistent structure:
+
+```typescript
+{
+  items?: NavigationMenuItem[]      // Main navigation items
+  header?: SectionHeader            // Optional header with title, avatar
+  children?: NavigationMenuItem[]   // Sub-navigation items
+  footer?: NavigationMenuItem[]     // Footer items
+}
+```
+
+**Flat sections** (arrays) are auto-wrapped:
+```typescript
+// Config
+sections: {
+  main: [{ label: 'Dashboard', to: '/app' }]
+}
+
+// Result
+sections.value.main = {
+  items: [{ label: 'Dashboard', to: '/app', active: true }],
+  header: undefined,
+  children: [],
+  footer: []
+}
+```
+
+### Runtime Functions in Config
+
+Config functions execute at runtime, so **composables work**:
+
+```typescript
+export default {
+  sections: {
     organization: {
       header: (ctx) => ({
-        title: ctx.activeOrganization?.name ?? 'Personal',
-        subtitle: ctx.activeOrganization?.slug,
-        avatar: { 
-          src: ctx.activeOrganization?.logo,
-          icon: 'i-lucide-building-2' 
+        title: ctx.activeOrganization?.name,
+        avatar: {
+          // ✅ Use composables directly!
+          src: toAbsoluteUrl(ctx.activeOrganization?.logo || '')
         }
       }),
-      items: [
-        { label: 'Overview', to: '{org}' },
-        { label: 'Team', to: '{org}/team' }
-      ],
-      children: [
-        { label: 'Settings', to: '{org}/settings' }
-      ],
-      footer: [
-        { label: 'Help', to: '/help' }
-      ]
+      items: [...]
     }
   }
 }
 ```
 
-Access nested sections:
+### Automatic Translation
 
-```vue
-<template>
-  <div>
-    <!-- Header -->
-    <div v-if="sections.organization.value.header">
-      <UAvatar :src="sections.organization.value.header.avatar.src" />
-      <h2>{{ sections.organization.value.header.title }}</h2>
-    </div>
-    
-    <!-- Items -->
-    <UNavigationMenu :items="sections.organization.value.items" />
-    
-    <!-- Children -->
-    <UNavigationMenu :items="sections.organization.value.children" />
-    
-    <!-- Footer -->
-    <UNavigationMenu :items="sections.organization.value.footer" />
-  </div>
-</template>
+**Zero config** with `@nuxtjs/i18n`:
+
+```typescript
+// navigation.config.ts - use translation keys
+export default {
+  sections: {
+    main: [
+      { label: 'nav.dashboard', to: '/app' },  // Auto-translated!
+      { label: 'nav.projects', to: '/projects' }
+    ]
+  }
+}
+
+// Component - translations applied automatically
+const { sections } = useNavigation(config)
+```
+
+**Custom translation resolver:**
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  navigation: {
+    translationResolver: () => {
+      const { t } = useTranslations()
+      return t
+    }
+  }
+})
 ```
 
 ### Automatic Active States
 
-Navigation items now include an `active` field automatically:
+Navigation items include `active` boolean based on current route:
 
 ```typescript
 {
   label: 'Blog',
   to: '/blog',
-  exact: false  // Active for /blog and /blog/*
+  exact: false,  // Active for /blog and /blog/*
+  active: true   // ✅ Auto-computed
 }
 ```
 
-All items have `active: boolean` computed based on current route:
+Use in templates:
 
 ```vue
 <template>
   <NuxtLink
-    v-for="item in sections.main.value"
+    v-for="item in sections.value.main.items"
     :to="item.to"
-    :class="{ 'font-bold': item.active }"  <!-- No manual route matching! -->
+    :class="{ 'font-bold': item.active }"
   >
     {{ item.label }}
   </NuxtLink>
 </template>
 ```
 
-### Translation Support
-
-Auto-translate labels with your i18n function:
-
-```typescript
-const { sections } = useNavigation(config, {
-  translationFn: (key) => $i18n.t(key)  // or t(key), or any translator
-})
-
-// All labels automatically translated!
-```
-
-In your config, use translation keys:
-
-```typescript
-export default {
-  sections: {
-    main: [
-      { label: 'nav.dashboard', to: '/app' },  // → Translated
-      { label: 'nav.projects', to: '/projects' }  // → Translated
-    ]
-  }
-}
-```
-
-## Template Strings
+## Template Variables
 
-Built-in template variables for dynamic path resolution:
+Built-in template variables for dynamic paths:
 
 | Template | Resolves To | Example |
 |----------|-------------|---------|
 | `{org}` | `/app` (personal) or `/app/:slug` (organization) | `{org}/projects` → `/app/acme/projects` |
-| `{slug}` | Current organization slug | `{slug}` → `acme`  |
+| `{slug}` | Current organization slug | `{slug}` → `acme` |
 | `{username}` | Current user's name or email | `/u/{username}` → `/u/john` |
 | `{user.id}` | Current user ID | `/users/{user.id}` → `/users/123` |
 
 ### Custom Templates
 
-Define custom template resolvers in `nuxt.config.ts`:
-
 ```typescript
+// nuxt.config.ts
 export default defineNuxtConfig({
-  modules: ['@xyz/navigation'],
-  
   navigation: {
     templates: {
-      '{workspace}': (ctx) => ctx.workspace?.slug ?? '',
-      '{tenant}': (ctx) => ctx.tenant?.id ?? 'default'
+      workspace: (ctx) => ctx.workspaceSlug || 'default',
+      tenant: (ctx) => ctx.activeTenant?.id || ''
     }
   }
 })
-```
 
-## Context Provider
-
-Define how navigation context is resolved:
-
-```typescript
-export default defineNuxtConfig({
-  modules: ['@xyz/navigation'],
-  
-  navigation: {
-    contextProvider: () => ({
-      // User information
-      user: useAuthUser(),
-      
-      // Active organization/tenant
-      activeOrganization: useActiveOrg(),
-      
-      // Feature flags
-      features: useFeatureFlags(),
-      
-      // Custom context
-      workspace: useWorkspace(),
-      permissions: usePermissions()
-    })
-  }
-})
+// Use in config
+{ label: 'Workspace', to: '/w/{workspace}/dashboard' }
 ```
 
-## Role-Based Access
+## Advanced Features
 
-Control navigation visibility based on user roles:
+### Feature Flags
 
 ```typescript
 {
-  label: 'Admin Panel',
-  to: '/admin',
-  roles: ['admin', 'superadmin']  // Only shown to admins
+  label: 'Analytics',
+  to: '/analytics',
+  features: ['analytics']  // Only shown if analytics feature enabled
 }
 ```
 
-## Feature Flags
-
-Show/hide items based on enabled features:
+Provide features via context:
 
 ```typescript
-{
-  label: 'Beta Feature',
-  to: '/beta',
-  features: ['betaAccess']  // Only shown if feature is enabled
-}
-
-// Multiple features (all must be enabled)
-{
-  label: 'Advanced Analytics',
-  to: '/analytics',
-  features: ['analytics', 'premium']
-}
+const { sections } = useNavigation(config, {
+  context: {
+    features: { analytics: true, team: false }
+  }
+})
 ```
 
-## Conditional Display
-
-Use custom conditions for complex logic:
+### Role-Based Filtering
 
 ```typescript
 {
-  label: 'Upgrade',
-  to: '/upgrade',
-  if: (ctx) => !ctx.user?.isPremium  // Show only to non-premium users
+  label: 'Admin Panel',
+  to: '/admin',
+  roles: ['admin', 'owner']  // Only for admins/owners
 }
 ```
 
-## Nested Navigation
+Configure role hierarchy:
 
-Create multi-level navigation structures:
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  navigation: {
+    config: {
+      roles: {
+        hierarchy: ['viewer', 'member', 'admin', 'owner'],
+        resolver: (user) => user?.role || 'viewer'
+      }
+    }
+  }
+})
+```
+
+### Nested Navigation
 
 ```typescript
 {
   label: 'Settings',
-  to: '{org}/settings',
+  to: '/settings',
   children: [
-    { label: 'General', to: '{org}/settings/general' },
-    { label: 'Team', to: '{org}/settings/team' },
-    { 
-      label: 'Billing', 
-      to: '{org}/settings/billing',
-      roles: ['admin']
-    }
+    { label: 'General', to: '/settings/general' },
+    { label: 'Billing', to: '/settings/billing', roles: ['admin'] }
   ]
 }
 ```
 
-## Sidebar State Management
-
-Built-in composable for managing sidebar state:
+### Custom Conditions
 
 ```typescript
-const sidebar = useSidebarState({
-  initialView: 'main',
-  persist: true  // Persists to localStorage
-})
-
-// Switch views
-await sidebar.switchToView('settings')
-
-// Go back
-sidebar.backToPrevious()
-
-// Reset to initial
-sidebar.resetView()
-
-// Check current view
-if (sidebar.isView('settings')) {
-  // ...
+{
+  label: 'Upgrade',
+  to: '/upgrade',
+  condition: (ctx) => !ctx.user?.isPremium  // Only for free users
 }
 ```
 
-## Framework Integration
-
-Works seamlessly with any UI library:
-
-### Nuxt UI
-
-```vue
-<template>
-  <UNavigationMenu :items="sections.main.value" orientation="vertical" />
-</template>
-```
-
-### Headless UI / Custom
-
-```vue
-<template>
-  <nav class="flex flex-col gap-2">
-    <NuxtLink
-      v-for="item in sections.main.value"
-      :key="item.label"
-      :to="item.to"
-      class="nav-link"
-    >
-      <Icon :name="item.icon" />
-      {{ item.label }}
-    </NuxtLink>
-  </nav>
-</template>
-```
-
 ## API Reference
 
 ### `useNavigation(config, options?)`
 
-Main composable for processing navigation configuration.
+Main composable for navigation.
 
 **Parameters:**
-- `config` - Navigation configuration object
-- `options` (optional) - Processing options
+- `config`: `NavigationConfig` - Navigation configuration object
+- `options?`: `UseNavigationOptions` - Optional configuration
 
 **Returns:**
 ```typescript
 {
-  sections: Record<string, ComputedRef<NavigationItem[]>>,
-  context: ComputedRef<NavigationContext>,
+  sections: ComputedRef<Record<string, ProcessedSection>>
+  context: ComputedRef<NavigationContext>
   refresh: () => void
 }
 ```
 
-### `useNavigationContext(override?)`
-
-Access current navigation context.
+**Options:**
 
-**Parameters:**
-- `override` (optional) - Override context values
-
-**Returns:**
 ```typescript
-ComputedRef<NavigationContext>
+interface UseNavigationOptions {
+  // Custom context provider
+  context?: NavigationContext | (() => NavigationContext)
+  
+  // Reactive updates (default: true)
+  reactive?: boolean
+  
+  // Custom template resolvers
+  templates?: Record<string, (ctx: NavigationContext) => string>
+  
+  // Override global translation function
+  translationFn?: (key: string) => string
+}
 ```
 
-### `useSidebarState(options?)`
-
-Manage sidebar view state.
+### Navigation Item Config
 
-**Parameters:**
 ```typescript
-{
-  initialView?: string,
-  persist?: boolean  // Default: false
+interface NavigationItemConfig {
+  label: string                              // Label (or translation key)
+  to?: string                                // Path (supports templates)
+  icon?: string                              // Icon name
+  exact?: boolean                            // Exact route matching (default: true)
+  
+  // Filtering
+  features?: string[]                        // Required feature flags
+  roles?: string[]                           // Required user roles
+  condition?: (ctx: NavigationContext) => boolean  // Custom condition
+  
+  // Nested navigation
+  children?: NavigationItemConfig[]
+  
+  // Custom handlers
+  onSelect?: (item: NavigationItemConfig) => void
+  
+  // Divider
+  divider?: boolean
+  
+  // Custom metadata
+  badge?: string | number
+  [key: string]: any                         // Additional custom fields
 }
 ```
 
-**Returns:**
+### Section Header
+
 ```typescript
-{
-  currentView: Ref<string>,
-  history: Ref<string[]>,
-  switchToView: (view: string) => Promise<void>,
-  backToPrevious: () => void,
-  resetView: () => void,
-  isView: (view: string) => boolean
+interface SectionHeader {
+  title?: string
+  subtitle?: string
+  avatar?: {
+    src?: string | null
+    icon?: string
+    fallback?: string
+  }
 }
 ```
 
-## TypeScript Support
+### Processed Section
 
-Full type safety with automatic inference:
+All sections return this normalized structure:
 
 ```typescript
-import type { NavigationConfig, NavigationItem } from '@xyz/navigation'
-
-const config: NavigationConfig = {
-  sections: {
-    main: [
-      // Fully typed items
-    ]
-  }
+interface ProcessedSection {
+  items?: NavigationMenuItem[]      // With active states
+  header?: SectionHeader
+  children?: NavigationMenuItem[]
+  footer?: NavigationMenuItem[]
 }
 ```
 
-## Examples
-
-### Multi-Tenant SaaS
+## Complete Example
 
 ```typescript
+// navigation.config.ts
 export default {
   sections: {
-    main: [
-      { label: 'Dashboard', to: '{org}' },
-      { label: 'Users', to: '{org}/users', roles: ['admin'] },
-      { label: 'Billing', to: '{org}/billing', features: ['billing'] }
+    // App navigation (flat)
+    app: [
+      { 
+        label: 'nav.dashboard', 
+        to: '/app', 
+        icon: 'i-lucide-home',
+        exact: true
+      },
+      { 
+        label: 'nav.projects', 
+        to: '/app/projects', 
+        icon: 'i-lucide-folder',
+        exact: false  // Active for /app/projects/*
+      }
+    ],
+    
+    // Organization navigation (nested)
+    organization: {
+      header: (ctx) => ({
+        title: ctx.activeOrganization?.name ?? 'Personal',
+        subtitle: ctx.activeOrganization?.slug,
+        avatar: {
+          src: useImageUrl().toAbsoluteUrl(
+            ctx.activeOrganization?.logo || ''
+          ),
+          icon: 'i-lucide-building-2',
+          fallback: ctx.activeOrganization?.name?.charAt(0)
+        }
+      }),
+      
+      items: [
+        { 
+          label: 'nav.overview', 
+          to: '{org}',
+          icon: 'i-lucide-layout-dashboard'
+        },
+        { 
+          label: 'nav.team', 
+          to: '{org}/team',
+          icon: 'i-lucide-users',
+          features: ['team']
+        },
+        {
+          label: 'nav.analytics',
+          to: '{org}/analytics',
+          icon: 'i-lucide-bar-chart',
+          features: ['analytics'],
+          roles: ['admin', 'owner']
+        }
+      ],
+      
+      children: [
+        {
+          label: 'nav.settings',
+          to: '{org}/settings',
+          icon: 'i-lucide-settings',
+          children: [
+            { label: 'nav.settings.general', to: '{org}/settings/general' },
+            { label: 'nav.settings.billing', to: '{org}/settings/billing', roles: ['owner'] }
+          ]
+        }
+      ],
+      
+      footer: [
+        { label: 'nav.help', to: '/help', icon: 'i-lucide-help-circle' },
+        { label: 'nav.docs', to: '/docs', icon: 'i-lucide-book' }
+      ]
+    },
+    
+    // Profile navigation
+    profile: [
+      { label: 'nav.profile.account', to: '/profile', icon: 'i-lucide-user' },
+      { label: 'nav.profile.preferences', to: '/preferences', icon: 'i-lucide-sliders' },
+      { divider: true },
+      { label: 'nav.profile.logout', icon: 'i-lucide-log-out', onSelect: () => logout() }
     ]
   }
 }
 ```
 
-### Context-Based Routing
+## Module Configuration
 
 ```typescript
-{
-  label: 'Profile',
-  to: (ctx) => ctx.activeOrganization 
-    ? `/${ctx.activeOrganization.slug}/profile`
-    : `/u/${ctx.user?.username}/profile`
-}
+// nuxt.config.ts
+export default defineNuxtConfig({
+  navigation: {
+    // Translation resolver (runtime)
+    translationResolver: () => {
+      const { t } = useTranslations()
+      return t
+    },
+    
+    // Custom templates
+    templates: {
+      workspace: (ctx) => ctx.workspaceSlug || 'default'
+    },
+    
+    // Context provider
+    contextProvider: (nuxtApp) => ({
+      user: nuxtApp.$auth?.user,
+      activeOrganization: nuxtApp.$org?.active,
+      features: nuxtApp.$features?.all()
+    }),
+    
+    // Role configuration
+    config: {
+      roles: {
+        hierarchy: ['viewer', 'member', 'admin', 'owner'],
+        resolver: (user) => user?.role || 'viewer'
+      }
+    }
+  }
+})
 ```
 
-### Progressive Disclosure
+## TypeScript
+
+Full type safety with inference:
 
 ```typescript
-{
-  label: 'Advanced',
-  to: '/advanced',
-  if: (ctx) => ctx.user?.role === 'developer' && ctx.features?.advanced
+import type { NavigationConfig, NavigationMenuItem } from '@xyz/navigation'
+
+const config: NavigationConfig = {
+  sections: {
+    main: [...]  // Fully typed
+  }
 }
+
+const { sections } = useNavigation(config)
+sections.value.main.items  // NavigationMenuItem[]
 ```
 
+## Migration Guide
+
+### From v1.0 to v1.2
+
+All sections now return normalized structure:
+
+```typescript
+// v1.0
+sections.value.main  // NavigationMenuItem[]
+sections.value.org   // { items, header, children, footer }
+
+// v1.2 (normalized)
+sections.value.main.items  // NavigationMenuItem[]
+sections.value.org.items   // NavigationMenuItem[]
+```
+
+Both flat and nested sections now have consistent API.
+
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
+MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions welcome! Please open an issue or PR.

package/dist/module.cjs

@@ -64,6 +64,47 @@ export {}
         contextProvider: options.contextProvider
       }
     );
+    let navigationConfigFromFile = null;
+    try {
+      const { existsSync } = await import('fs');
+      const navConfigPath = resolver.resolve(nuxt.options.rootDir, "navigation.config.ts");
+      if (existsSync(navConfigPath)) {
+        const configModule = await import(navConfigPath).catch(() => null);
+        navigationConfigFromFile = configModule?.default || null;
+        if (navigationConfigFromFile) {
+          const { sections, ...moduleOptionsFromFile } = navigationConfigFromFile;
+          if (Object.keys(moduleOptionsFromFile).length > 0) {
+            Object.assign(options, {
+              ...moduleOptionsFromFile,
+              ...options
+              // nuxt.config.ts takes precedence
+            });
+            if (nuxt.options.dev) {
+              console.log("[xyz-navigation] Loaded module options from navigation.config.ts");
+            }
+          }
+          if (!options.items && sections) {
+            options.items = { sections };
+          }
+        }
+        if (nuxt.options.dev) {
+          console.log("[xyz-navigation] Found navigation.config.ts at project root");
+        }
+      } else if (nuxt.options.dev) {
+        console.warn("[xyz-navigation] No navigation.config.ts found. Add it or use inline config in nuxt.config.ts");
+      }
+    } catch (error) {
+      if (nuxt.options.dev) {
+        console.warn("[xyz-navigation] Error loading navigation.config.ts:", error);
+      }
+    }
+    kit.addTemplate({
+      filename: "navigation-translation.mjs",
+      getContents: () => {
+        const resolverFn = options.translationResolver?.toString() || "null";
+        return `export const translationResolver = ${resolverFn}`;
+      }
+    });
     if (options.items) {
       kit.addTemplate({
         filename: "navigation-config.mjs",
@@ -75,29 +116,15 @@ export {}
         from: "#build/navigation-config.mjs"
       });
       if (nuxt.options.dev) {
-        console.log("[xyz-navigation] Using inline navigation configuration from nuxt.config.ts");
-      }
-    } else {
-      try {
-        const { existsSync } = await import('fs');
-        const navConfigPath = resolver.resolve(nuxt.options.rootDir, "navigation.config.ts");
-        if (existsSync(navConfigPath)) {
-          kit.addImports({
-            name: "default",
-            as: "navigationConfig",
-            from: navConfigPath
-          });
-          if (nuxt.options.dev) {
-            console.log("[xyz-navigation] Found navigation.config.ts at project root - auto-importing");
-          }
-        } else if (nuxt.options.dev) {
-          console.warn("[xyz-navigation] No navigation configuration found. Add navigation.config.ts or use inline config in nuxt.config.ts");
-        }
-      } catch (error) {
-        if (nuxt.options.dev) {
-          console.warn("[xyz-navigation] Error checking for navigation.config.ts:", error);
-        }
+        console.log("[xyz-navigation] Using navigation configuration from config files");
       }
+    } else if (navigationConfigFromFile) {
+      const navConfigPath = resolver.resolve(nuxt.options.rootDir, "navigation.config.ts");
+      kit.addImports({
+        name: "default",
+        as: "navigationConfig",
+        from: navConfigPath
+      });
     }
   }
 });

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0 || ^4.0.0"
   },
-  "version": "1.1.1",
+  "version": "1.2.0",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "2.0.0"

package/dist/module.mjs

@@ -61,6 +61,47 @@ export {}
         contextProvider: options.contextProvider
       }
     );
+    let navigationConfigFromFile = null;
+    try {
+      const { existsSync } = await import('fs');
+      const navConfigPath = resolver.resolve(nuxt.options.rootDir, "navigation.config.ts");
+      if (existsSync(navConfigPath)) {
+        const configModule = await import(navConfigPath).catch(() => null);
+        navigationConfigFromFile = configModule?.default || null;
+        if (navigationConfigFromFile) {
+          const { sections, ...moduleOptionsFromFile } = navigationConfigFromFile;
+          if (Object.keys(moduleOptionsFromFile).length > 0) {
+            Object.assign(options, {
+              ...moduleOptionsFromFile,
+              ...options
+              // nuxt.config.ts takes precedence
+            });
+            if (nuxt.options.dev) {
+              console.log("[xyz-navigation] Loaded module options from navigation.config.ts");
+            }
+          }
+          if (!options.items && sections) {
+            options.items = { sections };
+          }
+        }
+        if (nuxt.options.dev) {
+          console.log("[xyz-navigation] Found navigation.config.ts at project root");
+        }
+      } else if (nuxt.options.dev) {
+        console.warn("[xyz-navigation] No navigation.config.ts found. Add it or use inline config in nuxt.config.ts");
+      }
+    } catch (error) {
+      if (nuxt.options.dev) {
+        console.warn("[xyz-navigation] Error loading navigation.config.ts:", error);
+      }
+    }
+    addTemplate({
+      filename: "navigation-translation.mjs",
+      getContents: () => {
+        const resolverFn = options.translationResolver?.toString() || "null";
+        return `export const translationResolver = ${resolverFn}`;
+      }
+    });
     if (options.items) {
       addTemplate({
         filename: "navigation-config.mjs",
@@ -72,29 +113,15 @@ export {}
         from: "#build/navigation-config.mjs"
       });
       if (nuxt.options.dev) {
-        console.log("[xyz-navigation] Using inline navigation configuration from nuxt.config.ts");
-      }
-    } else {
-      try {
-        const { existsSync } = await import('fs');
-        const navConfigPath = resolver.resolve(nuxt.options.rootDir, "navigation.config.ts");
-        if (existsSync(navConfigPath)) {
-          addImports({
-            name: "default",
-            as: "navigationConfig",
-            from: navConfigPath
-          });
-          if (nuxt.options.dev) {
-            console.log("[xyz-navigation] Found navigation.config.ts at project root - auto-importing");
-          }
-        } else if (nuxt.options.dev) {
-          console.warn("[xyz-navigation] No navigation configuration found. Add navigation.config.ts or use inline config in nuxt.config.ts");
-        }
-      } catch (error) {
-        if (nuxt.options.dev) {
-          console.warn("[xyz-navigation] Error checking for navigation.config.ts:", error);
-        }
+        console.log("[xyz-navigation] Using navigation configuration from config files");
       }
+    } else if (navigationConfigFromFile) {
+      const navConfigPath = resolver.resolve(nuxt.options.rootDir, "navigation.config.ts");
+      addImports({
+        name: "default",
+        as: "navigationConfig",
+        from: navConfigPath
+      });
     }
   }
 });

package/dist/runtime/composables/useNavigation.js

@@ -29,13 +29,13 @@ export function useNavigation(config, options = {}) {
     templates,
     translationFn: translateFn
   };
-  const sections = Object.keys(config).reduce((acc, key) => {
+  const sectionsRaw = Object.keys(config).reduce((acc, key) => {
     const sectionKey = key;
     const section = config[sectionKey];
-    if (isNestedSection(section)) {
-      acc[sectionKey] = computed(() => {
-        const ctx = context.value;
-        const result = {};
+    acc[sectionKey] = computed(() => {
+      const ctx = context.value;
+      const result = {};
+      if (isNestedSection(section)) {
         if (section.header) {
           result.header = section.header(ctx);
         }
@@ -51,26 +51,34 @@ export function useNavigation(config, options = {}) {
           const footer = processNavigationItems(section.footer, ctx, processingOptions);
           result.footer = computeActiveStates(footer, ctx.route.path);
         }
-        return result;
-      });
-    } else {
-      acc[sectionKey] = computed(() => {
+      } else {
         const items = processNavigationItems(
           section,
-          context.value,
+          ctx,
           processingOptions
         );
-        return computeActiveStates(items, context.value.route.path);
-      });
-    }
+        result.items = computeActiveStates(items, ctx.route.path);
+        result.header = void 0;
+        result.children = [];
+        result.footer = [];
+      }
+      return result;
+    });
     return acc;
   }, {});
+  const sections = computed(() => {
+    return Object.keys(sectionsRaw).reduce((acc, key) => {
+      acc[key] = sectionsRaw[key].value;
+      return acc;
+    }, {});
+  });
   let refreshTrigger = 0;
   const refresh = () => {
     refreshTrigger++;
   };
   return {
     sections,
+    // Unwrapped: sections.app.items (no .value)
     context,
     refresh
   };

package/dist/runtime/plugins/navigation.js

@@ -37,7 +37,6 @@ export default defineNuxtPlugin(async (nuxtApp) => {
       navigation: {
         context: providedContext,
         translate: translationFn
-        // Make translation available globally
       }
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyz/navigation",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Context-aware, type-safe navigation for multi-tenant Nuxt applications",
   "type": "module",
   "exports": {
@@ -39,9 +39,22 @@
     "multi-tenant",
     "saas",
     "dynamic-routing",
-    "typescript"
+    "typescript",
+    "zero-config",
+    "i18n",
+    "role-based",
+    "feature-flags"
   ],
+  "author": "xyz",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xyz/xyz-navigation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xyz/xyz-navigation/issues"
+  },
+  "homepage": "https://github.com/xyz/xyz-navigation#readme",
   "dependencies": {
     "defu": "^6.1.4"
   },