Merge pull request #387 from primer/q4-cat-toad

Q4 Cat Toad Release PR

Author: Emily

README.md

@@ -76,6 +76,49 @@ export default () => (
 
 This will set the `color`, `font-family`, and `line-height` CSS properties to the same ones used in [primer-base](https://github.com/primer/primer/blob/master/modules/primer-base/lib/base.scss#L15).
 
+#### Theming
+
+Components are styled using Primer's [theme](https://github.com/primer/components/blob/master/src/theme.js) by default, but you can provide your own theme by using [styled-component's][styled-components] `<ThemeProvider>`. If you'd like to fully replace the Primer [theme](https://github.com/primer/components/blob/master/src/theme.js) with your custom theme, pass your theme to the `<ThemeProvider>` in the root of your application like so:
+
+```jsx
+import {ThemeProvider} from 'styled-components'
+
+const theme = { ... }
+
+const App = (props) => {
+  return (
+    <div>
+      <ThemeProvider theme={theme}>
+        <div>your app here</div>
+      </ThemeProvider>
+    </div>
+  )
+}
+
+```
+
+If you'd like to merge the Primer theme with your theme, you can do so importing the Primer theme and merging using Object.assign:
+
+```jsx
+import {ThemeProvider} from 'styled-components'
+import {theme} from '@primer/components'
+
+const customTheme = { ... }
+
+
+const App = (props) => {
+  return (
+    <div>
+      <ThemeProvider theme={Object.assign({}, theme, customTheme)}> // matching keys in customTheme will override keys in the Primer theme
+        <div>your app here</div>
+      </ThemeProvider>
+    </div>
+  )
+}
+```
+
+*Note that using `Object.assign` will only create a shallow merge. This means that if both themes have a `color` object, the _entire_ `color` object will be replaced with the new `color` object, instead of only replacing duplicate values from the original theme's color object.
+
 #### Static CSS rendering
 
 If you're rendering React components both server-side _and_ client-side, we suggest following [styled-component's server-side rendering instructions](https://www.styled-components.com/docs/advanced#server-side-rendering) to avoid the flash of unstyled content for server-rendered components. This repo's [documentation template component](https://github.com/primer/components/blob/master/pages/_document.js) demonstrates how to do this in [Next.js].

contributing.md

@@ -63,7 +63,7 @@ Default values for system props can be set in `Component.defaultProps`.
 
 Prop Types from system props such as `COMMON` or `TYPOGRAPHY` as well as styled-system functions can be spread in the component's prop types declaration (see example below).
 
- ⚠️ **Make sure to always set the default `theme` prop to our theme! This allows consumers of our components to access our theme values without a ThemeProvider.**
+ ⚠️ **Make sure to always set the default `theme` prop to our [theme](https://github.com/primer/components/blob/master/src/theme.js)! This allows consumers of our components to access our theme values without a ThemeProvider.**
 
 
 ```jsx

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/components",
-  "version": "8.2.0-beta",
+  "version": "9.0.0-beta",
   "description": "Primer react components",
   "main": "dist/index.umd.js",
   "module": "dist/index.esm.js",

pages/components/docs/Dropdown.md

@@ -3,26 +3,41 @@
 
 The Dropdown component is a lightweight context menu for housing navigation and actions.
 
+Dropdown.Button is used to trigger opening and closing the dropdown.
+
+Dropdown.Menu wraps your menu content. Be sure to pass a `direction` prop to this component to position the menu in relation to the Dropdown.Button.
+
 ## Default example
 ```.jsx
 <Dropdown scheme="primary" minWidth="5em">
-  <Box role="list">
-    <Box role="listitem">Item 1</Box>
-    <Box role="listitem">Item 2</Box>
-    <Box role="listitem">Item 3</Box>
-  </Box>
+  <Dropdown.Button>Dropdown </Dropdown.Button>
+  <Dropdown.Menu direction='sw'>
+    <Dropdown.Item>Item 1</Dropdown.Item>
+    <Dropdown.Item>Item 2</Dropdown.Item>
+    <Dropdown.Item>Item 3</Dropdown.Item>
+  </Dropdown.Menu>
 </Dropdown>
 ```
 
 ## System props
 
-Dropdown components get `COMMON` system props. Read our [System Props](/components/docs/system-props) doc page for a full list of available props.
+Dropdown, Dropdown.Menu, Dropdown.Button, and Dropdown.Item all get `COMMON` system props. Read our [System Props](/components/docs/system-props) doc page for a full list of available props.
 
 ## Component props
 
+#### Dropdown.Menu
 | Name | Type | Default | Description |
 | :- | :- | :-: | :- |
-| scheme | String | | Button scheme used to style the component, can be one of `danger`, `outline` or `primary` |
-| title | String | | Optional prop to set the text in the Dropdown button
+| direction | String | 'sw' | Sets the direction of the dropdown menu. |
+
+#### Dropdown.Item
+No additional props.
+
+#### Dropdown.Button
+No additional props.
+
+#### Dropdown
+No additional props.
+
 
 export const meta = {displayName: 'Dropdown'}

pages/components/docs/index.js

@@ -7,6 +7,7 @@ export {meta as CircleBadge} from './CircleBadge.md'
 export {meta as CircleOcticon} from './CircleOcticon.md'
 export {meta as CounterLabel} from './CounterLabel.md'
 export {meta as Details} from './Details.md'
+export {meta as Dropdown} from './Dropdown.md'
 export {meta as Donut} from './Donut.md'
 export {meta as FilterList} from './FilterList.md'
 export {meta as Flash} from './Flash.md'

pages/components/docs/primer-theme.md

@@ -20,7 +20,7 @@ Custom theming is an optional way to override the Primer values that control col
 
 There are two ways to change the theme of Primer components:
 
-1. You can override the theme for an entire tree of components using the `<ThemeProvider>` from [styled-components]:
+1. You can override the entire theme for an entire tree of components using the `<ThemeProvider>` from [styled-components]:
 
     ```jsx
     import {Block, Button, Text, theme as primer} from '@primer/components'
@@ -46,8 +46,27 @@ There are two ways to change the theme of Primer components:
     ```
 
     **⚠️ Note: [styled-components]'s `<ThemeProvider>` only allows exactly one child.**
+2. You can merge the Primer theme with your custom theme using Object.assign:
 
-1. You can theme individual components by passing the `theme` prop directly:
+```jsx
+import {ThemeProvider} from `styled-components`
+import {theme} from '@primer/components'
+
+const customTheme = { ... }
+
+
+const App = (props) => {
+  return (
+    <div>
+      <ThemeProvider theme={Object.assign({}, theme, customTheme)}> // matching keys in customTheme will override keys in the Primer theme
+        <div>your app here</div>
+      </ThemeProvider>
+    </div>
+  )
+}
+```
+
+3. You can theme individual components by passing the `theme` prop directly:
 
     ```jsx
     import {Text} from '@primer/components'
@@ -65,6 +84,7 @@ There are two ways to change the theme of Primer components:
 
     **☝️ This is an intentionally convoluted example, since you can use `<Text color='#f0f'>` out of the box.**
 
+
 Read the [styled-system docs](http://jxnblk.com/styled-system/getting-started#theming) for more information on theming in styled-system.
 
 [styled-components]: https://styled-components.com/

src/Avatar.js

@@ -1,6 +1,7 @@
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
-import {themeGet, space} from 'styled-system'
+import {get} from './constants'
+import {space} from 'styled-system'
 import theme from './theme'
 
 function borderRadius({size}) {
@@ -15,7 +16,7 @@ const Avatar = styled.img.attrs(props => ({
 }))`
   display: inline-block;
   overflow: hidden; // Ensure page layout in Firefox should images fail to load
-  line-height: ${themeGet('lineHeights.condensedUltra', 1)};
+  line-height: ${get('lineHeights.condensedUltra')};
   vertical-align: middle;
   ${borderRadius};
   ${space};

src/AvatarPair.js

@@ -1,11 +1,11 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
-import {themeGet} from 'styled-system'
+import {get} from './constants'
 import Avatar from './Avatar'
 import theme from './theme'
 
-const getBackgroundColor = themeGet('colors.white', '#fff')
+const getBackgroundColor = get('colors.white')
 
 const Wrapper = styled('div')`
   display: inline-flex;
@@ -15,7 +15,7 @@ const Wrapper = styled('div')`
 const childStyles = props => ({
   display: 'inline-block',
   overflow: 'hidden', // Ensure page layout in Firefox should images fail to load
-  lineHeight: `${themeGet('lineHeights.condensedUltra', 1)}`,
+  lineHeight: `${get('lineHeights.condensedUltra')}`,
   verticalAlign: 'middle',
   borderRadius: '2px',
   position: 'absolute',

src/BranchName.js

@@ -1,14 +1,13 @@
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
-import {themeGet} from 'styled-system'
 import theme from './theme'
-import {COMMON, Base} from './constants'
+import {COMMON, Base, get} from './constants'
 
 const BranchName = styled(Base)`
   display: inline-block;
   padding: 2px 6px;
-  font-size: ${themeGet('fontSizes.0', theme.fontSizes[0])}px;
-  font-family: ${themeGet('fonts.mono', theme.fonts.mono)};
+  font-size: ${get('fontSizes.0')}px;
+  font-family: ${get('fonts.mono')};
   color: rgba(27, 31, 35, 0.6);
   background-color: #eaf5ff;
   border-radius: 3px;

src/Button.js

@@ -12,7 +12,7 @@ function fontSize({size = '14px', ...props}) {
   }
 }
 
-const ButtonBase = ({is: Tag = 'div', onClick, disabled, theme, ...rest}) => {
+const ButtonBase = ({is: Tag, onClick, disabled, theme, ...rest}) => {
   return <Tag disabled={disabled} onClick={disabled ? undefined : onClick} {...rest} />
 }