Emotion 10 docs

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/css-prop.md

@@ -1,8 +1,8 @@
 ---
-title: "The css Prop"
+title: 'The css Prop'
 ---
 
-The primary way to style things in emotion is with the css prop, to use the css prop you need to ...jsx comment
+The primary way to style things in emotion is with the css prop, to use the css prop you need to import `jsx` from `@emotion/core` and set it as the jsx pragma by adding a comment like this `/** @jsx jsx */`
 
 To pass string styles, you must use `css` which is exported by `@emotion/core`, it can be used as a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) like below.
 
@@ -28,7 +28,7 @@ render(
 )
 ```
 
-You can also pass objects directly to the css prop, for more usage with objects, go [here](/docs/object-styles.md).
+You can also pass objects directly to the css prop, for more usage with objects, look at [the object styles page](/docs/object-styles.md).
 
 ```jsx
 // @live

docs/docs.yaml

@@ -17,7 +17,7 @@
     - with-props
     - theming
     - labels
-    - instances
+    - class-names
     - migrating-to-emotion-10
     #- benchmarks
 

docs/keyframes.md

@@ -1,8 +1,8 @@
 ---
-title: "Keyframes"
+title: 'Keyframes'
 ---
 
-If you need more control over an animation, you can use `keyframes` with the same JS interpolation as `css`. The `keyframes` function takes in a css keyframe definition and returns an animation name so that you can include it in other styles. This is similar to how `css` takes in styles and returns a className that you can use to apply the styles.
+If you need more control over an animation, you can use `keyframes` with the same JS interpolation as `css`. The `keyframes` function takes in a css keyframe definition and an object which can be interpolated in styles.
 
 ```jsx
 // @live
@@ -30,8 +30,7 @@ const bounce = keyframes`
 render(
   <div
     css={css`
-      animation: ${bounce.name} 1s ease infinite;
-      ${bounce.styles};
+      animation: ${bounce} 1s ease infinite;
     `}
   >
     some bouncing text!

docs/migrating-to-emotion-10.md

@@ -1,5 +1,5 @@
 ---
-title: "Migrating to Emotion 10"
+title: 'Migrating to Emotion 10'
 ---
 
 Emotion 10 is a large change to Emotion so it requires some changes to your code. Some of the changes can be done automatically via a codemod and the rest can be done incrementally.
@@ -55,7 +55,7 @@ The upgrades to emotion 10 are split into two parts. The first part can be done
 
 ## Codemoddable
 
-* Change all react-emotion imports so that styled is imported from `@emotion/styled` and all the emotion exports are split into a second import.
+- Change all react-emotion imports so that styled is imported from `@emotion/styled` and all the emotion exports are split into a second import.
 
 ```jsx
 import styled, { css } from 'react-emotion'
@@ -64,7 +64,7 @@ import styled from '@emotion/styled'
 import { css } from 'emotion'
 ```
 
-* Add a css call to the css prop when a template literal is used.
+- Add a css call to the css prop when a template literal is used.
 
 ```jsx
 let element = (
@@ -88,8 +88,8 @@ let element = (
 )
 ```
 
-* Add a `jsx` import and set jsx pragma
-* Alternatively, use this TODO babel preset
+- Add a `jsx` import and set jsx pragma
+- Alternatively, use this TODO babel preset
 
 ```jsx
 import { css } from '@emotion/core'
@@ -105,28 +105,27 @@ let element = (
 
 ## Manual Steps
 
-* Add compat cache with provider
+- Add compat cache with provider
+
+This step is necessary if you still use `css`, `keyframes` or `injectGlobal` from `emotion`. Once you remove all the usages of them in your app, you can remove this.
 
 ```jsx
 import { render } from 'react-dom'
 import App from './App'
-import * as emotion from 'emotion'
-import createCompatCache from '@emotion/compat-cache'
-import { Provider } from '@emotion/provider'
-
-let compatCache = createCompatCache(emotion)
+import { cache } from 'emotion'
+import { CacheProvider } from '@emotion/provider'
 
 render(
-  <Provider value={compatCache}>
+  <CacheProvider value={cache}>
     <App />
-  </Provider>,
+  </CacheProvider>,
   rootNode
 )
 ```
 
 ## Manual Steps over time
 
-* Change css usage to css prop
+- Change css usage to css prop
 
 ```jsx
 import { css } from 'emotion'
@@ -151,4 +150,33 @@ let element = (
 )
 ```
 
-* TODO: add a render prop component that can add multiple class names at once.
+If you have components that accepts props like `wrapperClassName` or etc. you can use the [`ClassNames` component](./class-names.md).
+
+```jsx
+import { css } from 'emotion'
+import { SomeComponent } from 'somewhere'
+let element = (
+  <SomeComponent
+    wrapperClassName={css`
+      color: hotpink;
+    `}
+  />
+)
+
+// ↓ ↓ ↓ ↓ ↓ ↓
+
+import { ClassNames } from '@emotion/core'
+import { SomeComponent } from 'somewhere'
+
+let element = (
+  <ClassNames>
+    {({ css }) => (
+      <SomeComponent
+        wrapperClassName={css`
+          color: hotpink;
+        `}
+      />
+    )}
+  </ClassNames>
+)
+```

docs/object-styles.md

@@ -1,11 +1,9 @@
 ---
-title: "Object Styles"
+title: 'Object Styles'
 ---
 
 Writing styles with objects is a powerful pattern built directly into the core of emotion. Instead of writing css properties in `kebab-case` like regular css, you write them in `camelCase`, for example `background-color` would be `backgroundColor`. Object styles are especially useful with the css prop because you don't need a css call like with string styles but object styles can also be used with styled.
 
-## ADD LINKS TO THE ABOVE STUFF
-
 ### Examples
 
 #### With the css prop
@@ -65,7 +63,8 @@ render(
       }
     }}
   >
-    This is darkorchid.<div className="name">This is orange</div>
+    This is darkorchid.
+    <div className="name">This is orange</div>
   </div>
 )
 ```

docs/styled.md

@@ -1,8 +1,8 @@
 ---
-title: "Styled Components"
+title: 'Styled Components'
 ---
 
-`styled` is a way to create React or Preact components that have styles attached to them. It's available from [@emotion/styled](/packages/@emotion/styled) and [TODO](/packages/preact-emotion). `styled` was heavily inspired by [styled-components](https://www.styled-components.com/) and [glamorous](https://glamorous.rocks/)
+`styled` is a way to create React or Preact components that have styles attached to them. It's available from [@emotion/styled](/packages/@emotion/styled) and [@emotion/preact-styled](/packages/@emotion/preact-styled). `styled` was heavily inspired by [styled-components](https://www.styled-components.com/) and [glamorous](https://glamorous.rocks/)
 
 ### Styling elements and components
 
@@ -154,3 +154,22 @@ render(<H1 color="lightgreen">This is lightgreen.</H1>)
 ```
 
 This API was inspired by [glamorous](https://github.com/paypal/glamorous). ❤️
+
+### Customizing prop forwarding
+
+By default, Emotion will pass all props to custom components and only props that are valid html attributes for string tags. This is can be customized by passing a custom `shouldForwardProp` function. You can also use `@emotion/is-prop-valid` to filter out props that are not valid as html attributes, it is what emotion uses internally.
+
+```jsx
+// @live
+import isPropValid from '@emotion/is-prop-valid'
+import styled from '@emotion/styled'
+
+const H1 = styled('h1', {
+  shouldForwardProp: prop =>
+    isPropValid(prop) && prop !== 'color'
+})(props => ({
+  color: 'hotpink'
+}))
+
+render(<H1 color="lightgreen">This is lightgreen.</H1>)
+```

docs/testing.md

@@ -1,5 +1,5 @@
 ---
-title: "Snapshot Testing"
+title: 'Snapshot Testing'
 ---
 
 Adding [snapshot tests with Jest](https://facebook.github.io/jest/docs/en/snapshot-testing.html) is a great way to help avoid unintended changes to your app's UI.
@@ -31,16 +31,21 @@ Writing a test with `jest-emotion` involves creating a snapshot from the `react-
 
 ```jsx
 import React from 'react'
-import * as emotion from 'emotion'
-import { createSerializer } from 'jest-emotion'
-import styled from 'react-emotion'
+import serializer from 'jest-emotion'
+/** @jsx jsx */
+import { jsx } from '@emotion/core'
 import renderer from 'react-test-renderer'
 
-expect.addSnapshotSerializer(createSerializer(emotion))
+expect.addSnapshotSerializer(serializer)
 
-const Button = styled('div')`
-  color: hotpink;
-`
+const Button = props => (
+  <button
+    css={{
+      color: 'hotpink'
+    }}
+    {...props}
+  />
+)
 
 test('Button renders correctly', () => {
   expect(
@@ -62,7 +67,7 @@ exports[`Button renders correctly 1`] = `
 }
 
 <div
-  className="emotion-0 emotion-1"
+  className="emotion-0"
 >
   This is hotpink.
 </div>

docs/theming.md

@@ -1,19 +1,21 @@
 ---
-title: "Theming"
+title: 'Theming'
 ---
 
-Themes are provided by the library [`emotion-theming`](https://github.com/emotion-js/emotion/tree/master/packages/emotion-theming).
+Theming is provided by the library [`emotion-theming`](https://emotion.sh/docs/emotion-theming).
 
 ```bash
 npm install -S emotion-theming
 ```
 
-Add `ThemeProvider` to the top level of your app and access the theme with `props.theme` in a styled component or provide a function that accepts the theme as the css prop. The api is laid out in detail [in the documentation](https://github.com/emotion-js/emotion/tree/master/packages/emotion-theming).
+Add `ThemeProvider` to the top level of your app and access the theme with `props.theme` in a styled component or provide a function that accepts the theme as the css prop. The api is laid out in detail [in the documentation](https://emotion.sh/docs/emotion-theming).
 
 ```jsx
 // @live
+/** @jsx jsx */
+import { jsx } from '@emotion/core'
 import styled from '@emotion/styled'
-import ThemeProvider from '@emotion/provider'
+import { ThemeProvider } from 'emotion-theming'
 
 const theme = {
   colors: {

docs/with-props.md

@@ -1,26 +1,8 @@
 ---
-title: "Attaching Props"
+title: 'Attaching Props'
 ---
 
-Sometimes it's useful to create components that already have props applied, like the example below with a password input. You use recompose's `withProps` higher-order component to do this.
-
-**[`withProps` documentation](https://github.com/acdlite/recompose/blob/master/docs/API.md#withprops)**
-
-```jsx
-// @live
-import styled from '@emotion/styled'
-import withProps from 'recompose/withProps'
-
-const RedPasswordInput = withProps({
-  type: 'password'
-})(styled('input')`
-  background-color: red;
-`)
-
-render(<RedPasswordInput />)
-```
-
-Alternatively, you can use the css prop and create a regular component like this.
+Some css-in-js libraries offer APIs to attach props to components, instead of having our own API to do that, we recommend creating a regular react component, using the css prop and attaching props like you would with any other React component.
 
 ```jsx
 // @live

site/src/components/Playground.js

@@ -22,6 +22,8 @@ export const scope = {
         return require('@emotion/styled-base')
       case '@emotion/css':
         return require('@emotion/css')
+      case '@emotion/is-prop-valid':
+        return require('@emotion/is-prop-valid')
       case 'emotion-theming':
         return require('emotion-theming')
       case 'recompose/withProps':