-
Notifications
You must be signed in to change notification settings - Fork 526
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update component docs (AnchoredOverlay, Avatar, AvatarStack, Box, BranchName, Breadcrumbs) #1702
Changes from all commits
edab87b
141207b
5ec41e7
0609dcf
142d399
2787767
d678c67
d4ceb46
2c657bf
4624ebe
987ef5b
94b8ffe
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
"@primer/components": patch | ||
--- | ||
|
||
Update `BranchName` styles to match github.com |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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<<Link href="/Overlay#props">OverlayProps</Link>> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ✨ |
||
</> | ||
} | ||
description={ | ||
<> | ||
Props to be spread on the internal <InlineCode>Overlay</InlineCode> component. | ||
</> | ||
} | ||
/> | ||
<PropsTableRow | ||
name="focusTrapSettings" | ||
type={ | ||
<> | ||
Partial<<Link href="/focusTrap#focustraphooksettings-interface">FocusTrapHookSettings</Link>> | ||
</> | ||
} | ||
description={ | ||
<> | ||
Settings to apply to the focus trap on the internal <InlineCode>Overlay</InlineCode> component. | ||
</> | ||
} | ||
/> | ||
<PropsTableRow | ||
name="focusZoneSettings" | ||
type={ | ||
<> | ||
Partial<<Link href="/focusZone#focuszonehooksettings-interface">FocusZoneHookSettings</Link>> | ||
</> | ||
} | ||
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 | ||
}} | ||
/> |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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="''" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ❗ I'm surprised this is There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think this is intentional.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. TIL, thanks! |
||
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={{ | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
}} | ||
/> |
This file was deleted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This wording is tricky — unlike most ref props, there's an expectation that the
AnchoredOverlay
isn't responsible for setting the value of the ref, right? only that it will use the ref's current value for positioning logic?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, this one is tricky. I mostly copied this description from the code comments but I agree that it's a bit confusing.