@primer/components 33.0.0-rc.b495ba4a → 33.1.0-rc.6856bcf5

package/docs/content/AnchoredOverlay.mdx

@@ -1,6 +1,8 @@
 ---
 title: AnchoredOverlay
 status: Alpha
+source: https://github.com/primer/react/blob/main/src/AnchoredOverlay/AnchoredOverlay.tsx
+storybook: https://primer.style/react/storybook?path=/story/generic-behaviors-anchoredoverlay--default-portal
 ---
 
 An `AnchoredOverlay` provides an anchor that will open a floating overlay positioned relative to the anchor.
@@ -8,7 +10,7 @@ The overlay can be opened and navigated using keyboard or mouse.
 
 See also [Overlay positioning](/Overlay#positioning).
 
-## Example
+## Examples
 
 ```jsx live
 <State default={false}>
@@ -35,3 +37,121 @@ See also [Overlay positioning](/Overlay#positioning).
   }}
 </State>
 ```
+
+## Props
+
+<PropsTable>
+  <PropsTableRow
+    name="open"
+    type="boolean"
+    defaultValue="false"
+    description="Determines whether the overlay portion of the component should be shown or not."
+  />
+  <PropsTableRow
+    name="onOpen"
+    type="(gesture: 'anchor-click' | 'anchor-key-press') => unknown"
+    description='A callback that is called whenever the overlay is currently closed and an "open gesture" is detected.'
+  />
+  <PropsTableRow
+    name="onClose"
+    type="(gesture: 'anchor-click' | 'click-outside' | 'escape') => unknown"
+    description='A callback that is called whenever the overlay is currently open and a "close gesture" is detected.'
+  />
+  <PropsTableRow
+    name="renderAnchor"
+    type="<T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element"
+    description={
+      <>
+        A custom function component used to render the anchor element. When renderAnchor is null, an anchorRef is
+        required.
+      </>
+    }
+  />
+  <PropsTableRow
+    name="anchorRef"
+    type="React.RefObject<HTMLElement>"
+    description={
+      <>
+        An override to the internal <InlineCode>renderAnchor</InlineCode> ref that will be used to position the overlay.
+        When <InlineCode>renderAnchor</InlineCode> is
+        <InlineCode>null</InlineCode>, this can be used to make an anchor that is detached from <InlineCode>
+          AnchoredOverlay
+        </InlineCode>.
+      </>
+    }
+  />
+  <PropsTableRow
+    name="side"
+    type={`| 'inside-top' 
+| 'inside-bottom' 
+| 'inside-left' 
+| 'inside-right' 
+| 'inside-center' 
+| 'outside-top' 
+| 'outside-bottom' 
+| 'outside-left' 
+| 'outside-right'`}
+    defaultValue="'outside-bottom'"
+  />
+  <PropsTableRow name="align" type="'start' | 'center' | 'end'" defaultValue="'start'" />
+  <PropsTableRow
+    name="overlayProps"
+    type={
+      <>
+        Partial&lt;<Link href="/Overlay#props">OverlayProps</Link>&gt;
+      </>
+    }
+    description={
+      <>
+        Props to be spread on the internal <InlineCode>Overlay</InlineCode> component.
+      </>
+    }
+  />
+  <PropsTableRow
+    name="focusTrapSettings"
+    type={
+      <>
+        Partial&lt;<Link href="/focusTrap#focustraphooksettings-interface">FocusTrapHookSettings</Link>&gt;
+      </>
+    }
+    description={
+      <>
+        Settings to apply to the focus trap on the internal <InlineCode>Overlay</InlineCode> component.
+      </>
+    }
+  />
+  <PropsTableRow
+    name="focusZoneSettings"
+    type={
+      <>
+        Partial&lt;<Link href="/focusZone#focuszonehooksettings-interface">FocusZoneHookSettings</Link>&gt;
+      </>
+    }
+    description={
+      <>
+        Settings to apply to the focus zone on the internal <InlineCode>Overlay</InlineCode> component.
+      </>
+    }
+  />
+</PropsTable>
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: false,
+    usedInProduction: true,
+    usageExamplesDocumented: false,
+    hasStorybookStories: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/Avatar.mdx

@@ -5,17 +5,19 @@ componentId: avatar
 source: https://github.com/primer/react/blob/main/src/Avatar.tsx
 ---
 
-import {Avatar} from '@primer/components'
+import {Avatar, Box} from '@primer/components'
 
-```jsx live
-<Avatar src="https://avatars.githubusercontent.com/primer" />
+```js
+import {Avatar} from '@primer/components'
 ```
 
-## Props
+## Examples
 
-<Props of={Avatar} />
+### Default
 
-## Examples
+```jsx live
+<Avatar src="https://avatars.githubusercontent.com/primer" />
+```
 
 ### Square
 
@@ -23,16 +25,29 @@ import {Avatar} from '@primer/components'
 <Avatar square src="https://avatars.githubusercontent.com/primer" />
 ```
 
-### AvatarPair
+## Props
 
-```jsx live
-<AvatarPair>
-  <Avatar src="https://avatars.githubusercontent.com/github" />
-  <Avatar src="https://avatars.githubusercontent.com/primer" />
-</AvatarPair>
-```
+### Avatar
+
+<PropsTable>
+  <PropsTableRow name="src" type="string" required description="URL of the avatar image." />{' '}
+  <PropsTableRow
+    name="alt"
+    type="string"
+    defaultValue="''"
+    description="Provide alt text when the avatar is used without a name next to it."
+  />
+  <PropsTableRow name="size" type="number" defaultValue="20" description="The size of the avatar in pixels." />
+  <PropsTableRow
+    name="square"
+    type="boolean"
+    defaultValue="false"
+    description="If true, the avatar will be square instead of circular."
+  />
+  <PropsTableSxRow />
+</PropsTable>
 
-## Component status
+## Status
 
 <ComponentChecklist
   items={{

package/docs/content/AvatarPair.mdx

@@ -0,0 +1,47 @@
+---
+title: AvatarPair
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/AvatarPair.tsx
+---
+
+```js
+import {AvatarPair} from '@primer/components'
+```
+
+## Examples
+
+```jsx live
+<AvatarPair>
+  <Avatar src="https://avatars.githubusercontent.com/github" />
+  <Avatar src="https://avatars.githubusercontent.com/primer" />
+</AvatarPair>
+```
+
+## Props
+
+### AvatarPair
+
+<PropsTable>
+  <PropsTableRow name="children" type="Avatar[]" />
+  <PropsTableSxRow />
+</PropsTable>
+
+## 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: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/AvatarStack.mdx

@@ -7,7 +7,13 @@ source: https://github.com/primer/react/blob/main/src/AvatarStack.tsx
 
 import {AvatarStack} from '@primer/components'
 
-### Default example
+```js
+import {AvatarStack} from '@primer/components'
+```
+
+## Examples
+
+### Default
 
 ```jsx live
 <AvatarStack>
@@ -31,12 +37,14 @@ import {AvatarStack} from '@primer/components'
 
 ## Props
 
-| Name       | Type              | Default | Description                          |
-| :--------- | :---------------- | :-----: | :----------------------------------- |
-| alignRight | Boolean           |         | Creates right aligned AvatarStack    |
-| sx         | SystemStyleObject |   {}    | Style to be applied to the component |
+### AvatarStack
+
+<PropsTable>
+  <PropsTableRow name="alignRight" type="boolean" defaultValue="false" description="Align the avatars to the right" />
+  <PropsTableSxRow />
+</PropsTable>
 
-## Component status
+## Status
 
 <ComponentChecklist
   items={{

package/docs/content/Box.mdx

@@ -9,18 +9,10 @@ import {Props} from '../src/props'
 import {ComponentChecklist} from '../src/component-checklist'
 import {Box} from '@primer/components'
 
-```jsx live
-<Box color="fg.muted" bg="canvas.subtle" p={3}>
-  Hello
-</Box>
+```js
+import {Box} from '@primer/components'
 ```
 
-## Props
-
-<Props of={Box} />
-
-Box also accepts all [styled system props](https://styled-system.com/table/).
-
 ## Examples
 
 ### Border on all sides
@@ -75,7 +67,17 @@ Use Box to create [grid](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_
 </Box>
 ```
 
-## Component status
+## Props
+
+### Box
+
+<PropsTable>
+  <PropsTableBasePropRows elementType="div" isPolymorphic refType="HTMLDivElement" />
+</PropsTable>
+
+Box also accepts all [styled system props](https://styled-system.com/table/).
+
+## Status
 
 <ComponentChecklist
   items={{

package/docs/content/BranchName.mdx

@@ -0,0 +1,52 @@
+---
+title: BranchName
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/BranchName.tsx
+---
+
+```js
+import {BranchName} from '@primer/components'
+```
+
+BranchName is a label-type component rendered as an `<a>` tag by default with monospace font.
+
+## Examples
+
+```jsx live
+<BranchName href="#">a_new_feature_branch</BranchName>
+```
+
+## Props
+
+### BranchName
+
+<PropsTable>
+  <PropsTableBasePropRows
+    elementType="a"
+    refType="HTMLAnchorElement"
+    isPolymorphic
+    passthroughPropsLink={
+      <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes">MDN</Link>
+    }
+  />
+</PropsTable>
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: false,
+    fullTestCoverage: false,
+    usedInProduction: false,
+    usageExamplesDocumented: false,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/{Breadcrumbs.md → Breadcrumbs.mdx}

@@ -5,6 +5,10 @@ description: Use breadcrumbs to show navigational context on pages that are many
 source: https://github.com/primer/react/blob/main/src/Breadcrumbs.tsx
 ---
 
+```js
+import {Breadcrumbs} from '@primer/components'
+```
+
 Breadcrumbs are used to show taxonomical 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. Breadcrumbs are most appropriate on pages that:
 
 - Are many levels deep on a site
@@ -16,7 +20,7 @@ To use Breadcrumbs with [react-router](https://github.com/ReactTraining/react-ro
 `as={NavLink}` and omit the `selected` prop.
 This ensures that the NavLink gets `activeClassName='selected'`
 
-## Default example
+## Examples
 
 ```jsx live
 <Breadcrumbs>
@@ -32,22 +36,26 @@ This ensures that the NavLink gets `activeClassName='selected'`
 
 ### Breadcrumbs
 
-| Prop name | Type              | Default | Description                          |
-| :-------- | :---------------- | :-----: | :----------------------------------- |
-| children  | ReactNode         |         | The `Breadcrumbs.Item`s              |
-| className | string            |         |                                      |
-| sx        | SystemStyleObject |  `{}`   | Style to be applied to the component |
+<PropsTable>
+  <PropsTableRow name="children" type="Breadcrumbs.Item[]" />
+  <PropsTableSxRow />
+</PropsTable>
 
 ### Breadcrumbs.Item
 
-| Prop name | Type              | Default | Description                                      |
-| :-------- | :---------------- | :-----: | :----------------------------------------------- |
-| as        | string            |   `a`   | Sets the HTML tag for the component              |
-| 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             |
+<PropsTable>
+  <PropsTableRow name="selected" type="boolean" defaultValue="false" />
+  <PropsTableBasePropRows
+    elementType="a"
+    refType="HTMLAnchorElement"
+    isPolymorphic
+    passthroughPropsLink={
+      <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes">MDN</Link>
+    }
+  />
+</PropsTable>
 
-## Component status
+## Status
 
 <ComponentChecklist
   items={{

package/docs/content/Link.mdx

@@ -0,0 +1,75 @@
+---
+title: Link
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/Link.tsx
+---
+
+import InlineCode from '@primer/gatsby-theme-doctocat/src/components/inline-code'
+import {Link} from '@primer/components'
+
+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.
+
+In special cases where you'd like a `<button>` styled like a `Link`, use `<Link as='button'>`. Make sure to provide a click handler with `onClick`.
+
+**Important:** When using the `as` prop, be sure to always render an accessible element type, like `a`, `button`, `input`, or `summary`.
+
+## Examples
+
+```jsx live
+<Link href="https://github.com">Link</Link>
+```
+
+## Props
+
+### Link
+
+<PropsTable>
+  <PropsTableRow
+    name="href"
+    type="string"
+    description={
+      <>
+        URL to be used for the Link. (The <InlineCode>href</InlineCode> is passed to the underlying{' '}
+        <InlineCode>&lt;a&gt;</InlineCode> element. If <InlineCode>as</InlineCode> is specified, the link behavior may
+        need different props).
+      </>
+    }
+  />
+  <PropsTableRow
+    name="muted"
+    type="boolean"
+    defaultValue="false"
+    description="Uses a less prominent shade for Link color, and the default link shade on hover"
+  />
+  <PropsTableRow name="underline" type="boolean" defaultValue="false" description="Adds underline to the Link" />
+  <PropsTableRow name="hoverColor" type="string" description="Color used when hovering over link" />
+  <PropsTableBasePropRows
+    elementType="a"
+    refType="HTMLAnchorElement"
+    passthroughPropsLink={
+      <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes">MDN</Link>
+    }
+    isPolymorphic
+  />
+</PropsTable>
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: false,
+    usedInProduction: true,
+    usageExamplesDocumented: false,
+    hasStorybookStories: false,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/Radio.md

@@ -0,0 +1,90 @@
+---
+title: Radio
+description: Use radios when a user needs to select one option from a list
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/Radio.tsx
+storybook: '/react/storybook?path=/story/forms-radio-button--default'
+---
+
+## Default example
+
+```jsx live
+<>
+  <Radio value="one" name="radio-group-name" />
+  <Radio value="two" name="radio-group-name" />
+  <Radio disabled value="three" name="radio-group-name" />
+</>
+```
+
+<Note>
+Please use a [Checkbox](/Checkbox) if the user needs to select more than one option in a list
+</Note>
+<Note variant="warning">
+Radio components should always be accompanied by a corresponding label to improve support for assistive technologies.
+</Note>
+
+## Grouping Radio components
+
+Use the `name` prop to group together related `Radio` components in a list.
+
+```jsx live
+<form>
+  <Box sx={{p: 1, display: 'flex', alignItems: 'center'}}>
+    <Radio id="radio-0" value="1" name="radio-example" />
+    <Text as="label" htmlFor="radio-0" sx={{fontSize: 1, marginLeft: 1}}>
+      <Text sx={{display: 'block'}}>Radio 1</Text>
+    </Text>
+  </Box>
+  <Box sx={{p: 1, display: 'flex', alignItems: 'center'}}>
+    <Radio id="radio-1" value="2" name="radio-example" />
+    <Text as="label" htmlFor="radio-1" sx={{fontSize: 1, marginLeft: 1}}>
+      <Text sx={{display: 'block'}}>Radio 2</Text>
+    </Text>
+  </Box>
+  <Box sx={{p: 1, display: 'flex', alignItems: 'center'}}>
+    <Radio id="radio-2" value="3" name="radio-example" />
+    <Text as="label" htmlFor="radio-2" sx={{fontSize: 1, marginLeft: 1}}>
+      <Text sx={{display: 'block'}}>Radio 3</Text>
+    </Text>
+  </Box>
+  <Box sx={{p: 1, display: 'flex', alignItems: 'center'}}>
+    <Radio id="radio-3" value="4" name="radio-example" />
+    <Text as="label" htmlFor="radio-3" sx={{fontSize: 1, marginLeft: 1}}>
+      <Text sx={{display: 'block'}}>Radio 4</Text>
+    </Text>
+  </Box>
+</form>
+```
+
+## Component props
+
+Native `<input>` attributes are forwarded to the underlying React `input` component and are not listed below.
+
+| Name           | Type        |  Default  | Description                                                                              |
+| :------------- | :---------- | :-------: | :--------------------------------------------------------------------------------------- |
+| value          | String      | undefined | Required. A unique value that is never shown to the user.                                |
+| name           | String      | undefined | Required. Used for grouping multiple radios                                              |
+| checked        | Boolean     | undefined | Optional. Modifies true/false value of the native radio                                  |
+| defaultChecked | Boolean     | undefined | Optional. Selects the radio 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 radio                         |
+
+## 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
+  }}
+/>