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.

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

TreeView: Add support for leading and trailing visuals #2383

Merged
merged 15 commits into from
Sep 30, 2022
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
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
5 changes: 5 additions & 0 deletions .changeset/twelve-beers-raise.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@primer/react": patch
---

TreeView: Add support for leading and trailing visuals
204 changes: 142 additions & 62 deletions docs/content/TreeView.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,63 +10,98 @@ description: A hierarchical list of items where nested items can be expanded and
### File tree navigation without directory links
Copy link
Contributor

Choose a reason for hiding this comment

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

Could we get an example (and maybe a story?) showing how to use the isExpanded render prop to set different icons for expanded and collapsed states.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Great idea 👍 Let me know if the docs I added make sense


```jsx live drafts
<nav aria-label="File navigation">
<TreeView aria-label="File navigation">
<TreeView.Item>
src
<TreeView.SubTree>
<TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
<TreeView.Item>
Button
<TreeView.SubTree>
<TreeView.LinkItem href="#" current>
Button.tsx
</TreeView.LinkItem>
<TreeView.LinkItem href="#">Button.test.tsx</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.Item>
</TreeView.SubTree>
</TreeView.Item>
<TreeView.Item>
public
<TreeView.SubTree>
<TreeView.LinkItem href="#">index.html</TreeView.LinkItem>
<TreeView.LinkItem href="#">favicon.ico</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.Item>
<TreeView.LinkItem href="#">package.json</TreeView.LinkItem>
</TreeView>
</nav>
<Box sx={{maxWidth: 400}}>
<nav aria-label="File navigation">
<TreeView aria-label="File navigation">
<TreeView.Item>
<TreeView.LeadingVisual>
<TreeView.DirectoryIcon />
</TreeView.LeadingVisual>
src
<TreeView.SubTree>
<TreeView.LinkItem href="#">
<TreeView.LeadingVisual>
<FileIcon />
</TreeView.LeadingVisual>
Avatar.tsx
<TreeView.TrailingVisual>
<StyledOcticon icon={DiffAddedIcon} color="success.fg" aria-label="added" />
</TreeView.TrailingVisual>
</TreeView.LinkItem>
<TreeView.LinkItem href="#" current>
<TreeView.LeadingVisual>
<FileIcon />
</TreeView.LeadingVisual>
Button.tsx
<TreeView.TrailingVisual>
<StyledOcticon icon={DiffModifiedIcon} color="attention.fg" aria-label="modified" />
</TreeView.TrailingVisual>
</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.Item>
<TreeView.LinkItem href="#">
<TreeView.LeadingVisual>
<FileIcon />
</TreeView.LeadingVisual>
package.json
<TreeView.TrailingVisual>
<StyledOcticon icon={DiffModifiedIcon} color="attention.fg" aria-label="modified" />
</TreeView.TrailingVisual>
</TreeView.LinkItem>
</TreeView>
</nav>
</Box>
```

### File tree navigation with directory links

```jsx live drafts
<nav aria-label="File navigation">
<TreeView aria-label="File navigation">
<TreeView.LinkItem href="#">
src
<TreeView.SubTree>
<TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
<TreeView.LinkItem href="#" current>
Button
<TreeView.SubTree>
<TreeView.LinkItem href="#">Button.tsx</TreeView.LinkItem>
<TreeView.LinkItem href="#">Button.test.tsx</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.LinkItem>
<TreeView.LinkItem href="#">
public
<TreeView.SubTree>
<TreeView.LinkItem href="#">index.html</TreeView.LinkItem>
<TreeView.LinkItem href="#">favicon.ico</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.LinkItem>
<TreeView.LinkItem href="#">package.json</TreeView.LinkItem>
</TreeView>
</nav>
<Box sx={{maxWidth: 400}}>
<nav aria-label="File navigation">
<TreeView aria-label="File navigation">
<TreeView.LinkItem href="#">
<TreeView.LeadingVisual>
<TreeView.DirectoryIcon />
</TreeView.LeadingVisual>
src
<TreeView.SubTree>
<TreeView.LinkItem href="#">
<TreeView.LeadingVisual>
<FileIcon />
</TreeView.LeadingVisual>
Avatar.tsx
</TreeView.LinkItem>
<TreeView.LinkItem href="#" current>
<TreeView.LeadingVisual>
<TreeView.DirectoryIcon />
</TreeView.LeadingVisual>
Button
<TreeView.SubTree>
<TreeView.LinkItem href="#">
<TreeView.LeadingVisual>
<FileIcon />
</TreeView.LeadingVisual>
Button.tsx
</TreeView.LinkItem>
<TreeView.LinkItem href="#">
<TreeView.LeadingVisual>
<FileIcon />
</TreeView.LeadingVisual>
Button.test.tsx
</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.LinkItem>
<TreeView.LinkItem href="#">
<TreeView.LeadingVisual>
<FileIcon />
</TreeView.LeadingVisual>
package.json
</TreeView.LinkItem>
</TreeView>
</nav>
</Box>
```

### With controlled expanded state
Expand All @@ -76,7 +111,7 @@ function ControlledTreeView() {
const [expanded, setExpanded] = React.useState(false)

return (
<Box sx={{display: 'grid', gap: 2}}>
<Box sx={{display: 'grid', gap: 2, maxWidth: 400}}>
<Button onClick={() => setExpanded(!expanded)}>{expanded ? 'Collapse' : 'Expand'}</Button>
<nav aria-label="File navigation">
<TreeView aria-label="File navigation">
Expand All @@ -98,6 +133,54 @@ function ControlledTreeView() {
render(<ControlledTreeView />)
```

### With stateful visuals

To render stateful visuals, pass a render function to `TreeView.LeadingVisual` and `TreeView.TrailingVisual`. The function will be called with the `expanded` state of the item.
colebemis marked this conversation as resolved.
Show resolved Hide resolved

```jsx live drafts
<Box sx={{maxWidth: 400}}>
<nav aria-label="File navigation">
<TreeView aria-label="File navigation">
<TreeView.Item>
<TreeView.LeadingVisual>
{({isExpanded}) => (isExpanded ? <FileDirectoryOpenFillIcon /> : <FileDirectoryFillIcon />)}
</TreeView.LeadingVisual>
src
<TreeView.SubTree>
<TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
<TreeView.LinkItem href="#" current>
Button.tsx
</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.Item>
</TreeView>
</nav>
</Box>
```

Since stateful directory icons are a common usecase for TreeView, we provide a `TreeView.DirectoryIcon` component for convenience. The above example can be rewritten as:
colebemis marked this conversation as resolved.
Show resolved Hide resolved

```jsx live drafts
<Box sx={{maxWidth: 400}}>
<nav aria-label="File navigation">
<TreeView aria-label="File navigation">
<TreeView.Item>
<TreeView.LeadingVisual>
<TreeView.DirectoryIcon />
</TreeView.LeadingVisual>
src
<TreeView.SubTree>
<TreeView.LinkItem href="#">Avatar.tsx</TreeView.LinkItem>
<TreeView.LinkItem href="#" current>
Button.tsx
</TreeView.LinkItem>
</TreeView.SubTree>
</TreeView.Item>
</TreeView>
</nav>
</Box>
```

## Props

### TreeView
Expand Down Expand Up @@ -190,17 +273,15 @@ render(<ControlledTreeView />)
{/* <PropsTableSxRow /> */}
</PropsTable>

<!-- TODO: Add leading and trailing visuals -->

<!-- ### TreeView.LeadingVisual
### TreeView.LeadingVisual

<PropsTable>
<PropsTableRow
name="children"
type={`| React.ReactNode
| (props: {isExpanded: boolean}) => React.ReactNode`}
/>
<PropsTableSxRow />
{/* <PropsTableSxRow /> */}
</PropsTable>

### TreeView.TrailingVisual
Expand All @@ -211,14 +292,12 @@ render(<ControlledTreeView />)
type={`| React.ReactNode
| (props: {isExpanded: boolean}) => React.ReactNode`}
/>
<PropsTableSxRow />
{/* <PropsTableSxRow /> */}
</PropsTable>

### TreeView.FolderIcon
### TreeView.DirectoryIcon

<PropsTable>
<PropsTableSxRow />
</PropsTable> -->
<PropsTable>{/* <PropsTableSxRow /> */}</PropsTable>

<!-- TODO: Add components to support async behavior (e.g. LoadingItem) -->

Expand All @@ -242,3 +321,4 @@ render(<ControlledTreeView />)
hasFigmaComponent: false
}}
/>
````
colebemis marked this conversation as resolved.
Show resolved Hide resolved
30 changes: 23 additions & 7 deletions docs/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
},
"dependencies": {
"@primer/gatsby-theme-doctocat": "^4.0.0",
"@primer/octicons-react": "^16.1.0",
"@primer/octicons-react": "^17.5.0",
"@primer/primitives": "4.1.0",
"@styled-system/prop-types": "^5.1.0",
"@styled-system/theme-get": "^5.1.0",
Expand Down
Loading