Fabric Elements

Description

Rackspace Fabric Design implemented as Web Components (custom elements), powered by Microsoft's FAST libraries/tooling

Change Log

See Change Log for the relevant release history.

Usage Instructions

See the Usage Guide for usage instructions (e.g. How to use Fabric custom elements in your React app).

Continue reading below for fabric-elements development-related notes for this repo.

Technologies

• FAST - Web Component libraries/tooling
• reactify-wc - React wrappers for Web Components
• Storybook - Demo playground for Web Components
• Web Test Runner - Test runner for Web Components
• Testing Library - Tests for Reactified Web Components

Prior Art

Along with Microsoft's FAST libraries and tooling, fabric-elements is heavily inspired by Helix UI

Requirements

• NodeJS and npm
• Windows, macOS, and Linux (Ubuntu) development environments are supported

Installation and Configuration

# Install npm via NodeJS, then run the following at repo root
npm install

Running Storybook

Run the following to automatically open a browser and load a developer preview of the components via Storybook.

# Run the Storybook stories
npm start

The Storybook stories are available at http://localhost:6006

Building

Run npm run build to build the JavaScript bundles in the following formats...

• Output compatible with ESM (ES6 Module) imports is located at /dist/esm/*
• Output compatible with standard script tag and script type="module" tag is located at /dist/js/*

Running Tests

Execute the following to run tests via Testing Library...

# Run tests in single-run mode (e.g. for CI/CD)
npm run test:react

# Run tests in watch mode (recommended for development)
npm run test:react:watch

Note that the tests assume the web components bundle has been built via npm run build

Running React Tests

Execute the following to run tests via Web Test Runner...

# Run tests in single-run mode (e.g. for CI/CD)
npm run test

# Run tests in watch mode (recommended for development)
npm run test:watch

Note that the tests assume the web components bundle has been built via npm run build

Linting via ESLint

For VS Code, add the following to your settings.json file to automatically lint your code on file save...

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

For JetBrains IDEs (e.g. WebStorm), perform the following steps to enable ESLint on file save...

1. Open Preferences and search for ESLint
2. Select the Automatic ESLint configuration radio button
3. Select the Run eslint --fix on save checkbox
4. Click the Apply or Save button in the preferences modal

Releasing Package to NPM

Perform the following steps to release a new version to npmjs.com...

1. Increment the package.json version entry using the YY.MM.DD pattern of CalVer. Note that the MM (month) and DD fields should not have a leading zero for consistency with the SemVer spec. Use an uppercase letter for subsequent versions published on the same day (e.g. YY.MM.DD-A).
2. Write a commit message that follows the pattern Release YY.MM.DD, matching the version in package.json. Only one commit that matches the pattern is required in the PR to kick off the release when merged.
3. Open a PR with the above change against the mainline (main) branch.
4. Merge the PR after obtaining the required approval(s), which will kick off the npm-publish GitHub Action workflow.

Known Issues

Webpack 4 and React 16 are required to avoid breaking Storybook

Webpack version 5 (or later?) and React 17 (or later?) seem to break Storybook's handling of Web Component previews/stories for this project, so we'll need to stick with Webpack 4.x and React 16.x for now.