Apolitical Styleguide
=====================

[![NPM](https://img.shields.io/npm/v/@apolitical/styleguide.svg)](https://www.npmjs.com/package/@apolitical/styleguide)

A re-usable collection of React Components for Apolitical's various UIs. Frontend Applications.

A reference UI is hosted on Gitlab Pages at https://apolitical.gitlab.io/styleguide - see [.gitlab-ci.yml](.gitlab-ci.yml).

Usage
-----

Install as a dependency:

```shell static
yarn add @apolitical/styleguide
```

This library is exported as `ApoliticalStyleguide`.
You must provide the following libraries:
`React`, `ReactDOM`, `ReactModal`, `ReactRouterDOM`, `styled`, `Supercluster`

> **Important**
>
> There are several peer dependencies you may wish to bring in, depending on what components you
> use. At the very least you will need `React` and `styled`. You must provide these as
> UMD modules. If you are using webpack the WebpackCdnPlugin will help you:
>
> `webpack.config.js`
> ```js static
> ...
> plugins: [
>   new WebpackCdnPlugin({
>     modules: {
>       react: [
>         { name: 'react', var: 'React', path: `umd/react.${prod ? 'production.min' : 'development'}.js` },
>         { name: 'react-dom', var: 'ReactDOM', path: `umd/react-dom.${prod ? 'production.min' : 'development'}.js` },
>         { name: 'react-router-dom', var: 'ReactRouterDOM', path: `umd/react-router-dom${prod ? '.min' : ''}.js` },
>         { name: 'styled-components', var: 'styled', path: `dist/styled-components${prod ? '.min' : ''}.js` },
>         // Optional
>         { name: 'react-modal', var: 'ReactModal', path: `dist/react-modal${prod ? '.min' : ''}.js` },
>         { name: 'supercluster', var: 'SuperCluster', path: `dist/styled-components${prod ? '.min' : ''}.js` },
>         // Must come last
>         { name: '@apolitical/styleguide', var: 'ApoliticalStyleguide', path: 'dist/index.js' },
>       ],
>     },
>   }),
> ]
> ```
> See externals in [webpack.config.js](webpack.config.js) for all dependencies.

Then, you can use our React components.

```js static
import { Atom, Molecule, Organism } from './index';
```

You can see a [full list of components here](https://apolitical.gitlab.io/styleguide/).

You will also want to bring the theme, by creating a wrapper:

```jsx static
import { Theme } from './index';
const { ApoliticalBrand, ApoliticalGlobalStyles } = Theme;

export default ({ children }) => (
  <>
    <ApoliticalGlobalStyles />
    <ThemeProvider theme={ApoliticalBrand}>
      {children}
    </ThemeProvider>
  </>
)
```

### Environments

There are several "environments" to be aware of. These are managed via `yarn` (or `npm` if you prefer):

#### `yarn run dev`

Use while working on the styleguide to start a development server and other tools for interactive work / testing.
The styleguide should become avalable at http://localhost:6060/ .
`dev-lite` is less resource-intensive, but `dev` is preferred. It uses the `development` webpack environment.


#### `yarn run build`

Produces the styleguide library which is imported into other projects. It uses the
`lib` webpack environment.

#### `yarn run build:analyze`

Produces the styleguide library *and* starts any profiling tools to help locate any issues. This
does not self terminate and therefore should not be used in CI. It uses the `analyze` webpack environment.

#### `yarn run build:styleguide`

Builds a static version of the styleguide. It uses the `production` webpack environment.


### Developing with Styleguide

#### `yarn run start`

This will make a local version of the styleguide available at `http://localhost:6060`
To link the local version of styleguide to the project that you are using it in:


### Linking to other repositories for local development

Sometimes you'll want to link your work in progress styleguide to another repo so you can test things in realtime without having to keep publishing to npm.

We've run into trouble getting the traditional yarn link to work, so `yalc` is an alternative method.
Try it with yarn link first, and if you cannot see the other repo updating with your changes, you can try yalc.

#### Linking with yarn

* In the styleguide repository in the terminal, while the project is not running, run `yarn link && yarn run dev`
* This creates what's called a symlink. This makes the project available locally for a node_module package to point to.
* In the project you'd like to use your local Styleguide in, run `yarn link "@apolitical/styleguide"`. This will tell that project's node_modules to point the `@apolitical/styleguide` package at your locally running package. Running `yarn install` after this will overwrite it with the released remote package. You can also run `yarn unlink @apolitical/styleguide` in your project and `yarn unlink` in the styleguide to unlink the two/break the symlink.

#### Linking with yalc

[Yalc documentation](https://github.com/whitecolor/yalc)

1. Run `yarn global add yalc` - this is a global install on your computer
2. In Styleguide, run `yalc publish`
3. In the repo you want to link to, run `yalc link @apolitical/styleguide`
4. Each time you make a change in Styleguide, you can run `yalc push` in Styleguide repo and these changes should reflect in the linked repo. If changes do not show up, try `yalc publish --push`
5. Add `.yalc/` and `yalc.lock` to your `.gitignore` file if it is not already there. This is just for local development, we don't want to commit yalc files.

** Note **

When you're done, you can run a regular `yarn install @apolitical/styleguide` in the linked repo to overwrite the yalc version, or run `yalc remove @apolitical/styleguide` in the linked repo.

Double check that the package in your linked repo's `package.json` is pointing to `@apolitical/styleguide`. `yalc link` should not touch the `package.json`, but it's wise to double check.


#### `Troubleshooting`

* **I can't see my changes**
Styleguide builds itself down to a minified file, found in `dist/umd.js`. Any other project that uses this as a package will read from this file. Sometimes, it doesn't update quickly, or it might need a nudge to do it.
If you are not seeing your changes, double check that you have run the project with `yarn run start:build`, as this tells it to update the `umd.js` file when it detects changes.
Try be patient, as sometimes it takes a minute or so for the linked project/project that is using this to receive the updated `umd.js` file.
Failing that, you can try to delete the `dist` folder and then run `yarn run build` to build it again.

* **I can't override styles when I import the components**
If you want your styleguide component to allow a user to override its styles, you need to add `className` as a prop.
ie.:
`export default ({className}) => <Box className={className} />;`
Then, in the repo you're using this component you'd do something like:
`const NewBox = styled.Box` and apply your styling in there.
StyledComponents does some work under the hood to auto generate classNames, but will not accept overrides without `className` being passed in.

Contributing
------------

If you want to help, that's brilliant! Have a look at our [Contributing Guide](CONTRIBUTING.md). We also adhere to a
[Code of Conduct](CODE_OF_CONDUCT.md), so please check that out, it includes details on who to contact if you have any
concerns.