Filtering functionality

Author: Amphiluke

README.md

@@ -253,6 +253,20 @@ The `CbxTree` interface also inherits methods from its parent, [HTMLElement](htt
 
 Validation-related methods [`checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity), [`reportValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity), and [`setValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity) are transparently exposed from the underlying `ElementInternals` object which allows the `<cbx-tree>` element participate in form validation.
 
+### `CbxTree.filter()`
+
+This method can be used to “filter” the tree by hiding those items that don’t meet custom criteria. The method accepts a single argument, a preficate function. The predicate is passed an object argument with item’s `title` and `value` as properties, and the return value must be `true` if the item passes the filter and `false` otherwise. It should be noted that if an item passes the filter, its *descendants* remain visible even if they themselves don’t satisfy the filtering condition.
+
+```javascript
+const readingList = document.querySelector('[name="reading-list[]"]');
+const filterInput = document.getElementById('filter');
+filterInput.addEventListener('input', () => {
+  const query = filterInput.value.trim().toLocaleLowerCase();
+  const predicate = query.length ? ({title}) => title.toLocaleLowerCase().includes(query) : () => true;
+  readingList.filter(predicate);
+});
+```
+
 ### `CbxTree.setData()`
 
 The `setData()` method is used for complete overwriting and rerendering the entire tree. It accepts a single argument, a new [tree data](#tree-data-structure). All existing changes will be lost and replaced by the newly provided data after calling this method. See an example in the [Usage notes](#usage-notes) section.

dist/cbx-tree.d.mts

@@ -34,6 +34,7 @@ export default class CbxTree extends HTMLElement {
   toJSON(): CbxRawTreeItem[];
   toggleChecked(checked?: boolean): void;
   toggle(isExpanding?: boolean): void;
+  filter(predicate: ({title: string, value: string}) => boolean): void;
 
   get validity(): ValidityState;
   get validationMessage(): string;

dist/cbx-tree.mjs

@@ -0,0 +1,73 @@
+const tree = document.getElementById('file-tree');
+
+const textNodes = [];
+export const collectTextNodes = () => {
+  textNodes.length = 0;
+  const treeWalker = document.createTreeWalker(tree.shadowRoot.firstElementChild, NodeFilter.SHOW_TEXT);
+  let currentNode = treeWalker.nextNode();
+  while (currentNode) {
+    textNodes.push(currentNode);
+    currentNode = treeWalker.nextNode();
+  }
+};
+
+const addHighlightCSS = () => {
+  const stylesheet = new CSSStyleSheet();
+  stylesheet.replaceSync('::highlight(filter-results){background-color:#ff0066;color:#fff;}');
+  tree.shadowRoot.adoptedStyleSheets.push(stylesheet);
+};
+
+// https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API#highlighting_search_results
+const highlightMatches = (query) => {
+  if (!CSS.highlights) {
+    return;
+  }
+  CSS.highlights.clear();
+  if (!query) {
+    return;
+  }
+  const ranges = textNodes.map((textNode) => {
+    const text = textNode.textContent.toLowerCase();
+    const indices = [];
+    let startPos = 0;
+    while (startPos < text.length) {
+      const index = text.indexOf(query, startPos);
+      if (index === -1) break;
+      indices.push(index);
+      startPos = index + query.length;
+    }
+    return indices.map((index) => {
+      const range = new Range();
+      range.setStart(textNode, index);
+      range.setEnd(textNode, index + query.length);
+      return range;
+    });
+  });
+  CSS.highlights.set('filter-results', new Highlight(...ranges.flat()));
+};
+
+customElements.whenDefined('cbx-tree').then(() => {
+  addHighlightCSS();
+  collectTextNodes();
+  const {subtreeProvider} = tree;
+  if (subtreeProvider) {
+    tree.subtreeProvider = (...args) => subtreeProvider(...args).finally(() => setTimeout(collectTextNodes, 0));
+  }
+});
+
+let timer = null;
+document.getElementById('filter').addEventListener('input', ({target}) => {
+  if (timer) {
+    return;
+  }
+  timer = setTimeout(() => {
+    timer = null;
+    const query = target.value.trim().toLocaleLowerCase();
+    const predicate = query.length ? ({title}) => title.toLocaleLowerCase().includes(query) : () => true;
+    tree.filter(predicate);
+    if (query.length) {
+      tree.toggle(true);
+    }
+    highlightMatches(query);
+  }, 250);
+});

docs/cbx-tree.mjs

@@ -46,18 +46,38 @@ button {
 }
 
 .archive-head {
-  align-items: baseline;
+  align-items: center;
   display: flex;
   gap: 0.8ch;
 
+  h2 {
+    flex-shrink: 0;
+  }
+
   button {
     align-items: center;
     display: flex;
     justify-content: center;
+  }
+
+  [type='search'] {
+    flex: 0 1 400px;
+    height: 1.8lh;
+    margin-inline-start: auto;
+  }
+
+  @media (width < 600px) {
+    flex-wrap: wrap;
 
-    &:first-of-type {
+    button:first-of-type {
       margin-inline-start: auto;
     }
+
+    [type='search'] {
+      flex-grow: 1;
+      margin: 0;
+      order: 1;
+    }
   }
 }
 

docs/filtering.mjs

@@ -17,9 +17,10 @@
 </head>
 <body>
   <h1><code>&lt;cbx-tree&gt;</code>: The Checkbox Tree element</h1>
-  <form action="." id="archive-form" class="archive-form">
+  <form action="." id="archive-form" class="archive-form" autocomplete="off">
     <div class="archive-head">
       <h2>Select files/directories</h2>
+      <input type="search" id="filter" placeholder="Filter the tree">
       <button type="button" id="toggle-all-btn" title="Expand/collapse all">
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="1lh" height="1lh" fill="currentColor">
           <path d="M3.65 9.15a.5.5 0 0 1 .7 0L8 12.79l3.65-3.64a.5.5 0 0 1 .7.7l-4 4a.5.5 0 0 1-.7 0l-4-4a.5.5 0 0 1 0-.7m0-2.3a.5.5 0 0 0 .7 0L8 3.21l3.65 3.64a.5.5 0 0 0 .7-.7l-4-4a.5.5 0 0 0-.7 0l-4 4a.5.5 0 0 0 0 .7"/>
@@ -46,5 +47,6 @@ <h2>Select files/directories</h2>
   </footer>
   <script type="module" src="./cbx-tree.mjs"></script>
   <script type="module" src="./index.mjs"></script>
+  <script type="module" src="./filtering.mjs"></script>
 </body>
 </html>

docs/index.css

@@ -8,6 +8,7 @@
   </head>
   <body>
     <form action="#">
+      <input id="filter" class="filter" type="search">
       <cbx-tree name="reading-list[]">
         <script type="application/json">
           [
@@ -34,12 +35,12 @@
                       "checked": true
                     },
                     {
-                      "title": "Theogony, <i>by Hesoid</i>",
+                      "title": "Theogony, <i>by Hesiod</i>",
                       "value": "theogony",
                       "icon": "./icons/manuscript.svg"
                     },
                     {
-                      "title": "Works and Days, <i>by Hesoid</i>",
+                      "title": "Works and Days, <i>by Hesiod</i>",
                       "value": "works-and-days",
                       "icon": "./icons/manuscript.svg"
                     },