@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/docs/content/SelectMenu.md

@@ -0,0 +1,433 @@
+---
+title: SelectMenu
+---
+
+The `SelectMenu` components are a suite of components which can be combined together to make several different variations of our GitHub select menu. At it's most basic form, a select menu is comprised of a `SelectMenu` wrapper, which contains a `summary` component of your choice and a `Select.Modal` which contains the select menu content. Use `SelectMenu.List` to wrap items in the select menu, and `SelectMenu.Item` to wrap each item.
+
+Several additional components exist to provide even more functionality: `SelectMenu.Header`, `SelectMenu.Filter`, `SelectMenu.Tabs`, `SelectMenu.TabPanel` `SelectMenu.Footer` and `SelectMenu.Divider`.
+
+## Basic Example
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+## SelectMenu
+
+Main wrapper component for select menu.
+
+```jsx
+<SelectMenu>{/* all other sub components are wrapped here*/}</SelectMenu>
+```
+
+### Component Props
+
+| Name       | Type      | Default | Description                                                                                                                              |
+| :--------- | :-------- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| initialTab | String    |         | If using the `SelectMenu.Tabs` component, you can use this prop to change the tab shown on open. By default, the first tab will be used. |
+| ref        | React ref |         | ref to pass down to SelectMenu component                                                                                                 |
+
+## SelectMenu.MenuContext
+
+SelectMenu.MenuContext is a [context object](https://reactjs.org/docs/context.html#reactcreatecontext) that exposes some helpful state values to be used via [`React.useContext`](https://reactjs.org/docs/hooks-reference.html#usecontext) in consuming applications. SelectMenu.MenuContext can only be used in components that are already wrapped in a `SelectMenu` as `SelectMenu` contains the [context provider](https://reactjs.org/docs/context.html#contextprovider).
+
+### Values available on MenuContext
+
+| Name           | Type     | Description                                                                                                                                     |
+| :------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
+| selectedTab    | string   | The currently selected tab                                                                                                                      |
+| setSelectedTab | function | Used to update the currently selected tab state                                                                                                 |
+| open           | boolean  | State for open/closed status of the menu modal                                                                                                  |
+| setOpen        | function | Used to update the `open` state                                                                                                                 |
+| initialTab     | string   | Mostly used internally to pass down which tab should be set to open by default. To change this value use the `initialTab` prop on `SelectMenu`. |
+
+### Example Usage
+
+```jsx
+import {SelectMenu, Button} from `@primer/components`
+import React, {useContext} from 'react'
+
+const MyMenu = () => {
+  <SelectMenu>
+    <MyButton />
+    <SelectMenu.Modal>
+      content
+    </SelectMenu.Modal>
+  </SelectMenu>
+}
+
+// note that we can only use the context in components that are already wrapped by SelectMenu (and thus the Context.Provider)
+const MyButton = () => {
+  const menuContext = useContext(SelectMenu.MenuContext);
+
+  return (
+    <Button as="summary">{menuContext.open ? 'Open' : 'Closed'}</Button>
+  )
+}
+```
+
+## SelectMenu.Modal
+
+Used to wrap the content in a `SelectMenu`.
+
+```jsx
+<SelectMenu.Modal>
+  {/* all menu content is wrapped in the modal*/}
+</SelectMenu.Menu>
+```
+
+### Right-aligned modal
+
+Use the `align='right'` prop to align the modal to the right. Note that this only modifies alignment for the modal, and not the SelectMenu itself. You will need to wrap the SelectMenu in a relatively positioned element for this to work properly.
+
+```jsx live
+<Box position="relative" display="flex" justifyContent="flex-end">
+  <SelectMenu>
+    <Button as="summary">Projects</Button>
+    <SelectMenu.Modal align="right">
+      <SelectMenu.Header>Projects</SelectMenu.Header>
+      <SelectMenu.List>
+        <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+        <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+        <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+        <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+      </SelectMenu.List>
+    </SelectMenu.Modal>
+  </SelectMenu>
+</Box>
+```
+
+### Component Props
+
+| Prop name | Type             | Default | Description                                       |
+| :-------- | :--------------- | :------ | ------------------------------------------------- |
+| align     | String           | 'left'  | Use `right` to align the select menu to the right |
+| width     | String or Number | 300px   | Sets the modal width                              |
+
+## SelectMenu.List
+
+Used to wrap the select menu list content. All menu items **must** be wrapped in a SelectMenu.List in order for the accessbility keyboard handling to function properly. If you are using the `SelectMenu.TabPanel` you do not need to provide a `SelectMenu.List` as that component renders a `SelectMenu.List` as a wrapper.
+
+```jsx
+<SelectMenu.List>{/* all menu  list items are wrapped in the list*/}</SelectMenu.List>
+```
+
+### Component Props
+
+SelectMenu.List components do not get any additional props besides system props.
+
+## SelectMenu.Item
+
+Individual items in a select menu. SelectMenu.Item renders an anchor tag by default, you'll need to make sure to provide the appropriate `href`.
+
+You can use a `button` tag instead by utilizing the [`as` prop](/core-concepts#the-as-prop). Be sure to consider [which HTML element is the right choice](https://marcysutton.com/links-vs-buttons-in-modern-web-applications) for your usage of the component.
+
+```jsx
+<SelectMenu.Item href="/link/to/thing" selected={true}>
+  {/* wraps an individual list item*/}
+</SelectMenu.Item>
+```
+
+### System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+| Name     | Type     | Default | Description                                                                                                                                                                                    |
+| :------- | :------- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| selected | boolean  |         | Used to apply styles to the selected items in the list.                                                                                                                                        |
+| onClick  | function |         | Function called when item is clicked. By default we also close the menu when items are clicked. If you would like the menu to stay open, pass an `e.preventDefault()` to your onClick handler. |
+
+## SelectMenu.Filter
+
+Use a `SelectMenu.Filter` to add a filter UI to your select menu. Users are expected to implement their own filtering and manage the state of the `value` prop on the input. This gives users more flexibility over the type of filtering and type of content passed into each select menu item.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Filter by Project</SelectMenu.Header>
+    <SelectMenu.Filter placeholder="Filter projects" value="" aria-label="Filter Projects" />
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Divider>More Options</SelectMenu.Divider>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### System Props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu.Filter components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+SelectMenu.Filter components receive all the props that the [TextInput](/TextInput) component gets.
+
+| Name  | Type   | Default | Description                                                                                                    |
+| :---- | :----- | :-----: | :------------------------------------------------------------------------------------------------------------- |
+| value | String |         | Users of this component must provide a value for the filter input that is managed in the consuming application |
+
+## SelectMenu.Tabs
+
+Use `SelectMenu.Tabs` to wrap the the tab navigation and `SelectMenu.Tab` for each tab in the navigation.
+
+`SelectMenu.TabPanel` should wrap each corresponding panel for each of the tabs. The `tabName` prop for each `SelectMenu.TabPanel` must match the name provided in the `tabName` prop on `SelectMenu.Tab`.
+
+To set one of the tabs to be open by default, use `initialTab` on the main `SelectMenu` component. Otherwise, the first tab will be shown by default.
+
+Each `Select.Menu` tab will need to have an `index` prop. The first tab should be at index `0`, the second at index `1` and so forth. The `index` prop is used to show the first tab by default.
+
+If you need access to the selected tab state, you can find it in the MenuContext object exported from `SelectMenu` as `MenuContext.selectedTab`.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.Tabs>
+      <SelectMenu.Tab index={0} tabName="Repository" />
+      <SelectMenu.Tab index={1} tabName="Organization" />
+    </SelectMenu.Tabs>
+    <SelectMenu.TabPanel tabName="Repository">
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.TabPanel>
+    <SelectMenu.TabPanel tabName="Organization">
+      <SelectMenu.Item href="#"> Project 2</SelectMenu.Item>
+    </SelectMenu.TabPanel>
+    <SelectMenu.Footer>Showing 3 of 3</SelectMenu.Footer>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### Component Props
+
+SelectMenu.Tabs components do not get any additional props besides system props.
+
+## SelectMenu.Tab
+
+Used for each individual tab inside of a `SelectMenu.Tabs`. Be sure to set the `index` prop to correspond to the order the tab is in. The `tabName` prop should correspond to the `tabName` set on the `SelectMenu.TabPanel`.
+
+The `onClick` prop is optional and can be used for any events or data fetching you might need to trigger on tab clicks.
+
+```jsx
+<SelectMenu.Tab index={0} tabName="Repository"/>
+<SelectMenu.Tab index={1} tabName="Organization"/>
+```
+
+### System Props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu.Tab components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+| Name    | Type     | Default | Description                                                                                                                |
+| :------ | :------- | :-----: | :------------------------------------------------------------------------------------------------------------------------- |
+| tabName | String   |         | Used to identify the corresponding tab. Must match the string used in the `tabs` array in the `SelectMenu.Tabs` component. |
+| index   | Number   |         | The index at which the tab is in the list of tabs                                                                          |
+| onClick | Function |         | Function to be called when the tab is clicked. Optional.                                                                   |
+
+## SelectMenu.TabPanel
+
+Wraps the content for each tab. Make sure to use the `tabName` prop to identify each tab panel with the correct tab in the tab navigation.
+
+**Note**: SelectMenu.TabPanel wraps content in a SelectMenu.List, so adding a SelectMenu.List manually is not necessary.
+
+```jsx
+<SelectMenu.TabPanel tabName="Repository">{/* Wraps content for each tab */}</SelectMenu.TabPanel>
+```
+
+### System Props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu.TabPanel components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+| Name    | Type   | Default | Description                                                                                                                |
+| :------ | :----- | :-----: | :------------------------------------------------------------------------------------------------------------------------- |
+| tabName | String |         | Used to identify the corresponding tab. Must match the string used in the `tabs` array in the `SelectMenu.Tabs` component. |
+
+## SelectMenu.Divider
+
+Use a `SelectMenu.Divider` to add information between items in a `SelectMenu.List`.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Divider>More Options</SelectMenu.Divider>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### System Props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu.Divder components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+SelectMenu.Divider components do not get any additional props besides system props.
+
+## SelectMenu.Footer
+
+Use a `SelectMenu.Footer` to add content to the bottom of the select menu.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+      <SelectMenu.Footer>Use ⌥ + click/return to exclude labels.</SelectMenu.Footer>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### System Props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu.Footer components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+SelectMenu.Footer components do not get any additional props besides system props.
+
+## SelectMenu.Header
+
+Use a `SelectMenu.Header` to add a header to the top of the select menu content.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.List>
+      <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+      <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+      <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+      <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+      <SelectMenu.Footer>Use ⌥ + click/return to exclude labels.</SelectMenu.Footer>
+    </SelectMenu.List>
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### System Props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu.Header components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+SelectMenu.Header components do not get any additional props besides system props.
+
+## SelectMenu.LoadingAnimation
+
+Use a `SelectMenu.LoadingAnimation` to add a loading animation inside of the SelectMenu.
+
+**Note**: You will need to handle showing/hiding the appropriate modal content for your application during the loading state. We recommend always showing the `SelectMenu.Filter` and `SelectMenu.Header` (if used) and hiding the rest of the modal content during the loading state.
+
+```jsx live
+<SelectMenu>
+  <Button as="summary">Projects</Button>
+  <SelectMenu.Modal>
+    <SelectMenu.Header>Projects</SelectMenu.Header>
+    <SelectMenu.Filter placeholder="Filter projects" value="" aria-label="Filter Projects" />
+    {true ? (
+      <SelectMenu.LoadingAnimation />
+    ) : (
+      <SelectMenu.List>
+        <SelectMenu.Item href="#">Primer React bugs</SelectMenu.Item>
+        <SelectMenu.Item href="#">Primer React roadmap</SelectMenu.Item>
+        <SelectMenu.Item href="#"> Project 3</SelectMenu.Item>
+        <SelectMenu.Item href="#">Project 4</SelectMenu.Item>
+        <SelectMenu.Footer>Use ⌥ + click/return to exclude labels.</SelectMenu.Footer>
+      </SelectMenu.List>
+    )}
+  </SelectMenu.Modal>
+</SelectMenu>
+```
+
+### System Props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+SelectMenu.LoadingAnimation components get `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+### Component Props
+
+SelectMenu.LoadingAnimation components do not get any additional props besides system props.

package/docs/content/SelectPanel.mdx

@@ -0,0 +1,67 @@
+---
+title: SelectPanel
+status: Alpha
+---
+
+A `SelectPanel` provides an anchor that will open an overlay with a list of selectable items, and a text input to filter the selectable items
+
+## Example
+
+```javascript live noinline
+function getColorCircle(color) {
+  return function () {
+    return (
+      <Box
+        borderWidth="1px"
+        borderStyle="solid"
+        bg={color}
+        borderColor={color}
+        width={14}
+        height={14}
+        borderRadius={10}
+        margin="auto"
+      />
+    )
+  }
+}
+
+const items = [
+  {leadingVisual: getColorCircle('#a2eeef'), text: 'enhancement', id: 1},
+  {leadingVisual: getColorCircle('#d73a4a'), text: 'bug', id: 2},
+  {leadingVisual: getColorCircle('#0cf478'), text: 'good first issue', id: 3},
+  {leadingVisual: getColorCircle('#ffd78e'), text: 'design', id: 4},
+  {leadingVisual: getColorCircle('#ff0000'), text: 'blocker', id: 5},
+  {leadingVisual: getColorCircle('#a4f287'), text: 'backend', id: 6},
+  {leadingVisual: getColorCircle('#8dc6fc'), text: 'frontend', id: 7}
+]
+
+function DemoComponent() {
+  const [selected, setSelected] = React.useState([items[0], items[1]])
+  const [filter, setFilter] = React.useState('')
+  const filteredItems = items.filter(item => item.text.toLowerCase().startsWith(filter.toLowerCase()))
+  const [open, setOpen] = React.useState(false)
+
+  return (
+    <SelectPanel
+      renderAnchor={({children, 'aria-labelledby': ariaLabelledBy, ...anchorProps}) => (
+        <DropdownButton aria-labelledby={` ${ariaLabelledBy}`} {...anchorProps}>
+          {children || 'Select Labels'}
+        </DropdownButton>
+      )}
+      placeholderText="Filter Labels"
+      open={open}
+      onOpenChange={setOpen}
+      items={filteredItems}
+      selected={selected}
+      onSelectedChange={setSelected}
+      onFilterChange={setFilter}
+      showItemDividers={true}
+      overlayProps={{width: 'small', height: 'xsmall'}}
+    />
+  )
+}
+
+render(<DemoComponent />)
+```
+
+## Component props

package/docs/content/SideNav.md

@@ -0,0 +1,179 @@
+---
+title: SideNav
+---
+
+The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **SideNav elements have no default width or positioning.**
+
+## Default example
+
+```jsx live
+<SideNav bordered maxWidth={360} aria-label="Main">
+  <SideNav.Link href="#account">
+    <Text>Account</Text>
+  </SideNav.Link>
+  <SideNav.Link href="#home" selected>
+    <Text>Profile</Text>
+  </SideNav.Link>
+  <SideNav.Link href="#emails">
+    <Text>Emails</Text>
+  </SideNav.Link>
+  <SideNav.Link href="#notifications">
+    <Text>Notifications</Text>
+  </SideNav.Link>
+</SideNav>
+```
+
+Different kinds of content can be added inside a SideNav item. Use system props to further style them if needed.
+
+## Full variant
+
+Add the `variant='full'` prop to a `SideNav.Link` to spread child elements across the link, which is useful for status icons, labels, and the like.
+
+```jsx live
+<SideNav bordered maxWidth={360} aria-label="Main">
+  <SideNav.Link href="#url">
+    <Text>Text Only</Text>
+  </SideNav.Link>
+  <SideNav.Link href="#url">
+    <Avatar size={16} mr={2} src="https://avatars.githubusercontent.com/hubot?s=32" />
+    <Text>With an avatar</Text>
+  </SideNav.Link>
+  <SideNav.Link href="#url">
+    <StyledOcticon sx={{mr: 2}} size={16} icon={ZapIcon} />
+    <Text>With an Octicon</Text>
+  </SideNav.Link>
+  <SideNav.Link href="#url" variant="full" selected>
+    <Text>With a status icon</Text>
+    <StyledOcticon sx={{mr: 2}} size={16} icon={DotIcon} color="icon.success" />
+  </SideNav.Link>
+  <SideNav.Link href="#url" variant="full">
+    <Text>With a label</Text>
+    <Label outline>label</Label>
+  </SideNav.Link>
+  <SideNav.Link href="#url" variant="full">
+    <Text>With a counter</Text>
+    <CounterLabel>16</CounterLabel>
+  </SideNav.Link>
+  <SideNav.Link href="#url">
+    <Heading as="h5" sx={{fontSize: 1}}>
+      A heading
+    </Heading>
+    <Text>and some more content</Text>
+  </SideNav.Link>
+</SideNav>
+```
+
+## Lightweight variant
+
+Add the `variant="lightweight"` prop to `SideNav` to render an alternative, more lightweight version that has items with no borders and are more condensed.
+
+```jsx live
+<Box
+  borderWidth="1px"
+  borderStyle="solid"
+  borderColor="border.primary"
+  borderRadius={2}
+  p={3}
+  backgroundColor="bg.secondary"
+  maxWidth={360}
+>
+  <Box
+    borderStyle="solid"
+    borderColor="border.primary"
+    borderWidth={0}
+    borderBottomWidth={1}
+    borderRadius={0}
+    mb={2}
+    pb={1}
+  >
+    <Heading as="h5" fontSize={1} color="text.secondary">
+      Menu
+    </Heading>
+  </Box>
+  <SideNav variant="lightweight">
+    <SideNav.Link href="#url">
+      <Text>Account</Text>
+    </SideNav.Link>
+    <SideNav.Link href="#url" selected>
+      <Text>Profile</Text>
+    </SideNav.Link>
+    <SideNav.Link href="#url">
+      <Text>Emails</Text>
+    </SideNav.Link>
+    <SideNav.Link href="#url">
+      <Text>Notifications</Text>
+    </SideNav.Link>
+  </SideNav>
+</Box>
+```
+
+It can also appear nested, as a sub navigation. Use margin/padding [System Props](/system-props) to add indentation.
+
+```jsx live
+<SideNav bordered maxWidth={360}>
+  <SideNav.Link href="#url">
+    <StyledOcticon mr={2} size={16} icon={PersonIcon} />
+    <Text>Account</Text>
+  </SideNav.Link>
+  <SideNav.Link href="#url" selected>
+    <StyledOcticon mr={2} size={16} icon={OctofaceIcon} />
+    <Text>Profile</Text>
+  </SideNav.Link>
+
+  <SideNav bordered variant="lightweight" py={3} pl={6} backgroundColor="sidenav.selectedBg">
+    <SideNav.Link href="#url" selected>
+      <Text>Sub item 1</Text>
+    </SideNav.Link>
+    <SideNav.Link href="#url">
+      <Text>Sub item 2</Text>
+    </SideNav.Link>
+    <SideNav.Link href="#url">
+      <Text>Sub item 3</Text>
+    </SideNav.Link>
+  </SideNav>
+
+  <SideNav.Link href="#url">
+    <StyledOcticon mr={2} size={16} icon={MailIcon} />
+    <Text>Emails</Text>
+  </SideNav.Link>
+</SideNav>
+```
+
+## Usage with React Router
+
+If using React Router, you can use the `as` prop to render the element as a `NavLink`. React Router will automatically handle setting `aria-current="page"` for you.
+
+```
+<SideNav.Link as={NavLink} to="...">...</SideNav.Link>
+```
+
+## System props
+
+<Note variant="warning">
+
+System props are deprecated in all components except [Box](/Box). Please use the [`sx` prop](/overriding-styles) instead.
+
+</Note>
+
+`SideNav` components get `COMMON`, `BORDER`, `LAYOUT`, and `FLEX` system props. `SideNav.Link` components get `COMMON` and `TYPOGRAPHY` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+### SideNav
+
+| Name     | Type    | Default  | Description                                                                    |
+| :------- | :------ | :------: | :----------------------------------------------------------------------------- |
+| as       | String  |  'nav'   | Sets the HTML tag for the component.                                           |
+| bordered | Boolean |  false   | Renders the component with a border.                                           |
+| variant  | String  | 'normal' | Set to `lightweight` to render [in a lightweight style](#lightweight-variant). |
+
+### SideNav.Link
+
+| Name      | Type    | Default  | Description                                                                                       |
+| :-------- | :------ | :------: | :------------------------------------------------------------------------------------------------ |
+| as        | String  |   'a'    | Sets the HTML tag for the component.                                                              |
+| href      | String  |          | URL to be used for the Link                                                                       |
+| muted     | Boolean |  false   | Uses a less prominent shade for Link color, and the default link shade on hover                   |
+| selected  | Boolean |  false   | Sets the link as selected, giving it a different style and setting the `aria-current` attribute.  |
+| underline | Boolean |  false   | Adds underline to the Link                                                                        |
+| variant   | String  | 'normal' | Set to `full` to render [a full variant](#full-variant), suitable for including icons and labels. |