Update component docs (AnchoredOverlay, Avatar, AvatarStack, Box, Bra…

…nchName, Breadcrumbs) (#1702) * Update AnchoredOverlay docs * Allow preformatted types in prop table * Add Link and InlineCode to global mdx scope * Update Avatar docs * Update AvatarStack docs * Update Box props * Update branchname docs * Update breadcrumbs docs * Update branchname snapshot * Create polite-trees-wink.md * Add AvatarPair docs
primer · Dec 19, 2021 · 2902124 · 2902124
1 parent 34f190c
commit 2902124
Show file tree

Hide file tree

Showing 14 changed files with 316 additions and 88 deletions.
diff --git a/.changeset/polite-trees-wink.md b/.changeset/polite-trees-wink.md
@@ -0,0 +1,5 @@
+---
+"@primer/components": patch
+---
+
+Update `BranchName` styles to match github.com
diff --git a/docs/content/AnchoredOverlay.mdx b/docs/content/AnchoredOverlay.mdx
@@ -1,14 +1,16 @@
 ---
 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.
 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
+  }}
+/>
diff --git a/docs/content/Avatar.mdx b/docs/content/Avatar.mdx
@@ -5,34 +5,49 @@ 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
 
 ```jsx live
 <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={{

diff --git a/docs/content/AvatarPair.mdx b/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
+  }}
+/>
diff --git a/docs/content/AvatarStack.mdx b/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={{

diff --git a/docs/content/Box.mdx b/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={{

diff --git a/docs/content/BranchName.md b/docs/content/BranchName.md