# **Acceptance criteria**

* There is a `Primer::OpenProject::TreeView` component within our Primer repo

* In general, the component follows the specification of the Primer team: [https://primer.style/product/components/tree-view/guidelines/](https://primer.style/product/components/tree-view/guidelines/) . We will repeat the most relevant parts in the following specification:


## Anatomy

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/407484/content"></div></figure>

1. **Parent node**: Expands/collapses to show/hide child nodes.

2. **End node**: A node with no children

3. **Chevron**: Expands/collapses a parent node and indicates expanded/collapsed state.

4. **Nesting level indicator lines**: Each line represents a level of nesting depth

5. **Leading action (optional)**: An IconButton to allow interaction with the node besides activating or expanding.

6. **Leading visual (optional)**: A visual cue for additional context

7. **Node label**: The text label for the node

8. **Trailing visual (optional)**: Same as a leading visual, but at the end


## Behaviour

**Expanding/Collapsing**

* Begin of the deletion \[OPEN\]End of the deletion Keyboard users can expand or collapse nodes without activating them by using the left and right arrow keys.

* For cursor users, there are two click areas:

* clicking the chevron only expands or collapses the node Begin of the insertion

End of the insertion Begin of the deletion

End of the deletion * Begin of the deletion \[OPEN\] should that fire an event so that we can react to it?

* End of the deletion clicking anywhere else will activate the node Begin of the insertion

End of the insertion Begin of the deletion

End of the deletion * Begin of the deletion \[OPEN\] What does &quot;activating&quot; mean? Send a request to an href?

* End of the deletion If the node cannot be activated, clicking anywhere on the node will expand it.

* When a child node is active, all of it&#39;s parent nodes should be expanded.

* If a user expands nested parent nodes and then collapses a parent node higher in the hierarchy, persist the expanded parent nodes lower in the hierarchy.


**Loading strategies**

* There are tow loading strategies:

* static

* dynamically with a loading indicator

* When no items can be loaded, there is a message shown &quot;No items found&quot; (Text might be adapted later)

* \[OPEN\] When the load fails, there is a simple error message inside the tree (Note, that this is contrary to what Primer does, see section &quot;Out of scope&quot;). Further, there is a small button to re-fetch the items.


Begin of the insertion## **Proposal for organising our work**End of the insertion Begin of the deletion <br>End of the deletion

Begin of the insertion**(To be discussed with Cameron)**

* **Start with:**

* Cameron will Iiplement the original TreeView as-is in Rails for OpenProject for navigation

* **Then:**

* Parimal will write a feature to extend SelectPanel to show hierarchies:

* v1: No extend/collapse

* v2: With extend/collapse

* Henriette will write a separate feature for a right-side component with actions (to complement a vanilla TreeView on the left for navigation)


#### **Use case to test:**

* Add TreeView (for navigation) to:

* Administration → Custom fields → Work packages → _{Custom field type hierarchy}_


End of the insertion ## Out of scope

* Begin of the deletion \[OPEN\]End of the deletion If non-end nodes are in the ancestry and the parent nodes cannot be activated, you may combine parent nodes into a single parent node to reduce the levels of nesting.


<figure class="image image_resized op-uc-figure" style="width:389px;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/407498/content"></div></figure>

* Inform users why the data cannot be retrieved and give them a path to resolve it. Begin of the insertion

* Primer says: &quot;TheEnd of the insertion Begin of the deletion TheEnd of the deletion error message cannot appear in the TreeView because it is not semantically a node in the tree. Instead, the error message should appear in a [Dialog](https://primer.style/product/components/dialog/) with an optional call-to-action that can resolve the Begin of the insertionerror.&quot; but we can possibly challenge this.


End of the insertion Begin of the deletion error.


<br>

End of the deletion ##

# **Open questions**

* Do we want to get it merged upstream?

* Begin of the deletion Do we need own visuals or is the component definition of Primer enough?

* End of the deletion How much accessibility support do we require in the first iteration? Begin of the insertion

* End of the insertion See Begin of the insertion[https://primer.style/product/components/tree-view/accessibility/](https://primer.style/product/components/tree-view/accessibility/)

* If it&#39;s in our repository and not upstream, we have a larger responsibility to ensure accessibility.


End of the insertion Begin of the deletion [https://primer.style/product/components/tree-view/accessibility/](https://primer.style/product/components/tree-view/accessibility/)&nbsp;


End of the deletion # **Potential usage**

Begin of the insertion<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>Use case</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>Dominic's notes</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>Remarks</strong></p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>Project selector</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">TheEnd of the insertion Begin of the deletion <br>

##

## Project selector

TheEnd of the deletion project selector allows the user to switch between projects. Begin of the insertionIt'sEnd of the insertion Begin of the deletion It&#39;sEnd of the deletion part of the topbar and always accessible to the Begin of the insertionuser</p><p class="op-uc-p"><strong>Functionality</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">ShowsEnd of the insertion Begin of the deletion user

**Functionality**

* ShowsEnd of the deletion all projects available to the user in a hierarchical Begin of the insertionstructure</p></li><li class="op-uc-list--item"><p class="op-uc-p">TheEnd of the insertion Begin of the deletion structure

* TheEnd of the deletion active project is highlighted Begin of the insertionvisually</p></li><li class="op-uc-list--item"><p class="op-uc-p">ItemsEnd of the insertion Begin of the deletion visually

* ItemsEnd of the deletion in the project selector are Begin of the insertionlinks</p></li><li class="op-uc-list--item"><p class="op-uc-p">OnEnd of the insertion Begin of the deletion links

* OnEnd of the deletion click the user is navigated to the selected Begin of the insertionproject</p></li><li class="op-uc-list--item"><p class="op-uc-p">ShowsEnd of the insertion Begin of the deletion project

* ShowsEnd of the deletion an icon for favorite Begin of the insertionprojects</p></li><li class="op-uc-list--item"><p class="op-uc-p">AllowsEnd of the insertion Begin of the deletion projects

* AllowsEnd of the deletion searching for project Begin of the insertionnames</p></li><li class="op-uc-list--item"><p class="op-uc-p">AllowEnd of the insertion Begin of the deletion names

* AllowEnd of the deletion filter for Begin of the insertionfavorites</p></li></ul><p class="op-uc-p"><imgEnd of the insertion Begin of the deletion favorites


<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:269px;" Begin of the insertionsrc="/api/v3/attachments/414876/content"></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>Vanilla Treeview:</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">Clicking on the parent node should not collapse/expand, but simply function as a link to the project</p></li><li class="op-uc-list--item"><p class="op-uc-p">We could use the leading action to clear current project scope</p></li></ul><p class="op-uc-p"><strong>Possible additional need:</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">Trailing action instead of/on top of trailing visual (to star/favourite a project)</p></li></ul></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>Include projects</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">InEnd of the insertion Begin of the deletion src="/api/v3/attachments/414876/content">

##

## Include projects

InEnd of the deletion work package list a user usually only sees work packages of the current project. But if wanted, the user can include work packages of other projects with the Begin of the insertion"include projects" selector.</p><p class="op-uc-p"><strong>Functionality</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">ShowsEnd of the insertion Begin of the deletion &quot;include projects&quot; selector.

**Functionality**

* ShowsEnd of the deletion all projects available to the user in a hierarchical Begin of the insertionstructure</p></li><li class="op-uc-list--item"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion structure

* UserEnd of the deletion can enable one or more projects Begin of the insertion(checkbox)</p></li><li class="op-uc-list--item"><p class="op-uc-p">"Only selected"-filterEnd of the insertion Begin of the deletion (checkbox)

* &quot;Only selected&quot;-filterEnd of the deletion to allow user an overview of the selected Begin of the insertionitems</p></li><li class="op-uc-list--item"><p class="op-uc-p">"IncludeEnd of the insertion Begin of the deletion items

* &quot;IncludeEnd of the deletion all Begin of the insertionsub-projects"-optionEnd of the insertion Begin of the deletion sub-projects&quot;-optionEnd of the deletion to enable all sub-projects when a project is Begin of the insertionenabled.</p></li><li class="op-uc-list--item"><p class="op-uc-p">DeselectEnd of the insertion Begin of the deletion enabled.

* DeselectEnd of the deletion all Begin of the insertionprojects</p></li></ul><p class="op-uc-p"><imgEnd of the insertion Begin of the deletion projects


<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:295px;" Begin of the insertionsrc="/api/v3/attachments/415033/content"></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>Not TreeView</strong></p><p class="op-uc-p">We will need a multi-level select component. We have these two options:</p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">Extend the Select panel to allow nesting/multi-level or</p></li><li class="op-uc-list--item"><p class="op-uc-p">Extend TreeView to allow multi-selection (leading action becomes a checkbox)</p></li></ul><p class="op-uc-p">We think extending the Select panel makes more sense.</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>ProjectEnd of the insertion Begin of the deletion src="/api/v3/attachments/415033/content">

<br>

## ProjectEnd of the deletion selector to activate Begin of the insertioneg. storages</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion e.g. storages in multiple projects at once

UserEnd of the deletion can select multiple projects to activate a project attribute, a work package type, a storage or other objects that can be added per Begin of the insertionproject</p><p class="op-uc-p"><strong>Functionality</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">ShowsEnd of the insertion Begin of the deletion project

**Functionality**

* ShowsEnd of the deletion all projects available to the user in a hierarchical Begin of the insertionstructure</p></li><li class="op-uc-list--item"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion structure

* UserEnd of the deletion can add projects one by one or include all Begin of the insertionsub-projects</p></li><li class="op-uc-list--item"><p class="op-uc-p">ProjectsEnd of the insertion Begin of the deletion sub-projects

* ProjectsEnd of the deletion that already have this storage activated are Begin of the insertiondisabled</p></li></ul><p class="op-uc-p"><imgEnd of the insertion Begin of the deletion disabled


<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:511px;" Begin of the insertionsrc="/api/v3/attachments/415096/content"></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>Not TreeView</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">We already have a fully-functioning auto-completor with projectEnd of the insertion Begin of the deletion src="/api/v3/attachments/415096/content">

##

## FileEnd of the deletion selector Begin of the insertion(Angular).</p></li><li class="op-uc-list--item"><p class="op-uc-p">Same as include project: Select panel with multi-level would be more useful (can input names)</p></li></ul></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>File selector</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion

UserEnd of the deletion can choose one or more files to attach as file links to a work Begin of the insertionpackage.</p><p class="op-uc-p"><strong>Functionality</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">ShowsEnd of the insertion Begin of the deletion package.

**Functionality**

* ShowsEnd of the deletion contents of a folder (sub-folders and Begin of the insertionfiles)</p></li><li class="op-uc-list--item"><p class="op-uc-p">HasEnd of the insertion Begin of the deletion files)

* HasEnd of the deletion breadcrumb for Begin of the insertionnavigation</p></li><li class="op-uc-list--item"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion navigation

* UserEnd of the deletion can select one or multiple Begin of the insertionitems</p></li><li class="op-uc-list--item"><p class="op-uc-p">ShowsEnd of the insertion Begin of the deletion items

* ShowsEnd of the deletion number of selected Begin of the insertionitems</p></li><li class="op-uc-list--item"><p class="op-uc-p">Clear selection</p><p class="op-uc-p"><br><br></p></li></ul><p class="op-uc-p"><imgEnd of the insertion Begin of the deletion items

* Clear selection

<br>


<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:395px;" Begin of the insertionsrc="/api/v3/attachments/415054/content"></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>TreeView for navigation, another component on the right for actions</strong></p><p class="op-uc-p">We considered three options, but think option 2 makes most sense.</p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">Option 1: Same as include projects (TreeView with multi-select)</p></li><li class="op-uc-list--item"><p class="op-uc-p"><i>Option 2: Use TreeView on the left, but use a different component on the right for actions (like selecting)</i></p></li><li class="op-uc-list--item"><p class="op-uc-p">Option 3: Shift+Select for TreeView?</p></li></ul></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>Location picker</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion src="/api/v3/attachments/415054/content">

##

## Location picker

UserEnd of the deletion can choose a location. Used to define the location for a manual project Begin of the insertionfolder.</p><p class="op-uc-p"><strong>Functionality</strong></p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">ShowsEnd of the insertion Begin of the deletion folder.

**Functionality**

* ShowsEnd of the deletion contents of a folder (sub-folders and Begin of the insertionfiles)</p></li><li class="op-uc-list--item"><p class="op-uc-p">HasEnd of the insertion Begin of the deletion files)

* HasEnd of the deletion breadcrumb for Begin of the insertionnavigation</p></li><li class="op-uc-list--item"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion navigation

* UserEnd of the deletion can select a Begin of the insertionlocation</p></li><li class="op-uc-list--item"><p class="op-uc-p">UserEnd of the insertion Begin of the deletion location

* UserEnd of the deletion can create new Begin of the insertionfolder</p></li></ul><p class="op-uc-p"><imgEnd of the insertion Begin of the deletion folder


<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:465px;" Begin of the insertionsrc="/api/v3/attachments/415058/content"></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>TreeViewEnd of the insertion Begin of the deletion src="/api/v3/attachments/415058/content">

##

## SelectorEnd of the deletion for Begin of the insertionnavigation, another component on the right for actions</strong></p><p class="op-uc-p">Same as file selector</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>Selector forEnd of the insertion custom field of type Begin of the insertionhierarchy</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">AEnd of the insertion Begin of the deletion Hierarchy

AEnd of the deletion user wants to select one or more items of a Begin of the insertionhierarchy.</p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">WorkEnd of the insertion Begin of the deletion hierarchy.

* WorkEnd of the deletion package Begin of the insertiontable<br><imgEnd of the insertion Begin of the deletion table
<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:316px;" Begin of the insertionsrc="/api/v3/attachments/415073/content"></p></li><li class="op-uc-list--item"><p class="op-uc-p">WorkEnd of the insertion Begin of the deletion src="/api/v3/attachments/415073/content">

* WorkEnd of the deletion package details Begin of the insertionview<br><imgEnd of the insertion Begin of the deletion view
<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:394px;" Begin of the insertionsrc="/api/v3/attachments/415068/content"></p></li><li class="op-uc-list--item"><p class="op-uc-p">ProjectEnd of the insertion Begin of the deletion src="/api/v3/attachments/415068/content">

* ProjectEnd of the deletion attribute of type Hierarchy - not implemented Begin of the insertionyet<br><imgEnd of the insertion Begin of the deletion yet
<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:418px;" Begin of the insertionsrc="/api/v3/attachments/415076/content"></p></li><li class="op-uc-list--item"><p class="op-uc-p">WorkEnd of the insertion Begin of the deletion src="/api/v3/attachments/415076/content">

* WorkEnd of the deletion package field in copy form - not implemented Begin of the insertionyet<br><imgEnd of the insertion Begin of the deletion yet
<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:382px;" Begin of the insertionsrc="/api/v3/attachments/415075/content"></p><p class="op-uc-p"><br><br></p></li></ul></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>Not TreeView</strong></p><p class="op-uc-p">Similar to include projects (Select panel with hierarchy)</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>ChangeEnd of the insertion Begin of the deletion src="/api/v3/attachments/415075/content">

<br>


## ChangeEnd of the deletion parent for Begin of the insertioncustumEnd of the insertion Begin of the deletion customEnd of the deletion field of type Begin of the insertionhierarchy</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">(NotEnd of the insertion Begin of the deletion Hierarchy items - NotEnd of the deletion implemented Begin of the insertionyet)</p><p class="op-uc-p">AEnd of the insertion Begin of the deletion yet

AEnd of the deletion user can change the parent of an item. In the three-dot menu of a row is the option Begin of the insertion"Change parent".End of the insertion Begin of the deletion &quot;Change parent&quot;.End of the deletion This triggers a modal to choose a new parent item for this row. The user sees the hierarchy and can select a new Begin of the insertionnote.</p><p class="op-uc-p"><imgEnd of the insertion Begin of the deletion note.

<imgEnd of the deletion class="image_resized op-uc-image op-uc-image_inline" style="width:509px;" Begin of the insertionsrc="/api/v3/attachments/415106/content"></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>TreeView for navigation, another component on the right for actions</strong></p><p class="op-uc-p">Same as file selector</p></td></tr></tbody></table></figure>End of the insertion Begin of the deletion src="/api/v3/attachments/415106/content">End of the deletion

Begin of the insertion##

##End of the insertion Begin of the deletion <br>

# Visuals

TBDEnd of the deletion