DEPRECATED - Pearson Elements-SDK

(As of August 2021 we are no longer supporting, maintaining, or updating this package. Please do not include this in your projects. If you are looking for an alternative you can try our Web Component library )

Updated to support Node 20 in v3

The Pearson Elements-SDK library contains a number of UI/UX interface elements that allow developers to develop applications using a consistent look and feel. Elements-SDK is split into two separate sets of functionality.

First are the CSS styles which allow the application to be developed according to the standards found at the Pearson UI/UX design site. Any UI/UX piece which only requires styling can be found in the /src/styles directory. This portion of the library is written exclusively in SASS and is transpiled at build time (either when Elements-SDK is built or when the SASS files are built by the consuming app). Second, are the JavaScript components which bring behaviors and programmatic functionality to the elements. This components are a mix of SASS/CSS styling and JavaScript functionality. Any UI/UX piece which requires both styling and functionality can be found in the /src/components directory. Components found in this directory need to be imported into the application from the built distribution file found in /build/dist.compounds.js

The Pearson Elements-SDK is intended for developers to consume as much or as little as needed to get the job done.

Consuming this SDK (via npm and imports)

It is recommended that Elements-SDK be installed into the project using npm:

npm install --save @pearson-components/elements-sdk

The installation provides both the dist files with minimized CSS and JavaScript code as well as the original source code, with required assets. This allows the option for the consuming app to include the SDK as a static asset or as part of a build process.

To comment out any SCSS file so it's not added to the application's rendered CSS, open src/styles/elements.scss and use JavaScript-style commenting. Example:

    @import 'base/variables';

    //@import 'base/html-tags';

    @import 'elements/typography/font-face';

The above would prevent the _html-tags.scss styles from being transpiled into the application's CSS file.

Consuming the JavaScript components requires importing into a consuming app as follows:

Import a single component:

import { Button } from '@pearson-components/elements-sdk/build/dist.elements-sdk';

Import all components:

import * as Compounds from '@pearson-components/elements-sdk/build/dist.elements-sdk';
const Button = Compounds.Button

or destructure as needed:

import {
  Button,
  Icon,
  TextInput,
  Select
} from '@pearson-components/elements-sdk/build/dist.elements-sdk';

Consuming this SDK (via HTML)

This library is published to NPM and is therefore available via unkpg.com. This allows teams to be able to consume the library through simple script includes (for JS) and to link to stylesheets (for CSS). Below is an example which includes the full CSS styling, JS library, and Icon sprite to enable the entire Elements-SDK library to be used.

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/@pearson-components/elements-sdk/build/css/elements.css" />
    <script type="text/javascript" src="https://unpkg.com/react@15.6.2/dist/react.min.js"></script>
    <script type="text/javascript" src="https://unpkg.com/react-dom@15.6.2/dist/react-dom.min.js"></script>
    <script type="text/javascript" src="https://unpkg.com/@pearson-components/elements-sdk/build/dist.elements-sdk.js"></script>
  </head>
  <body>
    <div id="app"></div>
    <script>
      if (document.body.children[0].nodeName !== 'svg') {
        var pe_ajax = new XMLHttpRequest();
        pe_ajax.open("GET", "https://unpkg.com/@pearson-components/elements-sdk/build/icons/p-icons-sprite-1.1.svg", true);
        pe_ajax.responseType = "document";
        pe_ajax.onload = function(e) {
          document.body.insertBefore(
            pe_ajax.responseXML.documentElement,
            document.body.childNodes[0]
          );
        }
        pe_ajax.send();
      }

      var rootElement = React.createElement(PhoneNumber, {id: 'demo', country: 'US', placeholder: 'enter phone', labelText: 'Mobile Phone'});
      var container = React.createElement('div', {}, rootElement);
      ReactDOM.render(container, document.getElementById('app'));
    </script>
  </body>
</html>

External Dependencies

React and ReactDOM (v0.14 or v15) are external dependencies required to use this component. They are npm-installable or available from a third-party CDN.

Polyfills

React components with internationalisation use React-Intl which relies on the ECMAScript Internationalisation API. This was not supported in Safari until version 10. If you are supporting Safari older than 10, there is a polyfill from Andy Earnshaw (see below).

CustomEvent support in IE is also polyfilled. Because many teams are supporting both IE 11 and Safari 9, we've combined the polyfills into a single script. The example below polyfills for CustomEvent and localisation for English and French:

<script src="https://cdn.polyfill.io/v2/polyfill.js?features=CustomEvent,Intl.~locale.en,Intl.~locale.fr"></script>

Be sure to include the above script (a version of it that makes sense for your project and supported browsers) on your HTML page running CompoundsSDK, if you need it.

Classes-only styling

If desired, Elements-SDK ships with a version that does not include any styling on plain HTML tags. Simply include build/css/elementsNoPlain.css, or add the /src/styles/elementsNoPlain.scss file to the project.

When using the ElementsNoPlain stylesheet, the (r)em-based sizing of page elements will differ from pages using the elements.css unless the consuming app is able to set the class the classpe-base-fontsizeon the html, body, or first main container of the page. To get the Open Sans font stack, use thepe-fontstackclass. Basic chunks of text (or their containers) can use thepe-copy` class to regulate font-size, line-height, and text color.

Using various Elements-SDK classes without the base settings for font-size, font-family, line-hieght and color will leave consuming apps with results that differ from other pages styled by elements.css (which may be desired).

Important: Fonts and Icons

Pearson Elements-SDK looks for the /fonts and /icons folders at the root of the served application. Copy the npm-installed /build/fonts and /build/icons to the correct location on the application's web server, and ensure the application is set up to allow the font files to download correctly and not filter out the response header Content Type (i.e. 'application/x-font-ttf') so the fonts may be rendered in the browser.

Internet Explorer

Some caching headers will prevent Internet Explorer from showing font files after a refresh. The culprits are Cache-control: no-store and on https Pragma: no-cache. The Vary header may also interfere with caching in IE.

Icons

Pearson Elements-SDK uses an SVG sprite for icons (the Pearson logos are two separate SVG files, not part of the sprite). The sprite file is found in /build/icons/ in Elements-SDK, and should be copied to the appropriate place, as mentioned above, on the application's web server. In additiona, to support Internet Explorer and some versions of Android where the default-Chrome browser is actually webkit, that SVG sprite must be present on the application's page. See the icons page under "Two methods of including icons" for examples of getting this sprite on your application page. Additionally, there are instructions on that page for how to add new icons.

Contributions

Please review the guidelines for contributing before getting started.

Git must be installed. Node.js v6 or higher must be installed (QA testing will target even numbered Node versions, specifically 6 and 8).

Windows users will need the following additional steps:

Install Ruby as the runtime engine for SCSS.
Install Python 2.7. Some node modules may rely on node-gyp, which requires Python on Windows.

Clone the project and install the dependencies and build the library:

git clone https://github.com/Pearson-Higher-Ed/elements-sdk.git
cd elements-sdk
npm install
npm run build

Verify everything worked correctly:

npm start

Then navigate to localhost:8081/compounds and click on the items on the page.

Adding Icons

See the icons documentation under "Adding new icons" for the process of adding a new icon.

Build the Documentation

Contibutors adding wholly new components to Elements-SDK (which have been already approved by UX design), in addition to writing all CSS and/or JavaScript for the component, will also need to add a new component page to the docs.

The documentation/demo website (which is bundled with the source code for Pearson Elements-SDK) is found in the /demo directory.

To add something new to the docs:

Create a file called Page.js to the /demo/demoPages/components directory. If the item consists of styles only, please add a file named StylesPage.js to the /demo/demoPages/styles directory. Please follow the patterns used by the other items in the respective directories to build out the structure of the page.
Open /demo/demoPages/HeaderPage.js and add the new item to the list according to the pattern of the other items on the page.
Open /demo/demoPages/HomePage.js and add the new item to the appropriate list according to the pattern of the oter items on the page.
Open /demo/demoRouter.js and import the new page created in the first step. Then add the new page to the router code found further down the file.
Save all files, rebuild, and start the demo app.

The new component's document page should:

have some explanation of what the purpose of the element or component is
have some example HTML (wrapped in demo tags, you can show both the rendered in-browser version as well as the actual HTML code in one go) for other developers to see where to best add Elements classes
demonstrate some of the component's functionality (if a JavaScript component)
have any special use notes if needed, such as accessibility or browser support gotchas

Test

The project is wired to unit test with Jest, "expect" assertion library, and expect-jsx to turn React elements into formatted strings.

npm test

QA Testing

QA may use the event harness to instantiate a component for testing using this format:

  document.body.dispatchEvent(new CustomEvent('o.InitCompounds', {
    detail: {
      elementId     : 'app',
      componentName : 'Button',
      props         : {
                       btnType :'primary',
                       btnSize :'xlarge',
                       children:'hi there'
                      }
    }
  }));

Guidelines

All submissions must be via pull request and approved before the pearson-design-accelerator@pearson.com team will merge and allow it to enter the release process. All submissions must pass this project's linting, test with 80% code coverage or greater, and be compatible with the version(s) of React approved for the Pearson User Experience Platform.

Acknowledgements

This project was inspired by other popular front-end frameworks published under the MIT license:

Pearson-Higher-Ed / elements-sdk

readme