@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/.storybook/preview.js

@@ -0,0 +1,69 @@
+import {addons} from '@storybook/addons'
+import {ThemeProvider, themeGet, theme} from '../src'
+import {createGlobalStyle} from 'styled-components'
+
+// set global theme styles for each story
+const GlobalStyle = createGlobalStyle`
+  body {
+    background-color: ${themeGet('colors.bg.primary')};
+    color: ${themeGet('colors.text.primary')};
+  }
+`
+export const globalTypes = {
+  colorMode: {
+    name: 'Color mode',
+    description: 'Color mode (day, night, auto)',
+    defaultValue: 'day',
+    toolbar: {
+      icon: 'paintbrush',
+      // array of colorMode items
+      items: ['day', 'night', 'auto'],
+      showName: true
+    }
+  },
+  dayScheme: {
+    name: 'Day color scheme',
+    description: 'Day color scheme',
+    defaultValue: 'light',
+    toolbar: {
+      icon: 'circlehollow',
+      items: Object.keys(theme.colorSchemes),
+      showName: true
+    }
+  },
+  nightScheme: {
+    name: 'Night color scheme',
+    description: 'Night color scheme',
+    defaultValue: 'dark',
+    toolbar: {
+      icon: 'circle',
+      items: Object.keys(theme.colorSchemes),
+      showName: true
+    }
+  }
+}
+
+// context.globals.X references items in globalTypes
+const withThemeProvider = (Story, context) => {
+  return (
+    <ThemeProvider
+      colorMode={context.globals.colorMode}
+      dayScheme={context.globals.dayScheme}
+      nightScheme={context.globals.nightScheme}
+    >
+      <GlobalStyle />
+      <Story {...context} />
+    </ThemeProvider>
+  )
+}
+export const decorators = [withThemeProvider]
+
+addons.setConfig({
+  // Some stories may set up keyboard event handlers, which can can be interfered
+  // with by these keyboard shortcuts.
+  enableShortcuts: false
+})
+
+export const parameters = {
+  actions: {argTypesRegex: '^on[A-Z].*'}
+}

package/.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Jest Current File",
+      "program": "${workspaceFolder}/node_modules/.bin/jest",
+      "args": ["${fileBasenameNoExtension}", "--config", "jest.config.js"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "disableOptimisticBPs": true,
+      "windows": {
+        "program": "${workspaceFolder}/node_modules/jest/bin/jest"
+      }
+    }
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "editor.formatOnSave": true,
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

package/@types/@styled-system/prop-types/index.d.ts

@@ -0,0 +1 @@
+declare module '@styled-system/prop-types'

package/@types/@styled-system/props/index.d.ts

@@ -0,0 +1 @@
+declare module '@styled-system/props'

package/@types/jest-styled-components/index.d.ts

@@ -0,0 +1 @@
+declare module 'jest-styled-components/serializer'

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @primer/components
 
+## 29.1.1
+
+### Patch Changes
+
+- [#1441](https://github.com/primer/react/pull/1441) [`f3f5afb9`](https://github.com/primer/react/commit/f3f5afb9cf91e0ce3ea287351c871eb1559f1fa4) Thanks [@jfuchs](https://github.com/jfuchs)! - Exclude storybook stories from TypeScript compilation for builds
+
 ## 29.1.0
 
 ### Minor Changes

package/CODEOWNERS

@@ -0,0 +1,2 @@
+# All changes should be reviewed by a member of the @react-reviewers team
+* @primer/react-reviewers

package/babel-defines.js

@@ -0,0 +1,13 @@
+const shared = {
+  __DEV__: "process.env.NODE_ENV !== 'production'"
+}
+
+module.exports = {
+  development: shared,
+  test: shared,
+  production: {
+    ...shared,
+    __DEV__: 'false',
+    'process.env.NODE_ENV': "'production'"
+  }
+}

package/babel.config.js

@@ -0,0 +1,39 @@
+const defines = require('./babel-defines')
+
+function replacementPlugin(env) {
+  return ['babel-plugin-transform-replace-expressions', {replace: defines[env]}]
+}
+
+const sharedPlugins = [
+  'macros',
+  'preval',
+  'add-react-displayname',
+  'babel-plugin-styled-components',
+  '@babel/plugin-proposal-nullish-coalescing-operator',
+  '@babel/plugin-proposal-optional-chaining'
+]
+
+function makePresets(moduleValue) {
+  return ['@babel/preset-typescript', ['@babel/preset-react', {modules: moduleValue}]]
+}
+
+module.exports = {
+  env: {
+    development: {
+      presets: makePresets(process.env.BABEL_MODULE || false),
+      plugins: [
+        ...(process.env.BABEL_MODULE === 'commonjs' ? ['@babel/plugin-transform-modules-commonjs'] : []),
+        ...sharedPlugins,
+        replacementPlugin('development')
+      ]
+    },
+    production: {
+      presets: makePresets(false),
+      plugins: [...sharedPlugins, replacementPlugin('production')]
+    },
+    test: {
+      presets: makePresets('commonjs'),
+      plugins: [...sharedPlugins, ['@babel/plugin-transform-modules-commonjs'], replacementPlugin('test')]
+    }
+  }
+}

package/contributor-docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at design-systems@github.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

package/contributor-docs/CONTRIBUTING.md

@@ -0,0 +1,274 @@
+# Contribution guidelines
+
+1. [Roadmap](#roadmap)
+2. [Before Getting Started](#before-getting-started)
+3. [Discussing non-public features or products](#discussing-non-public-features-or-products)
+4. [Developing Components](#developing-components)
+   - [Tools we use](#tools-we-use)
+   - [Component patterns](#component-patterns)
+   - [Adding system props](#adding-system-props)
+   - [Adding the sx prop](#adding-the-sx-prop)
+   - [Linting](#linting)
+   - [Testing](#testing)
+   - [TypeScript support](#typescript-support)
+   - [Additional resources](#additional-resources)
+5. [Writing documentation](#writing-documentation)
+6. [Creating a pull request](#creating-a-pull-request)
+   - [What to expect after opening a pull request](#what-to-expect-after-opening-a-pull-request)
+   - [What we look for in reviews](#what-we-look-for-in-reviews)
+7. [Deploying & publishing](#deploying-and-publishing)
+   - [Deploying](#deploying)
+   - [Path aliasing](#path-aliasing)
+   - [Publishing](#publishing)
+8. [Troubleshooting](#troubleshooting)
+9. [Glossary](#glossary)
+   - [System Props](#system-props)
+
+## Roadmap
+
+If you're looking for something to work on, a great place to start is our issues labeled [up for grabs](https://github.com/primer/react/issues?q=is%3Aopen+is%3Aissue+label%3A%22up+for+grabs%22)! If you've got a feature that you'd like to implement, be sure to check out our [Primer Components Roadmap](https://github.com/primer/react/projects/3) to make sure it hasn't already been started on.
+
+## Before Getting Started
+
+A common question asked about Primer Components is how to know what should be added to Primer Components and what is best left as a local component in a consuming application. Though there are no hard & fast rules about what can and cannot be added to Primer Components, here are a few things we take into consideration:
+
+- Is the new feature an existing pattern in Primer CSS or related to UI built at GitHub? Primer Components is first and foremost a library for building UI at GitHub - patterns that aren't currently being used in GitHub UI (either on github.com or in a GitHub owned project outside of github.com) probably shouldn't be added to Primer Components. Exceptions to this could be helper components that don't necessarily render UI but help with the development process (like `Flex`, `Grid`, or `Box`).
+
+- Does the proposed component get used in more than one or two places across GitHub UI? A component that's only meant to be used in one place and doesn't have potential to be reused in many places probably should exist as a local component. An example of something like this might be a component that renders content specific to a single GitHub product.
+
+**In general, we tend to be pretty excited about 99% of feature proposals and contributions!** If you would like to get started with a component proposal, open an issue using the [component proposal template](https://github.com/primer/react/issues/new?template=new-component-proposal.md).
+
+## Discussing non-public features or products
+
+As this is a public repo, please be careful not to include details or screenshots from unreleased GitHub products or features. In most cases, a good bug report, feature request, or pull request should be able to describe the work without including business logic or feature details, but if you must discuss context relating to an unreleased feature, please open an issue in the private [Design Systems repo](https://github.com/github/design-systems/issues/new/choose) and link to it in your issue or pull request.
+
+## Developing components
+
+We primarily use our documentation site as a workspace to develop new components or make changes to existing components (stay tuned for a better development environment coming soon!).
+
+Before running the documentation site locally, you'll need to install packages in the root and `docs` directories:
+
+```sh
+npm install && cd docs && npm install
+```
+
+Then navigate back to the root folder and run the following to start up the site:
+
+```sh
+npm start
+```
+
+Navigate to http://localhost:8000/ to see the site in your browser ✨
+
+### Tools we use
+
+1. We use [styled-components](https://www.styled-components.com/) to style our components.
+2. We use style functions from [styled-system](https://styled-system.com/) whenever possible, and styled-systems' `style()` function to create new ones.
+
+### Component patterns
+
+With a couple of exceptions, all components should be created with the `styled` function from [styled-components] and should have the appropriate groups of system props attached.
+
+Default values for system props can be set in `Component.defaultProps`.
+
+⚠️ **Do not set the default `theme` prop! This can sometimes override the theme provided by the ThemeProvider and cause unexpected theming issues.**
+
+Additionally, every component should support [the `sx` prop](https://primer.style/components/overriding-styles); remember to add `${sx}` to the style literal.
+
+Here's an example of a basic component written in the style of Primer Components:
+
+```jsx
+import {TYPOGRAPHY, COMMON} from './constants'
+import sx from './sx
+
+const Component = styled.div`
+  // additional styles here
+
+  ${COMMON};
+  ${TYPOGRAPHY};
+  ${sx};
+`
+
+Component.defaultProps = {
+  m: 0,
+  fontSize: 5,
+}
+
+export default Component
+```
+
+### Adding system props
+
+Each component should have access to the appropriate system props. Every component has access to `COMMON`. For **most** components added, you'll only need to give the component to `COMMON`. If you are unsure, ping a DS team member on your PR.
+
+Categories of system props are exported from `src/constants.js`:
+
+- `COMMON` includes color and spacing (margin and padding) props
+- `TYPOGRAPHY` includes font family, font weight, and line-height props
+- `POSITION` includes positioning props
+- `FLEX` includes flexbox props
+- `BORDER` includes border and box-shadow props
+- `GRID` includes grid props
+
+To give the component access to a group of system props, import the system prop function from `./constants` and include the system prop function in your styled-component like so:
+
+```jsx
+import {COMMON} from './constants'
+
+const Component = styled.div`
+  // additional styles here
+  ${COMMON};
+`
+```
+
+Remember that the system prop function inside your style declaration needs to go _after_ any built-in styles you want to be overridable.
+
+### Adding the `sx` prop
+
+Each component should provide access to a prop called `sx` that allows for setting theme-aware ad-hoc styles. See the [overriding styles](https://primer.style/components/overriding-styles) doc for more information on using the prop.
+
+Adding the `sx` prop is similar to adding system props; import the default export from the `sx` module, add it to your style definition, and add the appropriate prop types. **The `sx` prop should go at the _very end_ of your style definition.**
+
+```jsx
+import {COMMON} from './constants'
+import sx from './sx'
+
+const Component = styled.div`
+  // additional styles here
+  ${COMMON};
+  ${sx};
+`
+```
+
+### Linting
+
+We use the [React configuration](https://github.com/github/eslint-plugin-github/blob/master/lib/configs/react.js) from [GitHub's eslint plugin](https://github.com/github/eslint-plugin-github) to lint our JavaScript. To check your work before pushing, run:
+
+```sh
+npm run lint
+```
+
+Or, you can use [npx] to run eslint on one or more specific files:
+
+```sh
+# lint the component and the tests in src/__tests__
+npx eslint src/**/MyComponent.js
+```
+
+**Protip:** The [eslint `--fix` flag](https://eslint.org/docs/user-guide/command-line-interface#--fix) can automatically fix most linting errors, such as those involving whitespace or incorrect ordering of object keys and imports. You can fix those issues across the entire project with:
+
+```sh
+npm run lint -- --fix
+```
+
+**Protip:** `npm run lint -- --quiet` (or `npx eslint --quiet ...`) will suppress warnings so that you can focus on fixing errors.
+
+### Testing
+
+We test our components with [Jest](https://facebook.github.io/jest/) and [react-test-renderer](https://reactjs.org/docs/test-renderer.html). You can run the tests locally with `npm test`. To run the tests as you work, run Jest in watch mode with:
+
+```sh
+npm test -- --watch
+```
+
+See [`src/__tests__/example.js`](src/__tests__/example.js) for examples of ways that we test our components.
+
+### TypeScript support
+
+Several of the projects that consume Primer Components are written in TypeScript. Though Primer Components is not currently written in TS, we do export type definitions in order to make Primer Components compatible with other TS projects.
+
+Whenever adding new components or modifying the props of an existing component, **please make sure to update the type definition** in `index.d.ts`! This is super important to make sure we don't break compatibility :)
+
+### Additional resources
+
+- [Primer Components Philosophy](https://primer.style/components/philosophy)
+- [Primer Components Core Concepts](https://primer.style/components/core-concepts)
+- [Primer Components System Props](https://primer.style/components/system-props)
+- [Styled Components docs](https://styled-components.com/)
+- [Styled System docs](https://styled-system.com/)
+
+## Writing documentation
+
+We use [Doctocat](https://github.com/primer/doctocat) to power our documentation site at [https://primer.style/components](https://primer.style/components/).
+
+To add a new component to our documentation site, create a new file with the `.md` extension for your component in `docs/content` (e.g. `docs/content/Button.md`).
+
+## Creating a pull request
+
+When creating a new pull request, please follow the guidelines in the auto-populated pull request template. Be sure to add screenshots of any relevant work and a thoughtful description.
+
+### What to expect after opening a pull request
+
+After opening a pull request, a member of the design systems team will add the appropriate labels (major, minor, patch release labels) and update the base branch to the correct release branch. Usually, you'll receive a response from the design systems team within a day or two. The design systems team member will review the pull request keeping the following items in mind:
+
+### What we look for in reviews
+
+- If it's a new component, does the component make sense to add to Primer Components? (Ideally this is discussed before the pull request stage, please reach out to a DS member if you aren't sure if a component should be added to Primer Components!)
+- Does the component follow our [Primer Components code style](#component-patterns)?
+- Does the component use theme values for most CSS values?
+- Does the component have the [correct system props implemented](#adding-system-props)?
+- Is the component API intuitive?
+- Does the component have the appropriate [type definitions in `index.d.ts`](#typescript-support)?
+- Is the component documented accurately?
+- Does the component have appropriate tests?
+- Does the pull request increase the bundle size significantly?
+
+If everything looks great, the design systems team member will approve the pull request and merge when appropriate. Minor and patch changes are released frequently, and we try to bundle up breaking changes and avoid shipping major versions too often. If your pull request is time-sensitive, please let a design systems team member know. You do not need to worry about merging pull requests on your own, we'll take care of that for you :)
+
+## Deploying and publishing
+
+### Deploying
+
+All of our documentation sites use the [Now integration](https://github.com/organizations/primer/settings/installations/1007619) to deploy documentation changes whenever code is merged into main. The integration also creates a preview site every time you commit code to a branch. To view the preview site, navigate to the PR and find the comment from the `now` bot. This will include a link to the preview site for your branch.
+
+Once you merge your branch into main, any changes to the docs will automatically deploy. No further action is necessary.
+
+### Path aliasing
+
+This site is served as a subdirectory of [primer.style] using a [path alias](https://zeit.co/docs/features/path-aliases) configured in that repo's [`rules.json`](https://github.com/primer/primer.style/tree/master/rules.json). If you change the production deployment URL for this app, you will also need to change it there and re-deploy that app; otherwise, Now will automatically route requests from [primer.style/components](https://primer.style/components/) to the new deployment whenever you alias this one to `primer-components.now.sh`.
+
+### Publishing
+
+We use [changesets](https://github.com/atlassian/changesets) to managing versioning, publishing, and release notes. Here's how it works:
+
+#### Using changesets to prepare and publish a release
+
+1. When creating a new PR, changeset-bot will remind you to add a changeset if your change should trigger a new version number for the package.
+2. To create a new changeset on your local machine, run `npx changeset` and answer the prompts. If you are introducing multiple features in the PR, add a separate changeset for each.
+3. Push your new changes along with the changeset file to your PR; changeset-bot will show that there are valid changesets in the PR.
+4. When the PR is ready, merge it to the main branch.
+5. The changeset action will automatically create a new PR that bumps the version number appropriately, creates or updates `CHANGELOG.md`, and shows the release notes that will be used in the GitHub Release notes.
+6. If you want to release more features, merge them into the main branch and changesets will update the release PR. Note that it does this via force-pushing, so you should not edit the release PR yourself.
+7. When you're ready to release, merge the release PR into the main branch and changesets will publish the new version to npm and create a GitHub Release.
+
+## Troubleshooting
+
+**`npm start` fails with an error like `gatsby: command not found`**
+
+Make sure to run `npm install` from inside the `docs/` subfolder _as well as_ the root folder.
+
+**`npm start` fails with a different error**
+
+Ensure you are using the latest minor of Node.js for the major version specified in the `.nvmrc` file. For example, if `.nvmrc` contains `8`, make sure you're using the latest version of Node.js with the major version of 8.
+
+## Glossary
+
+### System props
+
+System props are style functions that provide one or more props, and can be passed directly the return value of [styled-components]'s `styled()` function:
+
+```jsx
+import {styled} from 'styled-components'
+import {space} from 'styled-system'
+const SpaceDiv = styled.div`
+  ${space}
+`
+```
+
+[classnames]: https://www.npmjs.com/package/classnames
+[spread syntax]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax
+[styled-system]: https://styled-system.com
+[table]: https://jxnblk.com/styled-system/table
+[npx]: https://www.npmjs.com/package/npx
+[now]: https://zeit.co/now
+[primer.style]: https://primer.style

package/contributor-docs/adrs/adr-001-typescript.md

@@ -0,0 +1,23 @@
+# ADR 1: TypeScript
+
+## Status
+
+Approved 2021-01-15
+
+## Context
+
+Primer React components was originally released without TypeScript type definitions, making it difficult for engineers to consume the library in TypeScript applications. In [July 2019](https://github.com/primer/react/commit/2983c935ea9ad600c04078adb25e40c3624c11fa#diff-7aa4473ede4abd9ec099e87fec67fd57afafaf39e05d493ab4533acc38547eb8), we created an [ambient declaration](https://www.geeksforgeeks.org/typescript-ambients-declaration/) file (`index.d.ts`) file to provide type definitions for TypeScript applications without having to rewrite Primer React components in TypeScript.
+
+`index.d.ts` has been an effective stopgap, enabling teams to build complex applications with Primer React components and TypeScript. However, because `index.d.ts` is disconnected from the implementation code, we've struggled to keep the type definitions up-to-date and accurate, as evidenced by [many](https://github.com/primer/react/issues/906) [TypeScript](https://github.com/primer/react/issues/540) [bug](https://github.com/primer/react/issues/520) [reports](https://github.com/primer/react/issues/534). As the library continues to grow in size and complexity, manually maintaining type definitions will become unsustainable.
+
+## Decision
+
+We will rewrite Primer React components in TypeScript.
+
+## Consequences
+
+- Type definitions can be generated by the TypeScript compiler, eliminating bugs caused by hand-written type definitions.
+- Engineers can upstream components from other TypeScript projects at GitHub without having to remove type annotations, improving the contributor experience.
+- We can refactor components with increased confidence.
+- Component prop documentation can be generated by [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript), eliminating inaccurate and out-of-date hand-written prop documentation.
+- New contributors will need some familiarity with TypeScript in order to make code contributions.