Sullivan
===========
*Totally WIP: Here be dragons*

**What?**

Opinionated toolkit to quickly build visual interfaces in JS.

**Why?**

:white_check_mark: Because we're humans who make mistakes and need constraints around a predefined styleguide.
:white_check_mark: Because some css patterns are really annoying to rewrite all the time.
:white_check_mark: Because there are too many different ways to peel this potato (styling in JS) and sometimes we just want to write code.
:white_check_mark: Because we're lazy developers.

**How?**

Uses Aphrodite [https://github.com/Khan/aphrodite](https://github.com/Khan/aphrodite) under the hood to dynamically generate classnames and inject styles.

Prefixes everything so you don't have to think about it (thanks to Aphrodite);

Provides a library of functional css styles generated according to passed in styleguide values.

Abstracts around overly verbosed css syntaxes.

Includes a set of transform functions to inject dynamic styles.

Sullivan is built with React in mind but doesn't depend on it so can be used in other non-react project.

## Installation

Using [npm](https://www.npmjs.com/):

    $ npm install sullivan

Then with a module bundler like [webpack](https://webpack.github.io/) that supports either CommonJS or ES2015 modules, use as you would anything else:

```js
// sully.js
// using an ES6 transpiler, like babel

import Sullivan from 'sullivan'
import {StyleSheet, css} from 'aphrodite'
import Styleguide from './styleguide' // BYOS - Bring Your Own Styleguide!

```

## Usage

Initialize the singleton somewhere in your project, Sullivan comes with opinional defaults but you should pass in your own map of values according to your project styleguide.

####**for a detailed example check out [The example project](https://github.com/adrianleb/sullivan/blob/master/example/index.js)**



```js
// ...

const sully = new Sullivan({
  aphroditeStylesheet: StyleSheet,
  styleguide: Styleguide
});
export default sully;


// Alternatively you can also export just set of things to work with using a convention your team agrees on.
const {utils: classes, rawUtils: raw, inline, mq, z, styleguide} = sully;
const {colors, sizes, textSizes} = styleguide;

export {
  classes,
  raw,
  inline,
  mq,
  z,
  colors,
  sizes,
  textSizes
}

```

Then inside your component:

```js
// component.js
import {classes, inline, raw, lineHeights} from './sully';

const FunkyComponent = () => {
  return (
    <div
      className={css(
        ss.wrap,
        classes.flex.center,
        classes.text.yellow,
        classes.bg.cover
      )}
      style={
        inline.bg.image("https://placekitten.com/200/300")
      }>
      Content will be flex centered and yellow with a pretty kitten covering the background!
    </div>
  );
};

const ss = StyleSheet.create({
  wrap: {
    ...raw.bg.blue,
    ...raw.ma.large,
    lineHeight: lineHeights.loose
  }
});
```

### Using your own Styleguide
When bootstraping Sullivan you must pass in a styleguide configuration containing:
- `sizes`: for margins and paddings
- `colors`: for backgrounds, text colors, svg colors...
- `textSizes`: for text sizes (good ol' typography)
- `lineHeights`: for text sizes (good ol' typography)
- `z`: for depth mapping, (default to z[0-9])

[You can see an example styleguide here](https://github.com/adrianleb/sullivan/blob/master/example/styleguide.js)

A styleguide map is an object with a human readable keys (to be used across utils) and values, with the exception of z-index and reset styles handling
You're welcome to call your keys anything you want, just be careful not to make them clash (for example, calling a color 'medium' and a textSize 'medium' will break your text utils).

## API

### `sheet`
Alias for Aphrodite's `StyleSheet` object.
`sheet.create` will generate a new set of unique classnames ready for injection, based on a passed in object of styles.

### `class`
Alias for Aphrodite's `css` object.
Combines generated classnames (either from `StyleSheet.create` or from `sullivan.util`) left to right and injects styles into document `head`.

### `rawUtil`
Catalogue of small abstractions around common css patterns.

### `util`
Same as `rawUtils` but pre-transformed by Aphrodite's `Stylesheet.create` method and ready for injection using `class`

### `inline`
Functional utils returning an object with a transformed css declaration.

### `z`
the same object passed in (or the default) of z-indexes to be used in custom stylesheets.

##Utils
New utils are constantly being added, this is the current list:
- spacing
- pos
- disp
- bg
- svg
- text
- flex
- cursor

#### Spacing
**Requires sizes**

Mapping to margins and paddings according to passed in size values,
for ease of use they are not namespaced by `spacing` but shorthanded based on their function:
- `ma/pa`: Margin/Padding All (top, right, bottom, left)
- `mv/pv`: Margin/Padding Vertical (top, bottom)
- `mh/ph`: Margin/Padding Horizontal (right, left)
- `mt/pt`: Margin/Padding Top
- `mb/pb`: Margin/Padding Bottom
- `ml/pl`: Margin/Padding Left
- `mr/pr`: Margin/Padding Right

The values are based on what you pass through the `sizes` argument.
Example based on defaults:
`utils.mt.small // outputs a classname with {margin-top: 5px}`

#### Disp
**No requirements**

Mapping to css display values
- `inline` : {display: inline}
- `inlineBlock` : {display: inline-block}
- `block` : {display: block}
- `flex` : {display: flex}
- `none` : {display: none}

Example:
`util.disp.flex // outputs a classname with {display: flex}`

#### BG
**Requires colors**

Mapping to background-color values according to passed in colors, also a small set of quick patterns.

Example based on defaults:
`util.bg.black // outputs a classname with {background-color: '#000'}`

##### bg.cover
Outputs:
```css
{
  background-size: 'cover',
  background-position: 'center',
  background-repeat: 'no-repeat'
}
```

#### SVG
**Requires colors**

Mapping to fill values according to passed in colors.
Example based on defaults:
`util.svg.black // outputs a classname with {fill: '#000'}`

#### Z
**Requires z**

Mapping to z-index values according to passed in z map.
Example based on defaults:
`util.z.z1 // outputs a classname with {z-index: '1'}`

z-index is a special case because beside the private API here provided you should also apply your own pattern on top with what makes sense to you:
```
sullivan.myZ = {
 nav: sullivan.z.z5,
 modal: sullivan.z9
 // etc...
}
```


#### Text
**Requires textSizes and colors**

Mapping to color, size and weights values according to passed in maps and a set of utils
Example color based on defaults:
`util.text.black // outputs a classname with {color: '#000'}`

Example size based on defaults:
`util.text.small // outputs a classname with {font-size: '12px'}`

Example line-height based on defaults:
`util.text.loose // outputs a classname with {line-height: 1.2}`

Example weight:
`util.text.light // outputs a classname with {font-weight: '300'}`

##### text.truncate
Outputs:
```
{
  max-width: 100%;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}
```

#### Flex
Mapping around the flex syntax (which can be a bit verbosed), also a small set of quick patterns.

Properties:
- `align`: alignItems
- `alignSelf`: alignSelf
- `justify`: justifyContent

Values:
- `Start`: flex-start
- `End`: flex-end
- `Center`: center
- `Around`: space-around
- `Between`: space-between

With properties and values combined they summon earth's greatest champion (yes, this is a captain planet reference):
`util.flex.alignEnd // outputs a classname with {align-items: 'flex-end'}`
`util.flex.justifyAround // outputs a classname with {justify-content: 'space-around'}`

##### flex.center
Outputs:
```
{
  display: 'flex',
  align-items: 'center',
  justify-content: 'center'
}
```

##### flex.column
Outputs:
```
{
  display: 'flex',
  flex-direction: 'column'
}
```
If you need to do anything else with flex, you're on your own.

## TODO
- Finish this readme file.
- Truncation text util.
- A helper to generate a "living styleguide" page based on passed in values and used utils.
- Some tests would be nice.
- A website would be cool.

# Contributing
Please do, this is built on top of other amazing open-source projects and belongs to the community.
- Ideas? suggest anything over an Issue or PR!
- Suggestions? Read above!
- bugs? Read above!
- this code smells and you can do better? Yes! You know what to do!

# Special Thanks
This project initially sparked from working on small to big scale React.js related projects and feeling the pains of using CSS in JS, special mention to [Kontor.com](http://kontor.com) for giving me room to introduce and mature some of these concepts, also [@colindresj] (https://github.com/colindresj) and [@dkozma](https://github.com/dkozma) for brainstorming ideas and giving suggestions.

# License (MIT)

Copyright (c) 2016 Adrian le Bas

Includes works from https://github.com/Khan/aphrodite, which is MIT licensed with the following copyright:

Copyright (c) 2016 Khan Academy

Which itself includes work from other libraries...