npm package: @hackthenorth/north
Description: Hack the North's reusable component library
Latest version: 2.2.10

# North

[![Build status](https://badge.buildkite.com/b2b8131fe886259e29a798a08d1fbd3d87d5c7895455045d1c.svg)](https://buildkite.com/hack-the-north/north)

North is Hack the North's frontend component library, built for use in React.

### Check it out

👉👉👉 [See all the components](https://hackathon.github.io/north) 👈👈👈

### Usage

#### Installation

First, install the package in your project:

```
$ npm install --save @hackthenorth/north
```

#### Defining a theme

North components derive their styling from a **theme definition** file.

When creating a theme for North, you can provide the following in your theme definition:

- `globalStyles`: a `css` object that defines styles to be applied globally
- `globalConstants`: an object containing constants that you want to be able to access when defining styled components
- `deviceBreakpoints`: an object containing maximum width breakpoints for different device names
- `modifiers`: each North component can have two properties defined in the theme definition:

  - `sharedStyles`: similar to `globalStyles`, this defines styles shared by all instances of this specific North component
  - `mods`: each key you specify in this property will be a modifier name that can be specified when using a North component to apply the corresponding style values defined in `modifiers`. A component can use multiple modifiers using any format accepted by the [classnames library](https://www.npmjs.com/package/classnames). Example usage:

  ```js
    <Button mods="error"/>
    <Button mods=["error", "secondary"]>
    <Button mods={error: SOME_CONDITIONAL, secondary: ANOTHER_CONDITIONAL}>
  ```

An example of a theme definition can be found in `src/themes/storybook.ts`, and more detailed schemas can be found through the TypeScript interface definitions in the source code.

#### Providing theme to components

After your theme has been defined, provide it to North by wrapping your application with a `North` provider component.

```js
// yourApp.js
import { North } from "@hackthenorth/north"; // import the provider
import YOUR_THEME_DEFINITION from "path/to/your/theme-def/file"; // your theme definition file

const App = () => (
  <North themeDefinition={YOUR_THEME_DEFINITION}>
    // rest of your app here...
  </North>
);
```

#### Using components

To use a themed North component:

```js
import { Card } from "@hackthenorth/north"; // import the component

// ...your component...
return <Card mods="YOUR_MODIFIER_NAME" />;
// ...your component...
```

The modifier name should be defined in your theme definition under the `modifiers` property of the component you're using.

### Development

#### Setup

First, clone the repo:

```
$ git clone https://github.com/hackathon/north.git
$ cd north
```

Then install dependencies and get it running:

```
$ npm install
$ npm start
```

Navigate to `localhost:9001` in your browser. This will load the Storybook documentation for North, where you can see every component in the North component library.

#### Adding a new component

Here's a handy dandy checklist to cover when you're adding a new component:

- [ ] Make sure the component has its ref forwarded
- [ ] Make sure both the unstyled and themed versions of the component have `displayName`s set
- [ ] Add tests (if necessary) in a `.test.tsx` file
- [ ] Add stories in a `.stories.tsx` file
- [ ] Add the component to the `themeFromDefinition` function [here](https://github.com/hackathon/north/blob/master/src/components/North/index.tsx#L76) (in alphabetical order)
- [ ] Export the component with the rest of North [here](https://github.com/hackathon/north/blob/master/src/components/index.ts) (in alphabetical order)
- [ ] Add typings for the component and its props to both the `ThemeDefinition` and `Theme` interfaces [here](https://github.com/hackathon/north/blob/master/src/theme.ts) (in alphabetical order)

#### Releasing a new version

When changes are ready to be released, do the following:

1. Make a pull request from `master` into `release`
2. Prefix your pull request title with one of `[major]|[minor]|[patch]` based on the changes and (very roughly) according to [semantic versioning](https://semver.org/)
3. Merge once all CI/checks pass

The `hackthenorth-platform` bot will automatically tag the release based on the previous version and your prefix before building and publishing the new version of the package to npm.

### Tech stack

- React
- styled-components
- Jest
- Storybook
- Rollup
- Buildkite
- TypeScript
- Github Pages

Components are built with React, and written in TypeScript. Tests are written in Jest, and test functionality as well as snapshot comparisons. The website is just an instance of Storybook, deployed to Github Pages by Buildkite every time we publish a new version. Rollup is used to create the published package.

We use `styled-components` to apply styles and for the theming ability that it provides.

### Deprecated components

The `Carousel`, `Dropdown`, `Gallery`, and `ProgressBar` components are deprecated and removed as of `version`1.0` of North.

### Improvements

Check out the 2019 [shitlist](./shitlist.md) as a starting point.