docs-bug(treeview): Add guide on how to migrate from old treeview to new treeview

[azimuthdeveloper]

Documentation Feedback

Following the sudden deprecation of the various tree controllers, it would be nice if there were some kind of documentation on how to remove tree controller and migrate to the new way of doing things. Also, the documentation still contains references to treeControl, which it shouldn't because the treeControl has been deprecated?

A simple migration guide would be warranted as well because there are tonnes of search results and guides on how to use the tree that just became out of date, so if there was an easy way to adapt code to the new way of doing things, that would be ideal.

Affected documentation page

https://material.angular.io/components/tree/overview

[azimuthdeveloper]

Actually, the tree documentation page needs some attention overall it seems.

In the v17 documentation, the "Tree with flat nodes" appears correct.

But then, in v 18.2.10, it looks wrong.

I think I'm reasonably good at the tree - I did an implementation for work and also wrote a fairly long article for LogRocket so I might be able to pop in a PR for these things, and fix other things (https://blog.logrocket.com/angular-tree-flat-vs-nested-and-more/).

Also, the various selectors seem to rely on knowing about the children beforehand and don't support returning asynchronously. When tree children are loaded from the server, how is this supposed to be handled?

Kind of not really related - I find the documentation for the treeview to be simultaneously overwhelming and light on details, almost like it's been built up over several years. This confusion is now only worse with the API documentation chopping and changing between the old treeControl implementation and the new childrenAccessor. People who were new to the tree would find the documentation very confusing in its current state. It's like the whole page needs to be redone. Would you accept a PR for this?

[azimuthdeveloper]

Just to help other people who might be trying to use async data in their trees: I figured it out. I tried a lot of things and in the end this is what stuck. My branch is here, I'm going to write about it soon with samples etc: https://github.com/azimuthdeveloper/angulartree/tree/inflight-changes-to-new-angular-tree

Basically,

For flat trees, use levelAccessor, and then on your node, use expandedChange to fire an event like handleNodeExpansion($event, node) where $event is the true/false state of whether the node is expanded or not, and node is the node that is being actuated. In that function, call your expand/contract function in the data source.

For nested trees, use childAccessor, and assign it to the children property of your node. It'll look like this. children must be of type Observable, so when they update, the tree updates. In my case, its a BehaviourSubject

childrenAccessor = (dataNode: NestedTreeNode) => dataNode.children;

Again, then on your node, use expandedChange to fire an event like handleNodeExpansion($event, node) where $event is the true/false state of whether the node is expanded or not, and node is the node that is being actuated. In that function, call your expand/contract function in the data source.

On a more personal note, I think Angular has been going from strength to strength lately, and I wouldn't want to get on here and complain or say anything derogatory. Please accept this as constructive feedback.

At the time of me writing this, the tree control sample page is an unintelligible mess, chopping back and forth between the old treeControl and new childrenAccessor/levelAccessor. The documentation was very hard to understand in the first place and now it's just gotten worse. There are samples on how to use childrenAccessor, but no samples on how to use levelAccessor, so people are free to guess their way through an implementation like I did.

It's not clear why the tree was revamped - I couldn't find a long issue with comments that ended in "okay I'm going to deprecate large parts of the tree and make it work differently" so it's difficult to understand why this change was even made in the first place.

It would be nice if, when new features shipped, there was a better copy-edit process on the documentation, documentation didn't ship with todo notes, documentation was at least at feature parity with previous releases (like async loading of nodes), documentation at least covered all features (such as levelAccessor being absent) and some rationale was given as to why the change occured. I'm a strong Angular supporter, I write about it professionally and use it in my day job, so this comes from a place where I want Angular to succeed in the long run.

[Sebi11]

I almost totally agree with you @azimuthdeveloper about the lack of documentation. Just one point to be fair: the new code to use MatTree seems way more simple and shorter than the version before Angular Materiel 18.2.

[andrewseguin]

To remark on why the tree changed, in short we had a number of accessibility issues with how the tree worked in the past. As we made changes to improve the accessibility, we had to make adjustments/improvements to the API. You can see a detailed note of the changes and their reasons in the original PR #29062

I agree the tree's documentation is subpar. Unfortunately we ran out of resources to give it the update it deserves. In particular I do wish we had a better guide on transitioning from the deprecated API to the current.

[WwwHhhYran]

@andrewseguin After reviewing this PR, I still find it difficult to understand why TreeControl should be deprecated.

For example, in the current documentation, when rendering a flat tree, we use style.display combined with shouldRender to show or hide certain child nodes. However, I would prefer if some nodes that do not need to be rendered could be filtered out directly. In the previous version, I could use TreeControl to query certain tree node is expanded or not, whick allows me to filter them and subsequently emit the dataStream of the dataSource. However, with the current approach of using CdkTree to manage nodes, I have to wait until CdkTree is initialized, so can use isExpanded method to accurately determine whether certain nodes need to be rendered. This limitation prevents me from filtering data within the dataSource, because dataSource is a Input() param of CdkTree. If we use CdkTree.isExpanded in dataSource, will lead to circular references.

The example can refer to material/tree/data source/flat-data-source.ts, how can i override the this._treeFlattener.expandFlattenedNodes used by the new feature ?

// ... others

return merge(
      collectionViewer.viewChange,
      this._treeControl.expansionModel.changed,
      this._flattenedData,
    ).pipe(
      map(() => {
        this._expandedData.next(
          this._treeFlattener.expandFlattenedNodes(this._flattenedData.value, this._treeControl),
        );
        return this._expandedData.value;
      }),
    );

I currently can't think of a suitable alternative to address above issue. If you have better suggestions, I would appreciate it if you could share them with me.