Merge pull request #182 from primer/release-1.0.0-beta

Release Tracking 1.0.0-beta

.babelrc

@@ -1,3 +1,10 @@
 {
-  "presets": ["env", "stage-0", "react"]
+  "presets": [
+    "env",
+    "stage-0",
+    "react"
+  ],
+  "plugins": [
+    "add-react-displayname"
+  ]
 }

.eslintrc.json

@@ -3,5 +3,8 @@
     "plugin:github/es6",
     "plugin:github/react",
     "plugin:jsx-a11y/recommended"
-  ]
+  ],
+  "rules": {
+    "import/no-namespace": "warn"
+  }
 }

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+// Describe your changes
+
+Closes #:
+
+
+#### If development process was changed:
+  Description of changes:
+  - [ ] Updated README?
+
+
+#### Merge Checklist:
+- [ ] Changed base branch to release branch
+- [ ] Updated Kit (`npm run build:docs)
+- [ ] Enabled GH Pages for testing
+- [ ] Tested in Chrome [(BrowserStack)](https://www.browserstack.com/)
+- [ ] Tested in Firefox [(BrowserStack)](https://www.browserstack.com/)
+- [ ] Tested in Safari [(BrowserStack)](https://www.browserstack.com/)
+- [ ] Tested in Edge [(BrowserStack)](https://www.browserstack.com/)

.gitignore

@@ -1,3 +1,4 @@
+.*.swp
 .DS_Store
 coverage/
 dist/

.npmignore

@@ -0,0 +1,7 @@
+*.tgz
+.*
+*.config.js
+coverage/
+docs/
+script/
+src/__tests__/

.npmrc

@@ -1,2 +1,4 @@
 save=true
 save-exact=true
+# we create our tags in Releases now
+git-tag-version=false

README.md

@@ -4,15 +4,51 @@
 
 ## Status
 
-⚠️ This project is WIP and not ready for production use yet!
+**⚠️ This project is WIP and not ready for production use yet!**
 
-Currently we link to the latest built Primer CSS so that we may use current Primer styles to start to build components. This does not include `primer-base` so as to avoid unwanted base overrides.
+Currently we link to the latest build of [Primer CSS] so that we may use current Primer styles to start to build components. This does not include `primer-base` so as to avoid unwanted base overrides.
 
 ## Installation
 
-Install primer-react in your project with:
+Install primer-react in your project with npm:
 
-`npm install primer-react`
+```
+npm install primer-react
+```
+
+## Usage
+
+**If you are upgrading from a version before `1.0.0-beta`, please read the [migration docs](migrating.md).**
+
+All of our components are exported by name from `primer-react`, so you can import them with:
+
+```js
+import {
+  Block,
+  Button,
+  Heading,
+  Text
+} from 'primer-react'
+```
+
+### Styling
+
+This project uses [emotion] under the hood to generate static CSS from _some_ component styles, but still relies on [Primer CSS] for some component styles that haven't yet been ported over.
+
+To ensure proper styling, you'll need to link to the most recent build of [Primer CSS] in one of the following ways:
+
+1. If you're using webpack, you can install [style-loader](https://github.com/webpack-contrib/style-loader) and [css-loader](), `import 'primer/build/build.css'` in your bundle, and include the following in your webpack config's `module.rules` list:
+
+    ```js
+    {
+      test: /\.css$/,
+      use: ['style-loader', 'css-loader']
+    }
+    ```
+
+1. **For pre-production applications**, you can link directly to [the build on unpkg.com](https://unpkg.com/primer/build/build.css).
+
+1. Otherwise, you can `npm install --save primer` and either or link `node_modules/primer/build/build.css` to your source directory.
 
 ## Local Development
 
@@ -76,11 +112,12 @@ test coverage data is generated in the `coverage/` directory.
 ## Principles
 
 - Everything is a component.
-- Aim for total style encapsulation, don't rely on inheritance to provide default styles.
+- Aim for total style encapsulation; don't rely on inheritance to provide default styles.
 - Build small building blocks with minimal props to keep complexity low.
 - Keep system constrained by only including props needed per component.
 - Favor extending or wrapping components for more complex operations.
 - Maintain design system consistency with utilities as props (for spacing, color, font-size, line-height, widths, and radii).
 
 
 [npx]: https://www.npmjs.com/package/npx
+[Primer CSS]: https://github.com/primer/primer

contributing.md

@@ -0,0 +1,150 @@
+# Contribution guidelines
+
+## Tools we use
+
+### Components
+1. We use [emotion] to style our components, and [emotion-theming] as the theme provider.
+1. We use style functions from [styled-system] whenever possible, and styled-systems' `style()` function to create new ones.
+1. We use [system-components] to reduce the amount of boilerplate needed to implement styled-system functions.
+
+## Component patterns
+With a couple of exceptions, all components should be created by the `withSystemProps()` function from `src/system-props.js`. This function takes a "component-ish" value as its first argument, and an array of [system props](#system-props) as the second:
+
+```jsx
+import {withSystemProps, POSITION} from './system-props'
+
+function Component(props) { 
+  /* implementation */
+}
+
+export default withSystemProps(Component, POSITION)
+
+// equivalent:
+export default withSystemProps({is: Component}, POSITION)
+
+// with more default props:
+export default withSystemProps(
+  {
+    is: Component,
+    m: 2
+  },
+  POSITION
+)
+```
+
+Categories of system props are exported from `src/system-props`:
+
+* `COMMON` includes color and spacing (margin and padding) props
+* `TYPOGRAPHY` includes `COMMON` and font family, font weight, and line-height
+* `POSITION` includes `COMMON` and positioning props
+* `FLEX_CONTAINER` includes `COMMON` and flexbox props for containers
+* `FLEX_ITEM` includes `COMMON` and flexbox props for items in a flex container
+
+### Components with only system props
+Components with only system props should be created by passing the default tag to `withSystemProps()`:
+
+```jsx
+import {withSystemProps, LAYOUT} from './system-props'
+
+const Block = withSystemProps('div', LAYOUT)
+```
+
+### Primer CSS components
+If you're just adding Primer CSS class names, you can pass the `className` prop to another component created with `withSystemProps()`, and it will be combined with any generated classes automatically:
+
+```jsx
+import Box from './Box'
+
+function FancyBox({flashing, ...rest}) {
+  return <Box className={flashing && 'Box--flashing'} {...rest} />
+}
+
+FancyBox.propTypes = {
+  flashing: PropTypes.bool,
+  // be sure to spread Box's prop-types
+  ...Box.propTypes
+}
+
+FancyBox.defaultProps = {
+  ...Box.defaultProps
+}
+
+// if you don't spread defaultProps from another system component,
+// you will need to wrap the export in withDefaultTheme()
+export default FancyBox
+```
+
+> **⚠️ If you use this pattern, passing the component to `withSystemProps()` should throw an error because system-components has an issue (_TODO: ref_) with calling the underlying component render function twice.**
+
+With the above pattern, it's possible to control whether users may pass additional class names to your component. If you want to allow this, the `className` prop should be listed in `propTypes` and combined with your own classes using the [classnames] function:
+
+```jsx
+import classnames from 'classnames'
+import Box from './Box'
+
+export default function FancyBox({flashing, className, ...rest}) {
+  const classes = classnames(className, flashing && 'Box--flashing')
+  return <Box className={classes} {...rest} />
+}
+
+FancyBox.propTypes = {
+  className: PropTypes.string,
+  flashing: PropTypes.bool,
+  ...Box.propTypes
+}
+```
+
+Alternatively, you can create the component from scratch using `withSystemProps()`, and pass it the same system props:
+
+```jsx
+import classnames from 'classnames'
+import {withSystemProps, LAYOUT} from './system-props'
+
+function FancyBox({flashing, className, is: Tag, ...rest}) {
+  return (
+    <Tag
+      className={classnames(className, flashing && 'Box--flashing')}
+      {...rest}
+    />
+  )
+}
+
+FancyBox.propTypes = {
+  flashing: PropTypes.bool
+}
+
+export default withSystemProps(FancyBox, LAYOUT)
+```
+
+In this case, you will need to deal explicitly with two props passed down from [emotion] and [system-components], respectively:
+
+  * `className`: You _must_ render this prop, otherwise **your component will not be styled.**
+  * `is`: This is what allows your component to render with arbitrary elements, and even other components. If you don't respect this prop, you should `delete Component.propTypes.is` to signal that it's not available.
+
+## Glossary
+
+### System props
+System props are style functions that provide on or more props, and can be passed directly the return value of [emotion]'s `styled()` function:
+
+```jsx
+import {styled} from 'react-emotion'
+import {space} from 'styled-system'
+const SpaceDiv = styled('div')(space)
+```
+
+System props come with `propTypes` that can be mixed into your own with ES6 [spread syntax]:
+
+```jsx
+SpaceDiv.propTypes = {
+  stellar: PropTypes.bool,
+  ...space.propTypes
+}
+```
+
+[classnames]: https://www.npmjs.com/package/classnames
+[emotion]: https://emotion.sh/
+[emotion-theming]: https://github.com/emotion-js/emotion/tree/master/packages/emotion-theming
+[spread syntax]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax
+[styled-system]: https://jxnblk.com/styled-system/getting-started
+[system-components]: https://jxnblk.com/styled-system/system-components
+[table]: https://jxnblk.com/styled-system/table