feat(tree-view): add filterTreeNodes utilities

[metonym]

Closes #2281

Add tree node filtering utilities for TreeView. Three new functions enable filtering hierarchical tree structures by predicate, ID, or text search.

• filterTreeNodes: generic predicate-based filtering
• filterTreeById: filter by node ID(s)
• filterTreeByText: case-insensitive text search

The filterTreeNodes function accepts a predicate function to filter nodes based on custom logic. It returns a new tree containing only matching nodes and their ancestors by default.

import { filterTreeNodes } from "carbon-components-svelte";

const tree = [
  { id: 1, text: "Documents", nodes: [
    { id: 2, text: "Work", nodes: [
      { id: 3, text: "Report.docx" }
    ]}
  ]}
];

const filtered = filterTreeNodes(tree, (node) => node.id === 3);
// Returns: [{ id: 1, text: "Documents", nodes: [{ id: 2, text: "Work", nodes: [{ id: 3, text: "Report.docx" }] }] }]

The filterTreeById function filters nodes by ID, accepting either a single ID or an array of IDs.

import { filterTreeById } from "carbon-components-svelte";

const filtered = filterTreeById(tree, 3);
// Or filter by multiple IDs:
const filtered = filterTreeById(tree, [3, 4]);

The filterTreeByText function performs case-insensitive substring matching on node text properties.

import { filterTreeByText } from "carbon-components-svelte";

const filtered = filterTreeByText(tree, "work");
// Matches any node where text contains "work" (case-insensitive)

All filter functions accept an optional options object with two properties. The includeAncestors option (default: true) includes parent nodes of matching nodes, ensuring the filtered tree maintains valid parent-child relationships. The includeChildren option (default: false) includes all descendants of matching nodes.

// Include all children of matching nodes
const filtered = filterTreeByText(tree, "Documents", { includeChildren: true });

// Exclude ancestors, only return matching nodes
const filtered = filterTreeNodes(tree, (node) => node.id === 3, { includeAncestors: false });

[metonym]

Released in v0.91.0