README.md

@vuecs/navigation 🧭

A package containing basic components, to build multi level navigation menus.

Note The package is still in development and the API is still subject to change. Besides, the documentation still needs to be expanded

Table of Contents

• Installation
• Usage
• Functions
  • buildNavigation
• Types
  • NavigationBuildContext
  • NavigationItem
  • NavigationProvider
• Example
• License

Installation

$ npm i --save @vuecs/navigation

Usage

To use the navigation component, a function must be defined, to retrieve a set of elements for a specific level and parent element.

module.ts

import {
    NavigationItem
} from "@vuecs/navigation";

const topNav: NavigationItem[] = [
    { name: 'Home', url: '/', icon: 'fa fa-home' },
    { name: 'Admin', url: '/admin/', activeMatch: '/admin/', icon: 'fas fa-cog' }
];

const sideDefaultNav : NavigationItem[] = [
    { name: 'Home', url: '/', icon: 'fa fa-home' },
    { name: 'About', url: '/info', icon: 'fa fa-info' }
];

const sideAdminNav : NavigatioNitem[] = [
    { name: 'Home', url: '/admin/', icon: 'fa fa-home' },
    { name: 'Users', url: '/admin/users', icon: 'fa fa-user' },
    
];

export function getNavigationItems(
    level: number,
    parent?: NavigationItem
) {
    if (level === 0) {
        return topNav;
    }
    
    if(parent) {
        if(level === 1) {
            if(parent.name === 'Home') {
                return sideDefaultNav;
            } 
            
            if(parent.name === 'Admin') {
                return sideAdminNav;
            }
        }
    }

    return [];
}

The next step is to create the vue entrypoint.

index.ts

import {
    injectNavigationManager,
    install
} from '@vuecs/navigation';
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { getNavigationItems } from './module';

const app = createApp();

app.use(install({
    items: ({ level, parent }) => {
        return getNavigationItems(level, parent);
    }
}));

const router = createRouter({
    history: createWebHistory(),
    routes: [
        /* ... */
    ],
});
app.use(router);

(async () => {
    const path = router?.currentRoute?.value?.fullPath;
    
    const navigationManager = injectNavigationManager();
    await navigationManager.build({ path });

    app.mount('#app');
})();

---

After those steps are completed, the VCNavItems SFC can be placed anywhere, if registered globally.

<template>
    <div>
        <VCNavItems :level="0" />
        
        <VCNavItems :level="1" />
    </div>
</template>

Types

NavigationItem

import { ElementType } from '@vuecs/navigation';

declare type NavigationItem = {
    level?: number,
    name?: string,

    url?: string,
    urlTarget?: '_self' | '_blank' | '_parent' | '_top' | string,

    default?: boolean,
    // link or separator
    type?: `${ElementType}`,

    icon?: string,

    active?: boolean,
    activeMatch?: string,

    display?: boolean,
    displayChildren?: boolean,

    root?: boolean,
    children?: NavigationItem[],

    meta?: Record<string, any>
};

Example

For an implementation example, on how to use this library, check out the example package.

License

Made with 💚

Published under MIT License.