Loam.Data 3.24.0

Loam

Pure C# themed controls for Avalonia applications.

Loam gives Avalonia apps a complete themed control set with a familiar, compact API, runtime theming, and no XAML.

Status: v3.1.0 released — published as Loam on NuGet. Over the v2 baseline, v3 adds end-to-end theme consistency, Material You, ergonomics fixes, and new shell controls; 3.1 splits charts, pickers, and heavy data controls into opt-in satellite packages (Loam.Charts, Loam.Pickers, Loam.Data). The full solution builds clean with 458 headless/unit tests passing. See the v3 plan and review, the v3 → v3.1 and v2 → v3 migration guides, the Development Plan, and the project memory (decisions, progress log, learnings, and the per-component status tracker).

📖 Documentation

A full documentation site (built with VitePress) lives in docs/ — guides (getting started, theming, C# authoring) plus a documented, example-rich page for every component group. It is published to GitHub Pages automatically via .github/workflows/docs.yml (set repository Settings → Pages → Source to GitHub Actions; the site publishes to https://araxis.github.io/loam/).

Run the docs locally:

cd docs
npm install
npm run docs:dev      # local preview at http://localhost:5173
npm run docs:build    # static build → docs/.vitepress/dist

What Loam is

• Familiar API. Component parameters use predictable names (Variant, Color, Size, Dense, Elevation, …); types live in Loam.Controls (e.g. Button, TextField, DataGrid<T>, the DialogService).
• Polished look. Role-based light/dark colors, tonal surfaces, elevation/shadows, click ripple, state layers, and a full typography scale, all token-driven.
• Pure C#. Controls, ControlThemes, and templates are authored in C# — no .axaml.
• Self-contained. Pickers (date/time/color) and the calendar are custom-built — no dependency on Avalonia's FluentTheme Calendar — and ship in the opt-in Loam.Pickers package.
• Modular. A lean core plus opt-in satellites (Loam.Charts, Loam.Pickers, Loam.Data); add only the control groups you use. Namespaces stay Loam.Controls across the split.
• Highly themeable. A LoamTheme data model with light/dark color schemes, compatibility palettes, and runtime token swapping.
• Cross-platform. One library targeting Avalonia 12 everywhere it runs.

What Loam is not

• Not a drop-in Razor port — you still build Avalonia views; Loam shrinks the mental gap.
• Not a framework wrapper. Loam is an independent control library built directly on Avalonia.

Quick start

Install the core package after a release is published, or reference src/Loam/Loam.csproj while developing from this repository. Add the satellite packages for the control groups you use — each depends on the core package, and namespaces stay Loam.Controls:

dotnet add package Loam
dotnet add package Loam.Charts    # PieChart, BarChart, LineChart
dotnet add package Loam.Pickers   # DatePicker, TimePicker, ColorPicker, DateRangePicker, MonthCalendar
dotnet add package Loam.Data      # DataGrid<T>, SimpleTable, TreeView, Pagination

1. Register the theme in your Application (add Avalonia's FluentTheme for the base controls Loam composes, then LoamTheme, then a registrar for each satellite you reference):

using Avalonia;
using Avalonia.Styling;
using Avalonia.Themes.Fluent;
using Loam.Theming;

public sealed class App : Application
{
    public override void Initialize()
    {
        Styles.Add(new FluentTheme());   // base templates for the window shell + built-in controls
        Styles.Add(new LoamTheme());     // Loam's pure-C# theming + core control themes on top

        Styles.Add(new LoamCharts());    // only if you reference Loam.Charts
        Styles.Add(new LoamPickers());   // only if you reference Loam.Pickers
        Styles.Add(new LoamData());      // only if you reference Loam.Data

        RequestedThemeVariant = ThemeVariant.Light;
    }
}

2. Build UI with Loam controls (object initializers, no XAML):

using Loam;
using Loam.Controls;

var form = new StackPanel
{
    Spacing = 12,
    Children =
    {
        new Text { Text = "Sign in", Typo = Typo.H5 },
        new TextField { Label = "Email", Variant = Variant.Outlined },
        new TextField { Label = "Password", Variant = Variant.Outlined },
        new Button { Content = "Continue", Variant = Variant.Filled, Color = LoamColor.Primary },
    },
};

3. Show a dialog / snackbar (no provider component — uses the window's overlay layer):

var ok = await DialogService.For(this).ConfirmAsync("Delete?", "This cannot be undone.", "Delete", "Cancel");
SnackbarService.For(this).Add(ok ? "Deleted" : "Cancelled", LoamColor.Info);

Theming

LoamTheme projects a LoamThemeData into Avalonia resources, with light/dark theme dictionaries. The default data includes role-based color schemes, compatibility palettes, typography, shadows, shape, spacing, stroke, density, field metrics, state layers, motion, layout, and z-index.

var theme = new LoamTheme();
theme.SetPrimary(Colors.Indigo);                 // recolor the primary at runtime
theme.SetPalette(customLight, customDark);        // swap whole palettes
Application.Current!.RequestedThemeVariant = ThemeVariant.Dark; // flip light/dark

All control colors resolve from tokens (LoamTokens), so theme/variant changes restyle the tree automatically. Per-control overrides use the same Loam knobs: Variant, Color, Size, Dense, Elevation, Outlined, Square, etc.

Component catalog

Groups tagged with a package name ship in that opt-in satellite (since 3.1); everything else is in the core Loam package. See the v3 → v3.1 migration guide.

See memory/component-inventory.md for the full component catalog and the live status of each control, including documented future enhancements such as richer DataGrid inline-edit, picker clock-face/HSV editing, and stacked/time-series charts.

Run the gallery

dotnet run --project samples/Loam.Gallery

The gallery has a side menu and focused pages for the component catalog.

Repository layout

Tech

• Avalonia 12.x, .NET 8 library target, C# pure code-only UI.
• xUnit + Avalonia.Headless.XUnit for behavior tests; .slnx solution; SDK pinned via global.json.
• Build: dotnet build · Test: dotnet test · Pack all four packages: dotnet pack Loam.slnx.

License

MIT.