npm:@vonage/vvd-core

README

Core - Vivid lifecycle

Vivid content may be consumed on different levels. One may consume a single component, like vwc-button, vwc-dialog etc. Another use might be to init a common context via vvd-context service to style a common HTML native semantics like H1, p etc.

Any of those involves internal mechanics initialization: fetching fonts for typography, initializing schemes for a theming / scheme management etc. We call those vivid core.

There is a lifecycle here. We've designed Vivid lifecycle to be self-contained, agnostic to other contexts and to not interfere nor require alignment to the existing application lifecycle or any other framework in place.

The chart below represents a general runtime initialization flow, while separating the system into the consumer-visible realm and the underlying platform.

Consumer realm's items are to be consumed by the hosting applications directly (API / imports etc). Below the line are the core parts of our system which are transparent to the consumer in vast majority of cases.

Flow chart

Initialization flavors

vivid core initialization may go 2 main paths:

auto-init: this is the default behavior, Vivid will auto init itself upon the first usage unless specified otherwise
manual: see below how to configure Vivid this way and when to use it

Readiness hook

In order to allow ourselves and consuming applications to run code after initialization is done, vivid core exposes a settled Promise. This Promise will resolve once all the core services are done and ready.

Important: in case of manual initialization, settled will be immediately rejected.

import vvdCore from '@vonage/vvd-core.js';

...

vvdCore.settled.then(() => {
    //	do whatever after the init, eg remove the loading "curtain"
});

Most obvious use of the settled is to remove the loading veil, which could be put over the site in order to prevent FOUC (flash of unstyled content).

Auto init

If consuming application took no special action, the first use of the Vivid's component/s will auto initialize the vivid core.

Default init

All the vivid core services auto-initialize to default values if not specified otherwise.

Pre-configured init

In order to help Vivid to initialize itself to some specific state, consuming application should use data-vvd-context attribute on html element. The below example will auto-initialize vivid core with the dark theme.

<html data-vvd-context="theme:dark">
...

Important: the attribute is being examined at the moment of initialization ONLY, so it should be in place BEFORE the initialization performed. We suggest using this feature as a purely static setup OOTB.

Manual init

Advanced consumer might like to manage the visual application state (we mean Vivid's part, eg theming) as per user setting.

This case would involve an async work to be done client side, eg fetching personalized settings from the server or from a local storage like IndexedDB.

Init with none keyword designed exactly for that. It will prevent auto init of the vivid core. It can be done in the following manner:

Set the data-vvd-context to none in HTML:

<html data-vvd-context="none">
...

Use the vivid core API to set configuration dynamically:

import vvdCore from '@vonage/vvd-core.js';

vividCore
    .set({
        scheme: 'dark'
    })
    .then(() => {
        //	do whatever after applying configuration
    });

Pay attention: set API is not limited to the init use case only, it may be used for any runtime (re-)configuration of the Vivid overlay.

Reminder: settled Promise of the vivid core is immediately rejected when none initialization flavor is used.

Usage no npm install needed!