Content
View differences
Updated by Dominic Bräunlein about 1 year ago
# **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**
* \[OPEN\] 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
* \[OPEN\] should that fire an event so that we can react to it?
* clicking anywhere else will activate the node
* \[OPEN\] What does "activating" mean? Send a request to an href?
* 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 tow 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.
<br>
## Out of scope
* \[OPEN\] 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. 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.
<br>
##
# **Open questions**
* Do we want to get it merged upstream?
* Do we need own visuals or is the component definition of Primer enough?
* 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/)
# **Potential usage**
<br>
##
## Project selector
The project selector allows the user to switch between projects. It's part of the topbar and always accessible to the user
**Functionality**
* Shows all projects available to the user in a hierarchical structure
* The active project is highlighted visually
* Items in the project selector are links
* On click the user is navigated to the selected project
* Shows an icon for favorite projects
* Allows searching for project names
* Allow filter for favorites
<img class="image_resized op-uc-image op-uc-image_inline" style="width:269px;" src="/api/v3/attachments/414876/content">
##
## Include projects
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.
**Functionality**
* Shows all projects available to the user in a hierarchical structure
* User can enable one or more projects (checkbox)
* "Only selected"-filter to allow user an overview of the selected items
* "Include all sub-projects"-option to enable all sub-projects when a project is enabled.
* Deselect all projects
<img class="image_resized op-uc-image op-uc-image_inline" style="width:295px;" src="/api/v3/attachments/415033/content">
<br>
## Project selector to activate e.g. storages in multiple projects at once
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
**Functionality**
* Shows all projects available to the user in a hierarchical structure
* User can add projects one by one or include all sub-projects
* Projects that already have this storage activated are disabled
<img class="image_resized op-uc-image op-uc-image_inline" style="width:511px;" src="/api/v3/attachments/415096/content">
##
## File selector
User can choose one or more files to attach as file links to a work package.
**Functionality**
* Shows contents of a folder (sub-folders and files)
* Has breadcrumb for navigation
* User can select one or multiple items
* Shows number of selected items
* Clear selection
<br>
<img class="image_resized op-uc-image op-uc-image_inline" style="width:395px;" src="/api/v3/attachments/415054/content">
##
## Location picker
User can choose a location. Used to define the location (when having for example a manual project folder.
**Functionality**
* Shows contents of a folder (sub-folders and files) Nextcloud instance connected)
* Has breadcrumb for navigation
* User can select a location
* User can create new folder
<img class="image_resized op-uc-image op-uc-image_inline" style="width:465px;" src="/api/v3/attachments/415058/content">
##
## Selector for custom Hierachy Custom field of type Hierarchy
A user wants to select one or more items of a hierarchy.
* Work package table
<img class="image_resized op-uc-image op-uc-image_inline" style="width:316px;" src="/api/v3/attachments/415073/content">
* Work package details view
<img class="image_resized op-uc-image op-uc-image_inline" style="width:394px;" src="/api/v3/attachments/415068/content">
* Project attribute of type Hierarchy - not implemented yet
<img class="image_resized op-uc-image op-uc-image_inline" style="width:418px;" src="/api/v3/attachments/415076/content">
* Work package field in copy form - not implemented yet
<img class="image_resized op-uc-image op-uc-image_inline" style="width:382px;" src="/api/v3/attachments/415075/content">
<br> selector
## Change parent for custom field of type Hierarchy items - Not implemented yet
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.
<img class="image_resized op-uc-image op-uc-image_inline" style="width:509px;" src="/api/v3/attachments/415106/content">
<br>
# Visuals
TBD
* 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**
* \[OPEN\] 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
* \[OPEN\] should that fire an event so that we can react to it?
* clicking anywhere else will activate the node
* \[OPEN\] What does "activating" mean? Send a request to an href?
* 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 tow 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.
<br>
## Out of scope
* \[OPEN\] 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. 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.
<br>
##
# **Open questions**
* Do we want to get it merged upstream?
* Do we need own visuals or is the component definition of Primer enough?
* 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/)
# **Potential usage**
<br>
##
## Project selector
The project selector allows the user to switch between projects. It's part of the topbar and always accessible to the user
**Functionality**
* Shows all projects available to the user in a hierarchical structure
* The active project is highlighted visually
* Items in the project selector are links
* On click the user is navigated to the selected project
* Shows an icon for favorite projects
* Allows searching for project names
* Allow filter for favorites
<img class="image_resized op-uc-image op-uc-image_inline" style="width:269px;" src="/api/v3/attachments/414876/content">
##
## Include projects
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.
**Functionality**
* Shows all projects available to the user in a hierarchical structure
* User can enable one or more projects (checkbox)
* "Only selected"-filter to allow user an overview of the selected items
* "Include all sub-projects"-option to enable all sub-projects when a project is enabled.
* Deselect all projects
<img class="image_resized op-uc-image op-uc-image_inline" style="width:295px;" src="/api/v3/attachments/415033/content">
<br>
## Project selector to activate e.g. storages in multiple projects at once
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
**Functionality**
* Shows all projects available to the user in a hierarchical structure
* User can add projects one by one or include all sub-projects
* Projects that already have this storage activated are disabled
<img class="image_resized op-uc-image op-uc-image_inline" style="width:511px;" src="/api/v3/attachments/415096/content">
##
## File selector
User can choose one or more files to attach as file links to a work package.
**Functionality**
* Shows contents of a folder (sub-folders and files)
* Has breadcrumb for navigation
* User can select one or multiple items
* Shows number of selected items
* Clear selection
<br>
<img class="image_resized op-uc-image op-uc-image_inline" style="width:395px;" src="/api/v3/attachments/415054/content">
##
## Location picker
User can choose a location. Used to define the location
**Functionality**
* Shows contents of a folder (sub-folders and files)
* Has breadcrumb for navigation
* User can select a location
* User can create new folder
<img class="image_resized op-uc-image op-uc-image_inline" style="width:465px;" src="/api/v3/attachments/415058/content">
##
## Selector for custom
A user wants to select one or more items of a hierarchy.
* Work package table
<img class="image_resized op-uc-image op-uc-image_inline" style="width:316px;" src="/api/v3/attachments/415073/content">
* Work package details view
<img class="image_resized op-uc-image op-uc-image_inline" style="width:394px;" src="/api/v3/attachments/415068/content">
* Project attribute of type Hierarchy - not implemented yet
<img class="image_resized op-uc-image op-uc-image_inline" style="width:418px;" src="/api/v3/attachments/415076/content">
* Work package field in copy form - not implemented yet
<img class="image_resized op-uc-image op-uc-image_inline" style="width:382px;" src="/api/v3/attachments/415075/content">
<br>
## Change parent for custom field of type Hierarchy items - Not implemented yet
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.
<img class="image_resized op-uc-image op-uc-image_inline" style="width:509px;" src="/api/v3/attachments/415106/content">
<br>
# Visuals
TBD