@primer/components 31.0.0-rc.ee65b7f1 → 31.0.0

package/contributor-docs/CONTRIBUTING.md

@@ -1,274 +0,0 @@
-# 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

@@ -1,23 +0,0 @@
-# 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.

package/contributor-docs/adrs/adr-002-behavior-isolation.md

@@ -1,108 +0,0 @@
-# ADR 2: Isolating behaviors through custom clements and vanilla JavaScript
-
-## Status
-
-Approved 2021-02-04
-
-## Related documents
-
-- April 18th, 2018: [Custom Elements Example](https://github.com/primer/react/pull/13)
-- May 8th, 2018: [Custom Elements Experiment](https://github.com/primer/react/pull/14)
-- May 18th 2018: [React & Custom Elements](https://docs.google.com/document/d/1b6D2jW3ztQJiKEtQINbb4JoHJ3F3szU6lBX-fGce6aY/edit?usp=sharing)
-- October 16th 2019: [Issue exploring pros & cons of reusing .com JS in React](https://github.com/github/issues-index-experiment/issues/90)
-- November 15th 2019: [Experiment porting PRC to web components](https://github.com/github/ui-engineering/issues/12#issuecomment-558257842)
-- November 27th 2019: [Usage of custom elements in IIE project](https://github.com/github/issues-index-experiment/pull/133)
-- November 27th 2019: [Styling custom elements with styled components](https://github.slack.com/archives/CMZ4DC9BL/p1574883198055600)
-- June 9th 2020: [Discussion in Slack about using skatejs for SSR](https://github.slack.com/archives/C0ER2LCG2/p1591707104461300)
-- November 10th 2020: [Replace dialog with details-dialog](https://github.com/primer/react/issues/907)
-- January 27th 2021: [Guidelines for authoring behaviors](https://github.com/primer/react/pull/992)
-- February 1st 2021: [Example of a vanilla JS behavior & accompanying hook](https://github.com/T-Hugs/components/commit/105c3a191681381377f5aa193cb241a2189db8a6)
-
-## Providing behaviors via custom elements
-
-### Context
-
-Throughout the last few years folks from the Design Infrastructure, Web Systems, and UI Platform teams have discussed the idea of using custom elements for behaviors in Primer React. The main goal of using custom elements in Primer React is to be able to author behaviors once and reuse them in any framework. Several experiments have been conducted which are listed above.
-
-### Assumptions
-
-De-duplication is not our highest or only priority. Attempts at de-duplication must be weighed against changes to the maintainer, developer, and customer experience.
-
-### Findings
-
-#### Developer experience regressions
-
-- Custom elements rendering their own subtrees (ShadowDOM) requires polyfills for as-yet implemented specifications. This means Primer React will accumulate added complexity if we were to implement Custom Elements with ShadowDOM.
-
-- Implementing Custom Elements in Primer React will require a division of client side and server side code, as custom elements should only be executed in a browser environment. Currently Primer React is "isomorphic" - in that the code can be executed anywhere that React can be, which includes NodeJS server runtimes, as well as the client side. While not insurmountable this does mean Primer React will accumulate added complexity, which likely will be surfaced to the user.
-
-- While it's possible to add server side libraries to enable Custom Elements to be rendered on the Server, this adds more complexity and is antithetical to the usage patterns of custom elements.
-
-- As of this writing, you cannot style custom elements with styled-components[^1]. This means that if a component wants to use a custom element to get behaviors and you also want to style that component, you must use another wrapper div to apply styles. This is a bug in styled-components and should be fixed in the next release.
-
-#### Incompatibility with some React tools
-
-Some of our GitHub custom elements such as `details-dialog` and `details-menu` make assumptions about the DOM tree. For example, `details-dialog` expects a `details` element to wrap the custom element and uses this assumption[^2] to determine whether or not clicks are happening inside or outside of the dialog and closes the dialog if the click happened outside of the dialog. This makes sense in most cases and is a nice way of enforcing proper usage of the details element, but breaks down when used with [React Portals](https://reactjs.org/docs/portals.html) which are often used to ensure menus are displayed correctly in cases where a parent has an overflow: hidden applied to it, or incompatible z-index.
-
-#### Extensibility
-
-Building behaviors in React Hooks gives us the ability to provide things like state and state change hooks to the consumer of the component. This allows the user to build on additional behaviors to the component based on the state or other variables provided to the component consumer. Doing the same with custom elements would require listening to events on the document[^3] and reacting to them. This is certainly do-able, but goes against some of the foundational principles of React (reacting to changes in the DOM vs changes in React state).
-
-#### Organizational overhead
-
-- GitHub’s custom elements are all managed in different repos which introduces more maintenance overhead.
-  - You'd need to npm link while developing if you want to test changes out with the presentational components themselves instead of making changes and seeing updates instantly. npm link usually doesn't work well with hot module reloading either.
-  - You'd need to draft & publish releases to both libraries every time you want to update the behavior
-  - If the behaviors are shared between github.com and Primer React, you'd need to do careful testing in both environments to make sure that changes don't create any regressions. That greatly widens the context that engineers need to keep in mind every time a change is made.
-- Reacting to changes will take a bit more time as we’ll need to orchestrate releases between custom elements and Primer React - as opposed to having behaviors already present in Primer React which can be versioned in lockstep.
-- Engineers who want to contribute to Primer React Components to build new components and behaviors would need to be familiar with both custom elements and React, two very different paradigms, and context switch between the two.
-
-#### Other
-
-- The custom element and web component API progress slower than React due to changes needing to go through the whatwq standards process.
-
-#### Risks of not switching to custom elements for behaviors
-
-- We spend extra time building behaviors in React that have already been built in our [custom elements library](https://github.github.io/web-systems-documentation/#custom-elements).
-  - There are currently 19 behaviors/components listed on the custom elements documentation site. Several of these we have already implemented in React in either Priemr React, Doctocat, or other React applications at GitHub which can be upstreamed (details-dialog, details-menu, clipboard-copy, text-expander, autocomplete, task-list via drag and drop hooks, tab-container, text-expander).
-- We decide not to invest further in React at GitHub and have wasted time we could have spent building more custom elements.
-  - This seems unlikely as there seems to be clear consensus that we will continue to build more and more highly interactive products.
-- The React library is abandoned and becomes obsolete.
-  - This is a risk with any technology that we may use, seems highly unlikely in the near term.
-  - While also a possibility for custom elements, the track record demonstrates deprecations of Web APIs is extremely rare and has a long deprecation path.
-- Behaviors in github.com using custom elements and behaviors in Primer REact diverge, leading to an inconsistent experience.
-  - This is probably the biggest risk we face, but moving to custom elements isn’t necessarily the only or best solution. We should explore other ways of detecting divergence such as integration tests.
-
-## Providing behaviors through vanilla JavaScript
-
-A simpler method of isolating component behaviors is to implement them in vanilla JavaScript (or TypeScript). This way, they can be shared between React components and web components. Both types of consumers would need to hook up the vanilla behavior to the component(s) that use(s) them.
-
-In some cases, this strategy is very straightforward. When a behavior can be made to have no dependencies other than the DOM, it is easy to isolate and consume in various frameworks. Behaviors that have effects on interactions/events, shared state, and component styles will be more difficult to isolate in this manner.
-
-### Interactions and events
-
-Many user interactions rely on DOM events, such as `click`, `keypress`, and `focus`. React's event system is _not_ the same as the native DOM event system. React implements a [SyntheticEvent](https://reactjs.org/docs/events.html) that wraps native events. Working with both `SyntheticEvent`s and native events simultaneously is significant additional complexity for maintainers and consumers. However, vanilla JavaScript must operate only using native events. This makes isolating behaviors that automatically hook up event listeners to DOM elements difficult to achieve, and the resulting simultaneous usage of native events and `SyntheticEvent` has the potential to degrade both the maintainer's and the consumer's developer experience using Primer React.
-
-### Shared state
-
-There are countless ways to manage state in a web application. React has its own ecosystem of state management strategies and libraries (in addition to its own primitive constructs for state management). Since there is no standard state management pattern in vanilla JavaScript, introducing such a pattern would add a new layer of complexity to the component behavior API.
-
-### Component styles
-
-Since Primer React uses styled-components to manage CSS styles, any behaviors that affect styles should be doing so with styled-components. Any vanilla JavaScript behaviors that affect styles will add complexity by introducing a second mechanism for applying styles, since they will not be able to use styled-components.
-
-## Decision
-
-### Custom elements
-
-Due to the challenges listed above and our priorities listed in the [Assumptions](#assumptions) section, we are not investing time in building out behaviors with custom elements in our Primer React library. Instead, we should spend time expanding coverage using React Hooks and focus on finding other approaches for making sure implementation of behaviors in our different stacks are consistent (such as integration tests).
-
-### Vanilla JavaScript behaviors
-
-Some behaviors can be implemented as vanilla JavaScript without introducing additional complexity to Primer React or its consumers. In cases where this is possible, behaviors will be implemented with no dependencies except the DOM and consumed within React Hooks to provide their functionality to Primer React.
-
-In general, _portions of behaviors_ that affect or rely on **user interactions and events**, **shared state**, or **CSS styles** should be kept in React Hooks. Parts of the behavior that can be implemented in isolation of these concepts should be built with no dependency on React or other libraries.
-
-[^1]: https://codesandbox.io/s/demo-styling-custom-element-g973d?file=/src/index.tsx
-[^2]: https://github.com/github/details-dialog-element/blob/main/src/index.ts#L195
-[^3]: https://github.com/github/details-dialog-element#details-dialog-close

package/contributor-docs/behaviors.md

@@ -1,132 +0,0 @@
-_Note: This documentation is a draft and is expected to undergo several revisions before being adopted._
-
-# Implementing Behaviors in Primer Components
-
-Behaviors in Primer Components are implemented via React Hooks. Primer Components provides two types of behaviors: generic behaviors and component behaviors.
-
-## Dependencies
-
-**External dependencies:** Third-party/external dependencies are not allowed, except under very strict circumstances. If you need to use an external dependency, open an issue and discuss with the team.
-
-**Internal dependencies:** Internal dependencies are fine and encouraged to reduce code duplication and maintain consistency. When taking an internal dependency, observe the following:
-
-- No circular dependencies
-- Components may depend on other components and component behaviors, but should avoid depending directly on generic behaviors.
-- Component behaviors may depend on other component behaviors and generic behaviors.
-- Generic behaviors may only depend on other generic behaviors.
-
-See below for a visualization of allowed dependencies.
-
-```
-               ____________
-              |            \*
-+-------------V--------+   /
-|   Generic behaviors  |---
-+----------------------+
-           ^
-          *|     ___________
-           |    |           \*
-+----------|----V-------+   /
-|  Component behaviors  |---
-+-----------------------+
-         ^
-        1|    _____
-         |   |     \*
-+--------|---V-+   /
-|  Components  |---
-+--------------+
-
-```
-
-## Generic behaviors
-
-Generic behaviors provide functionality that is not specific to any single component or class of components. If you can't tell which component it should operate on, it's probably a generic behavior. Generic behaviors are _low-level_. Generic behaviors may only have dependencies on other generic behaviors.
-
-### Examples
-
-- `useProvidedRefOrCreate`
-- `usePosition`
-- `useClickAway`
-- `useTypeAhead`
-
-## Component behaviors
-
-Component behaviors specifically implement behaviors for components. Therefore, hooks that implement component behaviors should always return an object containing props objects to be spread across the elements that make up the component's JSX. While component behaviors do not necessarily have to be one-to-one, **a component may only use one component behavior**. Sometimes it makes sense to use the same component behavior on several components. For example: the Dialog, Popover, and PointerBox components may all use the `usePopover` component behavior.
-
-### Examples
-
-- `usePopover`
-- `useComboBox`
-- `useFilteredSearch`
-- `useDetails`
-
-## Implementation guidelines
-
-All behaviors should be implemented as [React Hooks](https://reactjs.org/docs/hooks-intro.html).
-
-Component behaviors should be relatively brief. A component behavior should build a component's experience through the combination of several configured generic behaviors.
-
-Example: The Dialog component uses a `usePopover` behavior. The `usePopover` behavior in turn may call generic behaviors such as `usePosition` (to position the popover on the screen), `useClickAway` (to set up an event handler for clicking outside of the dialog), and `useFocusTrap` (to prevent focus from leaving the dialog while it is being shown).
-
-### Component implementation
-
-Component implementation is [discussed elsewhere](https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md#developing-components), but with respect to behaviors, follow these guidelines.
-
-- If a component has behaviors, it should make a call to exactly one component behavior hook.
-- The hook will return an object containing multiple props objects. Each of the returned objects are props that should be spread onto the appropriate JSX element.
-- Component implementations should be as clean as possible, mostly consisting of the JSX tree definition that the component renders.
-- Component props and, in some circumstances, context values, should serve as arguments to component behavior hooks.
-
-### Balancing API surface with supported scenarios
-
-The [YAGNI Principle](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it) cautions developers against building out functionality that isn't presently needed, but as a library, Primer Components should carefully balance the API surface area with building a library that functions for a wide range of use cases. Since it is difficult to define a quantitative test to determine whether or not a component or a behavior should support a certain scenario, there will be some subjectivity when it comes to choosing to build certain features. When adding a feature that seems too specific, try to _generalize_ it. Can multiple use cases be accounted for by implementing a single generalized feature? Can a known needed use case be extrapolated into a feature that supports that use case along with other use cases that are not yet known to be needed? If so, use these considerations when designing your APIs.
-
-### Sensible defaults, powerful configuration, and last-resort "escape hatches"
-
-- Defaults should take users down the “happy path” and place them into the “pit of success.”
-- Configuration allows the component to reach more use cases. Components that use configurations to deviate from defaults should be viewed as first-class supported scenarios, just as important as the defaults.
-- Escape hatches may be necessary to support consumers with requirements that we haven’t considered. It should be cleared that using escape hatches “voids your warranty,” yet, they should be fully documented.
-
-### Arguments to behaviors
-
-- As mentioned above, behaviors should have sensible defaults but powerful configuration. Behaviors are configured via arguments passed to the hook.
-- When possible, a hook should be able to be called with zero arguments to get all the defaults.
-- Each argument that is required should have an individual parameter on the hook function.
-- Optional arguments (i.e. “settings”) should be provided via a strongly typed settings object as the last argument to a hook function.
-
-### Return value of behavior hooks
-
-#### Component behavior hook return value
-
-Component behavior hooks produce _props_. Therefore, the return value of a component behavior should be a collection of props objects, intended to be spread onto JSX elements that render a component.
-
-- Each element of the object returned from a component behavior hook is a props object that can be spread onto a JSX element
-- The names of the keys should accurately indicate the JSX element onto which those props should be spread
-
-Example: The Dialog component uses a `usePopover` component behavior, which may return an object like:
-
-```
-{
-  popoverProps: PropsObject,
-  openClickTargetProps: PropsObject,
-  closeClickTargetProps: PropsObject
-}
-```
-
-Each of these props objects would then get spread onto their respective JSX elements.
-
-#### Generic behavior hook return value
-
-There are no restrictions on return values of generic behavior hooks. In fact, some behavioral hooks might not need to return anything. For example, a `useEscape` hook might simply set up a callback for an `Escape` keypress.
-
-### Refs
-
-- Often, a behavior will need to act on a real DOM element.
-- In this case, the hook should return a ref as part of the returned props for that element. The ref will get spread onto the element, giving the ref access to it.
-- Whenever you need a ref, it must be accepted as an optional setting to the hook. The hook then uses the `useProvidedRefOrCreate` hook to resolve a usable ref. Remember to return the resulting ref from the hook.
-
-## Testing behaviors
-
-- Whenever possible, test your changes in another application that makes heavy use of Primer Components.
-- You may even want to build and “marinate” your component in another application before merging a change to Primer Components.
-- Build the component, start using it in the application, and see how the component API feels. This approach works best for engineers at GitHub already working on a product written in React.