app-loader

stablev1.0.0

The application code launcher of the Design System.

Overview

This component will perform several tasks:

  1. Test browser capabilities (Javascript feature support, Browser APIs).
  2. Inject a polyfill bundle that covers the unsupported features in the document.
  3. Set up your application code to be executed on the 'DOMContentLoaded' event once the polyfills have finished loading.

A polyfill is a piece of code that implements a feature not supported by the current runtime environment.

We have two polyfill bundles, one for very old browsers (full), and another for mid tier browsers (partial). Modern browsers usually don't need loading polyfills.

Usage

Dependencies

To get the app-loader working, include the dependencies in your project in the following order:

  1. npm
  2. Javascript
"design-system": "git+ssh://git@github.com/Selectra-Dev/design-system.git"

import appLoader from 'design-system/src/js/00-utilities/app-loader';

Basic code

To use the app-loader, our application code first must be wrapped into a function. We'll then pass a reference to this function to the app-loader, and optionally a list of features our code need to function.

The app-loader will then test the capabilities of the browser, and conditionally inject a polyfill bundle before setting up the code to be called back when the DOM has finished loading.

🤩 Are you writing code for a DS component ?
If so, please be mindful of the polyfills your code could rely on, and add them to the component's JSDoc @fileOverview header using @requires tags. 

import appLoader from 'design-system/src/js/00-utilities/app-loader';

function app() {
  // We use 'classList' property in our code...
  document.body.classList.add( 'lol' );

  // And the 'fetch' API !
  let randomFetch =
    fetch( 'https://selectra.info/')
      .then( response => {
        return response.text()
      })
}

// No worries! We'll load some polyfills if the browser does not support
// some of these features.

appLoader({

  // The 'app' function will be set to be called back on the
  // 'DOMContentLoaded' event. After the polyfills are loaded.
  appCode: app,

  // We pass the list of features our application needs to function.
  // This is an optional step.
  appRequiredFeatures:
    [
      // Sub Array for Element's features.
      [
        'element',
        [
          'classList'
        ]
      ],
      // Sub Array for Fetch API
      [
        'fetch',
        [
          'all'
        ]
      ]
    ]
});

Function call

appLoader( init );
# Name Type Default Required Description
1 init Object / Yes A configuration object.
appCode

(mandatory: Function)

A reference to the application code function. Will be called once the polyfill bundle has finished loading.

appRequiredFeatures

(optional: Array)

This property can be used to pass the list of features (choosed from those included in the bundles) that our application needs to function.

If a feature is not supported by the browser but it's not included in this list , the app-loader will not take it in consideration since the code does not need that specific feature.

If this property is not present, all features are assumed to be needed.

This is how you must build this paramenter:

appRequiredFeatures:
  [
    // A sub array for each Built-In/API/Interface.
    [
      // Built-In/API/Interface identifier.
      'string',

      // An array to define which features are needed.
      [
        // Feature 1 ID
        'fromCodePoint',
        // Feature 2 ID
        'codePointAt',
        // etc
      ]
    ],
    // More...
    [
      // ...
    ],
  ]

Check the valid IDs for the Built-INs/APIs/Interfaces/Features in the feature list below.

You can also take a look at the code of the test.js file of the Design System demo page for a complete example.

polyfillsUrls

(optional: Object)

Use it to specify custom paths for the polyfill bundles. i.e:

polyfillsUrls:
  {
    full: '/custom/path/my-full-polyfill-bundle.min.js',
    partial: '/custom/path/my-partial-polyfill-bundle.min.js',
  }

Feature list

Here's a comprehensive list of features covered by the DS polyfill bundles.

Core Javascript

❗️ Check this ES6 Compatibility table for more information on core language feature support.

Built-In ID Feature Bundle
number isinteger Number.isInteger() Full
number parseInt Number.parseInt() Full
number parseFloat Number.parseFloat() Full
array from Array.from() Full
array forEach Array.prototype.forEach() Full
array includes Array.prototype.includes() Full
array from Array.prototype.slice() Full
math sign Math.sign() Full
string fromCodePoint String.fromCodePoint() Full
string codePointAt String.prototype.codePointAt() Full
string includes String.prototype.includes() Full
string repeat String.prototype.repeat() Full
object assign Object.assign() Full
symbol all Symbol Full
promise all Promise Full

Browser APIs & Interfaces

❗️ You can check either the MDN Web APIs & interfaces reference or the Can I use database for more information about APIs & interfaces support.

API / Interface ID Feature Bundle
parentNode append ParentNode.append() Full
element closest Element.closest() Full
element matches Element.matches() Full
element classList Element.classList() Full
scroll all ScrollToOptions Full, Partial
intersectionObserver all IntersectionObserver Full, Partial
fetch all fetch() Full, Partial
positionSticky all position: sticky Full, Partial