This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

@orbit-ui/react-components
TypeScript icon, indicating that this package has built-in type declarations

18.1.2 • Public • Published

@orbit-ui/react-components

Full documentation available at: https://orbit.sharegate.design

Add a new component

Adding a new component package involve a few extra steps:

Write storybook stories

As mentionned in the contributing guide, Storybook is use to develop, document and test a component.

To develop and document, we leverage the CSF and MDX features of Storybook.

To test, we rely on a third party called Chromatic that fully integrate with Storybook to provide visual testing capabilities.

Develop and document

Development stories are written for 2 purposes:

  • For the developper to test a component use case in a isolated story during the development lifecycle.
  • For the design team to try the component behaviors.

Documentation stories are written... well for documentation purpose!

To define a story once for development and documentation a story must be written with CSF in an *.stories.mdx file. The name of the file should match the component name.

A story must:

  • Be located in the Components top level section of the Storybook navigation menu.
  • The second level segment must be the capitalized name of the component.

Here's an exemple for the date range picker component:

// Button.stories.mdx

<Meta title="Components/Button" />

A component stories must provide:

  • A story named default that render the component default state.

The stories must be located in a docs folder next to the src folder of your component. Storybook is configured to load the following component stories: packages/react-components/src/*/docs/**.stories.mdx.

/packages
    /react-components
        /buttons
            /docs
                Button.stories.mdx
            /src

Tests

Before reading the following sections, please read our introduction to Orbit testing practices.

Visual testing

Specific stories for Chromatic are written to validate the specifications of a component with automated visual tests. The specifications stories are validated every night with Chromatic for visual regression issues.

Storybook is a fantastic tool for visual testing because a story is essentially a test specification. When it does make sense, multiple specifications can be bundled together in a story to save on Chromatic snapshots (which are not cheap!).

Specifications stories must be written with the storiesOf API in a *.chroma.jsx file.

A specifications story must:

  • Be located in the Chromatic top level section of the Storybook navigation menu.
  • The second level segment must be the capitalized name of the component (same as the development stories).

Here's an example:

// Button.chroma.jsx

import { paramsBuilder, storiesOfBuilder } from "@stories/utils";

function stories(segment) {
    return storiesOfBuilder(module, "Chromatic/Button")
        .segment(segment)
        .parameters(
            paramsBuilder()
                .build()
            )
        .build();
}

stories("/segment")
    .add("story-name",
         () =>
            ...
    )

The stories must be located in a tests/chromatic folder next to the src folder of your component. Storybook is configured to load the following tests specifications: packages/react-components/src/*/tests/chromatic/**.chroma.[jsx|tsx].

/packages
    /react-components
        /buttons
            /src
            /tests
                /chromatic
                    Button.chroma.jsx

For more information about the Storybook automated visual tests workflow, read the following blog post and the following introduction to visual testing.

Interaction testing

Since visual testing tools like Chromatic can't help much for interaction testing we rely on Jest](https://jestjs.io/) and React Testing Library for those. Similar to visual testing, interaction tests are validated every night.

NOTE: You should always prefer a visual test with Chromatic over an interaction test with Jest and React Testing Library. Chromatic tests are much quicker to write and easier to maintain.

Interaction tests must:

  • Be written in a *.test.[jsx|tsx] file.
  • Be located in a tests/jest folder next to the src folder of your component.
/packages
    /react-components
        /buttons
            /src
            /tests
                /jest
                    Button.test.jsx

Here's an example:

// Button.test.jsx

test("call onChange when the button is selected", () => {
    ....
});

Usually, interaction tests are split into 4 distinct regions: Behaviors, Aria, Api and Refs.

Component guidelines

Every Orbit UI custom components must share a consistent API and a similar design. Please read carefully the following guidelines before you develop a new component or update an existing one.

Design

Functional components

All components should be developed as functional components.

Hooks

All components should leverage React hooks.

Styling

An Orbit UI component shouldn't use Tachyons classes.

All styling should be done with native CSS. Custom classes should use Orbit UI foundation CSS variables when available.

Controlled & Auto-controlled

A component should always be develop to offer a controlled and auto-controlled usage.

A controlled component gives a lot of flexibility to the consumer and is well fit for a lot of use cases but also involve additional code. We believe a component should be flexible but also painless to use. That's why a component should also offer an auto-controlled mode for basic use cases who don't requires controlling the props.

Never stop event propagation

A component shouldn't stop the propagation of an event. Instead, other parts of the code should determine whether or not it should handle the event.

For more information, read the following blog post.

Handler event argument

Every component should provide the initiating event as the first argument when calling a user event handler.

const handleChange = event => {
    if (!isNil(onValueChange)) {
        onValueChange(event, event.target.value);
    }
});

Do the component stuff before calling the event handler

Before calling the user event handler always execute all the component logic related to the event.

const handleChange = event => {
    const newValue = event.target.value;

    // Call setValue before calling onValueChange.
    setValue(newValue);

    if (!isNil(onValueChange)) {
        onValueChange(event, newValue);
    }
});

Spread props

Unhandled props should always be spread on the root element of the component. If it's not practical to spread the props on the root element, consider adding an additional prop for the root element props (like wrapperProps) and spread those props on the root element.

function MyComponent({ className, children ...rest }) {
    return (
        <div className={className} {...rest}>
            {children}
        </div>
    );
}

Slots

All "slotable" components should accept an optionnal slot property.

As prop

A component should always accept an as prop and apply it to the root element of the component. The as prop allow the consumer to specify the type of the element to render. A default value should always be provided.

The following usage should be possible for all components:

<Button as="link" href="#>Click me!</Button>

Ref

A component should always accept a ref prop and apply it to the root element of the component.

Developer experience

Props and Typings

Every component and functions should provide static typings with TypeScript. For most required props, instead of defining the prop as required, you should instead provide a default value.

Naming

Event handlers props

Event handler props should be prefix by on and be in the present tense.

Ex:

  • Prefer onChange to onChanged
  • Prefer onItemClick to onItemClicked

Boolean props

A boolean prop shouldn't be prefix with is.

Ex:

  • Prefer open to isOpen
  • Prefer disabled to isDisabled

Prefer simpler props name

When there is no possible ambiguities, prefer a simpler prop name.

For example, prefer icon to inputIcon.

Initial values props name

Auto-controlled components will usually expose initial values props. Those props should be prefix with default.

Ex:

  • defaultOpen
  • defaultStartDate
  • defaultValues

Accessibility

All components should follow WAI-ARIA practices when applicable.

Babel

The components are transpiled to ES5 compatible code using babel. The babel configuration is located at the root of the react-components package.

The current configuration use babel-plugin-transform-runtime to optimize the file size of the components.

License

Copyright © 2019, GSoft inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE.

Dependents (2)

Package Sidebar

Install

npm i @orbit-ui/react-components

Weekly Downloads

15

Version

18.1.2

License

Apache-2.0

Unpacked Size

870 kB

Total Files

687

Last publish

Collaborators

  • infra.admin
  • patricklafrance
  • fraincs
  • alexasselin008