HopDev.Tree.EntityFramework 2.1.0

HopDev.Tree

A cross-platform hierarchical tree control for .NET MAUI, Avalonia, WPF, and Blazor with built-in database persistence, CRUD operations, drag-and-drop, search, checkboxes, accessibility, and localization.

Key Features

Core Architecture

• 4 platforms, 1 ViewModel — shared TreeViewModel, services, and business logic across MAUI, Avalonia, WPF, and Blazor
• Items within nodes — dual entity model (folders + items) in a single tree with independent selection, drag-drop, and context menus
• Multiple hierarchies — host multiple independent trees in a single database, isolated by HierarchyName and SubsystemName
• Auto-create on first load — hierarchies and root nodes are automatically created when referenced for the first time
• ReadOnly mode — TreeInteractionMode.ReadOnly disables editing, drag-drop, and context menus while keeping selection and expansion
• 407 unit tests — comprehensive coverage across core, services, repositories, integration, and edge cases

Database & Persistence

• Database-first — built-in EF Core persistence with 5 providers: SQLite, SQL Server, PostgreSQL, MySQL, Oracle
• Auto-create tables — tables are created automatically on first use (or opt out for migration-based workflows)
• Configurable table prefix — default tree_ prefix (e.g., tree_hierarchy, tree_node, tree_nodeitem), customizable or removable
• Schema support — optional schema isolation for SQL Server, PostgreSQL, and Oracle
• Audit fields — automatic CreatedAt, CreatedBy, ModifiedAt, ModifiedBy tracking on all entities (UTC, DOMAIN\Username format)
• Custom user identity — provide a GetCurrentUser function for web apps or override the default OS user detection
• Sort order management — automatic sort order assignment and reordering on drag-and-drop operations
• Expand state persistence — expanded/collapsed state is tracked and restored across reloads

CRUD Operations

• Built-in context menus — right-click menus with Add Folder, Add Root Folder, Add Item, Rename, Delete, Change Icon, Reset Icon
• Customizable context menu labels — all menu text comes from ITreeStringProvider, fully localizable
• Custom Add Item dialog — host applications implement OnAddItemRequestedAsync to provide their own UI for adding items with EntityType and EntityId
• Customizable Add Item label — AddItemLabel property to change the context menu text (e.g., "Add Document", "Add Employee")
• Validation hooks — ValidateNodeNameAsync and ValidateItemNameAsync for custom name validation rules
• Confirmation hooks — ConfirmDeleteNodeAsync and ConfirmDeleteItemAsync for custom delete confirmation logic
• Batch operations — AddItemRangeAsync, DeleteNodesAsync, DeleteItemsAsync for bulk operations
• Fully customizable dialogs — IDialogService interface with PromptAsync, ConfirmAsync, AlertAsync — override to use your own dialog system

Selection

• Single selection — click to select a node or item, clears previous selection
• Multi-selection — TreeSelectionMode.Multiple with Ctrl+Click toggle, Shift+Click range select
• Select All — Ctrl+A selects all visible nodes and items (multi-selection mode)
• Clear selection — programmatic ClearSelection() method
• SelectionChanged event — fired with AddedNodes, RemovedNodes, AddedItems, RemovedItems collections
• Allow/disallow node selection — AllowNodeSelection property to make the tree item-selection-only

Drag-and-Drop

• Internal drag-and-drop — reorder nodes and items within the tree with visual drop indicators
• External drop support — NodesAllowExternalDrop enables dropping external content onto tree nodes
• Drag-drop toggle — NodesAllowInternalDragDrop to enable/disable reordering independently of other editing
• Drop zone indicators — colored indicators show valid (green) and invalid (red) drop targets
• NodeDragOver / NodeDrop events — host applications can handle or cancel drops programmatically

Search

• Inline search bar — ShowInternalSearchBar toggles a built-in search UI with match count display
• Highlight mode — shows all nodes/items, visually emphasizes matches
• Filter mode — hides non-matching nodes/items, showing only matches and their ancestor path
• Search scope — SearchScope.NodeNames, ItemNames, or Both
• Next/Previous navigation — step through matches with navigation buttons
• SearchChanged event — fired when search text or results change
• Programmatic search — bind SearchText and FilterMode properties directly

Checkboxes

• Three-state checkboxes — Unchecked, Checked, Indeterminate (parent shows indeterminate when children are mixed)
• Cascading checks — parent↔child cascading with CascadingChecks property
• Checkbox scope — CheckboxScope.NodesOnly, ItemsOnly, or Both
• Database persistence — PersistCheckState saves check state to the database automatically
• Check/Uncheck All — CheckAllAsync() and UncheckAllAsync() methods
• GetCheckedNodes / GetCheckedItems — retrieve all currently checked entities
• CheckedChanged event — fired when any checkbox state changes

Custom Node Icons

• Per-node images — NodeImage stored as byte[] in the database (varbinary/BLOB)
• Built-in icon picker — enable with AllowCustomNodeIcons for a Change Icon / Reset Icon context menu
• Custom icon dialog — implement OnCustomIconRequestedAsync in ITreeActions to provide your own icon picker
• Default icon provider — ITreeIconProvider returns SVG path geometry for folder, item, and chevron icons — override for custom iconography

Theming

• 4 built-in themes — Light, Dark, High Contrast (WCAG AAA), System (follows OS)
• 15 color tokens — Background, Foreground, Hover, Selection, SelectionForeground, Accent, DropIndicator, DropTarget, InvalidDrop, SearchHighlight, SearchBarBackground, SearchBarBorder, FolderIcon, ItemIcon, CheckboxCheckedBackground
• Per-theme customization — override individual tokens via LightThemeColors, DarkThemeColors, HighContrastThemeColors properties
• WPF theme resources — LightTheme.xaml, DarkTheme.xaml, HighContrastTheme.xaml resource dictionaries
• Runtime theme switching — change theme at any time without reloading the tree

Accessibility

• MAUI — SemanticProperties.Description, SemanticProperties.Hint, AutomationProperties.IsInAccessibleTree, AutomationId on every node and item
• Avalonia — AutomationProperties integration
• Blazor — 10+ ARIA attributes (role="tree", role="search", aria-label, aria-live, aria-atomic, aria-hidden, role="status", role="alert")
• AutomationIds — unique TreeNode_{id} and TreeItem_{id} identifiers for UI testing

Keyboard Navigation

• Arrow keys — Up/Down to move between rows, Left/Right to collapse/expand nodes
• Home/End — jump to first/last visible row
• Enter/Space — activate selected item or toggle node expansion
• F2 — rename selected node or item
• Delete — delete selected node or item (with confirmation)
• Ctrl+A — select all (multi-selection mode)

Localization

• 28 localizable strings — context menus, dialog titles, prompts, confirmations, search placeholder, buttons
• ITreeStringProvider interface — implement for full localization, or subclass DefaultTreeStringProvider to override specific strings
• 30 sample languages — including RTL languages (Arabic, Hebrew)
• Runtime language switching — change StringProvider at any time without reloading
• RTL support — IsRightToLeft property mirrors the entire control layout

Typography & Kiosk Mode

• Font tokens — TreeFontSize (default 14), TreeFontFamily, KioskFontScale (default 1.3×)
• Kiosk mode — KioskMode property enables touch-optimized display with larger hit targets and scaled fonts

Events & Host Integration

• Node lifecycle events — OnNodeExpandingAsync, OnNodeExpandedAsync, OnNodeCollapsingAsync, OnNodeCollapsedAsync, OnNodeSelectedAsync, OnNodeAddedAsync, OnNodeRenamedAsync, OnNodeDeletedAsync, OnNodeMovedAsync
• Item lifecycle events — OnItemSelectedAsync, OnItemActivatedAsync (double-click/tap), OnItemAddedAsync, OnItemRenamedAsync, OnItemDeletedAsync, OnItemMovedAsync
• Control events — SelectionChanged, SearchChanged, CheckedChanged, NodeDragOver, NodeDrop
• ITreeActions interface — single implementation point for all host callbacks with DefaultTreeActions base class

Virtualization & Performance

• MAUI — flat row list drives CollectionView with UI virtualization; only visible rows are rendered
• Blazor — Blazor <Virtualize> component with configurable RowHeight and OverscanCount
• Avalonia / WPF — flat row list with efficient expand/collapse updates
• Expand state tracking — collapsed subtrees are excluded from the flat row list for minimal memory footprint

Programmatic API

• Navigation — ExpandNode, CollapseNode, ExpandAll, CollapseAll, ScrollToNodeAsync, ScrollToItemAsync
• CRUD — AddNodeAsync, RenameNodeAsync, DeleteNodeAsync, MoveNodeAsync, AddItemAsync, RenameItemAsync, DeleteItemAsync, MoveItemAsync, AddItemRangeAsync, UpdateNodeImageAsync
• Hierarchy management — CreateHierarchyAsync, UpdateHierarchyNameAsync, DeleteHierarchyAsync, GetHierarchiesBySubsystemAsync
• Stats — GetNodeCount(), GetItemCount()

Logging

• ILogger integration — structured logging via Microsoft.Extensions.Logging
• 4 severity levels — Debug, Information, Warning, Error with contextual properties
• Exception capture — errors during CRUD operations are logged with full exception details

Solution Structure

HopDev.Tree.slnx
├── src/
│   ├── HopDev.Tree.Core                    Core models, enums, abstractions
│   ├── HopDev.Tree.UI                      Shared ViewModels, services, business logic
│   ├── HopDev.Tree.EntityFramework         EF Core repositories and unit of work
│   ├── HopDev.Tree.EntityFramework.*       Provider packages (Sqlite, SqlServer, PostgreSql, MySql, Oracle)
│   ├── HopDev.Tree.Maui                    .NET MAUI tree control
│   ├── HopDev.Tree.Avalonia               Avalonia tree control
│   ├── HopDev.Tree.Wpf                    WPF tree control
│   └── HopDev.Tree.Web                    Blazor tree control
├── samples/
│   ├── HopDev.Tree.Sample                  MAUI sample app
│   ├── HopDev.Tree.Avalonia.Sample        Avalonia sample app
│   └── HopDev.Tree.Wpf.Sample            WPF sample app
├── tests/
│   └── HopDev.Tree.Tests                  407 unit tests
└── docs/                                   Architecture, API, guides, ADRs, designs

Quick Start

MAUI

<ct:TreeControl x:Name="TreeControl"
                HierarchyName="MyApp"
                SubsystemName="Documents" />

TreeControl.Initialize(unitOfWork, actions);
await TreeControl.LoadAsync();

Avalonia

<tree:TreeControl x:Name="TreeControl" />

TreeControl.Initialize(unitOfWork, actions);
await TreeControl.LoadAsync();

WPF

<tree:TreeControl x:Name="TreeControl" />

TreeControl.Initialize(unitOfWork, actions);
await TreeControl.LoadAsync();

Blazor

<TreeControl HierarchyName="MyApp" SubsystemName="Documents"
             UnitOfWork="@unitOfWork" Actions="@actions" />

License

MIT