JordanCWalsh/carbon

Carbon by Sage | ReactJS UI Component Library

Carbon

Carbon is a library of reusable React components and an interface for easily building user interfaces based on Flux.

Carbon Factory is supplementary to Carbon; providing tools to easily get your environment and project up and running to start building with React. As well as providing a command line interface to build projects, it manages tasks for compiling your assets and running test suites.

Check out our demo and documentation site for live examples and code snippets.

Documentation

Getting Started

• Setting up your environment
• An introduction to Node/npm
• Getting started
• A basic example of Flux

Guides

• Assets
• Flux
• Immutable
• Validations
• Decorators
• Handlers
• Retrieving Data
• Integrating React & Flux with Other UI

Testing

• Running Tests
• Help with Jest
• Debugging Tests
• Setting up Jest Cli

Tutorials

• Rails:
  • Hello world
  • Introducing data
  • Updating data
• Creating a component

Running the Example

Carbon has an example page, which demonstrates most of the components with a Flux implementation. This can be used to quickly see a demonstration of the components and/or as an area to test while developing with the components.

To run the example, do the following steps:

1. Clone the carbon repository (git clone git@github.com:Sage/carbon.git)
2. cd carbon
3. npm install
4. gulp
5. Navigate to http://localhost:8095/ in your favourite browser

Testing Changes Locally in your App

See the guide on installing unreleased changes

Submitting a Release

• N.B. Releases are created by Sage Carbon Team. We use semantic versioning

• If releasing a minor version, create a branch from master.

• If releasing a patch version, create a branch from the tag you want to patch. This should be the latest tag apart from exceptional circumstances.

• Bump the version in package.json.

• Ensure the CHANGELOG.md is up to date.

• Commit and push changes.

• If releasing a minor version, open a PR to master.

• If releasing a patch version, open a PR to release.

• Once merged, publish a release in GitHub using the new version number as the tag. Make sure to target the correct branch (master or release). This will auto-deploy to npm.

• If you have released from a branch other than master, open a PR to merge that branch back into master.

Technologies

The following is a list of technologies Carbon utilises:

• React (JSX) - Components are written using React, as well as the useful JSX syntax.
• Flux - If your application requires a heavy use of data and interaction, Carbon provides utilities for easily integrating Flux based data stores.
• Immutable.js - For better performance and data handling, the components rely on using immutable data.
• Node (CommonJS) - The components (or modules) are written using the CommonJS pattern. This allows for modularity and creating isolated/independent components.
• Browserify - In order to consume the modular components in the browser, the code is compiled through Browserify. This also allows managing other dependencies such as stylesheets and images.
• Gulp - To easily run tasks in development, the Gulp task runner is recommended.
• Babel (ES6) - To benefit from ES6 (and ES7) features, the code is compiled through Babel (this also compiles the JSX).

Licence

Carbon is licensed under the Apache-2.0 licence.

Copyright (c) 2017 Sage Group Plc. All rights reserved.