@xyz/navigation 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,422 @@
+# @xyz/navigation
+
+A flexible, context-aware navigation module for Nuxt 4 with zero performance overhead.
+
+[![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)
+
+## Features
+
+- 🎯 **Context-Aware Paths** - Dynamic path resolution using templates (`{org}`, `{slug}`, `{username}`)
+- 🔐 **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
+- 📘 **Full TypeScript Support** - Complete type safety and inference
+
+## Installation
+
+```bash
+pnpm add @xyz/navigation
+# or
+npm install @xyz/navigation
+# or
+yarn add @xyz/navigation
+```
+
+## Quick Start
+
+### 1. Add Module to nuxt.config.ts
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@xyz/navigation']
+})
+```
+
+### 2. Configure Navigation
+
+**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:
+
+```typescript
+export default {
+  sections: {
+    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
+          }
+        ]
+      }
+    ],
+    
+    profile: [
+      { label: 'My Profile', to: '/profile' },
+      { label: 'Preferences', to: '/preferences' }
+    ]
+  }
+}
+```
+
+### 3. Use in Components
+
+```vue
+<script setup lang="ts">
+import navigationConfig from '~/navigation.config'
+
+const { sections } = useNavigation(navigationConfig)
+</script>
+
+<template>
+  <nav>
+    <NuxtLink
+      v-for="item in sections.main"
+      :key="item.label"
+      :to="item.to"
+    >
+      {{ item.label }}
+    </NuxtLink>
+  </nav>
+</template>
+```
+
+## Template Strings
+
+Built-in template variables for dynamic path resolution:
+
+| Template | Resolves To | Example |
+|----------|-------------|---------|
+| `{org}` | `/app` (personal) or `/app/:slug` (organization) | `{org}/projects` → `/app/acme/projects` |
+| `{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
+export default defineNuxtConfig({
+  modules: ['@xyz/navigation'],
+  
+  navigation: {
+    templates: {
+      '{workspace}': (ctx) => ctx.workspace?.slug ?? '',
+      '{tenant}': (ctx) => ctx.tenant?.id ?? 'default'
+    }
+  }
+})
+```
+
+## 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()
+    })
+  }
+})
+```
+
+## Role-Based Access
+
+Control navigation visibility based on user roles:
+
+```typescript
+{
+  label: 'Admin Panel',
+  to: '/admin',
+  roles: ['admin', 'superadmin']  // Only shown to admins
+}
+```
+
+## Feature Flags
+
+Show/hide items based on enabled features:
+
+```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']
+}
+```
+
+## Conditional Display
+
+Use custom conditions for complex logic:
+
+```typescript
+{
+  label: 'Upgrade',
+  to: '/upgrade',
+  if: (ctx) => !ctx.user?.isPremium  // Show only to non-premium users
+}
+```
+
+## Nested Navigation
+
+Create multi-level navigation structures:
+
+```typescript
+{
+  label: 'Settings',
+  to: '{org}/settings',
+  children: [
+    { label: 'General', to: '{org}/settings/general' },
+    { label: 'Team', to: '{org}/settings/team' },
+    { 
+      label: 'Billing', 
+      to: '{org}/settings/billing',
+      roles: ['admin']
+    }
+  ]
+}
+```
+
+## Sidebar State Management
+
+Built-in composable for managing sidebar state:
+
+```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')) {
+  // ...
+}
+```
+
+## 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.
+
+**Parameters:**
+- `config` - Navigation configuration object
+- `options` (optional) - Processing options
+
+**Returns:**
+```typescript
+{
+  sections: Record<string, ComputedRef<NavigationItem[]>>,
+  context: ComputedRef<NavigationContext>,
+  refresh: () => void
+}
+```
+
+### `useNavigationContext(override?)`
+
+Access current navigation context.
+
+**Parameters:**
+- `override` (optional) - Override context values
+
+**Returns:**
+```typescript
+ComputedRef<NavigationContext>
+```
+
+### `useSidebarState(options?)`
+
+Manage sidebar view state.
+
+**Parameters:**
+```typescript
+{
+  initialView?: string,
+  persist?: boolean  // Default: false
+}
+```
+
+**Returns:**
+```typescript
+{
+  currentView: Ref<string>,
+  history: Ref<string[]>,
+  switchToView: (view: string) => Promise<void>,
+  backToPrevious: () => void,
+  resetView: () => void,
+  isView: (view: string) => boolean
+}
+```
+
+## TypeScript Support
+
+Full type safety with automatic inference:
+
+```typescript
+import type { NavigationConfig, NavigationItem } from '@xyz/navigation'
+
+const config: NavigationConfig = {
+  sections: {
+    main: [
+      // Fully typed items
+    ]
+  }
+}
+```
+
+## Examples
+
+### Multi-Tenant SaaS
+
+```typescript
+export default {
+  sections: {
+    main: [
+      { label: 'Dashboard', to: '{org}' },
+      { label: 'Users', to: '{org}/users', roles: ['admin'] },
+      { label: 'Billing', to: '{org}/billing', features: ['billing'] }
+    ]
+  }
+}
+```
+
+### Context-Based Routing
+
+```typescript
+{
+  label: 'Profile',
+  to: (ctx) => ctx.activeOrganization 
+    ? `/${ctx.activeOrganization.slug}/profile`
+    : `/u/${ctx.user?.username}/profile`
+}
+```
+
+### Progressive Disclosure
+
+```typescript
+{
+  label: 'Advanced',
+  to: '/advanced',
+  if: (ctx) => ctx.user?.role === 'developer' && ctx.features?.advanced
+}
+```
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/module.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+const kit = require('@nuxt/kit');
+const defu = require('defu');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const module$1 = kit.defineNuxtModule({
+  meta: {
+    name: "xyz-navigation",
+    configKey: "navigation",
+    compatibility: {
+      nuxt: "^3.0.0 || ^4.0.0"
+    }
+  },
+  defaults: {
+    enabled: true
+  },
+  async setup(options, nuxt) {
+    if (options.enabled === false) {
+      return;
+    }
+    const resolver = kit.createResolver((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('module.cjs', document.baseURI).href)));
+    nuxt.options.alias["#xyz-navigation"] = resolver.resolve("./runtime");
+    kit.addImports([
+      {
+        name: "useNavigation",
+        from: resolver.resolve("./runtime/composables/useNavigation")
+      },
+      {
+        name: "useNavigationContext",
+        from: resolver.resolve("./runtime/composables/useNavigationContext")
+      },
+      {
+        name: "useSidebarState",
+        from: resolver.resolve("./runtime/composables/useSidebarState")
+      }
+    ]);
+    kit.addPlugin(resolver.resolve("./runtime/plugins/navigation"));
+    kit.addTemplate({
+      filename: "types/xyz-navigation.d.ts",
+      getContents: () => `
+declare module '#app' {
+  interface NuxtApp {
+    $navigation: {
+      context: import('vue').ComputedRef<import('#xyz-navigation/types').NavigationContext>
+    }
+  }
+}
+
+export {}
+      `.trim()
+    });
+    nuxt.options.runtimeConfig.public.navigation = defu.defu(
+      nuxt.options.runtimeConfig.public.navigation,
+      {
+        enabled: options.enabled,
+        contextProvider: options.contextProvider
+      }
+    );
+    if (options.items) {
+      kit.addTemplate({
+        filename: "navigation-config.mjs",
+        getContents: () => `export default ${JSON.stringify(options.items, null, 2)}`
+      });
+      kit.addImports({
+        name: "default",
+        as: "navigationConfig",
+        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);
+        }
+      }
+    }
+  }
+});
+
+module.exports = module$1;

package/dist/module.d.cts

@@ -0,0 +1,8 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { ModuleOptions } from '../dist/runtime/types/config.js';
+export { ModuleOptions } from '../dist/runtime/types/config.js';
+export * from '../dist/runtime/types/index.js';
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.d.mts

@@ -0,0 +1,8 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { ModuleOptions } from '../dist/runtime/types/config.js';
+export { ModuleOptions } from '../dist/runtime/types/config.js';
+export * from '../dist/runtime/types/index.js';
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.d.ts

@@ -0,0 +1,8 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { ModuleOptions } from '../dist/runtime/types/config.js';
+export { ModuleOptions } from '../dist/runtime/types/config.js';
+export * from '../dist/runtime/types/index.js';
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "xyz-navigation",
+  "configKey": "navigation",
+  "compatibility": {
+    "nuxt": "^3.0.0 || ^4.0.0"
+  },
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "2.0.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,95 @@
+import { defineNuxtModule, createResolver, addImports, addPlugin, addTemplate } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "xyz-navigation",
+    configKey: "navigation",
+    compatibility: {
+      nuxt: "^3.0.0 || ^4.0.0"
+    }
+  },
+  defaults: {
+    enabled: true
+  },
+  async setup(options, nuxt) {
+    if (options.enabled === false) {
+      return;
+    }
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.alias["#xyz-navigation"] = resolver.resolve("./runtime");
+    addImports([
+      {
+        name: "useNavigation",
+        from: resolver.resolve("./runtime/composables/useNavigation")
+      },
+      {
+        name: "useNavigationContext",
+        from: resolver.resolve("./runtime/composables/useNavigationContext")
+      },
+      {
+        name: "useSidebarState",
+        from: resolver.resolve("./runtime/composables/useSidebarState")
+      }
+    ]);
+    addPlugin(resolver.resolve("./runtime/plugins/navigation"));
+    addTemplate({
+      filename: "types/xyz-navigation.d.ts",
+      getContents: () => `
+declare module '#app' {
+  interface NuxtApp {
+    $navigation: {
+      context: import('vue').ComputedRef<import('#xyz-navigation/types').NavigationContext>
+    }
+  }
+}
+
+export {}
+      `.trim()
+    });
+    nuxt.options.runtimeConfig.public.navigation = defu(
+      nuxt.options.runtimeConfig.public.navigation,
+      {
+        enabled: options.enabled,
+        contextProvider: options.contextProvider
+      }
+    );
+    if (options.items) {
+      addTemplate({
+        filename: "navigation-config.mjs",
+        getContents: () => `export default ${JSON.stringify(options.items, null, 2)}`
+      });
+      addImports({
+        name: "default",
+        as: "navigationConfig",
+        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);
+        }
+      }
+    }
+  }
+});
+
+export { module as default };

package/dist/runtime/composables/useNavigation.d.ts

@@ -0,0 +1,19 @@
+import type { NavigationConfig, NavigationResult, UseNavigationOptions } from '../types/index.js';
+/**
+ * Main navigation composable
+ * Processes navigation configuration and returns resolved items
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   app: [
+ *     { label: 'Dashboard', to: '{org}', icon: 'i-lucide-layout-dashboard' },
+ *     { label: 'Settings', to: '{org}/settings', icon: 'i-lucide-settings' }
+ *   ]
+ * }
+ *
+ * const { sections } = useNavigation(config)
+ * // sections.app.value → processed items
+ * ```
+ */
+export declare function useNavigation<T extends NavigationConfig>(config: T, options?: UseNavigationOptions): NavigationResult<T>;