Element Vanilla JavaScript Setup

The only project configuration required to use Element without a JavaScript framework is to:

1. Create an .npmrc file pointing to Element
2. Install the Element packages that you want to use
3. Ensure that your project supports SCSS
4. Make sure to include the Element SCSS in your build

Installation

You can choose whether you want to install just a handful of Element Vanilla components, or it you would rather install them all in one go. It is our recommendation to install them all to accelerate your development experience. Any JavaScript bundler will not include JS in your final bundle that you never imported, so installing all the components will not affect the size of your final bundle.

Note: Before installing any Element packages, you must create an .npmrc file pointing to Element

To install all components:

# Install with yarn
yarn add @element/components-web

# Or install with npm
npm i @element/components-web

To install components individually:

Where button and card are the two components that you want to use

# Install with yarn
yarn add @element/button @element/card

# Or install with npm
npm i @element/button @element/card

Using SASS with Webpack

There are an assortment of different ways that you could be compiling SCSS in your application, but one of the most common is via Webpack and Webpack's sass-loader.

If your project makes use of Webpack and sass-loader, then including the Element SCSS in your build means setting the sassOptions option of sass-loader. That might look something like this in your webpack.config.js:

// webpack.config.js
{
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          // 3. Creates `style` nodes from JS strings
          {loader: 'style-loader'},
          // 2. Translates CSS into Common JS strings
          {loader: 'css-loader'},
          // 1. Compiles SASS into CSS
          {
            loader: 'sass-loader',
            options: {
              implementation: require('sass'),
              sassOptions: {
                includePaths: ['../node_modules'], // https://github.com/sass/node-sass#includepaths
                fiber: require('fibers'), // https://github.com/webpack-contrib/sass-loader#implementation
              },
            },
          },
        ],
      },
    ]
  }
}

The key here is includePaths: ['../node_modules']. This tells the SASS compiler to search the node_modules directory when resolving import paths. So you can now write @use @element/button Because the path node_modules/@element/button/_index.scss exists in your project.

Using JS from this library

Please see the documentation for each specific component for usage instructions. Generally though, using the vanilla components will be as simple as:

let el = document.querySelector('.my-class')
let component = new ElementComponent(el)

Note: ElementComponent does not actually exist. It's used here for illustrative purposes only.

Structure of this library

Element Vanilla is structured in such a way that core logic is encapsulated in a single place, that we call a foundation. To allow the foundation to perform its duties, you pass it a series of functions that you've implemented to do things like interact with the DOM and notify the user. We refer to that grouping of functions as an adapter. The adapter required by each foundation is unique.

The idea behind this foundation-adapter pattern is to allow the foundations to be used by any JavaScript framework, even those that do not run in the browser; e.g. React Native. To accomplish this, the foundations do not make use of any browser API like document.querySelector(). Instead, the ability to fetch a node is delegated to the adapter. The developer implementing the adapter can then implement that function using the standard mechanisms for her environment.

Implementing an adapter to pass to a foundation is non-trivial and can be somewhat arduous. To make it easier to use the Element Vanilla library directly, in addition to foundations, most Element components also have a component class. The component implements the foundation-adapter pattern for use in the browser environment directly, supplying the necessary browser APIs and other logic.

Definitions

These are our definitions of the different parts of the architecture that are used by Element:

• Adapter: (adapter.ts) An object that contains a number of functions that relate to manipulating the DOM or notifying the user.  These functions are called by the foundation, because it is not aware of the specific DOM structure.

• Foundation: (foundation.ts) A class that handles the core functionality of a Element component or composition.  It relies on the adapter's functions to give it information about the DOM.

• Component: (component.ts) A simpler, less customizable interface to the functionality of a particular component, as compared to the foundation-adapter pattern. Many components have a foundation for higher customization as well as a component class for a simpler interface. Some may have only one or the other. Components can be used by developers writing vanilla JavaScript with minimal effort.

• Wrapper: A framework (React, Angular) specific implementation of the foundation-adapter pattern that creates markup, implements an adapter (capable of manipulating that markup), and instantiates a foundation for a particular component/composition.  These wrappers can then be used by developers within their framework of with minimal effort.