Build Hierarchy Node Editor Screen

epic-organizational-hierarchy-management-admin-portal-task-015 — Implement the modal/screen for creating and editing hierarchy nodes. Include fields for node name, type (chapter/region/national/local), and parent unit selector using the tree view. Provide validation feedback from the HierarchyStructureValidator inline. Support both create-new and edit-existing modes. On save, call HierarchyService and propagate cache invalidation.

high priority medium complexity frontend pending frontend specialist Tier 5

Acceptance Criteria

Screen opens in create mode when no existing node is passed; opens in edit mode with pre-filled fields when an existing HierarchyNode is passed

Node name field is required; inline validation error shown if empty on save attempt

Node type selector offers exactly four options: Chapter, Region, National, Local — rendered as a segmented control or dropdown

Parent unit selector opens the HierarchyTreeView in a modal/sheet; selected parent is shown as a breadcrumb or name chip in the field

HierarchyStructureValidator runs inline after each relevant field change and displays constraint violations (e.g., 'A National node cannot have a Region as parent') without requiring a save attempt

Save button is disabled while any validation error is present

On save in create mode, HierarchyService.createNode() is called and the screen closes, returning the new node to the caller

On save in edit mode, HierarchyService.updateNode() is called and the screen closes with the updated node

Cache invalidation is triggered after successful save so the tree view reflects changes immediately

Loading indicator shown on the save button during the API call; button disabled to prevent double-submission

API error on save is shown as an inline error banner at the top of the form, not a dialog

Edit mode: node type and parent unit are editable but HierarchyStructureValidator still enforces rules

WCAG 2.2 AA: all form fields have labels, error messages are associated with their fields via Semantics

Technical Requirements

frameworks

Flutter

BLoC (flutter_bloc)

apis

HierarchyService.createNode(name, type, parentId)

HierarchyService.updateNode(nodeId, name, type, parentId)

HierarchyStructureValidator.validate(node)

data models

HierarchyNode

HierarchyNodeType

HierarchyStructureRule

performance requirements

Form renders and is interactive within 100ms of screen open

Inline validation feedback appears within 50ms of field change

Save API call completes and screen closes within 2 seconds under normal network conditions

security requirements

Only admin roles can access this screen — enforce role guard at the route level

Node type and parent selection must be validated server-side in HierarchyService, not just client-side

Do not expose internal node IDs in the UI beyond what is needed

ui components

AppTextField for node name

NodeTypeSegmentedControl or NodeTypeDropdown

ParentUnitSelectorField (tappable field that opens HierarchyTreeView picker)

InlineValidationErrorText

FormErrorBanner (top of form, API errors)

SaveButton with loading state

HierarchyTreeViewPickerSheet (reuse from task-014)

Execution Context

Execution Tier

Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

View Full Execution Plan

Implementation Notes

Use a single HierarchyNodeEditorCubit with a NodeEditorState that holds all form field values and validation status. The cubit accepts an optional HierarchyNode? existingNode in its constructor — if non-null, initialize state with existing values (edit mode). Run HierarchyStructureValidator synchronously within the cubit on each field update event; this keeps validation fast and avoids async complexity.

For the parent unit selector, open the HierarchyTreeView as a picker by pushing a route that returns a HierarchyNode? via Navigator.pop(context, selectedNode). Store the returned node in the cubit state. Use a GlobalKey with Flutter's Form widget for standard field validation, but also gate the save button on cubit state validity for structure rule violations that Form doesn't handle.

After a successful save, call a cache invalidation method on HierarchyService (or emit a cache-bust event via a shared repository) before popping the screen.

Testing Requirements

Write widget tests for: (1) create mode renders empty form, (2) edit mode pre-fills all fields, (3) empty name shows validation error on save, (4) invalid type-parent combination shows inline validator error, (5) save button disabled while errors present, (6) successful create calls HierarchyService.createNode and pops screen, (7) successful edit calls HierarchyService.updateNode and pops screen, (8) API error shows error banner without closing screen, (9) loading state shown during save. Unit test HierarchyStructureValidator logic independently with all valid and invalid combinations. Aim for 90%+ coverage on validator and 80%+ widget coverage on the editor screen.

Component

Hierarchy Admin Portal Screen

ui high

Dependencies (2)

Implement the interactive tree view widget for displaying the organization hierarchy. Support expand/collapse nodes, display member counts per node, highlight selected node, and render visual indentation for depth. Integrate search highlight for matching nodes. Widget must handle large trees (1400+ nodes for NHF) with lazy loading of child nodes. Connect to HierarchyService for data and support node selection callbacks. epic-organizational-hierarchy-management-admin-portal-task-014 Build the high-complexity service layer that encapsulates all hierarchy business logic. Provide methods for tree traversal, node lifecycle management (create/rename/move/delete), member count computation, and search. Coordinate between organization unit repository and hierarchy cache. This is the primary service consumed by admin portal and access scope. epic-organizational-hierarchy-management-admin-portal-task-007

Epic Risks (3)

high impact medium prob security

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.

medium impact medium prob integration

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.

medium impact medium prob scope

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.

Quick Links

All Tasks Execution Plan