Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Adds draft SegmentedControl docs #2081

Merged
merged 14 commits into from
May 26, 2022
Merged

Adds draft SegmentedControl docs #2081

Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
c906d65
adds a draft for the SegmentedControl component docs
mperrotti May 18, 2022
5f85457
Merge branch 'main' into mp/segmented-control-docs-draft
mperrotti May 19, 2022
b8421bd
addresses first round of PR feedback
mperrotti May 19, 2022
bda37f3
Merge branch 'main' of github.com:primer/react into mp/segmented-cont…
mperrotti May 19, 2022
b53ad39
Merge branch 'mp/segmented-control-docs-draft' of github.com:primer/r…
mperrotti May 19, 2022
2947400
Merge branch 'main' into mp/segmented-control-docs-draft
mperrotti May 20, 2022
ffae4ae
Merge branch 'main' into mp/segmented-control-docs-draft
mperrotti May 23, 2022
c754dfd
changes 'block' prop name to 'fullWidth
mperrotti May 23, 2022
6edd979
Update docs/content/SegmentedControl.mdx
mperrotti May 24, 2022
266bce9
Update docs/content/SegmentedControl.mdx
mperrotti May 24, 2022
07d1382
Update docs/content/SegmentedControl.mdx
mperrotti May 24, 2022
0272ead
addresses remainder of PR feedback
mperrotti May 25, 2022
b0b7848
Merge branch 'main' into mp/segmented-control-docs-draft
mperrotti May 25, 2022
33a9474
Merge branch 'main' into mp/segmented-control-docs-draft
mperrotti May 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 213 additions & 0 deletions docs/content/SegmentedControl.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,213 @@
---
title: SegmentedControl
status: Draft
description: Use a segmented control to let users select an option from a short list and immediately apply the selection
---
mperrotti marked this conversation as resolved.
Show resolved Hide resolved

<Note variant="warning">Not implemented yet</Note>

## Examples

### Simple

```jsx live drafts
<SegmentedControl aria-label="File view">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would you indicate which Button is selected?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By passing selected to the SegmentedControl.Button

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it'll be common for consumers to explicitly set the selected prop, could we show that in the examples? Similar to how aria-current is set in most of the NavList examples: https://primer-d954104e87-13348165.drafts.github.io/NavList

<SegmentedControl.Button selected>Preview</SegmentedControl.Button>
<SegmentedControl.Button>Raw</SegmentedControl.Button>
<SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>
```

### With icons and labels

```jsx live drafts
<SegmentedControl aria-label="File view">
<SegmentedControl.Button selected leadingIcon={EyeIcon}>
Preview
</SegmentedControl.Button>
<SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
<SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>
```

### With icons only

```jsx live drafts
<SegmentedControl aria-label="File view">
<SegmentedControl.IconButton selected icon={EyeIcon} aria-label="Preview" />
<SegmentedControl.IconButton icon={FileCodeIcon} aria-label="Raw" />
<SegmentedControl.IconButton icon={PeopleIcon} aria-label="Blame" />
</SegmentedControl>
```

### With labels hidden on smaller viewports

```jsx live drafts
<SegmentedControl aria-label="File view" variant={{narrow: 'hideLabels', regular: 'none'}}>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't look like the variant is documented in the Props section

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. Will add...

<SegmentedControl.Button selected leadingIcon={EyeIcon}>
Preview
</SegmentedControl.Button>
<SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
<SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>
```

### Convert to a dropdown on smaller viewports

```jsx live drafts
<SegmentedControl aria-label="File view" variant={{narrow: 'dropdown', regular: 'none'}}>
<SegmentedControl.Button selected leadingIcon={EyeIcon}>
Preview
</SegmentedControl.Button>
<SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
<SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>
```

### Fill width of parent

```jsx live drafts
<SegmentedControl fullWidth aria-label="File view">
<SegmentedControl.Button selected>Preview</SegmentedControl.Button>
<SegmentedControl.Button>Raw</SegmentedControl.Button>
<SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>
```

### In a loading state

```jsx live drafts
<SegmentedControl loading aria-label="File view">
<SegmentedControl.Button selected>Preview</SegmentedControl.Button>
<SegmentedControl.Button>Raw</SegmentedControl.Button>
<SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>
```

### With a label and caption on the left

```jsx live drafts
<Box display="flex">
<Box flexGrow={1}>
<Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
File view
</Text>
<Text color="fg.subtle" fontSize={1} id="scCaption-vert" display="block">
Change the way the file is viewed
</Text>
</Box>
<SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
<SegmentedControl.Button selected>Preview</SegmentedControl.Button>
<SegmentedControl.Button>Raw</SegmentedControl.Button>
<SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>
</Box>
```

### With a label above and caption below

```jsx live drafts
<FormControl>
<FormControl.Label id="scLabel-horiz">File view</FormControl.Label>
<SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
<SegmentedControl.Button selected>Preview</SegmentedControl.Button>
<SegmentedControl.Button>Raw</SegmentedControl.Button>
<SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>
<FormControl.Caption id="scCaption-horiz">Change the way the file is viewed</FormControl.Caption>
</FormControl>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooh that's interesting! Is this in the context of a Form or otherwise as well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Otherwise as well. This component is not a substitute for RadioGroup.

Copy link
Member

@siddharthkp siddharthkp May 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

The name threw me off a bit 😅

```

### With something besides the first option selected

```jsx live drafts
<SegmentedControl aria-label="File view">
<SegmentedControl.Button selected>Preview</SegmentedControl.Button>
<SegmentedControl.Button selected>Raw</SegmentedControl.Button>
<SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>
```

### With a selection change handler

```jsx live drafts
<SegmentedControl
aria-label="File view"
onChange={selectedIndex => {
alert(`Segment ${selectedIndex}`)
}}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because the items are buttons, adding an onClick would also automatically work. Do we want to support both onClick on item and onChange on parent?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the onChange on the parent so that we don't have to add repetitive onClick handlers to each SegmentedControl.Button

>
<SegmentedControl.Button>Preview</SegmentedControl.Button>
<SegmentedControl.Button>Raw</SegmentedControl.Button>
<SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>
```

## Props

### SegmentedControl

<PropsTable>
<PropsTableRow name="aria-label" type="string" />
<PropsTableRow name="aria-labelledby" type="string" />
<PropsTableRow name="aria-describedby" type="string" />
<PropsTableRow name="fullWidth" type="boolean" description="Whether the control fills the width of its parent" />
<PropsTableRow name="loading" type="boolean" description="Whether the selected segment is being calculated" />
<PropsTableRow
name="onChange"
type="(selectedIndex?: number) => void"
description="The handler that gets called when a segment is selected"
/>
<PropsTableRow
name="variant"
type="{
narrow?: 'hideLabels' | 'dropdown',
regular?: 'hideLabels' | 'dropdown',
wide?: 'hideLabels' | 'dropdown'
}"
description="Configure alternative ways to render the control when it gets rendered in tight spaces"
/>
<PropsTableSxRow />
<PropsTableRefRow refType="HTMLDivElement" />
</PropsTable>

### SegmentedControl.Button

<PropsTable>
<PropsTableRow name="aria-label" type="string" />
<PropsTableRow name="leadingIcon" type="Component" description="The leading icon comes before item label" />
<PropsTableRow name="selected" type="boolean" description="Whether the segment is selected" />
<PropsTableSxRow />
<PropsTableRefRow refType="HTMLButtonElement" />
</PropsTable>

### SegmentedControl.IconButton

<PropsTable>
<PropsTableRow name="aria-label" type="string" />
<PropsTableRow name="icon" type="Component" description="The icon that represents the segmented control item" />
<PropsTableRow name="selected" type="boolean" description="Whether the segment is selected" />
<PropsTableSxRow />
<PropsTableRefRow refType="HTMLButtonElement" />
</PropsTable>

## Status

<ComponentChecklist
items={{
propsDocumented: true,
noUnnecessaryDeps: false,
adaptsToThemes: false,
adaptsToScreenSizes: false,
fullTestCoverage: false,
usedInProduction: false,
usageExamplesDocumented: false,
hasStorybookStories: false,
designReviewed: false,
a11yReviewed: false,
stableApi: false,
addressedApiFeedback: false,
hasDesignGuidelines: false,
hasFigmaComponent: false
}}
/>