[Tree widget]: Add docs for visibility handling

.vscode/extensions.json

@@ -3,5 +3,6 @@
     "dbaeumer.vscode-eslint",
     "esbenp.prettier-vscode",
     "streetsidesoftware.code-spell-checker",
-  ],
+    "mermaidchart.vscode-mermaid-chart"
+  ]
 }

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

@@ -0,0 +1,48 @@
+<!-- cspell: ignore getcategoriesvisibilitystatus -->
+
+# Categories tree specific visibility handling
+
+This document explains visibility handling for categories tree specific cases.
+
+## Table of contents
+
+- [Getting visibility status](#getting-visibility-status)
+  - [getDefinitionContainersVisibilityStatus](#getdefinitioncontainersvisibilitystatus)
+  - [getCategoriesVisibilityStatus](./SharedVisibilityHandling.md#getcategoriesvisibilitystatus)
+  - [getSubCategoriesVisibilityStatus](./SharedVisibilityHandling.md#getsubcategoriesvisibilitystatus)
+  - [getElementsVisibilityStatus](./SharedVisibilityHandling.md#getelementsvisibilitystatus)
+
+## Getting visibility status
+
+### getDefinitionContainersVisibilityStatus
+
+To determine definition containers' visibility status, get their child categories from cache and call [getCategoriesVisibilityStatus](./SharedVisibilityHandling.md#getcategoriesvisibilitystatus).
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 750
+    useMaxWidth: false
+---
+
+flowchart TD
+  RESULT_Partial[/partial/]
+  RESULT_Visible[/visible/]
+  RESULT_Hidden[/hidden/]
+
+  %% Start
+  TITLE(["<code>getDefinitionContainersVisibilityStatus</code>"]) --> A["Get categories under <code>props.definitionContainerIds</code> from cache. These are categories whose modelId is the same as definition container or categories of child definition containers (can be nested)"]
+
+  PROPS[\"
+    <code>props</code>
+    <div style='text-align: left;'>- definitionContainerIds: **Id64Arg**</div>
+  "\]
+
+  A -- categoryIds --> B["<code><a href='./SharedVisibilityHandling.md#getcategoriesvisibilitystatus'>getCategoriesVisibilityStatus</a>({ categoryIds, modelId: undefined })</code>"]
+
+  %% Results
+  B -- partial --> RESULT_Partial
+  B -- visible --> RESULT_Visible
+  B -- hidden --> RESULT_Hidden
+```

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

@@ -0,0 +1,82 @@
+<!-- cspell: ignore getcategoriesvisibilitystatus -->
+
+# Classifications tree specific visibility handling
+
+This document explains visibility handling for classifications tree specific cases.
+
+## Table of contents
+
+- [Getting visibility status](#getting-visibility-status)
+  - [getClassificationTablesVisibilityStatus](#getclassificationtablesvisibilitystatus)
+  - [getClassificationsVisibilityStatus](#getclassificationsvisibilitystatus)
+  - [getCategoriesVisibilityStatus](./SharedVisibilityHandling.md#getcategoriesvisibilitystatus)
+  - [getElementsVisibilityStatus](./SharedVisibilityHandling.md#getelementsvisibilitystatus)
+
+## Getting visibility status
+
+### getClassificationTablesVisibilityStatus
+
+To determine classification tables' visibility status, get their child categories from cache and call [getCategoriesVisibilityStatus](./SharedVisibilityHandling.md#getcategoriesvisibilitystatus).
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 750
+    useMaxWidth: false
+---
+
+flowchart TD
+  RESULT_Partial[/partial/]
+  RESULT_Visible[/visible/]
+  RESULT_Hidden[/hidden/]
+
+
+  %% Start
+  TITLE(["<code>getClassificationTablesVisibilityStatus</code>"]) --> A["Get categories under <code>props.classificationTableIds</code> from cache. These are categories of child classifications (can be nested)"]
+
+  PROPS[\"
+    <code>props</code>
+    <div style='text-align: left;'>- classificationTableIds: **Id64Arg**</div>
+  "\]
+
+  A -- categoryIds --> B["<code><a href='./SharedVisibilityHandling.md#getcategoriesvisibilitystatus'>getCategoriesVisibilityStatus</a>({ categoryIds, modelId: undefined })</code>"]
+
+  %% Results
+  B -- partial --> RESULT_Partial
+  B -- visible --> RESULT_Visible
+  B -- hidden --> RESULT_Hidden
+```
+
+### getClassificationsVisibilityStatus
+
+To determine classifications' visibility status, get their child categories from cache and call [getCategoriesVisibilityStatus](./SharedVisibilityHandling.md#getcategoriesvisibilitystatus).
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 750
+    useMaxWidth: false
+---
+
+flowchart TD
+  RESULT_Partial[/partial/]
+  RESULT_Visible[/visible/]
+  RESULT_Hidden[/hidden/]
+
+  %% Start
+  TITLE(["<code>getClassificationsVisibilityStatus</code>"]) --> A["Get categories under <code>props.classificationIds</code> from cache. These are related categories and categories of child classifications (can be nested)"]
+
+  PROPS[\"
+    <code>props</code>
+    <div style='text-align: left;'>- classificationIds: **Id64Arg**</div>
+  "\]
+
+  A -- categoryIds --> B["<code><a href='./SharedVisibilityHandling.md#getcategoriesvisibilitystatus'>getCategoriesVisibilityStatus</a>({ categoryIds, modelId: undefined })</code>"]
+
+  %% Results
+  B -- partial --> RESULT_Partial
+  B -- visible --> RESULT_Visible
+  B -- hidden --> RESULT_Hidden
+```

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

@@ -0,0 +1,47 @@
+<!-- cspell: ignore getmodelsvisibilitystatus -->
+
+# Models tree specific visibility handling
+
+This document explains visibility handling for models tree specific cases.
+
+## Table of contents
+
+- [Getting visibility status](#getting-visibility-status)
+  - [getSubjectsVisibilityStatus](#getsubjectsvisibilitystatus)
+  - [getModelsVisibilityStatus](./SharedVisibilityHandling.md#getmodelsvisibilitystatus)
+  - [getCategoriesVisibilityStatus](./SharedVisibilityHandling.md#getcategoriesvisibilitystatus)
+  - [getElementsVisibilityStatus](./SharedVisibilityHandling.md#getelementsvisibilitystatus)
+
+## Getting visibility status
+
+### getSubjectsVisibilityStatus
+
+To determine subjects' visibility status, get their child models from cache and call [getModelsVisibilityStatus](./SharedVisibilityHandling.md#getmodelsvisibilitystatus).
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 750
+    useMaxWidth: false
+---
+
+flowchart TD
+  RESULT_Partial[/partial/]
+  RESULT_Visible[/visible/]
+  RESULT_Hidden[/hidden/]
+
+  %% Start
+  TITLE("<code>getSubjectsVisibilityStatus</code>") --> A["Get models under <code>props.subjectIds</code> from cache. These are related models and models of child subjects (can be nested)"]
+
+  PROPS[\"<code>props</code>
+    <div style='text-align: left;'>- subjectIds: **Id64Arg**</div>
+  "\]
+
+  A -- modelIds --> B["<code><a href='./SharedVisibilityHandling.md#getmodelsvisibilitystatus'>getModelsVisibilityStatus</a>({ modelIds })</code>"]
+
+  %% Results
+  B -- partial --> RESULT_Partial
+  B -- visible --> RESULT_Visible
+  B -- hidden --> RESULT_Hidden
+```