[Tree widget]: add learning snippets on `next` by JonasDov · Pull Request #1780 · iTwin/viewer-components-react

JonasDov · 2026-08-17T12:05:34Z

part of #1737

Added more learning snippets for trees' configurations, TreeWidgetViewport, SharedTreeContextProvider, tree actions, classifications tree.
Updated readme to include newly added learning snippets.

Copilot

Pull request overview

Adds additional “learning snippets” documentation and test-backed examples for Tree Widget v4, expanding coverage around integration patterns (viewport/context/actions) and new/alpha trees (Classifications). This supports the v4 documentation effort described in #1737.

Changes:

Expanded @itwin/tree-widget-react README with new sections and snippets (tree integration, hierarchy config, actions, classifications).
Added/updated learning-snippets tests to generate and validate the new extracted snippets.
Updated learning-snippets test configuration (timeouts) and added a schema dependency for classifications examples.

Reviewed changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/tree-widget/README.md	Adds new documentation sections/snippets for tree integration, hierarchy configuration, actions, and classifications.
apps/learning-snippets/vitest.config.ts	Increases Vitest test/hook timeouts to reduce flakiness for longer-running snippet tests.
apps/learning-snippets/src/test/tree-widget/Usage.test.tsx	Updates usage snippet test to include `isSearchable` and forward `searchText`.
apps/learning-snippets/src/test/tree-widget/TreeIntegration.test.tsx	Adds new snippet-backed tests for explicit/custom viewport usage and shared tree context.
apps/learning-snippets/src/test/tree-widget/TestUtils.tsx	Removes extraction markers from initialization snippet source (moved to dedicated test).
apps/learning-snippets/src/test/tree-widget/ModelsTree.test.tsx	Adds snippet-backed tests for hierarchy config and tree actions; adjusts imports/util usage.
apps/learning-snippets/src/test/tree-widget/Localization.test.tsx	Updates snippet to wrap direct usage with `SharedTreeContextProvider` + localization provider.
apps/learning-snippets/src/test/tree-widget/Initialization.test.ts	Adds new snippet-backed test for initializing TreeWidget with a custom logger.
apps/learning-snippets/src/test/tree-widget/ClassificationsTree.test.tsx	Adds extensive snippet-backed tests/examples for the alpha Classifications tree (config/search/instance search/multi-iModel).
apps/learning-snippets/src/test/tree-widget/CategoriesTree.test.tsx	Adds snippet-backed test for categories hierarchy configuration.
apps/learning-snippets/src/setup.ts	Extends Testing Library async utility timeout.
apps/learning-snippets/package.json	Adds `@bentley/classification-systems-schema` dependency for classifications examples.
apps/learning-snippets/pnpm-lock.yaml	Lockfile updates for the new dependency and related resolution changes.

Files not reviewed (1)

apps/learning-snippets/pnpm-lock.yaml: Generated file

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

github-actions

Tree-Widget Next benchmark

Benchmark suite	Current: `6db6efb`	Previous: `1294455`	Deviation	Status
`models tree 50k 3D elements search > get search paths`	`889` ms	`868` ms	`2.42%`	〰️
`models tree 50k 3D elements search > get search paths (P95 of main thread blocks)`	`61` ms	`60` ms	`1.67%`	〰️
`models tree 50k 3D elements search > load hierarchy from search paths`	`115279` ms	`115631` ms	`-0.30%`	〰️
`models tree 50k 3D elements search > load hierarchy from search paths (P95 of main thread blocks)`	`96` ms	`98` ms	`-2.04%`	〰️
`models tree 50k categories > collect nodes`	`2981` ms	`2970` ms	`0.37%`	〰️
`models tree 50k categories > collect nodes (P95 of main thread blocks)`	`106` ms	`108` ms	`-1.85%`	〰️
`models tree 50k categories > validate initial visibility`	`1825` ms	`1848` ms	`-1.24%`	〰️
`models tree 50k categories > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k categories > change visibility`	`340` ms	`199` ms	`70.85%`	🚨
`models tree 50k categories > change visibility (P95 of main thread blocks)`	`190` ms	`51` ms	`272.55%`	🚨
`models tree 50k categories > validate changed visibility`	`2361` ms	`2404` ms	`-1.79%`	〰️
`models tree 50k categories > validate changed visibility (P95 of main thread blocks)`	`26` ms	`27` ms	`-3.70%`	〰️
`models tree 50k 3D elements > collect nodes`	`46305` ms	`46633` ms	`-0.70%`	〰️
`models tree 50k 3D elements > collect nodes (P95 of main thread blocks)`	`72` ms	`72` ms	`0%`	🟰
`models tree 50k 3D elements > validate initial visibility`	`1396` ms	`1383` ms	`0.94%`	〰️
`models tree 50k 3D elements > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > change model visibility`	`125` ms	`116` ms	`7.76%`	〰️
`models tree 50k 3D elements > change model visibility (P95 of main thread blocks)`	`24` ms	`25` ms	`-4%`	〰️
`models tree 50k 3D elements > validate changed model visibility`	`2132` ms	`2123` ms	`0.42%`	〰️
`models tree 50k 3D elements > validate changed model visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > change category node visibility`	`474` ms	`476` ms	`-0.42%`	〰️
`models tree 50k 3D elements > change category node visibility (P95 of main thread blocks)`	`36` ms	`27` ms	`33.33%`	〰️
`models tree 50k 3D elements > validate changed category visibility`	`1456` ms	`1510` ms	`-3.58%`	〰️
`models tree 50k 3D elements > validate changed category visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > validate per-model category override`	`1560` ms	`1477` ms	`5.62%`	〰️
`models tree 50k 3D elements > validate per-model category override (P95 of main thread blocks)`	`111` ms	`0` ms	`11100%`	🚨
`models tree 50k 3D elements > change element visibility`	`49` ms	`39` ms	`25.64%`	〰️
`models tree 50k 3D elements > change element visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > validate changed element visibility`	`2308` ms	`2337` ms	`-1.24%`	〰️
`models tree 50k 3D elements > validate changed element visibility (P95 of main thread blocks)`	`68` ms	`117` ms	`-41.88%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes`	`64043` ms	`64450` ms	`-0.63%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes (P95 of main thread blocks)`	`66` ms	`71` ms	`-7.04%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility`	`2132` ms	`2071` ms	`2.95%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`49` ms	`0` ms	`4900%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > change visibility`	`53` ms	`51` ms	`3.92%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > change visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility`	`5607` ms	`5715` ms	`-1.89%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`63` ms	`126` ms	`-50%`	✅
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes`	`65920` ms	`64450` ms	`2.28%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes (P95 of main thread blocks)`	`66` ms	`71` ms	`-7.04%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility`	`2310` ms	`2071` ms	`11.54%`	🚨
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`36` ms	`0` ms	`3600%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > change visibility`	`52` ms	`51` ms	`1.96%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > change visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility`	`7025` ms	`5715` ms	`22.92%`	🚨
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`119` ms	`126` ms	`-5.56%`	〰️
`categories tree 50k subCategories search > get search paths`	`993` ms	`1087` ms	`-8.65%`	〰️
`categories tree 50k subCategories search > get search paths (P95 of main thread blocks)`	`44` ms	`75` ms	`-41.33%`	〰️
`categories tree 50k subCategories search > load hierarchy from search paths`	`5764` ms	`5911` ms	`-2.49%`	〰️
`categories tree 50k subCategories search > load hierarchy from search paths (P95 of main thread blocks)`	`57` ms	`61` ms	`-6.56%`	〰️
`categories tree 50k subCategories > collect nodes`	`5706` ms	`5846` ms	`-2.39%`	〰️
`categories tree 50k subCategories > collect nodes (P95 of main thread blocks)`	`35` ms	`35` ms	`0%`	🟰
`categories tree 50k subCategories > validate initial visibility`	`1017` ms	`1045` ms	`-2.68%`	〰️
`categories tree 50k subCategories > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`categories tree 50k subCategories > change visibility`	`354` ms	`352` ms	`0.57%`	〰️
`categories tree 50k subCategories > change visibility (P95 of main thread blocks)`	`22` ms	`26` ms	`-15.38%`	〰️
`categories tree 50k subCategories > validate changed visibility`	`1087` ms	`1086` ms	`0.09%`	〰️
`categories tree 50k subCategories > validate changed visibility (P95 of main thread blocks)`	`27` ms	`29` ms	`-6.90%`	〰️
`categories tree 50k categories and excluded classes > collect nodes`	`114278` ms	`114867` ms	`-0.51%`	〰️
`categories tree 50k categories and excluded classes > collect nodes (P95 of main thread blocks)`	`101` ms	`136` ms	`-25.74%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility`	`5544` ms	`5251` ms	`5.58%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`58` ms	`47` ms	`23.40%`	〰️
`categories tree 50k categories and excluded classes > change visibility`	`808` ms	`829` ms	`-2.53%`	〰️
`categories tree 50k categories and excluded classes > change visibility (P95 of main thread blocks)`	`53` ms	`63` ms	`-15.87%`	〰️
`categories tree 50k categories and excluded classes > validate changed visibility`	`5537` ms	`5756` ms	`-3.80%`	〰️
`categories tree 50k categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`34` ms	`35` ms	`-2.86%`	〰️
`categories tree 50k categories and excluded classes > collect nodes`	`115887` ms	`114867` ms	`0.89%`	〰️
`categories tree 50k categories and excluded classes > collect nodes (P95 of main thread blocks)`	`119` ms	`136` ms	`-12.50%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility`	`5639` ms	`5251` ms	`7.39%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`59` ms	`47` ms	`25.53%`	〰️
`categories tree 50k categories and excluded classes > change visibility`	`801` ms	`829` ms	`-3.38%`	〰️
`categories tree 50k categories and excluded classes > change visibility (P95 of main thread blocks)`	`80` ms	`63` ms	`26.98%`	〰️
`categories tree 50k categories and excluded classes > validate changed visibility`	`7935` ms	`5756` ms	`37.86%`	🚨
`categories tree 50k categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`49` ms	`35` ms	`40%`	〰️
`classifications tree 50k classifications search > get search paths`	`2295` ms	`2385` ms	`-3.77%`	〰️
`classifications tree 50k classifications search > get search paths (P95 of main thread blocks)`	`194` ms	`200` ms	`-3%`	〰️
`classifications tree 50k classifications search > load hierarchy from search paths`	`64453` ms	`64635` ms	`-0.28%`	〰️
`classifications tree 50k classifications search > load hierarchy from search paths (P95 of main thread blocks)`	`24` ms	`27` ms	`-11.11%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes`	`33414` ms	`33578` ms	`-0.49%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes (P95 of main thread blocks)`	`62` ms	`81` ms	`-23.46%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility`	`2879` ms	`2957` ms	`-2.64%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`classifications tree 50k classifications and excluded classes > change visibility`	`175` ms	`163` ms	`7.36%`	〰️
`classifications tree 50k classifications and excluded classes > change visibility (P95 of main thread blocks)`	`23` ms	`26` ms	`-11.54%`	〰️
`classifications tree 50k classifications and excluded classes > validate changed visibility`	`3511` ms	`3529` ms	`-0.51%`	〰️
`classifications tree 50k classifications and excluded classes > validate changed visibility (P95 of main thread blocks)`	`71` ms	`99` ms	`-28.28%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes`	`34137` ms	`33578` ms	`1.66%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes (P95 of main thread blocks)`	`56` ms	`81` ms	`-30.86%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility`	`2827` ms	`2957` ms	`-4.40%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`classifications tree 50k classifications and excluded classes > change visibility`	`167` ms	`163` ms	`2.45%`	〰️
`classifications tree 50k classifications and excluded classes > change visibility (P95 of main thread blocks)`	`26` ms	`26` ms	`0%`	🟰
`classifications tree 50k classifications and excluded classes > validate changed visibility`	`3348` ms	`3529` ms	`-5.13%`	〰️
`classifications tree 50k classifications and excluded classes > validate changed visibility (P95 of main thread blocks)`	`49` ms	`99` ms	`-50.51%`	〰️

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

grigasp · 2026-08-18T07:45:47Z

+          type TreeActionsProps = Parameters<NonNullable<Parameters<typeof ModelsTreeComponent>[0]["getInlineActions"]>>[0];
+          type TreeActionTargetNode = TreeActionsProps["targetNode"];


These may look a bit scary. Maybe change the callbacks in ModelsTreeWithActionsProps to simply take node's label? That would be enough for us to verify they're called, and consumers would still see in the example that getInlineActions/getMenuActions/getContextMenuActions get multiple arguments like targetNode, selectedNodes & CommonTreeRendererProps

grigasp · 2026-08-18T07:46:36Z

+          const showPropertiesSpy = vi.fn();
+          const { getByText, getByRole } = render(<ModelsTreeWithActions onInspect={vi.fn()} onExport={vi.fn()} onShowProperties={showPropertiesSpy} />);
+          await waitFor(() => getByText("Model with actions"));
+          // inline and overflow menu actions are only rendered for a hovered or focused node, so only the context menu is exercised here


Is there an issue to get the node into the hovered or focused state? I think it would be good to exercise all 3 buttons.

grigasp · 2026-08-18T08:17:01Z

+                treeLabel="Configured classifications tree"
+                selectionStorage={selectionStorage}
+                hierarchyConfig={{
+                  rootClassificationSystemCode: "My Classification System",


A comment for rootClassificationSystemCode would be nice

grigasp · 2026-08-18T08:18:44Z

+        // __PUBLISH_EXTRACT_START__ TreeWidget.ClassificationsTreeMultipleIModelsExample
+        interface VersionedClassificationsTreeDefinitionProps {
+          imodelVersions: IModelConnection[];
+          targetItems: InstanceKey[];


what purpose does targetItems serve in this example?

grigasp · 2026-08-18T08:21:47Z


+### Classifications tree
+
+The Classifications tree displays classifications and the 3D geometric elements assigned to them. It supports visibility controls, label search, classification and element instance-key search, and classification renaming. The APIs of this tree are `@alpha` and may change between releases.


The APIs of this tree are @alpha and may change between releases.

I'm thinking maybe it's time to switch them to @beta (probably not this PR)?

grigasp · 2026-08-18T08:28:39Z

+
+#### Configuring the hierarchy and visibility
+
+The `hierarchyConfig` can select a root classification system and exclude element classes. When classifications are related to categories through a custom relationship, that relationship can be configured for visibility resolution:


When classifications are related to categories through a custom relationship, that relationship can be configured for visibility resolution

I think classificationToCategoriesRelationshipSpecification could use a more elaborate description. The primary reasons you'd want to use it:

When this relationship is NOT specified, we fall back to using Classification -> ClassificationSystems.ElementHasClassifications -> Element -> Category relationship path, which makes the queries slower.

When classification doesn't have any elements, we can't find the associated categories without this spec. So changing classification's display won't affect the underlying categories.

[Tree widget]: add learning snippets on next

4bd03bf

JonasDov requested a review from a team as a code owner August 17, 2026 12:05

Copilot AI lite review requested due to automatic review settings August 17, 2026 12:05

JonasDov requested a review from a team as a code owner August 17, 2026 12:05

Copilot started reviewing on behalf of JonasDov August 17, 2026 12:06 View session

Copilot AI reviewed Aug 17, 2026

View reviewed changes

Comment thread packages/tree-widget/README.md

Spell check

6db6efb

github-actions Bot reviewed Aug 17, 2026

View reviewed changes

grigasp reviewed Aug 18, 2026

View reviewed changes

Navigation Menu

Uh oh!

[Tree widget]: add learning snippets on `next` - #1780

[Tree widget]: add learning snippets on `next`#1780
JonasDov wants to merge 2 commits into
tree-widget/nextfrom
JonasD/lerning-snippets

JonasDov commented Aug 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

github-actions Bot left a comment •

edited

Loading

Uh oh!

grigasp Aug 18, 2026

Uh oh!

grigasp Aug 18, 2026

Uh oh!

grigasp Aug 18, 2026

Uh oh!

grigasp Aug 18, 2026

Uh oh!

grigasp Aug 18, 2026

Uh oh!

grigasp Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		type TreeActionsProps = Parameters<NonNullable<Parameters<typeof ModelsTreeComponent>[0]["getInlineActions"]>>[0];
		type TreeActionTargetNode = TreeActionsProps["targetNode"];


		### Classifications tree

		The Classifications tree displays classifications and the 3D geometric elements assigned to them. It supports visibility controls, label search, classification and element instance-key search, and classification renaming. The APIs of this tree are `@alpha` and may change between releases.


		#### Configuring the hierarchy and visibility

		The `hierarchyConfig` can select a root classification system and exclude element classes. When classifications are related to categories through a custom relationship, that relationship can be configured for visibility resolution:

Uh oh!

Conversation

JonasDov commented Aug 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

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 Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

grigasp Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

grigasp Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

grigasp Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

grigasp Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

grigasp Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot left a comment •

edited

Loading