feat: add toHierarchy utility for TreeView, RecursiveList

[metonym]

Based on #2069, as I'm unable to push directly to that outside PR. Closes #2069.

This adds a toHierarchy utility per @bhavers's suggestion.

Both TreeView and RecursiveList components have a nodes prop. The structure is hierarchical, where a node specifies "child" nodes via the nodes prop. However, data may often be flat, with a property specifying its parent node ID.

This adds a toHierarchy utility to easily convert a flat array of nodes into a shape acceptable by the recursive components. This utility is separated from any specific component both for reusability but also for performance. If unused, the utility should be tree-shaken from bundles.

The second, required argument is a callback to retrieve the parent ID value. It's generic as to not force using any specific key for the parent ID. However, id and nodes are required, as they match the prop shape for TreeView and RecursiveList.

Usage

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

toHierarchy(array, node => node.parentId);

TreeView

<script>
  import { TreeView, toHierarchy } from "carbon-components-svelte";
  import Analytics from "carbon-icons-svelte/lib/Analytics.svelte";

  let nodesFlat = [
    { id: 0, text: "AI / Machine learning", icon: Analytics },
    { id: 1, text: "Analytics" },
    { id: 2, text: "IBM Analytics Engine", pid: 1 },
    { id: 3, text: "Apache Spark", pid: 2 },
    { id: 4, text: "Hadoop", pid: 2 },
    { id: 5, text: "IBM Cloud SQL Query", pid: 1 },
    { id: 6, text: "IBM Db2 Warehouse on Cloud", pid: 1 },
    { id: 7, text: "Blockchain" },
    { id: 8, text: "IBM Blockchain Platform", pid: 7 },
    { id: 9, text: "Databases" },
    { id: 10, text: "IBM Cloud Databases for Elasticsearch", pid: 9 },
    { id: 11, text: "IBM Cloud Databases for Enterprise DB", pid: 9 },
    { id: 12, text: "IBM Cloud Databases for MongoDB", pid: 9 },
    { id: 13, text: "IBM Cloud Databases for PostgreSQL", pid: 9 },
    { id: 14, text: "Integration", disabled: true },
    { id: 15, text: "IBM API Connect", disabled: true, pid: 14 },
  ];
</script>

<TreeView
  labelText="Cloud Products"
  nodes={toHierarchy(nodesFlat, (node) => node.pid)}
/>

Implementation Details

• Uses a Map for efficient child-parent relationship lookups
• Handles both root-level and nested nodes appropriately
• Validates parent existence to prevent orphaned references
• Preserves original node properties while adding the nodes array where needed
• toHierarchy uses TypeScript generics for type safety and DX

Additional Notes

• carbon-preprocess-svelte will need to be re-indexed to optimize the import for toHierarchy. Otherwise, it will need to be directly imported to avoid slower development times (e.g., from "carbon-components-svelte/src/utility/toHierarchy")

[metonym]

Released in v0.87.0.

If using optimizeImports from carbon-preprocess-svelte, you'll need to upgrade to [email protected].