Skip to content

Commit 2c42c38

Browse files
colebemiscolebemis
authored
Update component docs (AnchoredOverlay, Avatar, AvatarStack, Box, BranchName, 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
1 parent 852f5e1 commit 2c42c38

File tree

14 files changed

+316
-88
lines changed

14 files changed

+316
-88
lines changed

‎.changeset/polite-trees-wink.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@primer/components": patch
3+
---
4+
5+
Update `BranchName` styles to match github.com

‎docs/content/AnchoredOverlay.mdx‎

Lines changed: 121 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
---
22
title: AnchoredOverlay
33
status: Alpha
4+
source: https://github.com/primer/react/blob/main/src/AnchoredOverlay/AnchoredOverlay.tsx
5+
storybook: https://primer.style/react/storybook?path=/story/generic-behaviors-anchoredoverlay--default-portal
46
---
57

68
An `AnchoredOverlay` provides an anchor that will open a floating overlay positioned relative to the anchor.
79
The overlay can be opened and navigated using keyboard or mouse.
810

911
See also [Overlay positioning](/Overlay#positioning).
1012

11-
## Example
13+
## Examples
1214

1315
```jsx live
1416
<State default={false}>
@@ -35,3 +37,121 @@ See also [Overlay positioning](/Overlay#positioning).
3537
}}
3638
</State>
3739
```
40+
41+
## Props
42+
43+
<PropsTable>
44+
<PropsTableRow
45+
name="open"
46+
type="boolean"
47+
defaultValue="false"
48+
description="Determines whether the overlay portion of the component should be shown or not."
49+
/>
50+
<PropsTableRow
51+
name="onOpen"
52+
type="(gesture: 'anchor-click' | 'anchor-key-press') => unknown"
53+
description='A callback that is called whenever the overlay is currently closed and an "open gesture" is detected.'
54+
/>
55+
<PropsTableRow
56+
name="onClose"
57+
type="(gesture: 'anchor-click' | 'click-outside' | 'escape') => unknown"
58+
description='A callback that is called whenever the overlay is currently open and a "close gesture" is detected.'
59+
/>
60+
<PropsTableRow
61+
name="renderAnchor"
62+
type="<T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element"
63+
description={
64+
<>
65+
A custom function component used to render the anchor element. When renderAnchor is null, an anchorRef is
66+
required.
67+
</>
68+
}
69+
/>
70+
<PropsTableRow
71+
name="anchorRef"
72+
type="React.RefObject<HTMLElement>"
73+
description={
74+
<>
75+
An override to the internal <InlineCode>renderAnchor</InlineCode> ref that will be used to position the overlay.
76+
When <InlineCode>renderAnchor</InlineCode> is
77+
<InlineCode>null</InlineCode>, this can be used to make an anchor that is detached from <InlineCode>
78+
AnchoredOverlay
79+
</InlineCode>.
80+
</>
81+
}
82+
/>
83+
<PropsTableRow
84+
name="side"
85+
type={`| 'inside-top'
86+
| 'inside-bottom'
87+
| 'inside-left'
88+
| 'inside-right'
89+
| 'inside-center'
90+
| 'outside-top'
91+
| 'outside-bottom'
92+
| 'outside-left'
93+
| 'outside-right'`}
94+
defaultValue="'outside-bottom'"
95+
/>
96+
<PropsTableRow name="align" type="'start' | 'center' | 'end'" defaultValue="'start'" />
97+
<PropsTableRow
98+
name="overlayProps"
99+
type={
100+
<>
101+
Partial&lt;<Link href="/Overlay#props">OverlayProps</Link>&gt;
102+
</>
103+
}
104+
description={
105+
<>
106+
Props to be spread on the internal <InlineCode>Overlay</InlineCode> component.
107+
</>
108+
}
109+
/>
110+
<PropsTableRow
111+
name="focusTrapSettings"
112+
type={
113+
<>
114+
Partial&lt;<Link href="/focusTrap#focustraphooksettings-interface">FocusTrapHookSettings</Link>&gt;
115+
</>
116+
}
117+
description={
118+
<>
119+
Settings to apply to the focus trap on the internal <InlineCode>Overlay</InlineCode> component.
120+
</>
121+
}
122+
/>
123+
<PropsTableRow
124+
name="focusZoneSettings"
125+
type={
126+
<>
127+
Partial&lt;<Link href="/focusZone#focuszonehooksettings-interface">FocusZoneHookSettings</Link>&gt;
128+
</>
129+
}
130+
description={
131+
<>
132+
Settings to apply to the focus zone on the internal <InlineCode>Overlay</InlineCode> component.
133+
</>
134+
}
135+
/>
136+
</PropsTable>
137+
138+
## Status
139+
140+
<ComponentChecklist
141+
items={{
142+
propsDocumented: true,
143+
noUnnecessaryDeps: true,
144+
adaptsToThemes: true,
145+
adaptsToScreenSizes: true,
146+
fullTestCoverage: false,
147+
usedInProduction: true,
148+
usageExamplesDocumented: false,
149+
hasStorybookStories: true,
150+
designReviewed: false,
151+
a11yReviewed: false,
152+
stableApi: false,
153+
addressedApiFeedback: false,
154+
hasDesignGuidelines: false,
155+
hasFigmaComponent: false
156+
}}
157+
/>

‎docs/content/Avatar.mdx‎

Lines changed: 29 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,34 +5,49 @@ componentId: avatar
55
source: https://github.com/primer/react/blob/main/src/Avatar.tsx
66
---
77

8-
import {Avatar} from '@primer/components'
8+
import {Avatar, Box} from '@primer/components'
99

10-
```jsx live
11-
<Avatar src="https://avatars.githubusercontent.com/primer" />
10+
```js
11+
import {Avatar} from '@primer/components'
1212
```
1313

14-
## Props
14+
## Examples
1515

16-
<Props of={Avatar} />
16+
### Default
1717

18-
## Examples
18+
```jsx live
19+
<Avatar src="https://avatars.githubusercontent.com/primer" />
20+
```
1921

2022
### Square
2123

2224
```jsx live
2325
<Avatar square src="https://avatars.githubusercontent.com/primer" />
2426
```
2527

26-
### AvatarPair
28+
## Props
2729

28-
```jsx live
29-
<AvatarPair>
30-
<Avatar src="https://avatars.githubusercontent.com/github" />
31-
<Avatar src="https://avatars.githubusercontent.com/primer" />
32-
</AvatarPair>
33-
```
30+
### Avatar
31+
32+
<PropsTable>
33+
<PropsTableRow name="src" type="string" required description="URL of the avatar image." />{' '}
34+
<PropsTableRow
35+
name="alt"
36+
type="string"
37+
defaultValue="''"
38+
description="Provide alt text when the avatar is used without a name next to it."
39+
/>
40+
<PropsTableRow name="size" type="number" defaultValue="20" description="The size of the avatar in pixels." />
41+
<PropsTableRow
42+
name="square"
43+
type="boolean"
44+
defaultValue="false"
45+
description="If true, the avatar will be square instead of circular."
46+
/>
47+
<PropsTableSxRow />
48+
</PropsTable>
3449

35-
## Component status
50+
## Status
3651

3752
<ComponentChecklist
3853
items={{

‎docs/content/AvatarPair.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: AvatarPair
3+
status: Alpha
4+
source: https://github.com/primer/react/blob/main/src/AvatarPair.tsx
5+
---
6+
7+
```js
8+
import {AvatarPair} from '@primer/components'
9+
```
10+
11+
## Examples
12+
13+
```jsx live
14+
<AvatarPair>
15+
<Avatar src="https://avatars.githubusercontent.com/github" />
16+
<Avatar src="https://avatars.githubusercontent.com/primer" />
17+
</AvatarPair>
18+
```
19+
20+
## Props
21+
22+
### AvatarPair
23+
24+
<PropsTable>
25+
<PropsTableRow name="children" type="Avatar[]" />
26+
<PropsTableSxRow />
27+
</PropsTable>
28+
29+
## Status
30+
31+
<ComponentChecklist
32+
items={{
33+
propsDocumented: true,
34+
noUnnecessaryDeps: true,
35+
adaptsToThemes: true,
36+
adaptsToScreenSizes: true,
37+
fullTestCoverage: false,
38+
usedInProduction: false,
39+
usageExamplesDocumented: true,
40+
designReviewed: false,
41+
a11yReviewed: false,
42+
stableApi: false,
43+
addressedApiFeedback: false,
44+
hasDesignGuidelines: false,
45+
hasFigmaComponent: false
46+
}}
47+
/>

‎docs/content/AvatarStack.mdx‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,13 @@ source: https://github.com/primer/react/blob/main/src/AvatarStack.tsx
77

88
import {AvatarStack} from '@primer/components'
99

10-
### Default example
10+
```js
11+
import {AvatarStack} from '@primer/components'
12+
```
13+
14+
## Examples
15+
16+
### Default
1117

1218
```jsx live
1319
<AvatarStack>
@@ -31,12 +37,14 @@ import {AvatarStack} from '@primer/components'
3137

3238
## Props
3339

34-
| Name | Type | Default | Description |
35-
| :--------- | :---------------- | :-----: | :----------------------------------- |
36-
| alignRight | Boolean | | Creates right aligned AvatarStack |
37-
| sx | SystemStyleObject | {} | Style to be applied to the component |
40+
### AvatarStack
41+
42+
<PropsTable>
43+
<PropsTableRow name="alignRight" type="boolean" defaultValue="false" description="Align the avatars to the right" />
44+
<PropsTableSxRow />
45+
</PropsTable>
3846

39-
## Component status
47+
## Status
4048

4149
<ComponentChecklist
4250
items={{

‎docs/content/Box.mdx‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,10 @@ import {Props} from '../src/props'
99
import {ComponentChecklist} from '../src/component-checklist'
1010
import {Box} from '@primer/components'
1111

12-
```jsx live
13-
<Box color="fg.muted" bg="canvas.subtle" p={3}>
14-
Hello
15-
</Box>
12+
```js
13+
import {Box} from '@primer/components'
1614
```
1715

18-
## Props
19-
20-
<Props of={Box} />
21-
22-
Box also accepts all [styled system props](https://styled-system.com/table/).
23-
2416
## Examples
2517

2618
### Border on all sides
@@ -75,7 +67,17 @@ Use Box to create [grid](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_
7567
</Box>
7668
```
7769

78-
## Component status
70+
## Props
71+
72+
### Box
73+
74+
<PropsTable>
75+
<PropsTableBasePropRows elementType="div" isPolymorphic refType="HTMLDivElement" />
76+
</PropsTable>
77+
78+
Box also accepts all [styled system props](https://styled-system.com/table/).
79+
80+
## Status
7981

8082
<ComponentChecklist
8183
items={{

‎docs/content/BranchName.md‎

Lines changed: 0 additions & 39 deletions
This file was deleted.

0 commit comments

Comments
 (0)