openproject-primer_view_components 0.85.0 → 0.86.1

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

@@ -15,26 +15,57 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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;
+var _FilterableTreeViewElement_instances, _FilterableTreeViewElement_filterFn, _FilterableTreeViewElement_abortController, _FilterableTreeViewElement_stateMap, _FilterableTreeViewElement_debounceTimer, _FilterableTreeViewElement_fetchAbortController, _FilterableTreeViewElement_expansionSnapshot, _FilterableTreeViewElement_selectedModeSnapshot, _FilterableTreeViewElement_checkedNodeIds, _FilterableTreeViewElement_checkedNodeFormPayloads, _FilterableTreeViewElement_isFiltered, _FilterableTreeViewElement_src_get, _FilterableTreeViewElement_isAsyncMode_get, _FilterableTreeViewElement_handleTreeViewEvent, _FilterableTreeViewElement_updateCheckedNodeIds, _FilterableTreeViewElement_handleTreeViewNodeChecked, _FilterableTreeViewElement_restoreNodeState, _FilterableTreeViewElement_handleFilterModeEvent, _FilterableTreeViewElement_undoClientSideFilter, _FilterableTreeViewElement_handleFilterInputEvent, _FilterableTreeViewElement_handleIncludeSubItemsCheckBoxEvent, _FilterableTreeViewElement_includeSubItems, _FilterableTreeViewElement_includeSubItemsUnder, _FilterableTreeViewElement_restoreAllNodeStates, _FilterableTreeViewElement_scheduleAsyncFetch, _FilterableTreeViewElement_fetchAndReplaceTree, _FilterableTreeViewElement_captureExpansionState, _FilterableTreeViewElement_applyExpansionSnapshot, _FilterableTreeViewElement_snapshotExpansionState, _FilterableTreeViewElement_restoreExpansionState, _FilterableTreeViewElement_restoreSelectionState, _FilterableTreeViewElement_expandAllSubTrees, _FilterableTreeViewElement_applyAsyncHighlights, _FilterableTreeViewElement_updateRetainedSelections, _FilterableTreeViewElement_applyFilterOptions, _FilterableTreeViewElement_applyHighlights, _FilterableTreeViewElement_applyManualHighlights, _FilterableTreeViewElement_removeHighlights;
 import { controller, target } from '@github/catalyst';
 import { TreeViewElement } from '../alpha/tree_view/tree_view';
 import { TreeViewSubTreeNodeElement } from '../alpha/tree_view/tree_view_sub_tree_node_element';
+const ASYNC_DEBOUNCE_MS = 300;
 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());
+        _FilterableTreeViewElement_stateMap.set(this, new Map()
+        // Async mode state
+        );
+        // Async mode state
+        _FilterableTreeViewElement_debounceTimer.set(this, null);
+        _FilterableTreeViewElement_fetchAbortController.set(this, null
+        // nodeId → wasExpanded: taken once before the first filter query is entered, cleared when filter is removed
+        );
+        // nodeId → wasExpanded: taken once before the first filter query is entered, cleared when filter is removed
+        _FilterableTreeViewElement_expansionSnapshot.set(this, null
+        // nodeId → wasExpanded: taken before entering "selected" mode, cleared when leaving it
+        );
+        // nodeId → wasExpanded: taken before entering "selected" mode, cleared when leaving it
+        _FilterableTreeViewElement_selectedModeSnapshot.set(this, null
+        // nodeId → checkedValue: persists across tree replacements, updated on every treeViewNodeChecked event
+        );
+        // nodeId → checkedValue: persists across tree replacements, updated on every treeViewNodeChecked event
+        _FilterableTreeViewElement_checkedNodeIds.set(this, new Map()
+        // nodeId → form payload: mirrors #checkedNodeIds but stores the data needed to synthesise a hidden
+        // form input for nodes that are checked but not currently in the DOM (e.g. filtered out).
+        );
+        // nodeId → form payload: mirrors #checkedNodeIds but stores the data needed to synthesise a hidden
+        // form input for nodes that are checked but not currently in the DOM (e.g. filtered out).
+        _FilterableTreeViewElement_checkedNodeFormPayloads.set(this, new Map());
+        _FilterableTreeViewElement_isFiltered.set(this, false);
     }
     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 });
+        if (__classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "a", _FilterableTreeViewElement_isAsyncMode_get)) {
+            void __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_fetchAndReplaceTree).call(this);
+        }
     }
     disconnectedCallback() {
         __classPrivateFieldGet(this, _FilterableTreeViewElement_abortController, "f").abort();
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_fetchAbortController, "f")?.abort();
+        if (__classPrivateFieldGet(this, _FilterableTreeViewElement_debounceTimer, "f") !== null)
+            clearTimeout(__classPrivateFieldGet(this, _FilterableTreeViewElement_debounceTimer, "f"));
     }
     handleEvent(event) {
         if (event.target === this.filterModeControl) {
@@ -56,6 +87,7 @@ let FilterableTreeViewElement = class FilterableTreeViewElement extends HTMLElem
     get treeView() {
         return this.treeViewList.closest('tree-view');
     }
+    // ─── End async mode ─────────────────────────────────────────────────────────
     set filterFn(newFn) {
         __classPrivateFieldSet(this, _FilterableTreeViewElement_filterFn, newFn, "f");
     }
@@ -144,17 +176,63 @@ let FilterableTreeViewElement = class FilterableTreeViewElement extends HTMLElem
 _FilterableTreeViewElement_filterFn = new WeakMap();
 _FilterableTreeViewElement_abortController = new WeakMap();
 _FilterableTreeViewElement_stateMap = new WeakMap();
+_FilterableTreeViewElement_debounceTimer = new WeakMap();
+_FilterableTreeViewElement_fetchAbortController = new WeakMap();
+_FilterableTreeViewElement_expansionSnapshot = new WeakMap();
+_FilterableTreeViewElement_selectedModeSnapshot = new WeakMap();
+_FilterableTreeViewElement_checkedNodeIds = new WeakMap();
+_FilterableTreeViewElement_checkedNodeFormPayloads = new WeakMap();
+_FilterableTreeViewElement_isFiltered = new WeakMap();
 _FilterableTreeViewElement_instances = new WeakSet();
+_FilterableTreeViewElement_src_get = function _FilterableTreeViewElement_src_get() {
+    return this.getAttribute('src');
+};
+_FilterableTreeViewElement_isAsyncMode_get = function _FilterableTreeViewElement_isAsyncMode_get() {
+    return !!__classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "a", _FilterableTreeViewElement_src_get);
+};
 _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':
+            // Always track checked node IDs before delegating, so async replacements can restore selection.
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_updateCheckedNodeIds).call(this, event);
             __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_handleTreeViewNodeChecked).call(this, event);
             break;
     }
 };
+_FilterableTreeViewElement_updateCheckedNodeIds = function _FilterableTreeViewElement_updateCheckedNodeIds(event) {
+    if (!__classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "a", _FilterableTreeViewElement_isAsyncMode_get))
+        return;
+    for (const nodeInfo of event.detail) {
+        const node = nodeInfo.node;
+        const nodeId = node.getAttribute('data-node-id');
+        if (nodeId) {
+            if (nodeInfo.checkedValue === 'false') {
+                __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeIds, "f").delete(nodeId);
+                __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeFormPayloads, "f").delete(nodeId);
+            }
+            else {
+                // In single-select mode, TreeView clears the previous selection internally
+                // (via checkOnlyAtPath) but the treeViewNodeChecked event only contains the
+                // newly selected node. Clear our tracked state so #restoreSelectionState does
+                // not re-check previously selected nodes after a tree replacement.
+                if (node.getAttribute('data-select-variant') === 'single') {
+                    __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeIds, "f").clear();
+                    __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeFormPayloads, "f").clear();
+                }
+                __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeIds, "f").set(nodeId, nodeInfo.checkedValue);
+                const payload = { path: nodeInfo.path };
+                const dataValue = node.getAttribute('data-value');
+                if (dataValue)
+                    payload.value = dataValue;
+                __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeFormPayloads, "f").set(nodeId, payload);
+            }
+        }
+    }
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_updateRetainedSelections).call(this);
+};
 _FilterableTreeViewElement_handleTreeViewNodeChecked = function _FilterableTreeViewElement_handleTreeViewNodeChecked(event) {
     if (!this.treeView)
         return;
@@ -199,19 +277,57 @@ _FilterableTreeViewElement_restoreNodeState = function _FilterableTreeViewElemen
 _FilterableTreeViewElement_handleFilterModeEvent = function _FilterableTreeViewElement_handleFilterModeEvent(event) {
     if (event.type !== 'itemActivated')
         return;
-    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+    if (__classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "a", _FilterableTreeViewElement_isAsyncMode_get)) {
+        if (this.filterMode === 'selected') {
+            // "selected" mode is client-side: snapshot expansion state before the filter collapses nodes,
+            // then apply client-side filter without a server round-trip.
+            __classPrivateFieldSet(this, _FilterableTreeViewElement_selectedModeSnapshot, __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_captureExpansionState).call(this), "f");
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+        }
+        else if (__classPrivateFieldGet(this, _FilterableTreeViewElement_selectedModeSnapshot, "f") !== null && this.queryString.length === 0) {
+            // Leaving "selected" mode with no active query: undo client-side filter and restore expansion
+            // state without a server round-trip (the full tree is already in the DOM).
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_undoClientSideFilter).call(this);
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyExpansionSnapshot).call(this, __classPrivateFieldGet(this, _FilterableTreeViewElement_selectedModeSnapshot, "f"));
+            __classPrivateFieldSet(this, _FilterableTreeViewElement_selectedModeSnapshot, null, "f");
+        }
+        else {
+            // "all" mode with an active query, or switching away from a custom mode: use async fetch.
+            __classPrivateFieldSet(this, _FilterableTreeViewElement_selectedModeSnapshot, null, "f");
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_scheduleAsyncFetch).call(this);
+        }
+    }
+    else {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+    }
+};
+_FilterableTreeViewElement_undoClientSideFilter = function _FilterableTreeViewElement_undoClientSideFilter() {
+    for (const el of this.querySelectorAll('tree-view li[hidden], tree-view-sub-tree-node[hidden]')) {
+        el.removeAttribute('hidden');
+    }
 };
 _FilterableTreeViewElement_handleFilterInputEvent = function _FilterableTreeViewElement_handleFilterInputEvent(event) {
     if (event.type !== 'input')
         return;
-    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+    // "selected" mode is always client-side – the server doesn't know the selection state.
+    if (__classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "a", _FilterableTreeViewElement_isAsyncMode_get) && this.filterMode !== 'selected') {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_scheduleAsyncFetch).call(this);
+    }
+    else {
+        __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);
+    // In async mode, toggling include-sub-items does not require a server round-trip: the client
+    // handles the visual state entirely (checking/disabling visible descendants). The flag will be
+    // included automatically in the next filter request triggered by a query or filter-mode change.
+    if (!__classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "a", _FilterableTreeViewElement_isAsyncMode_get)) {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyFilterOptions).call(this);
+    }
     if (this.includeSubItemsCheckBox.checked) {
         __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_includeSubItems).call(this);
     }
@@ -247,6 +363,179 @@ _FilterableTreeViewElement_restoreAllNodeStates = function _FilterableTreeViewEl
         __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_restoreNodeState).call(this, subTree);
     }
 };
+_FilterableTreeViewElement_scheduleAsyncFetch = function _FilterableTreeViewElement_scheduleAsyncFetch() {
+    if (__classPrivateFieldGet(this, _FilterableTreeViewElement_debounceTimer, "f") !== null)
+        clearTimeout(__classPrivateFieldGet(this, _FilterableTreeViewElement_debounceTimer, "f"));
+    __classPrivateFieldSet(this, _FilterableTreeViewElement_debounceTimer, setTimeout(() => {
+        __classPrivateFieldSet(this, _FilterableTreeViewElement_debounceTimer, null, "f");
+        void __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_fetchAndReplaceTree).call(this);
+    }, ASYNC_DEBOUNCE_MS), "f");
+};
+_FilterableTreeViewElement_fetchAndReplaceTree = async function _FilterableTreeViewElement_fetchAndReplaceTree() {
+    const src = __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "a", _FilterableTreeViewElement_src_get);
+    if (!src)
+        return;
+    const query = this.queryString;
+    const filterMode = this.filterMode || 'all';
+    const includeSubItems = this.includeSubItemsCheckBox?.checked ?? false;
+    // Snapshot expansion state the first time the user enters a filter query
+    if (!__classPrivateFieldGet(this, _FilterableTreeViewElement_isFiltered, "f") && query.length > 0) {
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_snapshotExpansionState).call(this);
+        __classPrivateFieldSet(this, _FilterableTreeViewElement_isFiltered, true, "f");
+    }
+    else if (__classPrivateFieldGet(this, _FilterableTreeViewElement_isFiltered, "f") && query.length === 0) {
+        __classPrivateFieldSet(this, _FilterableTreeViewElement_isFiltered, false, "f");
+    }
+    // Remember which filter state this particular request was for so we apply
+    // the correct post-processing even if the user types quickly.
+    const requestWasFiltered = query.length > 0;
+    // Abort any in-flight request
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_fetchAbortController, "f")?.abort();
+    const { signal } = (__classPrivateFieldSet(this, _FilterableTreeViewElement_fetchAbortController, new AbortController(), "f"));
+    const url = new URL(src, window.location.href);
+    url.searchParams.set('query', query);
+    url.searchParams.set('filter_mode', filterMode);
+    url.searchParams.set('include_sub_items', String(includeSubItems));
+    // Send currently-checked node IDs so the server can apply include-sub-items
+    // logic even for nodes that are no longer visible due to filtering / pagination.
+    for (const nodeId of __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeIds, "f").keys()) {
+        url.searchParams.append('checked_ids[]', nodeId);
+    }
+    this.setAttribute('data-loading', '');
+    this.setAttribute('aria-busy', 'true');
+    try {
+        const response = await fetch(url.toString(), {
+            signal,
+            headers: { Accept: 'text/html' },
+            credentials: 'same-origin',
+            method: 'GET',
+        });
+        if (!response.ok)
+            return;
+        const html = await response.text();
+        const doc = new DOMParser().parseFromString(html, 'text/html');
+        const newTreeView = doc.querySelector('tree-view');
+        if (!newTreeView)
+            return;
+        const oldTreeView = this.treeViewList?.closest('tree-view');
+        if (!oldTreeView)
+            return;
+        // Invalidate old stateMap entries – the referenced DOM nodes no longer exist after replacement.
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_stateMap, "f").clear();
+        oldTreeView.replaceWith(newTreeView);
+        // Catalyst re-resolves @target treeViewList dynamically on next access.
+        // Restore checked state for all nodes that now appear in the new tree.
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_restoreSelectionState).call(this);
+        // Re-apply include-sub-items visually if the checkbox is still checked.
+        if (includeSubItems) {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_includeSubItems).call(this);
+        }
+        if (requestWasFiltered) {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_expandAllSubTrees).call(this);
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyAsyncHighlights).call(this, query);
+            const hasResults = !!this.treeViewList?.querySelector('[role=treeitem]');
+            this.noResultsMessage.toggleAttribute('hidden', hasResults);
+            this.treeViewList?.toggleAttribute('hidden', !hasResults);
+        }
+        else {
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_removeHighlights).call(this);
+            __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_restoreExpansionState).call(this);
+            this.noResultsMessage.setAttribute('hidden', 'hidden');
+            this.treeViewList?.removeAttribute('hidden');
+        }
+        // Synthesise form inputs for nodes that are checked but absent from the current DOM
+        // (e.g. filtered out). Must run after restoreSelectionState so we know what is in the DOM.
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_updateRetainedSelections).call(this);
+    }
+    catch (e) {
+        if (e.name === 'AbortError')
+            return;
+        throw e;
+    }
+    finally {
+        this.removeAttribute('data-loading');
+        this.setAttribute('aria-busy', 'false');
+    }
+};
+_FilterableTreeViewElement_captureExpansionState = function _FilterableTreeViewElement_captureExpansionState() {
+    const snapshot = new Map();
+    for (const treeitem of this.querySelectorAll('[role=treeitem][data-node-id][data-node-type=sub-tree]')) {
+        snapshot.set(treeitem.getAttribute('data-node-id'), treeitem.getAttribute('aria-expanded') === 'true');
+    }
+    return snapshot;
+};
+_FilterableTreeViewElement_applyExpansionSnapshot = function _FilterableTreeViewElement_applyExpansionSnapshot(snapshot) {
+    for (const [nodeId, wasExpanded] of snapshot) {
+        const treeitem = this.querySelector(`[role=treeitem][data-node-id="${CSS.escape(nodeId)}"]`);
+        const subTreeNode = treeitem?.closest('tree-view-sub-tree-node');
+        if (subTreeNode) {
+            if (wasExpanded) {
+                subTreeNode.expand();
+            }
+            else {
+                subTreeNode.collapse();
+            }
+        }
+    }
+};
+_FilterableTreeViewElement_snapshotExpansionState = function _FilterableTreeViewElement_snapshotExpansionState() {
+    __classPrivateFieldSet(this, _FilterableTreeViewElement_expansionSnapshot, __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_captureExpansionState).call(this), "f");
+};
+_FilterableTreeViewElement_restoreExpansionState = function _FilterableTreeViewElement_restoreExpansionState() {
+    if (!__classPrivateFieldGet(this, _FilterableTreeViewElement_expansionSnapshot, "f"))
+        return;
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyExpansionSnapshot).call(this, __classPrivateFieldGet(this, _FilterableTreeViewElement_expansionSnapshot, "f"));
+    __classPrivateFieldSet(this, _FilterableTreeViewElement_expansionSnapshot, null, "f");
+};
+_FilterableTreeViewElement_restoreSelectionState = function _FilterableTreeViewElement_restoreSelectionState() {
+    if (!this.treeView)
+        return;
+    for (const treeitem of this.querySelectorAll('[role=treeitem][data-node-id]')) {
+        const nodeId = treeitem.getAttribute('data-node-id');
+        const savedValue = __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeIds, "f").get(nodeId);
+        if (savedValue !== undefined) {
+            this.treeView.setNodeCheckedValue(treeitem, savedValue);
+        }
+    }
+};
+_FilterableTreeViewElement_expandAllSubTrees = function _FilterableTreeViewElement_expandAllSubTrees() {
+    for (const subTreeNode of this.querySelectorAll('tree-view-sub-tree-node')) {
+        subTreeNode.expand();
+    }
+};
+_FilterableTreeViewElement_applyAsyncHighlights = function _FilterableTreeViewElement_applyAsyncHighlights(query) {
+    __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_removeHighlights).call(this);
+    const ranges = [];
+    for (const treeitem of this.querySelectorAll('[role=treeitem]')) {
+        const result = this.defaultFilterFn(treeitem, query, 'all');
+        if (result)
+            ranges.push(...result);
+    }
+    if (ranges.length > 0)
+        __classPrivateFieldGet(this, _FilterableTreeViewElement_instances, "m", _FilterableTreeViewElement_applyHighlights).call(this, ranges);
+};
+_FilterableTreeViewElement_updateRetainedSelections = function _FilterableTreeViewElement_updateRetainedSelections() {
+    // Only relevant when a form is wired up.
+    const prototype = this.treeView?.formInputPrototype;
+    if (!prototype)
+        return;
+    // Remove previously injected retained inputs.
+    for (const el of this.querySelectorAll('[data-filterable-tree-view-retained]')) {
+        el.remove();
+    }
+    for (const [nodeId, payload] of __classPrivateFieldGet(this, _FilterableTreeViewElement_checkedNodeFormPayloads, "f")) {
+        // Nodes currently in the DOM are already covered by TreeView's updateHiddenFormInputs.
+        const inDom = !!this.querySelector(`[role=treeitem][data-node-id="${CSS.escape(nodeId)}"]`);
+        if (inDom)
+            continue;
+        const input = document.createElement('input');
+        input.type = 'hidden';
+        input.name = prototype.name;
+        input.value = JSON.stringify(payload);
+        input.setAttribute('data-filterable-tree-view-retained', '');
+        this.appendChild(input);
+    }
+};
 _FilterableTreeViewElement_applyFilterOptions = function _FilterableTreeViewElement_applyFilterOptions() {
     if (!this.treeView)
         return;

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

@@ -0,0 +1,57 @@
+/* CSS for FilterableTreeView */
+
+/* Scroll layout
+ *
+ * The filterable-tree-view element itself acts as a flex column container.
+ * The toolbar (input, segmented control, checkbox) is fixed at the top.
+ * Only the tree area scrolls. The consumer is responsible for setting a
+ * height or max-height on the filterable-tree-view element (or its parent)
+ * to activate scrolling.
+ */
+
+/* stylelint-disable-next-line selector-max-type */
+filterable-tree-view {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  max-height: inherit;
+}
+
+.FilterableTreeViewLayout {
+  flex: 1;
+  min-height: 0;
+}
+
+.FilterableTreeViewTreeContainer {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* Highlight style for CSS Custom Highlight API */
+::highlight(primer-filterable-tree-view-search-results) {
+  background-color: var(--bgColor-attention-muted);
+}
+
+/* Fallback: <mark> elements used when CSS Custom Highlight API is unavailable */
+/* stylelint-disable-next-line selector-max-type */
+filterable-tree-view mark {
+  background-color: var(--bgColor-attention-muted);
+  color: inherit;
+}
+
+/* Loading skeleton */
+.FilterableTreeViewLoadingSkeleton {
+  display: none;
+}
+
+/* stylelint-disable selector-no-qualifying-type */
+/* stylelint-disable selector-max-type */
+filterable-tree-view[data-loading] .FilterableTreeViewLoadingSkeleton {
+  display: block;
+}
+
+filterable-tree-view[data-loading] tree-view,
+filterable-tree-view[data-loading] [data-target~="filterable-tree-view.noResultsMessage"] {
+  display: none;
+}

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

@@ -102,9 +102,44 @@ module Primer
     #
     # Currently `FilterableTreeView` does not emit any events aside from the events already emitted by the `TreeView`
     # component.
+    #
+    # ## Async loading strategy
+    #
+    # When `src` is set on the component, all filter interactions (text input, filter mode changes) trigger a debounced
+    # server request instead of client-side filtering. The server is responsible for returning a filtered `<tree-view>`
+    # HTML fragment that replaces the current tree.
+    #
+    # ### Behavior
+    #
+    # - The full tree is loaded initially from the server via `src`.
+    # - Each filter input event triggers a debounced (300 ms) request to the server.
+    # - The server returns a filtered `<tree-view>` element which replaces the existing one.
+    # - All matching results and their full ancestor hierarchy are expanded automatically.
+    # - Matching text is highlighted using the CSS Custom Highlight API (or `<mark>` fallback).
+    # - When the filter is cleared, the tree is replaced with the full (unfiltered) result from
+    #   the server and the expansion state from before the search is restored.
+    # - Checked nodes are preserved across tree replacements using `data-node-id` attributes.
+    # - When "include sub-items" is active and the tree is filtered, clicking a parent node
+    #   selects ALL its descendants (not just the visible filtered ones). Therefore, "include_sub_items" is passed
+    #   to the server, since it holds the only truth about the data.
+    #
+    # ### Server endpoint
+    #
+    # The server endpoint must return a `<tree-view>` HTML fragment. Each node must have a stable
+    # `data-node-id` on its `[role=treeitem]` element.
+    #
+    # ### Usage
+    #
+    # ```erb
+    # <%= render(Primer::OpenProject::FilterableTreeView.new(
+    #   src: my_path
+    # )) %>
+    # ```
     class FilterableTreeView < Primer::Component
       delegate :with_leaf, :with_sub_tree, to: :@tree_view
 
+      SUPPORTED_SELECT_VARIANTS = %i[multiple single none].freeze
+
       DEFAULT_FILTER_INPUT_ARGUMENTS = {
         name: :filter,
         label: I18n.t(:button_filter),
@@ -153,6 +188,7 @@ module Primer
 
       DEFAULT_NO_RESULTS_NODE_ARGUMENTS.freeze
 
+      # @param src [String] URL of the server endpoint that returns a filtered `<tree-view>` HTML fragment. When set, activates async (server-side) filtering mode. See "Async loading strategy" above.
       # @param tree_view_arguments [Hash] Arguments that will be passed to the underlying <%= link_to_component(Primer::Alpha::TreeView) %> component.
       # @param form_arguments [Hash] Form arguments that will be passed to the underlying <%= link_to_component(Primer::Alpha::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.
@@ -160,6 +196,7 @@ module Primer
       # @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::Alpha::TreeView::LeafNode) %> component that appears when no items match the filter criteria.
       def initialize(
+        src: nil,
         tree_view_arguments: {},
         form_arguments: {},
         filter_input_arguments: DEFAULT_FILTER_INPUT_ARGUMENTS.dup,
@@ -168,6 +205,8 @@ module Primer
         no_results_node_arguments: DEFAULT_NO_RESULTS_NODE_ARGUMENTS.dup,
         **system_arguments
       )
+        @tree_view_arguments = tree_view_arguments.dup
+
         tree_view_arguments[:data] = merge_data(
           tree_view_arguments, {
             data: { target: "filterable-tree-view.treeViewList" }
@@ -209,6 +248,7 @@ module Primer
 
         @system_arguments = deny_tag_argument(**system_arguments)
         @system_arguments[:tag] = :"filterable-tree-view"
+        @system_arguments[:src] = src if src
 
         @no_results_node_arguments = no_results_node_arguments
       end
@@ -232,15 +272,14 @@ module Primer
       def with_sub_tree(**system_arguments, &block)
         system_arguments[:select_variant] ||= :multiple
 
-        if system_arguments[:select_variant] != :multiple && system_arguments[:select_variant] != :single
-          raise ArgumentError, "FilterableTreeView only supports `:multiple` or `:single` as select_variant"
+        unless SUPPORTED_SELECT_VARIANTS.include?(system_arguments[:select_variant])
+          raise ArgumentError, "FilterableTreeView only supports #{SUPPORTED_SELECT_VARIANTS.map(&:inspect).to_sentence} as select_variant"
         end
 
-        if system_arguments[:select_variant] == :single
-          # In single selection, the include sub-items checkbox and the SegmentedControl make no sense
+        if system_arguments[:select_variant] != :multiple
+          # In single/none selection, the include sub-items checkbox makes no sense
           @include_sub_items_check_box_arguments[:hidden] = true
           @include_sub_items_check_box_arguments[:checked] = false
-          @filter_mode_control_arguments[:hidden] = true
         end
 
         @tree_view.with_sub_tree(
@@ -254,15 +293,14 @@ module Primer
       def with_leaf(**system_arguments, &block)
         system_arguments[:select_variant] ||= :multiple
 
-        if system_arguments[:select_variant] != :multiple && system_arguments[:select_variant] != :single
-          raise ArgumentError, "FilterableTreeView only supports `:multiple` or `:single` as select_variant"
+        unless SUPPORTED_SELECT_VARIANTS.include?(system_arguments[:select_variant])
+          raise ArgumentError, "FilterableTreeView only supports #{SUPPORTED_SELECT_VARIANTS.map(&:inspect).to_sentence} as select_variant"
         end
 
-        if system_arguments[:select_variant] == :single
-          # In single selection, the include sub-items checkbox and the SegmentedControl make no sense
+        if system_arguments[:select_variant] != :multiple
+          # In single/none selection, the include sub-items checkbox makes no sense
           @include_sub_items_check_box_arguments[:hidden] = true
           @include_sub_items_check_box_arguments[:checked] = false
-          @filter_mode_control_arguments[:hidden] = true
         end
 
         @tree_view.with_leaf(
@@ -271,9 +309,19 @@ module Primer
         )
       end
 
+      def async?
+        @system_arguments.key?(:src)
+      end
+
       private
 
       def before_render
+        if @system_arguments[:src] && @tree_view_arguments.any?
+          raise ArgumentError, "tree_view_arguments are not supported when src: is provided. " \
+                               "The initial tree shell is replaced on the first async fetch, so any " \
+                               "tree_view_arguments would be lost. Configure the tree in your server endpoint instead."
+        end
+
         content
 
         if @filter_mode_control.present? && @filter_mode_control.items.empty?