@primer/components 32.0.2-rc.859381a1 → 32.1.1-rc.b4502a34

package/docs/content/ActionList2.mdx

@@ -1,14 +1,14 @@
 ---
-title: ActionList
+title: ActionList v2
 status: Alpha
 source: https://github.com/primer/react/tree/main/src/ActionList2
 storybook: '/react/storybook?path=/story/composite-components-actionlist2'
-description: An ActionList is a list of items which can be activated or selected. ActionList is the base component for many of our menu-type components, including DropdownMenu and ActionMenu.
+description: An ActionList is a list of items that can be activated or selected. ActionList is the base component for many menu-type components, including DropdownMenu and ActionMenu.
 ---
 
 import {BorderBox, Avatar} from '@primer/components'
 import {ActionList} from '@primer/components/drafts'
-import {Props} from '../src/props'
+import {ComponentChecklist} from '../src/component-checklist'
 
 import {ImageContainer} from '@primer/gatsby-theme-doctocat'
 import {LinkIcon, AlertIcon, ArrowRightIcon} from '@primer/octicons-react'
@@ -357,3 +357,23 @@ render(<SelectFields />)
 
 - [ActionMenu](/ActionMenu)
 - [SelectPanel](/SelectPanel)
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: false,
+    usedInProduction: false,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: true,
+    hasFigmaComponent: true
+  }}
+/>

package/docs/content/Avatar.mdx

@@ -1,10 +1,10 @@
 ---
 title: Avatar
+status: Alpha
 componentId: avatar
 source: https://github.com/primer/react/blob/main/src/Avatar.tsx
 ---
 
-import {Props} from '../src/props'
 import {Avatar} from '@primer/components'
 
 ```jsx live
@@ -31,3 +31,23 @@ import {Avatar} from '@primer/components'
   <Avatar src="https://avatars.githubusercontent.com/primer" />
 </AvatarPair>
 ```
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: false,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/AvatarStack.mdx

@@ -1,12 +1,12 @@
 ---
 title: AvatarStack
+status: Alpha
+description: Use an avatar stack to display two or more avatars in an inline stack.
+source: https://github.com/primer/react/blob/main/src/AvatarStack.tsx
 ---
 
-import {Props} from '../src/props'
 import {AvatarStack} from '@primer/components'
 
-AvatarStack is used to display more than one Avatar in an inline stack.
-
 ### Default example
 
 ```jsx live
@@ -35,3 +35,23 @@ AvatarStack is used to display more than one Avatar in an inline stack.
 | :--------- | :---------------- | :-----: | :----------------------------------- |
 | alignRight | Boolean           |         | Creates right aligned AvatarStack    |
 | sx         | SystemStyleObject |   {}    | Style to be applied to the component |
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: false,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/BranchName.md

@@ -1,18 +1,38 @@
 ---
 title: BranchName
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/BranchName.tsx
 ---
 
 BranchName is a label-type component rendered as an `<a>` tag by default with monospace font.
 
-## Default example
-
-```jsx live live
+```jsx live
 <BranchName>a_new_feature_branch</BranchName>
 ```
 
-## Component props
+## Props
 
 | Name | Type   | Default | Description                         |
 | :--- | :----- | :-----: | :---------------------------------- |
 | as   | String |  `<a>`  | sets the HTML tag for the component |
 | href | String |         | a URL to link the component to      |
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: false,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/Breadcrumbs.md

@@ -1,6 +1,7 @@
 ---
 title: Breadcrumbs
 status: Alpha
+description: Use breadcrumbs to show navigational context on pages that are many levels deep in a site’s hierarchy. Breadcrumbs show and link to parent, grandparent, and sometimes great-grandparent pages.
 source: https://github.com/primer/react/blob/main/src/Breadcrumbs.tsx
 ---
 
@@ -27,7 +28,7 @@ This ensures that the NavLink gets `activeClassName='selected'`
 </Breadcrumbs>
 ```
 
-## Component props
+## Props
 
 ### Breadcrumbs
 
@@ -45,3 +46,23 @@ This ensures that the NavLink gets `activeClassName='selected'`
 | href      | string            |         | URL to be used for the Link                      |
 | selected  | boolean           | `false` | Used to style the link as selected or unselected |
 | sx        | SystemStyleObject |  `{}`   | Style to be applied to the component             |
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: false,
+    fullTestCoverage: false,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/Buttons.md

@@ -1,5 +1,6 @@
 ---
-title: Buttons
+title: Button
+status: Alpha
 ---
 
 `Button` is used for actions, like in forms, while `Link` is used for destinations, or moving from one page to another.

package/docs/content/Checkbox.md

@@ -0,0 +1,118 @@
+---
+title: Checkbox
+description: Use checkboxes to toggle between checked and unchecked states in a list or as a standalone form field
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/Checklist.tsx
+storybook: '/react/storybook?path=/story/forms-checkbox--default'
+---
+
+import {ComponentChecklist} from '../src/component-checklist'
+
+## Default example
+
+The `Checkbox` component can be used in controlled and uncontrolled modes.
+
+```jsx live
+<>
+  <Box as="form" sx={{p: 3, pt: 0, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="default-checkbox" />
+    <Text as="label" htmlFor="default-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Default checkbox
+    </Text>
+  </Box>
+  <Box as="form" sx={{p: 3, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="always-checked-checkbox" checked={true} />
+    <Text as="label" htmlFor="always-checked-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Always checked
+    </Text>
+  </Box>
+  <Box as="form" sx={{p: 3, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="always-unchecked-checkbox" checked={false} />
+    <Text as="label" htmlFor="always-unchecked-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Always unchecked
+    </Text>
+  </Box>
+
+  <Box as="form" sx={{p: 3, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="inactive-checkbox" checked={true} disabled />
+    <Text as="label" htmlFor="inactive-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Inactive
+    </Text>
+  </Box>
+</>
+```
+
+<Note variant="warning">
+Checkbox components should always be accompanied by a corresponding label to improve support for assistive technologies.
+</Note>
+
+## Indeterminate example
+
+An `indeterminate` checkbox state should be used if the input value is neither true nor false. This can be useful in situations where you are required to display an incomplete state, or one that is dependent on other input selections to determine a value.
+
+```jsx live
+<>
+  <Box as="form" sx={{p: 3, pt: 0, pb: 1, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="indeterminate-checkbox" onChange={() => {}} indeterminate={true} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor="controlled-checkbox">
+      <Text sx={{display: 'block'}}>Default checkbox</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-0`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-0`} checked={true} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-0`}>
+      <Text sx={{display: 'block'}}>Checkbox 1</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-1`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-1`} checked={false} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-1`}>
+      <Text sx={{display: 'block'}}>Checkbox 2</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-2`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-2`} checked={false} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-2`}>
+      <Text sx={{display: 'block'}}>Checkbox 3</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-3`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-3`} checked={false} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-3`}>
+      <Text sx={{display: 'block'}}>Checkbox 4</Text>
+    </Text>
+  </Box>
+</>
+```
+
+## Component props
+
+Native `<input>` attributes are forwarded to the underlying React `input` component and are not listed below.
+
+| Name           | Type        |  Default  | Description                                                                                                                                             |
+| :------------- | :---------- | :-------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| checked        | Boolean     | undefined | Optional. Modifies true/false value of the native checkbox                                                                                              |
+| defaultChecked | Boolean     | undefined | Optional. Checks the input by default in uncontrolled mode                                                                                              |
+| onChange       | ChangeEvent | undefined | Optional. A callback function that is triggered when the checked state has been changed.                                                                |
+| disabled       | Boolean     | undefined | Optional. Modifies the native disabled state of the native checkbox                                                                                     |
+| indeterminate  | Boolean     | undefined | Optional. Applies an [indeterminate](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#attr-indeterminate) state to the checkbox |
+
+## Component status
+
+<ComponentChecklist
+items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: false,
+    usageExamplesDocumented: false,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/CircleBadge.md

@@ -1,5 +1,6 @@
 ---
 title: CircleBadge
+status: Alpha
 ---
 
 Use CircleBadge to visually connect logos of third party services like in marketplace. Use CircleBadge.Icon to add an Octicon to the CircleBadge.

package/docs/content/CircleOcticon.md

@@ -1,5 +1,6 @@
 ---
 title: CircleOcticon
+status: Alpha
 ---
 
 CircleOcticon renders any Octicon with a circle background. CircleOcticons are most commonly used to represent the status of a pull request in the comment timeline.
@@ -7,7 +8,7 @@ CircleOcticon renders any Octicon with a circle background. CircleOcticons are m
 ## Default example
 
 ```jsx live
-<CircleOcticon icon={CheckIcon} size={32} sx={{bg: "success.fg", color: "fg.onEmphasis"}} />
+<CircleOcticon icon={CheckIcon} size={32} sx={{bg: 'success.fg', color: 'fg.onEmphasis'}} />
 ```
 
 ## Component props

package/docs/content/CounterLabel.md

@@ -1,6 +1,6 @@
 ---
 title: CounterLabel
-tags: pill
+status: Alpha
 ---
 
 Use the CounterLabel component to add a count to navigational elements and buttons.

package/docs/content/Details.md

@@ -1,5 +1,6 @@
 ---
-title: Details & useDetails hook
+title: Details
+status: Alpha
 ---
 
 `Details` is a styled `details` element for use with the `useDetails` hook. The `useDetails` hook returns the `open` state, a `setOpen` function to manually change the open state, and **`getDetailsProps` which must be spread onto your `Details` element in order for `Details` to get receive the proper behaviors provided by the hook**. See Kent Dodd's article on this pattern [here](https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters).

package/docs/content/Dialog.md

@@ -1,5 +1,6 @@
 ---
 title: Dialog
+status: Deprecated
 ---
 
 import State from '../components/State'

package/docs/content/Dialog2.mdx

@@ -1,5 +1,6 @@
 ---
 title: Dialog v2
+status: Alpha
 ---
 
 import State from '../components/State'

package/docs/content/Dropdown.md

@@ -1,5 +1,6 @@
 ---
 title: Dropdown
+status: Deprecated
 ---
 
 The Dropdown component is a lightweight context menu for housing navigation and actions.

package/docs/content/DropdownMenu.mdx

@@ -1,5 +1,6 @@
 ---
 title: DropdownMenu
+status: Alpha
 ---
 
 A `DropdownMenu` provides an anchor (button by default) that will open a floating menu of selectable items. The menu can be opened and navigated using keyboard or mouse. When an item is selected, the menu will close and the `onChange` callback will be called. If the default anchor button is used, the anchor contents will be updated with the selection.

package/docs/content/FilterList.md

@@ -1,5 +1,6 @@
 ---
 title: FilterList
+status: Alpha
 ---
 
 The FilterList component is a menu with filter options that filter the main content of the page.

package/docs/content/FilteredSearch.md

@@ -1,5 +1,6 @@
 ---
 title: FilteredSearch
+status: Alpha
 ---
 
 The FilteredSearch component helps style a Dropdown and a TextInput side-by-side.

package/docs/content/Flash.md

@@ -1,5 +1,6 @@
 ---
 title: Flash
+status: Alpha
 ---
 
 The Flash component informs users of successful or pending actions.

package/docs/content/FormGroup.md

@@ -1,5 +1,6 @@
 ---
 title: FormGroup
+status: Alpha
 ---
 
 Adds styles for multiple form elements used together.

package/docs/content/Header.md

@@ -1,5 +1,6 @@
 ---
 title: Header
+status: Alpha
 ---
 
 Use the `Header` component to create a header that has all of its items aligned vertically with consistent horizontal spacing.

package/docs/content/Heading.md

@@ -1,5 +1,6 @@
 ---
 title: Heading
+status: Alpha
 ---
 
 The Heading component will render an html `h2` tag without any default styling. Other heading level elements `h1-h6` are available through use of the `as` prop (see [System Props](/system-props) for additional explanation). Please reference the [w3 recommendations for headings](https://www.w3.org/WAI/tutorials/page-structure/headings/) to ensure your headings provide an accessible experience for screen reader users.
@@ -7,8 +8,11 @@ The Heading component will render an html `h2` tag without any default styling.
 **Attention:** Make sure to include a valid heading element to render a Heading component other than `h2` (`<Heading as="h1">H1 Element</Heading>`).
 
 ## Default example
+
 ```jsx live
-<Heading fontSize={1} mb={2}>H2 heading with fontSize={1}</Heading>
+<Heading fontSize={1} mb={2}>
+  H2 heading with fontSize={1}
+</Heading>
 ```
 
 ## System props
@@ -17,6 +21,6 @@ Heading components get `TYPOGRAPHY` and `COMMON` system props. Read our [System
 
 ## Component props
 
-| Prop name | Type    | Description                                      |
-| :-------- | :------ | :----------------------------------------------- |
-| as        | String or React element  | sets the HTML tag for the component              |
+| Prop name | Type                    | Description                         |
+| :-------- | :---------------------- | :---------------------------------- |
+| as        | String or React element | sets the HTML tag for the component |

package/docs/content/Label.md

@@ -1,5 +1,6 @@
 ---
 title: Label
+status: Alpha
 ---
 
 The Label component is used to add contextual metadata to a design. Visually it styles text, adds padding, and rounded corners.

package/docs/content/LabelGroup.md

@@ -1,5 +1,6 @@
 ---
 title: LabelGroup
+status: Alpha
 ---
 
 The LabelGroup component is used to add commonly used margins and wrapping for groups of Labels.

package/docs/content/Link.md

@@ -1,5 +1,6 @@
 ---
 title: Link
+status: Alpha
 ---
 
 The Link component styles anchor tags with default hyperlink color cues and hover text decoration. `Link` is used for destinations, or moving from one page to another.

package/docs/content/Overlay.mdx

@@ -1,5 +1,6 @@
 ---
 title: Overlay
+status: Alpha
 ---
 
 An `Overlay` is a flexible floating surface, used to display transient content such as menus, selection options, dialogs, and more. Overlays use shadows to express elevation. The `Overlay` component handles all behaviors needed by overlay UIs as well as the common styles that all overlays should have. `Overlay` is the base component for many of our overlay-type components.

package/docs/content/Pagehead.md

@@ -1,5 +1,6 @@
 ---
 title: Pagehead
+status: Alpha
 ---
 
 Give a page a clear, separated title and optional top nav by using Pagehead.

package/docs/content/Pagination.md

@@ -1,5 +1,6 @@
 ---
 title: Pagination
+status: Alpha
 ---
 
 import State from '../components/State'

package/docs/content/PointerBox.md

@@ -1,5 +1,6 @@
 ---
 title: PointerBox
+status: Alpha
 ---
 
 PointerBox is a [BorderBox](./BorderBox) component with a caret added to it.

package/docs/content/Popover.md

@@ -1,5 +1,6 @@
 ---
 title: Popover
+status: Alpha
 ---
 
 Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.

package/docs/content/Portal.mdx

@@ -1,5 +1,6 @@
 ---
 title: Portal
+status: Alpha
 ---
 
 Portals allow you to create a separation between the logical React component hierarchy and the physical DOM. See the [React documentation on portals](https://reactjs.org/docs/portals.html) for an in-depth explanation.

package/docs/content/Position.md

@@ -1,5 +1,5 @@
 ---
-title: Position Components
+title: Position
 status: Deprecated
 ---
 
@@ -69,14 +69,7 @@ Use [Box](/Box) instead.
 
   <Heading my={2}>Sticky</Heading>
 
-  <Box
-    borderWidth="1px"
-    borderStyle="solid"
-    borderColor="success.emphasis"
-    borderRadius={2}
-    border={1}
-    height={500}
-  >
+  <Box borderWidth="1px" borderStyle="solid" borderColor="success.emphasis" borderRadius={2} border={1} height={500}>
     <Sticky top={0} bg="success.subtle" p={6}>
       I'm sticky!
     </Sticky>

package/docs/content/ProgressBar.mdx

@@ -1,6 +1,7 @@
 ---
 title: ProgressBar
 componentId: progress_bar
+status: Alpha
 source: https://github.com/primer/react/blob/main/src/ProgressBar.tsx
 ---
 

package/docs/content/SelectMenu.md

@@ -1,5 +1,6 @@
 ---
 title: SelectMenu
+status: Deprecated
 ---
 
 The `SelectMenu` components are a suite of components which can be combined together to make several different variations of our GitHub select menu. At it's most basic form, a select menu is comprised of a `SelectMenu` wrapper, which contains a `summary` component of your choice and a `Select.Modal` which contains the select menu content. Use `SelectMenu.List` to wrap items in the select menu, and `SelectMenu.Item` to wrap each item.

package/docs/content/SideNav.md

@@ -1,5 +1,6 @@
 ---
 title: SideNav
+status: Alpha
 ---
 
 The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **SideNav elements have no default width or positioning.**

package/docs/content/StateLabel.md

@@ -1,5 +1,6 @@
 ---
 title: StateLabel
+status: Alpha
 ---
 
 Use StateLabel components to show the status of an issue or pull request.

package/docs/content/StyledOcticon.md

@@ -1,6 +1,6 @@
 ---
 title: StyledOcticon
-tags: icon
+status: Alpha
 ---
 
 StyledOcticon renders an [Octicon](https://octicons.github.com) with common system props, including `color`, margin, and padding.

package/docs/content/SubNav.md

@@ -1,5 +1,6 @@
 ---
 title: SubNav
+status: Alpha
 ---
 
 Use the SubNav component for navigation on a dashboard-type interface with another set of navigation components above it. This helps distinguish navigation hierarchy.

package/docs/content/TabNav.md

@@ -1,5 +1,6 @@
 ---
 title: TabNav
+status: Alpha
 ---
 
 Use the TabNav component to style navigation with a tab-based selected state, typically used for navigation placed at the top of the page.

package/docs/content/Text.md

@@ -1,5 +1,6 @@
 ---
 title: Text
+status: Alpha
 ---
 
 The Text component is a wrapper component that will apply typography styles to the text inside.
@@ -8,9 +9,15 @@ The Text component is a wrapper component that will apply typography styles to t
 
 ```jsx live
 <>
-  <Text as='p' fontWeight="bold">bold</Text>
-  <Text as='p' color="danger.fg">danger color</Text>
-  <Text as='p' color="fg.onEmphasis" bg="neutral.emphasis" p={2}>inverse colors</Text>
+  <Text as="p" fontWeight="bold">
+    bold
+  </Text>
+  <Text as="p" color="danger.fg">
+    danger color
+  </Text>
+  <Text as="p" color="fg.onEmphasis" bg="neutral.emphasis" p={2}>
+    inverse colors
+  </Text>
 </>
 ```