openproject-primer_view_components 0.70.4 → 0.71.0

data/app/components/primer/open_project/filterable_tree_view.js

@@ -0,0 +1,409 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _FilterableTreeViewElement_instances, _FilterableTreeViewElement_filterFn, _FilterableTreeViewElement_abortController, _FilterableTreeViewElement_stateMap, _FilterableTreeViewElement_handleTreeViewEvent, _FilterableTreeViewElement_handleTreeViewNodeChecked, _FilterableTreeViewElement_restoreNodeState, _FilterableTreeViewElement_handleFilterModeEvent, _FilterableTreeViewElement_handleFilterInputEvent, _FilterableTreeViewElement_handleIncludeSubItemsCheckBoxEvent, _FilterableTreeViewElement_includeSubItems, _FilterableTreeViewElement_includeSubItemsUnder, _FilterableTreeViewElement_restoreAllNodeStates, _FilterableTreeViewElement_applyFilterOptions, _FilterableTreeViewElement_applyHighlights, _FilterableTreeViewElement_applyManualHighlights, _FilterableTreeViewElement_removeHighlights;
+import { controller, target } from '@github/catalyst';
+import { TreeViewElement } from './tree_view/tree_view';
+import { TreeViewSubTreeNodeElement } from './tree_view/tree_view_sub_tree_node_element';
+let FilterableTreeViewElement = class FilterableTreeViewElement extends HTMLElement {
+    constructor() {
+        super(...arguments);
+        _FilterableTreeViewElement_instances.add(this);
+        _FilterableTreeViewElement_filterFn.set(this, void 0);
+        _FilterableTreeViewElement_abortController.set(this, void 0);
+        _FilterableTreeViewElement_stateMap.set(this, new Map());
+    }
+    connectedCallback() {
+        const { signal } = (__classPrivateFieldSet(this, _FilterableTreeViewElement_abortController, new AbortController(), "f"));
+        this.addEventListener('treeViewNodeChecked', this, { signal });
+        this.addEventListener('itemActivated', this, { signal });
+        this.addEventListener('input', this, { signal });
+    }
+    disconnectedCallback() {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_abortController, "f").abort();
+    }
+    handleEvent(event) {
+        if (event.target === this.filterModeControl) {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_handleFilterModeEvent).call(this, event);
+        }
+        else if (event.target === this.filterInput) {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_handleFilterInputEvent).call(this, event);
+        }
+        else if (event.target === this.includeSubItemsCheckBox) {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_handleIncludeSubItemsCheckBoxEvent).call(this, event);
+        }
+        else if (event.target instanceof TreeViewElement || event.target instanceof TreeViewSubTreeNodeElement) {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_handleTreeViewEvent).call(this, event);
+        }
+    }
+    get filterModeControl() {
+        return this.filterModeControlList.closest('segmented-control');
+    }
+    get treeView() {
+        return this.treeViewList.closest('tree-view');
+    }
+    set filterFn(newFn) {
+        __classPrivateFieldSet(this, _FilterableTreeViewElement_filterFn, newFn, "f");
+    }
+    get filterFn() {
+        if (__classPrivateFieldGet(this, _FilterableTreeViewElement_filterFn, "f")) {
+            return __classPrivateFieldGet(this, _FilterableTreeViewElement_filterFn, "f");
+        }
+        else {
+            return this.defaultFilterFn;
+        }
+    }
+    defaultFilterFn(node, query, filterMode) {
+        const ranges = [];
+        if (query.length > 0) {
+            const lowercaseQuery = query.toLowerCase();
+            const treeWalker = document.createTreeWalker(node, NodeFilter.SHOW_TEXT);
+            let currentNode = treeWalker.nextNode();
+            while (currentNode) {
+                const lowercaseNodeText = currentNode.textContent?.toLocaleLowerCase() || '';
+                let startIndex = 0;
+                while (startIndex < lowercaseNodeText.length) {
+                    const index = lowercaseNodeText.indexOf(lowercaseQuery, startIndex);
+                    if (index === -1)
+                        break;
+                    const range = new Range();
+                    range.setStart(currentNode, index);
+                    range.setEnd(currentNode, index + lowercaseQuery.length);
+                    ranges.push(range);
+                    startIndex = index + lowercaseQuery.length;
+                }
+                currentNode = treeWalker.nextNode();
+            }
+        }
+        if (ranges.length === 0 && query.length > 0) {
+            return null;
+        }
+        switch (filterMode) {
+            case 'selected': {
+                // Only match nodes that have been checked
+                if (this.treeView?.getNodeCheckedValue(node) !== 'false') {
+                    return ranges;
+                }
+                break;
+            }
+            case 'all': {
+                return ranges;
+            }
+        }
+        return null;
+    }
+    get filterMode() {
+        const current = this.filterModeControl?.current;
+        if (current) {
+            return current.getAttribute('data-name');
+        }
+        else {
+            return null;
+        }
+    }
+    get queryString() {
+        return this.filterInput.value;
+    }
+    // Iterates over the nodes in the given sub-tree in depth-first order, yielding a list of leaf nodes
+    // and an array of ancestor nodes. It uses the aria-level information attached to each node to determine
+    // the next level of the tree to visit.
+    *eachDescendantDepthFirst(node, level, ancestry) {
+        for (const subTreeItem of node.querySelectorAll(`[role=treeitem][data-node-type='sub-tree'][aria-level='${level}']`)) {
+            const subTree = subTreeItem.closest('tree-view-sub-tree-node');
+            yield* this.eachDescendantDepthFirst(subTree, level + 1, [...ancestry, subTree]);
+        }
+        const leafNodes = node.querySelectorAll(`[role=treeitem][data-node-type='leaf'][aria-level='${level}']`);
+        yield [leafNodes, ancestry];
+    }
+    // Yields only the shallowest (i.e. lowest depth) sub-tree nodes that are checked, i.e. does not
+    // visit a sub-tree's children if that sub-tree is checked.
+    *eachShallowestCheckedSubTree(root) {
+        if (this.treeView?.getNodeCheckedValue(root.node) === 'true') {
+            yield root;
+            return; // do not descend further
+        }
+        for (const childSubTree of root.eachDirectDescendantSubTreeNode()) {
+            yield* this.eachShallowestCheckedSubTree(childSubTree);
+        }
+    }
+};
+_FilterableTreeViewElement_filterFn = new WeakMap();
+_FilterableTreeViewElement_abortController = new WeakMap();
+_FilterableTreeViewElement_stateMap = new WeakMap();
+_FilterableTreeViewElement_instances = new WeakSet();
+_FilterableTreeViewElement_handleTreeViewEvent = function _FilterableTreeViewElement_handleTreeViewEvent(origEvent) {
+    const event = origEvent;
+    // NOTE: This event only fires if someone actually activates the check mark, i.e. does not fire
+    // when calling this.treeView.setNodeCheckedValue.
+    switch (origEvent.type) {
+        case 'treeViewNodeChecked':
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_handleTreeViewNodeChecked).call(this, event);
+            break;
+    }
+};
+_FilterableTreeViewElement_handleTreeViewNodeChecked = function _FilterableTreeViewElement_handleTreeViewNodeChecked(event) {
+    if (!this.treeView)
+        return;
+    if (!this.includeSubItemsCheckBox.checked)
+        return;
+    // Although multiple nodes may have been checked (eg. if the TreeView is in descendants mode),
+    // the one that actually received the click, i.e. the local root the user checked, is the first
+    // entry. We only care about sub-tree nodes because checking them affects all leaf nodes, so
+    // there's no need to check or uncheck individual leaves.
+    const nodeInfo = event.detail[0];
+    if (this.treeView.getNodeType(nodeInfo.node) !== 'sub-tree')
+        return;
+    const subTree = nodeInfo.node.closest('tree-view-sub-tree-node');
+    if (nodeInfo.checkedValue === 'false') {
+        // If the sub-tree has been unchecked, restore whatever state they were in before. We don't
+        // need to explicitly enable the sub-tree because restoring will handle setting the enabled
+        // or disabled state per-node.
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_restoreNodeState).call(this, subTree);
+    }
+    else {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_includeSubItemsUnder).call(this, subTree);
+    }
+};
+_FilterableTreeViewElement_restoreNodeState = function _FilterableTreeViewElement_restoreNodeState(subTree) {
+    if (!this.treeView)
+        return;
+    if (!__classPrivateFieldGet(this, _FilterableTreeViewElement_stateMap, "f").has(subTree))
+        return;
+    const descendantStates = __classPrivateFieldGet(this, _FilterableTreeViewElement_stateMap, "f").get(subTree);
+    for (const [element, state] of descendantStates.entries()) {
+        let node = element;
+        if (element instanceof TreeViewSubTreeNodeElement) {
+            node = element.node;
+        }
+        this.treeView.setNodeCheckedValue(node, state.checked ? 'true' : 'false');
+        this.treeView.setNodeDisabledValue(node, state.disabled);
+    }
+    // once node state has been restored, there's no reason to keep it around - it will be saved
+    // again if this sub-tree gets checked
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_stateMap, "f").delete(subTree);
+};
+_FilterableTreeViewElement_handleFilterModeEvent = function _FilterableTreeViewElement_handleFilterModeEvent(event) {
+    if (event.type !== 'itemActivated')
+        return;
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+};
+_FilterableTreeViewElement_handleFilterInputEvent = function _FilterableTreeViewElement_handleFilterInputEvent(event) {
+    if (event.type !== 'input')
+        return;
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+};
+_FilterableTreeViewElement_handleIncludeSubItemsCheckBoxEvent = function _FilterableTreeViewElement_handleIncludeSubItemsCheckBoxEvent(event) {
+    if (!this.treeView)
+        return;
+    if (event.type !== 'input')
+        return;
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+    if (this.includeSubItemsCheckBox.checked) {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_includeSubItems).call(this);
+    }
+    else {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_restoreAllNodeStates).call(this);
+    }
+};
+_FilterableTreeViewElement_includeSubItems = function _FilterableTreeViewElement_includeSubItems() {
+    if (!this.treeView)
+        return;
+    for (const subTree of this.treeView.rootSubTreeNodes()) {
+        for (const checkedSubTree of this.eachShallowestCheckedSubTree(subTree)) {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_includeSubItemsUnder).call(this, checkedSubTree);
+        }
+    }
+};
+_FilterableTreeViewElement_includeSubItemsUnder = function _FilterableTreeViewElement_includeSubItemsUnder(subTree) {
+    if (!this.treeView)
+        return;
+    const descendantStates = new Map();
+    for (const node of subTree.eachDescendantNode()) {
+        descendantStates.set(node, {
+            checked: this.treeView.getNodeCheckedValue(node) === 'true',
+            disabled: this.treeView.getNodeDisabledValue(node),
+        });
+        this.treeView.setNodeCheckedValue(node, 'true');
+        this.treeView.setNodeDisabledValue(node, true);
+    }
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_stateMap, "f").set(subTree, descendantStates);
+};
+_FilterableTreeViewElement_restoreAllNodeStates = function _FilterableTreeViewElement_restoreAllNodeStates() {
+    for (const subTree of __classPrivateFieldGet(this, _FilterableTreeViewElement_stateMap, "f").keys()) {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_restoreNodeState).call(this, subTree);
+    }
+};
+_FilterableTreeViewElement_applyFilterOptions = function _FilterableTreeViewElement_applyFilterOptions() {
+    if (!this.treeView)
+        return;
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_removeHighlights).call(this);
+    const query = this.queryString;
+    const mode = this.filterMode || undefined;
+    const generation = window.crypto.randomUUID();
+    const filterRangesCache = new Map();
+    const expandAncestors = (...ancestors) => {
+        for (const ancestor of ancestors) {
+            ancestor.expand();
+            ancestor.removeAttribute('hidden');
+            ancestor.setAttribute('data-generation', generation);
+            if (cachedFilterFn(ancestor.node, query, mode)) {
+                ancestor.node.removeAttribute('aria-disabled');
+            }
+            else {
+                ancestor.node.setAttribute('aria-disabled', 'true');
+            }
+        }
+    };
+    // This function is called in the loop below for both leaf  nodes and sub-tree nodes to determine
+    // if they match, and subsequently whether or not to hide them. However, it serves a secondary purpose
+    // as well in that it remembers the range information returned by the filter function so it can be
+    // used to highlight matching ranges later.
+    const cachedFilterFn = (node, queryStr, filterMode) => {
+        if (!filterRangesCache.has(node)) {
+            filterRangesCache.set(node, this.filterFn(node, queryStr, filterMode));
+        }
+        return filterRangesCache.get(node) !== null;
+    };
+    /* We iterate depth-first here in order to be able to examine the most deeply nested leaf nodes
+     * before their parents. This enables us to easily hide the parent if none of its children match.
+     * To handle expanding and collapsing ancestors, the algorithm iterates over the provided ancestor
+     * chain, expanding "upwards" to the root.
+     *
+     * Using this technique does mean it's possible to iterate over the same ancestor multiple times.
+     * For example, consider two nodes that share the same ancestor. Node A contains matching children,
+     * but node B does not. The algorithm below will visit node A first and expand it and all its
+     * ancestors. Next, the algorithm will visit node B and collapse all its ancestors. To avoid this,
+     * the algorithm attaches a random "generation ID" to each node visited. If the generation ID
+     * matches when visiting a particular node, we know that node has already been visited and should
+     * not be hidden or collapsed.
+     */
+    for (const [leafNodes, ancestors] of this.eachDescendantDepthFirst(this.treeViewList, 1, [])) {
+        const parent = ancestors[ancestors.length - 1];
+        let atLeastOneLeafMatches = false;
+        for (const leafNode of leafNodes) {
+            if (cachedFilterFn(leafNode, query, mode)) {
+                leafNode.closest('li')?.removeAttribute('hidden');
+                atLeastOneLeafMatches = true;
+            }
+            else {
+                leafNode.closest('li')?.setAttribute('hidden', 'hidden');
+            }
+        }
+        if (atLeastOneLeafMatches) {
+            expandAncestors(...ancestors);
+        }
+        else {
+            if (parent) {
+                if (cachedFilterFn(parent.node, query, mode)) {
+                    // sub-tree matched, so expand ancestors
+                    expandAncestors(...ancestors);
+                }
+                else {
+                    // this node has already been marked by the current generation and is therefore
+                    // a shared ancestor - don't collapse or hide it
+                    if (parent.getAttribute('data-generation') !== generation) {
+                        parent.collapse();
+                        parent.setAttribute('hidden', 'hidden');
+                    }
+                }
+            }
+        }
+    }
+    // convert range map into a 1-dimensional array with no nulls so it can be given to
+    // #applyHighlights (and therefore CSS.highlights.set) more easily
+    const allRanges = Array.from(filterRangesCache.values())
+        .flat()
+        .filter(r => r !== null);
+    if (allRanges.length === 0 && query.length > 0) {
+        this.treeViewList.setAttribute('hidden', 'hidden');
+        this.noResultsMessage.removeAttribute('hidden');
+    }
+    else {
+        this.treeViewList.removeAttribute('hidden');
+        this.noResultsMessage.setAttribute('hidden', 'hidden');
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyHighlights).call(this, allRanges);
+    }
+};
+_FilterableTreeViewElement_applyHighlights = function _FilterableTreeViewElement_applyHighlights(ranges) {
+    // Attempt to use the new-ish custom highlight API:
+    // https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API
+    if (CSS.highlights) {
+        CSS.highlights.set('primer-filterable-tree-view-search-results', new Highlight(...ranges));
+    }
+    else {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyManualHighlights).call(this, ranges);
+    }
+};
+_FilterableTreeViewElement_applyManualHighlights = function _FilterableTreeViewElement_applyManualHighlights(ranges) {
+    const textNode = ranges[0].startContainer;
+    const parent = textNode.parentNode;
+    const originalText = textNode.textContent;
+    const fragments = [];
+    let lastIndex = 0;
+    for (const { startOffset, endOffset } of ranges) {
+        // text before the highlight
+        if (startOffset > lastIndex) {
+            fragments.push(document.createTextNode(originalText.slice(lastIndex, startOffset)));
+        }
+        // highlighted text
+        const mark = document.createElement('mark');
+        mark.textContent = originalText.slice(startOffset, endOffset);
+        fragments.push(mark);
+        lastIndex = endOffset;
+    }
+    // remaining text after the last highlight
+    if (lastIndex < originalText.length) {
+        fragments.push(document.createTextNode(originalText.slice(lastIndex)));
+    }
+    // replace original text node with our text + <mark> elements
+    for (const frag of fragments.reverse()) {
+        parent.insertBefore(frag, textNode.nextSibling);
+    }
+    parent.removeChild(textNode);
+};
+_FilterableTreeViewElement_removeHighlights = function _FilterableTreeViewElement_removeHighlights() {
+    // quick-and-dirty way of ignoring any existing <mark> elements and restoring
+    // the original text
+    for (const mark of this.querySelectorAll('mark')) {
+        if (!mark.parentElement)
+            continue;
+        mark.parentElement.replaceChildren(mark.parentElement.textContent);
+    }
+};
+__decorate([
+    target
+], FilterableTreeViewElement.prototype, "filterInput", void 0);
+__decorate([
+    target
+], FilterableTreeViewElement.prototype, "filterModeControlList", void 0);
+__decorate([
+    target
+], FilterableTreeViewElement.prototype, "treeViewList", void 0);
+__decorate([
+    target
+], FilterableTreeViewElement.prototype, "noResultsMessage", void 0);
+__decorate([
+    target
+], FilterableTreeViewElement.prototype, "includeSubItemsCheckBox", void 0);
+FilterableTreeViewElement = __decorate([
+    controller
+], FilterableTreeViewElement);
+export { FilterableTreeViewElement };
+if (!window.customElements.get('filterable-tree-view')) {
+    window.FilterableTreeViewElement = FilterableTreeViewElement;
+    window.customElements.define('filterable-tree-view', FilterableTreeViewElement);
+}

data/app/components/primer/open_project/filterable_tree_view.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Primer
+  module OpenProject
+    # A TreeView and associated filter controls for searching nested hierarchies.
+    #
+    # ## Filter controls
+    #
+    # `FilterableTreeView`s can be filtered using two controls, both present in the toolbar above the tree:
+    #
+    # 1. A free-form query string from a text input field.
+    # 2. A `SegmentedControl` with two options (by default):
+    #    1. The "Selected" option causes the component to only show checked nodes, provided they also satisfy the other
+    #       filter criteria described here.
+    #    2. The "All" option causes the component to show all nodes, provided they also satisfy the other filter
+    #       criteria described here.
+    #
+    # ## Custom filter modes
+    #
+    # 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 adding the default modes %>
+    #   <% tree_view.with_default_filter_modes %>
+    #   <% tree_view.with_filter_mode(name: "Custom", system_arguments)
+    # <% end %>
+    # ```
+    #
+    # ## Filter behavior
+    #
+    # By default, matching node text is identified by looking for an exact substring match, operating on a lowercased
+    # version of both the query string and the node text. For more information, and to provide a customized filter
+    # function, please see the section titled "Customizing the filter function" below.
+    #
+    # Nodes that match the filter appear as normal; nodes that do not match are presented as follows:
+    #
+    # 1. Leaf nodes are hidden.
+    # 2. Sub-tree nodes with no matching children are hidden.
+    # 3. Sub-tree nodes with at least one matching child are disabled but still visible.
+    #
+    # ## Checking behavior
+    #
+    # By default, checking a node in a `FilterableTreeView` checks only that node (i.e. no child nodes are checked).
+    # To aide in checking children in deeply nested or highly populated hierarchies, a third control exists in the
+    # toolbar: the "Include sub-items" check box. If this feature is turned on, checking sub-tree nodes causes all
+    # children, both leaf and sub-tree nodes, to also be checked recursively. Moreover, turning this feature on will
+    # cause the children of any previously checked nodes to be checked recursively. Unchecking a node while in
+    # "Include sub-items" mode will restore that sub-tree and all its children to their previously checked state, so as
+    # not to permanently override a user's selections. Unchecking the "Include sub-items" check box has a similar effect,
+    # i.e. restores all previous user selections under currently checked sub-trees.
+    #
+    # ## JavaScript API
+    #
+    # `FilterableTreeView` does not yet have an extensive JavaScript API, but this may change in the future as the
+    # component is further developed to fit additional use-cases.
+    #
+    # ### Customizing the 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.
+    #
+    # ### Events
+    #
+    # Currently `FilterableTreeView` does not emit any events aside from the events already emitted by the `TreeView`
+    # component.
+    class FilterableTreeView < Primer::Component
+      delegate :with_leaf, :with_sub_tree, to: :@tree_view
+
+      DEFAULT_FILTER_INPUT_ARGUMENTS = {
+        name: :filter,
+        label: I18n.t(:button_filter),
+        type: :search,
+        leading_visual: { icon: :search },
+        visually_hide_label: true,
+        show_clear_button: true,
+      }
+
+      DEFAULT_FILTER_INPUT_ARGUMENTS.freeze
+
+      DEFAULT_FILTER_MODE_CONTROL_ARGUMENTS = {
+        aria: {
+          label: I18n.t("filterable_tree_view.filter_mode.label")
+        }
+      }
+
+      DEFAULT_FILTER_MODE_CONTROL_ARGUMENTS.freeze
+
+      DEFAULT_INCLUDE_SUB_ITEMS_CHECK_BOX_ARGUMENTS = {
+        label: I18n.t("filterable_tree_view.include_sub_items"),
+        name: :include_sub_items
+      }
+
+      DEFAULT_INCLUDE_SUB_ITEMS_CHECK_BOX_ARGUMENTS.freeze
+
+      DEFAULT_FILTER_MODES = {
+        all: {
+          label: I18n.t("filterable_tree_view.filter_mode.all"),
+          selected: true,
+        },
+
+        selected: {
+          label: I18n.t("filterable_tree_view.filter_mode.selected"),
+        }
+      }
+
+      DEFAULT_FILTER_MODES.freeze
+
+      DEFAULT_NO_RESULTS_NODE_ARGUMENTS = {
+        label: I18n.t("filterable_tree_view.no_results_text")
+      }
+
+      DEFAULT_NO_RESULTS_NODE_ARGUMENTS.freeze
+
+      # @param tree_view_arguments [Hash] Arguments that will be passed to the underlying <%= link_to_component(Primer::OpenProject::TreeView) %> component.
+      # @param form_arguments [Hash] Form arguments that will be passed to the underlying <%= link_to_component(Primer::OpenProject::TreeView) %> component. These arguments allow the selections made within a `FilterableTreeView` to be submitted to the server as part of a Rails form. Pass the `builder:` and `name:` options to this hash. `builder:` should be an instance of `ActionView::Helpers::FormBuilder`, which are created by the standard Rails `#form_with` and `#form_for` helpers. The `name:` option is the desired name of the field that will be included in the params sent to the server on form submission.
+      # @param filter_input_arguments [Hash] Arguments that will be passed to the <%= link_to_component(Primer::Alpha::TextField) %> component.
+      # @param filter_mode_control_arguments [Hash] Arguments that will be passed to the <%= link_to_component(Primer::Alpha::SegmentedControl) %> component.
+      # @param include_sub_items_check_box_arguments [Hash] Arguments that will be passed to the <%= link_to_component(Primer::Alpha::CheckBox) %> component.
+      # @param no_results_node_arguments [Hash] Arguments that will be passed to a <%= link_to_component(Primer::OpenProject::TreeView::LeafNode) %> component that appears when no items match the filter criteria.
+      def initialize(
+        tree_view_arguments: {},
+        form_arguments: {},
+        filter_input_arguments: DEFAULT_FILTER_INPUT_ARGUMENTS.dup,
+        filter_mode_control_arguments: DEFAULT_FILTER_MODE_CONTROL_ARGUMENTS.dup,
+        include_sub_items_check_box_arguments: DEFAULT_INCLUDE_SUB_ITEMS_CHECK_BOX_ARGUMENTS.dup,
+        no_results_node_arguments: DEFAULT_NO_RESULTS_NODE_ARGUMENTS.dup,
+        **system_arguments
+      )
+        tree_view_arguments[:data] = merge_data(
+          tree_view_arguments, {
+            data: { target: "filterable-tree-view.treeViewList" }
+          }
+        )
+
+        @tree_view = Primer::OpenProject::TreeView.new(
+          form_arguments: form_arguments,
+          **tree_view_arguments
+        )
+
+        filter_input_arguments[:data] = merge_data(
+          filter_input_arguments, {
+            data: { target: "filterable-tree-view.filterInput" }
+          }
+        )
+
+        @filter_input = Primer::Alpha::TextField.new(**filter_input_arguments)
+
+        filter_mode_control_arguments[:data] = merge_data(
+          filter_mode_control_arguments, {
+            data: { target: "filterable-tree-view.filterModeControlList" }
+          }
+        )
+
+        @filter_mode_control = Primer::Alpha::SegmentedControl.new(**filter_mode_control_arguments)
+
+        include_sub_items_check_box_arguments[:data] = merge_data(
+          include_sub_items_check_box_arguments, {
+            data: { target: "filterable-tree-view.includeSubItemsCheckBox" }
+          }
+        )
+
+        @include_sub_items_check_box = Primer::Alpha::CheckBox.new(**include_sub_items_check_box_arguments)
+
+        @system_arguments = deny_tag_argument(**system_arguments)
+        @system_arguments[:tag] = :"filterable-tree-view"
+
+        @no_results_node_arguments = no_results_node_arguments
+      end
+
+      def with_default_filter_modes
+        DEFAULT_FILTER_MODES.each do |name, system_arguments|
+          with_filter_mode(name: name, **system_arguments)
+        end
+      end
+
+      def with_filter_mode(name:, **system_arguments)
+        system_arguments[:data] = merge_data(
+          system_arguments, {
+            data: { name: name }
+          }
+        )
+
+        @filter_mode_control.with_item(**system_arguments)
+      end
+
+      def with_sub_tree(**system_arguments, &block)
+        @tree_view.with_sub_tree(
+          sub_tree_component_klass: SubTree,
+          **system_arguments,
+          select_variant: :multiple,
+          select_strategy: :self,
+          &block
+        )
+      end
+
+      def with_leaf(**system_arguments, &block)
+        @tree_view.with_leaf(
+          **system_arguments,
+          select_variant: :multiple,
+          &block
+        )
+      end
+
+      private
+
+      def before_render
+        content
+
+        if @filter_mode_control.items.empty?
+          with_default_filter_modes
+        end
+      end
+    end
+  end
+end