Reveal-basis NPM

Reveal Basis

Reveal Basis is a 'no dependencies' UI Kit which provides a set of tools to ease the front end developer job.

It aims to help with DOM elements that have to be shown/hidden (spinner, modals, notifications, etc.) by providing basis toggling and triggering mechanism.

You can have a look at some code samples on the library examples page.

Components are built to be the less opinionated possible. For example, at the 'core' level an .above element does nothing but appear on top of the page content.

The real benefits come from the 'modifier' layer where you can define some custom behaviour, constrain width or position, etc.

This separation of concerns allows you to benefit from the core mechanism of the library as a basis, a starting point from which you can add whatever fits your needs.

Reveal Basis supplies a few common modifiers, like modals or notification transitions. They can be used as examples to create your own and can easily be overridden if need be.

Table of Content

Installation

Install with regular `<link>` and `<script>` tags

Reveal Basis stylesheet and script file contain core mechanisms for toggling components and are needed for the library to work.

As you would do with a lot of other libraries, you can install it by inserting a <link> tag in your page's <head> and a <script> tag just before the body closing tag </body>:

Copy the reveal-basis.min.js and the reveal-basis.css files (both found in the dist folder) into your own project structure (eg. lib/js/reveal-basis.min.js) and insert them into your page template:

<!-- index.html -->
<head>
    [...]
    <link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>

<body>
    [...]
    <script src="lib/js/reveal-basis.min.js"></script>
</body>

You can test if the library is correctly set up with an above component:

<!-- index.html -->
<head>
    <link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>

<body>
    <button data-toggle="above" data-target="#test-above">Show a modal-ipsum</button>
    <div class="above --type-modal --position-top" id="test-above">
        Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aut beatae, ex maiores minus nesciunt provident quos vitae voluptatem. Distinctio dolor, explicabo iste minus molestiae ullam vero! Adipisci provident reiciendis veniam.
    </div>

    <script src="lib/js/reveal-basis.min.js"></script>
</body>

Install with NPM

Reveal Basis is also available as a Node package.

To download and install it locally in your node_modules folder, just type this command within your project root folder:

npm install --save reveal-basis

You will then be able to use it the ES6 way, in your own script files:

// script.js
import * as reveal from 'reveal-basis';

reveal.notification.create({
    message: "Hello World!",
    duration: 3000 // in milliseconds
});

Override default styles

One of the advantages of installing Reveal Basis via NPM is that you can change library style defaults with Sass.

You can find all the variables names used by the library in the src/style/components/_variables.scss file.

As the Sass keyword !default is used, you can override those values within your own Sass build process, as you would do with Bootstrap variables for example.

Let's see an example:

// _myOwnVariables.scss
$overlay-background-color: red;

// main.scss
@import 'myOwnVariables'; // import your custom file first
@import '~reveal-basis/src/style/components/_variables.scss'; // the `~` stands for the node_modules folder

And now you can display your beautiful red overlay:

// script.js
import * as rb from 'reveal-basis';

rb.overlay.show();

Components

Above

above component's purpose is to display an element above the current page content (imagine a modal dialog box or a drawer type sliding menu).

Above: Usage

The triggering element (button or anchor) needs to contain data-toggle="above" attribute.

An eventual closing element needs to have the .dismiss class and to be inside the .above element. It can only be triggered with a 'click' event.

Above: Options

.--no-overlay

By default, triggering an .above element will also trigger the page's #overlay element. This behaviour can been changed by adding a .--no-overlay class on the .above element.

<div class="above --no-overlay">Lorem ipsum...</div>

.--lock-overlay

The .above element is dismissed when the page's #overlay is clicked. To change this behaviour, just add a .--lock-overlay class on the .above element.

<div class="above --lock-overlay">Lorem ipsum...</div>

Let's see some 'core' examples (just wait for the 'modifier' section for funnier stuff):

Trigger an `.above` with a button, through a `[data-target]` attribute

<!-- this button will toggle an '.above' element which 'id' is 'targeted-above' -->
<button data-toggle="above" data-target="#targeted-above">Show</button>

<!-- this is the '.above' element that will be triggered -->
<div id="targeted-above" class="above">
    <button class="dismiss">Hide</button>
    <p>Lorem ipsum dolor sit amet...</p>
</div>

Trigger an `.above` with an anchor, through a `[href]` attribute

<!-- this anchor tag will toggle an '.above' element which 'id' is 'targeted-above' -->
<a data-toggle="above" href="#targeted-above">Show</a>

<!-- this is the '.above' element that will be triggered -->
<div id="targeted-above" class="above">
    <button class="dismiss">Hide</button>
    <p>Lorem ipsum dolor sit amet...</p>
</div>

Trigger an `.above` with a button inside an `.above-group` element

<div class="above-group">

    <!-- trigger and '.above' are enclosed by an '.above-group' element,
    no need for a [data-target] or a [href] attributes here -->
    <button data-toggle="above">Show</button>

    <div class="above">
        <button class="dismiss">Hide</button>
        <p>Lorem ipsum dolor sit amet...</p>
    </div>

</div>

> Play with the examples

Above: Modifiers

Default .above behaviour can be extended by adding some modifier classes.

Transitions

Reveal Basis has a few bonus classes to make an .above element slide from one side of the view: .--transition-top, .--transition-right, .--transition-bottom, .--transition-left:

<div class="above --transition-left">

There is also a .--transition-scale modifier:

<div class="above --transition-scale">

> Play with the examples

Modal dialog box

The .--type-modal class constrains the .above element to the center of the view (horizontally and vertically).

Its dimensions are shrinked to half its width by default: <div class="above --type-modal">

It can also leverage a transition modifier: <div class="above --type-modal --transition-top">

> Play with the examples

Drawer

An 'drawer' type above (.--type-drawer) could be used to toggle a side menu, for example.

It has to use a static positioning modifier (eg. .--position-left) or a transition one (eg. .--transition-right).

Notes:

if no positioning modifier is used, an drawer type above (.--type-drawer) will behave the same as a simple .above element.

if you are overriding default variables, you can change the default dimension set by $above-drawer-dimension variable.

> Play with the examples

Customization examples

You can build upon the .above element and its modifiers to create your own custom elements.

> Play with the examples

Above: Note

If you are overriding default variables, be aware that global padding of above component has to be explicitly given through $above-padding variable as it is needed for positioning calculation.

The visibility state modifier class for an .above element is .is-visible.

Notification

notifications are alerting components types.

For example, a notification can be displayed as a feedback when the website user has performed an operation (eg. successful login).

Notification: Usage

Notifications can be used either after a page load (.notifications already on DOM) or triggered manually (eg. after a user has clicked on something)

Static notifications

The typical use for a static .notification is when a user has just been redirected to a new page after some kind of event.

eg. User is welcomed on their profile page after a successful login validation:

<div class="notification">Welcome on your profile page</div>

To display a notification on page load, just add the .notification class on one of your template's element. It will 'convert' it to a notification along with all its content, including buttons, links, images, etc.

options:

To make it dismissible (with a click), just add the .dismiss class directly on the notification or on a trigger element inside it.

<div class="notification dismiss">Click anywhere to dismiss me</div>

<div class="notification">Click <span class="dismiss">here</span> to dismiss me</div>

To make the notification stick, add the .--sticky class, it will remove the default duration.

<div class="notification --sticky">I won't disappear... like ever...</div>

> Play with the examples

Static notifications: modifiers

A simple block appearing on top of your content being kind of limited, Reveal Basis supplies some useful modifiers.

position and width (--position-right, --width-auto):

> Play with the examples

transition - slide (--transition-slide):

> Play with the examples

transition - fade (--transition-fade):

> Play with the examples

Scripted notifications

The typical use for a scripted .notification is to give a direct feedback to the user (without redirection or page reload).

eg. User tried to submit a form but didn't fill a required field in.

The notification is triggered via javascript, using the library rb (reveal basis) global variable, along with its notification.create method.

<script>
    [... (failed form validation)]

    rb.notification.create("Please fill in all the required fields");
</script>

> Play with the example

Notification options

The create method accepts an option object as an optional second parameter:

<script>
    [...]

    rb.notification.create("Please fill in all the required fields", {
        classes: [],
        position: 'left',
        width: 'auto',
        transitions: ['slide', 'fade'],
        duration: 6000,
        speed: 300,
        dismissOnClick: true,
    });
</script>

classes: an array of classes (eg. classes: ["error", "small"])

default: empty array

Just pass the css classes you want for your notification (eg. "my-warning-notification").

position: a string, either 'left' or 'right'

default: "left"

This option is used with width and/or transitions options.

Used with width: 'auto', the notification will stick on the position side of the screen (if its content isn't already screen wide).

Used with transitions: ['slide'], the notification will appear on screen from the position-hand side.

width: a string, either 'full' or 'auto'

default: "auto"

By default a notification will be displayed on the entire device screen width ('full'). If this option is set to 'auto', the notification with only be as wide as its content.

transitions: an array of transition modifiers (eg. transitions: ["slide", "fade", "insert-your-own"])

default: "slide", "fade"

Those two transitions are set by default because you will likely want them on your typical notification. You can get rid of them by passing an empty array transitions: [] or your own custom transition(s).

Reveal Basis ships with a few transition modifiers:

"slide" will make your notification slide in and out of the screen.

"fade" will make it fade in and out.

You totally can combine all the transitions to achieve the effect you want.

To create your own transition, you will have to follow some simple rules:

its class name has to start with .--transition-
define the 'normal' and the 'is-visible' state

/* my custom transition */
.--transition-custom {
  transform: rotateZ(0deg);
  width: 100%;
}
.--transition-custom.is-visible {
  transform: rotateZ(720deg);
  width: 25%;
}

duration: an int

default: 6000

Duration is set in milliseconds (1000 equals 1 second) and represents the time the notification will be displayed.

A duration of 0 will keep the notification indefinitely on screen.

speed: an int

default: 300

Speed is the transition speed. It will have no effect if no transitions are set transitions: [].

dismissOnClick: a boolean

default: true

As its name implies, if dismissOnClick option is passed, the notification will be dismiss when user click on it.

The library add a dismiss class on the notification. You can take advantage on this to add custom style to differentiate between dismissible notifications and non-dismissible ones.

> Play with the example

Drop

drop component's purpose is to display a hidden element near the triggering element (eg. a dropdown menu).

Drop: Usage

Similarly to an .above, the triggering element (button, anchor, span or whatever) needs to contain data-toggle="drop" attribute.

To hide back the .drop element, just click again on the trigger button or move your mouse outside a .--trigger-hover .drop's trigger.

Let's see some 'core' examples:

Trigger a `.drop` with a button, through a `[data-target]` attribute

<!-- button triggered drop -->
<button data-toggle="drop" data-target="#button-trigger">Trigger drop with a button</button>

<div id="button-trigger" class="drop bg-gray">
    <p>This drop has been triggered by <b>a button</b></p>
</div>

Trigger a `.drop` with an anchor, through a `[href]` attribute

<!-- anchor triggered drop -->
<a data-toggle="drop" href="#anchor-trigger">Trigger drop with an anchor</a>

<div id="anchor-trigger" class="drop bg-gray">
    <p>This drop has been triggered by <b>an anchor</b></p>
</div>

Trigger a `.drop` with a button inside a `.drop-group` element

<!-- trigger and '.drop' are enclosed in an '.drop-group' element, no need for a [data-target] or a [href] attributes here -->
<div class="drop-group">

    <button data-toggle="drop">Trigger drop within a group</button>

    <div class="drop bg-gray">
        <p>This drop has been triggered within <b>a drop-group</b>, without being specifically targeted</p>
    </div>
</div>

> Play with the examples

Drop: Modifiers

.--type-block

By default, a .drop element will appear above the page's content. Adding the .--type-block modifier will get the element inside the content flow, as a block type would.

<div class="drop --type-block">Lorem ipsum...</div>

.--trigger-hover

This option allow a .drop element to be triggered via an hover event on the trigger element.

Both trigger and .drop elements has to be inside the same .drop-group container:

<!-- drop is triggered by hovering the drop-group trigger element -->
<div class="drop-group">

    <div data-toggle="drop">Trigger drop on hover</div>

    <div class="drop --trigger-hover bg-gray">
        <p>This drop has been triggered by an hover event</p>
    </div>
</div>

> Play with the examples

Overlay

On page load, Reveal Basis creates and appends an #overlay element on the DOM.

This #overlay is used for Above and Spinner components but is also available in your own code if you need it.

Overlay: Usage

Overlay: access via es6 modules

If you have installed Reveal Basis via NPM, you can access the component by importing the library and creating a new instance of the overlay:

// script.js
import * as reveal from 'reveal-basis';

let overlay = new reveal.overlay();

Overlay: access via `rb` global variable

As long as you have imported the library with a <script> tag before using it, you have access to its global rb variable:

<!-- index.html -->
<head>
    <link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>

<body>
    [...]

    <script src="lib/js/reveal-basis.min.js"></script>
    
    <script>
        let overlay = new rb.overlay();
    </script>
</body>

Overlay: API

Whether you import the library or you include it via a <script> tag, you have now access to its API:

Overlay: show()

Nothing really fancy here, the overlay will appear on screen: overlay.show();

Overlay: hide()

Hide the overlay: overlay.hide();

Overlay: lock()

You can add the .is-locked class to the overlay by calling overlay.lock() before showing it: overlay.lock(); overlay.show();

It is the default behaviour of an Above's Overlay when the option --lock-overlay is used.

By default it will use a 'not-allowed' icon cursor on mouse hovering, but you can take advantage of this class, eg. you can't dismiss an .above element if the #overlay is locked.

> Play with the examples

Spinner

On page load, Reveal Basis creates and appends a #spinner element on the DOM.

Spinner is a utility component that can display a loading animation.

Its usage is similar to Overlay's one:

Spinner: Usage

Spinner: access via es6 modules

If you have installed Reveal Basis via NPM, you can access the component by importing the library and creating a new instance of the Spinner:

// script.js
import * as reveal from 'reveal-basis';

let spinner = new reveal.spinner();

Spinner: access via `rb` global variable

As long as you have imported the library with a <script> tag before using it, you have access to its global rb variable:

<!-- index.html -->
<head>
    <link rel="stylesheet" href="lib/css/reveal-basis.css">
</head>

<body>
    [...]

    <script src="lib/js/reveal-basis.min.js"></script>

    <script>
        let spinner = new rb.spinner();
    </script>
</body>