# Joufflu WPF Components - full documentation

> Every documentation page of Joufflu concatenated in one file. Index with one-line summaries: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/llms.txt

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/index.md -->

# Joufflu WPF Components

**A modern WPF component library that makes your desktop apps look good by
default.**

WPF inputs and reusable components for .NET, built on a design system of themed
brushes, dimensions and layout helpers. Every control reads its colours through
`DynamicResource`, so the whole UI re-themes live between Light and Dark — no
restart, no flicker.

These pages mirror the controls in the **`Joufflu.Samples`** gallery app — same
titles, descriptions and code snippets. Each control page lists example markup you
can paste into your views.

{: .note }
> **Using an LLM agent?** Point it at the machine-readable
> [`llms.txt`](https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/llms.txt)
> index — a single file linking every page's raw Markdown source, or
> [`llms-full.txt`](https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/llms-full.txt)
> for every page in one file. Use those raw URLs rather
> than the rendered site, which can return `403` to automated fetchers.

## Highlights

- 🌗 **Live Light / Dark theming** — flip the theme at runtime and every control follows instantly.
- 🎨 **A real design system, built to be customized** — semantic colours, dimensions, sizing and spacing exposed as override-able resource keys; the gallery's **Customize theme** window (palette button in its title bar) edits them live and generates the dictionary.
- 🧩 **Ready-to-use inputs** — numeric, decimal and timespan pickers, searchable and tag combo boxes, file and colour pickers, inline-editable text, dropdowns.
- 🧭 **Navigation & overlays** — a navigation menu, a view-model-first page container, awaitable modal dialogs and a paging selector.
- 🗂️ **A file explorer** — breadcrumb, folder tree and file list sharing a source, with shell-backed file operations and nodes of your own.
- 🧾 **JSON data trees** — fill a value in against a JSON Schema, or build one from scratch.
- 🪟 **Custom-chrome window & natives** — a themed application shell plus restyled built-in WPF controls that match out of the box.
- 📦 **Modular packages** — take just the core styles, or add inputs and navigation only where you need them.

{: .note }
> The gallery's **Native controls** group — WPF's built-in controls restyled to match the
> design system (text boxes, combo boxes, data grid, …) — is mostly undocumented
> here; only natives with named style variants are (see
> [Native controls](natives/index.md)). Otherwise these pages cover the
> custom controls the library adds.

## Sections

| Section | What's inside |
|---|---|
| [Themes](themes/index.md) | The application shell (`ThemedWindow`), `ThemeManager`, the design tokens and the live theme customizer |
| [Native controls](natives/index.md) | Text sizes and muted text, `FontIcon` and `Chevron`, the `Card` styles, buttons and toggle buttons (solid, soft & outline variants) |
| [Toolkit](toolkit/index.md) | Sizing, spacing, derived dimensions, tooltips, animation, drag and drop, shared width, creating a custom control |
| [Joufflu controls](controls/index.md) | The optional packages: [Feedback](feedback/index.md) (`Badge`, `Spinner`, toasts), [Inputs](inputs/index.md) (numeric, search, combo boxes, pickers, `Dropdown`…), [Navigation](navigation/index.md) (`NavigationMenu`, overlays, `Paging`), [Data](data/index.md) (`DataFill`, `DataEdit`, `DataDisplay`) and [File explorer](file-explorer/index.md) |

## Getting started

1. Add the packages you need. `Joufflu` is the core (styles & theming);
   `Joufflu.Data`, `Joufflu.Feedback`, `Joufflu.FileExplorer`, `Joufflu.Inputs` and
   `Joufflu.Navigation` are optional and all build on it:

   ```sh
   dotnet add package Joufflu
   dotnet add package Joufflu.Data          # optional: JSON data trees (needs Joufflu.Inputs)
   dotnet add package Joufflu.Feedback      # optional: badges, spinner, toasts
   dotnet add package Joufflu.FileExplorer  # optional: file explorer (needs Joufflu.Feedback)
   dotnet add package Joufflu.Inputs        # optional: input controls
   dotnet add package Joufflu.Navigation    # optional: navigation & overlays
   ```

2. Merge the control styles in `App.xaml` so the themed styles and the
   `joufflu:Dimensions` keys are available (the `joufflu:Brushes` come with the
   theme, step 3):

   ```xml
   <Application.Resources>
       <ResourceDictionary>
           <ResourceDictionary.MergedDictionaries>
               <ResourceDictionary Source="pack://application:,,,/Joufflu;component/Resources.xaml" />
           </ResourceDictionary.MergedDictionaries>
       </ResourceDictionary>
   </Application.Resources>
   ```

3. Initialize the theme manager once at startup, before the first window shows:

   ```csharp
   // App.xaml.cs — OnStartup
   ThemeManager.Instance.Initialize();
   ```

4. Use the controls as shown in the pages above.

New to the library? The [Tutorial](tutorial.md) builds a full
navigable app shell — side menu, pages, modals and toasts — from scratch, and the
[Recipes](recipes.md) give copy-paste screens. Choosing between UI libraries? See
[Joufflu vs other WPF UI libraries](comparison.md).

To explore everything interactively, run the **`Joufflu.Samples`** project.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/tutorial.md -->

# Tutorial: a navigable app shell

Builds a small MVVM app on `Joufflu.Navigation`: a collapsible side menu that
switches pages, a shared shell view model owning the navigation services, an
example page, and a modal overlay plus a toast raised from it. The result
matches the wiring the **`Joufflu.Samples`** gallery uses.

{: .note }
> Assumes the packages are installed and `App.xaml` merges the Joufflu resource
> dictionaries, with `ThemeManager.Instance.Initialize()` called at startup. See
> [Getting started](index.md#getting-started) first if not.

The snippets use these namespaces:

```xml
xmlns:controls="clr-namespace:Joufflu.Controls;assembly=Joufflu"
xmlns:feedback="clr-namespace:Joufflu.Feedback.Controls;assembly=Joufflu.Feedback"
xmlns:fonts="clr-namespace:Joufflu.Assets.Fonts;assembly=Joufflu"
xmlns:nav="clr-namespace:Joufflu.Navigation.Controls;assembly=Joufflu.Navigation"
xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu"
```

## How it fits together

Three services drive everything, shared between the shell window and the pages:

| Service | Role |
|---|---|
| `Navigator` | Holds the current page (a view model) and switches between pages. Built with a resolver turning a page type into the page instance. |
| `Overlayer` | Shows modal overlays on top of the current page. |
| `ToastService` | Shows stacking, auto-dismissing notifications. |

Navigation is **view-model-first**: navigate to a *view model* and WPF resolves
the matching *view* through an implicit `DataTemplate`. A plain `ContentControl`
bound to `Navigator.CurrentPage` renders the current page; `NavigationMenu` drives
the same `Navigator` from the side; `OverlayContainer` and `ToastContainer` wrap
the whole app and host the overlay and toast stacks above it.

## Step 1 — The shared shell view model

The shell view model owns the three services so the window and every page share
the same instances. It also keeps a registry of pages keyed by their own type,
which is what the menu items target. It starts empty; the first page is added in
Step 4.

```csharp
using CommunityToolkit.Mvvm.ComponentModel;
using Joufflu.Feedback;
using Joufflu.Navigation;

public class ShellViewModel : ObservableObject
{
    // Shared with the shell window's page container, NavigationMenu and the
    // overlay/toast containers, and injected into the pages that need them.
    public Navigator Navigator { get; }
    public Overlayer Overlays { get; } = new();
    public ToastService Toasts { get; } = new();

    // Pages keyed by their own type, which is what the menu's NavigationItems
    // target. Filled in as we add pages (Step 4).
    private readonly Dictionary<Type, object> _pages = new();

    public ShellViewModel()
    {
        // The navigator turns an item's target type into the page to display.
        Navigator = new Navigator(target => _pages.GetValueOrDefault(target));
    }
}
```

## Step 2 — Map view models to views

An implicit `DataTemplate` (a `DataType` with no `x:Key`) maps each view model to
its view. Add one per page, typically in `App.xaml`. The `HomeViewModel` /
`HomeView` pair comes in Step 4; here is the mapping it needs:

```xml
<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <!-- Joufflu resource dictionaries merged here (see Getting started) -->
        </ResourceDictionary.MergedDictionaries>

        <!-- One DataTemplate per page: the view model resolves to its view. -->
        <DataTemplate DataType="{x:Type vm:HomeViewModel}">
            <views:HomeView />
        </DataTemplate>
    </ResourceDictionary>
</Application.Resources>
```

The same mechanism resolves overlay content — add a `DataTemplate` for every
overlay view model too (Step 5).

## Step 3 — The shell window

A `ThemedWindow` whose content is a `ToastContainer` around an `OverlayContainer`,
wrapping the side `NavigationMenu` and the page `ContentControl`. Bind everything to
the shell view model's services so they stay in sync: selecting a menu item navigates
the page, and the overlays/toasts use the shared services.

Wrapping the *whole* app rather than the page area only is what lets a full screen
overlay cover the entire window, side menu included. Toasts wrap the overlays in
turn, so they stay on top of them.

The `d:DataContext` line gives the XAML designer the runtime view-model type, so
bindings like `{Binding Navigator}` get IntelliSense and design-time validation.
No runtime effect.

```xml
<controls:ThemedWindow
    x:Class="MyApp.ShellWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:controls="clr-namespace:Joufflu.Controls;assembly=Joufflu"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:feedback="clr-namespace:Joufflu.Feedback.Controls;assembly=Joufflu.Feedback"
    xmlns:fonts="clr-namespace:Joufflu.Assets.Fonts;assembly=Joufflu"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:nav="clr-namespace:Joufflu.Navigation.Controls;assembly=Joufflu.Navigation"
    xmlns:vm="clr-namespace:MyApp.ViewModels"
    Title="My App"
    Width="1000"
    Height="640"
    d:DataContext="{d:DesignInstance Type=vm:ShellViewModel}"
    mc:Ignorable="d">
    <!-- Each container wraps the app and stacks its own layer above it. -->
    <feedback:ToastContainer Toasts="{Binding Toasts}">
        <nav:OverlayContainer Overlays="{Binding Overlays}">
            <DockPanel>
                <nav:NavigationMenu DockPanel.Dock="Left" Navigator="{Binding Navigator}">

                    <!-- An item targets the type of the page it navigates to. -->
                    <nav:NavigationItem TargetType="{x:Type vm:HomeViewModel}">
                        <nav:NavigationItem.Icon>
                            <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Home}" />
                        </nav:NavigationItem.Icon>
                        Home
                    </nav:NavigationItem>
                </nav:NavigationMenu>

                <!-- Renders the current page, resolved by its implicit DataTemplate. -->
                <ContentControl Content="{Binding Navigator.CurrentPage}" />
            </DockPanel>
        </nav:OverlayContainer>
    </feedback:ToastContainer>
</controls:ThemedWindow>
```

Its code-behind (`ShellWindow.xaml.cs`) must derive from `ThemedWindow` too
(`public partial class ShellWindow : ThemedWindow`), or the build fails on the
mismatched base class.

Create the window in code to pass the shell view model as its `DataContext`,
e.g. in `App.xaml.cs` (`using Joufflu.Themes;` for `ThemeManager`):

```csharp
protected override void OnStartup(StartupEventArgs e)
{
    base.OnStartup(e);
    ThemeManager.Instance.Initialize();

    var shell = new ShellViewModel();
    new ShellWindow { DataContext = shell }.Show();
}
```

{: .note }
> Remove `StartupUri="MainWindow.xaml"` from `App.xaml`, or WPF opens that window
> too and you end up with two.

{: .note }
> Each item's `TargetType` is passed to the navigator's resolver, which returns
> the page. Add more items with the Step 4 recipe. A `NavigationGroup` expands to
> reveal children instead of navigating; a `NavigationTitle` is a section label.
> See [Navigation menu](navigation/navigation-menu.md) for the full
> markup.

## Step 4 — An example page

A page is a view model plus a matching view. The view model takes the shared
services to open overlays and raise toasts:

```csharp
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using Joufflu.Feedback;
using Joufflu.Navigation;

public class HomeViewModel : ObservableObject
{
    private readonly IOverlayer _overlays;
    private readonly IToastService _toasts;

    public IRelayCommand SayHelloCommand { get; }
    public IAsyncRelayCommand DeleteCommand { get; }

    public HomeViewModel(IOverlayer overlays, IToastService toasts)
    {
        _overlays = overlays;
        _toasts = toasts;

        SayHelloCommand = new RelayCommand(SayHello);
        DeleteCommand = new AsyncRelayCommand(DeleteAsync);
    }

    // ... commands implemented in Step 5 ...
}
```

Its view:

```xml
<UserControl
    x:Class="MyApp.Views.HomeView"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"
    xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu">
    <StackPanel Margin="{DynamicResource {x:Static joufflu:Dimensions.Spacing}}" toolkit:Spacing.Gap="12">
        <TextBlock toolkit:Sizing.Size="xl" FontWeight="Bold" Text="Home" />
        <StackPanel Orientation="Horizontal" toolkit:Spacing.Gap="8">
            <Button Command="{Binding SayHelloCommand}" Content="Say hello" />
            <Button Command="{Binding DeleteCommand}" Content="Delete…"
                    Style="{StaticResource DangerButton}" />
        </StackPanel>
    </StackPanel>
</UserControl>
```

Register the page in the shell and land on it at startup. In `ShellViewModel`
(Step 1), the constructor builds the page with the shared services and navigates
to it:

```csharp
public ShellViewModel()
{
    // Register the page under its own type, which is what its NavigationItem targets.
    _pages[typeof(HomeViewModel)] = new HomeViewModel(Overlays, Toasts);

    Navigator = new Navigator(target => _pages.GetValueOrDefault(target));

    // Navigate to the default page so the window doesn't start empty.
    Navigator.Navigate(typeof(HomeViewModel));
}
```

The recipe per page, repeated for each:

1. Write its view model and view.
2. Map them with a `DataTemplate` (Step 2).
3. Register the view model under its type in `_pages` (above).
4. Point a `NavigationItem` at that type (Step 3).

## Step 5 — Modals and toasts from the page

### A toast

One call on the shared `ToastService`. Toasts stack in the top-right and
auto-dismiss:

```csharp
private void SayHello() => _toasts.Success("Hello!", "Greetings");
```

### A modal overlay, then a toast with the result

`Overlayer.ShowAsync` returns a `Task<bool?>` that completes when the overlay
closes: `true` when the content validates it, `false` when it cancels it, `null`
when the user dismisses it with the close cross. The overlay content owns its
buttons and closes itself through the overlayer.

Overlay content view model:

```csharp
public class DeleteConfirmViewModel : ObservableObject
{
    private readonly IOverlayer _overlays;

    public string Message { get; }
    public IRelayCommand CancelCommand { get; }
    public IRelayCommand DeleteCommand { get; }

    public DeleteConfirmViewModel(IOverlayer overlays, string message)
    {
        _overlays = overlays;
        Message = message;
        // Cancel and Validate close this overlay and hand false / true to the awaiting ShowAsync.
        CancelCommand = new RelayCommand(() => _overlays.Cancel(this));
        DeleteCommand = new RelayCommand(() => _overlays.Validate(this));
    }
}
```

Its view (add a matching `DataTemplate` as in Step 2):

```xml
<UserControl
    x:Class="MyApp.Views.DeleteConfirmView"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu">
    <StackPanel MinWidth="320" toolkit:Spacing.Gap="16">
        <TextBlock Text="{Binding Message}" TextWrapping="Wrap" />
        <StackPanel HorizontalAlignment="Right" toolkit:Spacing.Gap="8" Orientation="Horizontal">
            <Button Command="{Binding CancelCommand}" Content="Cancel"
                    Style="{StaticResource SecondaryButton}" />
            <Button Command="{Binding DeleteCommand}" Content="Delete"
                    Style="{StaticResource DangerButton}" />
        </StackPanel>
    </StackPanel>
</UserControl>
```

Open it from the page and react to the result with a toast:

```csharp
private async Task DeleteAsync()
{
    var content = new DeleteConfirmViewModel(_overlays, "Delete this item? This can't be undone.");
    var options = new OverlayOptions { Title = "Please confirm", CloseOnClickAway = false };

    bool? result = await _overlays.ShowAsync(content, options);

    if (result == true)
        _toasts.Success("Item deleted.", "Confirmed");
    else
        _toasts.Info("Cancelled.");
}
```

The full loop: the menu navigates the `Navigator`, the page opens a modal through
the shared `Overlayer`, awaits its result, and confirms with the shared
`ToastService`.

{: .note }
> A plain "are you sure?" needs none of this content: `_overlays.Confirm(message,
> title)` shows the [standard confirmation overlay](navigation/overlays.md) and
> returns the same `Task<bool?>`. Write your own content, as above, when the modal
> shows more than a message.

## Where to go next

- [Navigation menu](navigation/navigation-menu.md) — groups,
  nesting, the collapsible rail and the menu `Header`.
- [Overlays](navigation/overlays.md) — overlay options and
  stacking.
- [Toasts](feedback/toasts.md) — toast types and sticky
  toasts.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/recipes.md -->

# Recipes

Complete, copy-paste building blocks for the screens most apps need. They assume the
packages are installed and `App.xaml` merges the Joufflu resources with
`ThemeManager.Instance.Initialize()` called at startup (see
[Getting started](index.md#getting-started)). For a whole app shell, follow the
[Tutorial](tutorial.md).

Every snippet uses these namespaces:

```xml
xmlns:feedback="clr-namespace:Joufflu.Feedback.Controls;assembly=Joufflu.Feedback"
xmlns:inputs="clr-namespace:Joufflu.Inputs.Controls;assembly=Joufflu.Inputs"
xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"
xmlns:nav="clr-namespace:Joufflu.Navigation.Controls;assembly=Joufflu.Navigation"
xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu"
```

## A settings page

A `Card` per group of settings, headings sized with `Sizing.Size`, `Spacing.Gap`
instead of per-element margins, and a toast to confirm the save.

```xml
<StackPanel Margin="{DynamicResource {x:Static joufflu:Dimensions.Spacing}}" toolkit:Spacing.Gap="16">
    <TextBlock toolkit:Sizing.Size="xl" FontWeight="Bold" Text="Settings" />

    <Border Style="{StaticResource Card}">
        <StackPanel toolkit:Spacing.Gap="12">
            <TextBlock toolkit:Sizing.Size="lg" FontWeight="SemiBold" Text="General" />
            <TextBlock Opacity="{DynamicResource {x:Static joufflu:Colors.MutedOpacity}}" Text="Applies to every project." />

            <TextBox Text="{Binding UserName, UpdateSourceTrigger=PropertyChanged}" />
            <inputs:NumericUpDown Value="{Binding MaxItems, Mode=TwoWay}" />
            <ComboBox ItemsSource="{Binding Languages}" SelectedItem="{Binding Language}" />
            <CheckBox Content="Check for updates at startup" IsChecked="{Binding CheckUpdates}" />
        </StackPanel>
    </Border>

    <StackPanel HorizontalAlignment="Right" Orientation="Horizontal" toolkit:Spacing.Gap="8">
        <Button Command="{Binding ResetCommand}" Content="Reset" Style="{StaticResource SecondaryButton}" />
        <Button Command="{Binding SaveCommand}" Content="Save" Style="{StaticResource PrimaryButton}" />
    </StackPanel>
</StackPanel>
```

```csharp
// SaveCommand, with the shared ToastService injected
private void Save()
{
    _settings.Save();
    _toasts.Success("Settings saved.", "Done");
}
```

## Brand it: a custom theme

Customizing is overriding tokens, not restyling controls. Create a dictionary with
the keys you want to change, merge it **after** the Joufflu resources, and every
control, restyled native and Joufflu control picks the change up. Use the gallery's
**Customize theme** window (the palette button in its title bar) to pick colours and dimensions live and copy the generated
dictionary rather than writing it by hand.

```xml
<!-- App.xaml -->
<ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="pack://application:,,,/Joufflu;component/Resources.xaml" />
    <ResourceDictionary Source="MyTheme.xaml" />   <!-- your overrides, after Joufflu -->
</ResourceDictionary.MergedDictionaries>
```

To make a palette selectable by name next to System / Light / Dark, register it
before `Initialize()`:

```csharp
ThemeManager.Instance.Register(
    "Ocean",
    new Uri("pack://application:,,,/MyApp;component/Themes/Ocean.xaml"),
    isDark: true);

ThemeManager.Instance.Initialize();
```

The keys to override are listed in [Design tokens](themes/tokens.md) and the full
flow in [Customize theme](themes/customize-theme.md) and [Theme](themes/theme.md).

## A theme switcher

`ThemeManager.Theme` takes `System`, `Light`, `Dark` or the name of a registered
custom theme and re-themes the whole UI live. Persisting the choice is up to the app;
see [Theme](themes/theme.md#persisting-the-theme).

```csharp
using Joufflu.Themes;

ThemeManager.Instance.Theme = ThemeManager.Dark;
```

## A searchable, paged table

`Search` debounces typing before it raises `SearchChanged`, `Paging` tells the view
model which slice to show. The view model filters, counts and slices.

```xml
<Grid Margin="{DynamicResource {x:Static joufflu:Dimensions.Spacing}}" toolkit:Spacing.Gap="0,12">
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition Height="*" />
        <RowDefinition Height="Auto" />
    </Grid.RowDefinitions>

    <inputs:Search x:Name="Search" />

    <DataGrid Grid.Row="1" AutoGenerateColumns="False" ItemsSource="{Binding PageItems}">
        <DataGrid.Columns>
            <DataGridTextColumn Binding="{Binding Id}" Header="Id" />
            <DataGridTextColumn Binding="{Binding Name}" Header="Name" />
            <DataGridTemplateColumn Header="Status">
                <DataGridTemplateColumn.CellTemplate>
                    <DataTemplate>
                        <feedback:Badge Variant="Success">Active</feedback:Badge>
                    </DataTemplate>
                </DataGridTemplateColumn.CellTemplate>
            </DataGridTemplateColumn>
        </DataGrid.Columns>
    </DataGrid>

    <nav:Paging
        Grid.Row="2"
        Total="{Binding Total}"
        PageNumber="{Binding PageNumber, Mode=TwoWay}"
        Capacity="{Binding Capacity, Mode=TwoWay}" />
</Grid>
```

```csharp
// code-behind: route the debounced text to the view model
Search.SearchChanged += text => ((ItemsViewModel)DataContext).Filter = text;
```

See [Paging](navigation/paging.md#paged-data-grid) for the view-model side.

## Confirm before deleting

One awaited call shows a modal over the whole window, with the confirm button
coloured for a destructive action. The `Overlayer` is the one the window's
`OverlayContainer` is bound to.

```csharp
bool? confirmed = await _overlays.Confirm(
    "Delete the selected item? This action cannot be undone.",
    "Please confirm",
    EnumConfirmationType.Danger);

if (confirmed == true)
{
    Delete();
    _toasts.Success("Item deleted.");
}
```

## A status row with badges and a spinner

```xml
<StackPanel Orientation="Horizontal" toolkit:Spacing.Gap="8">
    <feedback:Spinner />
    <TextBlock VerticalAlignment="Center" Text="Syncing..." />
    <feedback:Badge Variant="Info">12 pending</feedback:Badge>
    <feedback:Badge Variant="Danger">3 errors</feedback:Badge>
</StackPanel>
```

## A form with a different density

`Sizing.Size` (`xs`, `sm`, `md`, `lg`...) is inherited, so setting it once on a panel
resizes every control inside it.

```xml
<StackPanel toolkit:Sizing.Size="sm" toolkit:Spacing.Gap="8">
    <TextBox />
    <ComboBox />
    <Button Content="Apply" Style="{StaticResource PrimaryButton}" />
</StackPanel>
```

## Rules these recipes follow

- Look changes are token overrides in a dictionary merged after Joufflu (or a registered
  theme), never edits to control styles.
- Colours come from the theme (`{DynamicResource {x:Static joufflu:Brushes.ForegroundBrush}}`),
  never from hex values, so Light / Dark and custom themes keep working.
- Gaps between children use `Spacing.Gap`, not a `Margin` on each child.
- Roles are named styles (`PrimaryButton`, `DangerButton`, `Card`) and tokens (`Sizing.Size`
  for text sizes, `Colors.MutedOpacity` for muted text), not literal values.
- Modals and toasts go through the shared `Overlayer` and `ToastService`, never
  `MessageBox`.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/themes/index.md -->

# Themes

The theme layer of the core `Joufflu` package: the window wrapping the app, the
palettes switched at runtime, the tokens a theme is made of and the live editor
generating your own. `ThemeManager` lives in the `Joufflu.Themes` namespace,
`ThemedWindow` in `Joufflu.Controls` and the token keys on `Joufflu.Colors`,
`Joufflu.Brushes` and `Joufflu.Dimensions`.

- **Application shell** — the window styles, and the overlay/toast containers wrapping the app.
- **Theme** — `ThemeManager` for System/Light/Dark plus registering custom themes, and how to bind a theme switcher UI to it.
- **Design tokens** — the reference of every `Colors`, `Brushes` and `Dimensions` key a theme is made of, and the role each one plays in the control styles.
- **Customize theme** — the live theme editor and preset themes.

Snippets use the `joufflu` XML namespace for the design-system keys, plus `nav`
and `feedback` for the application shell containers:

```xml
xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"
xmlns:nav="clr-namespace:Joufflu.Navigation.Controls;assembly=Joufflu.Navigation"
xmlns:feedback="clr-namespace:Joufflu.Feedback.Controls;assembly=Joufflu.Feedback"
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/themes/application-shell.md -->

# Application shell

Styles that shape the whole window rather than a control on a page. The
`Joufflu.Samples` gallery window is the live example.

## Window

The default `Window` style themes a standard WPF window (background, foreground,
native chrome) to match the design system. Applied implicitly to every `Window`.

```xml
<Window ...>
    <!-- inherits the themed Window style automatically -->
</Window>
```

## ThemedWindow

`ThemedWindow` is a custom window with a fully styled title bar and caption
buttons.

```xml
<controls:ThemedWindow xmlns:controls="clr-namespace:Joufflu.Controls;assembly=Joufflu"
                       Title="My app">
    ...
</controls:ThemedWindow>
```

The bar takes its colours from the theme: `TitleBarBackground` (`DisplayBorder0Brush`,
transparent with `AllowContentOverTitleBar`), `TitleBarForeground` (`ForegroundBrush`)
and `WindowButtonHighlightBrush`, the hover of the minimize and maximize buttons
(`ActionInteractionBrush`). Set them on the window to recolour it.

### AppIcon

The title bar shows no icon by default. Add an `AppIcon` to
`ThemedWindow.TitleBarContent` to bring it back: it shows the application's icon (or
the `Source` it is given), a click opens the window's system menu and a double click
closes the window, like a native icon.

```xml
<controls:ThemedWindow ... TitleVisibility="Collapsed">
    <controls:ThemedWindow.TitleBarContent>
        <controls:AppIcon />
    </controls:ThemedWindow.TitleBarContent>
    ...
</controls:ThemedWindow>
```

`TitleBarContent` shares its cell with the title text, so collapse the title or pad it
when both are shown.

### AllowContentOverTitleBar

Set `AllowContentOverTitleBar="True"` to draw content beneath a transparent title
bar instead of below it. A full-height side panel's background then reaches the
top of the window, while the caption buttons keep floating top-right:

```xml
<controls:ThemedWindow ...
    AllowContentOverTitleBar="True"
    TitleVisibility="Collapsed">
    ...
</controls:ThemedWindow>
```

`TitleVisibility="Collapsed"` hides the title text, clearing the top-left corner for
the side panel's own header.

#### Layering

The window is drawn in three layers, bottom to top:

1. the title bar surface (`TitleBarBackground`) and its drag area;
2. the window content;
3. the title, `TitleBarContent` and the caption buttons.

So content can be drawn over the bar, but never over the title bar content or the
caption buttons: they stay visible and clickable.

#### Grabbing the window through the content

The drag area sits *under* the content. A control with a `null` background lets the
mouse through to it, so the window can still be grabbed and moved from the top strip;
a control with a background (even `Transparent`) swallows the click. Leave the
containers around the page (`DockPanel`, `Grid`, `OverlayContainer`, `ToastContainer`...)
without a `Background`, and only paint what must be clickable:

```xml
<!-- Draggable: no Background, the click reaches the title bar -->
<Grid Height="30" />

<!-- Not draggable: the border takes the click -->
<Border Height="30" Background="Transparent" />
```

#### Keeping content clear of the bar

**Compromise.** The window does not lay out your page: content is free to run under
the title bar, so a page's own controls (a header, a scrollbar, a button) can end up
behind the title bar content or the caption buttons. Reserve a strip of empty space
at the top of the content equal to the bar's height, a fixed value shared through
`Dimensions.TitleBarHeight` and `Dimensions.TitleBarHeightOffset`:

```xml
<controls:ThemedWindow ...
    xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"
    AllowContentOverTitleBar="True">

    <feedback:ToastContainer Toasts="{Binding Toasts}">
        <nav:OverlayContainer Overlays="{Binding Overlays}">
            <DockPanel>
                <nav:NavigationMenu DockPanel.Dock="Left" ... />

                <!-- The page drops below the bar; overlays and toasts stay full-bleed. -->
                <ContentControl
                    Margin="{DynamicResource {x:Static joufflu:Dimensions.TitleBarHeightOffset}}"
                    Content="{Binding Navigator.CurrentPage}" />
            </DockPanel>
        </nav:OverlayContainer>
    </feedback:ToastContainer>
</controls:ThemedWindow>
```

The `Joufflu.Samples` gallery window uses this setup. The offset is built from
`TitleBarHeight` when the resources load, so if you override `TitleBarHeight`, override
`TitleBarHeightOffset` (`0,<height>,0,0`) with it.

{: .note }
> Offset only the panels whose top strip holds interactive content, a hosted page
> and its scrollbar. Offsetting the page alone leaves the containers around it
> full-bleed, so modal backdrops still cover the whole window.

`TitleBarContent` is in layer 3 too: give it no background (or handle the drag
yourself) when the window should stay grabbable through it.

#### NavigationMenu under the bar

A `NavigationMenu` reaching the top of the window leaves its header strip (the
`Header` and the free space beside the collapse button) draggable. The header is not
interactive; the collapse button and the items are.

## OverlayContainer

Wraps the whole application and layers the modal overlay stack above it
(`Joufflu.Navigation`). Because it encapsulates everything — side menu included —
a full screen overlay covers the whole window.

```xml
<nav:OverlayContainer Overlays="{Binding Overlays}">
    <!-- the whole app: menu, page, status bar, ... -->
</nav:OverlayContainer>
```

## ToastContainer

Stacks the toasts in a corner of whatever it wraps — `Position` picks which one
(`Joufflu.Feedback`, usable on its own without the navigation package). Wrap it
*around* the `OverlayContainer` so toasts stay above the overlays too:

```xml
<feedback:ToastContainer Toasts="{Binding Toasts}" Position="BottomRight">
    <nav:OverlayContainer Overlays="{Binding Overlays}">
        <!-- the whole app -->
    </nav:OverlayContainer>
</feedback:ToastContainer>
```

## The current page

The current page needs no dedicated container: a plain `ContentControl` bound to
the navigator renders it, the view resolved by an implicit `DataTemplate`.

```xml
<ContentControl Content="{Binding Navigator.CurrentPage}" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/themes/theme.md -->

# Theme

Joufflu ships two colour palettes — `Themes/Light.xaml` and `Themes/Dark.xaml` — with the
same keys, different values. `ThemeManager` swaps the active one at runtime through a single
merged dictionary; since every control reads its colours through `DynamicResource`, the whole
UI re-themes live.

The keys themselves — what each colour and dimension is used for — are listed in
[Design tokens](tokens.md).

Themes are selected **by name**. Three are always available — `System`, `Light` and `Dark` —
and you can register your own palettes so they become selectable alongside the built-ins.

## App setup

Merge only the control styles in `App.xaml`. Do **not** hardcode a theme dictionary — the
manager inserts the matching Light/Dark dictionary right after them at runtime.

```xml
<!-- App.xaml -->
<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceDictionary Source="pack://application:,,,/Joufflu;component/Resources.xaml" />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>
```

Initialize the manager once at startup, before the first window is shown:

```csharp
// App.xaml.cs — OnStartup
ThemeManager.Instance.Initialize();
```

## ThemeManager

Owns the active theme. Set `Theme` (a name) from anywhere and the UI re-themes live:

```csharp
using Joufflu.Themes;

ThemeManager.Instance.Theme = ThemeManager.Dark;   // "System" / "Light" / "Dark" / any registered name

bool isDark = ThemeManager.Instance.IsDark;         // the theme actually on screen
```

`ThemeManager.System`, `.Light` and `.Dark` are string constants for the built-in names. In the
`System` theme the manager reads the Windows apps theme and keeps following it, so the UI tracks
the OS light/dark switch automatically.

The manager does **not** persist the selection — that is left to the app, since each app stores its
settings differently (see [Persisting the theme](#persisting-the-theme)).

## Registering a custom theme

A custom theme is just a resource dictionary with the same keys as `Light.xaml` / `Dark.xaml`
(see [Customize theme](customize-theme.md) to generate one). It can also override any
[dimension](tokens.md#dimensions) — a denser or rounder theme — since the manager merges it right
after `Resources.xaml`. Register it by name — from a pack
`Uri` or an in-memory `ResourceDictionary` — and it becomes selectable through `Theme`, appearing
in the `Themes` list next to the built-ins:

```csharp
// Register BEFORE Initialize() so a restored custom selection can be applied on launch.
ThemeManager.Instance.Register(
    "Ocean",
    new Uri("pack://application:,,,/MyApp;component/Themes/Ocean.xaml"),
    isDark: true);   // isDark surfaces through IsDark while the theme is selected

ThemeManager.Instance.Initialize();

// Later, select it like any other theme:
ThemeManager.Instance.Theme = "Ocean";
```

Reusing an existing name replaces that theme; `Unregister(name)` removes a custom one (the built-ins
cannot be removed). Registering the currently-selected theme re-applies it live — handy when the
restored selection is a custom theme registered after `Initialize()`.

## Persisting the theme

`ThemeManager` does not save the selected theme — each app owns its settings and usually wants to
fold the theme into the same store as its other preferences. Making the choice survive a restart is
two small steps:

1. **Restore** the saved name before `Initialize()`, so the right theme is shown from the first frame.
2. **Save** on every change: `ThemeManager` is an `ObservableObject`, so subscribe to `PropertyChanged`
   and write the name whenever `Theme` changes.

```csharp
// App.xaml.cs — OnStartup, after registering custom themes and before Initialize().
string? saved = LoadThemeSetting();                 // your own settings store
if (!string.IsNullOrWhiteSpace(saved))
    ThemeManager.Instance.Theme = saved;

ThemeManager.Instance.PropertyChanged += (_, e) =>
{
    if (e.PropertyName == nameof(ThemeManager.Theme))
        SaveThemeSetting(ThemeManager.Instance.Theme);
};

ThemeManager.Instance.Initialize();
```

`LoadThemeSetting`/`SaveThemeSetting` are whatever your app already uses (a JSON file, the registry,
`Settings.settings`, …). The sample app persists a small JSON file under `%AppData%` — see its
`App.xaml.cs` for the full working example.

## Theme switcher

No dedicated switcher control — bind any UI directly to `ThemeManager.Instance.Theme`. Map each
theme name to a `RadioButton` with the enum-to-boolean converter (it compares by value, so it works
with the theme-name strings too):

```xml
xmlns:themes="clr-namespace:Joufflu.Themes;assembly=Joufflu"
xmlns:conv="clr-namespace:Joufflu.Converters;assembly=Joufflu"

<!-- In the resources of the window or the app -->
<conv:EnumMatchToBooleanConverter x:Key="EnumMatch" />

<RadioButton Content="System"
    IsChecked="{Binding Theme, Source={x:Static themes:ThemeManager.Instance},
        Converter={StaticResource EnumMatch},
        ConverterParameter=System, Mode=TwoWay}" />
<RadioButton Content="Light"
    IsChecked="{Binding Theme, Source={x:Static themes:ThemeManager.Instance},
        Converter={StaticResource EnumMatch},
        ConverterParameter=Light, Mode=TwoWay}" />
<RadioButton Content="Dark"
    IsChecked="{Binding Theme, Source={x:Static themes:ThemeManager.Instance},
        Converter={StaticResource EnumMatch},
        ConverterParameter=Dark, Mode=TwoWay}" />
<!-- Registered custom themes slot in the same way -->
<RadioButton Content="Ocean"
    IsChecked="{Binding Theme, Source={x:Static themes:ThemeManager.Instance},
        Converter={StaticResource EnumMatch},
        ConverterParameter=Ocean, Mode=TwoWay}" />
```

See the **Theme** page in the sample gallery for the full working example.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/themes/tokens.md -->

# Design tokens

A theme is a collection of the keys below. Every control style reads them
through `DynamicResource`, so a theme only has to redefine what it wants to change — anything it
leaves out keeps the built-in value.

A theme registered with `ThemeManager` can define both colours and dimensions: it is merged right after
`Resources.xaml`, so its `Dimensions` keys (and `Colors.DisabledOpacity` / `MutedOpacity`) override the built-in
ones, and change with the theme. A dictionary merged after `Resources.xaml` still overrides
every theme.

Keys are `ComponentResourceKey` statics rather than strings, so a renamed key breaks the build
instead of silently falling back at runtime:

```xml
xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"

<!-- Always DynamicResource: a theme swap, or the customizer editing a
     dimension, has to reach controls already on screen. -->
<Border
    Background="{DynamicResource {x:Static joufflu:Brushes.DisplayBase0Brush}}"
    BorderBrush="{DynamicResource {x:Static joufflu:Brushes.DisplayBorder0Brush}}"
    BorderThickness="{DynamicResource {x:Static joufflu:Dimensions.DisplayThickness}}"
    CornerRadius="{DynamicResource {x:Static joufflu:Dimensions.DisplayRadius}}" />

<!-- The raw Color is there for what a brush cannot express -->
<GradientStop Offset="0" Color="{DynamicResource {x:Static joufflu:Colors.PrimaryColor}}" />
```

See [Theme](theme.md) for swapping palettes at runtime, [Customize theme](customize-theme.md)
for editing these values live, and [Derived dimensions](../toolkit/derived-dimensions.md) for scaling one
per side or per corner.

## Colors

Each colour exists twice: `Joufflu.Colors.XColor` holds the `Color`, `Joufflu.Brushes.XBrush` the
`SolidColorBrush` built from it. Use the brush in the UI; the colour is there for gradients,
animations and anything that needs the raw value.

### Bases

Three colours a theme defines for the neutrals. The controls do not read them directly but through the
three categories below, whose base falls back to them unless the theme gives a category a base of its
own. Use them for an app's own layout.

| Key | Used for |
|---|---|
| `Base0` | The page, and by default what an action is filled with, so on a display it reads as set into it. An action is not put directly on the page. |
| `Base1` | A card, and by default the base of a display and of an input. |
| `Base2` | A contrast inside a card, for an app's own layout. |

### Categories

Every control belongs to one of three categories, each with the same four brushes. Only the base is a
colour, and it is optional: a theme that leaves it out gets the global colour in brackets, through a
`ColorFallback`. The three others are derived from it by mixing toward the `Foreground`, so the direction
is right in a light and in a dark theme and no theme defines them.

| Brush | Used for |
|---|---|
| `XBase` | The background. |
| `XBorder0` | The base mixed 10% toward `Foreground`: the border, and the parts that sit on the base (a header, a track, a tag). |
| `XBorder1` | The border mixed 10% toward `Foreground`: a border that must stand out from a `XBorder0` background (the border of a `CardSecondary`), and the border of an interacted control. |
| `XInteraction` | The base mixed 10% toward `Foreground`: the background of an interacted control. |

An interaction turns the border to `XBorder1` and the background to `XInteraction`. A part with no
border at rest (a row, a menu item, a ghost button) keeps none. Disabled is `DisabledOpacity`, selected
and checked are the primary.

| Category | Base | Controls | Interaction |
|---|---|---|---|
| **Display** | `DisplayBase0` (`Base1`), `DisplayBase1` (`Base2`) | Card, popup, tooltip, expander, group box, and the frame of a list, tree, grid, menu or tab control. Its items (rows, menu items, tabs, navigation entries) are actions without a fill at rest. `DisplayBase1` is a contrast inside it (the header of a group box or a data grid), its own colour, not derived. | None of its own: `DisplayInteraction` is there for an app's informative hover. |
| **Input** | `InputBase0` (`Base1`), `InputBase1` (`Base2`) | Text box, combo box, check box, radio button, slider. `InputBase1` is a contrast inside it, its own colour, not derived. | On focus: the border; the background too, except where text is typed. No hover. |
| **Action** | `ActionBase0` (`Base0`) | Button, toggle button. A grip (scroll bar thumb, grid splitter, slider thumb) turns `ActionBorder1` when hovered or dragged. | On hover. Pressed is a translation down, not a colour; no focus border. |

A theme overrides a category by defining its base, for example inputs set apart from the cards, with
their `Border0`, `Border1` and `Interaction` brushes following:

```xml
<Color x:Key="{x:Static joufflu:Colors.InputBase0Color}">#FFFFFF</Color>
```

`ColorFallback` is public: a library of your own can declare an optional colour the same way (see
`Joufflu/Styles/Brushes.xaml`).

### Text

| Key | Used for |
|---|---|
| `Foreground` | Default text and icon colour, on any base. |

### Accents

Six semantic families sharing one shape — the five keys of each are shown side by side below:
`X` is the fill, `XForeground` the text and icons drawn on top of it: the two colours a theme defines.
The others are brushes only, derived from the fill so no theme defines them. `XInteractionBrush` is the
fill while hovered (and a checked solid toggle button): the fill mixed 10% toward its own `XForeground`, so a dark fill with light
foreground lightens and a pale one darkens, in a light and in a dark theme alike. `XSoftBrush` is the fill at low opacity (soft buttons,
outline hover) and `XSoftInteractionBrush` its hover, drawn with the fill as text, as a soft
button is. Secondary is the exception: its fill is pale, made to sit under its foreground, so its
soft tint and the text of its soft and outline buttons come from `SecondaryForeground`.

<table>
<tbody>
<tr><td style="white-space:nowrap"><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#18181B;color:#FAFAFA">Aa</div><code style="font-size:11px">Primary</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#2F2F31;color:#FAFAFA">Aa</div><code style="font-size:11px">PrimaryInteraction</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#FAFAFA;color:#FAFAFA">&nbsp;</div><code style="font-size:11px">PrimaryForeground</code></div><div style="display:inline-block;text-align:center;margin-left:8px;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(24,24,27,.14);color:#18181B">Aa</div><code style="font-size:11px">PrimarySoft</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(24,24,27,.24);color:#18181B">Aa</div><code style="font-size:11px">PrimarySoftInteraction</code></div></td><td>Main call to action: the default filled button, the selected tab or navigation entry.</td></tr>
<tr><td style="white-space:nowrap"><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#E4E4E7;color:#27272A">Aa</div><code style="font-size:11px">Secondary</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#D1D1D4;color:#27272A">Aa</div><code style="font-size:11px">SecondaryInteraction</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#27272A;color:#27272A">&nbsp;</div><code style="font-size:11px">SecondaryForeground</code></div><div style="display:inline-block;text-align:center;margin-left:8px;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(39,39,42,.08);color:#27272A">Aa</div><code style="font-size:11px">SecondarySoft</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(39,39,42,.14);color:#27272A">Aa</div><code style="font-size:11px">SecondarySoftInteraction</code></div></td><td>Neutral filled action, for a button that must read as a button without competing with <code>Primary</code>.</td></tr>
<tr><td style="white-space:nowrap"><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#00D390;color:#004C39">Aa</div><code style="font-size:11px">Success</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#00C687;color:#004C39">Aa</div><code style="font-size:11px">SuccessInteraction</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#004C39;color:#004C39">&nbsp;</div><code style="font-size:11px">SuccessForeground</code></div><div style="display:inline-block;text-align:center;margin-left:8px;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(0,211,144,.14);color:#00D390">Aa</div><code style="font-size:11px">SuccessSoft</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(0,211,144,.24);color:#00D390">Aa</div><code style="font-size:11px">SuccessSoftInteraction</code></div></td><td>Confirmation: success toast, valid state, positive badge.</td></tr>
<tr><td style="white-space:nowrap"><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#00BAFE;color:#042E49">Aa</div><code style="font-size:11px">Info</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#00ACEC;color:#042E49">Aa</div><code style="font-size:11px">InfoInteraction</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#042E49;color:#042E49">&nbsp;</div><code style="font-size:11px">InfoForeground</code></div><div style="display:inline-block;text-align:center;margin-left:8px;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(0,186,254,.14);color:#00BAFE">Aa</div><code style="font-size:11px">InfoSoft</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(0,186,254,.24);color:#00BAFE">Aa</div><code style="font-size:11px">InfoSoftInteraction</code></div></td><td>Neutral information: info toast, informative badge.</td></tr>
<tr><td style="white-space:nowrap"><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#FCB700;color:#793205">Aa</div><code style="font-size:11px">Warning</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#EFAA00;color:#793205">Aa</div><code style="font-size:11px">WarningInteraction</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#793205;color:#793205">&nbsp;</div><code style="font-size:11px">WarningForeground</code></div><div style="display:inline-block;text-align:center;margin-left:8px;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(252,183,0,.14);color:#FCB700">Aa</div><code style="font-size:11px">WarningSoft</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(252,183,0,.24);color:#FCB700">Aa</div><code style="font-size:11px">WarningSoftInteraction</code></div></td><td>Something needs attention but nothing is broken yet.</td></tr>
<tr><td style="white-space:nowrap"><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#FF627D;color:#4D0218">Aa</div><code style="font-size:11px">Danger</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#ED5873;color:#4D0218">Aa</div><code style="font-size:11px">DangerInteraction</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:#4D0218;color:#4D0218">&nbsp;</div><code style="font-size:11px">DangerForeground</code></div><div style="display:inline-block;text-align:center;margin-left:8px;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(255,98,125,.14);color:#FF627D">Aa</div><code style="font-size:11px">DangerSoft</code></div><div style="display:inline-block;text-align:center;margin-right:6px"><div style="width:78px;height:34px;line-height:34px;border-radius:4px;border:1px solid rgba(128,128,128,.4);background:rgba(255,98,125,.24);color:#FF627D">Aa</div><code style="font-size:11px">DangerSoftInteraction</code></div></td><td>Destructive action and validation errors — a delete button, the border of a field in error.</td></tr>
</tbody>
</table>

The swatches show the built-in **Light** palette; every theme redefines the same sixteen keys (`Foreground`, the three bases and the twelve accent colours).
The sample gallery renders them live against whichever theme is selected.

### State

| Key | Used for |
|---|---|
| `DisabledOpacity` | Opacity applied to a whole control while `IsEnabled` is `False` (`0.5`). Disabled controls fade rather than switch to a dedicated palette, so a single key covers every control. |
| `MutedOpacity` | Opacity of muted text: placeholders, hints, descriptions, captions (`0.65`). Muted text is dimmed rather than given its own colour, so it follows the foreground it sits in. |

## Dimensions

`Joufflu.Dimensions` holds the metrics. The values in parentheses are the built-in defaults.

### Shape

What a `Border` takes, a `Thickness` or a `CornerRadius`. Bind it through
[`Derive`](../toolkit/derived-dimensions.md) when you need only some sides or corners.

| Key | Type | Used for |
|---|---|---|
| `Thickness` | `Thickness` | The global border (`1`). |
| `Radius` | `CornerRadius` | The global corner radius (`4`). |
| `DisplayRadius`, `InputRadius`, `ActionRadius` | `CornerRadius` | The radius of each category (`4`). The controls clamp each corner to half their height, so a large one gives a pill. |
| `DisplayThickness`, `InputThickness`, `ActionThickness` | `Thickness` | The border of each category (`1`). |
| `DisplayPadding` | `Thickness` | The padding inside a display (`12`). An action is padded by `ActionPaddingXs`…`ActionPaddingLg`, an input by `InputPaddingXs`…`InputPaddingLg`; a button or an input takes only their horizontal part, its height coming from its size, while a row, a menu item or a tab takes both. |
| `DisplayPaddingSm` | `Thickness` | The padding inside a compact display: a popup, a menu, a tooltip, a badge (`4`, a third of `DisplayPadding` in the customizer). |

The global `Radius` and `Thickness` are for an app's own layout: the controls read the category keys.
Override a category key in a dictionary merged after `Resources.xaml` (or in a registered theme) to
reshape that category alone:

```xml
<CornerRadius x:Key="{x:Static joufflu:Dimensions.ActionRadius}">16</CornerRadius>
```

### Layout

Distances between things rather than inside them.

| Key | Type | Used for |
|---|---|---|
| `Spacing` | `Thickness` | Standard gap between sibling elements and page padding (`12`). Feed it to [`Spacing.Gap`](../toolkit/spacing.md). |
| `TitleBarHeight` | `double` | Height of the custom window title bar (`30`). |
| `TitleBarHeightOffset` | `Thickness` | `Top` only, used as a margin to push content below an overlapping title bar. |

### Control heights

Vertical size of single line controls. [`Sizing.Size`](../toolkit/sizing.md) picks one of the four; `md` is
the default written in the base styles, so only `xs`/`sm`/`lg` appear in the size triggers.

| Key | Value | Used for |
|---|---|---|
| `HeightXs` | `24` | Dense tables and toolbars. |
| `HeightSm` | `28` | |
| `HeightMd` | `32` | The default. |
| `HeightLg` | `40` | Prominent, touch friendly controls. |
| `HeightEmbedded` | `20` | `0.625` of `HeightMd`, kept in sync by the theme customizer. The `EmbeddedButton`, a button inside an input (clear, open, step…). |

### Font sizes

A `TextBlock` picks one through [`Sizing.Size`](../natives/typography.md) (`xs` to `xl`; `md` keeps
the inherited body size), like the controls do, so restyling the scale restyles the text.

| Key | Value |
|---|---|
| `FontSizeXs` | `11` |
| `FontSizeSm` | `12` |
| `FontSizeMd` | `13` (the default body size) |
| `FontSizeLg` | `16` |
| `FontSizeXl` | `24` |

### Paddings

Space inside a control, one `Thickness` per size. Two families: buttons and anything content shaped
use `ActionPaddingXs`…`ActionPaddingLg`, text inputs use `InputPadding*`, whose halved horizontal keeps the caret closer to
the border.

| Key | Value | Input key | Value |
|---|---|---|---|
| `ActionPaddingXs` | `6,2` | `InputPaddingXs` | `3,2` |
| `ActionPaddingSm` | `9,3` | `InputPaddingSm` | `4.5,3` |
| `ActionPaddingMd` | `12,4` | `InputPaddingMd` | `6,4` |
| `ActionPaddingLg` | `18,6` | `InputPaddingLg` | `9,6` |

`ActionPaddingMd` and `InputPaddingMd` are the defaults.

See the **Design tokens** page in the sample gallery for the same reference with live swatches.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/themes/customize-theme.md -->

# Customize theme

The gallery's theme customizer tweaks colours and dimensions with the whole
gallery updating live. It opens in a window of its own, from the palette button
next to the light / dark switch in the gallery's title bar, so the gallery behind
it is the preview. Start from a **preset theme**, then copy or save the
generated resource dictionary and merge it into your app **after** the Joufflu
resources to apply it.

The design system is exposed as resource keys you override in a dictionary:
`joufflu:Colors.*` for the colours and `joufflu:Dimensions.*` for the metrics. The
`joufflu:Brushes.*` are built from the colours by the core resources, so overriding a
colour is enough for every brush to follow. [Design tokens](tokens.md) lists them all, with the role each one
plays in the control styles.

The controls read the category tokens (`Display*`, `Input*`, `Action*`), not the global ones. The
customizer has two modes:

- **Simple**: you set the neutrals (Base 0, Base 1, Base 2, Foreground) and the shape
  (corner radius, border thickness, spacing) once, and displays, inputs and actions follow them. The
  generated dictionary leaves the category colours out, so they fall back to the global ones, and
  writes the global radius, thickness and spacing into the category keys (`DisplayRadius`,
  `InputRadius`, `ActionThickness`, `DisplayPadding`…). It also edits three scales,
  each set by its md value with the other sizes following by fixed ratios: **Control height**
  (`HeightXs`..`Lg`), **Font size** (`FontSizeXs`..`Xl`) and **Control padding**
  (`ActionPaddingXs`..`Lg`, the input paddings at half the horizontal). The control padding scale
  is shown in the simple mode only.
- **Complete**: each category gets its own base colour, corner radius, border
  thickness and padding (horizontal and vertical), starting from the simple values. The padding is
  the inside of a display (`DisplayPadding`), and the md padding of an input or an action, the
  other sizes (`InputPaddingXs`..`Lg`, `ActionPaddingXs`..`Lg`) following it with the ratios of the
  control padding, which is only edited in the simple mode. The generated dictionary writes the
  category base colours (`ActionBase0Color`…) and shapes. Going back to the simple mode drops them.

The other brushes of a category (`Border0`, `Border1`, `Interaction`) are derived from its base either way.
A hand-written dictionary overriding only `Dimensions.Radius` or `Dimensions.Thickness` does
not reach the controls: override the category keys.

```xml
<!-- Merge your overrides AFTER the Joufflu resources -->
<ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="pack://application:,,,/Joufflu;component/Resources.xaml" />
    <ResourceDictionary Source="MyTheme.xaml" />
</ResourceDictionary.MergedDictionaries>
```

Run the **`Joufflu.Samples`** app and click the palette button in the title bar to
generate a dictionary interactively.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/natives/index.md -->

# Native controls

WPF's built-in controls, restyled to match the design system. No special types
needed — a plain `<Button>`, `<TextBox>` or `<ComboBox>` picks up the themed look
as soon as the styles are merged (see [Getting started](../index.md#getting-started)).

This section covers the core visuals and the button variants:

- **Typography** — text sizes, muted text and the `TextMuted` / `Title` styles.
- **Font icon** — the bundled Lucide icon font, sized like the text, and the `Chevron` of expandable headers.
- **Card** — the themed container for grouped content.
- **Buttons** — the solid, soft, outline and ghost variants in the semantic colours, and their toggle button twins.

The other natives (text box, combo box, check box, list, tree, data grid, tabs,
menus…) are restyled transparently and need nothing beyond the merged styles; they
are shown in the **Native controls** group of the **`Joufflu.Samples`** gallery
rather than here. A few of them have a named style or a setting worth knowing:

```xml
<!-- Multi-line text: accepts Return, takes the height it is given, scrolls instead of wrapping -->
<TextBox Height="120" Style="{StaticResource MultilineTextBox}" />

<!-- A destructive menu item -->
<MenuItem Header="Delete" Style="{StaticResource DangerMenuItem}" />

<!-- A long list: scroll by item and only build the items in view -->
<ListBox ScrollViewer.CanContentScroll="True" ItemsSource="{Binding Items}" />
```

Binding errors turn an input's border red and add a corner badge listing them, the
`ValidationErrorTemplate`; see [Create a custom control](../toolkit/custom-control.md)
to give an input of your own the same.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/natives/typography.md -->

# Typography

A `TextBlock` takes its size from the same `Sizing.Size` the controls use, and
muted text is dimmed with a token rather than given a colour of its own. A plain
`<TextBlock>` is the default body size. Two named styles cover the common cases:
`TextMuted` (muted opacity, wrapping) and `Title` (semi-bold, `FontSizeLg`).

## Sizes

A `TextBlock` takes its font size from `Sizing.Size`, like the controls: `xs` to
`xl` read the `FontSize` [tokens](../themes/tokens.md#font-sizes), `md` keeps the
inherited body size. `Sizing.Size` is inherited, so a panel set to a size sizes
the text inside it too.

```xml
<TextBlock toolkit:Sizing.Size="xl" Text="xl" />
<TextBlock toolkit:Sizing.Size="lg" Text="lg" />
<TextBlock Text="md, the inherited body size" />
<TextBlock toolkit:Sizing.Size="sm" Text="sm" />
<TextBlock toolkit:Sizing.Size="xs" Text="xs" />
```

## Headings

A heading is a size and a weight: `xl` for a page title, `lg` for a section, the
body size for a minor heading.

```xml
<TextBlock toolkit:Sizing.Size="xl" FontWeight="Bold" Text="Page title" />
<TextBlock toolkit:Sizing.Size="lg" FontWeight="SemiBold" Text="Section" />
<TextBlock FontWeight="SemiBold" Text="Minor heading" />
```

## Muted text

Secondary text (hints, descriptions, captions) is dimmed with the `MutedOpacity`
token rather than given a colour of its own, so it follows whatever foreground it
sits in.

```xml
<TextBlock Text="Default body text" />
<TextBlock Opacity="{DynamicResource {x:Static joufflu:Colors.MutedOpacity}}"
           Text="Muted text" />
```

## Named styles

`TextMuted` applies the `MutedOpacity` token and wraps the text, for descriptions
and hints. `Title` is semi-bold at the `FontSizeLg` size, for a card or section
title.

```xml
<TextBlock Style="{StaticResource Title}" Text="Card title" />
<TextBlock Style="{StaticResource TextMuted}" Text="A longer description that wraps." />
```

{: .note }
> The sizes come from an implicit `TextBlock` style. Inside a control template of
> your own, set `FontSize` from the token directly
> (`{DynamicResource {x:Static joufflu:Dimensions.FontSizeLg}}`).

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/natives/icons.md -->

# Font icon

`FontIcon` renders a glyph from the embedded [Lucide](https://lucide.dev) icon
font. It derives from `TextBlock`, so it takes a foreground brush, aligns like
text and can be dropped anywhere content is expected — inside a button, a label
or a stack panel.

The glyphs are exposed as constants on `LucideFontIcons`; set one on the `Text`
property through `x:Static`.

```xml
<!-- Declare the namespaces once on the root element -->
<UserControl
    xmlns:fonts="clr-namespace:Joufflu.Assets.Fonts;assembly=Joufflu"
    xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"
    xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu">

    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Leaf}" />
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Home}" />
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Bell}" />
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Settings}" />
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Trash}" />
</UserControl>
```

The constants are named after the Lucide icons in PascalCase (the close glyph is
the lowercase `x`). Check `LucideFontIcons` with IntelliSense rather than guessing
a name.

## Sizes

The size follows the inherited `Sizing.Size` attached property (`xs` / `sm` /
`md` / `lg` / `xl`), so an icon scales with the control — or the panel — it sits
in. `md` is the default.

```xml
<fonts:FontIcon toolkit:Sizing.Size="xs" Text="{x:Static fonts:LucideFontIcons.Leaf}" />
<fonts:FontIcon toolkit:Sizing.Size="sm" Text="{x:Static fonts:LucideFontIcons.Leaf}" />
<fonts:FontIcon toolkit:Sizing.Size="md" Text="{x:Static fonts:LucideFontIcons.Leaf}" />
<fonts:FontIcon toolkit:Sizing.Size="lg" Text="{x:Static fonts:LucideFontIcons.Leaf}" />
```

## Colour

Foreground is a normal `TextBlock` property, so point it at any design-system
brush to give an icon a semantic hue.

```xml
<fonts:FontIcon
    Foreground="{DynamicResource {x:Static joufflu:Brushes.PrimaryBrush}}"
    Text="{x:Static fonts:LucideFontIcons.Leaf}" />
<fonts:FontIcon
    Foreground="{DynamicResource {x:Static joufflu:Brushes.SuccessBrush}}"
    Text="{x:Static fonts:LucideFontIcons.Leaf}" />
<fonts:FontIcon
    Foreground="{DynamicResource {x:Static joufflu:Brushes.WarningBrush}}"
    Text="{x:Static fonts:LucideFontIcons.Leaf}" />
<fonts:FontIcon
    Foreground="{DynamicResource {x:Static joufflu:Brushes.DangerBrush}}"
    Text="{x:Static fonts:LucideFontIcons.Leaf}" />
```

## In a button

Pair an icon with `Sizing.IsSquare` for a compact, single-icon button.
See [Buttons](buttons.md#icon-buttons).

```xml
<Button toolkit:Sizing.IsSquare="True" Style="{StaticResource PrimaryButton}">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Plus}" />
</Button>
```

## Chevron

`Chevron` is the `FontIcon` of a header that opens content below it: its glyph
follows `IsExpanded`. `Placement="Leading"` (the default, before the header as in a
tree) points right, then down once open; `Placement="Trailing"` (after the header,
as in an expander) points down, then up. The glyph switches without an animation.
The tree view, expander, navigation group and data display all use it.

`ChevronToggleButton` is the expander of a tree row built on it: a bare, square,
non-focusable toggle in the row's foreground.

```xml
<!-- A tree row's expander -->
<ToggleButton IsChecked="{Binding IsExpanded}" Style="{StaticResource ChevronToggleButton}" />

<!-- After a header -->
<fonts:Chevron IsExpanded="{Binding IsExpanded}" Placement="Trailing" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/natives/card.md -->

# Card

`Card` and `CardSecondary` are named `Border` styles that provide the app's
padded, rounded surfaces. Apply them through the `Style` property of a plain
`<Border>` and put any content inside.

## Card

The primary surface for grouping content, a display: a `DisplayBase0` fill, a
`DisplayBorder0` border, `DisplayRadius` corners and `DisplayPadding` as padding.

```xml
<Border Style="{StaticResource Card}">
    <StackPanel toolkit:Spacing.Gap="4">
        <TextBlock FontWeight="Bold" Text="Card" />
        <TextBlock
            Opacity="{DynamicResource {x:Static joufflu:Colors.MutedOpacity}}"
            Text="The primary surface for grouping content."
            TextWrapping="Wrap" />
    </StackPanel>
</Border>
```

## CardSecondary

A subtly inset panel meant to sit **inside** a `Card`. It uses the `DisplayBorder0`
fill, the part of a display that sits on its base, so it reads as a distinct area of the card, and the
`DisplayBorder1` border to stand out from it.

```xml
<Border Style="{StaticResource Card}">
    <StackPanel toolkit:Spacing.Gap="8">
        <TextBlock FontWeight="Bold" Text="Nested" />
        <Border Style="{StaticResource CardSecondary}">
            <TextBlock Text="CardSecondary inside a Card." TextWrapping="Wrap" />
        </Border>
    </StackPanel>
</Border>
```

{: .note }
> Both styles read the display tokens (see [Design tokens](../themes/tokens.md)), so
> they follow Light / Dark and any custom theme automatically, and a theme restyles every
> card by overriding the `Display*` colours or dimensions.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/natives/buttons.md -->

# Buttons

A plain `<Button>` is themed by default. Named styles, applied through `Style`,
give it a semantic intent and a visual emphasis — solid, soft or outline.

## Variants

The solid named styles map to the semantic brushes: a filled background with its
matching content colour. `GhostButton` has no fill or border; hovering fills it.

```xml
<Button>Default</Button>
<Button Style="{StaticResource PrimaryButton}">Primary</Button>
<Button Style="{StaticResource SecondaryButton}">Secondary</Button>
<Button Style="{StaticResource GhostButton}">Ghost</Button>
<Button Style="{StaticResource SuccessButton}">Success</Button>
<Button Style="{StaticResource DangerButton}">Danger</Button>
<Button Style="{StaticResource InfoButton}">Info</Button>
<Button Style="{StaticResource WarningButton}">Warning</Button>
<Button IsEnabled="False">Disabled</Button>
```

## Soft

A tinted background with the semantic hue as text — lower emphasis than solid,
for secondary actions. The tint is the semantic colour at low opacity (≈14 %,
≈24 % on hover), not a dedicated palette entry, so it derives automatically in
both Light and Dark and follows any custom theme. Secondary's colour is a pale fill,
not a hue, so its soft and outline variants draw with its foreground instead, at a
lighter tint (≈8 %, ≈14 % on hover).

```xml
<Button Style="{StaticResource SoftPrimaryButton}">Primary</Button>
<Button Style="{StaticResource SoftSecondaryButton}">Secondary</Button>
<Button Style="{StaticResource SoftSuccessButton}">Success</Button>
<Button Style="{StaticResource SoftInfoButton}">Info</Button>
<Button Style="{StaticResource SoftWarningButton}">Warning</Button>
<Button Style="{StaticResource SoftDangerButton}">Danger</Button>
```

{: .note }
> Since the soft text is the semantic hue itself, the brighter semantics (Success,
> Warning) sit at lower text-contrast on the pale tint in the Light theme. Reserve
> soft buttons for short labels / secondary actions, or use solid when contrast
> matters.

## Outline

A coloured border and text over a transparent fill; hovering fills it with the
soft tint. Secondary draws its border and text with its foreground.

```xml
<Button Style="{StaticResource OutlinePrimaryButton}">Primary</Button>
<Button Style="{StaticResource OutlineSecondaryButton}">Secondary</Button>
<Button Style="{StaticResource OutlineSuccessButton}">Success</Button>
<Button Style="{StaticResource OutlineInfoButton}">Info</Button>
<Button Style="{StaticResource OutlineWarningButton}">Warning</Button>
<Button Style="{StaticResource OutlineDangerButton}">Danger</Button>
```

## Icon buttons

`IsSquare` makes a button as wide as it is tall, for a single icon. Composes with
any variant.

```xml
<Button toolkit:Sizing.IsSquare="True" Style="{StaticResource PrimaryButton}">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Plus}" />
</Button>
<Button toolkit:Sizing.IsSquare="True">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Settings}" />
</Button>
<Button toolkit:Sizing.IsSquare="True" Style="{StaticResource DangerButton}">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Trash}" />
</Button>
```

## Sizes

The inherited `Sizing.Size` attached property (`xs` / `sm` / `md` /
`lg`) scales height, font size and padding.

```xml
<Button toolkit:Sizing.Size="xs">XS</Button>
<Button toolkit:Sizing.Size="sm">SM</Button>
<Button toolkit:Sizing.Size="md">MD</Button>
<Button toolkit:Sizing.Size="lg">LG</Button>
```

A button inside an input (clear, open, step…) uses `EmbeddedButton`: see
[Create a custom control](../toolkit/custom-control.md).

## Toggle buttons

A plain `<ToggleButton>` is themed like a button and filled with the primary
colour when checked. The ghost, solid, soft and outline styles each have a toggle
twin, the `Button` suffix replaced by `ToggleButton`. Checked, the ghost toggle
turns primary, a solid one takes its hover shade, and soft and outline ones turn
solid.

```xml
<ToggleButton IsChecked="True">Default</ToggleButton>
<ToggleButton Style="{StaticResource PrimaryToggleButton}">Primary</ToggleButton>
<ToggleButton Style="{StaticResource GhostToggleButton}">Ghost</ToggleButton>
<ToggleButton Style="{StaticResource SoftSuccessToggleButton}">Success</ToggleButton>
<ToggleButton Style="{StaticResource OutlineDangerToggleButton}">Danger</ToggleButton>
```

`IconToggleButton` is a ready-made square toggle for a single icon, transparent
until hovered or checked. `IsSquare` composes with any other variant.

```xml
<ToggleButton Style="{StaticResource IconToggleButton}">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Bell}" />
</ToggleButton>
<ToggleButton toolkit:Sizing.IsSquare="True" Style="{StaticResource PrimaryToggleButton}">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Settings}" />
</ToggleButton>
```

The chevron toggle of a tree row, `ChevronToggleButton`, is on the
[Font icon](icons.md#chevron) page.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/index.md -->

# Toolkit

Design-system helpers that shape controls and layouts rather than being controls
themselves. They all live in the `Joufflu.Toolkit` namespace of the core
`Joufflu` package — `Sizing`, `Spacing`, `Derive`, `Tooltip`, `PopupPlacement`, `Animate`, `DropTarget`,
`DropData`, `DragSource`, `SharedWidth` and `DataGridEditing` (which the `DataGrid` style uses to
theme the editors of its built-in columns). The theme manager, tokens and window have their own section, see
[Themes](../themes/index.md).

- **Sizing** — the `Sizing.Size` and `IsSquare` attached properties.
- **Spacing** — the `Spacing.Gap` attached property for gaps between children.
- **Derived dimensions** — the `Derive.BorderThickness`, `Derive.CornerRadius` and `Derive.Margin` attached properties, with their factors scaling the value side by side, for thicknesses, radii and margins that follow the theme live.
- **Tooltip & popup placement** — every `ToolTip` themed and placed on a side of its element; `Tooltip.Placement` picks the side, `Tooltip.Alignment` how it lines up (centred by default) and `Tooltip.MaxWidth` where its text wraps. The `PopupPlacement.Side`, `Alignment` and `Gap` attached properties place any `Popup` the same way, flipped to the opposite side at a screen edge.
- **Animate** — the `Animate.Bounce` attached property for a looping vertical hop on any element, with `BounceHeight` and `BounceDuration` shaping it, and `Animate.Spin` for an endless turn around its centre, with `SpinDuration` setting its speed.
- **Drag and drop** — the `DropTarget.Command`, `IsDragOver` and `Effect` attached properties for turning any element into a drop target, with the `DropData` telling what was dropped and where, and `DragSource.Data`, `AllowedEffects` and `IsDragging` for turning any element into a drag source.
- **Shared width** — the `SharedWidth` decorator and its `IsScope` attached property, which give every input of a group the width of the narrowest one so they line up across the depths of a tree.
- **Create a custom control** — the category a control of your own belongs to (display, input, action), the tokens and states of each, then an input built step by step: background and border, height, sizes and padding, states, the validation error style and embedded buttons.

Snippets use the `toolkit` XML namespace for those helpers, `joufflu` for the
design-system keys and `fonts` for the icons, plus `feedback` where an example
targets one of its controls:

```xml
xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"
xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu"
xmlns:fonts="clr-namespace:Joufflu.Assets.Fonts;assembly=Joufflu"
xmlns:feedback="clr-namespace:Joufflu.Feedback.Controls;assembly=Joufflu.Feedback"
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/sizing.md -->

# Sizing

## Sizing.Size

The inherited `Size` attached property (`xs` / `sm` / `md` / `lg`) scales height,
font size and padding. `xl` exists too, for text and icons: a `TextBlock` takes
the `FontSizeXl` size and a `FontIcon` grows, while controls fall back to `md`.
Since it inherits, setting it on a panel sizes every child.

```xml
<!-- Attached property drives height, font size and padding -->
<Button toolkit:Sizing.Size="xs" />
<Button toolkit:Sizing.Size="sm" />
<Button toolkit:Sizing.Size="md" />  <!-- default -->
<Button toolkit:Sizing.Size="lg" />

<!-- Size is inherited, so a panel sets it for every child -->
<StackPanel toolkit:Sizing.Size="lg">
    <TextBox /> <ComboBox /> <Button>OK</Button>
</StackPanel>
```

Other controls honor the same attached property — `TreeView` scales its expander,
indentation and text together:

```xml
<TreeView toolkit:Sizing.Size="lg" ItemsSource="{Binding Tree}" />
```

## Sizing.IsSquare

`IsSquare` forces equal width and height, for single-icon buttons.

```xml
<Button toolkit:Sizing.IsSquare="True"
        toolkit:Sizing.Size="lg">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Leaf}" />
</Button>
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/spacing.md -->

# Spacing

## Spacing.Gap

`Gap` adds even spacing between a panel's children — no per-child margins. A
`StackPanel` spaces along its orientation; `WrapPanel` and `Grid` space on both
axes.

`Gap` is a `Thickness`: a single value is a uniform gap on both axes, a
`"horizontal,vertical"` pair sets each axis independently (`Left` drives
horizontal, `Top` vertical).

```xml
<!-- Gap adds spacing between children of any panel -->
<!-- StackPanel: gap along the Orientation axis -->
<StackPanel Orientation="Horizontal" toolkit:Spacing.Gap="8">
    <Button>One</Button> <Button>Two</Button> <Button>Three</Button>
</StackPanel>

<!-- Gap is a Thickness: one value is uniform, -->
<!-- "horizontal,vertical" sets each axis (Left/Top) -->
<WrapPanel toolkit:Spacing.Gap="8,12">
    ...
</WrapPanel>

<!-- Grid: gap sits between rows and columns -->
<Grid toolkit:Spacing.Gap="12">
    ...
</Grid>
```

{: .note }
> Spacing is implemented through child margins, so any margin set directly on a
> child is overwritten while spacing is active. A `WrapPanel` doesn't know where its
> lines break, so each child gets the gap after it: the panel keeps one trailing gap
> on its right and bottom edges.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/derived-dimensions.md -->

# Derived dimensions

A `Thickness` or a `CornerRadius` declared in a `ResourceDictionary` is baked at
parse time. Its `Left`/`Top`/`Right`/`Bottom` (or `TopLeft`/`TopRight`/…) are
plain CLR properties, not dependency properties, so they can only be fed with
`StaticResource` and never follow a later change of the scalar they were built
from:

```xml
<!-- Baked at load: editing BorderWidth at runtime does nothing here -->
<system:Double x:Key="BorderWidth">1</system:Double>
<Thickness x:Key="MenuBorderThickness" Right="{StaticResource BorderWidth}" />
```

`Derive.BorderThickness`, `Derive.CornerRadius` and `Derive.Margin` build the
value on the element instead, from a real `DynamicResource`. A scalar edited at
runtime — by the [theme customizer](../themes/customize-theme.html), for instance — flows
straight through, and no derived resource key has to be declared or re-pushed by
hand.

Point it at the key of the category the element belongs to (`DisplayThickness`,
`DisplayRadius`, `InputRadius`, `ActionRadius`…, see [Design tokens](../themes/tokens.html)), so the
part follows the rest of the control when a theme reshapes that category. The global `Thickness` and
`Radius` are for an app's own layout.

## Factors

Each of the three properties has a matching factor, a `Thickness` (or a
`CornerRadius`) whose components multiply the derived value side by side:

| Factor component | Result |
| --- | --- |
| `0` | The side or corner is dropped |
| `1` | It is kept as is |
| anything else | It is scaled — `2` for a doubled margin, `0.5` for a halved radius |

The default is `1,1,1,1`, so the derived value is applied whole.

## Derive.BorderThickness

Point `Derive.BorderThickness` at a resource key and pick the sides with
`Derive.BorderThicknessFactor`, in the usual `Left,Top,Right,Bottom` order.

```xml
<!-- Right edge only, following Dimensions.DisplayThickness live -->
<Border toolkit:Derive.BorderThickness="{x:Static joufflu:Dimensions.DisplayThickness}"
        toolkit:Derive.BorderThicknessFactor="0,0,1,0" />

<!-- Open at the bottom, with a doubled top edge -->
<Border toolkit:Derive.BorderThickness="{x:Static joufflu:Dimensions.DisplayThickness}"
        toolkit:Derive.BorderThicknessFactor="1,2,1,0" />
```

Both properties work in a `Style` setter, so a style can derive its border
without a keyed `Thickness`:

```xml
<Style x:Key="SidePanel" TargetType="Border">
    <Setter Property="toolkit:Derive.BorderThickness" Value="{x:Static joufflu:Dimensions.DisplayThickness}" />
    <Setter Property="toolkit:Derive.BorderThicknessFactor" Value="0,0,1,0" />
</Style>
```

> **In a style, the fed property stops being overridable.** The derived value is
> pushed with `SetCurrentValue`, which outranks a style setter — and even a local
> value; only an animation or a template trigger still takes over. So do not also
> set the property it feeds (here `BorderThickness`) in the same style, move any
> `Style.Triggers` that change it onto the `Derive` property, and expect that a
> consumer can no longer override it. `Derive` fits a value the control owns — a
> `Border` inside a template. When the fed property has to stay overridable — a
> text input's `Padding`, say — give it a plain keyed default
> (`Dimensions.InputPadding*`) instead.

## Derive.CornerRadius

Same shape, with `Derive.CornerRadiusFactor` in the
`TopLeft,TopRight,BottomRight,BottomLeft` order.

```xml
<!-- Top corners only, matching the border it sits in -->
<Border toolkit:Derive.CornerRadius="{x:Static joufflu:Dimensions.DisplayRadius}"
        toolkit:Derive.CornerRadiusFactor="1,1,0,0" />
```

## Derive.Margin

Same shape again, on any `FrameworkElement`, with `Derive.MarginFactor`.

```xml
<!-- Spaced everywhere but the top -->
<Border toolkit:Derive.Margin="{x:Static joufflu:Dimensions.Spacing}"
        toolkit:Derive.MarginFactor="1,0,1,1" />
```

## Notes

- The source resource may be a `Thickness` / `CornerRadius` (every Joufflu shape
  key is one), whose own sides are then scaled, or a `double`, spread over every
  side or corner before scaling.
- Pass the resource **key** (`{x:Static …}`): `Derive` follows the resource
  itself. A `Thickness`, `CornerRadius` or `double` value is taken as is instead,
  so inside a template `toolkit:Derive.Margin="{TemplateBinding Padding}"` scales
  the control's own padding.
- `Derive.BorderThickness` applies to `Border` and to any `Control`;
  `Derive.CornerRadius` applies to `Border`; `Derive.Margin` to any
  `FrameworkElement`. Anything else throws.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/tooltip.md -->

# Tooltip & popup placement

Set `ToolTip` the usual way, as a string or arbitrary XAML: every tooltip is themed. Its
style places it with a custom placement rather than at the mouse, centred on a side of
the element and kept a small gap clear of it, and WPF flips it to the opposite side
when it would run off a screen edge. The show delay is the native one. Any other `Popup`
is placed the same way with [`PopupPlacement`](#popupplacement).

```xml
<!-- A string tooltip -->
<Button Content="Save" ToolTip="Save your changes" />

<!-- Arbitrary content: icons, panels, anything -->
<Button Content="Rich tooltip">
    <Button.ToolTip>
        <StackPanel Orientation="Horizontal" toolkit:Spacing.Gap="8">
            <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Info}" />
            <TextBlock Text="Arbitrary content, icons included." />
        </StackPanel>
    </Button.ToolTip>
</Button>
```

## Tooltip.Placement

`Tooltip.Placement`, set on the element, chooses which side its tooltip sits on —
`Top`, `Bottom` (default), `Left` or `Right`.

```xml
<Button Content="Top"    ToolTip="Placed above" toolkit:Tooltip.Placement="Top" />
<Button Content="Bottom" ToolTip="Placed below" toolkit:Tooltip.Placement="Bottom" />
<Button Content="Left"   ToolTip="Placed left"  toolkit:Tooltip.Placement="Left" />
<Button Content="Right"  ToolTip="Placed right" toolkit:Tooltip.Placement="Right" />
```

## Tooltip.Alignment

`Tooltip.Alignment`, set on the element, lines its tooltip up with it along that side —
`Start`, `Center` (default) or `End`. Above or below, `Start` aligns the left edges and
`End` the right ones; beside, the top and the bottom edges.

```xml
<Button Content="Start"  ToolTip="Aligned on the left edge"  toolkit:Tooltip.Alignment="Start" />
<Button Content="Center" ToolTip="Centred under the button" toolkit:Tooltip.Alignment="Center" />
<Button Content="End"    ToolTip="Aligned on the right edge" toolkit:Tooltip.Alignment="End" />
```

## Tooltip.MaxWidth

`Tooltip.MaxWidth`, set on the element, is the width past which the text of its
tooltip wraps: `320` by default.

```xml
<Button Content="Narrow"
        toolkit:Tooltip.MaxWidth="160"
        ToolTip="A long description, wrapped at a narrower max width." />
```

{: .note }
> The placement is the one of [`PopupPlacement`](#popupplacement), with its default 2 DIP gap.
> The style sets the tooltip's own `Placement`, so `ToolTipService.Placement` on an
> element no longer moves it: use `Tooltip.Placement`. The style does it through
> `Tooltip.IsPlaced="True"`, so a `ToolTip` style of your own keeps the placement
> when it is based on the Joufflu one (`BasedOn="{StaticResource {x:Type ToolTip}}"`) or
> sets that property itself. A `ToolTip` set from a
> trigger composes as usual — the [navigation menu](../navigation/navigation-menu.md)
> gives each item a right-placed tooltip only while the menu is collapsed.

{: .note }
> `Tooltip` was named `ThemedTooltip` before. Its `Placement` takes a `PopupSide`, which
> replaces `TooltipPlacement` with the same values.

## PopupPlacement

`PopupPlacement` places any `Popup` on a side of its `PlacementTarget`, lined up with it,
and flips it to the opposite side when it would run off a screen edge. Tooltips and
[dropdowns](../inputs/dropdown.md) are placed the same way: a dropdown reads these
properties from its button. Set anywhere else than on a `Popup` or a dropdown button,
they do nothing.

```xml
<!-- Under the search box, its right edge on the box's right edge, 2 DIPs below (the default gap) -->
<Popup PlacementTarget="{Binding ElementName=SearchBox}"
       toolkit:PopupPlacement.Side="Bottom"
       toolkit:PopupPlacement.Alignment="End">
    <inputs:DropdownPopupHost>
        <TextBlock Text="Placed popup" />
    </inputs:DropdownPopupHost>
</Popup>
```

| Attached property | Type | Default | Purpose |
|---|---|---|---|
| `PopupPlacement.Side` | `PopupSide?` | `null` (`Bottom`) | Side of the target the popup sits on: `Top`, `Bottom`, `Left`, `Right`. |
| `PopupPlacement.Alignment` | `PopupAlignment?` | `null` (`Start`) | How the popup lines up with the target along that side: `Start`, `Center`, `End`. |
| `PopupPlacement.Gap` | `double` | `2` | Space kept between the target and the popup, on the opposite side too; the same as tooltips. |

Above or below the target, `Start` aligns the left edges and `End` the right ones;
beside it, the top and the bottom edges. `Center` centres the popup on that side.

Setting `Side` or `Alignment` hands the placement over: the popup's `Placement` becomes
`Custom` and a `CustomPopupPlacementCallback` reads the three properties each time it
opens. The one left unset takes its default. A `Gap` alone changes nothing. Clearing
both gives the popup back its native `Placement`.

- The popup's own `HorizontalOffset` and `VerticalOffset` still apply on top.
- Changing a property while the popup is open moves it: WPF only places a popup when it
  opens, so it is closed and reopened.
- The popup is placed on the preferred side first, then on the opposite side with the
  same alignment when the first does not fit on the screen. It slides sideways to stay
  on screen above or below the target, up or down beside it.

{: .note }
> A `Popup` renders in its own tree, so the theme `Foreground` does not reach its
> content. Wrap the content in an `inputs:DropdownPopupHost` (from `Joufflu.Inputs`)
> for the themed frame and foreground, as above.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/animate.md -->

# Animate

Attached properties that animate any element without touching its template.

## Animate.Bounce

`Bounce` loops a vertical hop on any element — a notification badge, a
call-to-action button — without touching its template.

The element rises to the full height, lands, then rebounds twice at roughly 42%
and 18% of it before coming to rest: heights fall off geometrically and each
rebound spends less time in the air than the last, the way something bouncing
loses the same share of its energy on every impact. That settle is what keeps it
from reading as a mechanical up-down pulse.

It animates a `TranslateTransform` added to the element's `RenderTransform`, so
it never affects layout and never moves its neighbours. `BounceHeight` sets how
far the first hop rises (in DIPs, default `6`), the rebounds scaling with it,
and `BounceDuration` the length of a full cycle (default `0:0:1`) — the hop and
its rebounds plus the pause before the next one, so a longer duration reads as a
slow idle nudge rather than a slower hop.

```xml
<!-- Bounce loops a vertical hop on any element, template untouched -->
<Button toolkit:Animate.Bounce="True">Look at me</Button>

<!-- Tune the hop: height in DIPs, duration of a full cycle (hop + pause) -->
<fonts:FontIcon
    toolkit:Animate.Bounce="True"
    toolkit:Animate.BounceHeight="10"
    toolkit:Animate.BounceDuration="0:0:0.6"
    Text="{x:Static fonts:LucideFontIcons.Bell}" />

<!-- Hidden elements pause their own hop: no frames spent on a -->
<!-- bounce nobody can see, resumed when the element is back   -->
<Border Visibility="Collapsed" toolkit:Animate.Bounce="True" />
```

## Binding the bounce

`Bounce` is a plain boolean, so bind it to a view-model flag to start and stop
the loop at runtime.

```xml
<!-- Bounce is a plain bool, so bind it to start and stop the loop -->
<feedback:Badge toolkit:Animate.Bounce="{Binding HasUnread}">3</feedback:Badge>

<!-- A transform already on the element is kept and composed with -->
<!-- the bounce, then restored once Bounce goes back to False     -->
<Border toolkit:Animate.Bounce="{Binding HasUnread}">
    <Border.RenderTransform>
        <RotateTransform Angle="8" />
    </Border.RenderTransform>
</Border>
```

{: .note }
> `BounceHeight` and `BounceDuration` are baked into the animation's key frames,
> so changing either while the element is bouncing restarts the hop from the top
> of its cycle.

## Animate.Spin

`Spin` turns an element endlessly, clockwise and at constant speed — a loading
glyph, a refresh icon while it works. `SpinDuration` sets the time of one full
turn (default `0:0:1`). The `Spinner` of `Joufflu.Feedback` is built on it.

The element turns around its own centre whatever its `RenderTransformOrigin`,
and keeps doing so when it is resized. Like the bounce it runs on the
`RenderTransform`, so it never affects layout; a transform already on the
element is kept, and the element turns as that transform draws it.

```xml
<!-- Spin turns any element around its centre, template untouched -->
<fonts:FontIcon toolkit:Animate.Spin="True" Text="{x:Static fonts:LucideFontIcons.Loader}" />

<!-- SpinDuration is the time of one full turn -->
<fonts:FontIcon
    toolkit:Animate.Spin="True"
    toolkit:Animate.SpinDuration="0:0:3"
    Text="{x:Static fonts:LucideFontIcons.Settings}" />

<!-- A plain bool too: spin a refresh icon only while it works -->
<fonts:FontIcon
    toolkit:Animate.Spin="{Binding IsRefreshing}"
    Text="{x:Static fonts:LucideFontIcons.RefreshCw}" />
```

`Spin` and `Bounce` can be set on the same element: it hops while it turns,
and each stops on its own.

## Hidden elements and lifetime

Every animation pauses itself whenever the element is not visible — `Collapsed`
or `Hidden`, under a collapsed ancestor, or out of the visual tree — parks at
rest, and starts again from the top of its cycle when the element comes back.
An animation left on a hidden element therefore costs no frames.

Nothing has to be unhooked for the element to be collected: the helper keeps no
reference back to it, and an element dropped with `Bounce` or `Spin` still
`True` is collected exactly like one that was stopped first — WPF retires the
clock once its target goes away.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/drop-target.md -->

# Drag and drop

## DropTarget.Command

`DropTarget.Command` makes **any** element a drop target: `AllowDrop` and the four
drag events (`DragEnter`, `DragOver`, `DragLeave`, `Drop`) are handled for you, and
the command is executed with the dropped `IDataObject` as parameter.

The command's `CanExecute` is what decides the accepted data: what it refuses can't
be dropped — the cursor shows a no-drop sign — and never lights the zone up.

```xml
<!-- AllowDrop and the drag events are handled by the behavior -->
<Border toolkit:DropTarget.Command="{Binding DropFilesCommand}"
        BorderThickness="{DynamicResource {x:Static joufflu:Dimensions.DisplayThickness}}">
    <TextBlock VerticalAlignment="Center" Text="Drop .pdf files here" />
</Border>
```

```csharp
// The command's CanExecute is the whole filter: what it refuses can't be dropped
public IRelayCommand DropFilesCommand { get; }
    = new RelayCommand<IDataObject>(DropFiles, CanDropFiles);

private static bool CanDropFiles(IDataObject? data)
{
    string[]? files = data?.GetData(DataFormats.FileDrop) as string[];
    return files?.Length > 0 && files.All(f => Path.GetExtension(f).Equals(".pdf", StringComparison.OrdinalIgnoreCase));
}

// Same IDataObject, once the drop landed
private static void DropFiles(IDataObject? data) { ... }
```

{: .note }
> `CanExecute` is called on every mouse move of the drag, so keep it cheap and side
> effect free — look at the paths, not at the files.

## Where the drop landed

The parameter is a `DropData`: the dragged data — which it is an `IDataObject` of, so a
command only interested in what was dropped keeps taking one and reads it as above — and
where the pointer is on the target, for the drops that land *somewhere* rather than just on
something: a canvas placing what it receives under the cursor, a list inserting it at an
index.

```csharp
// Position is relative to Target, the element holding DropTarget.Command
private void DropNode(IDataObject? data)
{
    if (data is not DropData drop)
        return;

    Point onCanvas = drop.Target.TranslatePoint(drop.Position, Canvas);
    ...
}
```

{: .note }
> `Position` is where the drop landed for the command itself, and where the pointer is for
> `CanExecute`, which is called all along the drag: a target can accept a drag over one of
> its areas and refuse it over another.

## DropTarget.IsDragOver

`IsDragOver` is `true` while **accepted** data hovers the element, which is all a
trigger needs to highlight a valid drop. It inherits, so template and content
children see it too.

```xml
<Border toolkit:DropTarget.Command="{Binding DropFilesCommand}"
        BorderThickness="{DynamicResource {x:Static joufflu:Dimensions.DisplayThickness}}">
    <!-- Background and BorderBrush are styled, not set on the Border, so the trigger can override them -->
    <Border.Style>
        <Style TargetType="Border">
            <Setter Property="Background" Value="Transparent" />
            <Style.Triggers>
                <!-- True only while accepted data hovers: refused files never highlight -->
                <Trigger Property="toolkit:DropTarget.IsDragOver" Value="True">
                    <Setter Property="Background" Value="{DynamicResource {x:Static joufflu:Brushes.PrimaryInteractionBrush}}" />
                    <Setter Property="BorderBrush" Value="{DynamicResource {x:Static joufflu:Brushes.PrimaryBrush}}" />
                </Trigger>
            </Style.Triggers>
        </Style>
    </Border.Style>
    <TextBlock VerticalAlignment="Center" Text="Drop .pdf files here" />
</Border>
```

## DropTarget.Effect

`Effect` is the drop effect reported to the drag source for an accepted drop, which
drives the mouse cursor — `Copy` by default. Data the source doesn't allow this
effect for is rejected, so a `Move` target only accepts drags that can be moved.

```xml
<Border toolkit:DropTarget.Command="{Binding MoveCommand}"
        toolkit:DropTarget.Effect="Move" />
```

## DragSource.Data

`DragSource.Data` is the counterpart of `DropTarget.Command`: it makes **any** element
a drag source, carrying that data to the drop targets. The mouse events are handled
for you, and the drag only starts once the pointer moved past the system drag
threshold, so clicks keep working — a draggable button is still clickable.

The data is given to the targets as is when it already is an `IDataObject`, and
wrapped in a `DataObject` otherwise: a `string` arrives as text, a view model under
its own type — and under every base class and interface of it, so a target can ask for
what the data **is** instead of having to know the exact kind it is given.

```xml
<!-- The mouse events are handled by the behavior: the drag starts past the system threshold -->
<Border toolkit:DragSource.Data="{Binding}"
        toolkit:DragSource.AllowedEffects="Move">
    <TextBlock Text="{Binding}" />
</Border>
```

```csharp
// The target reads what the source carried, wrapped in a DataObject
private static string? GetTag(IDataObject? data) => data?.GetData(DataFormats.UnicodeText) as string;

// Whatever kind of node was dragged, the target only asks for the base it can handle
private static BaseNode? GetNode(IDataObject? data) => data?.GetData(typeof(BaseNode)) as BaseNode;
```

## DragSource.AllowedEffects

`AllowedEffects` is what the source lets the targets answer with — `Copy` by default.
A target asking for anything else is refused, so `AllowedEffects` and
`DropTarget.Effect` must agree for the drop to happen.

```xml
<!-- Both agree on Move: the item leaves the source -->
<Border toolkit:DragSource.Data="{Binding}" toolkit:DragSource.AllowedEffects="Move" />
<Border toolkit:DropTarget.Command="{Binding TakeCommand}" toolkit:DropTarget.Effect="Move" />
```

## DragSource.IsDragging

`IsDragging` is `true` for the whole duration of the drag, which is all a trigger
needs to fade the original out while it travels. It inherits, so template and content
children see it too.

```xml
<Border toolkit:DragSource.Data="{Binding}">
    <Border.Style>
        <Style TargetType="Border">
            <Style.Triggers>
                <!-- True for the whole drag: the original fades out while it travels -->
                <Trigger Property="toolkit:DragSource.IsDragging" Value="True">
                    <Setter Property="Opacity" Value="0.4" />
                </Trigger>
            </Style.Triggers>
        </Style>
    </Border.Style>
    <TextBlock Text="{Binding}" />
</Border>
```

{: .note }
> The drag is a blocking call: nothing else happens on the element until the drop
> lands or the drag is cancelled.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/shared-width.md -->

# Shared width

## SharedWidth

`SharedWidth` lines up inputs that each get a different amount of room, such as the rows of
a tree at different depths. Wrap each input in a `SharedWidth`: it stretches over its cell
and gives the input the width of the narrowest member of its group, against its right edge.
Their right edges already line up, so their left edges do too.

Each group is the closest ancestor marked `SharedWidth.IsScope`:

```xml
<TreeView toolkit:SharedWidth.IsScope="True" ItemsSource="{Binding Fields}">
    <TreeView.ItemTemplate>
        <HierarchicalDataTemplate ItemsSource="{Binding Children}">
            <Grid toolkit:Spacing.Gap="4">
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto" />
                    <ColumnDefinition Width="*" />
                </Grid.ColumnDefinitions>
                <TextBlock VerticalAlignment="Center" Text="{Binding Name}" />
                <toolkit:SharedWidth Grid.Column="1">
                    <TextBox Text="{Binding Value}" />
                </toolkit:SharedWidth>
            </Grid>
        </HierarchicalDataTemplate>
    </TreeView.ItemTemplate>
</TreeView>
```

`DataFill` and `DataEdit` use it for their editors.

- Only visible members count: the rows of a collapsed node are ignored until it expands.
- A member's room is the width its parent arranges it at, so give it a stretching cell
  (`*` column, stretched panel). The shared width follows when a member is added or removed
  or the scope is resized.
- The shared width only changes how the input is laid out, never the size the member asks
  for. A scope sized to its content (a centered dialog, an `Auto` column, a horizontal
  scroll) stays stable instead of bouncing between two widths.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/toolkit/custom-control.md -->

# Create a custom control

A control of your own sits with the Joufflu ones when it reads the tokens of its
category, so a theme restyling that category restyles it too. Pick the category the
control belongs to, then follow its rules. A control derived from a native one
(`TextBox`, `Button`, `ListBox`…) gets them all by basing its style on the native one.

| Category | What it is | Tokens | States |
|---|---|---|---|
| **Display** | Shows content without being interacted with: a card, a popup, a tooltip, a panel, the frame of a list | `DisplayBase0/Border0/Border1/InteractionBrush`, `DisplayRadius`, `DisplayThickness`, `DisplayPadding` (`DisplayPaddingSm` when compact) | None of its own (`DisplayInteractionBrush` is there for an informative hover). Its items (rows, entries) are actions without a fill at rest |
| **Input** | Takes a value: a text field, a picker, a rating, a check | `InputBase0/Border0/Border1/InteractionBrush`, `InputRadius`, `InputThickness`, `InputPaddingXs`…`Lg`, `HeightXs`…`Lg` | No hover; on focus the border turns `InputBorder1Brush` (and the background `InputInteractionBrush` when no text is typed in it) |
| **Action** | Runs something: a button, a toggle, an item of a display | `ActionBase0/Border0/Border1/InteractionBrush`, `ActionRadius`, `ActionThickness`, `ActionPaddingXs`…`Lg`, `HeightXs`…`Lg` | On hover the border turns `ActionBorder1Brush` and the background `ActionInteractionBrush`; moved down when pressed, no focus border |

In every category, disabled is `DisabledOpacity`, selected and checked are the primary,
and sizes follow `Sizing.Size`. [Design tokens](../themes/tokens.html) lists each key with
its role and fallback.

## Example: an input

The gallery's **Create a custom control** page builds a star `RatingInput` from a bare
`Control` step by step, following every rule of the **Input** category by hand; a display
or an action follows the same steps with the keys of its own category. The rules:

| | Rule | Tokens |
|---|---|---|
| **Required** | Background | `Brushes.InputBase0Brush` (`InputBorder0Brush` for a part that sits on it: a tag, a track) |
| **Required** | Border colour, thickness and radius | `Brushes.InputBorder0Brush`, `Dimensions.InputThickness`, `Dimensions.InputRadius` (clamped to half the height with `MaxCornerRadiusConverter`) |
| **Required** | Height, for a one-line input | `Dimensions.HeightMd` |
| Optional | Sizes and padding | `HeightXs`…`HeightLg`, `FontSizeXs`…`FontSizeLg`, `InputPaddingXs`…`InputPaddingLg` |
| Optional | Focus and disabled states (an input has no hover) | `InputBorder1Brush` (focus), `Colors.DisabledOpacity` |
| Optional | Validation error style | `DangerBrush`, `ValidationErrorTemplate` |
| Optional | Buttons inside the input | `EmbeddedButton` |

Always reference the tokens with `DynamicResource`: a `StaticResource` is read once and
misses every later theme switch.

## Derive from a native control first

When the input is a native control underneath (a `TextBox` with extras, a `ComboBox`
variant…), derive from it and base the style on the native one. It inherits every rule
on this page at once, and only the template needs writing:

```xml
<Style TargetType="{x:Type local:PrefixedTextBox}" BasedOn="{StaticResource {x:Type TextBox}}">
    <Setter Property="Template"> ... </Setter>
</Style>
```

The template must keep reading `Background`, `BorderBrush`, `BorderThickness` and
`Padding` through `TemplateBinding`, or the inherited triggers have nothing to act on.
The rest of this page is for an input built from a bare `Control`.

## The minimum

Set the background, the border and the height from the tokens in the style, and let the
template read them from the control:

```xml
<Style TargetType="{x:Type local:RatingInput}">
    <Setter Property="Background" Value="{DynamicResource {x:Static joufflu:Brushes.InputBase0Brush}}" />
    <Setter Property="BorderBrush" Value="{DynamicResource {x:Static joufflu:Brushes.InputBorder0Brush}}" />
    <Setter Property="BorderThickness" Value="{DynamicResource {x:Static joufflu:Dimensions.InputThickness}}" />
    <Setter Property="Height" Value="{DynamicResource {x:Static joufflu:Dimensions.HeightMd}}" />
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="{x:Type local:RatingInput}">
                <Grid>
                    <!-- The radius is clamped to half the height, like the native inputs: a large one gives a pill -->
                    <Border Background="{TemplateBinding Background}"
                            BorderBrush="{TemplateBinding BorderBrush}"
                            BorderThickness="{TemplateBinding BorderThickness}"
                            Tag="{DynamicResource {x:Static joufflu:Dimensions.InputRadius}}">
                        <Border.CornerRadius>
                            <MultiBinding Converter="{StaticResource MaxCornerRadiusConverter}">
                                <Binding Path="Tag" RelativeSource="{RelativeSource Self}" />
                                <Binding Path="ActualWidth" RelativeSource="{RelativeSource Self}" />
                                <Binding Path="ActualHeight" RelativeSource="{RelativeSource Self}" />
                            </MultiBinding>
                        </Border.CornerRadius>
                    </Border>
                    <!-- content -->
                </Grid>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>
```

Setting them in the style rather than in the template keeps them overridable, and lets
the triggers below change them. A multi-line input (a list, a text area) leaves the
height alone.

`MaxCornerRadiusConverter`, and `HorizontalThicknessConverter` below, are in
`Joufflu.Converters`: declare them in the dictionary holding the style (see
[Embedded buttons](#embedded-buttons) for why).

```xml
<!-- xmlns:converters="clr-namespace:Joufflu.Converters;assembly=Joufflu" -->
<converters:MaxCornerRadiusConverter x:Key="MaxCornerRadiusConverter" />
<converters:HorizontalThicknessConverter x:Key="HorizontalThicknessConverter" />
```

## Sizes and padding

`Sizing.Size` is inherited: a panel set to `lg` expects every input in it to grow. Set the
`md` values by default, and one trigger per other size:

| Size | Height | Font size | Input padding |
|---|---|---|---|
| `xs` | `HeightXs` (24) | `FontSizeXs` (11) | `InputPaddingXs` (3,2) |
| `sm` | `HeightSm` (28) | `FontSizeSm` (12) | `InputPaddingSm` (4.5,3) |
| `md` | `HeightMd` (32) | `FontSizeMd` (13) | `InputPaddingMd` (6,4) |
| `lg` | `HeightLg` (40) | `FontSizeLg` (16) | `InputPaddingLg` (9,6) |

```xml
<Setter Property="FontSize" Value="{DynamicResource {x:Static joufflu:Dimensions.FontSizeMd}}" />
<Setter Property="Padding" Value="{DynamicResource {x:Static joufflu:Dimensions.InputPaddingMd}}" />

<Style.Triggers>
    <Trigger Property="toolkit:Sizing.Size" Value="xs">
        <Setter Property="Height" Value="{DynamicResource {x:Static joufflu:Dimensions.HeightXs}}" />
        <Setter Property="FontSize" Value="{DynamicResource {x:Static joufflu:Dimensions.FontSizeXs}}" />
        <Setter Property="Padding" Value="{DynamicResource {x:Static joufflu:Dimensions.InputPaddingXs}}" />
    </Trigger>
    <!-- same for sm and lg -->
</Style.Triggers>
```

Inputs use the `InputPadding` keys, tighter than the `ActionPadding` keys of the buttons.
The height of a one-line input comes from its size, so, like the native inputs, the
template lays the content over the border inside the **horizontal** part of `Padding`
only, centred vertically: it lines up with the text of the native inputs, and a large
vertical padding never crushes it. `HorizontalThicknessConverter` drops the vertical part:

```xml
<Grid>
    <Border ... />
    <Grid VerticalAlignment="Center"
          Margin="{TemplateBinding Padding, Converter={StaticResource HorizontalThicknessConverter}}">
        <!-- content -->
    </Grid>
</Grid>
```

## States

An input has no hover state: on focus the native inputs turn their border to `InputBorder1Brush`, and
they fade when disabled. One you type text into keeps its background, as a `TextBox` does: a darker
fill would lower the contrast of the text. One you only pick from (a combo box, a check box) also turns
its background to `InputInteractionBrush`.

```xml
<Trigger Property="IsKeyboardFocusWithin" Value="True">
    <Setter Property="BorderBrush" Value="{DynamicResource {x:Static joufflu:Brushes.InputBorder1Brush}}" />
</Trigger>
<Trigger Property="IsEnabled" Value="False">
    <Setter Property="Opacity" Value="{DynamicResource {x:Static joufflu:Colors.DisabledOpacity}}" />
</Trigger>
```

## Validation error style

Binding errors show in two layers, as on every Joufflu input: the input turns its own
border red, and `ValidationErrorTemplate` adds a badge on the corner whose tooltip lists
the errors. The template draws no border of its own, so the trigger is what makes the
border red:

```xml
<Setter Property="Validation.ErrorTemplate" Value="{DynamicResource ValidationErrorTemplate}" />

<!-- In Style.Triggers, after the focus trigger so it wins over it -->
<Trigger Property="Validation.HasError" Value="True">
    <Setter Property="BorderBrush" Value="{DynamicResource {x:Static joufflu:Brushes.DangerBrush}}" />
</Trigger>
```

A user of the input drops the badge with `Validation.ErrorTemplate="{x:Null}"`; the red
border stays.

## Embedded buttons

A button inside the input (clear, open, step…) uses the `EmbeddedButton` style: a
transparent square of `HeightEmbedded` (20). Centred in the content row, which takes
no vertical padding, it fits every size, down to the 24 of `xs`.

```xml
<Grid VerticalAlignment="Center"
      Margin="{TemplateBinding Padding, Converter={StaticResource HorizontalThicknessConverter}}">
    <Grid.ColumnDefinitions>
        <ColumnDefinition />
        <ColumnDefinition Width="Auto" />
    </Grid.ColumnDefinitions>
    <!-- content -->
    <Button Grid.Column="1" Command="{Binding ClearCommand, RelativeSource={RelativeSource TemplatedParent}}"
            Style="{StaticResource EmbeddedButton}">
        <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.x}" />
    </Button>
</Grid>
```

`EmbeddedButton` is a named style of `Button.named.xaml`. A `StaticResource` in a
`ResourceDictionary` only sees that dictionary and the ones it merges, so a dictionary
holding the input's style merges it:

```xml
<ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="pack://application:,,,/Joufflu;component/Styles/Natives/Actions/Button.named.xaml" />
</ResourceDictionary.MergedDictionaries>
```

## Checking the result

Put the input next to a `TextBox` and compare them:

- in each size, with `Sizing.Size` on a parent panel;
- after switching between Light and Dark, and to a custom theme;
- focused and disabled;
- with a binding error, with and without `Validation.ErrorTemplate="{x:Null}"`.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/controls/index.md -->

# Joufflu controls

The controls Joufflu adds on top of the restyled natives, one optional package
each. They all build on the core `Joufflu` package and read the same design
tokens, so they follow the theme like the natives do.

| Section | Package | What's inside |
|---|---|---|
| [Feedback](../feedback/index.md) | `Joufflu.Feedback` | `Badge`, `Spinner`, toasts |
| [Inputs](../inputs/index.md) | `Joufflu.Inputs` | `NumericUpDown`, `DecimalUpDown`, `TimeSpanPicker`, `FormatTextBox`, `Search`, `ComboBoxSearch`, `ComboBoxTags`, `TextEditable`, `FilePicker`, `ColorPicker`, `Dropdown` |
| [Navigation](../navigation/index.md) | `Joufflu.Navigation` | `NavigationMenu`, overlays (modal dialogs), `Paging` |
| [Data](../data/index.md) | `Joufflu.Data` | `DataFill`, `DataEdit`, `DataDisplay` |
| [File explorer](../file-explorer/index.md) | `Joufflu.FileExplorer` | `ExplorerList`, `ExplorerTree`, `Explorer` and their sources |

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/feedback/index.md -->

# Feedback

Feedback controls from the optional
[`Joufflu.Feedback`](https://www.nuget.org/packages/Joufflu.Feedback) package,
built on the design system.

- **Badge** — a themed pill in the semantic colours.
- **Spinner** — an indeterminate loading indicator.
- **Toasts** — transient notifications shown from a service, stacked in any corner by a `ToastContainer`.

Add the package (`dotnet add package Joufflu.Feedback`). Only the core
`Resources.xaml` needs merging: the controls' styles load from the package's
`Themes/Generic.xaml`. The controls live in the
`Joufflu.Feedback.Controls` namespace:

```xml
xmlns:feedback="clr-namespace:Joufflu.Feedback.Controls;assembly=Joufflu.Feedback"
xmlns:joufflu="clr-namespace:Joufflu;assembly=Joufflu"
xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu"
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/feedback/badge.md -->

# Badge

## Variants

A pill themed from the semantic brushes. Pick a variant with the `Variant`
property (`Default` when unset).

```xml
<feedback:Badge>Default</feedback:Badge>
<feedback:Badge Variant="Primary">Primary</feedback:Badge>
<feedback:Badge Variant="Secondary">Secondary</feedback:Badge>
<feedback:Badge Variant="Success">Success</feedback:Badge>
<feedback:Badge Variant="Info">Info</feedback:Badge>
<feedback:Badge Variant="Warning">Warning</feedback:Badge>
<feedback:Badge Variant="Danger">Danger</feedback:Badge>
```

## Sizes

Sized through the inherited `Sizing.Size` attached property.

```xml
<feedback:Badge Variant="Primary" toolkit:Sizing.Size="xs">xs</feedback:Badge>
<feedback:Badge Variant="Primary" toolkit:Sizing.Size="sm">sm</feedback:Badge>
<feedback:Badge Variant="Primary">md</feedback:Badge>
<feedback:Badge Variant="Primary" toolkit:Sizing.Size="lg">lg</feedback:Badge>
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/feedback/spinner.md -->

# Spinner

## Loading indicator

An indeterminate loading indicator. Colour comes from `Foreground` (the primary
brush by default), diameter from `Sizing.Size`.

```xml
<feedback:Spinner toolkit:Sizing.Size="xs" />
<feedback:Spinner toolkit:Sizing.Size="sm" />
<feedback:Spinner />
<feedback:Spinner toolkit:Sizing.Size="lg" />
<feedback:Spinner toolkit:Sizing.Size="lg"
                  Foreground="{DynamicResource {x:Static joufflu:Brushes.DangerBrush}}" />
```

A collapsed or hidden spinner stops turning, so it can stay in the view and be shown
through `Visibility` while work runs.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/feedback/toasts.md -->

# Toasts

Transient notifications stacked in a corner of the window, above page content and
overlays, auto-dismissed after 5 seconds by default (`ToastOptions.Duration`) unless sticky.

## Hosting the toasts

A `ToastContainer` bound to the same `ToastService` renders them. It wraps the
content it sits above, so wrapping the whole window keeps the toasts on top of
everything:

```xml
<feedback:ToastContainer Toasts="{Binding Toasts}">
    <!-- the whole app -->
</feedback:ToastContainer>
```

The container creates a `ToastService` of its own when none is bound; bind one from
your shell view model to share it with the pages, behind `IToastService`.

When the app also uses an
[`OverlayContainer`](../navigation/overlays.md#hosting-the-overlays), wrap it
*inside* the `ToastContainer` so toasts stay above the modal overlays:

```xml
<feedback:ToastContainer Toasts="{Binding Toasts}">
    <nav:OverlayContainer Overlays="{Binding Overlays}">
        <!-- the whole app -->
    </nav:OverlayContainer>
</feedback:ToastContainer>
```

## Toast types

Show them from an injected `IToastService` (in `Joufflu.Feedback`):

```csharp
toasts.Info("A neutral message.", "Heads up");
toasts.Success("Saved.");
toasts.Warning("Careful.");
toasts.Error("Failed.");
toasts.Show(new ToastOptions { Message = "Sticky", Duration = TimeSpan.Zero });
```

A `Duration` of `TimeSpan.Zero` makes a toast sticky: it stays until the user
closes it.

## Loading toast

A loading toast shows a spinner and stays until updated. Change its type, title,
message or duration from the returned instance once the work progresses or ends:

```csharp
ToastInstance toast = toasts.Loading("Preparing…", "Uploading files");
toast.Message = "File 1 of 3";
// once done
toast.Type = ToastType.Success;
toast.Title = "Upload complete";
toast.Message = "3 files uploaded.";
toast.Duration = TimeSpan.FromSeconds(5); // starts the auto-dismiss
```

Every `ToastInstance` can be updated this way, not only loading ones. Changing
`Duration` restarts the countdown from that moment. `toasts.Close(toast)` removes a
toast early.

## Position

The `ToastContainer`'s `Position` picks the corner the stack sits in: `TopRight` (the default), `TopLeft`,
`BottomRight` or `BottomLeft`. The newest toast always sits closest to that corner,
so the stack grows away from it. Bind it to change corners at runtime — the
gallery's **Toasts** page does exactly that.

```xml
<feedback:ToastContainer Toasts="{Binding Toasts}" Position="BottomRight">
    <!-- the whole app -->
</feedback:ToastContainer>
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/index.md -->

# Inputs

Inputs from the `Joufflu.Inputs` library. Two-way bindable like the built-in WPF
inputs.

- **Numeric & format inputs** — `NumericUpDown`, `DecimalUpDown`,
  `TimeSpanPicker` and the underlying `FormatTextBox`.
- **Search** — a debounced `Search` box.
- **Search combo box** — the searchable `ComboBoxSearch`.
- **Combo box tags** — multi-selection built on `ComboBoxSearch`.
- **Text editable** — a value that becomes editable on demand.
- **File picker** — pick a file through the system dialog.
- **Color picker** — pick a colour with a saturation square, hue and alpha
  sliders.
- **Dropdown** — attached properties opening a popup of any content off a `ToggleButton`.

All snippets assume these XML namespaces:

```xml
xmlns:inputs="clr-namespace:Joufflu.Inputs.Controls;assembly=Joufflu.Inputs"
xmlns:format="clr-namespace:Joufflu.Inputs.Controls.Format;assembly=Joufflu.Inputs"
xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu"
xmlns:fonts="clr-namespace:Joufflu.Assets.Fonts;assembly=Joufflu"
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/numeric-inputs.md -->

# Numeric & format inputs

## NumericUpDown

Selects a whole number (`long?`). Built on `FormatTextBox` with a single
`IntegerGroup`, plus clear and increment/decrement buttons.

```xml
<inputs:NumericUpDown Value="{Binding NumericValue, Mode=TwoWay}" />
```

## DecimalUpDown

Selects a `decimal?` value, through a single `DecimalGroup`.

```xml
<inputs:DecimalUpDown Value="{Binding DecimalValue, Mode=TwoWay}" />
```

## TimeSpanPicker

Selects a `TimeSpan?` through a days/hours/minutes/seconds format.

```xml
<inputs:TimeSpanPicker Value="{Binding Duration, Mode=TwoWay}" />
```

## Bounds and format

To bound or format the number of a `NumericUpDown` or a `DecimalUpDown`, write its
group yourself: a group given as content replaces the default one (which is
nullable and keeps its own caret, so set those back when you want them).

```xml
<inputs:NumericUpDown Value="{Binding Quantity, Mode=TwoWay}">
    <format:IntegerGroup Min="0" Max="99" IsNullable="True" SelectsWhole="False" />
</inputs:NumericUpDown>
```

## FormatTextBox

The base input: groups the user types into, with literal text between them,
each group read into its own value and navigated with <kbd>Tab</kbd> / arrows.

```xml
<format:FormatTextBox>
    <format:IntegerGroup Max="23" StringFormat="00" />
    <format:FormatLiteral Text="h " />
    <format:IntegerGroup Max="59" StringFormat="00" />
    <format:FormatLiteral Text="m" />
</format:FormatTextBox>
```

`IntegerGroup` counts in `long` and `DecimalGroup` in `decimal`. Both take:

| Property | Default | Meaning |
|---|---|---|
| `Min`, `Max` | the type's own | Bounds of what can be typed or spun to. `Max` also sets the group's width: once the number is as long as it, typing moves on to the next group. |
| `Step` | `1` / `0.1` | What <kbd>↑</kbd> / <kbd>↓</kbd> and the mouse wheel add or take away. |
| `StringFormat` | none | A .NET numeric format string: `00` pads to two digits, `N0` separates thousands. |
| `IsNullable` | `false` | Whether the group can hold no number rather than zero. |
| `PromptChar` | `-` | Shown once per character of a group holding no number. |
| `SelectsWhole` | `true` | Selected, typed over and emptied as one thing; when `false` the group keeps its own caret, like a plain text box. |

`Values` holds one value per group, raising `ValuesChanged`.
`ShowDeleteButton="False"` and `ShowIncrementsButtons="False"` hide the clear and
increment/decrement buttons, on every format input.

## Validation

Binding errors (here from an ObservableValidator) turn the input's border red, and
`ValidationErrorTemplate` adds a corner badge whose tooltip lists them. Bring each
value in range to clear it: a rating from 1 to 10, a ratio from 0 to 1, at most
one hour. The last input sets `Validation.ErrorTemplate` to `{x:Null}`: no badge,
only the red border.

```xml
<inputs:NumericUpDown Value="{Binding Rating, Mode=TwoWay}" />
<inputs:DecimalUpDown Value="{Binding Ratio, Mode=TwoWay}" />
<inputs:TimeSpanPicker Value="{Binding ShortDuration, Mode=TwoWay}" />

<!-- Opt out of the template: only the input's own red border remains -->
<inputs:NumericUpDown Validation.ErrorTemplate="{x:Null}" Value="{Binding Rating, Mode=TwoWay}" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/search.md -->

# Search

## Search

A text box that waits for typing to settle (300 ms) before reporting the search,
to limit calls to an API or database. <kbd>Escape</kbd> clears it.

```xml
<!-- MVVM: SearchText is two-way by default and only updates once typing settles -->
<inputs:Search SearchText="{Binding Query}" />
<!-- or a command, executed with the text -->
<inputs:Search SearchCommand="{Binding SearchCommand}" />
```

```csharp
// code-behind: search.SearchChanged += text => Filter(text);
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/combo-box-search.md -->

# Search combo box

## ComboBoxSearch

An editable combo box that filters its items as you type, on the text
`DisplayMemberPath` shows for each item.

The chevron on the right opens the list, as do <kbd>Up</kbd> and <kbd>Down</kbd>.
Opening it that way shows every choice, even once an item is selected: the text
left behind by a selection is not a search, so it does not filter the list down to
the item already picked. <kbd>Escape</kbd> closes the list and clears the selection,
and text matching no item is cleared when the focus leaves.

```xml
<inputs:ComboBoxSearch ItemsSource="{Binding Countries}"
                       SelectedItem="{Binding SelectedCountry}" />
```

## Validation

Binding errors (here from an ObservableValidator) turn the input's border red, and
`ValidationErrorTemplate` adds a corner badge whose tooltip lists them. Pick a
country to clear it. The second input sets `Validation.ErrorTemplate` to
`{x:Null}`: no badge, only the red border.

```xml
<inputs:ComboBoxSearch ItemsSource="{Binding Countries}"
                       SelectedItem="{Binding RequiredCountry}" />

<!-- Opt out of the template: only the input's own red border remains -->
<inputs:ComboBoxSearch Validation.ErrorTemplate="{x:Null}" ... />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/combo-box-tags.md -->

# Combo box tags

## ComboBoxTags

Builds on `ComboBoxSearch` to select several items, shown as removable tags.
Selected items leave the list. Set `AllowAdd="True"` to let users add values not in
the source list.

```xml
<inputs:ComboBoxTags AllowAdd="True"
                     ItemsSource="{Binding Countries}"
                     SelectedItems="{Binding SelectedCountries}" />
```

<kbd>Enter</kbd> adds the typed text when `AllowAdd` is set, and <kbd>Backspace</kbd>
on an empty text removes the last tag. With `AllowAdd` and no `ItemsSource`, it is a free
list of tags: no chevron, nothing drops down.

Bind `SelectedItems` to a mutable `IList` (the gallery uses an
`ObservableCollection<object>`; with `AllowAdd` its element type must accept a
`string`). The control edits that list in place. Changes made to its contents from
the view model are not picked up: assign a new collection instead.

## Validation

Binding errors (here from an ObservableValidator) turn the input's border red, and
`ValidationErrorTemplate` adds a corner badge whose tooltip lists them. Pick a
second country to clear it. The second input sets `Validation.ErrorTemplate` to
`{x:Null}`: no badge, only the red border.

```xml
<inputs:ComboBoxTags ItemsSource="{Binding Countries}"
                     SelectedItems="{Binding RequiredCountries}" />

<!-- Opt out of the template: only the input's own red border remains -->
<inputs:ComboBoxTags Validation.ErrorTemplate="{x:Null}" ... />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/text-editable.md -->

# Text editable

## TextEditable

Displays a value that turns into an editable text box on demand, for use outside
a form. A double click or the pencil button starts the edit; <kbd>Enter</kbd> or the
check commits it, <kbd>Escape</kbd> or the cross cancels it.

```xml
<inputs:TextEditable Text="{Binding EditableText, Mode=TwoWay}" />
```

`Text` only changes on commit. The `TextChanged` event then reports the new `Text`
and the `OldText`.

## Validation

Binding errors (here from an ObservableValidator) turn the input's border red, and
`ValidationErrorTemplate` adds a corner badge whose tooltip lists them. Shorten
the title to 10 characters to clear it. The second input sets
`Validation.ErrorTemplate` to `{x:Null}`: no badge, only the red border.

```xml
<inputs:TextEditable Text="{Binding ShortText, Mode=TwoWay}" />

<!-- Opt out of the template: only the input's own red text and border remain -->
<inputs:TextEditable Validation.ErrorTemplate="{x:Null}" Text="{Binding ShortText, Mode=TwoWay}" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/file-picker.md -->

# File picker

## FilePicker

Selects a file through the system dialog and exposes the chosen path, with a clear
button. The path can also be typed.

```xml
<inputs:FilePicker FilePath="{Binding FilePath, Mode=TwoWay}" />
```

## File types

`Options` takes a `FilePickerOptions`: `Filter` lists the file types the dialog
offers, in `OpenFileDialog.Filter` syntax, and `DefaultExtension` is the extension it
appends to a typed name.

```xml
<inputs:FilePicker FilePath="{Binding ImagePath}" Options="{Binding ImageOptions}" />
```

```csharp
public FilePickerOptions ImageOptions { get; } = new()
{
    Filter = "Images (*.png;*.jpg)|*.png;*.jpg|All files (*.*)|*.*",
    DefaultExtension = ".png"
};
```

## Validation

Binding errors (here from an ObservableValidator) turn the input's border red, and
`ValidationErrorTemplate` adds a corner badge whose tooltip lists them. Choose a
file to clear it. The second input sets `Validation.ErrorTemplate` to `{x:Null}`:
no badge, only the red border.

```xml
<inputs:FilePicker FilePath="{Binding RequiredFilePath}" />

<!-- Opt out of the template: only the input's own red border remains -->
<inputs:FilePicker Validation.ErrorTemplate="{x:Null}" FilePath="{Binding RequiredFilePath}" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/color-picker.md -->

# Color picker

## ColorPicker

Edits a colour through an editable hex value and a popup with a saturation square,
hue and alpha sliders. Two-way bindable through `Color`
(`System.Windows.Media.Color`).

```xml
<inputs:ColorPicker Color="{Binding Color, Mode=TwoWay}" />
```

The popup provides:

- a **saturation / brightness** square you can drag,
- a **hue** slider,
- an **alpha** slider (checkerboard behind a transparent → opaque ramp),
- an editable **hex** field and an **opacity** percentage. A `#RRGGBB` hex (or a
  colour name such as `Teal`) keeps the opacity, a pasted `#AARRGGBB` sets it too.
  Text that spells no colour reverts to the current one.

## Validation

Binding errors (here from an ObservableValidator) turn the input's border red, and
`ValidationErrorTemplate` adds a corner badge whose tooltip lists them. Pick an
opaque colour to clear it. The second input sets `Validation.ErrorTemplate` to
`{x:Null}`: no badge, only the red border.

```xml
<inputs:ColorPicker Color="{Binding OpaqueColor}" />

<!-- Opt out of the template: only the input's own red border remains -->
<inputs:ColorPicker Validation.ErrorTemplate="{x:Null}" Color="{Binding OpaqueColor}" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/inputs/dropdown.md -->

# Dropdown

Attached properties that hang a themed popup off any `ToggleButton` — a menu of
commands, a filter panel, a colour list. The popup is open while the button is
checked, and closes when you click outside it.

The button is not wrapped in a control: it stays a plain `ToggleButton` you own,
so its `Style`, its content, its triggers and every attached property
(`Sizing.IsSquare`, `Sizing.Size`, `Derive.*`, …) apply directly to it.

## Dropdown

`Dropdown.Popup` hangs the popup off the button, open while it is checked.
`Dropdown.CloseOnClick` dismisses it when a button inside it is clicked, the way
picking a command from a menu does (see [Closing on click](#closing-on-click)).

```xml
<ToggleButton Content="Actions" inputs:Dropdown.CloseOnClick="True">
    <inputs:Dropdown.Popup>
        <StackPanel toolkit:Spacing.Gap="4">
            <Button Content="Rename" Style="{StaticResource GhostButton}" />
            <Button Content="Duplicate" Style="{StaticResource GhostButton}" />
            <Button Content="Delete" Style="{StaticResource GhostButton}" />
        </StackPanel>
    </inputs:Dropdown.Popup>
</ToggleButton>
```

| Attached property | Type | Default | Purpose |
|---|---|---|---|
| `Dropdown.Popup` | `object` | `null` | Content shown in the popup. Setting it is what turns the button into a dropdown. |
| `toolkit:PopupPlacement.Side` / `Alignment` / `Gap` | | `Bottom` / `Start` / `2` | Where the popup opens, set on the button (see [Popup placement](#popup-placement)). |
| `Dropdown.HorizontalOffset` | `double` | `0` | Extra horizontal offset applied on top of the placement. |
| `Dropdown.VerticalOffset` | `double` | `0` | Extra vertical offset applied on top of the placement; the popup sits 2 DIPs from the button by default (the `PopupPlacement` gap). |
| `Dropdown.CloseOnClick` | `bool` | `false` | Close the popup when a button inside it is clicked. |
| `Dropdown.PopupStyle` | `Style` | `null` | Style of the `DropdownPopupHost` drawing the chrome — its background, border, `CornerRadius`, `Padding`, `Foreground` or template (see [Popup chrome](#popup-chrome)). |

## Popup placement

The [`PopupPlacement`](../toolkit/tooltip.md#popupplacement) properties set on the
button place its popup, the way `ToolTipService.Placement` is set on the element
owning a tooltip:

- `Side` — `Bottom` (default), `Top`, `Left` or `Right`. `Top` opens it upward,
  useful for a dropdown sitting near the bottom of the window.
- `Alignment` — `Start` (default), `Center` or `End`. Below or above the button, `End`
  right-aligns the popup on it.
- `Gap` — space between the button and the popup, `2` by default.

When the popup does not fit on the screen, it flips to the opposite side.
`Dropdown.HorizontalOffset` and `Dropdown.VerticalOffset` add to that placement.

```xml
<!-- Side: Bottom (default), Top, Left, Right; Alignment: Start (default), Center, End; Gap: 2 by default -->
<ToggleButton Content="Filter"
              toolkit:PopupPlacement.Side="Bottom"
              toolkit:PopupPlacement.Alignment="End">
    <inputs:Dropdown.Popup>
        <TextBlock Text="Opens down, right aligned." />
    </inputs:Dropdown.Popup>
</ToggleButton>
```

{: .note }
> `Dropdown.Placement` and its `DropdownPlacement` corners are gone: `BottomRight` is
> now `Side="Bottom"` with `Alignment="End"`, `TopLeft` is `Side="Top"`. A tooltip on the
> same button keeps its own `Tooltip.Placement`, so the two popups are placed apart.

## Button style

Because the button is a real `ToggleButton`, every `ToggleButton` style and
attached property works directly on it, `Sizing.IsSquare` and `Sizing.Size`
included. An icon-only dropdown is just an icon-only toggle button:

```xml
<ToggleButton
    toolkit:PopupPlacement.Alignment="End"
    toolkit:Sizing.IsSquare="True"
    toolkit:Sizing.Size="lg">
    <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.EllipsisVertical}" />
    <inputs:Dropdown.Popup>
        <TextBlock Text="An icon only dropdown." />
    </inputs:Dropdown.Popup>
</ToggleButton>
```

## Closing on click

By default the popup stays open until you click outside it. For a menu of commands
that is rarely what you want, so `Dropdown.CloseOnClick` dismisses it as soon as a
button inside is clicked, as in the first example above.

It listens for `ButtonBase.Click`, not for any mouse click, so a `TextBox`, a
`Slider` or a `ComboBox` in the popup stays usable. The flip side is that a
`CheckBox`, a `RadioButton` or a nested `ToggleButton` is a `ButtonBase` too and
will close it — leave `CloseOnClick` off for a popup built out of those.

The command still runs: the click is not handled, it only unchecks the button.

## Popup chrome

The popup content is wrapped in a `DropdownPopupHost`, a `ContentControl` whose
default style draws the themed border. A `Popup` is only a positioning primitive —
it derives from `FrameworkElement`, so it has no template, background or padding of
its own — which is why `Dropdown.PopupStyle` targets the host rather than the popup.
Base it on the default style to keep the theme:

```xml
<ToggleButton Content="Padded">
    <inputs:Dropdown.PopupStyle>
        <Style
            TargetType="{x:Type inputs:DropdownPopupHost}"
            BasedOn="{StaticResource {x:Type inputs:DropdownPopupHost}}">
            <Setter Property="Padding" Value="12,8" />
        </Style>
    </inputs:Dropdown.PopupStyle>
    <inputs:Dropdown.Popup>
        <TextBlock Text="Content padded away from the border." />
    </inputs:Dropdown.Popup>
</ToggleButton>
```

The style sets the host's `Background`, `BorderBrush`, `BorderThickness`,
`CornerRadius`, `Padding` and `Foreground`. They default to the display tokens:
`DisplayBase0Brush`, `DisplayBorder0Brush`, `DisplayThickness`, `DisplayRadius` and
`DisplayPaddingSm`.

## Bindings inside the popup

A `Popup` lives outside the button's logical tree, so nothing would normally flow
into it. `DataContext` and `Sizing.Size` are relayed from the button and the host
restates the theme `Foreground`, so ordinary command and value bindings need nothing
special. A `Foreground` set on the button itself does not flow in; set it through
`Dropdown.PopupStyle` instead:

```xml
<ToggleButton Content="Actions">
    <inputs:Dropdown.Popup>
        <Button Command="{Binding RenameCommand}" Content="Rename" />
    </inputs:Dropdown.Popup>
</ToggleButton>
```

What cannot cross the boundary is anything that walks *out* of the popup — a
`RelativeSource` ancestor lookup or an `ElementName`, both of which stop at the
popup's own `PopupRoot`. Bind through `DropdownPopupHost.PlacementTarget` instead;
the host is a plain ancestor inside the popup, so that lookup stays in one tree:

```xml
<Button Command="{Binding PlacementTarget.DataContext.SaveCommand,
    RelativeSource={RelativeSource AncestorType={x:Type inputs:DropdownPopupHost}}}" />
```

`PlacementTarget` is the `ToggleButton` itself, so the same route reaches its
properties — `IsChecked`, a `Tag`, an inherited value — not just its `DataContext`.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/navigation/index.md -->

# Navigation

Navigation building blocks from `Joufflu.Navigation`:

- **Navigation menu** — a collapsible side menu driven by a `Navigator`.
- **Overlays** — modal dialogs stacked above the current page, plus a standard confirmation.
- **Paging** — a page selector for browsing large sets of data.

The view models use `Navigator`, `Overlayer` / `IOverlayer` and `IPage` from the
`Joufflu.Navigation` namespace. The XAML snippets use the `nav` XML namespace, the
core `fonts` and `toolkit` ones, plus `vm` for your own view models:

```xml
xmlns:nav="clr-namespace:Joufflu.Navigation.Controls;assembly=Joufflu.Navigation"
xmlns:fonts="clr-namespace:Joufflu.Assets.Fonts;assembly=Joufflu"
xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu"
xmlns:vm="clr-namespace:MyApp.ViewModels"
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/navigation/navigation-menu.md -->

# Navigation menu

## Collapsible side menu

The collapsible side menu plugged into its own `Navigator`. The collapse button
folds it to an icons-only rail. A `NavigationGroup` displays like an item but expands
to reveal children, and groups can nest. A `NavigationTitle` labels a section and
turns into a separator line once collapsed.

When collapsed, each item and group hides its label and surfaces it as a
right-placed [tooltip](../toolkit/tooltip.md) on hover, keeping the icons-only
rail discoverable. `IsCollapsed` (bindable) collapses the menu from code. A group's
`Icon` is what shows on the collapsed rail, and `IsExpanded` (closed by default)
opens it; a group holding the selected item opens on its own.

Under a `ThemedWindow` with `AllowContentOverTitleBar`, the menu's top strip (the
`Header` and the space beside the collapse button) drags the window; the collapse
button and the items stay clickable. The `Header` is therefore not interactive.

```xml
<nav:NavigationMenu Navigator="{Binding DemoNavigator}">
    <!-- Optional header slot, hidden when collapsed -->
    <nav:NavigationMenu.Header>
        <StackPanel Orientation="Horizontal" toolkit:Spacing.Gap="8">
            <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Rocket}" />
            <TextBlock Text="My app" />
        </StackPanel>
    </nav:NavigationMenu.Header>
    <nav:NavigationTitle>Demo</nav:NavigationTitle>
    <!-- An item targets the type of the page it navigates to -->
    <nav:NavigationItem TargetType="{x:Type vm:HomeViewModel}">
        <nav:NavigationItem.Icon>
            <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Home}" />
        </nav:NavigationItem.Icon>
        Home
    </nav:NavigationItem>
    <!-- A group displays like an item but expands to reveal children -->
    <nav:NavigationGroup Header="Parent">
        <nav:NavigationGroup.Icon>
            <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.Folder}" />
        </nav:NavigationGroup.Icon>
        <nav:NavigationItem TargetType="{x:Type vm:Submenu1ViewModel}">Submenu 1</nav:NavigationItem>
        <nav:NavigationItem TargetType="{x:Type vm:Submenu2ViewModel}">Submenu 2</nav:NavigationItem>
        <!-- Groups can nest -->
        <nav:NavigationGroup Header="Parent">
            <!-- … more items … -->
        </nav:NavigationGroup>
    </nav:NavigationGroup>
</nav:NavigationMenu>
```

## Resolving a target type to a page

An item's `TargetType` is the **type** of the page (view model) it navigates to.
The `Navigator` turns that type into the page instance through the resolver it is
built with — usually a lookup in the shell view model's page registry:

```csharp
// Pages keyed by their own type, which is what the menu items target.
private readonly Dictionary<Type, object> _pages = new object[]
{
    new HomeViewModel(),
    new Submenu1ViewModel(),
    new Submenu2ViewModel(),
}.ToDictionary(page => page.GetType());

public Navigator Navigator { get; }

public ShellViewModel()
{
    Navigator = new Navigator(target => _pages.GetValueOrDefault(target));
}
```

An item shows as selected while the current page is of its `TargetType`, so give
each menu entry its own page type. Returning `null` from the resolver (an unknown
type) leaves the current page in place.

Navigating from code takes either form — a type, resolved the same way, or a page
instance directly:

```csharp
Navigator.Navigate(typeof(HomeViewModel));
Navigator.Navigate(new HomeViewModel());
```

## Page lifecycle

A page doesn't have to implement anything. One that wants to know when it is shown
or left implements `IPage`, whose two methods have empty defaults so only the one
needed is written:

```csharp
public class HomeViewModel : IPage
{
    public void OnNavigatedTo() => Refresh();
}
```

The `Navigator` calls `OnNavigatedFrom` on the page it leaves, then `OnNavigatedTo`
on the new one. Overlay content gets the same calls when it is shown and closed.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/navigation/overlays.md -->

# Overlays

Modal content shown above the page: a title bar with a close cross and a content
area. Multiple overlays stack.

## Hosting the overlays

Overlays are rendered by an `OverlayContainer` bound to the `Overlayer` you
show them from. Wrap the whole window content in it so an overlay covers
everything — side menu included:

```xml
<nav:OverlayContainer Overlays="{Binding Overlays}">
    <!-- the whole app -->
</nav:OverlayContainer>
```

The container creates an `Overlayer` of its own when none is bound. Bind one from
your shell view model to share it with the pages: `Overlays` takes it as an
`IOverlayer`, so the shell can expose the contract only.

Toasts have their own [`ToastContainer`](../feedback/toasts.md); wrap it around
this one to keep them above the overlays.

## Showing an overlay

The overlay content owns its buttons and closes itself through the overlayer, in
one of three ways that tell the caller how it ended:

| Close with | `ShowAsync` returns |
|---|---|
| `overlays.Validate(content)` | `true` |
| `overlays.Cancel(content)` | `false` |
| `overlays.Ignore(content)` | `null` — also what the close cross and a click on the dimmed background do |

Each closes the overlay showing that exact content, even when another overlay sits
above it.

`OverlayOptions` exposes `Title`, `ShowCloseButton`, `CloseOnClickAway` (set
`false` to force the user through the action buttons) and `FullScreen`.

### Any object

Any object works as content, resolved to its view through an implicit
`DataTemplate`, with the options given at show time:

```csharp
var options = new OverlayOptions { Title = "Edit profile" };
bool? result = await overlays.ShowAsync(content, options);
```

Content implementing `IOverlayContent` carries its own `Options` instead, so
`ShowAsync` can be called without them.

### Awaiting a result

Content implementing `IOverlayContent<TResult>` also exposes the `Result` it was
validated with. Shown through the generic `ShowAsync`, the overlay hands that
result back when validated, and the default of `TResult` when cancelled or
ignored:

```csharp
public partial class SampleFormViewModel : ObservableObject, IOverlayContent<string>
{
    private readonly IOverlayer _overlays;

    public SampleFormViewModel(IOverlayer overlays) => _overlays = overlays;

    public OverlayOptions Options { get; } = new() { Title = "Edit profile", CloseOnClickAway = false };

    [ObservableProperty]
    private string _name = "Ada Lovelace";

    public string? Result => Name;

    [RelayCommand]
    private void Save() => _overlays.Validate(this);

    [RelayCommand]
    private void Cancel() => _overlays.Cancel(this);
}
```

```csharp
string? name = await overlays.ShowAsync(new SampleFormViewModel(overlays));
if (name != null)
    // saved
```

`IOverlayContent` derives from [`IPage`](navigation-menu.md#page-lifecycle), so content can also react to
being shown and closed through `OnNavigatedTo` / `OnNavigatedFrom`.

## Standard confirmation

For the common "are you sure?" case, `Confirm` shows a built-in overlay — the
message plus a *Cancel* / *Confirm* pair — with no content of your own:

```csharp
bool? result = await overlays.Confirm(
    "Delete the selected item? This action cannot be undone.",
    "Please confirm",
    EnumConfirmationType.Danger);

if (result == true)
    // confirmed
```

`EnumConfirmationType` colours the confirm button in the matching semantic style:
`Neutral` (the default), `Info`, `Success`, `Warning` or `Danger`.

## Full screen

`FullScreen = true` stretches the overlay over the entire container instead of a
centered, sized panel — a whole-window editor or wizard rather than a dialog:

```csharp
await overlays.ShowAsync(content, new OverlayOptions { Title = "Edit", FullScreen = true });
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/navigation/paging.md -->

# Paging

## Paging

Page selector for a set of `Total` items. It exposes `PageNumber` and `Capacity`
(items per page), and the range currently displayed. Pages are elided with a
separator when there are more than seven of them.

```xml
<nav:Paging Total="123" />
```

| Property | Type | Default | Purpose |
|---|---|---|---|
| `Total` | `int` | `-1` | Number of items in the whole set. A negative value (the `-1` default) leaves it unknown: the range label is hidden and the page count unbounded. `0` is an empty set. |
| `PageNumber` | `int` | `1` | Current page, 1-based. Clamped between `1` and the last page. |
| `Capacity` | `int` | `10` | Items per page, picked from `AvailableCapacities` (`5, 10, 25, 50, 100, 200` by default). |
| `IsTotalKnown` | `bool` (read-only) | — | Whether `Total` is known (`>= 0`). |
| `PageMax` | `int` (read-only) | — | Last page, derived from `Total` and `Capacity`. |
| `IntervalMin` / `IntervalMax` | `int` (read-only) | — | Bounds of the range currently displayed, shown as `1-10 of 123`. |

## Paged data grid

Paging only tells you which slice to display, it never touches the data itself.
Bind `Total` to the number of items in the whole set, then bind `PageNumber` and
`Capacity` two way so the view model is notified of every change and can load the
matching slice.

```xml
<DataGrid ItemsSource="{Binding PageItems}" AutoGenerateColumns="False">
    <DataGrid.Columns>
        <DataGridTextColumn Header="Id" Binding="{Binding Id}" />
        <DataGridTextColumn Header="Name" Binding="{Binding Name}" />
    </DataGrid.Columns>
</DataGrid>
<nav:Paging
    Total="{Binding Total}"
    PageNumber="{Binding PageNumber, Mode=TwoWay}"
    Capacity="{Binding Capacity, Mode=TwoWay}" />
```

```csharp
// The view model reacts to any paging change from its own setters.
public int PageNumber
{
    get => _pageNumber;
    set { if (SetProperty(ref _pageNumber, value)) UpdatePage(); }
}

public int Capacity
{
    get => _capacity;
    set { if (SetProperty(ref _capacity, value)) UpdatePage(); }
}

private void UpdatePage()
{
    // Query only the current page (Skip/Take, SQL OFFSET/FETCH, API page parameters, …)
    PageItems.Clear();
    foreach (var item in _source.Skip((PageNumber - 1) * Capacity).Take(Capacity))
        PageItems.Add(item);
}
```

{: .note }
> `Mode=TwoWay` is required: neither `PageNumber` nor `Capacity` binds two way by
> default, so without it the control would never push the new page back to the
> view model.

## Paging without a known total

Leave `Total` at its `-1` default when the size of the set is unknown (a cursor-based
API, a stream). The range label is hidden and the page list grows one page ahead of
the current one, so the user can always move forward:

```xml
<!-- Total left at its -1 default -->
<nav:Paging
    PageNumber="{Binding PageNumber, Mode=TwoWay}"
    Capacity="{Binding Capacity, Mode=TwoWay}" />
```

Set `Total` as soon as you know it and the control switches back to a bounded list.

## Reacting without bindings

For code-behind, the control raises `PagingChange` with the new page number and
capacity every time either changes:

```csharp
paging.PagingChange += (pageNumber, capacity) => UpdatePage(pageNumber, capacity);
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/data/index.md -->

# Data

JSON values edited as a tree, from the optional
[`Joufflu.Data`](https://www.nuget.org/packages/Joufflu.Data) package.

- **Data fill** — fills in a value against a JSON Schema.
- **Data form** — fills in a value against a JSON Schema as a form, with the inputs and rules the schema gives.
- **Data edit** — builds a value from scratch.
- **Data display** — shows a value read only.

Add the package (`dotnet add package Joufflu.Data`). Only the core `Resources.xaml` needs
merging. The snippets use:

```xml
xmlns:data="clr-namespace:Joufflu.Data.Controls;assembly=Joufflu.Data"
```

```csharp
using Joufflu.Data.Model;
using NJsonSchema;
using DataObject = Joufflu.Data.Model.DataObject; // System.Windows has one too
```

## Nodes

The controls take a `Node`: `DataFill` and `DataEdit` edit a `DataObject` root in place,
`DataDisplay` only shows it, and takes any node or a `JToken`
([Data display](data-display.md#show-a-node)).

| Node | Holds |
|---|---|
| `DataObject` | `Properties`, keyed by unique, case-sensitive keys |
| `DataArray` | `Values`, keyed `[0]`, `[1]`…, and the `Template` new items are cloned from |
| `DataValue` | a `Value`, or the `Options` of an enum |

`ToToken()` returns the JSON:

```csharp
string? json = Node.ToToken()?.ToString();
```

## From a schema

`ToDataNode()` builds the tree of an [NJsonSchema](https://github.com/RicoSuter/NJsonSchema)
`JsonSchema`:

```csharp
Node = (DataObject)JsonSchema.FromType<Order>().ToDataNode();
```

| Schema | Editor | Written as |
|---|---|---|
| `string` | `TextBox` | string |
| `string`, format `date` / `date-time` | `DatePicker` | ISO 8601 string |
| `string`, format `time-span` / `duration` | `TimeSpanPicker` | `[d.]hh:mm:ss` string |
| `integer` | `NumericUpDown` | number |
| `number` | `DecimalUpDown` | number |
| `boolean` | `CheckBox` | `true` / `false` |
| `enum` | `ComboBox`, named by `x-enumNames` | the option's value |
| `array` / `object` | tree | array / object |

New values start at `null` when nullable, else at the type's default (`""`, `0`, `false`,
today, the first option).

{: .note }
> Not supported: arrays with a list of item schemas, or with no `items` schema. A schema with no type (`{}`) becomes a value filled in as free text.

## To a schema

`ToJsonSchema()` does the reverse: the schema of a tree, built from a schema or with
`DataEdit`, following the table above (time spans get the `time-span` format):

```csharp
JsonSchema schema = Node.ToJsonSchema();
string json = schema.ToJson();
```

Keys, `Description`, `IsNullable`, `IsRequired` and the enum `Options` are kept; values are not.

## From JSON

`Load()` fills a tree with a JSON value, the reverse of `ToToken()`, to edit a value again:

```csharp
Node = (DataObject)schema.ToDataNode();
Node.Load(JToken.Parse(json), ManualValues);
```

The tree keeps its shape. A node matching one of the [manual values](#manual-values), or one its
editor can't hold (an object given a string, say), is forced to it rather than lost; a property
the JSON leaves out is forced to **undefined** when not required.

Without a schema, `ToDataNode()` on a `JToken` infers the tree from the value, for `DataEdit`:

```csharp
Node = (DataObject)JObject.Parse(json).ToDataNode();
```

`ReadDataNode()` gives the same tree straight from a `JsonReader`, for a large file: it is never
held as tokens too ([open a file](data-display.md#open-a-file)). A key given twice keeps its last
value, comments are skipped.

```csharp
using var reader = new JsonTextReader(File.OpenText(path));
DataNode node = reader.ReadDataNode();
```

`Changed` is raised when the data of a node or of anything under it changes, to react to an
edit anywhere in the tree: a key, a value, the manual mode or entry, an array template,
children added or removed. Expanding a node, flagging a duplicate key or moving a node to
another parent change no data and raise nothing.

## Manual values

`ManualValues` lists what a field can be forced to instead of its editor, like a
placeholder resolved later. Each entry names the type it fits (`null` fits any):

```csharp
public IReadOnlyList<DataManualValue> ManualValues { get; } =
[
    new(EnumDataType.String, "TBD"),
    new(EnumDataType.Integer, -1L),
];
```

The feather toggle swaps a field's editor for the entries that fit it, plus **undefined**
(the property is left out) when not required and **null** when nullable. It is disabled
when nothing fits. Objects and arrays have it too: forced, their properties or items are
hidden and the entry is written in their place, and they come back as they were once released.

An entry that takes any name is a `DataManualPattern`, the name written between braces:

```csharp
new DataManualPattern(null, "$row.columns['{column name}']"),
```

The list shows it as the hint `$row.columns['column name']`, which can't be picked. Typing
`unit price` offers `$row.columns['unit price']` in its place. `Load` forces a value the
pattern writes back to it.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/data/data-fill.md -->

# Data fill

## Fill in from a schema

`DataFill` edits the values of a node [built from a schema](index.md#from-a-schema): keys
and shape are fixed, only values and array items change.

```xml
<data:DataFill Node="{Binding Node}" ManualValues="{Binding ManualValues}" />
```

- A property's `description` shows as an info tooltip.
- **Add** on an array clones its `Template`; array items can be removed.
- Every editor takes the width of the narrowest one, so they line up whatever their depth
  (see [shared width](../toolkit/shared-width.md)).
- The feather toggle forces a field, object or array to one of the
  [manual values](index.md#manual-values), hiding the properties or items of an object or an array.

To reset, build a new node from the schema.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/data/data-form.md -->

# Data form

## A form from a schema

`DataForm` fills in a node [built from a schema](index.md#from-a-schema), like
[`DataFill`](data-fill.md), but as a form rather than a tree: a labelled field per property,
objects as groups of fields, arrays as lists of items.

```xml
<data:DataForm Node="{Binding Node}" ManualValues="{Binding ManualValues}" />
```

Each field reads what the schema says of it:

| Schema | Field |
|---|---|
| `title` (`[Display(Name = ...)]`) | Its label, the key otherwise. |
| `description` (`[Description]`) | Under the label. |
| `required` (`[Required]`) | A `*` after the label. |
| `minimum`, `maximum` (`[Range]`) | Checked as it is typed: "At least 1.", "At most 20." |
| `minLength`, `maxLength`, `pattern` | Checked the same way: "Required.", "At most 5 characters.", "Doesn't match the expected format (...)". |
| `x-input: file`, `x-file-filter` | A `FilePicker`, its dialog showing the filter. |
| `x-input: multiline` | A text box of several lines. |

The `x-input` keys have no JSON Schema equivalent. NJsonSchema writes them from attributes:

```csharp
public class Shipment
{
    [Display(Name = "Customer name")]
    [Description("Who receives the parcel.")]
    [Required]
    public string Customer { get; set; } = "";

    [JsonSchemaExtensionData(DataInputs.SchemaKey, DataInputs.File)]
    [JsonSchemaExtensionData(DataInputs.FileFilterSchemaKey, "PDF files|*.pdf|All files|*.*")]
    public string DeliveryNote { get; set; } = "";

    [Range(1, 20)]
    public int Parcels { get; set; } = 1;
}
```

- The broken rule of a value is `DataValue.Error`, null when it breaks none. It is also reported
  on `Value` through `INotifyDataErrorInfo`, so its editor turns its border red and
  `ValidationErrorTemplate` adds a corner badge whose tooltip says why (see
  [Create a custom control](../toolkit/custom-control.md)). A forced value is never checked.
- A boolean is a single checkbox holding its label. Forced, it shows its label above the manual
  values, like any other field.
- **Add** on an array clones its `Template`. Each item, forced or not, has its own remove button.
- A field offers to be forced only to the [manual values](index.md#manual-values) that fit it:
  `null` and undefined alone don't clutter a form. With no `ManualValues`, the form only edits
  values. A field forced already keeps its toggle, to bring its editor back.
- The form scrolls on its own: give it a height.

## An array of strings

An array of strings is a [`ComboBoxTags`](../inputs/combo-box-tags.md): each item is a tag,
removed with its cross, and **Enter** adds the typed text as a new one. Any other array lists its
items, each with its own editor and remove button.

```csharp
public class Mailing
{
    [Description("Who the mail goes to, one address per item.")]
    public List<string> Recipients { get; set; } = [];
}

var node = (DataObject)JsonSchema.FromType<Mailing>().ToDataNode();
node.Load(JObject.Parse("""{ "Recipients": ["alice@example.com", "bob@example.com"] }"""));
```

```xml
<data:DataForm Node="{Binding ArrayNode}" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/data/data-edit.md -->

# Data edit

## Build from scratch

`DataEdit` builds a node freely: add properties and array items of any type, rename keys,
set values, remove rows.

```xml
<data:DataEdit Node="{Binding Node}" />
```

```csharp
public DataObject Node { get; set; } = new("");
```

- New properties are named `key`, `key 1`, `key 2`…; a duplicate key is flagged on its text box.
- **Add** on an array picks the item type, or clones its `Template` when it has one.
- A `Choice` value edits its options (strings) from the list button next to it: type one and
  press Enter, or remove one. The first option becomes the value.

Without a bound `Node`, it starts from an empty object. `ManualValues` works as in
[Data fill](data-fill.md).

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/data/data-display.md -->

# Data display

## Show a node

`DataDisplay` shows a node read only: the key, the type and the value of each node.

```csharp
Node = (DataObject)JsonSchema.FromType<Order>().ToDataNode();
Node.Load(JToken.Parse(json), ManualValues);
```

```xml
<data:DataDisplay Node="{Binding Node}" />
```

- `Node` takes any `DataNode`: an object shows its properties as the first level, an array or a
  value is that level itself.
- Values read the way their editor shows them: the name of a `Choice` option, a date without
  its time when it has none, a time span as `[d.]hh:mm:ss`.
- A value runs on one line: a line break shows as `↵`, a text past 1000 characters is cut.
- **null** and **undefined** are greyed and italic, apart from a text saying "null".
- A value forced to one of the [manual values](index.md#manual-values) is flagged with a
  feather. A forced object or array shows the entry instead of its properties or items.
- A node with a `Description` shows it on an info icon, as in [Data fill](data-fill.md).

The user can only expand and collapse nodes. The display follows the node: values and keys
changed, children added or removed, a node forced or expanded in code show up before the next
render.

## Show a JToken

A `JToken` bound to `Node` is read as `ToDataNode()` does ([From JSON](index.md#from-json)), so a
plain value is shown without building a node first.

```csharp
public JToken Token { get; } = new JValue("Hello");
```

```xml
<data:DataDisplay Node="{Binding Token}" />
```

## Open a file

Read the file with [`ReadDataNode()`](index.md#from-json) off the UI thread, then show the node:

```csharp
// When FilePath changes
using var reader = new JsonTextReader(File.OpenText(FilePath));
Node = await Task.Run(() => reader.ReadDataNode());
```

```xml
<inputs:FilePicker FilePath="{Binding FilePath}" Options="{Binding JsonFileOptions}" />
<data:DataDisplay Node="{Binding Node}" />
```

- The file is never held as tokens too, only as nodes.
- The tree is laid flat in rows of one height, and only the rows in view are built. A file of
  millions of nodes scrolls, expands and collapses as a small one does.
- Give the display a height (a `Grid` row, a fixed `Height`). In a `StackPanel` or a
  `ScrollViewer` it is measured with endless room, and builds every row.

`inputs:FilePicker` is the [file picker](../inputs/file-picker.md) of `Joufflu.Inputs`.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/file-explorer/index.md -->

# File explorer

A themed file explorer from the optional
[`Joufflu.FileExplorer`](https://www.nuget.org/packages/Joufflu.FileExplorer) package.

- **List** — the nodes of the opened folder, with extra columns of your own.
- **Tree** — the loaded hierarchy, folders only by default.
- **Explorer** — everything together: control bar, tree, list and a status bar.
- **Sources** — what the controls display: the disk, the disk watched live, or a source of your own.

Add the package (`dotnet add package Joufflu.FileExplorer`; it brings
`Joufflu.Feedback` along, the sources report their errors as toasts). Only the core
`Resources.xaml` needs merging: the controls' styles load from each package's
`Themes/Generic.xaml`. The snippets use these namespaces:

```xml
xmlns:fileExplorer="clr-namespace:Joufflu.FileExplorer.Controls;assembly=Joufflu.FileExplorer"
xmlns:base="clr-namespace:Joufflu.FileExplorer.Controls.Base;assembly=Joufflu.FileExplorer"
xmlns:fileSystem="clr-namespace:Joufflu.FileExplorer.FileSystem;assembly=Joufflu.FileExplorer"
xmlns:icons="clr-namespace:Joufflu.FileExplorer.Icons;assembly=Joufflu.FileExplorer"
xmlns:toolkit="clr-namespace:Joufflu.Toolkit;assembly=Joufflu"
xmlns:fonts="clr-namespace:Joufflu.Assets.Fonts;assembly=Joufflu"
```

## Sources

Every control binds a `Source`, an `IExplorerSource`: it holds the opened directory
(`Current`), the loaded hierarchy (`Root`) and the commands acting on the nodes.
`FileSystemSource` reads a folder of this machine:

```csharp
// using Joufflu.FileExplorer.Nodes; and Joufflu.FileExplorer.FileSystem; — toasts is an injected IToastService, null is accepted
public IExplorerSource Source { get; }
// in the constructor, where toasts is in scope
Source = new FileSystemSource(@"C:\Projects", toasts);
// ...
await Source.Open();
```

Controls sharing the same source stay in sync: selecting a folder in the tree, double
clicking one in the list or using the breadcrumb opens it for all of them.

{: .note }
> `FileSystemSource` hands copying, moving, renaming and deleting over to the Windows
> shell, so they come with its progress window, its "replace or skip" prompt and its
> recycle bin.

`FileSystemWatcherSource` reads the same disk and keeps up with it, and a source of
your own displays whatever you hand over — see [sources](sources.md).

## Nodes

A source hands over `IExplorerNode`s: a `Name`, a `Path`, a `ModifiedAt` and the
`Parent` directory. `IExplorerDirectory` adds its `Children` and its `DirectoryTree` (itself and its ancestors, for
the breadcrumb), `IExplorerFile` a `Size`.
`FileSystemFile` and `FileSystemDirectory` implement them for the disk, and a type of
your own is displayed like the others — see
[virtual nodes](sources.md#virtual-nodes).

## Interactions

Both the list and the tree come with:

- **Context menus** — keyed on the node type, so a type of your own gets a menu of its own.
- **Drag and drop** — between the controls, and with the Windows explorer.
- **Shortcuts** — `F2` renames, `Ctrl+C` / `Ctrl+X` / `Ctrl+V` copy, cut and paste, `Delete` removes.
- **`VisibleNodes`** — the kinds of node shown: `All`, `Files` or `Directories`.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/file-explorer/list.md -->

# List

## ExplorerList

Lists the nodes of the opened folder, directories first then by natural name order,
with each file's size. Double click a folder to open it, right click a node for its
menu.

```xml
<fileExplorer:ExplorerList Source="{Binding Source}" />
```

`SelectedNodes` is read-only: bind it `OneWay`, for a status bar counting the
selection for instance. `View` gives the sorted and filtered nodes as the list
displays them.

## Extra columns

`ExtraColumns` adds columns after the ones of the list (name, modification date, size).
Each cell is bound to the node of its row, so a node type of your own shows the data it
carries: here the path every node has, and a cell template reading the parent folder.

```xml
<fileExplorer:ExplorerList Source="{Binding Source}">
    <fileExplorer:ExplorerList.ExtraColumns>
        <GridViewColumn Header="Full path" Width="260" DisplayMemberBinding="{Binding Path}" />
        <GridViewColumn Header="In folder">
            <GridViewColumn.CellTemplate>
                <DataTemplate>
                    <TextBlock Text="{Binding Parent.Name}" />
                </DataTemplate>
            </GridViewColumn.CellTemplate>
        </GridViewColumn>
    </fileExplorer:ExplorerList.ExtraColumns>
</fileExplorer:ExplorerList>
```

`Explorer` has an `ExtraColumns` of its own, handed over to its list.

## Filtering the nodes

`VisibleNodes` chooses the kinds of node shown: `All` by default, or `Files` /
`Directories` to keep only one. Here the list keeps only the files.

```xml
<fileExplorer:ExplorerList Source="{Binding Source}" VisibleNodes="Files" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/file-explorer/tree.md -->

# Tree

## ExplorerTree

Shows the loaded hierarchy, each level sorted on its own so it stays independent from
the list. A tree shows only folders by default. Selecting a folder opens it, and so
does expanding it, which selects it; a double click expands it.

```xml
<fileExplorer:ExplorerTree Source="{Binding Source}" />
```

## Showing files too

`VisibleNodes` chooses the kinds of node a control shows: `Directories` (the tree
default), `Files`, or `All`. Set it to `All` to list the files alongside the folders.

```xml
<fileExplorer:ExplorerTree Source="{Binding Source}" VisibleNodes="All" />
```

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/file-explorer/explorer.md -->

# Explorer

## Explorer

Everything together: the control bar with the breadcrumb of the opened path, the tree
of the loaded hierarchy next to the list of the opened folder, and a status bar
counting its items and the selected ones.

```xml
<fileExplorer:Explorer Source="{Binding Source}" />
```

The parts share the `Source` of the explorer, which is what keeps them in sync.
`ExtraColumns` is handed over to its list, see
[extra columns](list.md#extra-columns).

Each part is a control of its own, to lay out differently: `ExplorerControlBar` (the
breadcrumb, each folder reopened by a click, and a button up to the parent folder),
[`ExplorerTree`](tree.md) and [`ExplorerList`](list.md), bound to the same source.

```xml
<fileExplorer:ExplorerControlBar Source="{Binding Source}" />
```

## Custom node template

The node visuals are implicit templates keyed by node type: redeclaring one in the
resources of a control replaces it there only. Here `ExplorerIconConverter` trades the
font icons for the icons the system associates with each file type.

```xml
<fileExplorer:Explorer Source="{Binding Source}">
    <fileExplorer:Explorer.Resources>
        <DataTemplate x:Key="NodeWithSystemIcon">
            <StackPanel Orientation="Horizontal" toolkit:Spacing.Gap="4">
                <Image Width="16" Height="16"
                       Source="{Binding Converter={x:Static icons:ExplorerIconConverter.Small}}" />
                <TextBlock Text="{Binding Name}" />
            </StackPanel>
        </DataTemplate>
        <!-- Replaces the implicit template of the node type, in this control only -->
        <DataTemplate DataType="{x:Type fileSystem:FileSystemFile}">
            <ContentPresenter Content="{Binding}" ContentTemplate="{StaticResource NodeWithSystemIcon}" />
        </DataTemplate>
        <DataTemplate DataType="{x:Type fileSystem:FileSystemDirectory}">
            <ContentPresenter Content="{Binding}" ContentTemplate="{StaticResource NodeWithSystemIcon}" />
        </DataTemplate>
    </fileExplorer:Explorer.Resources>
</fileExplorer:Explorer>
```

## Virtual nodes

A source hands over the nodes it wants, of the disk or of the application, and a node
type of your own is templated like the others — see
[virtual nodes](sources.md#virtual-nodes).

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/file-explorer/sources.md -->

# Sources

Every control binds a `Source`, an `IExplorerSource`: it holds the opened directory
(`Current`), the loaded hierarchy (`Root`) and the commands the menus and the shortcuts
act with. Controls sharing the same source stay in sync — selecting a folder in the
tree, double clicking one in the list or using the breadcrumb opens it for all of them.

```csharp
// using Joufflu.FileExplorer.Nodes; and Joufflu.FileExplorer.FileSystem; — toasts is an injected IToastService, null is accepted
public IExplorerSource Source { get; }
// in the constructor, where toasts is in scope
Source = new FileSystemSource(@"C:\Projects", toasts);
// ...
await Source.Open();
```

## FileSystemSource

A directory of this machine, read when it is opened: a directory is loaded along with
two levels of sub directories, so the tree shows an expander without reading the disk
again.

{: .note }
> Copying, moving, renaming and deleting are handed over to the Windows shell, so they
> come with its progress window, its "replace or skip" prompt and its recycle bin. A
> whole selection goes in one call, which is what keeps the windows of the shell to one
> for the batch.

What it reads is a snapshot: the nodes are read again when a directory is opened, or
after an operation made through the explorer. A change made outside of it — by another
application, or by the Windows explorer — shows up the next time that directory is
opened.

## FileSystemWatcherSource

The same source, watching the disk: a file or a directory created, deleted, renamed or
moved outside of the explorer shows up in it without a refresh.

```csharp
public IExplorerSource Source { get; }
// in the constructor, where toasts is in scope
Source = new FileSystemWatcherSource(@"C:\Projects", toasts);
// ...
await Source.Open();
```

The opened directory follows what happens to it: renamed, it is opened again under its
new path; deleted, the directory that held it is opened instead, the way the Windows
explorer does.

{: .note }
> It is `IDisposable`: dispose it to stop watching. Only the loaded nodes are
> maintained, an event about a directory that has never been opened being dropped — it
> will be read from the disk when it is opened. The content of a file isn't watched, a
> node only carrying the size and the date it has been read with.

## Virtual nodes

A source hands over the nodes it wants: this one adds a `notes.md` of its own in every
directory, associated to a path no file of the disk stands behind. A node type of the
application is templated like the others — its visual and its context menu are keyed on
its type, and an extra column shows the state it carries.

Opening a directory reads the disk off the UI thread, so a slow or a network drive doesn't
freeze the window, then hands what it read to `ApplyDirectory` on the UI thread, once for
the directory and once for each sub directory read along with it. Override it to add nodes
of your own next to the ones read.

```csharp
// A node type of the application : it carries a path, and a state no file of the disk has.
// An IExplorerNode and not an IExplorerFile : it has no size, so the size column stays empty on its row.
public class VirtualFile : ObservableObject, IExplorerNode
{
    public string Path { get; set; }
    public string Name { get; }
    public DateTime ModifiedAt { get; }
    public IExplorerDirectory? Parent { get; set; }

    public bool IsPinned { get => isPinned; set => SetProperty(ref isPinned, value); }
    private bool isPinned;

    public VirtualFile(IExplorerDirectory parent, string name)
    {
        Parent = parent;
        Name = name;
        Path = System.IO.Path.Combine(parent.Path, name);
        ModifiedAt = parent.ModifiedAt;
    }
}

// A source hands its own nodes over along with the ones it reads.
public class VirtualFilesSource : FileSystemSource
{
    public VirtualFilesSource(string rootDirectoryPath, IToastService? toasts) : base(rootDirectoryPath, toasts) { }

    protected override void ApplyDirectory(IExplorerDirectory directory, DirectoryRead read)
    {
        base.ApplyDirectory(directory, read);
        directory.Children.Add(GetVirtualFile(directory));
    }

    // Nothing to hand over to the shell : a virtual file is opened by the application itself.
    public override Task Open(IExplorerNode node) { ... }
}

// Template of the cells of the extra column, chosen by node type.
public class PinnedCellTemplateSelector : DataTemplateSelector
{
    public DataTemplate? PinnedTemplate { get; set; }
    public DataTemplate? EmptyTemplate { get; set; }

    public override DataTemplate? SelectTemplate(object item, DependencyObject container)
        => item is VirtualFile ? PinnedTemplate : EmptyTemplate;
}
```

The context menu of a node type is a `DataTemplate` keyed with
`ContextMenuTemplateKey`. Its data context is an `ExplorerMenuContext`: `Node` for the
node the menu was opened on, `Nodes` for the whole selection, `Source`, and the commands
of the items — `OpenCommand`, `CopyCommand`, `CutCommand`, `PasteCommand`,
`RemoveCommand` and `CreateDirectoryCommand` run on the source, `BeginRenameCommand`
renames the node in the control the menu was opened in, and `OpenInExplorerCommand`,
`OpenWithDefaultCommand` and `CopyPathCommand` act on the disk, disabled for a source
that isn't a `FileSystemSource`. Copy, cut and remove act on `Nodes`; the others take the
node as their `CommandParameter`.

```xml
<fileExplorer:Explorer Source="{Binding VirtualSource}">
    <fileExplorer:Explorer.Resources>
        <!-- Cells of the extra column : the box only exists on the rows carrying the state -->
        <DataTemplate x:Key="PinnedCell">
            <CheckBox IsChecked="{Binding IsPinned, Mode=OneWay}" IsHitTestVisible="False" />
        </DataTemplate>
        <DataTemplate x:Key="EmptyCell" />
        <local:PinnedCellTemplateSelector x:Key="PinnedCellSelector"
                                          PinnedTemplate="{StaticResource PinnedCell}"
                                          EmptyTemplate="{StaticResource EmptyCell}" />

        <!-- Visual of the virtual nodes, implicit as the ones of the library are -->
        <DataTemplate DataType="{x:Type local:VirtualFile}">
            <StackPanel Orientation="Horizontal" toolkit:Spacing.Gap="4">
                <fonts:FontIcon Text="{x:Static fonts:LucideFontIcons.StickyNote}" />
                <TextBlock Text="{Binding Name}" />
            </StackPanel>
        </DataTemplate>

        <!-- Context menu keyed on the node type, replaces the one of the files nowhere else -->
        <DataTemplate x:Key="{base:ContextMenuTemplateKey local:VirtualFile}">
            <ContextMenu>
                <MenuItem Header="Pinned" IsCheckable="True"
                          IsChecked="{Binding Node.IsPinned, Mode=TwoWay}" />
                <MenuItem Header="Copy path" Command="{Binding CopyPathCommand}"
                          CommandParameter="{Binding Node}" />
            </ContextMenu>
        </DataTemplate>
    </fileExplorer:Explorer.Resources>
    <fileExplorer:Explorer.ExtraColumns>
        <!-- The column is shared by every row : its template is chosen by node type,
             so IsPinned is only bound on the rows that have it -->
        <GridViewColumn Header="Pinned" Width="70"
                        CellTemplateSelector="{StaticResource PinnedCellSelector}" />
    </fileExplorer:Explorer.ExtraColumns>
</fileExplorer:Explorer>
```

{: .note }
> A context menu template is searched from the most specific type of the node up to
> `object`, and on the scope of the menu (`Single`, `Multiple`, `None` outside of any
> node). The built-in menus are keyed on `FileSystemDirectory` and `FileSystemFile` for a single
> node and on `object` for a multi-selection or the empty area, so a single node of a type of
> your own shows no menu until you key one on its type.

## A source of something else

A source that reads none of the disk implements `IExplorerSource` itself: `Root` and
`Current`, `Open()` and `Open(node)`, `Transfer(paths, target, isMove)` for what is
dropped or pasted into it, and the plain operations the menus and the shortcuts run:
`Rename(node, name)`, `Remove(nodes)`, `CreateDirectory(parent)`, `Copy(nodes)`,
`Cut(nodes)`, `Paste(target)` and `CanPaste()`. The controls build the commands
themselves, so a source holds no UI.

The nodes it hands over are `IExplorerNode`s: a `Name`, a `Path`, a `ModifiedAt` and
the `Parent` directory, `IExplorerDirectory` adding its `Children` and its
`DirectoryTree` (itself and its ancestors, from the root, which the breadcrumb shows),
and `IExplorerFile` a `Size`.

---

<!-- source: https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/comparison.md -->

# Joufflu vs other WPF UI libraries

Which WPF UI library should you pick for a modern-looking desktop app? This page
says where Joufflu fits and, as importantly, where another library is the better
choice. Check each project's own repository for its current status before deciding:
this page does not track their releases.

## At a glance

| You want | Reach for |
|---|---|
| A neutral, modern look that you can make your own by overriding tokens, with live Light / Dark theming, a themed window, and inputs, navigation, modals and toasts that already match | **Joufflu** |
| A Material Design look | MaterialDesignInXaml |
| A Windows 11 / Fluent look | WPF-UI, ModernWpf, or the Fluent theme built into recent .NET versions of WPF |
| A Metro-style window and controls | MahApps.Metro |
| The widest catalogue of ready-made controls | HandyControl, Extended WPF Toolkit |
| Plain WPF with only a few touch-ups | Hand-written styles |

## What Joufflu is

- **One design system, not a bag of controls.** Colours, corner radius, spacing,
  control heights and font sizes are resource keys (`joufflu:Colors.*`, which the
  `joufflu:Brushes.*` follow, and `joufflu:Dimensions.*`). Every Joufflu control and
  every restyled native control reads them through `DynamicResource`, so a theme
  change reaches all of them at once.
- **Customizable by design.** Brand colours, corner radius, spacing, control heights
  and font sizes are all tokens: override a few in a dictionary merged after the Joufflu
  resources and every control follows, with no `ControlTemplate` copied or edited.
  Register a whole palette by name (`ThemeManager.Instance.Register`) to make it selectable next
  to Light and Dark. The gallery's **Customize theme** window edits the tokens live,
  starts from presets and generates the dictionary to paste into your app
  ([Customize theme](themes/customize-theme.md)).
- **Restyled natives.** Buttons, text boxes, combo boxes, data grids and the rest of the
  built-in WPF controls pick up the style from the implicit styles, with no
  `Style=` needed on each one.
- **The pieces an app shell needs.** `ThemedWindow` (custom chrome), `NavigationMenu` and
  a view-model-first `Navigator`, awaitable modal overlays (`await overlays.Confirm(...)`),
  stacking toasts, paging, badges, a spinner, a file explorer and JSON-schema driven
  data trees.
- **Typed, explicit APIs.** Layout and size helpers are attached properties
  (`Spacing.Gap`, `Sizing.Size`, `Derive.Margin`) checked by the XAML compiler, with no
  reflection or string-based conventions.
- **Modular.** Core styles in `Joufflu`; inputs, navigation, feedback, file explorer and
  data are separate NuGet packages you add only when needed.
- **Built to be read by AI agents.** [`llms.txt`](https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/llms.txt),
  [`llms-full.txt`](https://raw.githubusercontent.com/ndegheselle/Joufflu/main/docs/llms-full.txt)
  and a Claude Code plugin give an agent the exact namespaces, names and wiring.

## When not to pick Joufflu

Be honest about the trade-offs:

- **It is young and has a single maintainer.** Expect API changes between 0.x versions,
  and a smaller community than the long-established libraries.
- **It targets `net10.0-windows` only.** Older .NET Framework and earlier .NET versions
  are not supported.
- **It has its own look.** Tokens let you re-colour and re-proportion it, but it does
  not reproduce Material Design or Windows 11 Fluent visuals. If your product must
  follow one of those design languages, use a library built for it.
- **The control catalogue is focused.** There is no ribbon, docking manager, charting
  or property grid. Combine Joufflu with a dedicated library for those, or write them
  against the same tokens.

## Migrating or mixing

- To move an existing view onto Joufflu, replace hardcoded colours and sizes with the
  tokens and named styles, and delete local styles that fight the implicit ones. The
  `joufflu-restyle` skill of the [Claude Code plugin](https://github.com/ndegheselle/Joufflu/tree/main/plugins/joufflu)
  automates this audit.
- Two libraries that both restyle the native controls will fight over the implicit
  styles. If you mix, keep one of them in charge of the natives and use the other only
  for controls it alone provides.

## Next steps

- [Getting started](index.md#getting-started)
- [Tutorial: a navigable app shell](tutorial.md)
- [Recipes](recipes.md): complete, copy-paste screens