From addbb6ffebd0d194e46be0f10c22af026f5cab78 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Mon, 23 Mar 2026 05:36:32 -0400 Subject: [PATCH] fix(ui): move treeview-storage.js to Host wwwroot where static files are served --- docs/plans/2026-03-23-treeview-component.md | 1128 +++++++++++++++++ ...026-03-23-treeview-component.md.tasks.json | 16 + docs/requirements/Component-TreeView.md | 626 +++++++++ .../wwwroot/js/treeview-storage.js | 0 4 files changed, 1770 insertions(+) create mode 100644 docs/plans/2026-03-23-treeview-component.md create mode 100644 docs/plans/2026-03-23-treeview-component.md.tasks.json create mode 100644 docs/requirements/Component-TreeView.md rename src/{ScadaLink.CentralUI => ScadaLink.Host}/wwwroot/js/treeview-storage.js (100%) diff --git a/docs/plans/2026-03-23-treeview-component.md b/docs/plans/2026-03-23-treeview-component.md new file mode 100644 index 0000000..bb30792 --- /dev/null +++ b/docs/plans/2026-03-23-treeview-component.md @@ -0,0 +1,1128 @@ +# TreeView Component Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task. + +**Goal:** Build a reusable generic `TreeView` Blazor component and integrate it into the Instances, Data Connections, and Areas pages. + +**Architecture:** Generic component in `Components/Shared/` with `@typeparam TItem`, render fragments for content/context menu, internal expand/collapse state with sessionStorage persistence via JS interop, and ARIA accessibility. Three pages refactored to use it. + +**Tech Stack:** Blazor Server, Bootstrap 5, bUnit 2.0.33-preview, xUnit, IJSRuntime for sessionStorage. + +--- + +### Task 1: Create TreeView.razor — Core Rendering (R1, R2, R3, R4, R14) + +**Files:** +- Create: `src/ScadaLink.CentralUI/Components/Shared/TreeView.razor` + +**Step 1: Write the failing tests** + +Create test file with core rendering tests. + +Create: `tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs` + +```csharp +using Bunit; +using ScadaLink.CentralUI.Components.Shared; + +namespace ScadaLink.CentralUI.Tests; + +public class TreeViewTests : BunitContext +{ + // Test model + record TestNode(string Key, string Label, List Children); + + private static List SimpleRoots() => new() + { + new("a", "Alpha", new() + { + new("a1", "Alpha-1", new()), + new("a2", "Alpha-2", new() + { + new("a2x", "Alpha-2-X", new()) + }) + }), + new("b", "Beta", new()), + }; + + private IRenderedComponent> RenderTree( + List? items = null, + Action>>? configure = null) + { + return Render>(parameters => + { + parameters + .Add(p => p.Items, items ?? SimpleRoots()) + .Add(p => p.ChildrenSelector, n => n.Children) + .Add(p => p.HasChildrenSelector, n => n.Children.Count > 0) + .Add(p => p.KeySelector, n => n.Key) + .Add(p => p.NodeContent, node => $"{node.Label}"); + configure?.Invoke(parameters); + }); + } + + [Fact] + public void Renders_RootLevelItems() + { + var cut = RenderTree(); + var rootItems = cut.FindAll("[role='tree'] > li[role='treeitem']"); + Assert.Equal(2, rootItems.Count); + Assert.Contains("Alpha", rootItems[0].TextContent); + Assert.Contains("Beta", rootItems[1].TextContent); + } + + [Fact] + public void Renders_EmptyContent_WhenNoItems() + { + var cut = RenderTree(items: new(), configure: p => + p.Add(x => x.EmptyContent, "Nothing here")); + Assert.Contains("Nothing here", cut.Markup); + } + + [Fact] + public void LeafNodes_HaveNoToggle() + { + var cut = RenderTree(); + // Beta is a leaf (no children) + var betaItem = cut.FindAll("li[role='treeitem']") + .First(li => li.TextContent.Contains("Beta")); + Assert.Empty(betaItem.QuerySelectorAll(".tv-toggle")); + } + + [Fact] + public void BranchNodes_ShowCollapsedToggle() + { + var cut = RenderTree(); + var alphaItem = cut.FindAll("li[role='treeitem']") + .First(li => li.TextContent.Contains("Alpha")); + var toggle = alphaItem.QuerySelector(".tv-toggle"); + Assert.NotNull(toggle); + Assert.Equal("false", alphaItem.GetAttribute("aria-expanded")); + } + + [Fact] + public void CollapsedBranch_ChildrenNotInDom() + { + var cut = RenderTree(); + // Children of collapsed Alpha should not be in the DOM + Assert.DoesNotContain("Alpha-1", cut.Markup); + } + + [Fact] + public void ClickToggle_ExpandsNode_ShowsChildren() + { + var cut = RenderTree(); + var toggle = cut.Find(".tv-toggle"); + toggle.Click(); + Assert.Contains("Alpha-1", cut.Markup); + Assert.Contains("Alpha-2", cut.Markup); + } + + [Fact] + public void ClickToggle_CollapseExpandedNode() + { + var cut = RenderTree(); + var toggle = cut.Find(".tv-toggle"); + toggle.Click(); // expand + Assert.Contains("Alpha-1", cut.Markup); + toggle.Click(); // collapse + Assert.DoesNotContain("Alpha-1", cut.Markup); + } + + [Fact] + public void DeepNesting_ExpandParentThenChild() + { + var cut = RenderTree(); + // Expand Alpha + cut.Find(".tv-toggle").Click(); + // Now find Alpha-2's toggle and expand it + var a2Item = cut.FindAll("li[role='treeitem']") + .First(li => li.TextContent.Contains("Alpha-2")); + a2Item.QuerySelector(".tv-toggle")!.Click(); + Assert.Contains("Alpha-2-X", cut.Markup); + } + + [Fact] + public void InitiallyExpanded_ExpandsMatchingNodes() + { + var cut = RenderTree(configure: p => + p.Add(x => x.InitiallyExpanded, n => n.Key == "a")); + // Alpha should be expanded showing children + Assert.Contains("Alpha-1", cut.Markup); + Assert.Contains("Alpha-2", cut.Markup); + } + + [Fact] + public void RootUl_HasTreeRole() + { + var cut = RenderTree(); + Assert.NotNull(cut.Find("ul[role='tree']")); + } + + [Fact] + public void NodeLi_HasTreeitemRole() + { + var cut = RenderTree(); + var items = cut.FindAll("li[role='treeitem']"); + Assert.True(items.Count >= 2); + } + + [Fact] + public void ExpandedBranch_HasAriaExpandedTrue() + { + var cut = RenderTree(configure: p => + p.Add(x => x.InitiallyExpanded, n => n.Key == "a")); + var alphaItem = cut.FindAll("li[role='treeitem']") + .First(li => li.TextContent.Contains("Alpha")); + Assert.Equal("true", alphaItem.GetAttribute("aria-expanded")); + } + + [Fact] + public void ChildGroup_HasGroupRole() + { + var cut = RenderTree(configure: p => + p.Add(x => x.InitiallyExpanded, n => n.Key == "a")); + Assert.NotNull(cut.Find("ul[role='group']")); + } + + [Fact] + public void Indentation_ChildrenIndentedByIndentPx() + { + var cut = RenderTree(configure: p => + { + p.Add(x => x.InitiallyExpanded, n => n.Key == "a"); + p.Add(x => x.IndentPx, 30); + }); + // Alpha-1 is depth 1 → padding-left should be 30px + var a1Row = cut.FindAll(".tv-row") + .First(r => r.TextContent.Contains("Alpha-1")); + Assert.Contains("padding-left: 30px", a1Row.GetAttribute("style") ?? ""); + } +} +``` + +**Step 2: Run tests to verify they fail** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests" -v minimal` +Expected: Compilation error — `TreeView` component doesn't exist yet. + +**Step 3: Implement TreeView.razor** + +Create: `src/ScadaLink.CentralUI/Components/Shared/TreeView.razor` + +The component should: +- Accept `@typeparam TItem` with all parameters from the API summary in the requirements doc. +- Use a `HashSet _expandedKeys` for expand/collapse state. +- Render recursively: a private `RenderNode(TItem item, int depth)` method outputting `
  • ` with toggle span (`.tv-toggle`), content area (`.tv-content`), and recursive `
      ` for children. +- Each row `
      ` has `style="padding-left: {depth * IndentPx}px"`. +- Branch toggle: `` showing `+` or `−`. +- Leaf nodes: no toggle, but same left padding alignment (the content area starts at the same x as branch content — add a spacer element the same width as the toggle). +- `aria-expanded` on branch `
    • `, `role="group"` on child `
        `. +- When collapsed, do NOT render child `
          ` at all (not just `display:none`). +- `EmptyContent` shown when `Items` is null or empty. +- Apply `InitiallyExpanded` in `OnParametersSet` on first render only: walk all items recursively, add matching keys to `_expandedKeys`. + +**Step 4: Run tests to verify they pass** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests" -v minimal` +Expected: All tests PASS. + +**Step 5: Commit** + +```bash +git add src/ScadaLink.CentralUI/Components/Shared/TreeView.razor tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs +git commit -m "feat(ui): add TreeView component with core rendering, expand/collapse, ARIA (R1-R4, R14)" +``` + +--- + +### Task 2: Add Selection Support (R5) + +**Files:** +- Modify: `src/ScadaLink.CentralUI/Components/Shared/TreeView.razor` +- Modify: `tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs` + +**Step 1: Write the failing tests** + +Add to `TreeViewTests.cs`: + +```csharp +[Fact] +public void Selection_Disabled_ClickDoesNotFireCallback() +{ + object? selected = null; + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, false); + p.Add(x => x.SelectedKeyChanged, (object? key) => selected = key); + }); + cut.Find(".tv-content").Click(); + Assert.Null(selected); +} + +[Fact] +public void Selection_Enabled_ClickContentFiresCallback() +{ + object? selected = null; + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKeyChanged, (object? key) => selected = key); + }); + // Click Alpha's content area + var alphaContent = cut.FindAll(".tv-content") + .First(c => c.TextContent.Contains("Alpha")); + alphaContent.Click(); + Assert.Equal("a", selected); +} + +[Fact] +public void Selection_ClickToggle_DoesNotChangeSelection() +{ + object? selected = null; + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKeyChanged, (object? key) => selected = key); + }); + cut.Find(".tv-toggle").Click(); + Assert.Null(selected); +} + +[Fact] +public void Selection_SelectedNode_HasCssClass() +{ + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKey, (object)"a"); + }); + var alphaRow = cut.FindAll(".tv-row") + .First(r => r.TextContent.Contains("Alpha")); + Assert.Contains("bg-primary", alphaRow.ClassList); +} + +[Fact] +public void Selection_CustomCssClass_Applied() +{ + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKey, (object)"a"); + p.Add(x => x.SelectedCssClass, "my-highlight"); + }); + var alphaRow = cut.FindAll(".tv-row") + .First(r => r.TextContent.Contains("Alpha")); + Assert.Contains("my-highlight", alphaRow.ClassList); +} + +[Fact] +public void Selection_AriaSelected_SetOnSelectedNode() +{ + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKey, (object)"a"); + }); + var alphaItem = cut.FindAll("li[role='treeitem']") + .First(li => li.TextContent.Contains("Alpha")); + Assert.Equal("true", alphaItem.GetAttribute("aria-selected")); +} +``` + +**Step 2: Run tests to verify they fail** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests.Selection" -v minimal` +Expected: FAIL + +**Step 3: Implement selection in TreeView.razor** + +Add to the component: +- When `Selectable` is true and the `.tv-content` area is clicked, invoke `SelectedKeyChanged` with the node's key. +- When rendering, if a node's key equals `SelectedKey`, add `SelectedCssClass` to the `.tv-row` div. +- Add `aria-selected="true"` on the selected `
        • `. +- The `.tv-toggle` click handler must NOT propagate to selection (use `@onclick:stopPropagation` or separate event handling). + +**Step 4: Run tests to verify they pass** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests" -v minimal` +Expected: All PASS. + +**Step 5: Commit** + +```bash +git add src/ScadaLink.CentralUI/Components/Shared/TreeView.razor tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs +git commit -m "feat(ui): add selection support to TreeView (R5)" +``` + +--- + +### Task 3: Add Session Storage Persistence (R11) + +**Files:** +- Create: `src/ScadaLink.CentralUI/wwwroot/js/treeview-storage.js` +- Modify: `src/ScadaLink.CentralUI/Components/Shared/TreeView.razor` +- Modify: `tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs` + +**Step 1: Write the failing tests** + +Add to `TreeViewTests.cs`: + +```csharp +[Fact] +public void SessionStorage_Null_NoJsInteropCalls() +{ + var cut = RenderTree(configure: p => + p.Add(x => x.StorageKey, (string?)null)); + // Expand a node + cut.Find(".tv-toggle").Click(); + // No JS interop should have been invoked + Assert.Empty(JSInterop.Invocations); +} + +[Fact] +public void SessionStorage_Set_ExpandWritesToStorage() +{ + JSInterop.SetupVoid("treeviewStorage.save", _ => true); + JSInterop.Setup("treeviewStorage.load", _ => true).SetResult(null); + var cut = RenderTree(configure: p => + p.Add(x => x.StorageKey, "test-tree")); + // Expand Alpha + cut.Find(".tv-toggle").Click(); + var saveInvocations = JSInterop.Invocations + .Where(i => i.Identifier == "treeviewStorage.save"); + Assert.NotEmpty(saveInvocations); +} + +[Fact] +public void SessionStorage_RestoresExpandedOnMount() +{ + // Pre-populate storage with Alpha expanded + JSInterop.Setup("treeviewStorage.load", _ => true) + .SetResult("[\"a\"]"); + JSInterop.SetupVoid("treeviewStorage.save", _ => true); + var cut = RenderTree(configure: p => + p.Add(x => x.StorageKey, "test-tree")); + // Alpha should be expanded from storage + Assert.Contains("Alpha-1", cut.Markup); +} + +[Fact] +public void SessionStorage_TakesPrecedenceOverInitiallyExpanded() +{ + // Storage says nothing expanded, but InitiallyExpanded says expand Alpha + JSInterop.Setup("treeviewStorage.load", _ => true) + .SetResult("[]"); + JSInterop.SetupVoid("treeviewStorage.save", _ => true); + var cut = RenderTree(configure: p => + { + p.Add(x => x.StorageKey, "test-tree"); + p.Add(x => x.InitiallyExpanded, n => n.Key == "a"); + }); + // Storage (empty) takes precedence — Alpha should NOT be expanded + Assert.DoesNotContain("Alpha-1", cut.Markup); +} +``` + +**Step 2: Run tests to verify they fail** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests.SessionStorage" -v minimal` +Expected: FAIL + +**Step 3: Create JS interop file** + +Create: `src/ScadaLink.CentralUI/wwwroot/js/treeview-storage.js` + +```javascript +window.treeviewStorage = { + save: function (storageKey, keysJson) { + sessionStorage.setItem("treeview:" + storageKey, keysJson); + }, + load: function (storageKey) { + return sessionStorage.getItem("treeview:" + storageKey); + } +}; +``` + +Add a ` +``` + +**Step 4: Implement persistence in TreeView.razor** + +- Inject `[Inject] private IJSRuntime JSRuntime { get; set; } = default!;` +- In `OnAfterRenderAsync(bool firstRender)`: if `firstRender && StorageKey != null`, call `JSRuntime.InvokeAsync("treeviewStorage.load", StorageKey)`. If result is not null, deserialize JSON array of keys into `_expandedKeys` and call `StateHasChanged()`. Set a `_storageLoaded = true` flag. +- Only apply `InitiallyExpanded` when `StorageKey` is null OR storage returned null (no prior state). +- On every `ToggleExpand`, if `StorageKey != null`, serialize `_expandedKeys` to JSON and call `JSRuntime.InvokeVoidAsync("treeviewStorage.save", StorageKey, json)`. + +**Step 5: Run tests to verify they pass** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests" -v minimal` +Expected: All PASS. + +**Step 6: Commit** + +```bash +git add src/ScadaLink.CentralUI/wwwroot/js/treeview-storage.js src/ScadaLink.CentralUI/Components/Shared/TreeView.razor tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs +git commit -m "feat(ui): add sessionStorage persistence for TreeView expansion state (R11)" +``` + +--- + +### Task 4: Add ExpandAll, CollapseAll, RevealNode (R12, R13) + +**Files:** +- Modify: `src/ScadaLink.CentralUI/Components/Shared/TreeView.razor` +- Modify: `tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs` + +**Step 1: Write the failing tests** + +Add to `TreeViewTests.cs`: + +```csharp +[Fact] +public void ExpandAll_ExpandsAllBranches() +{ + var cut = RenderTree(); + cut.Instance.ExpandAll(); + cut.Render(); + // All nested content should be visible + Assert.Contains("Alpha-1", cut.Markup); + Assert.Contains("Alpha-2", cut.Markup); + Assert.Contains("Alpha-2-X", cut.Markup); +} + +[Fact] +public void CollapseAll_CollapsesAllBranches() +{ + var cut = RenderTree(configure: p => + p.Add(x => x.InitiallyExpanded, _ => true)); + Assert.Contains("Alpha-1", cut.Markup); + cut.Instance.CollapseAll(); + cut.Render(); + Assert.DoesNotContain("Alpha-1", cut.Markup); +} + +[Fact] +public void RevealNode_ExpandsAncestors() +{ + var cut = RenderTree(); + // Alpha-2-X is at depth 2 — both Alpha and Alpha-2 need expanding + cut.Instance.RevealNode("a2x"); + cut.Render(); + Assert.Contains("Alpha-2-X", cut.Markup); + // Intermediate nodes should also be visible + Assert.Contains("Alpha-2", cut.Markup); +} + +[Fact] +public void RevealNode_WithSelect_SelectsNode() +{ + object? selected = null; + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKeyChanged, (object? key) => selected = key); + }); + cut.Instance.RevealNode("a2x", select: true); + cut.Render(); + Assert.Equal("a2x", selected); +} + +[Fact] +public void RevealNode_UnknownKey_NoOp() +{ + var cut = RenderTree(); + // Should not throw + cut.Instance.RevealNode("nonexistent"); + cut.Render(); + // Alpha still collapsed + Assert.DoesNotContain("Alpha-1", cut.Markup); +} +``` + +**Step 2: Run tests to verify they fail** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests.ExpandAll|CollapseAll|RevealNode" -v minimal` +Expected: FAIL (methods don't exist) + +**Step 3: Implement the public methods** + +In `TreeView.razor`: + +- `ExpandAll()`: Walk the entire tree recursively starting from `Items`. For each node where `HasChildrenSelector` returns true, add its key to `_expandedKeys`. Call `PersistExpandedState()` and `StateHasChanged()`. +- `CollapseAll()`: Clear `_expandedKeys`. Call `PersistExpandedState()` and `StateHasChanged()`. +- `RevealNode(object key, bool select = false)`: Build a parent lookup dictionary by walking the full tree (key → parent key). Starting from the target key, walk up through parents, adding each ancestor key to `_expandedKeys`. If `select` is true, set `SelectedKey` and invoke `SelectedKeyChanged`. Call `PersistExpandedState()` and `StateHasChanged()`. If key not found in the tree, return silently. +- Extract `PersistExpandedState()` private method that serializes and writes to sessionStorage if `StorageKey` is set. + +**Step 4: Run tests to verify they pass** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests" -v minimal` +Expected: All PASS. + +**Step 5: Commit** + +```bash +git add src/ScadaLink.CentralUI/Components/Shared/TreeView.razor tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs +git commit -m "feat(ui): add ExpandAll, CollapseAll, RevealNode to TreeView (R12, R13)" +``` + +--- + +### Task 5: Add Context Menu (R15) + +**Files:** +- Modify: `src/ScadaLink.CentralUI/Components/Shared/TreeView.razor` +- Modify: `tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs` + +**Step 1: Write the failing tests** + +Add to `TreeViewTests.cs`: + +```csharp +[Fact] +public void ContextMenu_Null_NoMenuRendered() +{ + var cut = RenderTree(); + // Right-click Alpha — no context menu should appear + var alphaRow = cut.FindAll(".tv-row") + .First(r => r.TextContent.Contains("Alpha")); + alphaRow.ContextMenu(); + Assert.Throws(() => cut.Find(".dropdown-menu")); +} + +[Fact] +public void ContextMenu_RightClickShowsMenu() +{ + var cut = RenderTree(configure: p => + p.Add(x => x.ContextMenu, (TestNode node) => + $"")); + var alphaRow = cut.FindAll(".tv-row") + .First(r => r.TextContent.Contains("Alpha")); + alphaRow.ContextMenu(); + var menu = cut.Find(".dropdown-menu"); + Assert.Contains("Action for Alpha", menu.TextContent); +} + +[Fact] +public void ContextMenu_EmptyFragment_NoMenu() +{ + // ContextMenu renders nothing for leaves + var cut = RenderTree(configure: p => + p.Add(x => x.ContextMenu, (TestNode node) => + node.Children.Count > 0 ? $"" : "")); + // Right-click Beta (leaf) — fragment renders empty + var betaRow = cut.FindAll(".tv-row") + .First(r => r.TextContent.Contains("Beta")); + betaRow.ContextMenu(); + Assert.Throws(() => cut.Find(".dropdown-menu")); +} + +[Fact] +public void ContextMenu_RightClickDifferentNode_ReplacesMenu() +{ + var cut = RenderTree(configure: p => + { + p.Add(x => x.InitiallyExpanded, n => n.Key == "a"); + p.Add(x => x.ContextMenu, (TestNode node) => + $""); + }); + // Right-click Alpha + cut.FindAll(".tv-row").First(r => r.TextContent.Contains("Alpha")).ContextMenu(); + Assert.Contains("Alpha", cut.Find(".dropdown-menu").TextContent); + // Right-click Alpha-1 + cut.FindAll(".tv-row").First(r => r.TextContent.Contains("Alpha-1")).ContextMenu(); + var menus = cut.FindAll(".dropdown-menu"); + Assert.Single(menus); + Assert.Contains("Alpha-1", menus[0].TextContent); +} +``` + +**Step 2: Run tests to verify they fail** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests.ContextMenu" -v minimal` +Expected: FAIL + +**Step 3: Implement context menu** + +In `TreeView.razor`: + +- Add `[Parameter] public RenderFragment? ContextMenu { get; set; }` +- Add state: `private TItem? _contextMenuItem`, `private double _contextMenuX`, `private double _contextMenuY`, `private bool _showContextMenu` +- On the `.tv-row` div, add `@oncontextmenu="(e) => OnContextMenu(e, item)" @oncontextmenu:preventDefault="_showContextMenu"`. +- `OnContextMenu(MouseEventArgs e, TItem item)`: set `_contextMenuItem = item`, `_contextMenuX = e.ClientX`, `_contextMenuY = e.ClientY`, `_showContextMenu = true`. +- Render the menu: if `_showContextMenu && _contextMenuItem != null && ContextMenu != null`, render a `
          ` containing `@ContextMenu(_contextMenuItem)`. +- Handle empty fragment: after rendering, if the dropdown-menu has no child elements, hide it. Alternatively, always render and use CSS or check for content. The simplest approach: always render the container, and the test for "empty" checks whether any `.dropdown-item` children exist. If not, suppress `preventDefault` so browser default menu shows. +- Dismiss: add a `@onclick` handler on a full-page overlay `
          ` (transparent, z-index below the menu) that sets `_showContextMenu = false`. Also handle Escape via `@onkeydown`. +- Clicking a menu item: the consumer's `@onclick` handler runs, then the overlay catch dismisses the menu on the next render. + +**Step 4: Run tests to verify they pass** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests" -v minimal` +Expected: All PASS. + +**Step 5: Commit** + +```bash +git add src/ScadaLink.CentralUI/Components/Shared/TreeView.razor tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs +git commit -m "feat(ui): add right-click context menu to TreeView (R15)" +``` + +--- + +### Task 6: Add External Filtering Tests (R8) + +**Files:** +- Modify: `tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs` + +This task adds tests for filtering behavior that should already work from the core implementation (the component just renders whatever `Items` it receives). These tests verify that expansion state is preserved across re-renders with different items. + +**Step 1: Write the tests** + +Add to `TreeViewTests.cs`: + +```csharp +[Fact] +public void Filtering_ReducedItems_HidesRemovedRoots() +{ + var cut = RenderTree(); + Assert.Contains("Alpha", cut.Markup); + Assert.Contains("Beta", cut.Markup); + // Re-render with only Alpha + cut.SetParametersAndRender(p => + p.Add(x => x.Items, SimpleRoots().Where(n => n.Key == "a").ToList())); + Assert.Contains("Alpha", cut.Markup); + Assert.DoesNotContain("Beta", cut.Markup); +} + +[Fact] +public void Filtering_ExpansionStatePreserved() +{ + var cut = RenderTree(); + // Expand Alpha + cut.Find(".tv-toggle").Click(); + Assert.Contains("Alpha-1", cut.Markup); + // Filter to only Alpha + cut.SetParametersAndRender(p => + p.Add(x => x.Items, SimpleRoots().Where(n => n.Key == "a").ToList())); + // Alpha should still be expanded + Assert.Contains("Alpha-1", cut.Markup); + // Restore full list — Alpha still expanded + cut.SetParametersAndRender(p => + p.Add(x => x.Items, SimpleRoots())); + Assert.Contains("Alpha-1", cut.Markup); +} + +[Fact] +public void Filtering_SelectionCleared_WhenNodeDisappears() +{ + object? selected = "b"; // Beta selected + var cut = RenderTree(configure: p => + { + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKey, (object)"b"); + p.Add(x => x.SelectedKeyChanged, (object? key) => selected = key); + }); + // Filter to only Alpha — Beta disappears + cut.SetParametersAndRender(p => + { + p.Add(x => x.Items, SimpleRoots().Where(n => n.Key == "a").ToList()); + p.Add(x => x.Selectable, true); + p.Add(x => x.SelectedKey, (object)"b"); + p.Add(x => x.SelectedKeyChanged, (object? key) => selected = key); + }); + // Selection should be cleared + Assert.Null(selected); +} +``` + +**Step 2: Run tests** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests.Filtering" -v minimal` +Expected: PASS (behavior comes from core implementation). If any fail, fix in TreeView.razor. + +**Step 3: Commit** + +```bash +git add tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs +git commit -m "test(ui): add external filtering tests for TreeView (R8)" +``` + +--- + +### Task 7: Integrate TreeView into Data Connections Page + +**Files:** +- Modify: `src/ScadaLink.CentralUI/Components/Pages/Admin/DataConnections.razor` + +This is the simplest integration (two-level tree, no recursion). + +**Step 1: Read the current file** + +Read: `src/ScadaLink.CentralUI/Components/Pages/Admin/DataConnections.razor` + +**Step 2: Implement the changes** + +The page currently has a flat table. Replace it with a TreeView: + +- Add a `TreeNode` record and `NodeKind` enum in the `@code` block: + ```csharp + record TreeNode(string Key, string Label, NodeKind Kind, List Children, + DataConnection? Connection = null, int? SiteId = null); + enum NodeKind { Site, DataConnection } + ``` + +- Add `_treeRoots` field built in `LoadDataAsync()`: + ```csharp + private List _treeRoots = new(); + ``` + +- In `LoadDataAsync()`, after loading sites and connections, build the tree: + ```csharp + var connBySite = _connections.GroupBy(c => c.SiteId).ToDictionary(g => g.Key, g => g.ToList()); + _treeRoots = _sites.Select(site => new TreeNode( + Key: $"site-{site.Id}", + Label: site.Name, + Kind: NodeKind.Site, + Children: (connBySite.GetValueOrDefault(site.Id) ?? new()) + .Select(c => new TreeNode( + Key: $"conn-{c.Id}", + Label: c.Name, + Kind: NodeKind.DataConnection, + Children: new(), + Connection: c)) + .ToList(), + SiteId: site.Id + )).ToList(); + ``` + +- Replace the `` with: + ```razor + + + @if (node.Kind == NodeKind.Site) + { + @node.Label + @node.Children.Count + } + else + { + @node.Label + @node.Connection!.Protocol + } + + + @if (node.Kind == NodeKind.DataConnection) + { + +
          + + } +           + + No data connections configured. + +           + ``` + +- Remove the old `
          ` / `` / `` markup and inline Edit/Delete buttons. +- Keep `_toast`, `_confirmDialog`, the "Create" button header, loading/error handling, and the `DeleteConnection` method. + +**Step 3: Build and verify** + +Run: `dotnet build src/ScadaLink.CentralUI/ScadaLink.CentralUI.csproj` +Expected: Build succeeds. + +**Step 4: Commit** + +```bash +git add src/ScadaLink.CentralUI/Components/Pages/Admin/DataConnections.razor +git commit -m "refactor(ui): replace data connections table with TreeView grouped by site" +``` + +--- + +### Task 8: Integrate TreeView into Areas Page + +**Files:** +- Modify: `src/ScadaLink.CentralUI/Components/Pages/Admin/Areas.razor` + +**Step 1: Read the current file** + +Read: `src/ScadaLink.CentralUI/Components/Pages/Admin/Areas.razor` + +**Step 2: Implement the changes** + +The Areas page has a two-panel layout. Keep the left site list panel. Replace the right panel's custom flat-tree rendering with a TreeView using the `Area` entity directly as `TItem`. + +- Replace the manual tree rendering block (the `@foreach (var node in _flatTree)` loop with indentation) with: + ```razor + + + @area.Name + + + +
          + +           + + No areas for this site. Add one above. + +           + ``` + +- Add `_rootAreas` field computed from `_areas`: + ```csharp + private List _rootAreas => _areas.Where(a => a.ParentAreaId == null).ToList(); + ``` + +- Remove: `BuildFlatTree()`, `AddChildren()`, the `AreaTreeNode` record, `_flatTree` field, and all manual indentation CSS. +- Keep: site list panel, add/edit form, `LoadAreasAsync()`, `SaveArea()`, `DeleteArea()`, `GetAreaPath()`. + +**Step 3: Build and verify** + +Run: `dotnet build src/ScadaLink.CentralUI/ScadaLink.CentralUI.csproj` +Expected: Build succeeds. + +**Step 4: Commit** + +```bash +git add src/ScadaLink.CentralUI/Components/Pages/Admin/Areas.razor +git commit -m "refactor(ui): replace manual area tree rendering with TreeView component" +``` + +--- + +### Task 9: Integrate TreeView into Instances Page + +**Files:** +- Modify: `src/ScadaLink.CentralUI/Components/Pages/Deployment/Instances.razor` + +This is the most complex integration — deep hierarchy with filtering and context menu. + +**Step 1: Read the current file** + +Read: `src/ScadaLink.CentralUI/Components/Pages/Deployment/Instances.razor` + +**Step 2: Add tree model and builder** + +Add to `@code` block: + +```csharp +record InstanceTreeNode(string Key, string Label, InstanceNodeKind Kind, + List Children, Instance? Instance = null, + bool IsStale = false); +enum InstanceNodeKind { Site, Area, Instance } + +private List _treeRoots = new(); + +private void BuildTree() +{ + // Build the hierarchy: Site → Area (recursive) → Instance + _treeRoots = _sites.Select(site => + { + var siteAreas = _allAreas.Where(a => a.SiteId == site.Id).ToList(); + var siteInstances = _filteredInstances.Where(i => i.SiteId == site.Id).ToList(); + + var areaNodes = BuildAreaNodes(siteAreas, siteInstances, parentId: null); + + // Instances with no area attach directly under the site + var unassigned = siteInstances + .Where(i => i.AreaId == null) + .Select(MakeInstanceNode) + .ToList(); + + var children = areaNodes.Concat(unassigned).ToList(); + + return new InstanceTreeNode( + Key: $"site-{site.Id}", + Label: site.Name, + Kind: InstanceNodeKind.Site, + Children: children); + }) + .Where(s => s.Children.Count > 0) // Prune empty sites + .ToList(); +} + +private List BuildAreaNodes(List allAreas, + List instances, int? parentId) +{ + return allAreas + .Where(a => a.ParentAreaId == parentId) + .Select(area => + { + var childAreas = BuildAreaNodes(allAreas, instances, area.Id); + var areaInstances = instances + .Where(i => i.AreaId == area.Id) + .Select(MakeInstanceNode) + .ToList(); + var children = childAreas.Concat(areaInstances).ToList(); + return new InstanceTreeNode( + Key: $"area-{area.Id}", + Label: area.Name, + Kind: InstanceNodeKind.Area, + Children: children); + }) + .Where(a => a.Children.Count > 0) // Prune empty areas + .ToList(); +} + +private InstanceTreeNode MakeInstanceNode(Instance inst) => new( + Key: $"inst-{inst.Id}", + Label: inst.UniqueName, + Kind: InstanceNodeKind.Instance, + Children: new(), + Instance: inst, + IsStale: _stalenessMap.GetValueOrDefault(inst.Id)); +``` + +**Step 3: Update ApplyFilters to build tree** + +In `ApplyFilters()`, after the existing filtering logic, replace `UpdatePage()` with `BuildTree()`. Remove `_totalPages`, `_currentPage`, `_pagedInstances`, `GoToPage()`, `UpdatePage()`, and `PageSize`. + +**Step 4: Replace table with TreeView** + +Replace the `
          ` and pagination markup with: + +```razor + + + @switch (node.Kind) + { + case InstanceNodeKind.Site: + @node.Label + break; + case InstanceNodeKind.Area: + @node.Label + break; + case InstanceNodeKind.Instance: + @node.Label + @node.Instance!.State + @if (node.Instance!.State != InstanceState.NotDeployed) + { + + @(node.IsStale ? "Stale" : "Current") + + } + break; + } + + + @if (node.Kind == InstanceNodeKind.Instance) + { + var inst = node.Instance!; + var isStale = node.IsStale; + + @if (inst.State == InstanceState.Enabled) + { + + } + else if (inst.State == InstanceState.Disabled) + { + + } + + +
          + + } +           + + No instances match the current filters. + +           + +
          + @_filteredInstances.Count instance(s) total +
          +``` + +Add fields: +```csharp +private TreeView _instanceTree = default!; +private object? _selectedKey; +``` + +**Step 5: Remove old table/pagination code** + +Remove from `@code`: +- `_pagedInstances`, `_currentPage`, `_totalPages`, `PageSize` +- `GoToPage()`, `UpdatePage()` +- Keep: `_allInstances`, `_filteredInstances`, `_allAreas`, `_sites`, `_templates`, `_stalenessMap`, `ApplyFilters()` (modified), all action methods, diff modal + +**Step 6: Build and verify** + +Run: `dotnet build src/ScadaLink.CentralUI/ScadaLink.CentralUI.csproj` +Expected: Build succeeds. + +**Step 7: Commit** + +```bash +git add src/ScadaLink.CentralUI/Components/Pages/Deployment/Instances.razor +git commit -m "refactor(ui): replace instances table with hierarchical TreeView (Site → Area → Instance)" +``` + +--- + +### Task 10: Full Build Verification + +**Files:** +- No changes — verification only. + +**Step 1: Build entire solution** + +Run: `dotnet build ScadaLink.slnx` +Expected: Build succeeds with 0 errors. + +**Step 2: Run all tests** + +Run: `dotnet test ScadaLink.slnx -v minimal` +Expected: All tests pass (including the new TreeView tests and existing tests). + +**Step 3: Run TreeView tests specifically** + +Run: `dotnet test tests/ScadaLink.CentralUI.Tests/ --filter "FullyQualifiedName~TreeViewTests" -v minimal` +Expected: All TreeView tests pass. + +**Step 4: Commit (if any fixes needed)** + +Only if build/test failures required fixes: +```bash +git add -A +git commit -m "fix(ui): resolve build/test issues from TreeView integration" +``` diff --git a/docs/plans/2026-03-23-treeview-component.md.tasks.json b/docs/plans/2026-03-23-treeview-component.md.tasks.json new file mode 100644 index 0000000..068c4ca --- /dev/null +++ b/docs/plans/2026-03-23-treeview-component.md.tasks.json @@ -0,0 +1,16 @@ +{ + "planPath": "docs/plans/2026-03-23-treeview-component.md", + "tasks": [ + {"id": 22, "subject": "Task 1: Create TreeView.razor — Core Rendering (R1-R4, R14)", "status": "pending"}, + {"id": 23, "subject": "Task 2: Add Selection Support (R5)", "status": "pending", "blockedBy": [22]}, + {"id": 24, "subject": "Task 3: Add Session Storage Persistence (R11)", "status": "pending", "blockedBy": [23]}, + {"id": 25, "subject": "Task 4: Add ExpandAll, CollapseAll, RevealNode (R12, R13)", "status": "pending", "blockedBy": [24]}, + {"id": 26, "subject": "Task 5: Add Context Menu (R15)", "status": "pending", "blockedBy": [25]}, + {"id": 27, "subject": "Task 6: Add External Filtering Tests (R8)", "status": "pending", "blockedBy": [26]}, + {"id": 28, "subject": "Task 7: Integrate TreeView into Data Connections Page", "status": "pending", "blockedBy": [27]}, + {"id": 29, "subject": "Task 8: Integrate TreeView into Areas Page", "status": "pending", "blockedBy": [27]}, + {"id": 30, "subject": "Task 9: Integrate TreeView into Instances Page", "status": "pending", "blockedBy": [27]}, + {"id": 31, "subject": "Task 10: Full Build Verification", "status": "pending", "blockedBy": [28, 29, 30]} + ], + "lastUpdated": "2026-03-23T00:00:00Z" +} diff --git a/docs/requirements/Component-TreeView.md b/docs/requirements/Component-TreeView.md new file mode 100644 index 0000000..18addcf --- /dev/null +++ b/docs/requirements/Component-TreeView.md @@ -0,0 +1,626 @@ +# TreeView Component + +## Purpose + +A reusable, generic Blazor Server component that renders hierarchical data as an expandable/collapsible tree. The component is data-agnostic — it accepts any tree-shaped data via type parameters and render fragments, following the same pattern as the existing `DataTable` shared component. + +## Location + +`src/ScadaLink.CentralUI/Components/Shared/TreeView.razor` + +## Primary Use Case: Instance Hierarchy + +The motivating use case is displaying instances organized by site and area: + +``` +- Site A + + Area 1 + - Sub Area 1 + Instance 1 + Instance 2 + + Area 2 ++ Site B ++ Site C +``` + +**Hierarchy**: Site → Area → Sub Area (recursive) → Instance (leaf) + +Nodes at each level may be expandable (branches) or plain items (leaves). Leaf nodes have no expand/collapse toggle. + +## Requirements + +### R1 — Generic Type Parameter + +The component accepts a single type parameter `TItem` representing any node in the tree. The consumer provides: + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `Items` | `IReadOnlyList` | Yes | Root-level items | +| `ChildrenSelector` | `Func>` | Yes | Returns children for a given node | +| `HasChildrenSelector` | `Func` | Yes | Whether the node can be expanded (branch vs. leaf) | +| `KeySelector` | `Func` | Yes | Unique key per node (for state tracking) | + +### R2 — Render Fragments + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `NodeContent` | `RenderFragment` | Yes | Renders the label/content for each node | +| `EmptyContent` | `RenderFragment?` | No | Shown when `Items` is empty | + +The `NodeContent` fragment receives the `TItem` and is responsible for rendering the node's display (text, icons, badges, action buttons, etc.). The tree component only renders the structural chrome (indentation, expand/collapse toggle, vertical guide lines). + +### R3 — Expand/Collapse Behavior + +- Each branch node displays a toggle indicator: `+` when collapsed, `−` when expanded. +- Clicking the **toggle icon** expands/collapses the node. Clicking the **content area** does **not** toggle expansion (it is reserved for selection — see R5). +- Leaf nodes (where `HasChildrenSelector` returns `false`) display no toggle — they are indented inline with sibling branch nodes. +- Expand/collapse state is tracked internally by the component using `KeySelector` for identity. +- All nodes start collapsed by default unless `InitiallyExpanded` is set. +- **Session persistence**: When the user navigates away and returns, previously expanded nodes are restored (see R11). + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `InitiallyExpanded` | `Func?` | No | Predicate — nodes matching this start expanded (first load only, before any persisted state exists) | + +### R4 — Indentation and Visual Structure + +- Each depth level is indented by a fixed amount (default 24px, configurable via `IndentPx` parameter). +- Vertical guide lines connect parent to children at each depth level (thin left-border or CSS pseudo-element). +- The toggle icon is inline with the node content, left-aligned at the current depth. +- Leaf nodes align with sibling branch labels (the content starts at the same horizontal position, with empty space where the toggle would be). + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `IndentPx` | `int` | No | Pixels per indent level. Default: 24 | +| `ShowGuideLines` | `bool` | No | Show vertical connector lines. Default: true | + +### R5 — Selection + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `Selectable` | `bool` | No | Enable click-to-select. Default: false | +| `SelectedKey` | `object?` | No | Currently selected node key (two-way binding) | +| `SelectedKeyChanged` | `EventCallback` | No | Fires when selection changes | +| `SelectedCssClass` | `string` | No | CSS class for selected node. Default: `"bg-primary bg-opacity-10"` | + +When `Selectable` is true, clicking a node row selects it (highlighted). Clicking the expand/collapse toggle does **not** change selection — only clicking the content area does. + +### R6 — Lazy Loading (Deferred) + +Future enhancement. For now, all children are provided synchronously via `ChildrenSelector`. A future version may support `Func>>` for on-demand loading with a spinner placeholder. + +### R7 — Keyboard Navigation (Deferred) + +Future enhancement. Arrow keys for navigation, Enter/Space for expand/collapse, Home/End for first/last. + +### R8 — External Filtering + +The tree component itself does **not** implement filter UI. Filtering is driven externally by the consuming page — for example, a site dropdown that filters the tree to show only the selected site's hierarchy. + +**How it works:** +- The consumer filters `Items` (and/or adjusts `ChildrenSelector` results) and passes the filtered list to the component. +- When `Items` changes (Blazor re-render), the component re-renders the tree with the new data. +- **Expansion state is preserved across filter changes.** Nodes that were expanded before filtering remain expanded if they reappear after the filter changes. The component tracks expanded keys independently of the current `Items` — keys are never purged when items disappear, so re-adding a previously expanded node restores its expanded state. +- Selection is cleared if the selected node is no longer present after filtering. + +**Example — site filter on the instances page:** +```razor + + + + ... + + +@code { + private int? _selectedSiteId; + + private List GetFilteredRoots() + { + if (_selectedSiteId == null) return _allRoots; + return _allRoots.Where(r => r.SiteId == _selectedSiteId).ToList(); + } +} +``` + +This keeps filter logic in the page (domain-specific) while the component handles rendering whatever it receives. + +### R9 — Styling + +- Uses Bootstrap 5 utility classes only (no third-party frameworks). +- No hardcoded colors — uses standard Bootstrap text/background utilities. +- Toggle icons: Unicode characters (`+` / `−`) in a `` with `cursor: pointer`, or a small SVG chevron. No icon library dependency. +- Compact row height for dense data (matching `table-sm` density). +- Hover effect on rows: subtle background highlight (`bg-light` or similar). +- CSS scoped to the component via Blazor CSS isolation (`TreeView.razor.css`). + +### R10 — No Internal Scrolling + +The tree renders inline in the page flow. The consuming page is responsible for placing it in a scrollable container if needed (e.g., `overflow-auto` with `max-height`). + +### R11 — Session-Persistent Expansion State + +When a user expands nodes, navigates away (e.g., clicks an instance link to the configure page), and returns to the page, the tree must restore the same expansion state. + +**Mechanism:** +- The component requires a `StorageKey` parameter — a unique string identifying this tree instance (e.g., `"instances-tree"`, `"data-connections-tree"`). +- Expanded node keys are stored in browser `sessionStorage` under the key `treeview:{StorageKey}`. +- On mount (`OnAfterRenderAsync` first render), the component reads `sessionStorage` and expands any nodes whose keys are present. This takes precedence over `InitiallyExpanded`. +- On every expand/collapse toggle, the component writes the updated set of expanded keys to `sessionStorage`. +- `sessionStorage` is scoped to the browser tab — each tab has independent state. State is cleared when the tab is closed. + +**Implementation note:** Blazor Server requires `IJSRuntime` to access `sessionStorage`. The component injects `IJSRuntime` and uses a small JS interop helper (inline or in a shared `.js` file) for `getItem`/`setItem`. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `StorageKey` | `string?` | No | Key for sessionStorage persistence. If null, expansion state is not persisted (in-memory only). | + +### R12 — Expand All / Collapse All + +The component exposes methods that the consumer can call via `@ref`: + +```csharp +/// Expands all branch nodes in the tree (recursive). +public void ExpandAll(); + +/// Collapses all branch nodes in the tree. +public void CollapseAll(); +``` + +**Usage:** +```razor + + + + + +@code { + private TreeView _tree = default!; +} +``` + +Both methods update sessionStorage if `StorageKey` is set. `ExpandAll` requires walking the full tree via `ChildrenSelector` to collect all branch node keys. + +### R13 — Programmatic Expand-to-Node + +The component exposes a method to reveal a specific node by expanding all of its ancestors: + +```csharp +/// Expands all ancestor nodes so that the node with the given key becomes visible. +/// Optionally selects the node and scrolls it into view. +public void RevealNode(object key, bool select = false); +``` + +This requires the component to build a parent lookup (key → parent key) from the tree data. When called: + +1. Walk from the target node's key up to the root, collecting ancestor keys. +2. Expand all ancestors. +3. If `select` is true, set the node as selected and fire `SelectedKeyChanged`. +4. After rendering, scroll the node element into view via JS interop (`element.scrollIntoView({ block: 'nearest' })`). + +**Use case:** Search box on the instances page — user types "Motor-1", results list shows matching instances. Clicking a result calls `_tree.RevealNode(instanceKey, select: true)` to expand the Site → Area path and highlight the instance. + +### R14 — Accessibility (ARIA) + +The component renders semantic ARIA attributes for screen reader support: + +- The root `
            ` has `role="tree"`. +- Each node `
          • ` has `role="treeitem"`. +- Branch nodes have `aria-expanded="true"` or `aria-expanded="false"`. +- Child `
              ` containers have `role="group"`. +- When `Selectable` is true, the selected node has `aria-selected="true"`. +- Each node row has a unique `id` derived from `KeySelector` for anchor targeting. + +This is baseline accessibility — no keyboard navigation yet (deferred in R7), but screen readers can understand the tree structure. + +### R15 — Context Menu + +The component supports an optional right-click context menu on nodes, defined by the consumer via a render fragment. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `ContextMenu` | `RenderFragment?` | No | Menu content rendered when a node is right-clicked. Receives the right-clicked `TItem`. | + +**Behavior:** +- Right-clicking a node renders the `ContextMenu` fragment for that node. The component checks whether the fragment produces any content — **if the fragment renders nothing (empty markup), no menu is shown and the browser default context menu is used.** This is how per-node-type menus work: the consumer uses `@if` blocks in the fragment, and nodes that don't match any condition simply produce no output. +- When content is produced, the browser's default context menu is suppressed (`@oncontextmenu:preventDefault`) and a floating menu is shown at the cursor. +- The menu is rendered as a Bootstrap dropdown: `
              ` containing ` + @if (node.State == InstanceState.Enabled) + { + + } + else if (node.State == InstanceState.Disabled) + { + + } + + +
              + + } + else if (node.Kind == NodeKind.Site) + { + + } + + +``` + +This keeps the tree clean — no inline action buttons cluttering leaf nodes. Different node types can show different menu items (instances get full CRUD actions, sites might get bulk operations, areas might have no menu at all). + +**Positioning:** +- The menu is absolutely positioned relative to the viewport using the mouse event's `clientX`/`clientY`. +- If the menu would overflow the viewport bottom or right edge, it flips direction (opens upward or leftward). +- The component handles positioning internally — no JS interop needed (CSS `position: fixed` with `top`/`left` from the mouse event). + +### R16 — Multi-Selection (Deferred) + +Future enhancement. Single selection (R5) covers current needs. A future version may add: + +- `MultiSelect` bool parameter +- `SelectedKeys` / `SelectedKeysChanged` for set-based selection +- Shift+click for range select, Ctrl+click for toggle +- Use case: bulk operations (select multiple instances → deploy/disable all) + +## Component API Summary + +```csharp +@typeparam TItem + +// Data +[Parameter] public IReadOnlyList Items { get; set; } +[Parameter] public Func> ChildrenSelector { get; set; } +[Parameter] public Func HasChildrenSelector { get; set; } +[Parameter] public Func KeySelector { get; set; } + +// Rendering +[Parameter] public RenderFragment NodeContent { get; set; } +[Parameter] public RenderFragment? EmptyContent { get; set; } +[Parameter] public RenderFragment? ContextMenu { get; set; } + +// Layout +[Parameter] public int IndentPx { get; set; } = 24; +[Parameter] public bool ShowGuideLines { get; set; } = true; + +// Expand/Collapse +[Parameter] public Func? InitiallyExpanded { get; set; } +[Parameter] public string? StorageKey { get; set; } // sessionStorage persistence key + +// Selection +[Parameter] public bool Selectable { get; set; } +[Parameter] public object? SelectedKey { get; set; } +[Parameter] public EventCallback SelectedKeyChanged { get; set; } +[Parameter] public string SelectedCssClass { get; set; } = "bg-primary bg-opacity-10"; + +// Public methods (called via @ref) +public void ExpandAll(); +public void CollapseAll(); +public void RevealNode(object key, bool select = false); +``` + +## Usage Example: Instance Hierarchy + +```razor +@* Build a unified tree model from sites, areas, and instances *@ + + + + @switch (node.Kind) + { + case NodeKind.Site: + @node.Label + break; + case NodeKind.Area: + @node.Label + break; + case NodeKind.Instance: + @node.Label + Enabled + break; + } + + + No items to display. + + + +@code { + private object? _selectedKey; + private List _roots = new(); + + record TreeNode(string Key, string Label, NodeKind Kind, List Children); + enum NodeKind { Site, Area, Instance } +} +``` + +## Usage Example: Data Connections by Site + +A simpler two-level tree — Site → Data Connections (leaves): + +``` +- Site A + Data Connection 1 + Data Connection 2 ++ Site B ++ Site C +``` + +```razor + + + @if (node.Kind == NodeKind.Site) + { + @node.Label + } + else + { + @node.Label + @node.Protocol + } + + + +@code { + private List _roots = new(); + + record TreeNode(string Key, string Label, NodeKind Kind, List Children, string? Protocol = null); + enum NodeKind { Site, DataConnection } + + // Build: group data connections by SiteId, wrap each site as a branch + // with its connections as leaf children +} +``` + +This demonstrates the component working with a flat two-level grouping — no recursive hierarchy needed. The consumer simply groups data connections by site and builds one level of children per site node. + +## Tree Model Construction Pattern + +The consuming page is responsible for building the tree model. The component only knows about `TItem`. + +**Instance hierarchy** (deep, recursive): +1. Load sites, areas (with `ParentAreaId` hierarchy), and instances. +2. Build `Area` subtree per site using recursive `ParentAreaId` traversal. +3. Attach instances as leaf children of their assigned area (or directly under the site if `AreaId` is null). +4. Wrap each entity in a uniform `TreeNode`. + +**Data connections by site** (flat, two-level): +1. Load sites and data connections. +2. Group connections by `SiteId`. +3. Each site becomes a branch node with its connections as leaf children. + +## Other Potential Uses + +The component is generic enough for: + +- **Template inheritance tree**: Template → child templates (via `ParentTemplateId`) +- **Area management**: Site → Area hierarchy (replace current flat indentation in Areas.razor) +- **Data connections**: Site → connections (flat grouping, as shown above) +- **Navigation sidebar**: Hierarchical menu structure +- **File/folder browser**: Any nested structure + +## Testing + +Unit tests use the existing bUnit + xUnit + NSubstitute setup in `tests/ScadaLink.CentralUI.Tests/`. Tests live in a dedicated file: `TreeViewTests.cs`. + +All tests use a simple test model: + +```csharp +record TestNode(string Key, string Label, List Children); +``` + +### Test Categories + +**Rendering:** +- Renders root-level items with correct labels +- Renders `EmptyContent` when `Items` is empty +- Does not render `EmptyContent` when items exist +- Leaf nodes have no expand/collapse toggle +- Branch nodes show `+` toggle when collapsed + +**Expand/Collapse:** +- Clicking toggle expands node and shows children +- Clicking expanded toggle collapses node and hides children +- Children of collapsed nodes are not in the DOM +- Deep nesting: expand parent, then expand child — grandchildren visible +- `InitiallyExpanded` predicate expands matching nodes on first render + +**Indentation:** +- Root nodes have zero indentation +- Child nodes are indented by `IndentPx` pixels per depth level +- Custom `IndentPx` value is applied correctly + +**Selection:** +- When `Selectable` is false (default), clicking a node does not fire `SelectedKeyChanged` +- When `Selectable` is true, clicking node content fires `SelectedKeyChanged` with correct key +- Clicking expand toggle does **not** change selection +- Selected node has `SelectedCssClass` applied +- Custom `SelectedCssClass` is used when provided + +**External Filtering:** +- Re-rendering with a filtered `Items` list removes hidden root nodes +- Expansion state is preserved after filter changes — expanding Site A, filtering to Site A only, then removing filter still shows Site A expanded +- Selection is cleared when the selected node disappears from filtered results + +**Session Persistence (R11):** +- When `StorageKey` is null, no JS interop calls are made +- When `StorageKey` is set, expanding a node writes to sessionStorage via JS interop +- On mount with a `StorageKey`, reads sessionStorage and restores expanded nodes +- Persisted state takes precedence over `InitiallyExpanded` + +*Note: sessionStorage tests mock `IJSRuntime` (already available via bUnit's `JSInterop`).* + +**Expand All / Collapse All (R12):** +- `ExpandAll()` expands all branch nodes — all descendants visible +- `CollapseAll()` collapses all branch nodes — only roots visible +- `ExpandAll()` updates sessionStorage when `StorageKey` is set +- `CollapseAll()` clears sessionStorage expanded set when `StorageKey` is set + +**RevealNode (R13):** +- `RevealNode(key)` expands all ancestors of the target node +- Target node's content is present in the DOM after reveal +- `RevealNode(key, select: true)` selects the node and fires `SelectedKeyChanged` +- `RevealNode` with unknown key is a no-op (does not throw) +- Deeply nested node (3+ levels) — all intermediate ancestors expanded + +**Accessibility (R14):** +- Root `
                ` has `role="tree"` +- Node `
              • ` elements have `role="treeitem"` +- Expanded branch has `aria-expanded="true"` +- Collapsed branch has `aria-expanded="false"` +- Child container `
                  ` has `role="group"` +- Selected node has `aria-selected="true"` when `Selectable` is true + +**Context Menu (R15):** +- Right-clicking a node shows the context menu with consumer-defined content +- Context menu is positioned at cursor coordinates +- When `ContextMenu` parameter is null, right-click does not render a menu +- When `ContextMenu` fragment renders empty content for a node type, no menu appears and browser default is used +- Right-clicking a node type with menu items shows the menu; right-clicking a node type without menu items does not +- Clicking a menu item dismisses the menu +- Clicking outside the menu dismisses it +- Right-clicking a different node replaces the current menu + +### Test File Location + +`tests/ScadaLink.CentralUI.Tests/TreeViewTests.cs` + +## Dependencies + +- Bootstrap 5 (already included in CentralUI) +- No additional packages +- bUnit 2.0.33-preview (already in test project) + +## Page Integration Notes + +### 1. Instances Page (`/deployment/instances` — Instances.razor) + +**Current state:** Flat table with filters (Site, Template, Status, Search), pagination, and 6 inline action buttons per row (Deploy, Disable/Enable, Configure, Diff, Delete). ~490 lines. + +**Change to:** +- Replace the `
          ` with a `` showing Site → Area → Sub Area → Instance hierarchy. +- **Keep the existing filter bar** (Site, Template, Status, Search). Filters control which tree roots and leaves are shown: + - Site filter: pass only the matching site root to `Items`. + - Template/Status/Search filters: filter at the instance (leaf) level. Branch nodes with no matching descendants should be pruned from the tree. Build a helper method (`BuildFilteredTree()`) that walks the hierarchy bottom-up, keeping only branches that contain at least one matching instance. +- **Remove the table, pagination, and Actions column.** The tree replaces all of this. +- **Move all 6 action buttons into the `ContextMenu` fragment**, shown only for instance nodes: + - Deploy/Redeploy, Disable/Enable (conditional on state), Configure, Diff, Delete (with divider). + - Site and Area nodes get no context menu (browser default). +- **Node content per type:** + - Site nodes: `SiteName` + - Area nodes: `AreaName` + - Instance nodes: `UniqueName` + status badge + staleness badge +- **Tree model:** Build in `LoadDataAsync` — load sites, areas (recursive via `ParentAreaId`), instances. Group instances by `SiteId` + `AreaId`. Instances with `AreaId == null` attach directly under their site. Wrap in a uniform `TreeNode` record. +- **StorageKey:** `"instances-tree"` +- **Selection:** Enable selection. Clicking an instance could show a detail panel or simply highlight it for context menu use. + +**Files to modify:** +- `src/ScadaLink.CentralUI/Components/Pages/Deployment/Instances.razor` — replace table with TreeView, add tree model building, move actions to context menu, keep filter bar. + +**Removed code:** +- Pagination logic (`_currentPage`, `_totalPages`, `_pagedInstances`, `GoToPage`) +- Actions column markup +- `
          ` / `` / `` structure + +--- + +### 2. Data Connections Page (`/admin/data-connections` — DataConnections.razor) + +**Current state:** Flat table listing all data connections across all sites. Columns: ID, Name, Protocol, Site, Primary Config, Backup Config, Actions (Edit, Delete). No filters. ~119 lines. + +**Change to:** +- Replace the `
          ` with a `` showing Site → Data Connection hierarchy (two levels, no recursion). +- **No filter bar needed initially** — the tree naturally groups by site. If the number of sites grows, a site filter dropdown can be added later using the external filtering pattern. +- **Move Edit and Delete into the `ContextMenu` fragment**, shown only for data connection nodes: + - Edit → navigates to `/admin/data-connections/{id}/edit` + - Delete → shows confirm dialog, then deletes + - Site nodes get no context menu. +- **Node content per type:** + - Site nodes: `SiteName` + child count badge (e.g., `3`) + - Data Connection nodes: `Name` + protocol badge (e.g., `OPC UA`) +- **Tree model:** Group data connections by `SiteId`. Each site becomes a branch, its connections become leaves. Sites with no connections still appear as empty branches (expandable but no children). +- **StorageKey:** `"data-connections-tree"` + +**Files to modify:** +- `src/ScadaLink.CentralUI/Components/Pages/Admin/DataConnections.razor` — replace table with TreeView, add tree model building, move actions to context menu. + +**Removed code:** +- `
          ` / `` / `` structure +- Inline Edit/Delete buttons + +--- + +### 3. Areas Page (`/admin/areas` — Areas.razor) + +**Current state:** Two-panel layout. Left panel: site list (`list-group`). Right panel: manually indented flat tree of areas for the selected site, with `[+]`/`-` indicators, inline Edit/Delete buttons, and an add/edit form. Custom `BuildFlatTree()` / `AddChildren()` methods, `AreaTreeNode` record, manual `padding-left` indentation. ~293 lines. + +**Change to:** +- **Keep the two-panel layout** (site list on left, area tree on right). +- Replace the custom flat-tree rendering in the right panel with a `` component. +- **Site selection stays as-is** (left panel `list-group` click sets `_selectedSiteId`). This acts as the external filter — the TreeView receives only the selected site's areas as `Items`. +- **Move Edit and Delete into the `ContextMenu` fragment** for area nodes: + - Edit → loads area into the add/edit form (same as current behavior) + - Delete → shows confirm dialog (with child check, same as current) +- **Node content:** `AreaName` — optionally show instance count if available. +- **Tree model:** For the selected site, load root areas (`ParentAreaId == null`), use `ChildrenSelector` to return child areas. The `Area` entity already has `Children` collection, so it can be used directly as `TItem` without a wrapper record — `ChildrenSelector = a => a.Children.ToList()`, `HasChildrenSelector = a => a.Children.Any()`, `KeySelector = a => a.Id`. +- **Keep the add/edit form** at the top of the right panel (above the tree). The "Parent Area" dropdown stays. +- **StorageKey:** `"areas-tree"` + +**Files to modify:** +- `src/ScadaLink.CentralUI/Components/Pages/Admin/Areas.razor` — replace custom flat-tree rendering with TreeView, remove `BuildFlatTree()`, `AddChildren()`, `AreaTreeNode` record, manual indentation CSS. + +**Removed code:** +- `BuildFlatTree()` method +- `AddChildren()` recursive helper +- `AreaTreeNode` record +- Manual `padding-left` indentation +- Custom `[+]`/`-` toggle rendering +- Inline Edit/Delete buttons in the tree rows + +## Interactions + +- **DataTable**: The tree replaces flat tables on the three pages listed above. Other pages that don't need hierarchy continue using DataTable. +- **InstanceConfigure.razor**: Right-click → Configure on an instance node navigates to `/deployment/instances/{Id}/configure`. +- **Areas.razor**: The simplest integration — `Area` entity used directly as `TItem`, no wrapper needed. diff --git a/src/ScadaLink.CentralUI/wwwroot/js/treeview-storage.js b/src/ScadaLink.Host/wwwroot/js/treeview-storage.js similarity index 100% rename from src/ScadaLink.CentralUI/wwwroot/js/treeview-storage.js rename to src/ScadaLink.Host/wwwroot/js/treeview-storage.js