@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/docs/content/getting-started.md

@@ -0,0 +1,134 @@
+---
+title: Getting started
+---
+
+## Installation
+
+To get started using Primer React, install the package and its peer dependencies with your package manager of choice:
+
+```bash
+# with npm
+npm install @primer/components react react-dom styled-components
+
+# with yarn
+yarn add @primer/components react react-dom styled-components
+```
+
+You can now import Primer React from the main package module:
+
+```javascript
+// using import syntax
+import {Box, Flex} from '@primer/components'
+
+// using require syntax
+const {Box, Flex} = require('@primer/components')
+```
+
+### Polyfills & Browser Support
+
+Primer React supports the current versions of [Chrome](https://www.google.com/chrome/), [Firefox](http://www.mozilla.org/firefox/), [Safari](http://www.apple.com/safari/), and [Microsoft Edge](https://www.microsoft.com/en-us/windows/microsoft-edge), as well as the [Firefox Extended Support Release](https://www.mozilla.org/en-US/firefox/organizations/). This is in-line with [GitHub's Browser Support](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/supported-browsers).
+
+Primer React does not transform code to support older ECMAScript versions, such as ES5, and it uses ECMAScript features such as `Object.assign`, as well as syntax features such as native classes and Object destructuring and spreading.
+
+Environments that Primer React is used in should have all the necessary polyfills to comply with the latest code standards, as Primer React will not ship with these. Additionally, as Primer React does not transform code to support older versions, it may be necessary for projects to transform this code if support for older browsers (such as Edge 18) is needed.
+
+### Minimizing bundle size
+
+Module bundlers that use ECMAScript modules (ESM) will automatically tree-shake Primer React, ensuring that no unused code is included in your final bundle. However, if you're not using ESM, you may be able to drastically reduce the size of your final bundle by importing components individually from the `lib` subfolder:
+
+```javascript
+// using import syntax
+import Box from '@primer/components/lib/Box'
+import Flex from '@primer/components/lib/Flex'
+
+// using require syntax
+const Box = require('@primer/components/lib/Box')
+const Flex = require('@primer/components/lib/Flex')
+```
+
+Note that the modules in the `lib` folder are CommonJS-style modules; if you're using ESM and a compatible module bundler, importing files individually from `lib` provides no benefit.
+
+### Peer dependencies
+
+Primer React ships with a few libraries labeled as peer dependencies. These libraries are separated because they are commonly already installed in the host project and having multiple versions can introduce errors.
+
+Primer React requires the following libraries to be installed along with it:
+
+- `styled-components` at version 4.0.0 or higher
+- `react` at versions 16.8.0 or higher
+- `react-dom` at versions 16.8.0 or higher
+
+## ThemeProvider
+
+For Primer React to work correctly and accurately apply color schemes, you must add `ThemeProvider` to the root of your application:
+
+```jsx
+import {ThemeProvider} from '@primer/components'
+
+function App() {
+  return (
+    <ThemeProvider>
+      <div>...</div>
+    </ThemeProvider>
+  )
+}
+```
+
+See [Theming](/theming) for more details on advanced configuration, color modes, and overriding theme values.
+
+## BaseStyles
+
+In order to set baseline color, font-family, and line-heights across your project, you will need to establish base Primer styles for your app by wrapping all of your Primer components in `<BaseStyles>` at the root of your app:
+
+```jsx
+import {BaseStyles, Box, Heading} from '@primer/components'
+
+export default const MyApp = () => (
+  <BaseStyles>
+    <Box m={4}>
+      <Heading mb={2}>Hello, world!</Heading>
+      <p>This will get Primer text styles.</p>
+    </Box>
+  </BaseStyles>
+)
+```
+
+This will apply the same `color`, `font-family`, and `line-height` styles to the `<body>` as [Primer CSS's base styles](https://github.com/primer/css/blob/master/src/base/base.scss#L15-L20).
+
+## Static CSS rendering
+
+If you're rendering React components both server- 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.
+
+## TypeScript
+
+Primer React includes TypeScript support and ships with its own typings. You will need still need to to install type typings for the peer dependencies if you import those in your own application code.
+
+Once installed, you can import components and their prop type interfaces from the `@primer/components` package:
+
+```typescript
+import {BorderBox, BorderBoxProps} from '@primer/components'
+```
+
+### Fixing "Duplicate identifier 'FormData'"
+
+Ever since `@types/styled-components` version `4.1.19`, it has had a dependency on both `@types/react` and `@types/react-native`. Unfortunately, those declarations clash; for more information, see [issue 33311](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33311) and [issue 33015](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33015) in the DefinitelyTyped repo.
+
+You may run into this conflict even if you're not importing anything from `react-native` or don't have it installed. This is because some package managers hoist packages to the top-level `node_modules` folder, and the TypeScript compiler automatically includes types from all folders in `node_modules/@types` by default.
+
+The TypeScript compiler allows you to opt-out of this behavior [using the `typeRoots` and `types` configuration options](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types), and the best solution for this error — for now — seems to be to opt out the automatic inclusion of `node_modules/@types` and instead list the types you want to be included individually.
+
+In your `tsconfig.json`, set the `types` array under the `compilerOptions` like so:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node", "react", "styled-components", "jest"]
+  }
+}
+```
+
+Of course, customize the array based on the `@types/` packages you have installed for your project.
+
+## Silencing warnings
+
+Like React, Primer React emits warnings to the JavaScript console under certain conditions, like using deprecated components or props. Similar to React, you can silence these warnings by setting the `NODE_ENV` environment variable to `production` during bundling.

package/docs/content/index.md

@@ -0,0 +1,33 @@
+---
+title: Getting started
+---
+
+import {HeroLayout} from '@primer/gatsby-theme-doctocat'
+export default HeroLayout
+
+## Primer React
+
+Primer React is a React implementation of GitHub's [Primer Design System](https://primer.style/) 🎉
+
+## Principles
+
+- Everything is a component.
+- 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 wrapping or extending components for more complex operations.
+- Maintain design system consistency with utilities as props (for spacing, color, font-size, line-height, widths, and radii).
+
+## Getting started
+
+Check out [our getting started guide](/getting-started) for everything you need to know about installing and using Primer React.
+
+## Local development
+
+To run `@primer/components` locally when adding or updating components:
+
+1. Clone this repo: `git clone https://github.com/primer/react`
+2. Install dependencies: `npm install`
+3. Run the dev app: `npm start`
+
+> 👉 See [the contributing docs](https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md) for more info on code style, testing, and coverage.

package/docs/content/linting.md

@@ -0,0 +1,35 @@
+---
+title: Linting
+description: Primer React offers an ESLint plugin to enforce best practices and fix common problems. 
+---
+
+<Note variant="warning">
+
+`eslint-plugin-primer-react` is experimental. Please report issues in the [primer/react](https://github.com/primer/react) repository.
+
+</Note>
+
+## Installation
+
+1. Assuming you already have [ESLint](https://www.npmjs.com/package/eslint) and [Primer React](https://github.com/primer/react) installed, run:
+
+   ```shell
+   npm install --save-dev eslint-plugin-primer-react
+
+   # or
+   
+   yarn add --dev eslint-plugin-primer-react
+   ```
+
+2. In your [ESLint configuration file](https://eslint.org/docs/user-guide/configuring/configuration-files), extend the recommended Primer React ESLint config:
+
+   ```js
+   {
+     "extends": [
+       // ...
+       "plugin:primer-react/recommended"
+     ]
+   }
+   ```
+
+See the [eslint-plugin-primer-react](https://github.com/primer/eslint-plugin-primer-react) respository for a list of included lint rules.

package/docs/content/overriding-styles.mdx

@@ -0,0 +1,79 @@
+---
+title: Overriding styles with the sx prop
+---
+
+Our goal with Primer React is to hit the sweet spot between providing too little and too much styling flexibility; too little and the design system is too rigid, and too much and it becomes too difficult to maintain a consistent style. Our components are designed to cover common usage patterns, but sometimes a component just isn't _quite_ flexible enough to look the way you need it to look. For those cases, we provide the `sx` prop.
+
+The `sx` prop allows ad-hoc styling that is still theme-aware. Declare the styles you want to apply in CamelCase object notation, and try to use theme values in appropriate CSS properties when possible. If you've passed a custom theme using `ThemeProvider` or a `theme` prop, the `sx` prop will honor the custom theme. For more information on theming in Primer React, check out [the Primer Theme documentation](/primer-theme).
+
+## When to use the `sx` prop
+
+The `sx` prop provides a lot of power, which means it is an easy tool to abuse. To best make use of it, we recommend following these guidelines:
+
+- Use the `sx` prop for small stylistic changes to components. For more substantial changes, consider abstracting your style changes into your own wrapper component.
+- Avoid nesting and pseudo-selectors in `sx` prop values when possible.
+
+## Basic example
+
+This example demonstrates applying a bottom border to `Heading`, a component that does not receive `BORDER` system props. The `borderBottomWidth` value comes from `theme.borderWidths` and `borderBottomColor` comes from `theme.colors`.
+
+```jsx live
+<Heading pb={2}>Heading</Heading>
+
+<Heading
+  pb={2}
+  sx={{
+    borderBottomWidth: 1,
+    borderBottomColor: 'border.primary',
+    borderBottomStyle: 'solid'
+  }}>
+    Heading with bottom border
+</Heading>
+```
+
+## Responsive values
+
+Just like [values passed to system props](https://styled-system.com/responsive-styles), values in the `sx` prop can be provided as arrays to provide responsive styling.
+
+```jsx live
+<Box
+  borderWidth="1px"
+  borderStyle="solid"
+  borderColor="border.primary"
+  borderRadius={2}
+  p={2}
+  sx={{
+    bg: ['bg.primary', 'bg.info', 'bg.success', 'bg.warning', 'bg.danger']
+  }}
+>
+  Responsive background color
+</Box>
+```
+
+## Nesting, pseudo-classes, and pseudo-elements
+
+The `sx` prop also allows for declaring styles based on media queries, psueudo-classes, and pseudo-elements. This example, though contrived, demonstrates the ability:
+
+```jsx live
+<Box
+  sx={{
+    '> *': {
+      borderWidth: 1,
+      borderColor: 'border.primary',
+      borderStyle: 'solid',
+      borderBottomWidth: 0,
+      padding: 2,
+      ':last-child': {
+        borderBottomWidth: 1
+      },
+      ':hover': {
+        bg: 'border.tertiary'
+      }
+    }
+  }}
+>
+  <Box>First</Box>
+  <Box>Second</Box>
+  <Box>Third</Box>
+</Box>
+```

package/docs/content/philosophy.md

@@ -0,0 +1,23 @@
+---
+title: Primer React Philosophy
+---
+
+## Presentational Components
+ We are focusing primarily on presentational components that help standardize common design patterns. Primer React components don't handle fetching and submitting data to/from APIs. If you would like to handle data in a Primer Component, feel free to create a wrapper around the Primer Component to do so.
+
+## Assume that people will break the rules, provide safe ways for them to do so
+While we aim to standardize design in Primer React, we also provide some flexibility with constraint-based props. We offer system props via [styled-system](https://github.com/styled-system/styled-system) to allow users of the components to make small customizations, such as color and spacing, using values from the theme. Users also have the option to override the theme with a theme of their own.
+
+
+## Pattern Components vs Helper Components
+
+Our components can roughly be categorized into two different component types:
+
+
+- Pattern Components
+
+Pattern components help us repeat commonly used UI patterns and interactions in order to maintain our brand and provide a great user experience. Some examples of pattern components are `Button`, `Avatar`, or `Label`.
+
+- Helper Components
+
+Helper components are components that help the user achieve common CSS patterns while maintaining some control over values used. Some examples of helper components are `Flex`, `Text`, `Grid`, and the `Position` components.

package/docs/content/primer-theme.md

@@ -0,0 +1,89 @@
+---
+title: Primer Theme
+---
+
+import {theme} from '@primer/components'
+
+Primer React components come with built-in access to our Primer theme. The [theme file](https://github.com/primer/react/blob/main/src/theme-preval.ts) contains an object which holds values for common variables such as color, fonts, box shadows, and more. Our theme file pulls many of its color and typography values from [primer-primitives](https://github.com/primer/primer-primitives).
+
+Many of our theme keys correspond to system props on our components. For example, if you'd like to set the max width on a `<Box>` set the `maxWidth` prop to `medium`: `<Box maxWidth='medium'>`
+
+In the background, [styled-system](https://github.com/styled-system/styled-system) does the work of finding the `medium` value from `maxWidth` key in the theme file and applying the corresponding CSS.
+
+Our full theme can be found [here](https://github.com/primer/react/blob/main/src/theme-preval.js).
+
+### Custom Theming
+
+Custom theming is an optional way to override the Primer values that control color, spacing, typography, and other aspects of our components.
+
+There are two ways to change the theme of Primer components:
+
+1. You can override the entire theme for an entire tree of components using the `<ThemeProvider>` from [styled-components]:
+
+   ```javascript
+   import {Box, Button, Text, theme as primer} from '@primer/components'
+   import {ThemeProvider} from 'styled-components'
+
+   // a theme with custom spacing and font sizes
+   const theme = {
+     ...primer,
+     space: [0, 8, 16, 32, 64],
+     fontSizes: [10, 12, 16, 24, 48]
+   }
+
+   // override
+   theme.colors.bodytext = '#111'
+
+   export default () => (
+     <ThemeProvider theme={theme}>
+       <Box color="bodytext" p={4}>
+         <Text fontSize={4}>Hello, world!</Text>
+       </Box>
+     </ThemeProvider>
+   )
+   ```
+
+   **⚠️ Note: [styled-components]'s `<ThemeProvider>` only allows exactly one child.**
+
+2. You can merge the Primer theme with your custom theme using Object.assign:
+
+   ```javascript
+   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:
+
+   ```javascript
+   import {Text} from '@primer/components'
+
+   const theme = {
+     colors: {
+       magenta: '#f0f'
+     }
+   }
+
+   export default () => (
+     <Text theme={theme} color="magenta">
+       Hi, I'm magenta!
+     </Text>
+   )
+   ```
+
+   **☝️ This is an intentionally convoluted example, since you can use `<Text color='#f0f'>` out of the box.**
+
+Read the [styled-system docs](https://styled-system.com/#theming) for more information on theming in styled-system.
+
+[styled-components]: https://styled-components.com/

package/docs/content/ssr.mdx

@@ -0,0 +1,43 @@
+---
+title: Server-side rendering with Primer React
+---
+
+## SSR-safe ID generation
+
+Some Primer components generate their own DOM IDs. Those IDs must be isomorphic (so that server-side rendering and client-side rendering yield the same ID, avoiding hydration issues) and unique across the DOM. We use [@react-aria/ssr](https://react-spectrum.adobe.com/react-aria/ssr.html) to generate those IDs. In client-only rendering, this doesn't require any additional work. In SSR contexts, you must wrap your application with at least one `SSRProvider`:
+
+```
+import {SSRProvider} from '@primer/components';
+
+function App() {
+  return (
+    <SSRProvider>
+      <MyApplication />
+    </SSRProvider>
+  )
+}
+```
+
+`SSRProvider` maintains the context necessary to ensure IDs are consistent. In cases where some parts of the react tree are rendered asynchronously, you should wrap an additional `SSRProvider` around the conditionally rendered elements:
+
+```
+function MyApplication() {
+  const [dataA] = useAsyncData('a');
+  const [dataB] = useAsyncData('b');
+
+  return (
+    <>
+      <SSRProvider>
+        {dataA && <MyComponentA data={dataA} />}
+      </SSRProvider>
+      <SSRProvider>
+        {dataB && <MyComponentB data={dataB} />}
+      </SSRProvider>
+    </>
+  )
+}
+```
+
+This will ensure that the IDs are consistent for any sequencing of `dataA` and `dataB` being resolved.
+
+See also [React Aria's server side rendering documentation](https://react-spectrum.adobe.com/react-aria/ssr.html).

package/docs/content/system-props.mdx

@@ -0,0 +1,37 @@
+---
+title: System Props
+---
+
+import {PropsList, COMMON, LAYOUT, BORDER, TYPOGRAPHY, FLEX, POSITION, GRID} from '../components'
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+Primer React components utilize what we call "system props" to apply a standard set of props to each component. Using [styled-system](https://github.com/jxnblk/styled-system), groups of props are automatically applied to each component. Most components get the `COMMON` set of props which give the component access to color and space props (margin, padding, color and background color). These groups correspond to the `color` and `space` functions from `styled-system` which can be referenced in the styled system [table of style functions](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#core).
+
+To check which system props each component includes, check the documentation for that component.
+
+### The `as` prop
+
+All Primer React components have access to the `as` prop, provided by [styled-components](https://www.styled-components.com/docs/api#as-polymorphic-prop). We use the `as` prop to render a component with the styles of the passed component in `as`, but with the system props of the base component.
+
+For example, if you wanted to add some flex utilities to the `Text` component, you could do:
+
+```jsx live
+<Text as={Flex}>Hello!</Text>
+```
+
+### System Prop Categories
+
+| Category     | Included Props                        | styled-system docs                                                                                                                                                                                            |
+| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `COMMON`     | <PropsList systemProps={COMMON}/>     | [styled-system core docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#core)                                                                                                             |
+| `TYPOGRAPHY` | <PropsList systemProps={TYPOGRAPHY}/> | [styled-system typography docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#typography)                                                                                                 |
+| `BORDER`     | <PropsList systemProps={BORDER}/>     | [styled-system border docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#border)                                                                                                         |
+| `LAYOUT`     | <PropsList systemProps={LAYOUT}/>     | [styled-system layout docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#layout) <br/> [styled-system misc docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#misc) |
+| `POSITION`   | <PropsList systemProps={POSITION}/>   | [styled-system position docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#position)                                                                                                     |
+| `FLEX`       | <PropsList systemProps={FLEX}/>       | [styled-system flexbox docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#flexbox)                                                                                                       |
+| `GRID`       | <PropsList systemProps={GRID}/>       | [styled-system grid docs](https://github.com/styled-system/styled-system/blob/master/docs/table.md#grid-layout)                                                                                               |

package/docs/content/theme-reference.md

@@ -0,0 +1,16 @@
+---
+title: Theme reference
+description: The default theme object for Primer React components
+---
+
+import {theme} from '@primer/components'
+
+<Note>
+
+See [Theming](/theming) to learn how theming works in Primer React.
+
+</Note>
+
+Colors in this theme object are imported from [Primer Primitives](https://primer.style/primitives/colors).
+
+<pre><code class="language-json">{JSON.stringify(theme, null, 2)}</code></pre>