Content
View differences
Updated by Parimal Satyal about 1 year ago
### **Context**
We are currently working on creating a Rails/ViewComponent version of Primer's Treeview: <mention class="mention" data-id="62667" data-type="work_package" data-text="###62667">###62667</mention>
Whilst useful, the TreeView's limitations make it unsuitable for user in places like the 'Include projects' drop-down, which requires hierarchy _and_ multi-select. The [Select panel](https://primer.style/components/selectpanel) would solve this problem if it supported hierarchies, but it doesn't.
### **Acceptance criteria**
* Create a new Primer component will be constructed with:
* A container like the Select panel (with a search field), but
* The ActionList replaced by a TreeView
* The list:
* Should look and behave like a TreeView 🌳
* The list should support at least 5 levels of hierarchy
* _\[open\] possibly unlimited?_
* Should allow selecting multiple items
* Each individual node in the TreeView will also have a leading checkbox to select/deselect the component
* The component should require the user to explicitly execute an action on that list (eg. "Submit")
* The component provides a text field to filter the result list
* _\[open\] The component allows two filtering stategies._
* _Static: only if the underlying TreeView itself is static_
* _filtering is done at browser-level (no server calls required)_
* _Dynamic: if the underlying TreeView is dynamic (additional async calls can be made) (?? Open: Could probably also be used if the underlying TreeView is static)_
* _filtering will send a new request to the server to populate **all** results that match the given string,_
* _If there is a lot content (eg. over 25 objects, regardless of if this is a parent or the result node):_
* _The component display only the first 25 items and there will be a 'Show more' action at the very bottom. This includes both nodes and leaves in the hierarchy._
* _Clicking on the show more will append the next 25 items to the list._
* _\[Open\] Does that mean that with the dynamic loading strategy we also only show 25 items when opening the component (so before anything was filtered)_
* _The logic to decide which items to show is as follows:_
* _**Start at the top level**: Begin with the first top-level node and expand it._
* _**Load children**: Display the children of the first node until the 25-item limit is reached._
* _**Nested nodes**: If the first node contains child nodes (i.e., nested nodes), the **first child node should be expanded first**, and its children should be displayed with priority (e.g., 1 child node + 23 of its children = 24 + 1 top-level node = 25)._
* _**Expand additional nodes**:_
_If the first node has fewer than 24 children (including child nodes), the next top-level node is expanded, and its children are displayed until the total of 25 visible elements is reached_
* The nodes in the list can be expanded/collapsed
* _\[open\] For certain usages (eg. project selector) with need it to be possible for the parent node to be selectable even though all sub-nodes Iterate and unselected. (Brought up by Marc)_
add this in v2?_
#### **Additonal considerations**
These additional features or options are worth considering but might not have to be a part of the component itself:
* A segmented control to filter the view (eg. 'All | Favourites')
* An additional action that acts on the whole list (eg. 'Select all' / 'Clear selection')
* The project selector in admin pages (eg. for a project attribute) can be the first use case.
* To discuss with Cameron.
**Initial thoughts from meeting with Cameron:**
* But we can start with a static list for v1 and then iterate and write scenarios.
* We _could_ potentially, at a component level, apply the same filter criteria to the server results. Let the feature deal with it.
* An alternate approach is, instead of 'show more', require the search to be more specific and afford ways for the user to be more specific. Worth considering.
* Select panel has three fetch strategies:
* local/static
* eventually local / lazylocal
* remote
#### **Use cases**
<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 original 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>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"><br></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;"><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>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> </p></li></ul></td><td class="op-uc-table--cell" style="vertical-align:top;"><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"><p class="op-uc-p"><strong>Project class="op-uc-p">Project selector for admin settings requireing the selection of projects (Eg. Project attributes)</strong></p></td><td attributes)</p></td><td class="op-uc-table--cell"><p class="op-uc-p">Places with the 'Project' tab, eg. File storages.</p><p class="op-uc-p">Today in a dialog but perhaps this is not necessary once we have this component.</p><p class="op-uc-p"><img class="image_resized op-uc-image op-uc-image_inline" style="width:678px;" src="/api/v3/attachments/434783/content"></p></td><td class="op-uc-table--cell"><p class="op-uc-p">Replace modal but with a way to select project by traversing the hierarchy. With an option of course to include all sub-projecs.</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell"><p class="op-uc-p"><strong>Wiki page management</strong></p></td><td class="op-uc-table--cell"><p class="op-uc-p"><br></p></td><td class="op-uc-table--cell"><p class="op-uc-p">For actions like bulk delete or bulk move. Might need draggable. </p><p class="op-uc-p">Wiki is not the biggest priority right now.</p></td></tr></tbody></table></figure> class="op-uc-p"><br></p></td></tr></tbody></table></figure>
**Figma mockups**
* To be defined
**Technical notes**
* <br>
**Permissions and visibility considerations**
* _None_
**Translation considerations**
* _None_
**Out of scope**
* tbd
We are currently working on creating a Rails/ViewComponent version of Primer's Treeview: <mention class="mention" data-id="62667" data-type="work_package" data-text="###62667">###62667</mention>
Whilst useful, the TreeView's limitations make it unsuitable for user in places like the 'Include projects' drop-down, which requires hierarchy _and_ multi-select. The [Select panel](https://primer.style/components/selectpanel) would solve this problem if it supported hierarchies, but it doesn't.
### **Acceptance criteria**
* Create a new Primer component will be constructed with:
* A container like the Select panel (with a search field), but
* The ActionList replaced by a TreeView
* The list:
* Should look and behave like a TreeView 🌳
* The list should support at least 5 levels of hierarchy
* _\[open\] possibly unlimited?_
* Should allow selecting multiple items
* Each individual node in the TreeView will also have a leading checkbox to select/deselect the component
* The component should require the user to explicitly execute an action on that list (eg. "Submit")
* The component provides a text field to filter the result list
* _\[open\] The component allows two filtering stategies._
* _Static: only if the underlying TreeView itself is static_
* _filtering is done at browser-level (no server calls required)_
* _Dynamic: if the underlying TreeView is dynamic (additional async calls can be made) (?? Open: Could probably also be used if the underlying TreeView is static)_
* _filtering will send a new request to the server to populate **all** results that match the given string,_
* _If there is a lot content (eg. over 25 objects, regardless of if this is a parent or the result node):_
* _The component display only the first 25 items and there will be a 'Show more' action at the very bottom. This includes both nodes and leaves in the hierarchy._
* _Clicking on the show more will append the next 25 items to the list._
* _\[Open\] Does that mean that with the dynamic loading strategy we also only show 25 items when opening the component (so before anything was filtered)_
* _The logic to decide which items to show is as follows:_
* _**Start at the top level**: Begin with the first top-level node and expand it._
* _**Load children**: Display the children of the first node until the 25-item limit is reached._
* _**Nested nodes**: If the first node contains child nodes (i.e., nested nodes), the **first child node should be expanded first**, and its children should be displayed with priority (e.g., 1 child node + 23 of its children = 24 + 1 top-level node = 25)._
* _**Expand additional nodes**:_
_If the first node has fewer than 24 children (including child nodes), the next top-level node is expanded, and its children are displayed until the total of 25 visible elements is reached_
* The nodes in the list can be expanded/collapsed
These additional features or options are worth considering but might not have to be a part of the component itself:
* A segmented control to filter the view (eg. 'All | Favourites')
* An additional action that acts on the whole list (eg. 'Select all' / 'Clear selection')
* The project selector in admin pages (eg. for a project attribute) can be the first use case.
* To discuss with Cameron.
* But we can start with a static list for v1 and then iterate and write scenarios.
* We _could_ potentially, at a component level, apply the same filter criteria to the server results. Let the feature deal with it.
* An alternate approach is, instead of 'show more', require the search to be more specific and afford ways for the user to be more specific. Worth considering.
* Select panel has three fetch strategies:
* local/static
* eventually local / lazylocal
* remote
#### **Use cases**
<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 original 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>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"><br></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;"><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>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> </p></li></ul></td><td class="op-uc-table--cell" style="vertical-align:top;"><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"><p class="op-uc-p"><strong>Project
**Figma mockups**
* To be defined
**Technical notes**
* <br>
**Permissions and visibility considerations**
* _None_
**Translation considerations**
* _None_
**Out of scope**
* tbd