# **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**

* 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

* clicking anywhere else will activate the node

* 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.


## Out of scope

* 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.

* Primer says: &quot;The 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 error.&quot; but we can possibly challenge this.


##

# **Open questions**

* Do we want to get it merged upstream?

* How much accessibility support do we require in the first iteration?

* See [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.


# **Proposal for organising our work**

**(To be discussed with Cameron)**

* **Start with:**

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

* First use case to test: ###62993

* **Then:**

* Parimal will write a feature to extend SelectPanel to show hierarchies: Begin of the insertion<mention class="mention" data-id="63321" data-type="work_package" data-text="###63321">###63321</mention>

End of the insertion Begin of the deletion

End of the deletion * Begin of the deletion v1: No extend/collapse

* v2: With extend/collapse

* End of the deletion Henriette will write a separate feature for a right-side component with actions (e.g. for the location picker) to complement a vanilla TreeView on the left for navigation; out of scope for this WorkPackage.)


# **Potential usage**

<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;width:500px;"><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">The project selector allows the user to switch between projects. It's part of the topbar and always accessible to the user</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">Shows all projects available to the user in a hierarchical structure</p></li><li class="op-uc-list--item"><p class="op-uc-p">The active project is highlighted visually</p></li><li class="op-uc-list--item"><p class="op-uc-p">Items in the project selector are links</p></li><li class="op-uc-list--item"><p class="op-uc-p">On click the user is navigated to the selected project</p></li><li class="op-uc-list--item"><p class="op-uc-p">Shows an icon for favorite projects</p></li><li class="op-uc-list--item"><p class="op-uc-p">Allows searching for project names</p></li><li class="op-uc-list--item"><p class="op-uc-p">Allow filter for favorites</p></li></ul><p class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:269px;" src="/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">[Open] 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">In 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 "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">Shows all projects available to the user in a hierarchical structure</p></li><li class="op-uc-list--item"><p class="op-uc-p">User can enable one or more projects (checkbox)</p></li><li class="op-uc-list--item"><p class="op-uc-p">"Only selected"-filter to allow user an overview of the selected items</p></li><li class="op-uc-list--item"><p class="op-uc-p">"Include all sub-projects"-option to enable all sub-projects when a project is enabled.</p></li><li class="op-uc-list--item"><p class="op-uc-p">Deselect all projects</p></li></ul><p class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:295px;" src="/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 Begin of the insertioncomponent:</p><p class="op-uc-p"><mention class="mention" data-id="63321" data-type="work_package" data-text="###63321">###63321</mention>&nbsp;</p><p class="op-uc-p">WeEnd of the insertion Begin of the deletion component. WeEnd of the deletion 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>Project selector to activate eg. storages</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">User can select multiple projects to activate a project attribute, a work package type, a storage or other objects that can be added per project</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">Shows all projects available to the user in a hierarchical structure</p></li><li class="op-uc-list--item"><p class="op-uc-p">User can add projects one by one or include all sub-projects</p></li><li class="op-uc-list--item"><p class="op-uc-p">Projects that already have this storage activated are disabled</p></li></ul><p class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:511px;" src="/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 project selector (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">User can choose one or more files to attach as file links to a work package.</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">Shows contents of a folder (sub-folders and files)</p></li><li class="op-uc-list--item"><p class="op-uc-p">Has breadcrumb for navigation</p></li><li class="op-uc-list--item"><p class="op-uc-p">User can select one or multiple items</p></li><li class="op-uc-list--item"><p class="op-uc-p">Shows number of selected items</p></li><li class="op-uc-list--item"><p class="op-uc-p">Clear selection</p><p Begin of the insertionclass="op-uc-p"><br><br><br><br><br><br><br><br><br><br></p></li></ul><pEnd of the insertion Begin of the deletion class="op-uc-p"><br><br><br><br><br><br><br><br></p></li></ul><pEnd of the deletion class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:395px;" src="/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: Split the content: 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">User can choose a location. Used to define the location for a manual project folder.</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">Shows contents of a folder (sub-folders and files)</p></li><li class="op-uc-list--item"><p class="op-uc-p">Has breadcrumb for navigation</p></li><li class="op-uc-list--item"><p class="op-uc-p">User can select a location</p></li><li class="op-uc-list--item"><p class="op-uc-p">User can create new folder</p></li></ul><p class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:465px;" src="/api/v3/attachments/415058/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><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 for custom field of type hierarchy</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">A user wants to select one or more items of a hierarchy.</p><ul class="op-uc-list"><li class="op-uc-list--item"><p class="op-uc-p">Work package table<br><img class="image_resized op-uc-image op-uc-image_inline" style="width:316px;" src="/api/v3/attachments/415073/content"></p></li><li class="op-uc-list--item"><p class="op-uc-p">Work package details view<br><img class="image_resized op-uc-image op-uc-image_inline" style="width:394px;" src="/api/v3/attachments/415068/content"></p></li><li class="op-uc-list--item"><p class="op-uc-p">Project attribute of type Hierarchy - not implemented yet<br><img class="image_resized op-uc-image op-uc-image_inline" style="width:418px;" src="/api/v3/attachments/415076/content"></p></li><li class="op-uc-list--item"><p class="op-uc-p">Work package field in copy form - not implemented yet<br><img class="image_resized op-uc-image op-uc-image_inline" style="width:382px;" src="/api/v3/attachments/415075/content"></p><p Begin of the insertionclass="op-uc-p"><br><br><br><br><br><br><br><br><br><br></p></li></ul></td><tdEnd of the insertion Begin of the deletion class="op-uc-p"><br><br><br><br><br><br><br><br></p></li></ul></td><tdEnd of the deletion 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 Begin of the insertionhierarchy):</p><p class="op-uc-p">###63321</p></td></tr><trEnd of the insertion Begin of the deletion hierarchy)</p></td></tr><trEnd of the deletion class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;width:100px;"><p class="op-uc-p"><strong>Change parent for custum field of type hierarchy</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">(Not implemented yet)</p><p class="op-uc-p">A user can change the parent of an item. In the three-dot menu of a row is the option "Change parent". This triggers a modal to choose a new parent item for this row. The user sees the hierarchy and can select a new note.</p><p class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:509px;" src="/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><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p"><strong>Show the hierachy for a hierarchy custom field</strong></p></td><td class="op-uc-table--cell" style="vertical-align:top;"><p class="op-uc-p">(Not implemented yet)</p><p class="op-uc-p">A user can easily see and navigate the hierachy of a hierarchy customField. The TreeView would displayed next to the BorderBox.</p><p class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:453px;" src="/api/v3/attachments/417307/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">Prime example for the tree view. Would be a great first use case, see #62993</p></li></ul></td></tr></tbody></table></figure>

##

##