TreeGrid Flat Hierarchy Support

[yuriy-fix]

Description

Support flat hierarchy in TreeGrid by shifting hierarchy and cache management to the server to fix scroll glitches, refresh issues, and loading performance.

Tier

Free

License

Apache 2.0

Motivation

Background

Vaadin's TreeGrid uses a hierarchical lazy-loading model that requires separate requests for each level of the hierarchy. The existing logic (HierarchicalDataProvider and HierarchicalDataCommunicator) relies on client-side scroll events to fetch data, making it hard to handle deeply nested trees, large data sets, or responsive interactions like drag & drop or scrolling to specific items.

User problem

This architecture results in limited UX and DX due to:

• Skipped items when scrolling upwards: Lazily calculated sizes cause children to be inserted after scroll range has passed them.
• refreshAll() shifts scroll unexpectedly: Re-fetching entire tree resets scroll position unpredictably.
• Request waterfall: Pre-expanded trees trigger many redundant fetches with large loading overhead.
• Complex client code: gridConnector duplicates server-side hierarchy logic, making it harder to maintain.
• Lack of advanced interactions: scrollToItem is unsupported; refreshItem(item, true) is unreliable.

Solution

The solution introduces a flat hierarchy mode, where the server sends a flattened list of visible items and handles all hierarchy-related logic. The client renders this list like a regular Grid, applying indentation based on depth metadata.

Key changes:

• Client-side:

  • Renders flat data without tracking expanded state or hierarchy
  • Eliminates hierarchical cache and per-level data requests

• Server-side:

  • Computes the visible range from a flattened tree
  • Tracks expanded items and manages a tree-structured cache

• Data provider:

  • Can optionally support flat hierarchy mode by implementing:
    • isFlatHierarchy(boolean)
    • getDepth(item)
  • Sending single hierarchical query with getExpandedItemIds
  • Returns a flat, ordered slice including all expanded descendants

See the full RFC document for details.

This change resolves key TreeGrid limitations and makes it more flexible for complex use cases.

Requirements

• Refactor HierarchicalDataCommunicator to support server-side flattening
• Refactor gridConnector to render flattened data
• Add support for flat hierarchy mode in data providers via optional methods like isFlatHierarchy and getDepth to supply hierarchy metadata for flattened rendering
• Ensure scroll behavior is supported with flat provider
• Ensure drag&drop results in stable scroll and updated visible range when using refreshAll
• Maintain compatibility with legacy data providers

Nice-to-haves

• Introduce scrollToItem
• Add support for flat hierarchy in TreeData and TreeDataProvider

Risks, limitations and breaking changes

Refactoring may affect Vaadin add-ons using internal APIs (e.g., selectionGrid)

Public API

• Behavior change of TreeGrid#setPageSize (pages are calculated relative to the whole grid, not individual levels)
• Behavior change of HierarchicalDataCommunicator#setRequestedRange or introduce setViewportRange (accepts flat range instead of root level range)
• Remove HierarchicalDataCommunicator#setParentRequestedRange
• Remove HierarchicalDataCommunicator#confirmUpdate(int id, String parentKey)
• Remove AbstractDataProvider#refreshItem(T item, boolean refreshChildren) due to inconsistencies in behavior across data provider types, use refreshAll instead
• Remove HierachicalDataCommunicator#getParentOfItem
• Remove HierachicalDataCommunicator#getIndex
• Remove HierachicalDataCommunicator#getParentIndex

Protected API

• Remove HierarchyMapper
• Remove TreeGridArrayUpdater , use GridArrayUpdater instead
• Remove HierarchicalArrayUpdater
• Remove HierarchicalCommunicationController
• Remove HierarchicalDataCommunicator#doUnregister
• Remove HierarchicalDataCommunicator#getPassivatedKeys
• Remove HierarchicalDataCommunicator#getHierarchyMapper
• Make DataCommunicator#requestFlush protected

Materials

• RFC Document
• Prototype in flow-components
• Prototype in flow
• Forum thread on drag & drop
• Related issue

Pre-implementation checklist

• Estimated (estimate entered into Estimate custom field)
• Product Manager sign-off
• Engineering Manager sign-off

Pre-release checklist

• Documented (link to documentation provided in sub-issue or comment)
• UX/DX tests conducted and blockers addressed
• Approved for release by Product Manager

Security review

To be considered

[vursen]

Additional protected methods that will be deprecated and removed, as they are no longer relevant with the new HierarchicalDataCommunicator design:

• HierarchicalDataCommunicator#collapse(T item, boolean syncClient)
• HierarchicalDataCommunicator#expand(T item, boolean syncClient)
• HierarchicalDataCommunicator#createHierarchyMapper(HierarchicalDataProvider<T, F> dataProvider)