Skip to content

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

[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.erb
new file mode 100644
index 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
+&lt;%= render(Primer::OpenProject::FilterableTreeView.new) do |tree_view| %&gt;
+ <%# remove this line to prevent that the default modes "All" and "Selected" are shown %>
+ &lt;% tree_view.with_default_filter_modes %&gt;
+ &lt;% tree_view.with_filter_mode(name: "Custom third option") %&gt;
+&lt;% 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.erb
similarity index 91%
rename from lookbook/docs/components/tree-view.md.erb
rename to lookbook/docs/components/tree-view/tree-view.md.erb
index 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.rb
new file mode 100644
index 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
+end
diff --git a/lookbook/previews/open_project/common/tree_view_preview.rb b/lookbook/previews/open_project/common/tree_view_preview.rb
index 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] toggle
def 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")