ui

UI Patterns & Components

Overview

LionFire provides a comprehensive Blazor UI toolkit built on MudBlazor that integrates seamlessly with reactive data patterns, MVVM architecture, and workspace-scoped services. This documentation covers UI patterns, component usage, and best practices for building reactive Blazor applications.

Key Philosophy: Minimize boilerplate while maintaining flexibility. Components should work automatically with reactive data sources, but allow manual control when needed.

---

Documentation Structure

1. Blazor MVVM Patterns ⭐ START HERE

Essential reading for understanding when to use automatic vs. manual patterns.

Topics:

• ObservableDataView Pattern (Automatic) - Zero-boilerplate data grids
• Manual ViewModel Pattern - Full control for detail pages
• Decision flowchart - Which pattern to use?
• Complete examples - Both patterns side-by-side

When to Use:

• Building list or detail views
• Deciding between automatic and manual approaches
• Understanding reactive binding

---

2. Component Catalog

Reference guide for all available UI components.

Contents:

• ObservableDataView - Reactive data grid with CRUD
• InspectorView - Property grid inspector
• WorkspaceSelector - Workspace selection UI
• CascadingT - Type-safe cascading values
• Utility components

When to Use:

• Finding components for common scenarios
• Understanding component parameters
• Exploring advanced features

---

3. Reactive UI Updates

Deep dive into how reactive updates flow through the UI.

Topics:

• Change detection mechanisms
• Observable subscriptions
• StateHasChanged optimization
• Performance considerations

When to Use:

• Debugging update issues
• Optimizing performance
• Understanding internals

---

Quick Start

Pattern 1: Automatic List View (Recommended for Lists)

Use when: Displaying a list of workspace documents with standard CRUD operations.

@page "/bots" <ObservableDataView TKey="string" TValue="BotEntity" TValueVM="BotVM" DataServiceProvider="@WorkspaceServices" ReadOnly=false> <Columns> <PropertyColumn Property="x => x.Value.Name" /> <PropertyColumn Property="x => x.Value.Description" /> </Columns> </ObservableDataView> @code { [CascadingParameter(Name = "WorkspaceServices")] public IServiceProvider? WorkspaceServices { get; set; } }

What you get:

• ✅ Automatic data loading from workspace
• ✅ Built-in toolbar (Add, Edit, Delete)
• ✅ Reactive updates when files change
• ✅ Sorting, filtering, pagination
• ✅ ~20 lines of code total

---

Pattern 2: Manual Detail View (Recommended for Details)

Use when: Displaying/editing a single document with custom layout.

@page "/bots/{BotId}" <MudCard> <MudCardContent> <MudTextField Label="Name" @bind-Value="vm.Value.Name" /> <MudTextField Label="Description" @bind-Value="vm.Value.Description" /> <MudSwitch @bind-Checked="vm.Value.Enabled" Label="Enabled" /> </MudCardContent> <MudCardActions> <MudButton OnClick="Save" Color="Color.Primary">Save</MudButton> </MudCardActions> </MudCard> @code { [Parameter] public string? BotId { get; set; } [CascadingParameter(Name = "WorkspaceServices")] public IServiceProvider? WorkspaceServices { get; set; } ObservableReaderWriterItemVM<string, BotEntity, BotVM>? vm; protected override void OnInitialized() { var reader = WorkspaceServices.GetService<IObservableReader<string, BotEntity>>(); var writer = WorkspaceServices.GetService<IObservableWriter<string, BotEntity>>(); vm = new ObservableReaderWriterItemVM<string, BotEntity, BotVM>(reader, writer); vm.Id = BotId; // Automatically loads  } private async Task Save() { await vm.Write(); // Save to file  } }

What you get:

• ✅ Full layout control
• ✅ Automatic data loading/saving
• ✅ Reactive updates from file changes
• ✅ Custom validation and commands
• ✅ ~40 lines of code total

---

Core Concepts

1. Workspace-Scoped Services

Problem: UI components need access to workspace-specific data readers/writers.

Solution: Cascade WorkspaceServices (IServiceProvider) from layout to descendants.

<!-- Layout Component --> <CascadingValue Name="WorkspaceServices" Value="@WorkspaceServices"> @Body </CascadingValue> <!-- Child Component --> @code { [CascadingParameter(Name = "WorkspaceServices")] public IServiceProvider? WorkspaceServices { get; set; }  // Now can resolve workspace services  var reader = WorkspaceServices.GetService<IObservableReader<string, MyEntity>>(); }

Why: Each workspace has its own service provider with readers/writers pointing to that workspace's directories. See Service Scoping.

---

2. Reactive Data Binding

LionFire components automatically update when:

• Entity properties change (via INotifyPropertyChanged)
• Files are added/removed from workspace
• Observable collections emit changes

Requirements:

1. Entity must implement INotifyPropertyChanged
2. Use ReactiveObject or [ObservableProperty]
3. Component subscribes to observables

Example:

// ✅ Reactive Entity public partial class BotEntity : ReactiveObject { [Reactive] private string? _name; // Automatically notifies changes } // ❌ Non-Reactive Entity public class BotEntity { public string? Name { get; set; } // No notifications! }

---

3. ViewModel Layer

ViewModels wrap entities and provide UI-specific functionality:

// Entity (data model) public partial class BotEntity : ReactiveObject { [Reactive] private string? _name; [Reactive] private decimal _profitLoss; } // ViewModel (adds UI logic) public class BotVM : KeyValueVM<string, BotEntity> { public BotVM(string key, BotEntity value) : base(key, value) { } // Computed property for UI public string DisplayName => $"{Value.Name} ({Key})"; // UI-specific formatting public string ProfitLossFormatted => Value.ProfitLoss.ToString("C2"); // Commands public ReactiveCommand<Unit, Unit> ToggleEnabled { get; } }

When to Use VMs:

• Need computed properties for display
• Need commands for UI actions
• Want to keep entities pure (no UI logic)

---

4. Component Hierarchy

Application Root ↓ WorkspaceLayoutVM ↓ Cascades WorkspaceServices Blazor Pages (@page "/bots") ↓ Uses ObservableDataView (automatic) OR Manual ViewModel Pattern ↓ Both resolve IObservableReader/Writer ↓ Backed by File System (HJSON files) 

---

Patterns Summary

When to Use Each Pattern

Scenario	Pattern	Component/VM	Boilerplate
List View	Automatic	ObservableDataView	Minimal (~20 lines)
Detail View	Manual	ObservableReaderWriterItemVM	Medium (~40 lines)
Master-Detail	Hybrid	List uses ObservableDataView, detail uses manual VM	Mixed
Read-Only Display	Manual	ObservableReaderItemVM	Minimal
Custom Layout	Manual	Custom VM with direct reader/writer access	High (full control)

---

Architecture Integration

Layer Stack

UI Layer (Blazor Components) ↓ uses ViewModel Layer (KeyValueVM, ObservableReaderWriterItemVM) ↓ wraps Reactive Persistence Layer (IObservableReader/Writer) ↓ backed by File System (HJSON files in workspace) 

Service Resolution Flow

Blazor Component ↓ CascadingParameter WorkspaceServices (IServiceProvider) ↓ GetService<T>() IObservableReader<TKey, TValue> ↓ Points to workspace1/Bots/ directory 

---

Best Practices

1. Prefer ObservableDataView for Lists

<!-- ✅ Good - Minimal code --> <ObservableDataView TKey="string" TValue="Bot" TValueVM="BotVM" DataServiceProvider="@WorkspaceServices" /> <!-- ❌ Avoid - Manual list management --> @code { List<BotVM> bots; protected override async Task OnInitializedAsync() { var reader = WorkspaceServices.GetService<IObservableReader<string, Bot>>();  // Manual subscription, disposal, updates...  } }

---

2. Use Manual Pattern for Detail Views

<!-- ✅ Good - Full control over layout --> <MudCard> <MudTextField @bind-Value="vm.Value.Name" /> <MudTextField @bind-Value="vm.Value.Description" /> </MudCard> <!-- ❌ Avoid - ObservableDataView for single item --> <ObservableDataView ... /> <!-- Overkill for one item -->

---

3. Cascade WorkspaceServices, Not Individual Services

<!-- ✅ Good - Cascade provider --> <CascadingValue Name="WorkspaceServices" Value="@WorkspaceServices"> @Body </CascadingValue> <!-- ❌ Avoid - Cascading individual services --> <CascadingValue Value="@BotReader"> <CascadingValue Value="@BotWriter"> <CascadingValue Value="@PortfolioReader"> <!-- Too many cascades! --> </CascadingValue>

---

4. Use ReactiveObject for Entities

// ✅ Good - Reactive notifications public partial class BotEntity : ReactiveObject { [Reactive] private string? _name; } // ❌ Avoid - No change notifications public class BotEntity { public string? Name { get; set; } }

---

5. Dispose Subscriptions Properly

@implements IAsyncDisposable @code { IDisposable? subscription; protected override void OnInitialized() { subscription = reader.Values.Connect().Subscribe(changes => {  // Handle changes  }); } public async ValueTask DisposeAsync() { subscription?.Dispose(); } }

---

Common Scenarios

Scenario 1: Simple Read-Only List

<ObservableDataView TKey="string" TValue="Config" TValueVM="ConfigVM" DataServiceProvider="@WorkspaceServices" ReadOnly="true"> <Columns> <PropertyColumn Property="x => x.Value.Name" /> </Columns> </ObservableDataView>

---

Scenario 2: Editable List with Add/Delete

<ObservableDataView TKey="string" TValue="Bot" TValueVM="BotVM" DataServiceProvider="@WorkspaceServices" ReadOnly="false" CreatableTypes="@(new[] { typeof(Bot) })"> <Columns> <PropertyColumn Property="x => x.Value.Name" /> <TemplateColumn> <CellTemplate> <MudSwitch @bind-Checked="context.Item.Value.Enabled" /> </CellTemplate> </TemplateColumn> </Columns> </ObservableDataView>

---

Scenario 3: Master-Detail Navigation

List Page:

@page "/bots" <ObservableDataView ...> <Columns> <TemplateColumn> <CellTemplate> <MudButton Href="@($"/bots/{context.Item.Key}")">Edit</MudButton> </CellTemplate> </TemplateColumn> </Columns> </ObservableDataView>

Detail Page:

@page "/bots/{BotId}" <MudCard> <MudCardContent> <MudTextField @bind-Value="vm.Value.Name" /> <!-- Custom layout --> </MudCardContent> </MudCard> @code { [Parameter] public string? BotId { get; set; } ObservableReaderWriterItemVM<string, Bot, BotVM>? vm; }

---

Scenario 4: Custom Column Templates

<ObservableDataView ...> <Columns> <!-- Status indicator --> <TemplateColumn> <CellTemplate> <MudIcon Icon="@Icons.Material.Filled.Circle" Color="@(context.Item.Value.Enabled ? Color.Success : Color.Default)" /> </CellTemplate> </TemplateColumn> <!-- Action buttons --> <TemplateColumn> <CellTemplate> <MudIconButton Icon="@Icons.Material.Filled.PlayArrow" OnClick="@(() => StartBot(context.Item))" /> <MudIconButton Icon="@Icons.Material.Filled.Stop" OnClick="@(() => StopBot(context.Item))" /> </CellTemplate> </TemplateColumn> </Columns> </ObservableDataView>

---

Troubleshooting

Issue: "Unable to resolve service IObservableReader"

Cause: Using root DI container instead of workspace services.

Fix:

<!-- ❌ Wrong --> <ObservableDataView DataServiceProvider="@ServiceProvider" /> <!-- ✅ Correct --> <ObservableDataView DataServiceProvider="@WorkspaceServices" />

---

Issue: UI not updating when entity changes

Cause: Entity doesn't implement INotifyPropertyChanged.

Fix:

// ❌ Wrong public class Bot { public string Name { get; set; } } // ✅ Correct public partial class Bot : ReactiveObject { [Reactive] private string? _name; }

---

Issue: Component shows empty grid

Check:

1. Is DataServiceProvider set to WorkspaceServices?
2. Are files present in workspace directory?
3. Is entity type registered with AddWorkspaceChildType<T>()?
4. Check console for errors

Debug:

var reader = WorkspaceServices.GetService<IObservableReader<string, Bot>>(); Console.WriteLine($"Keys: {string.Join(", ", reader?.Keys.Items)}");

---

Related Documentation

Architecture

• Workspace Architecture - High-level workspace concepts
• Service Scoping - Understanding workspace services
• MVVM Architecture - ViewModel patterns

Project Documentation

• LionFire.Blazor.Components.MudBlazor - ObservableDataView deep dive
• LionFire.Data.Async.Mvvm - ViewModels and reactive patterns
• LionFire.Reactive - Observable readers/writers

Guides

• How-To: Create Blazor Workspace Page - Step-by-step tutorial

---

Summary

LionFire's Blazor UI toolkit provides two primary patterns:

Automatic Pattern (Lists)

• Component: ObservableDataView
• Boilerplate: Minimal (~20 lines)
• Use for: Lists, grids, CRUD

Manual Pattern (Details)

• ViewModel: ObservableReaderWriterItemVM
• Boilerplate: Medium (~40 lines)
• Use for: Detail views, custom layouts

Key Benefit: Both patterns integrate seamlessly with workspace-scoped services and reactive data persistence, eliminating manual subscription management and state synchronization.

Next Steps:

1. Read Blazor MVVM Patterns for detailed examples
2. Browse Component Catalog for available components
3. Check Reactive UI Updates for performance optimization