@xyz/navigation 1.0.0

package/dist/runtime/composables/useNavigation.js

@@ -0,0 +1,40 @@
+import { computed, isRef, unref } from "vue";
+import { useNavigationContext } from "./useNavigationContext.js";
+import { processNavigationItems } from "../utils/processor.js";
+import { createTemplateRegistry } from "../config/default-templates.js";
+import { validateNavigationConfig } from "../utils/validators.js";
+export function useNavigation(config, options = {}) {
+  if (import.meta.dev) {
+    validateNavigationConfig(config);
+  }
+  const baseContext = useNavigationContext();
+  const context = computed(() => {
+    const base = baseContext.value;
+    if (options.context) {
+      const customContext = isRef(options.context) ? unref(options.context) : typeof options.context === "function" ? options.context() : options.context;
+      return { ...base, ...customContext };
+    }
+    return base;
+  });
+  const templates = createTemplateRegistry(options.templates);
+  const processingOptions = {
+    templates
+  };
+  const sections = Object.keys(config).reduce((acc, key) => {
+    const sectionKey = key;
+    acc[sectionKey] = computed(() => {
+      const items = config[sectionKey];
+      return processNavigationItems(items, context.value, processingOptions);
+    });
+    return acc;
+  }, {});
+  let refreshTrigger = 0;
+  const refresh = () => {
+    refreshTrigger++;
+  };
+  return {
+    sections,
+    context,
+    refresh
+  };
+}

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

@@ -0,0 +1,10 @@
+import { type ComputedRef } from 'vue';
+import type { NavigationContext } from '../types/index.js';
+/**
+ * Get or create navigation context
+ * This composable provides reactive access to navigation context
+ *
+ * @param override - Optional context override
+ * @returns Computed navigation context
+ */
+export declare function useNavigationContext(override?: Partial<NavigationContext>): ComputedRef<NavigationContext>;

package/dist/runtime/composables/useNavigationContext.js

@@ -0,0 +1,19 @@
+import { computed } from "vue";
+import { useRoute, useNuxtApp } from "#app";
+export function useNavigationContext(override) {
+  const route = useRoute();
+  const nuxtApp = useNuxtApp();
+  return computed(() => {
+    const providedContext = nuxtApp.$navigation?.context || {
+      user: null,
+      activeOrganization: null,
+      features: {}
+    };
+    const baseContext = {
+      ...providedContext,
+      route,
+      ...override
+    };
+    return baseContext;
+  });
+}

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

@@ -0,0 +1,17 @@
+import type { SidebarState, SidebarStateOptions } from '../types/index.js';
+/**
+ * Sidebar state management composable
+ * Manages multi-view sidebar state with history tracking and optional persistence
+ *
+ * @example
+ * ```ts
+ * const sidebar = useSidebarState({
+ *   initialView: 'app',
+ *   persist: true
+ * })
+ *
+ * await sidebar.switchToView('settings')
+ * sidebar.backToPrevious()
+ * ```
+ */
+export declare function useSidebarState(options?: SidebarStateOptions): SidebarState;

package/dist/runtime/composables/useSidebarState.js

@@ -0,0 +1,69 @@
+import { ref, computed, watch } from "vue";
+export function useSidebarState(options = {}) {
+  const {
+    initialView = "default",
+    persist = false,
+    onBeforeSwitch,
+    onAfterSwitch
+  } = options;
+  const storageKey = typeof persist === "object" && persist.key ? persist.key : "nuxt-navigation:sidebar-view";
+  const storage = typeof persist === "object" && persist.storage ? persist.storage : "localStorage";
+  const getPersistedView = () => {
+    if (!persist || typeof window === "undefined") return initialView;
+    try {
+      const stored = storage === "localStorage" ? localStorage.getItem(storageKey) : sessionStorage.getItem(storageKey);
+      return stored || initialView;
+    } catch {
+      return initialView;
+    }
+  };
+  const currentView = ref(getPersistedView());
+  const historyStack = ref([currentView.value]);
+  if (persist && typeof window !== "undefined") {
+    watch(currentView, (newView) => {
+      try {
+        const storageAPI = storage === "localStorage" ? localStorage : sessionStorage;
+        storageAPI.setItem(storageKey, newView);
+      } catch (error) {
+        console.warn("[xyz-navigation] Failed to persist sidebar view:", error);
+      }
+    });
+  }
+  const switchToView = async (view) => {
+    if (currentView.value === view) return;
+    if (onBeforeSwitch) {
+      const canSwitch = await onBeforeSwitch(currentView.value, view);
+      if (canSwitch === false) return;
+    }
+    currentView.value = view;
+    historyStack.value.push(view);
+    if (onAfterSwitch) {
+      onAfterSwitch(view);
+    }
+  };
+  const backToPrevious = () => {
+    if (historyStack.value.length <= 1) return;
+    historyStack.value.pop();
+    const previousView = historyStack.value[historyStack.value.length - 1];
+    currentView.value = previousView;
+    if (onAfterSwitch) {
+      onAfterSwitch(previousView);
+    }
+  };
+  const resetView = () => {
+    currentView.value = initialView;
+    historyStack.value = [initialView];
+    if (onAfterSwitch) {
+      onAfterSwitch(initialView);
+    }
+  };
+  const isView = (view) => computed(() => currentView.value === view);
+  return {
+    currentView,
+    history: computed(() => [...historyStack.value]),
+    switchToView,
+    backToPrevious,
+    resetView,
+    isView
+  };
+}

package/dist/runtime/config/default-templates.d.ts

@@ -0,0 +1,9 @@
+import type { NavigationContext, TemplateResolver } from '../types/index.js';
+/**
+ * Built-in template resolvers
+ */
+export declare const defaultTemplates: TemplateResolver[];
+/**
+ * Create template resolver registry from built-in and custom templates
+ */
+export declare function createTemplateRegistry(customTemplates?: Record<string, (ctx: NavigationContext) => string>): TemplateResolver[];

package/dist/runtime/config/default-templates.js

@@ -0,0 +1,31 @@
+export const defaultTemplates = [
+  {
+    pattern: "{org}",
+    resolve: (ctx) => ctx.activeOrganization?.slug ? `/app/${ctx.activeOrganization.slug}` : "/app",
+    description: "Organization context base path - resolves to /app or /app/{slug}"
+  },
+  {
+    pattern: "{slug}",
+    resolve: (ctx) => ctx.activeOrganization?.slug ?? "",
+    description: "Organization slug"
+  },
+  {
+    pattern: "{username}",
+    resolve: (ctx) => ctx.user?.name || ctx.user?.email || "",
+    description: "User name or email"
+  },
+  {
+    pattern: "{user.id}",
+    resolve: (ctx) => ctx.user?.id || "",
+    description: "User ID"
+  }
+];
+export function createTemplateRegistry(customTemplates) {
+  const registry = [...defaultTemplates];
+  if (customTemplates) {
+    for (const [pattern, resolve] of Object.entries(customTemplates)) {
+      registry.push({ pattern, resolve });
+    }
+  }
+  return registry;
+}

package/dist/runtime/plugins/navigation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Navigation plugin
+ * Initializes navigation context using user-defined or default context provider
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/plugins/navigation.js

@@ -0,0 +1,22 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+const defaultContextProvider = () => ({
+  user: null,
+  activeOrganization: null,
+  features: {}
+});
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig();
+  const contextProviderOption = config.public.navigation?.contextProvider;
+  let contextProvider = defaultContextProvider;
+  if (contextProviderOption && typeof contextProviderOption === "function") {
+    contextProvider = () => contextProviderOption(nuxtApp);
+  }
+  const providedContext = contextProvider();
+  return {
+    provide: {
+      navigation: {
+        context: providedContext
+      }
+    }
+  };
+});

package/dist/runtime/types/config.d.ts

@@ -0,0 +1,83 @@
+import type { NavigationContext } from './index.js';
+/**
+ * Module options for xyz-navigation
+ */
+export interface ModuleOptions {
+    /**
+     * Enable/disable the module
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Inline navigation items configuration
+     * Alternative to creating a separate navigation.config.ts file
+     *
+     * @example
+     * navigation: {
+     *   items: {
+     *     sections: {
+     *       main: [
+     *         { label: 'Dashboard', to: '{org}' },
+     *         { label: 'Projects', to: '{org}/projects' }
+     *       ]
+     *     }
+     *   }
+     * }
+     */
+    items?: any;
+    /**
+     * Default context provider
+     * - Function: Custom provider function that receives NuxtApp
+     * - undefined: Use default (null values for user/activeOrganization)
+     *
+     * @example
+     * // Define custom context provider
+     * contextProvider: (nuxtApp) => ({
+     *   user: nuxtApp.$auth?.user ?? null,
+     *   activeOrganization: nuxtApp.$org?.active ?? null,
+     *   features: nuxtApp.$features?.all() ?? {}
+     * })
+     */
+    contextProvider?: ((nuxtApp: any) => Partial<NavigationContext>);
+    /**
+     * Custom template variables
+     * Extend or override default template resolvers
+     */
+    templates?: Record<string, (ctx: NavigationContext) => string>;
+    /**
+     * Global navigation configuration
+     */
+    config?: {
+        /**
+         * Default feature flag resolver
+         */
+        features?: Record<string, boolean> | (() => Record<string, boolean>);
+        /**
+         * Role definitions and hierarchy
+         */
+        roles?: {
+            hierarchy?: string[];
+            resolver?: (user: any) => string | string[];
+        };
+        /**
+         * Translation function
+         */
+        i18n?: {
+            enabled?: boolean;
+            resolver?: (key: string) => string;
+        };
+    };
+    /**
+     * Enable development mode features
+     */
+    dev?: {
+        /**
+         * Log navigation context changes
+         */
+        logContext?: boolean;
+        /**
+         * Validate configuration on hot reload
+         */
+        validateOnHotReload?: boolean;
+    };
+}

package/dist/runtime/types/index.d.ts

@@ -0,0 +1,225 @@
+import type { RouteLocationNormalizedLoaded } from 'vue-router';
+/**
+ * Navigation context containing user, organization, and route information
+ */
+export interface NavigationContext {
+    /**
+     * Current authenticated user
+     */
+    user: {
+        id?: string;
+        name?: string;
+        email?: string;
+        [key: string]: any;
+    } | null;
+    /**
+     * Active organization/tenant
+     */
+    activeOrganization: {
+        id?: string;
+        slug?: string;
+        name?: string;
+        [key: string]: any;
+    } | null;
+    /**
+     * Current route
+     */
+    route: RouteLocationNormalizedLoaded;
+    /**
+     * Feature flags
+     */
+    features?: Record<string, boolean>;
+    /**
+     * Custom context data
+     */
+    [key: string]: any;
+}
+/**
+ * Template resolver function type
+ */
+export interface TemplateResolver {
+    /**
+     * Template pattern to match (e.g., '{org}', '{slug}')
+     */
+    pattern: string;
+    /**
+     * Resolver function
+     */
+    resolve: (ctx: NavigationContext) => string;
+    /**
+     * Description for documentation
+     */
+    description?: string;
+}
+/**
+ * Navigation item configuration
+ */
+export interface NavigationItemConfig {
+    /**
+     * Unique identifier (optional)
+     */
+    id?: string;
+    /**
+     * Label (translation key or static string)
+     */
+    label: string;
+    /**
+     * Route path
+     * - Static string: '/app/settings'
+     * - Template string: '{org}/dashboard'
+     * - Context function: (ctx) => `/custom/${ctx.org.slug}`
+     */
+    to?: string | ((ctx: NavigationContext) => string);
+    /**
+     * Icon identifier
+     */
+    icon?: string;
+    /**
+     * Badge configuration
+     */
+    badge?: {
+        label?: string;
+        color?: string;
+        variant?: string;
+    };
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: {
+        text: string;
+        placement?: 'top' | 'bottom' | 'left' | 'right';
+    };
+    /**
+     * Feature flag requirement
+     * Supports dot notation: 'organizations.billing'
+     */
+    feature?: string;
+    /**
+     * Role requirements
+     */
+    roles?: string[];
+    /**
+     * Custom condition
+     */
+    if?: (ctx: NavigationContext) => boolean;
+    /**
+     * Click handler (for action items)
+     */
+    onSelect?: (ctx: NavigationContext) => void | Promise<void>;
+    /**
+     * Child items (for nested navigation)
+     */
+    children?: NavigationItemConfig[];
+    /**
+     * Exact route matching
+     * @default true
+     */
+    exact?: boolean;
+    /**
+     * Custom metadata
+     */
+    meta?: Record<string, any>;
+    /**
+     * Divider (if true, renders as divider instead of link)
+     */
+    divider?: boolean;
+}
+/**
+ * Processed navigation menu item (after resolution and filtering)
+ */
+export interface NavigationMenuItem extends Omit<NavigationItemConfig, 'to' | 'children'> {
+    to?: string;
+    children?: NavigationMenuItem[];
+}
+/**
+ * Navigation configuration type
+ */
+export type NavigationConfig = Record<string, NavigationItemConfig[]>;
+/**
+ * Options for useNavigation composable
+ */
+export interface UseNavigationOptions {
+    /**
+     * Custom context provider
+     * Overrides module-level context
+     */
+    context?: NavigationContext | (() => NavigationContext);
+    /**
+     * Enable reactive updates
+     * @default true
+     */
+    reactive?: boolean;
+    /**
+     * Custom template resolvers
+     */
+    templates?: Record<string, (ctx: NavigationContext) => string>;
+}
+/**
+ * Result from useNavigation composable
+ */
+export interface NavigationResult<T extends NavigationConfig> {
+    /**
+     * Resolved navigation items for each section
+     */
+    sections: {
+        [K in keyof T]: import('vue').ComputedRef<NavigationMenuItem[]>;
+    };
+    /**
+     * Current navigation context
+     */
+    context: import('vue').ComputedRef<NavigationContext>;
+    /**
+     * Refresh navigation (re-process all items)
+     */
+    refresh: () => void;
+}
+/**
+ * Sidebar state options
+ */
+export interface SidebarStateOptions {
+    /**
+     * Initial view
+     */
+    initialView?: string;
+    /**
+     * Persist view state
+     */
+    persist?: boolean | {
+        key?: string;
+        storage?: 'localStorage' | 'sessionStorage';
+    };
+    /**
+     * View transition hooks
+     */
+    onBeforeSwitch?: (from: string, to: string) => boolean | Promise<boolean>;
+    onAfterSwitch?: (view: string) => void;
+}
+/**
+ * Sidebar state management
+ */
+export interface SidebarState {
+    /**
+     * Current active view
+     */
+    currentView: import('vue').Ref<string>;
+    /**
+     * View history stack
+     */
+    history: import('vue').ComputedRef<string[]>;
+    /**
+     * Switch to a specific view
+     */
+    switchToView: (view: string) => Promise<void>;
+    /**
+     * Go back to previous view
+     */
+    backToPrevious: () => void;
+    /**
+     * Reset to initial view
+     */
+    resetView: () => void;
+    /**
+     * Check if currently in a specific view
+     */
+    isView: (view: string) => import('vue').ComputedRef<boolean>;
+}

package/dist/runtime/utils/processor.d.ts

@@ -0,0 +1,43 @@
+import type { NavigationContext, NavigationItemConfig, NavigationMenuItem, TemplateResolver } from '../types/index.js';
+/**
+ * Processing options for navigation items
+ */
+export interface ProcessingOptions {
+    /**
+     * Template resolvers
+     */
+    templates: TemplateResolver[];
+    /**
+     * Role hierarchy for role-based filtering
+     */
+    roleHierarchy?: string[];
+    /**
+     * Role resolver function
+     */
+    roleResolver?: (user: any) => string | string[];
+}
+/**
+ * Check if a feature flag is enabled
+ * Supports dot notation: 'organizations.billing'
+ */
+export declare function checkFeatureFlag(item: NavigationItemConfig, ctx: NavigationContext): boolean;
+/**
+ * Check if user has required roles
+ * Supports role hierarchy
+ */
+export declare function checkRoles(item: NavigationItemConfig, ctx: NavigationContext, options: ProcessingOptions): boolean;
+/**
+ * Check custom condition
+ */
+export declare function checkCondition(item: NavigationItemConfig, ctx: NavigationContext): boolean;
+/**
+ * Process navigation items through the filtering and resolution pipeline
+ *
+ * Pipeline:
+ * 1. Filter by feature flags
+ * 2. Filter by roles
+ * 3. Filter by custom conditions
+ * 4. Resolve paths
+ * 5. Process children recursively
+ */
+export declare function processNavigationItems(items: NavigationItemConfig[], ctx: NavigationContext, options: ProcessingOptions): NavigationMenuItem[];

package/dist/runtime/utils/processor.js

@@ -0,0 +1,55 @@
+import { resolvePath } from "./resolver.js";
+export function checkFeatureFlag(item, ctx) {
+  if (!item.feature) return true;
+  if (!ctx.features) return false;
+  const keys = item.feature.split(".");
+  let current = ctx.features;
+  for (const key of keys) {
+    if (current && typeof current === "object" && key in current) {
+      current = current[key];
+    } else {
+      return false;
+    }
+  }
+  return current === true;
+}
+export function checkRoles(item, ctx, options) {
+  if (!item.roles || item.roles.length === 0) return true;
+  if (!ctx.user) return false;
+  let userRoles;
+  if (options.roleResolver) {
+    const resolved = options.roleResolver(ctx.user);
+    userRoles = Array.isArray(resolved) ? resolved : [resolved];
+  } else {
+    const role = ctx.user.role || ctx.user.roles;
+    userRoles = Array.isArray(role) ? role : role ? [role] : [];
+  }
+  return item.roles.some((requiredRole) => {
+    if (userRoles.includes(requiredRole)) return true;
+    if (options.roleHierarchy) {
+      const userHighestRoleIndex = Math.max(
+        ...userRoles.map((r) => options.roleHierarchy.indexOf(r))
+      );
+      const requiredRoleIndex = options.roleHierarchy.indexOf(requiredRole);
+      return userHighestRoleIndex >= requiredRoleIndex;
+    }
+    return false;
+  });
+}
+export function checkCondition(item, ctx) {
+  if (!item.if) return true;
+  return item.if(ctx);
+}
+export function processNavigationItems(items, ctx, options) {
+  return items.filter((item) => checkFeatureFlag(item, ctx)).filter((item) => checkRoles(item, ctx, options)).filter((item) => checkCondition(item, ctx)).map((item) => {
+    const processed = {
+      ...item,
+      to: item.to ? resolvePath(item.to, ctx, options.templates) : void 0,
+      children: item.children ? processNavigationItems(item.children, ctx, options) : void 0
+    };
+    if (processed.children && processed.children.length === 0) {
+      delete processed.children;
+    }
+    return processed;
+  });
+}

package/dist/runtime/utils/resolver.d.ts

@@ -0,0 +1,16 @@
+import type { NavigationContext, TemplateResolver } from '../types/index.js';
+/**
+ * Resolve a path string or function to a final path
+ * Handles both template strings and context functions
+ *
+ * @example
+ * resolvePath('{org}', ctx, templates) // → '/app' or '/app/acme'
+ * resolvePath('{org}/dashboard', ctx, templates) // → '/app/dashboard' or '/app/acme/dashboard'
+ * resolvePath((ctx) => `/${ctx.org.slug}`, ctx, templates) // → '/acme'
+ */
+export declare function resolvePath(path: string | ((ctx: NavigationContext) => string), ctx: NavigationContext, templates: TemplateResolver[]): string;
+/**
+ * Resolve multiple template variables in a path
+ * This is a convenience function that wraps resolvePath
+ */
+export declare function resolveTemplates(path: string, ctx: NavigationContext, templates: TemplateResolver[]): string;

package/dist/runtime/utils/resolver.js

@@ -0,0 +1,16 @@
+export function resolvePath(path, ctx, templates) {
+  if (typeof path === "function") {
+    return path(ctx);
+  }
+  let resolved = path;
+  for (const template of templates) {
+    if (resolved.includes(template.pattern)) {
+      const value = template.resolve(ctx);
+      resolved = resolved.replace(new RegExp(template.pattern.replace(/[{}]/g, "\\$&"), "g"), value);
+    }
+  }
+  return resolved;
+}
+export function resolveTemplates(path, ctx, templates) {
+  return resolvePath(path, ctx, templates);
+}