docs(tree-view): add filter nodes examples

Author: metonym

docs/src/pages/components/TreeView.svx

@@ -113,3 +113,28 @@ Use `TreeView.showNode` to expand, select, and focus a specific node.
 Convert flat data to a hierarchical structure using the `toHierarchy` utility.
 
 <FileSource src="/framed/TreeView/TreeViewFlatArray" />
+
+## Filter by text with search input
+
+Combine a `Search` input with `filterTreeByText` to create an interactive searchable tree. Type to filter nodes by name (case-insensitive substring matching).
+
+<FileSource src="/framed/TreeView/TreeViewFilter" />
+
+## Filter utilities
+
+Three filtering functions are available:
+
+<UnorderedList svx-ignore style="margin-bottom: var(--cds-spacing-08)">
+  <ListItem><strong>filterTreeByText(tree, text, options)</strong>: Case-insensitive substring search on node text</ListItem>
+  <ListItem><strong>filterTreeById(tree, id, options)</strong>: Filter by single ID or array of IDs</ListItem>
+  <ListItem><strong>filterTreeNodes(tree, predicate, options)</strong>: Custom filtering with predicate function</ListItem>
+</UnorderedList>
+
+## Filter options
+
+All filter functions accept an optional `options` object:
+
+<UnorderedList svx-ignore style="margin-bottom: var(--cds-spacing-08)">
+  <ListItem><strong>includeAncestors</strong> (default: true): Include parent chain of matched nodes</ListItem>
+  <ListItem><strong>includeChildren</strong> (default: false): Include all descendants of matched nodes</ListItem>
+</UnorderedList>

docs/src/pages/framed/TreeView/TreeViewFilter.svelte

@@ -0,0 +1,127 @@
+<script>
+  import { filterTreeByText, Search, TreeView } from "carbon-components-svelte";
+
+  const allNodes = [
+    {
+      id: "1",
+      text: "Documents",
+      nodes: [
+        {
+          id: "1-1",
+          text: "Work",
+          nodes: [
+            { id: "1-1-1", text: "Report.docx" },
+            { id: "1-1-2", text: "Presentation.pptx" },
+            { id: "1-1-3", text: "Budget.xlsx" },
+            { id: "1-1-4", text: "Meeting Notes.txt" },
+          ],
+        },
+        {
+          id: "1-2",
+          text: "Personal",
+          nodes: [
+            { id: "1-2-1", text: "Resume.pdf" },
+            { id: "1-2-2", text: "Cover Letter.pdf" },
+            { id: "1-2-3", text: "Portfolio.pdf" },
+          ],
+        },
+        {
+          id: "1-3",
+          text: "Projects",
+          nodes: [
+            {
+              id: "1-3-1",
+              text: "Website",
+              nodes: [
+                { id: "1-3-1-1", text: "index.html" },
+                { id: "1-3-1-2", text: "styles.css" },
+                { id: "1-3-1-3", text: "script.js" },
+              ],
+            },
+            {
+              id: "1-3-2",
+              text: "App",
+              nodes: [
+                { id: "1-3-2-1", text: "main.py" },
+                { id: "1-3-2-2", text: "config.json" },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      id: "2",
+      text: "Pictures",
+      nodes: [
+        { id: "2-1", text: "Vacation.jpg" },
+        { id: "2-2", text: "Family.jpg" },
+        { id: "2-3", text: "Birthday.png" },
+      ],
+    },
+    {
+      id: "3",
+      text: "Music",
+      nodes: [
+        {
+          id: "3-1",
+          text: "Rock",
+          nodes: [
+            { id: "3-1-1", text: "Song1.mp3" },
+            { id: "3-1-2", text: "Song2.mp3" },
+          ],
+        },
+        {
+          id: "3-2",
+          text: "Jazz",
+          nodes: [
+            { id: "3-2-1", text: "Song3.mp3" },
+            { id: "3-2-2", text: "Song4.mp3" },
+          ],
+        },
+        {
+          id: "3-3",
+          text: "Classical",
+          nodes: [{ id: "3-3-1", text: "Symphony.mp3" }],
+        },
+      ],
+    },
+  ];
+
+  let searchValue = "";
+  let expandedIds = [];
+
+  // Reactively filter nodes based on search input
+  $: filteredNodes =
+    searchValue.trim() === ""
+      ? allNodes
+      : filterTreeByText(allNodes, searchValue);
+
+  // Auto-expand filtered nodes to show matches
+  $: if (searchValue.trim() !== "" && filteredNodes.length > 0) {
+    // Extract all node IDs from filtered tree for expansion
+    const extractIds = (nodes) => {
+      const ids = [];
+      for (const node of nodes) {
+        ids.push(node.id);
+        if (node.nodes) {
+          ids.push(...extractIds(node.nodes));
+        }
+      }
+      return ids;
+    };
+    expandedIds = extractIds(filteredNodes);
+  } else {
+    expandedIds = [];
+  }
+</script>
+
+<Search placeholder="Search tree nodes..." bind:value={searchValue} />
+
+{#if filteredNodes.length > 0}
+  <TreeView labelText="File System" nodes={filteredNodes} {expandedIds} />
+{:else}
+  <div style="padding: 1rem; color: var(--cds-text-secondary);">
+    No matching nodes found for "{searchValue}"
+  </div>
+{/if}