MS Teams

react components & styles for fanatical interfaces https://particles.janus.team/

In Depth docs:

• Changelog
• Contributing Guide
• Vision
• FAQ
• Divergences with Helix
• Hindsight

Readme Contents:

• Quick Start
• Documentation
• Vision
• Local Development
• Feedback

Missing Something? Something Broken?

Please create an issue and let us know.

We will use issues as a way to track things found by ourselves and by others and eventually convert those into cards to be worked on for our backlog.

Of course you're also welcome to submit a PR and make the changes yourself.

Semantic Versioning

janus-particles adheres to the usual semver guidelines:

• major version bumps for (most - except previously announced deprecation cases) breaking changes.
• minor version bumps for new features or significant improvements or (some - previously announced deprecation) breaking changes.
• revision version bumps for bugfixes or small improvements.

Pre/Alpha/Beta/RC releases

janus-particles does not officially support nor endorse the usage of any non-final releases. By non-final release we mean anything with a - suffix in the version number (e.g.: 5.0.0-alpha001).

We internally do use extensively releases with -rc/alpha/beta/pre suffixes for the purposes of extensive testing, but we do not recommend ever using any of those in a production environment, nor to rely that anything in any such release will ever stay the same in the final release.

Quick Start

Install with npm or yarn

npm i @janus.team/janus-particles
# or
yarn add @janus.team/janus-particles

Peer dependencies

yarn add\
  @janus.team/janus-particles@^4.16\
  @janus.team/janus-copilot@^3.1.1\
  @formatjs/intl-pluralrules\
  @formatjs/intl-relativetimeformat@^4.4.0\
  @sentry/browser@^5.7.1\
  @tippy.js/react@^3.1.1\
  classnames@^2.2.5\
  crypto@^1.0.1\
  downshift@^3.2.10\
  font-awesome@^4.7.0\
  intl\
  intl-format-cache@^4.2.2\
  intl-locales-supported\
  intl-messageformat-parser@^3.2.1\
  intl-messageformat@^7.3.2\
  js-cookie@^2.2.0\
  lodash@^4.17.11\
  moment-timezone@^0.5.21\
  moment@^2.18.1\
  object-assign@^4.1.1\
  prop-types@^15.5.10\
  qs@^6.7.0\
  react-datetime@^2.11.1\
  react-intl@^3.3.2\
  react-router-dom@^4.3.1\
  react-tippy@^1.2.3\
  uuid@^3.3.2\
  verror@^1.10.0\
  victory@^0.24.1

# yes, this is a lot - sorry. we are not happy about it either : (

Usage

Javascript

import { Button } from '@janus.team/janus-particles';

<Button onClick={...}>
  Press Me
</Button>
...

CSS

Add the particles css to your build.

import 'font-awesome/css/font-awesome.css';
import 'react-tippy/dist/tippy.css';
import '@janus.team/janus-particles/dist/particles.css';

Jest

You need [email protected] (at least).

Add this to your package.json:

"jest": {
  "transformIgnorePatterns": [
    "(?!.*janus.*)(?!.*@babel/runtime.*)node_modules"
  ]
}

Documentation

Complete docs available in the particles storybook.

Where are prop tables and story source code?!

As of version 5.0.0 we made the hard decision to no longer support those features (in that format at least). There has been an extensive set of problems with the @storybook/addon-info that powers both of those pieces and we decided to no longer use it.

The good news, however, is that the storybook team itself agrees that a better approach was necessary and have started to rollout @storybook/addon-docs that should cover both source code for stories and prop tables in a more sane way. We envision particles making heavy use of these new features in the near future (backfilling docs for old components) and using it as the default for new development.

We ask for your understanding and patience in this transition period, and meanwhile we suggest reading the source as a stopgap measure to understand how the code behind a story looks or to read comments around props in a component.

Vision

This project aims to help scale the development of Janus frontend applications through the use of reusable and self contained react components.

• This is a single, centralized place to share our teams' frontend development best practices.
• Including particles in your app should never interfere with any other styles or behavior, it is meant to be consumed by real world production applications without disrupting anything around it. All styles are opt-in by design and components are independent.
• This aims to provid a reduced the time to ship new features, through:
  • documentation for components
  • copy/paste examples
  • versioned components
  • clarification around approaches to state management

Particles vs Helix

• the Helix design is the look and feel for Rackspace, any discrepancy from it in particles will be considered as a bug unless explicitly listed in the known divergences doc.
• if something in particles looks different than helix, here are your (non-mutually-exclusive) options:
  • ask around in #janus-ux and/or #rss-eng.
  • change your code with extra CSS to match helix.
  • open a PR to particles to change it to match helix.
  • open an issue to particles to ask for changes to match helix.
  • open a PR to particles to add to the known list of divergences if you think that particles is more correct.
  • talk to the helix team in #helix if you think helix itself should change.
• the helix ui toolkit is a particular implementation of the helix design system and can be seen as an alternative (less janus opinionated) to particles. We strongly disencourage using both the helix toolkit and particles in the same project.

You can read a lot more about it here if you want an extensive description about this history.

Success Measurements

• Pages look and feel the same accross multiple Janus UIs, be it the legacy janus-ui or any micro/mini UIs developed under the Janus UI Platform.
• Potential expansion outside of the Janus tribe (e.g.: RSS org).
• Alignment with the look and feel of the helix design framework.

Local Development

Install yarn

• Install lib dependencies with yarn install
• Run tests with yarn test (if you have an issue on OSX Sierra+ with watchman, try brew install watchman)
• Lint with yarn lint
• Build components with yarn build

Preview Documentation

Storybook

We use react storybook to document components. To launch the local development server, run:

yarn start

Table of Contents

The table of contents found at the root of our documentation site is built with create-react-app. To preview this locally, run:

cd docs
yarn start

Then visit localhost:3000 on your browser of choice.

Export documentation

You can export the documentation site to a static build with:

yarn run build:docs

To build older versions of documentation, update docs/versions.json with the tagged versions to build. Then run yarn build:doc-versions. To publish these versions to S3, grab the AWS credentials for the environments dev and prod. You can deploy to the desired enviroment via: yarn publish:doc-versions <env>. Example deploy to dev: yarn publish:doc-versions dev.

During build in jenkins, docs are automatically published:

• particles.janus.team/versions/master/index.html & particles.dev.janus.team/versions/master/index.html (for master branch builds)
• https://particles.dev.janus.team/versions/{sha}/index.html - 6 character git commit sha
• https://particles.janus.team/versions/{tag}/index.html - tagged release

Feedback

Check us out on slack at #janus-ux and/or #rss-eng.