feat(tree-view): add nodesFlat prop

[metonym]

No description provided.

[brunnerh]

I don't really see a reason to bloat TreeView with this, this could probably exist as a separate function or in user-land entirely.

<TreeView nodes={toHierarchy(nodeList)}>

[metonym]

@brunnerh Agreed – I like the notion of a separate utility (tree-shakeable) that can be optionally used.

[bhavers]

Shall i make this a separate function?
One downside from a DX perspective that i could see (not sure) is that you would loose easy reactivity with nodes=treeview.toHierarchy(flatdata) instead of nodesFlat=flatdata (i guess you would need an #key block for the former).

[metonym]

@bhavers Yes. Let's make this a separate function. If I'm understanding correctly, I don't think reactivity would be a concern – if nodes changes, all downstream dependencies should be auto-updated.

• Create a treeview.js file in the src/TreeView directory with the exported function to flatten the nodes. Moving the logic outside of the component avoid penalizing usage in which the function is not used (it should be tree-shaken).
• Also create a treeview.d.ts file, which will be copied over to types as part of build process. A nice reference is breakpointObserver.d.ts

[bhavers]

Ok, will do so some moment in the upcoming days. Thanks for the extra explanation.

[bhavers]

@metonym I don't get it to work.
It keeps complaining that the function toHierarchy is not exported, but it is.

Uncaught (in promise) SyntaxError: The requested module '/@fs/Users/bramhavers/Documents/code/carbon-components-svelte/src/index.js?t=1733084657166' does not provide an export named 'toHierarchy' (at TreeViewFlatArray.svelte:2:22)

And i am also not clear why we would need those definition files. It seems quite double because the javascript files already contain JSDoc type declarations.
In breakpointobserver i also saw a index.d.ts which is identical to index.js, which makes little sense to me.
Hope you can provide a hint on what i am doing wrong here.

[bhavers]

@metonym Never mind, a day later and a fresh quick look reveals that i was looking at the wrong index.js. Will make a new commit.

[bhavers]

@metonym It works. Couple of questions:

• toHierarchy (in treeview.js) didn't show up in the docs, so i created a proxy toHierarchy in TreeView.svelte. Is that ok, or does it bloat the component & prevent tree shaking? How would we otherwise get toHierarchy in the docs?
• the test wouldn't run with toHierarchy in treeview.js; only when using toHierarchy from TreeView. I guess that has to do with the test runner not being linked to the new code? (i ran npm run test from the carbon root.
• i added toHierarchy to src/index.js, but also to TreeView/index.js, and also added some definitions files. Seems all a bit double. Is that as designed or should i have only updated it in one place?

[metonym]

@bhavers Great work! I've reviewed this and implemented the following changes. I opened #2072 since I was not able to push directly to the outside PR.

• Avoid modifying the existing TreeView component since toHierarchy is designed to be used outside of it (formatting nodes prop as an input). This avoids any penalty to consumers that do not use this function, as toHierarchy can be tree-shaken.
• Refactor toHierarchy to have a required second argument – a callback function to retrieve the parent ID (if applicable) on a given node. This avoids the need to hardcode the key of the parent ID. Any key (except id and nodes) can be used. As a user, I wouldn't assume "pid" to mean parent ID. This also saves a need to normalize the array before passing it to this function.
• Refactor toHierarchy to avoid an extra loop to prune "empty" nodes. Instead, the parent existence is validated before child nodes are added.
• Refactor toHierarchy TypeScript definitions to leverage generics. This allows for additional type safety, as it requires the parent ID to be a valid property and the supplied array of objects.
• Finally, since the nodes prop of both TreeView and RecursiveList are the same, I made this utility even more generic for use with either component.

type NodeLike = {
  id: string | number;
  nodes?: NodeLike[];
  [key: string]: any;
};

export function toHierarchy<
  T extends NodeLike,
  K extends keyof Omit<T, "id" | "nodes">,
>(
  flatArray: T[] | readonly T[],
  /**
   * Function that returns the parent ID for a given node.
   * @example
   * toHierarchy(flatArray, (node) => node.parentId);
   */
  getParentId: (node: T) => T[K] | null,
): (T & { nodes?: (T & { nodes?: T[] })[] })[];

[bhavers]

@metonym Thank you for the explanation. I went through your refactorings and it was really helpful to see how this is done. Although i don't think i fully the grasp the generics wizardry ;-)
Looking forward to using this new function.

[metonym]

Released in v0.87.0.

If using optimizeImports from carbon-preprocess-svelte, you'll need to upgrade to carbon-preprocess-svelte@0.11.9.