[Tree widget]: Add docs for visibility handling by JonasDov · Pull Request #1606 · iTwin/viewer-components-react

JonasDov · 2026-02-23T10:17:40Z

Added Visibility.md file, it explains the structure of how visibility handling works in tree widget. Also, added diagrams that showcase how visibility status is determined for different types of nodes.

github-actions

Tree-Widget Next benchmark

Benchmark suite	Current: `1dc2819`	Previous: `9e3cf65`	Deviation	Status
`categories tree creates initial filtered view for 50k items`	`1523.75` ms	`1491.45` ms	`2.17%`	〰️
`categories tree creates initial filtered view for 50k items (P95 of main thread blocks)`	`78` ms	`78` ms	`0%`	🟰
`categories tree changing definition container visibility changes visibility for 50k subCategories`	`7353.04` ms	`5447.92` ms	`34.97%`	🚨
`categories tree changing definition container visibility changes visibility for 50k subCategories (P95 of main thread blocks)`	`41` ms	`66` ms	`-37.88%`	〰️
`categories tree changing definition container visibility changes visibility for 50k categories`	`12501.56` ms	`10935.91` ms	`14.32%`	🚨
`categories tree changing definition container visibility changes visibility for 50k categories (P95 of main thread blocks)`	`297` ms	`571` ms	`-47.99%`	✅
`classifications tree loads initial view for iModel with 50k classifications`	`31.18` ms	`37.72` ms	`-17.34%`	〰️
`classifications tree loads initial view for iModel with 50k classifications (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`classifications tree loads first branch for iModel with 50k classifications`	`876.92` ms	`899.54` ms	`-2.51%`	〰️
`classifications tree loads first branch for iModel with 50k classifications (P95 of main thread blocks)`	`119` ms	`79` ms	`50.63%`	〰️
`models tree creates initial filtered view for 50k target items`	`905.78` ms	`889.52` ms	`1.83%`	〰️
`models tree creates initial filtered view for 50k target items (P95 of main thread blocks)`	`69` ms	`82` ms	`-15.85%`	〰️
`models tree validates categories visibility for imodel with 50k categories`	`4749.56` ms	`4572.18` ms	`3.88%`	〰️
`models tree validates categories visibility for imodel with 50k categories (P95 of main thread blocks)`	`170` ms	`175` ms	`-2.86%`	〰️
`models tree changing model visibility changes visibility for 50k elements`	`2080.67` ms	`1994.85` ms	`4.30%`	〰️
`models tree changing model visibility changes visibility for 50k elements (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree changing category visibility changes visibility for 50k elements`	`2057.06` ms	`1999.18` ms	`2.90%`	〰️
`models tree changing category visibility changes visibility for 50k elements (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree changing per-model-category override changes visibility for 50k elements`	`2034.94` ms	`1957.44` ms	`3.96%`	〰️
`models tree changing per-model-category override changes visibility for 50k elements (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree changing element visibility changes only parent nodes visibility with 50k elements`	`2766.17` ms	`2768.95` ms	`-0.10%`	〰️
`models tree changing element visibility changes only parent nodes visibility with 50k elements (P95 of main thread blocks)`	`360` ms	`312` ms	`15.38%`	〰️
`models tree changing element visibility changes only parent nodes visibility with 50k child elements with different categories`	`2747.39` ms	`2696.04` ms	`1.90%`	〰️
`models tree changing element visibility changes only parent nodes visibility with 50k child elements with different categories (P95 of main thread blocks)`	`335` ms	`384` ms	`-12.76%`	〰️

This comment was automatically generated by workflow using github-action-benchmark.

grigasp · 2026-02-23T13:55:39Z

what do you think about using this?

packages/itwin/tree-widget/Visibility.md

grigasp · 2026-02-25T07:25:48Z

packages/itwin/tree-widget/Visibility.md

+  R3[/hidden/]
+
+  %% Start
+  TITLE([getSubjectsVisibilityStatus]) --> A["Get models under Props.subjectIds from cache. These are related models and models of child subjects (can be nested)"]


could we put Props.subjectIds to backticks?

Seems that mermaid diagrams don't understand backticks and show backtick symbols instead. Wrapped in <code> sections instead.

Maybe add the rest, too? E.g. TITLE, PROPS and function calls like

A -- modelIds --> B["<code><a href='./SharedVisibilityHandling.md#getmodelsvisibilitystatus'>getModelsVisibilityStatus</a>({ modelIds })</code>"]

grigasp · 2026-02-25T07:26:37Z

packages/itwin/tree-widget/Visibility.md

+  PROPS[\"Props
+    <div style='text-align: left;'>- subjectIds: **Id64Arg**</div>
+  "\]


For me it would be clearer if Props started with lower case, e.g. props. Interesting in hearing others' thoughts (@saskliutas @MartynasStrazdas)

Renamed to props

packages/itwin/tree-widget/Visibility.md

grigasp · 2026-02-25T07:40:58Z

packages/itwin/tree-widget/Visibility.md

+### Getting visibility status
+
+#### getSubjectsVisibilityStatus


What do you think about structuring them based on the tree they're used in, instead of just having a plain list of diagrams?

Here's what I'm imagining:

Have a separate markdown file per tree + one for shared visibility handling.

Each tree specific markdown would have its specific diagrams (e.g. getSubjectsVisibilityStatus would be in models tree markdown) and reference the shared ones that apply to them (e.g. getModelsVisibilityStatus would be in shared markdown and referenced from models tree markdown).

The "Architecture" section stays, but instead of having all the diagrams it only references them.

Each file will have less diagrams, so we can provide a bit more details. E.g. I think it would be good to have a short description of the diagram. Don't need much for the ones that are clear (e.g. getSubjectsVisibilityStatus), but some of them aren't that clear (e.g. getModelWithCategoryVisibilityStatus) and could use an explanation.

Tried to split up based on your suggestion, added short descriptions. Have a look.

After looking again, I think "Architecture" should be renamed to "Visibility logic" or something like that. The diagrams don't show the architecture.

Also, instead of just linking the files, I'd rather there was a combined TOC for each tree, e.g.:

- Getting visibility status - Models tree - getSubjectsVisibilityStatus - getModelsVisibilityStatus - getCategoriesVisibilityStatus - getElementsVisibilityStatus - Categories tree - getDefinitionContainersVisibilityStatus - getCategoriesVisibilityStatus - getSubCategoriesVisibilityStatus - getElementsVisibilityStatus - Classifications tree - getClassificationTablesVisibilityStatus - getClassificationsVisibilityStatus - getCategoriesVisibilityStatus - getElementsVisibilityStatus

Note: I don't think we need to link utility functions like getAlwaysOrNeverDrawnVisibilityStatus - they get linked from each top-level function diagram.

Renamed to Visibility logic added the suggestion inside Visibility logic

Copilot

Pull request overview

This PR adds comprehensive documentation for visibility handling in the tree widget component. The documentation explains how visibility is determined and changed across different tree types (Models, Categories, and Classifications) and node types, providing detailed architectural insights with Mermaid flowcharts.

Changes:

Added Visibility.md documentation file with detailed architecture explanations and Mermaid flowcharts showing visibility status determination for different node types
Added Mermaid Chart VS Code extension to recommended extensions for easier diagram editing

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
packages/itwin/tree-widget/Visibility.md	New comprehensive documentation file explaining visibility handling architecture, including file structure overview, viewport visibility rules, and detailed flowcharts for visibility status methods
.vscode/extensions.json	Added `mermaidchart.vscode-mermaid-chart` extension to support viewing and editing the Mermaid diagrams in the new documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/itwin/tree-widget/Visibility.md

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

.vscode/extensions.json

packages/itwin/tree-widget/docs/Visibility.md

packages/itwin/tree-widget/docs/ModelsTreeVisibilityHandling.md

packages/itwin/tree-widget/docs/CategoriesTreeVisibilityHandling.md

packages/itwin/tree-widget/src/tree-widget-react/components/trees/common/TreeWidgetViewport.ts

packages/itwin/tree-widget/docs/SharedVisibilityHandling.md

packages/itwin/tree-widget/docs/ClassificationsTreeVisibilityHandling.md

grigasp · 2026-03-10T11:50:38Z

packages/itwin/tree-widget/docs/Visibility.md

+    - Data stored in this cache is requested only once, because it does not change.
+  - Tree-specific id caches ([`CategoriesTreeIdsCache`](../src/tree-widget-react/components/trees/categories-tree/internal/CategoriesTreeIdsCache.ts), [`ClassificationsTreeIdsCache`](../src/tree-widget-react/components/trees/classifications-tree/internal/ClassificationsTreeIdsCache.ts), [`ModelsTreeIdsCache`](../src/tree-widget-react/components/trees/models-tree/internal/ModelsTreeIdsCache.ts)):
+    - Store various tree-specific relationships, (e.g. models tree ids cache stores element's model <-> subject relationship).
+    - Implements `BaseVisibilityHandlerImpl` so each tree-specific cache can be used in [`BaseVisibilityHelper`](../src/tree-widget-react/components/trees/common/internal/visibility/BaseVisibilityHelper.ts).


extends BaseIdsCacheImpl?

grigasp · 2026-03-10T11:52:47Z

packages/itwin/tree-widget/docs/Visibility.md

+    - When changing element or element grouping nodes' visibility, need to put all children (nested as well) into always/never drawn list. This cache is used to retrieve child nodes' ids in such cases.
+    - It is not used (and should not be used) when getting visibility status:
+      - Only total children counts (this is stored on nodes `extendedData` property) and child always/never drawn elements (these are retrieved from [`AlwaysAndNeverDrawnElementInfoCache`](../src/tree-widget-react/components/trees/common/internal/caches/AlwaysAndNeverDrawnElementInfoCache.ts)) are needed for determining visibility.
+      - It should not be used when getting visibility status, since element might have hundreds of thousands of child elements. And retrieving this information for each element in the hierarchy would be very slow.


We already have "It is not used (and should not be used) when getting visibility status" above, so maybe remove that part from this bullet point and start it with "Element might have ..."

grigasp · 2026-03-10T11:58:33Z

packages/itwin/tree-widget/docs/SharedVisibilityHandling.md

+
+# Shared visibility handling
+
+This document explains the shared parts of visibility handling in models, categories and classifications trees. Please read <a href='./Visibility.md#how-visibility-is-determined-in-the-viewport'>how visibility is determined in the viewport</a> before continuing.


should use markdown [label](./link.md#section) syntax for links

grigasp · 2026-03-10T12:08:42Z

packages/itwin/tree-widget/docs/SharedVisibilityHandling.md

+
+This document explains the shared parts of visibility handling in models, categories and classifications trees. Please read <a href='./Visibility.md#how-visibility-is-determined-in-the-viewport'>how visibility is determined in the viewport</a> before continuing.
+
+## Getting visibility status


Maybe add a TOC above this section? The diagrams are big and there's a lot of scroll needed to find one that I'm interested in.

## Table of contents - [Getting visibility status](#getting-visibility-status) - [getSubCategoriesVisibilityStatus](#getsubcategoriesvisibilitystatus) - [getModelsVisibilityStatus](#getmodelsvisibilitystatus) - [getCategoriesVisibilityStatus](#getcategoriesvisibilitystatus) - [getModelWithCategoryVisibilityStatus](#getmodelwithcategoryvisibilitystatus) - [getElementsVisibilityStatus](#getelementsvisibilitystatus) - [getAlwaysOrNeverDrawnVisibilityStatus](#getalwaysorneverdrawnvisibilitystatus)

grigasp · 2026-03-10T12:11:16Z

packages/itwin/tree-widget/docs/ModelsTreeVisibilityHandling.md

+
+This document explains visibility handling for models tree specific cases.
+
+## Getting visibility status


Similar to my other comment, I'd add a TOC here. Also, in addition to getSubjectsVisibilityStatus, I'd link the high-level ones from shared (e.g. status getters for models, categories, elements)

grigasp · 2026-03-10T12:17:21Z

packages/itwin/tree-widget/Visibility.md

+  R3[/hidden/]
+
+  %% Start
+  TITLE([getSubjectsVisibilityStatus]) --> A["Get models under Props.subjectIds from cache. These are related models and models of child subjects (can be nested)"]


Maybe add the rest, too? E.g. TITLE, PROPS and function calls like

A -- modelIds --> B["<code><a href='./SharedVisibilityHandling.md#getmodelsvisibilitystatus'>getModelsVisibilityStatus</a>({ modelIds })</code>"]

grigasp · 2026-03-10T12:22:50Z

packages/itwin/tree-widget/Visibility.md

+### Getting visibility status
+
+#### getSubjectsVisibilityStatus


After looking again, I think "Architecture" should be renamed to "Visibility logic" or something like that. The diagrams don't show the architecture.

Also, instead of just linking the files, I'd rather there was a combined TOC for each tree, e.g.:

- Getting visibility status - Models tree - getSubjectsVisibilityStatus - getModelsVisibilityStatus - getCategoriesVisibilityStatus - getElementsVisibilityStatus - Categories tree - getDefinitionContainersVisibilityStatus - getCategoriesVisibilityStatus - getSubCategoriesVisibilityStatus - getElementsVisibilityStatus - Classifications tree - getClassificationTablesVisibilityStatus - getClassificationsVisibilityStatus - getCategoriesVisibilityStatus - getElementsVisibilityStatus

Note: I don't think we need to link utility functions like getAlwaysOrNeverDrawnVisibilityStatus - they get linked from each top-level function diagram.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/itwin/tree-widget/docs/Visibility.md

packages/itwin/tree-widget/docs/ModelsTreeVisibilityHandling.md

packages/itwin/tree-widget/docs/CategoriesTreeVisibilityHandling.md

packages/itwin/tree-widget/docs/ClassificationsTreeVisibilityHandling.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

[Tree widget]: Add docs for visibility handling

0b2ca40

JonasDov requested review from a team as code owners February 23, 2026 10:17

JonasDov requested review from MartynasStrazdas, grigasp and saskliutas February 23, 2026 10:18

github-actions bot reviewed Feb 23, 2026

View reviewed changes

ben-polinsky approved these changes Feb 23, 2026

View reviewed changes

JonasDov added 3 commits February 24, 2026 17:04

Use mermaid

7212502

Remove white background

9547037

Remove white background #2

eca0bd9

grigasp reviewed Feb 25, 2026

View reviewed changes

Merge branch 'tree-widget/next' into JonasD/visibility-md

1ea8d85

Copilot AI review requested due to automatic review settings February 26, 2026 15:34

Copilot started reviewing on behalf of JonasDov February 26, 2026 15:34 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

packages/itwin/tree-widget/Visibility.md Outdated Show resolved Hide resolved

packages/itwin/tree-widget/Visibility.md Outdated Show resolved Hide resolved

packages/itwin/tree-widget/Visibility.md Outdated Show resolved Hide resolved

JonasDov added 3 commits March 2, 2026 14:18

Merge branch 'tree-widget/next' into JonasD/visibility-md

934c316

Address comments

4ffaafe

Merge branch 'tree-widget/next' into JonasD/visibility-md

9491989

JonasDov requested a review from Copilot March 3, 2026 13:20

Copilot started reviewing on behalf of JonasDov March 3, 2026 13:20 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

JonasDov added 5 commits March 3, 2026 15:33

Remove comma

e3f95a7

Remove '

cba0696

Copilot alwaysDrawn suggestion

59a227c

relationship

e9bd9aa

Explain always drawn exclusive flag

2eb2e5f

JonasDov requested a review from grigasp March 5, 2026 10:58

Merge branch 'tree-widget/next' into JonasD/visibility-md

19766eb

Merge branch 'tree-widget/next' into JonasD/visibility-md

5646885

grigasp reviewed Mar 10, 2026

View reviewed changes

JonasDov added 2 commits March 19, 2026 16:39

Address comments

ad77adf

Merge branch 'tree-widget/next' into JonasD/visibility-md

f2f427c

JonasDov requested a review from Copilot March 20, 2026 12:50

Copilot started reviewing on behalf of JonasDov March 20, 2026 12:51 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

JonasDov and others added 3 commits March 20, 2026 16:22

Update packages/itwin/tree-widget/docs/Visibility.md

7e50627

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update packages/itwin/tree-widget/docs/Visibility.md

dce1d8d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Address comments

1dc2819

		### Getting visibility status

		#### getSubjectsVisibilityStatus


		# Shared visibility handling

		This document explains the shared parts of visibility handling in models, categories and classifications trees. Please read <a href='./Visibility.md#how-visibility-is-determined-in-the-viewport'>how visibility is determined in the viewport</a> before continuing.


		This document explains the shared parts of visibility handling in models, categories and classifications trees. Please read <a href='./Visibility.md#how-visibility-is-determined-in-the-viewport'>how visibility is determined in the viewport</a> before continuing.

		## Getting visibility status


		This document explains visibility handling for models tree specific cases.

		## Getting visibility status

Conversation

JonasDov commented Feb 23, 2026

Uh oh!

github-actions bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Tree-Widget Next benchmark

Uh oh!

grigasp commented Feb 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot left a comment •

edited

Loading