npm package: @sitecrafting/gearlab-tools-pattern-library
Description: The official GearLab Tools Pattern Library components and documenations 
Latest version: 0.1.0

# GearLab Tools Pattern Library

Proof of concept for the GearLab Tools Pattern Library doc site

## Getting started

In a Terminal window, install the dependencies:

```bash
yarn
```

In a Terminal window, run the dev server:

```bash
yarn start
```

In a second Terminal window, run the build process:

```bash
yarn build
```

This will watch your files and recompile on changes to any files inside `src/`.

## Development

Patterns are documented as `FancyComponent` instances inside `src/app.js`. Each `FancyComponent` is independent of the others and documents a separate use-case of one or more components or patterns. `FancyComponent` is fancy indeed; it knows how to render its children as literal HTML and how to escape and format that HTML for documentation purposes.

`FancyComponent` patterns are grouped together under a small number of `DocPage` components, which are how the side nav gets generated. The doc site code expects to see a `route` and `title` property on each `DocPage`. Each `FancyComponent` should have an `id` and `title`:

```jsx
    <DocPage route="/foundations" title="Foundations">
      <FancyComponent id="typography" title="Typography">
          <p className="u-medium-text">Lorem ipsum</p>{"\n"}

          <p className="u-plain-label">Minim proident ex...</p>
          <h1>The quick brown fox jumps over the lazy dog.</h1>
        </FancyComponent>
    </DocPage>
```

Note the whitespace literal (`{"\n"}`) above. This is completely optional and just tells React to insert a newline in the doc HTML snippet (since the actual blank line in the JSX above will be collapsed when React renders the snippet).

Instead of `FancyComponent`s, you can also use vanilla HTML elements inside a `DocPage`. As long as each on also has its own unique `title` and a unique `id`, it will be reflected in the nav structure and rendered like a normal element on the page. Use `<section>` elements for consistency's sake.

```jsx
    <DocPage route="/" title="Getting Started">
        <section id="introduction" title="Introduction">
            <h2>Introduction</h2>
            <p>Lorem ipsum dolor sit amet.</p>
        </section>
        <section id="installation" title="Installation">
            <h2>Installation</h2>
            <code>npm install some-code</code>
        </section>
    </DocPage>
```

The main `PatternLibrary` component in charge of rendering the doc site parses the components and renders each `DocPage`.

To define a new component, just add a `<FancyComponent>` inside one of the `DocPage` components in `src/app.js`. You can also add any number of new `DocPage` components; just make sure to include a `route` and a `title` prop on each so that the navigation component knows how to render it and which URL it points to.

### Full-page examples

For full-page examples that compose different components such as the [login page](https://projects.invisionapp.com/share/XRU2V0NFZUQ#/screens/385549256), we need HTML pages that live outside the regular pattern nav structure. Here's how to add these examples:

#### Step 1: add a subdirectory under `./docs/examples`

Each example gets its own directory inside `./docs/examples`. An example can consist of just an `index.html` inside its own example directory, or it can get as complex as you want it to.

#### Step 2: Link to your example URL from `PatternLibrary`

To link to your example, just set up a new link inside the `PatternLibrary` component itself. Note the one in there for `/examples/login` already.

#### Step 3: Add a Netlify redirect

The local dev server that gets spun up with `yarn start` will serve the route `/examples/my-example` from the file at `/docs/examples/my-example/index.html`. However, for serving this on Netlify we need to be more explicit and add this route directly. In the `netlify.toml` file, add a route for your example **before the final [[redirects]] block**, so that the last two redirects look like:

```toml
[[redirects]]
  from = "/examples/my-example"
  to = "/docs/examples/my-example/index.html"
  status = 200

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
```



# CSS Architecture

## File Structure/Organization
* Settings (less/settings)
  * variables
  * normalize
  * mixins

* Generic (less/generic)
  * global styles- bare elements (headings, links, base none class name styles)
  * utilities - utilities and/or rules that should trump

* Objects (less/objects)
  * Structural elements such as flexboxgrid

* Components (less/components)
  * Individual component styles


app.less - primary source of all css pieces imported for compilation.

Custom font import would be included at the top of this file before all other less files

## Naming Conventions- BEM
.block (primary part/component)
.block__element (a child element that depends on block)
.block--modifier (a modification to the default block)

## NameSpacing

* Utility Classes:  .u-utility{ … }
* Javascript Actions: .js-open-model
  * No styles should be associated with these classnames
* State: .is-state or .has-state
  * example: .has-error or .is-active
* Components: .c-btn, .c-nav-bar, .c-stat-card