@vue-layout/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 @vue-layout/navigation

Usage

To use the navigation component, a constant must be defined, which satisfy the NavigationProvider type.

The implementation will provide different navigation elements for each tier. The tier is a numeric value, which can be any positive integer (including 0).

module.ts

import {
    NavigationItem,
    createNavigationProvider
} from "@vue-layout/navigation";

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

export const navigationProvider = createNavigationProvider({
    async getItems(tier: number, itemsActive: NavigationItem[]) {
        // Return elements for a specific tier.
        // The context provides the current active elements for
        // the parent tiers.
        
        if(tier === 0) {
            return primaryItems;
        }
        
        // tier does not exist
        return undefined;
    },
    async getItemsActiveByURL(url: string) {
        // build element context for url
        if (url === '/') {
            return [
                primaryItems[0]
            ]
        }

        if (url === '/about') {
            return [
                primaryItems[1]
            ]
        }

        return undefined;
    }
});

The next step is to create the vue entrypoint.

index.ts

import {
    buildNavigation,
    install
} from '@vue-layout/navigation';
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { navigationProvider } from './module';

const app = createApp();

app.use(install({
    navigationProvider
}));

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

(async () => {
    const url = router?.currentRoute?.value?.fullPath;
    await buildNavigation({ url });

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

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

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

Functions

buildNavigation

▸ function buildNavigation(context?: NavigationBuildContext): Promise<void>

Build all navigation tiers, by url or active items.

Example

URL

import { buildNavigation } from '@vue-layout/navigation';

await buildNavigation({
    url: '/'
});

This will call the getItemsActive method of the NavigationProvider implementation, to calculate the active items.

items

import { buildNavigation } from '@vue-layout/navigation';

await buildNavigation({
    items: [
        {id: 'default', tier: 0, name: 'Home'}
    ]
})

The items property will be passed as second argument to the getItems method of the NavigationProvider implementation, to build a specific tier navigation.

route

import { RouteLocation } from 'vue-router';
import { buildNavigationWithRoute } from '@vue-layout/navigation';

const route : RouteLocation = {
    fullPath: '/',
    ...
};

await buildNavigation({
    route
})

Types

NavigationBuildContext

import { NavigationItem } from '@vue-layout/navigation';
import { RouteLocationNormalized } from 'vue-router';

declare type NavigationBuildContext = {
    items?: NavigationItem[],
    route?: RouteLocationNormalized,
    url?: string
};

NavigationItem

import { ElementType } from '@vue-layout/navigation';

declare type NavigationItem = {
    id?: string | number,
    tier?: number,
    name?: string,

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

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

    icon?: string,

    active?: boolean,

    display?: boolean,
    displayChildren?: boolean,

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

    requireLoggedIn?: boolean,
    requireLoggedOut?: boolean,
    requirePermissions?: string | string[] | ((checker: (name: string) => boolean) => boolean)

    [key: string]: any
};

NavigationProvider

import { NavigationItem } from '@vue-layout/navigation';

declare type NavigationProvider = {
    getItems: (
        tier: number, items: NavigationItem[]
    ) => Promise<NavigationItem[] | undefined> | undefined | NavigationItem[],
    getItemsActive: (
        url: string
    ) => Promise<NavigationItem[]> | NavigationItem[]
};

Example

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

License

Made with 💚

Published under MIT License.