Merge pull request #16 from helpscout/styled-theme-provider

Styled + ThemeProvider

.babelrc

@@ -1,3 +1,6 @@
 {
-  "presets": ["env", "react"]
+  "presets": ["env", "react", "flow"],
+  "plugins": [
+    "transform-object-rest-spread"
+  ]
 }

.prettierignore

@@ -0,0 +1,4 @@
+package.json
+package-lock.json
+dist/
+coverage/

.prettierrc.yml

@@ -0,0 +1,3 @@
+semi: false
+singleQuote: true
+trailingComma: es5

README.md

@@ -1,29 +1,27 @@
-# ❄️  Fancy [![npm version](https://badge.fury.io/js/%40helpscout%2Ffancy.svg)](https://badge.fury.io/js/%40helpscout%2Ffancy) [![Build Status](https://travis-ci.org/helpscout/fancy.svg?branch=master)](https://travis-ci.org/helpscout/fancy) [![Coverage Status](https://coveralls.io/repos/github/helpscout/fancy/badge.svg?branch=master)](https://coveralls.io/github/helpscout/fancy?branch=master)
+# ❄️ Fancy [![npm version](https://badge.fury.io/js/%40helpscout%2Ffancy.svg)](https://badge.fury.io/js/%40helpscout%2Ffancy) [![Build Status](https://travis-ci.org/helpscout/fancy.svg?branch=master)](https://travis-ci.org/helpscout/fancy) [![Coverage Status](https://coveralls.io/repos/github/helpscout/fancy/badge.svg?branch=master)](https://coveralls.io/github/helpscout/fancy?branch=master)
 
 > A simple way to include CSS with React Components.
 
-* **Tiny**, around 1.7 KB gzipped
-* **One dependency** - ([Stylis](https://github.com/thysultan/stylis.js))
-* **Write** plain ol' CSS. Period.
-* **Pre-processing** when you need it. Powered by [Stylis](https://github.com/thysultan/stylis.js).
-* **Uniquely** generated classNames, [CSS Modules](https://github.com/css-modules/css-modules) style.
-* **Integrate** with ease into your existing setup. No fiddling with Webpack required.
-
+- **Tiny**, around 2.05 KB gzipped
+- **One dependency** - ([Stylis](https://github.com/thysultan/stylis.js))
+- **Write** plain ol' CSS. Period.
+- **Pre-processing** when you need it. Powered by [Stylis](https://github.com/thysultan/stylis.js).
+- **Uniquely** generated classNames, [CSS Modules](https://github.com/css-modules/css-modules) style.
+- **Integrate** with ease into your existing setup. No fiddling with Webpack required.
 
 ## 🔧 Installation
 
 ```
 npm install --save @helpscout/fancy
 ```
 
-
 ## 🕹 Usage
 
 Here's a quick example of how you can compose regular CSS with your React components.
 
 ```jsx
 import React from 'react'
-import fancy from '@helpscout/fancy'
+import styled from '@helpscout/fancy'
 
 const css = `
   .Button {
@@ -40,10 +38,9 @@ const Button = props => {
   </button>
 }
 
-export default fancy(css)(Button)
+export default styled(Button)(css)
 ```
 
-
 ## 📘 Documentation
 
 [View the docs](./docs/) to get started with Fancy!

docs/README.md

@@ -1,6 +1,7 @@
 # Documentation
 
-* [Getting Started](./getting-started.md)
-* [Nesting](./nesting.md)
-* [Dynamic Styles](./dynamic-styles.md)
-* [Dynamic ClassNames](./dynamic-classnames.md)
+- [Getting Started](./getting-started.md)
+- [Nesting](./nesting.md)
+- [Dynamic Styles](./dynamic-styles.md)
+- [Dynamic ClassNames](./dynamic-classnames.md)
+- [Theming](./theming.md)

docs/dynamic-classnames.md

@@ -4,7 +4,6 @@ In this guide, we're going to be using dynamic classNames generated by Fancy (in
 
 This feature was popularized by [CSS Modules](https://github.com/css-modules/css-modules).
 
-
 ### Basic Example
 
 Fancy provides you with a "styles" prop, that contains unique classNames that is generated from and maps to your defined CSS.
@@ -22,7 +21,7 @@ const css = `
     border: 1px solid black;
   }
 `
-const StyledCard = fancy(css)(Card)
+const StyledCard = styled(Card)(css)
 ```
 
 #### Result (CSS)
@@ -46,8 +45,6 @@ Fancy **preserves** your original className. This is allow for reusability of yo
 
 Note: This feature is **only available** to class-based selectors. Selectors like `div` or `#id` will not receive unique classNames.
 
-
-
 ### BEM example
 
 Fancy will generate unique classNames for BEM-style nested selectors.
@@ -71,7 +68,7 @@ const css = `
     }
   }
 `
-const StyledCard = fancy(css)(Card)
+const StyledCard = styled(css)(Card)
 ```
 
 #### Result (CSS)
@@ -90,8 +87,6 @@ const StyledCard = fancy(css)(Card)
 }
 ```
 
-
-
 ### Multiple classNames example
 
 Fancy's unique className generator isn't limited to a single className scope. Include as many as you need!
@@ -115,7 +110,7 @@ const css = `
     padding: 20px;
   }
 `
-const StyledCard = fancy(css)(Card)
+const StyledCard = styled(css)(Card)
 ```
 
 #### Result (CSS)
@@ -134,8 +129,6 @@ const StyledCard = fancy(css)(Card)
 }
 ```
 
-
-
 ### Sibling classNames
 
 Fancy allows for you to create sibling rules, indicated by `+` or `~`.
@@ -157,7 +150,7 @@ const css = `
     }
   }
 `
-const StyledCard = fancy(css)(Card)
+const StyledCard = styled(css)(Card)
 ```
 
 #### Result (CSS)

docs/dynamic-styles.md

@@ -9,18 +9,17 @@ You can define dynamic styles by passing a `function` into `fancy`. It will have
 ### Example
 
 ```jsx
-const Card = props => (<div {...props} />)
-const css = (props) => `
+const Card = props => <div {...props} />
+const css = props => `
   div {
     background: ${props.title ? 'red' : 'blue'};
     position: relative;
     border: 1px solid black;
   }
 `
-const StyledCard = fancy(css)(Card)
+const StyledCard = styled(Card)(css)
 ```
 
-
 ### 🤔 How does it work…
 
 Under the hood, Fancy does a `diff` check in it's virtual Stylesheet (not unlike how React handles VDOM diffing) every time a [component updates](https://reactjs.org/docs/react-component.html#componentdidupdate). If an update occurs, it regenerates the style rules and re-injects it into the document stylesheet.

docs/getting-started.md

@@ -9,7 +9,6 @@ import React from 'react'
 import fancy from '@helpscout/fancy'
 ```
 
-
 ### Step 2: Define your styles
 
 Write your CSS styles as a string. This is default out-of-the-box CSS. Use things like `:hover`, `@media` queries, as you normally would!
@@ -25,29 +24,24 @@ const css = `
 
 Note: You can of course use string interpolation. It's still JS after all!
 
-
 ### Step 3: Create your component
 
 Create your component as you normally would.
 
 ```jsx
-const Button = props => (
-  <button className='Button' {...props} />
-)
+const Button = props => <button className="Button" {...props} />
 ```
 
 Note: The reference the CSS `className` to match the CSS you wrote. Fancy does not generated uniquely hashed classNames for you. See [CSS Modules](https://github.com/css-modules/css-modules) for that feature.
 
-
 ### Step 4: Compose your CSS with your component
 
 When exporting your component, compose it with the `fancy` higher-order component along with your CSS styles.
 
 ```jsx
-export default fancy(css)(Button)
+export default styled(Buton)(css)
 ```
 
-
 ### Final code
 
 ```jsx
@@ -61,11 +55,9 @@ const css = `
   }
 `
 
-const Button = props => (
-  <button className='Button' {...props} />
-)
+const Button = props => <button className="Button" {...props} />
 
-export default fancy(css)(Button)
+export default styled(Button)(css)
 ```
 
 ### Results

docs/nesting.md

@@ -2,7 +2,6 @@
 
 Fancy comes with [stylis](https://github.com/thysultan/stylis.js), a tiny CSS pre-processor. This (amazing) little library provides nifty features like nesting, similar to what you'd get with Less or Sass.
 
-
 ### Example
 
 ```jsx
@@ -19,12 +18,10 @@ const css = `
 `
 
 const Card = props => (
-  <div className='Card'>
-    <div className='Card__block'>
-      {props.children}
-    </div>
+  <div className="Card">
+    <div className="Card__block">{props.children}</div>
   </div>
 )
 
-const StyledCard = fancy(css)(Card)
+const StyledCard = styled(Card)(css)
 ```

docs/theming.md

@@ -0,0 +1,53 @@
+# Theming
+
+Fancy comes with `Theme.Provider`. Added to the top-level of your app, it can modify fancy styled components via a special `props.theme` prop.
+
+Define your theme props to `Theme.Provider` as `theme`.
+
+### Example
+
+```jsx
+import styled, { ThemeProvider } from '@helpscout/fancy'
+
+const css = props => `
+  .Card {
+    background: ${props.theme.dark ? 'black' : 'white'};
+    position: relative;
+    border: 1px solid black;
+  }
+`
+
+const Card = props => (
+  <div className="Card">
+    <div className="Card__block">{props.children}</div>
+  </div>
+)
+
+const StyledCard = styled(Card)(css)
+
+const App = () => {
+  ;<div id="App">
+    <ThemeProvider theme={{ dark: true }}>
+      <div>
+        ...
+        <StyledCard />
+        ...
+      </div>
+    </ThemeProvider>
+  </div>
+}
+```
+
+## Scoping
+
+`Theme.Provider` has another special `scope` prop that allows you to define additional selectors to scope your fancy `styled` component CSS under.
+
+### Example
+
+```jsx
+<ThemeProvider scope="html #App">
+  <StyledCard />
+</ThemeProvider>
+```
+
+If the hashed CSS classes for `StyledCard` was `.Card__213jdhx`, they will now render as `html #App .Card__213jdhx`.