Avalonia Layout Zafiro

# Interactions and Logic

To keep XAML clean and maintainable, minimize logic in views and avoid excessive use of converters.

## 🎭 Xaml.Interaction.Behaviors

Use `Interaction.Behaviors` to handle UI-related logic that doesn't belong in the ViewModel, such as focus management, animations, or specialized event handling.

```xml
<TextBox Text="{Binding Address}">
    <Interaction.Behaviors>
        <UntouchedClassBehavior />
    </Interaction.Behaviors>
</TextBox>
```

### Why use Behaviors?
- **Encapsulation**: UI logic is contained in a reusable behavior class.
- **Clean XAML**: Avoids code-behind and complex XAML triggers.
- **Testability**: Behaviors can be tested independently of the View.

## 🚫 Avoiding Converters

Converters often lead to "magical" logic hidden in XAML. Whenever possible, prefer:

1.  **ViewModel Properties**: Let the ViewModel provide the final data format (e.g., a `string` formatted for display).
2.  **MultiBinding**: Use for simple logic combinations (And/Or) directly in XAML.
3.  **Behaviors**: For more complex interactions that involve state or events.

### When to use Converters?
Only use them when the conversion is purely visual and highly reusable across different contexts (e.g., `BoolToOpacityConverter`).

## 🧩 Simplified Interactions

If you find yourself needing a complex converter or behavior, consider if the component can be simplified or if the data model can be adjusted to make the view binding more direct.


# Building Generic Components

Reducing nesting and complexity is achieved by breaking down views into generic, reusable components.

## 🧊 Generic Components

Instead of building large, complex views, extract recurring patterns into small `UserControl`s.

### Example: A generic "Summary Item"
Instead of repeating a `Grid` with labels and values:

```xml
<!-- ❌ BAD: Repeated Grid -->
<Grid ColumnDefinitions="*,Auto">
   <TextBlock Text="Total:" />
   <TextBlock Grid.Column="1" Text="{Binding Total}" />
</Grid>
```

Create a generic component (or use `EdgePanel` with a Style):

```xml
<!-- ✅ GOOD: Use a specialized control or style -->
<EdgePanel StartContent="Total:" EndContent="{Binding Total}" Classes="SummaryItem" />
```

## 📉 Flattening Layouts

Avoid deep nesting. Deeply nested XAML is hard to read and can impact performance.

- **StackPanel vs Grid**: Use `StackPanel` (with `Spacing`) for simple linear layouts.
- **EdgePanel**: Great for "Label - Value" or "Icon - Text - Action" rows.
- **UniformGrid**: Use for grids where all cells are the same size.

## 🔧 Component Granularity

- **Atomical**: Small controls like custom buttons or icons.
- **Molecular**: Groups of atoms like a `HeaderedContainer` with specific content.
- **Organisms**: Higher-level sections of a page.

Aim for components that are generic enough to be reused but specific enough to simplify the parent view significantly.


# Semantic Containers

Using the right container for the data type simplifies XAML and improves maintainability. `Zafiro.Avalonia` provides specialized controls for common layout patterns.

## 📦 HeaderedContainer

Prefer `HeaderedContainer` over a `Border` or `Grid` when a section needs a title or header.

```xml
<HeaderedContainer Header="Security Settings" Classes="WizardSection">
    <StackPanel>
        <!-- Content here -->
    </StackPanel>
</HeaderedContainer>
```

### Key Properties:
- `Header`: The content or string for the header.
- `HeaderBackground`: Brush for the header area.
- `ContentPadding`: Padding for the content area.

## ↔️ EdgePanel

Use `EdgePanel` to position elements at the edges of a container without complex `Grid` definitions.

```xml
<EdgePanel StartContent="{Icon fa-wallet}" 
           Content="Wallet Balance" 
           EndContent="$1,234.00" />
```

### Slots:
- `StartContent`: Aligned to the left (or beginning).
- `Content`: Fills the remaining space in the middle.
- `EndContent`: Aligned to the right (or end).

## 📇 Card

A simple container for groupi