OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub
Ruby agile-developmentangularbcfboardsbug-trackerganttgantt-chartifcissue-trackerjira-alternativekanbanopenprojectproduct-managementproject-managementproject-planningroadmaprubyscrumtimelineworkflows
[64608] Document FilterableTreeView in Lookbook (#20300)
Henriette Dargeb82bbce7ef21
diff --git a/lookbook/docs/components/tree-view/filterable-tree-view.md.erb b/lookbook/docs/components/tree-view/filterable-tree-view.md.erbnew file mode 100644index 00000000000..44ede0b3060--- /dev/null+++ b/lookbook/docs/components/tree-view/filterable-tree-view.md.erb@@ -0,0 +1,159 @@+The `FilterableTreeView` is an extended `TreeView` implementation for scenarios where filtering and managing selections within a large tree structure is required. It extends the `TreeView` by introducing filtering and view control options, making it particularly useful for workflows that require selection of nodes from hierarchies.++## Overview++<%= embed OpenProject::Common::FilterableTreeViewPreview, :default %>++## Anatomy++The `FilterableTreeView` consists of the following UI elements:++1. **Segmented Control**: Allows toggling between viewing all items and only selected ones. Labels and filter logic are configurable+2. **Search Field**: A text field with a leading search icon used to filter the tree content via text+3. **Checkbox "Include sub-nodes"**: When enabled, checking a parent node will also include its descendants+4. **TreeView**: An embedded `TreeView` component with multi-select enabled and static loading strategy++## Features++### TreeView behavior++The embedded `TreeView` behaves according to its specification, with a few notable constraints and extensions:++- **Loading strategy**: Only supports `static` loading.+- **Multi-select support**: Enabled by default.++For details on the `TreeView` itself, refer to the [TreeView documentation](./tree_view).++---++### Search functionality++The search field enables text-based filtering of the tree.++**Behavior:**++- Partial matches are supported (e.g., `"par"` matches `"partial"`).+- If a **leaf** matches but its ancestors do not, the full hierarchy for that leaf is shown.+- Non-matching nodes in a visible path are **greyed out and disabled** (not clickable).+- Matching characters in results are **highlighted**.++**Multi-select considerations:**++- Selections made **before** filtering are preserved, even if they are not visible in the current filter.+- If **"Include sub-nodes"** is enabled:+ - Selecting a parent will select all its descendants, even if they’re hidden due to filtering.+- On form submission, **all selected items** are submitted, including those currently not shown.++---++### Segmented control++A segmented control toggles the visible tree scope:++- **All**: Shows the full tree (default view).+- **Selected**: Shows only selected items and their ancestors.++**Behavior in "Selected" mode:**++- The full path to selected items is shown; non-selected ancestors are **greyed out and disabled**.+- Checking parents will still select all descendants (if "Include sub-nodes" is enabled), not only the visible ones.+- Unchecked items remain visible until the form is submitted or manually reloaded.++**Custom filter logic**++The labels as well as the logic for the segmented control are configurable. For details, please check the technical notes section at the bottom.++---++### "Include sub-nodes" checkbox++This checkbox controls whether checking a parent node selects all of its children.++**Behavior:**++- When **checked**:+ - Checking a parent automatically selects and disables all descendants.+ - Unchecking a parent unchecks all children as well.+- When **unchecked again**:+ - The component does **remember** how a selection was made (manual vs. auto). Previously auto-selected descendants get unselected while manually selected items remain selected.++---++## Best practices++**Do:**++- Use this component when users need to **search and selectively choose** items in a tree.+- Enable **"Include sub-nodes"** if selecting a parent should automatically include all descendants.++**Don't:**++- Don’t use `FilterableTreeView` with a dynamic loading strategy – only static loading is supported.+- Don't use the component for simple hierarchies which don't need filtering; instead use `TreeView`.++## Used in++- (Planned) In the admin settings as a way of selecting projects in which to enable a certain object, like a project attribute, type or custom field.++## Examples++See detailed examples in the [preview section](../../../inspect/primer/open_project/filterable_tree_view/default).++<%= embed OpenProject::Common::FilterableTreeViewPreview, :default, panels: %i[params source] %>++## Technical notes++### Custom select control++In addition to the default filter modes of `'all'` and `'selected'` described above, `FilterableTreeView` supports+adding custom filter modes. Adding a filter mode will cause its label to appear in the `SegmentedControl` in the+toolbar, and will be passed as the third argument to the filter function (see below).++Here's how to add a custom filter mode in addition to the default ones:++```erb+<%= render(Primer::OpenProject::FilterableTreeView.new) do |tree_view| %>+ <%# remove this line to prevent that the default modes "All" and "Selected" are shown %>+ <% tree_view.with_default_filter_modes %>+ <% tree_view.with_filter_mode(name: "Custom third option") %>+<% end %>+```++#### Custom filter function++The filter function can be customized by setting the value of the `filterFn` property to a function with the+following signature:++```typescript+export type FilterFn = (node:HTMLElement, query:string, filterMode?:string) => Range[]|null+```++This function will be called once for each node in the tree every time filter controls change (i.e. when the+filter mode or query string are altered). The function is called with the following arguments:++|Argument |Description |+|:-----------|:----------------------------------------------------------------|+|`node` |The HTML node element, i.e. the element with `role=treeitem` set.|+|`query` |The query string. |+|`filterMode`|The filter mode, either `'all'` or `'selected'`. |++The component expects the filter function to return specific values depending on the type of match:++1. No match - return `null`+2. Match but no highlights (eg. when the query string is empty) - return an empty array+3. Match with highlights - return a non-empty array of `Range` objects++##### Example:++```javascript+const filterableTreeView = document.querySelector('filterable-tree-view')+filterableTreeView.filterFn = (node, query, filterMode) => {+ // custom filter implementation here+}+```++You can read about `Range` objects here: https://developer.mozilla.org/en-US/docs/Web/API/Range.++For a complete example demonstrating how to implement a working filter function complete with range highlighting,+see the default filter function available in the `FilterableTreeViewElement` JavaScript class, which is part of+the Primer source code.diff --git a/lookbook/docs/components/tree-view.md.erb b/lookbook/docs/components/tree-view/tree-view.md.erbsimilarity index 91%rename from lookbook/docs/components/tree-view.md.erbrename to lookbook/docs/components/tree-view/tree-view.md.erbindex 375dbe12f2c..02e55ff84a1 100644--- a/lookbook/docs/components/tree-view.md.erb+++ b/lookbook/docs/components/tree-view/tree-view.md.erb@@ -40,11 +40,11 @@ We support two loading strategies:* static (default): All items are loaded when the component is rendered* dynamic: Sub-nodes are loaded from the server as soon as a node is expanded. Please note, that this option is currently not available in combination with the `select_variant: :multiple`.-For more examples have a look [here](../../inspect/primer/open_project/file_tree_view/loading_skeleton).+For more examples have a look [here](../../../inspect/primer/alpha/tree_view/loading_skeleton).### FileTreeView-There is a special component called `FileTreeView` which is a pre-configured `TreeView` for the use case of showing a file hierarchy. For more information, have a look at the [detailed examples here](../../inspect/primer/open_project/file_tree_view/default).+There is a special component called `FileTreeView` which is a pre-configured `TreeView` for the use case of showing a file hierarchy. For more information, have a look at the [detailed examples here](../../../inspect/primer/alpha/file_tree_view/default).<%= embed OpenProject::Common::TreeViewPreview, :file_tree, panels: %i[params source] %>@@ -64,9 +64,9 @@ There is a special component called `FileTreeView` which is a pre-configured `Tr## Examples-For detailed examples have a look at the other [preview examples](../../inspect/primer/open_project/tree_view/playground) of the component.+For detailed examples have a look at the other [preview examples](../../../inspect/primer/alpha/tree_view/playground) of the component.-Please check out also the [playground for the individual items](../../inspect/primer/open_project/tree_view/leaf_node_playground).+Please check out also the [playground for the individual items](../../../inspect/primer/alpha/tree_view/leaf_node_playground).This is an exemplary playground of the `Primer::Alpha::TreeView`.diff --git a/lookbook/previews/open_project/common/filterable_tree_view_preview.rb b/lookbook/previews/open_project/common/filterable_tree_view_preview.rbnew file mode 100644index 00000000000..f3f909bedbf--- /dev/null+++ b/lookbook/previews/open_project/common/filterable_tree_view_preview.rb@@ -0,0 +1,75 @@+# frozen_string_literal: true++#-- copyright+# OpenProject is an open source project management software.+# Copyright (C) the OpenProject GmbH+#+# This program is free software; you can redistribute it and/or+# modify it under the terms of the GNU General Public License version 3.+#+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:+# Copyright (C) 2006-2013 Jean-Philippe Lang+# Copyright (C) 2010-2013 the ChiliProject Team+#+# This program is free software; you can redistribute it and/or+# modify it under the terms of the GNU General Public License+# as published by the Free Software Foundation; either version 2+# of the License, or (at your option) any later version.+#+# This program is distributed in the hope that it will be useful,+# but WITHOUT ANY WARRANTY; without even the implied warranty of+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+# GNU General Public License for more details.+#+# You should have received a copy of the GNU General Public License+# along with this program; if not, write to the Free Software+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.+#+# See COPYRIGHT and LICENSE files for more details.+#++++module OpenProject+ module Common+ # @hidden+ class FilterableTreeViewPreview < Lookbook::Preview+ # @label Default+ # @display min_height 400px+ # @param expanded [Boolean] toggle+ # @param leading_icon [Boolean] toggle+ # @param trailing_icon [Boolean] toggle+ def default(expanded: true, leading_icon: true, trailing_icon: true)+ render(Primer::OpenProject::FilterableTreeView.new) do |component|+ component.with_sub_tree(label: "OpenProject",+ expanded: expanded) do |sub_tree|+ if leading_icon+ sub_tree.with_leading_visual_icons(label: "Foobar") do |icons|+ icons.with_expanded_icon(icon: :heart, color: :accent)+ icons.with_collapsed_icon(icon: :"heart-fill", color: :accent)+ end+ end++ sub_tree.with_leaf(label: "Website")++ sub_tree.with_sub_tree(label: "OpenProject GmbH",+ expanded: expanded) do |sub_tree2|+ sub_tree2.with_leaf(label: "HR")+ sub_tree2.with_leaf(label: "Development", current: true)++ if trailing_icon+ sub_tree2.with_trailing_visual_icon(icon: :"feed-heart")+ end+ end++ sub_tree.with_leaf(label: "Freedom edition")++ sub_tree.with_leaf(label: "Documentation")+ end++ component.with_leaf(label: "External project A")++ component.with_leaf(label: "External project B")+ end+ end+ end+ end+enddiff --git a/lookbook/previews/open_project/common/tree_view_preview.rb b/lookbook/previews/open_project/common/tree_view_preview.rbindex d954b0f7255..aec85c90a84 100644--- a/lookbook/previews/open_project/common/tree_view_preview.rb+++ b/lookbook/previews/open_project/common/tree_view_preview.rb@@ -113,7 +113,7 @@ module OpenProject# @display min_height 200px# @param expanded [Boolean] toggledef file_tree(expanded: true)- render(Primer::OpenProject::FileTreeView.new) do |component|+ render(Primer::Alpha::FileTreeView.new) do |component|component.with_directory(label: "src", expanded: expanded) do |dir|dir.with_trailing_visual_icon(icon: :"diff-modified")