Avalonia Zafiro Development

# Avalonia, Zafiro & Reactive Rules

## Avalonia UI Rules

- **Strict Avalonia**: Never use `System.Drawing`; always use Avalonia types.
- **Pure ViewModels**: ViewModels must **never** reference Avalonia types.
- **Bindings Over Code-Behind**: Logic should be driven by bindings.
- **DataTemplates**: Prefer explicit `DataTemplate`s and typed `DataContext`s.
- **VisualStates**: Avoid using `VisualStates` unless absolutely required.

## Zafiro Guidelines

- **Prefer Abstractions**: Always look for existing Zafiro helpers, extension methods, and abstractions before re-implementing logic.
- **Validation**: Use Zafiro's `ValidationRule` and validation extensions instead of ad-hoc reactive logic.

## DynamicData & Reactive Rules

### The Mandatory Approach

- **Operator Preference**: Always prefer **DynamicData** operators (`Connect`, `Filter`, `Transform`, `Sort`, `Bind`, `DisposeMany`) over plain Rx operators when working with collections.
- **Readable Pipelines**: Build and maintain pipelines as a single, readable chain.
- **Lifecycle**: Use `DisposeWith` for lifecycle management.
- **Minimal Subscriptions**: Subscriptions should be minimal, centralized, and strictly for side-effects.

### Forbidden Anti-Patterns

- **Ad-hoc Sources**: Do NOT create new `SourceList` / `SourceCache` on the fly for local problems.
- **Logic in Subscribe**: Do NOT place business logic inside `Subscribe`.
- **Operator Mismatch**: Do NOT use `System.Reactive` operators if a DynamicData equivalent exists.

### Canonical Patterns

**Validation of Dynamic Collections:**
```csharp
this.ValidationRule(
        StagesSource
            .Connect()
            .FilterOnObservable(stage => stage.IsValid)
            .IsEmpty(),
        b => !b,
        _ => "Stages are not valid")
    .DisposeWith(Disposables);
```

**Filtering Nulls:**
Use `WhereNotNull()` in reactive pipelines.
```csharp
this.WhenAnyValue(x => x.DurationPreset).WhereNotNull()
```


# Core Technical Skills & Architecture

## Mandatory Expertise

The developer must possess strong expertise in:
- **C# and modern .NET**: Utilizing the latest features of the language and framework.
- **Avalonia UI**: For cross-platform UI development.
- **MVVM Architecture**: Maintaining strict separation between UI and business logic.
- **Clean Code & Clean Architecture**: Focusing on maintainability and inward dependency flow.
- **Functional Programming in C#**: Embracing immutability and functional patterns.
- **Reactive Programming**: Expertise in DynamicData and System.Reactive.

## Architectural Principles

- **Pure MVVM**: Mandatory for all UI code. Logic must be independent of UI concerns.
- **Composition over Inheritance**: Favor modular building blocks over deep inheritance hierarchies.
- **Inward Dependency Flow**: Abstractions must not depend on implementations.
- **Immutability**: Prefer immutable structures where practical to ensure predictability.
- **Stable Public APIs**: Design APIs carefully to ensure long-term stability and clarity.


# Naming & Coding Standards

## General Standards

- **Explicit Names**: Favor clarity over cleverness.
- **Async Suffix**: Do **NOT** use the `Async` suffix in method names, even if they return `Task`.
- **Private Fields**: Do **NOT** use the `_` prefix for private fields.
- **Static State**: Avoid static state unless explicitly justified and documented.
- **Method Design**: Keep methods small, expressive, and with low cyclomatic complexity.

## Error Handling

- **Result & Maybe**: Use types from **CSharpFunctionalExtensions** for flow control and error handling.
- **Exceptions**: Reserved strictly for truly exceptional, unrecoverable situations.
- **Boundaries**: Never allow exceptions to leak across architectural boundaries.


# Common Patterns in Angor/Zafiro

## Refreshable Collections

The `RefreshableCollection` pattern is used to manage lists that can be refreshed via a command, maintaining an internal `SourceCache`/`SourceList` and exposing a `ReadOnlyOb