Emotion 10 docs

BREAKING_CHANGES_IN_V10.md

@@ -1,12 +1,12 @@
 # Breaking Changes
 
-* Only supports react@16.3 and above(+ preact)
-* functions in interpolations are stringified in css and cx calls(probably won't affect you very much, there's a warning about it in v9)
-* `create-emotion-styled` is gone, use the new styled api and a provider
-* The css prop doesn't work via the babel plugin. `jsx` can be manually imported from `@emotion/core` or [babel-plugin-jsx-pragmatic](https://github.com/jmm/babel-plugin-jsx-pragmatic) can be used. (should we make a babel preset for that?)
-* MORE STUFF THAT I CAN'T REMEMBER RIGHT NOW
-* emotion will not be stored on the global object so create-emotion only accepts 1 argument, the options
-* channel and createBroadcast from emotion-theming no longer exist
-* extractStatic is gone
-* create-emotion-server accepts the cache instead of the emotion instance
-* jest-emotion no longer accepts an emotion instance, only the options arg, it also requires a DOM now
+- Only supports react@16.3 and above(+ preact)
+- functions in interpolations are stringified in css and cx calls(probably won't affect you very much, there's a warning about it in v9)
+- `create-emotion-styled` is gone, use the new styled api and a provider
+- The css prop doesn't work via the babel plugin. `jsx` can be manually imported from `@emotion/core` or [babel-plugin-jsx-pragmatic](https://github.com/jmm/babel-plugin-jsx-pragmatic) can be used. (should we make a babel preset for that?)
+- MORE STUFF THAT I CAN'T REMEMBER RIGHT NOW
+- emotion will not be stored on the global object so create-emotion only accepts 1 argument, the options
+- channel and createBroadcast from emotion-theming no longer exist
+- extractStatic is gone
+- create-emotion-server accepts the cache instead of the emotion instance
+- jest-emotion no longer accepts an emotion instance, only the options arg, it also requires a DOM now

CONTRIBUTING.md

@@ -1,31 +1,31 @@
 ## Prerequisites
 
-* [Node.js](http://nodejs.org/) >= v7 must be installed.
-* [Yarn](https://yarnpkg.com/en/docs/install)
+- [Node.js](http://nodejs.org/) >= v7 must be installed.
+- [Yarn](https://yarnpkg.com/en/docs/install)
 
 ## Installation
 
-* Run `yarn` in the repository's root directory to install everything you need for development.
-* Run `yarn build` in the root directory to build the modules.
+- Run `yarn` in the repository's root directory to install everything you need for development.
+- Run `yarn build` in the root directory to build the modules.
 
 > NOTE:
 >
 > lerna is **NOT** used for installing packages. Only yarn is used. lerna is only used for publishing
 
 ## Running Tests
 
-* `yarn test` will run the tests once.
-* `yarn coverage` will run the tests and produce a coverage report in `coverage/`.
-* `yarn test:watch` will run the tests on every change.
+- `yarn test` will run the tests once.
+- `yarn coverage` will run the tests and produce a coverage report in `coverage/`.
+- `yarn test:watch` will run the tests on every change.
 
 ## Building
 
-* Run `yarn build` in the root directory to build the modules. (Required before publishing)
-* Run `yarn build PACKAGE_NAME ANOTHER_PACKAGE_NAME` to only build certain packages.
-* Run `yarn build:watch` to build packages on every change.
+- Run `yarn build` in the root directory to build the modules. (Required before publishing)
+- Run `yarn build PACKAGE_NAME ANOTHER_PACKAGE_NAME` to only build certain packages.
+- Run `yarn build:watch` to build packages on every change.
 
 ## Documentation Website Development
 
-* Run above installation steps and then
-* Run `yarn start:site` to run a development server of gatsby.
-* Run `yarn build:site` to create a build of the assets for the documentation website.
+- Run above installation steps and then
+- Run `yarn start:site` to run a development server of gatsby.
+- Run `yarn build:site` to create a build of the assets for the documentation website.

README.md

@@ -6,7 +6,6 @@
 
 **Emotion 10 is currently in beta, there are many breaking changes between versions, [for docs on Emotion 9 please go to the latest v9 tag](https://github.com/emotion-js/emotion/tree/v9.2.12/docs) or https://emotion.sh**
 
-
 [![Backers on Open Collective](https://opencollective.com/emotion/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/emotion/sponsors/badge.svg)](#sponsors) [![npm version](https://badge.fury.io/js/emotion.svg)](https://badge.fury.io/js/emotion)
 [![Build Status](https://img.shields.io/circleci/project/github/emotion-js/emotion/master.svg)](https://circleci.com/gh/emotion-js/emotion)
 [![codecov](https://codecov.io/gh/emotion-js/emotion/branch/master/graph/badge.svg)](https://codecov.io/gh/emotion-js/emotion)
@@ -25,13 +24,13 @@ Emotion is a performant and flexible CSS-in-JS library. Building on many other C
 
 Frequently viewed docs:
 
-* [Introduction](https://emotion.sh/docs/introduction)
-* [Install](https://emotion.sh/docs/install)
-* [CSS](https://emotion.sh/docs/css)
-* [Styled Components](https://emotion.sh/docs/styled)
-* [Composition](https://emotion.sh/docs/composition)
-* [Nested Selectors](https://emotion.sh/docs/nested)
-* [Media Queries](https://emotion.sh/docs/media-queries)
+- [Introduction](https://emotion.sh/docs/introduction)
+- [Install](https://emotion.sh/docs/install)
+- [CSS](https://emotion.sh/docs/css)
+- [Styled Components](https://emotion.sh/docs/styled)
+- [Composition](https://emotion.sh/docs/composition)
+- [Nested Selectors](https://emotion.sh/docs/nested)
+- [Media Queries](https://emotion.sh/docs/media-queries)
 
 ### Quick Start
 
@@ -87,36 +86,36 @@ Look here 👉 _[emotion babel plugin feature table and documentation](https://g
 
 ### Examples
 
-* [emotion website](site) [[Demo Here](https://emotion.sh)]
-* [next-hnpwa-guide-kit](https://github.com/tkh44/next-hnpwa-guide-kit) [[Demo Here](https://hnpwa.life)]
-* [reactivesearch](https://github.com/appbaseio/reactivesearch), a react UI library for Elasticsearch [[Website](https://opensource.appbase.io/reactivesearch/)]
-* [circuit-ui](https://github.com/sumup/circuit-ui), a react component library built at SumUp [[Storybook](https://sumup.github.io/circuit-ui/)]
-* [govuk-react](https://github.com/penx/govuk-react/), a React component library built for UK Government departments
-* **open a PR and add yours!**
+- [emotion website](site) [[Demo Here](https://emotion.sh)]
+- [next-hnpwa-guide-kit](https://github.com/tkh44/next-hnpwa-guide-kit) [[Demo Here](https://hnpwa.life)]
+- [reactivesearch](https://github.com/appbaseio/reactivesearch), a react UI library for Elasticsearch [[Website](https://opensource.appbase.io/reactivesearch/)]
+- [circuit-ui](https://github.com/sumup/circuit-ui), a react component library built at SumUp [[Storybook](https://sumup.github.io/circuit-ui/)]
+- [govuk-react](https://github.com/penx/govuk-react/), a React component library built for UK Government departments
+- **open a PR and add yours!**
 
 ### Ecosystem
 
-* [stylelint](https://github.com/stylelint/stylelint) - A mighty, modern linter that helps you avoid errors and enforce conventions in your styles.
-* [facepaint](https://github.com/emotion-js/facepaint)
-* [emotion-vue](https://github.com/egoist/emotion-vue)
-* [ember-emotion](https://github.com/alexlafroscia/ember-emotion)
-* [CSS to emotion transform](https://transform.now.sh/css-to-emotion/)
-* [ShevyJS](https://github.com/kyleshevlin/shevyjs)
-* [design-system-utils](https://github.com/mrmartineau/design-system-utils) - Utilities to give better access to your design system.
-* [polished](https://github.com/styled-components/polished) - Lightweight set of Sass/Compass-style mixins/helpers for writing styles in JavaScript.
+- [stylelint](https://github.com/stylelint/stylelint) - A mighty, modern linter that helps you avoid errors and enforce conventions in your styles.
+- [facepaint](https://github.com/emotion-js/facepaint)
+- [emotion-vue](https://github.com/egoist/emotion-vue)
+- [ember-emotion](https://github.com/alexlafroscia/ember-emotion)
+- [CSS to emotion transform](https://transform.now.sh/css-to-emotion/)
+- [ShevyJS](https://github.com/kyleshevlin/shevyjs)
+- [design-system-utils](https://github.com/mrmartineau/design-system-utils) - Utilities to give better access to your design system.
+- [polished](https://github.com/styled-components/polished) - Lightweight set of Sass/Compass-style mixins/helpers for writing styles in JavaScript.
 
 ### In the Wild
 
-* [healthline.com](https://www.healthline.com)
-* [nytimes.com](https://www.nytimes.com)
-* [vault.crucible.gg](http://vault.crucible.gg/)
-* [saldotuc.com](https://saldotuc.com)
-* [gatsbythemes.com](https://gatsbythemes.com/)
-* [blazity.com](https://blazity.com/)
-* [postmates.com](https://postmates.com/)
-* [thedisconnect.co](https://thedisconnect.co/one)
-* [zefenify.com](https://zefenify.com/about.html)
-* [sentry.io](https://sentry.io)
+- [healthline.com](https://www.healthline.com)
+- [nytimes.com](https://www.nytimes.com)
+- [vault.crucible.gg](http://vault.crucible.gg/)
+- [saldotuc.com](https://saldotuc.com)
+- [gatsbythemes.com](https://gatsbythemes.com/)
+- [blazity.com](https://blazity.com/)
+- [postmates.com](https://postmates.com/)
+- [thedisconnect.co](https://thedisconnect.co/one)
+- [zefenify.com](https://zefenify.com/about.html)
+- [sentry.io](https://sentry.io)
 
 ## Contributors
 

docs/babel.md

@@ -1,5 +1,5 @@
 ---
-title: "Babel Plugin"
+title: 'Babel Plugin'
 ---
 
 `babel-plugin-emotion` is highly recommended. All of the options that can be provided to `babel-plugin-emotion` are documented in [`babel-plugin-emotion`'s README](https://github.com/emotion-js/emotion/tree/master/packages/babel-plugin-emotion).

docs/class-names.md

@@ -0,0 +1,33 @@
+---
+title: 'Class Names'
+---
+
+It can be useful to create to create a className that is not passed to a component, for example if a component accepts a `wrapperClassName` prop or similar. To do this, Emotion exposes a render prop component which you can pass a function which accepts `css` and `cx`. If you have used versions of Emotion prior to Emotion 10 or used vanilla Emotion, the `css` and `cx` functions work exactly like they do in versions.
+
+```jsx
+// @live
+import { ClassNames } from '@emotion/core'
+
+// this might be a component from npm that accepts a wrapperClassName prop
+let SomeComponent = props => (
+  <div className={props.wrapperClassName}>
+    in the wrapper!
+    <div className={props.className}>{props.children}</div>
+  </div>
+)
+
+render(
+  <ClassNames>
+    {({ css, cx }) => (
+      <SomeComponent
+        wrapperClassName={css({ color: 'green' })}
+        className={css`
+          color: hotpink;
+        `}
+      >
+        from children!!
+      </SomeComponent>
+    )}
+  </ClassNames>
+)
+```

docs/composition.md

@@ -2,19 +2,20 @@
 title: "Composition"
 ---
 
-Composition is one of the most powerful and useful patterns in Emotion. You can compose styles together by interpolating the class name returned from `css` in another style block.
+Composition is one of the most powerful and useful patterns in Emotion. You can compose styles together by interpolating value returned from `css` in another style block.
 
 ```jsx
 // @live
-import { css } from 'emotion'
+/** @jsx jsx */
+import { jsx, css } from '@emotion/core'
 
 const base = css`
   color: hotpink;
 `
 
 render(
   <div
-    className={css`
+    css={css`
       ${base};
       background-color: #eee;
     `}
@@ -30,68 +31,72 @@ For example, we have some base styles and a danger style, we want the danger sty
 
 ```jsx
 // @live
-import { css } from 'emotion'
-
-const danger = css`
-  color: red;
-`
-
-const base = css`
-  background-color: lightgray;
-  color: turquoise;
-`
-
 render(
-  <div className={`${base} ${danger}`}>
-    What color will this be?
+  <div>
+    <style>
+      {`
+        .danger {
+          color: red;
+        }
+        .base {
+          background-color: lightgray;
+          color: turquoise;
+        }
+      `}
+      >
+    </style>
+    <p className="base danger">What color will this be?</p>
   </div>
 )
 ```
 
-With Emotion though, it's much easier, all we have to change is add `css` before the template literal where we combine the classes and Emotion will use the styles that were passed to danger and base and merge them in the order that they're interpolated.
+With Emotion though, we can create styles and combine them
 
 ```jsx
 // @live
-import { css } from 'emotion'
+/** @jsx jsx */
+import { css, jsx } from '@emotion/core'
 
 const danger = css`
   color: red;
 `
 
 const base = css`
-  background-color: lightgray;
+  background-color: darkgreen;
   color: turquoise;
 `
 
 render(
-  <div
-    className={css`
-      ${base} ${danger};
-    `}
-  >
-    What color will this be?
+  <div>
+    <div css={base}>This will be turquoise</div>
+    <div css={[danger, base]}>
+      This will be also be turquoise since the base styles
+      overwrite the danger styles.
+    </div>
+    <div css={[base, danger]}>This will be red</div>
   </div>
 )
 ```
 
-> Note:
->
-> This is just an example to demonstrate composition, for class name merging with emotion you should use [cx](/docs/cx.md).
-
 ## Composing dynamic styles
 
+## I FEEL LIKE THIS IS A REALLY SPECIFIC THING AND MORE NEEDS TO BE SAID ABOUT THE STUFF ABOVE
+
+## ALSO, WE PROBABLY NEED A PLACE TO TALK ABOUT PATTERNS
+
 You can also do dynamic composition based on props and use it in `styled`.
 
 ```jsx
 // @live
-import styled, { css } from 'react-emotion'
+import styled from '@emotion/styled'
+import { css } from '@emotion/core'
 
 const dynamicStyle = props =>
   css`
     color: ${props.color};
   `
 
-const Container = styled('div')`
+const Container = styled.div`
   ${dynamicStyle};
 `
 render(
@@ -105,14 +110,15 @@ If you're composing lots of other styles and aren't using any string styles dire
 
 ```jsx
 // @live
-import styled, { css } from 'react-emotion'
+import styled from '@emotion/styled'
+import { css } from '@emotion/core'
 
 const dynamicStyle = props =>
   css`
     color: ${props.color};
   `
 
-const Container = styled('div')(dynamicStyle)
+const Container = styled.div(dynamicStyle)
 
 render(
   <Container color="lightgreen">