# Feature DREAM-252 - TreeView Primer View Component

Project: Stream Design System
Status: closed
URL: https://community.openproject.org/work_packages/DREAM-252

## Planning

| Attribute | Value |
| --- | --- |
| Date |  |
| Priority | Medium |
| Target versions | 16.1.0 |
| Sprint |  |
| Backlog bucket |  |
| Votes |  |
| List | a11y report 2025 |
| Roadmap |  |
| Relevance |  |

## OPEN POINTS / FEEDBACK

| ID | Subject | Status | Decision |
| --- | --- | --- | --- |
| DREAM-278 | How do we handle multi-selection with a dynamic loading strategies? | decided | Do not allow dynamic loading strategy in combination with the select variant multiple |

## Use cases

_No work packages_

## Features and Chunks

_No work packages_

## Bugs and other work packages

| ID | Type | Subject | Status | Assignee | Target versions | Spent time | Module |
| --- | --- | --- | --- | --- | --- | --- | --- |
| DREAM-291 | Bug | TreeView is not collapsible when clicking the arrows | closed |  | 16.1.0 |  | Frontend components and Primer design system / TreeView |
| DREAM-282 | Code maintenance | Document TreeView in our lookbook | closed |  | 16.1.0 |  | Frontend components and Primer design system |
| DREAM-307 | Bug | Checkboxes should be selected when clicking the label | rejected |  | 16.1.0 |  | Frontend components and Primer design system / TreeView |
| DREAM-287 | Bug | Broken pages in Primer lookbook | closed |  | 16.2.0 |  | Frontend components and Primer design system / Lookbook |

## Technical Details

| Attribute | Value |
| --- | --- |
| Module | Frontend components and Primer design system |
| Feature Flag |  |
| Requires doc change | No |
| Enterprise plan |  |

## Details

| Attribute | Value |
| --- | --- |
| Pull preview |  |
| Mockups |  |
| Accessibility | Yes |

## People

| Attribute | Value |
| --- | --- |
| Assignee |  |
| Accountable | Henriette Darge |
| Product manager |  |
| Feature Lead |  |
| Developers | Cameron Dutro |
| Designer | Parimal Satyal |
| Ordered by |  |
| Signed off by |  |
| Interest by |  |

## Estimates and progress

| Attribute | Value |
| --- | --- |
| PD (min) |  |
| PD (max) |  |
| Work |  |
| Labor costs |  |

## Description

# **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/> . 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'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 two loading strategies:
    
      - static
    
      - dynamically with a loading indicator

  - When no items can be loaded, there is a message shown "No items found" (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 "Out of scope"). Further, there is a small button to re-fetch the items.

**Multi-select**

  - Additionally to the Primer specification, there is an option to allow multi-select
    
      - When that is chosen, the component renders checkboxes in front of the items

  - There is an additional option to decide whether all children should also be selected when a parent is selected

  - **Note**: The multi-select option is not allowed in combination with the dynamic loading strategy, see <mention class="mention" data-id="63714" data-type="work_package" data-text="##63714">##63714</mention>

## 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: "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." but we can possibly challenge this.

## 

# **Open questions**

  - ~~Do we want to get it merged upstream?~~
    
      - We try to, but will start development in our fork

  - How much accessibility support do we require in the first iteration?
    
      - See <https://primer.style/product/components/tree-view/accessibility/>
    
      - If it'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: <mention class="mention" data-id="62993" data-type="work_package" data-text="###62993">###62993</mention>

  - **Then:**
    
      - Parimal will write a feature to extend SelectPanel to show hierarchies: <mention class="mention" data-id="63321" data-type="work_package" data-text="###63321">\#\#\#63321</mention>
    
      - 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 component:</p>
<p class="op-uc-p"><mention class="mention" data-id="63321" data-type="work_package" data-text="###63321"><mention class="mention" data-id="63321" data-type="work_package" data-text="###63321">###63321</mention></mention> </p>
<p class="op-uc-p">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>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 class="op-uc-p"><br><br><br><br><br><br><br><br><br><br><br><br><br><br></p>
</li>
</ul>
<p 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 class="op-uc-p"><br><br><br><br><br><br><br><br><br><br><br><br><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>
<p class="op-uc-p"><mention class="mention" data-id="63321" data-type="work_package" data-text="###63321">###63321</mention></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>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 <mention class="mention" data-id="62993" data-type="work_package" data-text="#62993">#62993</mention></p></li></ul>
</td>
</tr>
</tbody></table></figure>

## 

##
