@caspeco/navigation-core

This package installs the TypeScript type definitions for the <caspeco-navigation-menu> Web Component as well as some utility functions.

Additional Resources

• Development docs (CONTRIBUTING.md)
• Type documentation website
• Sample application (dev)
• Confluence page

Installation

Install the package from npm.

npm i @caspeco/navigation-core

Usage

Correctly typed props

To make sure you are passing the correct props, you can use the NavigationMenuProps type:

import type { NavigationMenuProps } from "@caspeco/navigation-core";

export const NavigationMenu = () => {
    const navProps: NavigationMenuProps = {
        currentLocation: window.location.href,
        itemGroup: "Staff",
        // etc ...
    };

    return <caspeco-navigation-menu {...navProps}></caspeco-navigation-menu>;
};

Listening to events

The navigation has some Custom Events that you may want to listen to. Navigation events are always dispatched on the body element, and will bubble.

import type { MobileMenuClosedEventName } from "@caspeco/navigation-core";

useEffect(() => {
    const eventName: MobileMenuClosedEventName = "mobile-menu-closed";

    function handleMobileMenuClosed() {
        doSomething();
    }

    window.addEventListener(eventName, handleMobileMenuClosed);

    return () => {
        window.removeEventListener(eventName, handleMobileMenuClosed);
    };
}, []);

Language Selection

The navigation menu supports language selection, allowing users to change the interface language.

Reading the language from cookie

Use the getLocale function to get the current locale from the rms.locale cookie on page load:

import { getLocale } from "@caspeco/navigation-core";

// e.g. "en-GB", "sv-SE", "da-DK"
const currentLocale = getLocale();

Listening to language changes

When a user changes the language in the navigation menu, a rms-locale-change Custom Event is dispatched on the document body (bubbling). The new locale is included in the event's detail. Consumers should listen to this event and update their language accordingly:

import type { LocaleChangeEventName } from "@caspeco/navigation-core";

useEffect(() => {
    const eventName: LocaleChangeEventName = "rms-locale-change";

    function handleLocaleChanged(event: Event) {
        if (!(event instanceof CustomEvent)) {
            return;
        }

        const newLocale = event.detail.locale as string; // e.g., "en-GB", "sv-SE", "da-DK", etc.
        
        // Update your application's language
        updateApplicationLanguage(newLocale);
    }

    window.addEventListener(eventName, handleLocaleChanged);

    return () => {
        window.removeEventListener(eventName, handleLocaleChanged);
    };
}, []);

Setting the language

In most cases, the languages should be changed by the user through the navigation menu. If you have a very good reason to change the language programmatically, you can use the setLocale function:

import { setLocale } from "@caspeco/navigation-core";

// Sends a POST to the SSO API in dev to set the locale cookie, and dispatches the "rms-locale-change" event.
setLocale({ locale: "en-GB", environment: "dev" });

Context

The context contains information about the company (or system!) that the user has selected in the context selector.

Reading context

To read the RMS context correctly, you can use the getRmsContext() function:

import { getRmsContext } from "@caspeco/navigation-core";

function getContextId(): string {
    const { companyId, systemName } = getRmsContext();
    return companyId ?? systemName;
}

Setting context

If you need to, you can also setRmsContext(), but the use case for this should be rare. Make sure that you trigger a page navigation (either reload the page or redirect the user) after setting the context.

Preventing context changes

By default, when a user changes their context in the context selector, their selection is saved in browser storage and they are redirected to the overview page. In some cases you may want to send them somewhere else (e.g. Cloud App wants to send people to /cloud/home), in which case you can intercept and cancel the context-selected Custom Event:

import { setRmsContext, type RmsContext, type ContextSelectedEventName } from "@caspeco/navigation-core";

useEffect(() => {
    const eventName: ContextSelectedEventName = "context-selected";

    function handleContextChanged(event: Event) {
        if (!(event instanceof CustomEvent)) {
            return;
        }

        // Cancel default behavior
        event.preventDefault();

        // Set the context
        const newContext = event.detail as RmsContext;
        setRmsContext(newContext);

        // Redirect somewhere other than the Overview page
        window.location.href = "rms.caspeco.se/cloud/home";
    }

    window.addEventListener(eventName, handleContextChanged);

    return () => {
        window.removeEventListener(eventName, handleContextChanged);
    };
}, []);

Installing <caspeco-navigation-menu>

Option 1: Use the NPM package (experimental)

Available in >=3.8.0-alpha.0

Get URL and ID and inject manually

import { getNavigationScriptData } from "@caspeco/navigation-core";

const { src, id } = getNavigationScriptData({ environment: "stage" });
const script = document.createElement("script");
script.id = id;
script.src = src;
script.type = "module";
document.head.appendChild(script);

Get HTMLScriptElement and inject manually

Will skip injection if it already exists in the DOM.

import { getNavigationHTMLScriptElement } from "@caspeco/navigation-core";

const { scriptElement, data } = getNavigationHTMLScriptElement({ environment: "stage" });
document.head.appendChild(scriptElement);

Inject automatically

Will skip injection if it already exists in the DOM.

import { injectHTMLNavigationElement } from "@caspeco/navigation-core";

injectHTMLNavigationElement({ environment: "stage" });

Option 2: Use the CDN url directly (not using npm package)

Add it manually by importing the deployed script from our CDN urls, e.g.:

<script type="module" src="https://webcomponents.caspeco.net/v3/index.js"></script>

• Development: https://webcomponents.dev.caspeco.net/v{MAJOR_VERSION}/index.js
• Stage: https://webcomponents.stage.caspeco.net/v{MAJOR_VERSION}/index.js
• Production: https://webcomponents.caspeco.net/v{MAJOR_VERSION}/index.js

Side effects

Mobile navigation

On small devices (< 768px) the navigation is turned into a mobile navigation bar at the bottom of the screen. When this happens, the mobile-nav class is added to the root html document.

You may need to update your application to respond to this change, for example to change the height of your application from 100% to calc(100% - var(--mobile-navigation-height)). The --mobile-navigation-height is automatically added on your root html document when the navigation is installed.

This is an example of what had to be done on the Overview page:

main {
    height: 100%;
    /* ... */
}

+ .mobile-nav main {
+     height: calc(100% - var(--mobile-navigation-height));
+ }

Favicons

The navigation will overwrite your existing favicons with the correctly branded favicons as soon as it loads.

document.title

As of 2025-04-08 the navigation does not change your document.title, but soon it will modify it automatically depending on the page's name in the navigation.