React Magma

Getting started with React Magma in your application

Setup Requirements

1. Your project needs to be running React v16.5 or greater

Add the react-magma components to your project

npm install --save react-magma-dom

Documentation Site

For more information on using React Magma, see the React Magma Documentation

This site has general usage information, as well as information on all of the available components, including code examples and demos. It also has design guidelines from the UX team with more details about the why and when to use each component in your project.

Contributing to React Magma

System Dependencies

Node v14.x or greater with npm 7.1.x or greater

Steps to Run Documentation locally

1. Clone this repo:

git clone git@github.com:cengage/react-magma.git

2. Install the project's dependencies with the npm ci command

   Why npm ci?

   Using npm ci instead of npm install will install dependencies based on package-lock.json so you will get specific package versions and it should also speed up the install.

npm ci

3. Run Storybook to view examples of each component with

npm run storybook

View Storybook examples at http://localhost:6006/.

4. Run the development server for the docs site. You can run the docs from the repository root with

npm run docs

or from the package directory with

cd packages/react-magma-docs
npm run develop

Visit the docs at http://localhost:3000. The docs will not reflect local changes in the CodeSandbox examples.

Project Structure

The project is built using a monorepo structure with the help of Lerna.

Each folder under the packages folder is it's own, independent package. Each package can be built and deployed as a node module, or in the case of an app like react-magma-docs, it can be built and served as if it had its own repository.

Lerna handles dependencies within the monorepo, using symlinks to connect dependent packages. For example,react-magma-docs uses react-magma-dom. When a dependent project is build the consuming project automatically gets the latest build.

Source Organization

The project is broken out into multiple packages.

The react-magma-dom package is the React components for use in a browser. We followed this naming convention to leave room for react-magma-native and potentially other render targets in the future.

The react-magma-docs package handles the React Magma documentation, and is built on the Gatsby framework.

The react-magma-icons package handles all of the SVG icons in the React Magma library. Being in a separate package allows for changes or additions to the icons to happen without consumers having to update the whole component library.

Adding new components

React-Magma uses PlopJS to scaffold new components. This simultaneously increases consistency with new components and speeds up the time it takes a developer to get started with a new component. Simply run npm run plop and answer the prompts. This will create a skeleton for the component with stories, tests and a page in the documentation.

Building

Once you have finished making your code changes within a package run npm run build or npm run build-watch from inside that package.

You must build before your changes will be reflected in the browser.

Running Tests

Each package has a test command. You can run them from the individual package, or you can run them from the root of the project.

Running npm run test or npm run test-watch from inside a specific package will run the tests for that package.

Running npm run test from the repository root will run the test command for all packages that include tests.

You can also run specific tests from the repository root with:

# run the dom tests
npm run test-dom

npm run covg to see the generated lcov coverage reports.

Wallaby.js

This repository contributors are welcome to use Wallaby.js OSS License to get test results immediately as you type, and see the results in your editor right next to your code.

Updating the Docs

The react-magma-docs is the project for the documentation site. Any changes to the public API of an existing component or the creation of a new component must be accurately captured documented here.

This project uses MDX, allowing the combination of Markdown and React components.

Each component has its own .mdx file. If you have created a new component you will need to create a new .mdx file under the pages/api folder. If you have updated an existing component, you will need to review the existing docs page and update it as needed.

Creating a Docs Page

Add in the navigation details at the top of the page in the front matter.

---
pageTitle: '{ComponentName} API'
title: '{ComponentName}'
props:
  - {ComponentName}Props
---

Import the ScopeableLayout component. You may also need other things, such as components from react-magma-dom to use outside of examples (such as an Alert), or theLink from gatsby to link to other pages.

import { ScopeableLayout } from '../../components/layout';

Add the ScopeableLayout component to the bottom of the file.

export default props => <ScopeableLayout {...props} />;

Page Heading

The heading for the docs page can be created by using markdown with the following syntax:

[{ComponentName}]("/design/{component} 'api')

The URL following the name of the component is the link to respective Designs Docs page, and is optional. The api string indicates that the page is in the Component API.

Alternatively, you can also import the DocsHeading component and use the component with the appropriate props.

import { DocsHeading } from '../../components/DocsHeading;

<DocsHeading to="/design/{component}/" type="api">

CodeSandbox Examples

Create a basic usage example and an example for each of the different use cases of the component, using CodeSandbox.

```tsx codesandbox=magma
import React from 'react';
import { ComponentName } from 'react-magma-dom';

export function Example() {
  return <ComponentName />;
}
```

Interfaces and Property Tables

The property tables that we use are generated automatically, but require some wiring up. The interface in the typescript file must be annotated with typedoc comments. You will also need to add the needed props to the frontmatter in the mdx file. This will allow for our props table component to match the props referenced in the frontmatter to build out the props table. For example:

/**
 * @children required
 */
export interface SomeComponentProps
  extends React.HTMLAttributes<HTMLDivElement> {
  /**
   * The description for a component prop.
   * @default "the default prop value"
   */
  someOptionalComponentProp?: string;
}

---
pageTitle: Some Component API
title: Some Component
props:
  - SomeComponentProps
---

## Examples

...

## props

<SomeComponentProps />

Storybook Examples

React Magma uses Storybook for local testing of individual UI components. Each component should have a Storybook story that reflects each of its variations in state. TThe story files live along side the individual component files. Run Storybook from the root folder:

npm run storybook

Committing Code

This project adheres to SemVer and enforces a specific commit message format.

Commit messages for this project follow the conventional commit format.

This is enforced with a commit-msg hook via Husky which also runs linting, prettier and tests prior to allowing a commit.

To make it easier to adhere to this format, there is a root level npm script that will help format your commit message.

After adding your files to the git stage, run:

npm run cm

#format - with subject
git commit -m "<topic>(<subject>): <short description>"

#example - with subject
git commit -m "feat(button): Added icon capabilities to button"

#format - no subject
git commit -m "<topic>: <short description>"

#example - no subject
git commit -m "feat: Added icon capabilities to button"

#format
git commit -m "<type>(subject): <short description>

<optional body>

<optional footer>"

#example
git commit -m "feat(button): Added icon capabilities to button

More verbose description of what was added with the icon feature of the button.

BREAKING CHANGE: description of what part of the API brakes with this commit"