@rss-eng/fabric-elements v21.6.3
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...
- Open Preferences and search for
ESLint
- Select the
Automatic ESLint configuration
radio button - Select the
Run eslint --fix on save
checkbox - Click the
Apply
orSave
button in the preferences modal
Releasing Package to NPM
Perform the following steps to release a new version to npmjs.com...
- Increment the package.json
version
entry using theYY.MM.DD
pattern of CalVer. Note that theMM
(month) andDD
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
). - 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. - Open a PR with the above change against the mainline (
main
) branch. - 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.