Implement Hierarchy Admin Portal Screen
epic-organizational-hierarchy-management-admin-portal-task-016 — Build the top-level HierarchyAdminPortalScreen combining all hierarchy management UI elements. Integrate the HierarchyTreeView as main content, add node controls (add root/child node buttons), implement search bar with real-time tree filtering, display member count badges per node, and provide contextual action menu (edit, delete, move) on node long-press or tap. Requires admin role guard. Enable non-technical org administrators to self-serve all structural changes.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Compose this screen from the already-built sub-widgets (HierarchyTreeView, HierarchyNodeEditorScreen, UnitAssignmentPanel) — this task is primarily integration and orchestration, not new widget building. The HierarchyAdminPortalCubit manages: selectedNode, searchQuery, and isLoading state. Keep search debounce in the cubit using a Timer that resets on each search input event. For the contextual action menu, use a ModalBottomSheet with three ListTile options rather than a PopupMenuButton, as bottom sheets are more accessible and ergonomic on mobile.
The delete confirmation dialog should query HierarchyService.getDescendantCount(nodeId) and include this in the dialog message (e.g., 'This will also delete 34 child nodes'). For the move operation, reuse HierarchyTreeView in a special 'picker mode' (pass a mode enum or a selectionCallback to differentiate from normal navigation). After any mutation, emit a RefreshTreeEvent to the HierarchyTreeViewCubit — this triggers a root-level re-fetch while preserving the expand/collapse state for unchanged nodes. This screen is the primary tool for org administrators at NHF managing 1,400 local chapters — prioritize reliability and clear feedback over visual complexity.
Testing Requirements
Write widget and integration tests for: (1) non-admin user redirected to no-access screen, (2) search bar filters tree and clears correctly, (3) 'Add root node' button opens editor in create mode with no parent, (4) selecting a node shows 'Add child node' button, (5) 'Add child node' opens editor with correct parent pre-selected, (6) long-press on node opens action menu with Edit/Delete/Move, (7) delete confirmation shows correct child count and calls HierarchyService.deleteNode on confirm, (8) move picker opens and HierarchyService.moveNode called on confirm, (9) tree refreshes after each mutation. E2E test (against Supabase test instance): full admin workflow — create root, add child, edit child name, move child to different root, delete node. Accessibility test: verify admin controls are not reachable by unauthorized roles in widget tests. Aim for 85%+ coverage.
If the AccessScopeService and the Supabase RLS policies use different logic to determine accessible units, a coordinator could see data in the client that RLS blocks server-side, causing confusing empty states, or worse, RLS could block data the scope service declares accessible.
Mitigation & Contingency
Mitigation: Define the canonical scope computation in a single Supabase Postgres function shared by both the RLS policies and the RPC endpoint called by AccessScopeService. The client-side service calls this RPC rather than reimplementing the logic, ensuring a single source of truth.
Contingency: Add integration tests that execute the same access decision through both the RLS policy path and the AccessScopeService path and assert identical results. Use these as regression guards in the CI pipeline.
When a user switches active chapter via the ChapterSwitcher, widgets that are already built may not receive the context-change event if they subscribe incorrectly to the ActiveChapterState BLoC, leading to stale data being displayed under the new chapter context.
Mitigation & Contingency
Mitigation: Use Riverpod's ref.watch on the active chapter provider at the root of each scoped data subtree rather than at individual leaf widgets. Trigger a global data refresh by invalidating all scoped providers when the chapter changes.
Contingency: Add an app-level chapter-change listener that forces a full navigation stack reset to the home screen on chapter switch, guaranteeing all widgets rebuild from scratch with the new context. Accept the UX cost of navigation reset for correctness.
Non-technical organization administrators may find the hierarchy management interface too complex for the structural changes they need to make frequently (e.g., chapter renaming, coordinator reassignment), leading to low adoption and continued reliance on manual processes.
Mitigation & Contingency
Mitigation: Conduct usability testing with at least one NHF administrator before finalizing the admin portal screen layout. Prioritize the most common operations (rename, reparent, add child) as primary actions in the UI. Include inline help text and confirmation dialogs with plain-language descriptions of consequences.
Contingency: Provide a simplified 'quick edit' mode that exposes only the three most common operations (rename, deactivate, add child) and hides advanced structural operations behind an 'Advanced' toggle.