shiny-maui-shell

name	shiny-maui-shell
description	Generate .NET MAUI Shell pages, ViewModels, navigation, and source-generated routes using Shiny MAUI Shell
auto_invoke	true
triggers	["maui shell","shell navigation","xaml navigation","attached navigation","tab badge","badge","shell switch","switch shell","maui navigation","maui page","maui viewmodel","INavigator","IDialogs","ShellMap","ShellProperty","UseShinyShell","UseDialogs","UseShinyDialogs","ShinyDialogs","UseUxDiversDialogs","ShinyShell","ShellServices","ShinyAppBuilder","IMainThread","Shiny.Maui.Shell","IPageLifecycleAware","INavigationConfirmation","INavigationAware","NavigateTo","GoBack","PopToRoot","SetRoot","[Truncated]"]

Shiny MAUI Shell Skill

You are an expert in Shiny MAUI Shell, a library that enhances .NET MAUI Shell with ViewModel lifecycle management, navigation services, source generation, tab badges, and XAML-triggered navigation.

When to Use This Skill

Invoke this skill when the user wants to:

• Create new MAUI pages with ViewModels using Shiny Shell conventions
• Set up or configure Shiny MAUI Shell in their application
• Switch between different Shell instances at runtime (e.g., login shell vs main app shell)
• Implement navigation between pages using INavigator
• Set or clear tab badge values on tabs in the active Shell
• Add route-based XAML navigation with Navigate.* attached properties
• Build multi-segment navigation chains using INavigationBuilder (push multiple pages, pop-and-push)
• Show dialogs (alert, confirm, prompt, action sheet) using IDialogs
• Add ViewModel lifecycle hooks (appearing, disappearing, navigation confirmation)
• Use source generation with [ShellMap] and [ShellProperty] attributes
• Pass parameters between pages during navigation
• Create modal pages or tab navigation
• Migrate from vanilla MAUI Shell or Prism navigation to Shiny MAUI Shell
• Set up AI-driven navigation using Microsoft.Extensions.AI with route discovery and NavigateToRoute
• Create AI-compatible ViewModels with descriptive [ShellMap] and [ShellProperty] attributes

Library Overview

Documentation: https://shinylib.net/maui GitHub: https://github.com/shinyorg/mauishell NuGet: Shiny.Maui.Shell Namespace: Shiny

Shiny MAUI Shell wraps .NET MAUI Shell to provide:

• Page-to-ViewModel registration and automatic BindingContext assignment
• A testable INavigator service for all navigation operations
• A testable IDialogs service for alert, confirm, prompt, and action sheet dialogs
• INavigationBuilder for multi-segment navigation (push multiple pages in one operation, pop-and-push)
• Native numeric tab badges via INavigator.SetTabBadge* / ClearTabBadge*
• Attached-property XAML navigation via Navigate.Route, Navigate.RelativeNavigation, and parameter helpers
• Shell switching — swap the entire Shell at runtime (e.g., login → main app)
• ViewModel lifecycle interfaces (appearing, disappearing, dispose, navigation confirmation)
• Source generators that eliminate boilerplate route registration, produce strongly-typed navigation methods, and generate AI tool metadata
• ShinyShell base class for deterministic initial-page BindingContext assignment
• ShellServices record that aggregates INavigator, IDialogs, and IMainThread for convenient single-parameter injection
• IMainThread abstraction with built-in workarounds for macOS and Linux where MainThread.InvokeOnMainThreadAsync can deadlock / fail
• Pluggable IDialogs implementation via UseDialogs<TDialog>() — swap in your own dialog provider (e.g. ACR UserDialogs, a custom sheet, a test double)

Inspired by Prism Library by Dan Siegel and Brian Lagunas.

Setup

1. Install NuGet Package

dotnet add package Shiny.Maui.Shell

2. Configure in MauiProgram.cs

Manual registration:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseShinyShell(x => x
            .Add<MainPage, MainViewModel>(registerRoute: false)
            .Add<DetailPage, DetailViewModel>("Detail")
            .Add<SettingsPage, SettingsViewModel>("Settings")
        )
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
        });

    return builder.Build();
}

With source generation (preferred):

builder
    .UseMauiApp<App>()
    .UseShinyShell(x => x
        .AddGeneratedMaps()
        .AddAiTools()       // registers AiMauiShellTools as singleton for AI integration
    )

With a custom dialog provider:

builder
    .UseMauiApp<App>()
    .UseShinyShell(x => x
        .AddGeneratedMaps()
        .UseDialogs<MyCustomDialogs>()   // register a custom IDialogs implementation
    );

UseDialogs<TDialog>() replaces the default ShellDialogs provider. The default registration uses TryAddSingleton, so a UseDialogs<> call always wins.

Built-in alternative providers (same IDialogs interface — no ViewModel changes):

// Owned, animated, themeable dialogs via Shiny.Maui.Controls (package: Shiny.Maui.Shell.ShinyDialogs)
builder
    .UseMauiApp<App>()
    .UseShinyControls()                  // registers the Controls IDialogService
    .UseShinyShell(x => x.AddGeneratedMaps().UseShinyDialogs());

// Styled UXDivers popups (package: Shiny.Maui.Shell.UxDiversDialogs)
builder
    .UseMauiApp<App>()
    .UseUxDiversDialogs()                 // initialize UXDivers popup infrastructure
    .UseShinyShell(x => x.AddGeneratedMaps().UseUxDiversDialogs());

3. AppShell must inherit from ShinyShell

Your AppShell (or any Shell subclass) must inherit from Shiny.ShinyShell instead of Shell. This ensures the initial page's BindingContext is set deterministically via Shell's own OnNavigated lifecycle.

AppShell.xaml:

<shiny:ShinyShell
    x:Class="MyApp.AppShell"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:shiny="clr-namespace:Shiny;assembly=Shiny.Maui.Shell"
    xmlns:local="clr-namespace:MyApp"
    Title="MyApp">

    <ShellContent
        Title="Home"
        ContentTemplate="{DataTemplate local:MainPage}"
        Route="MainPage" />

</shiny:ShinyShell>

AppShell.xaml.cs:

using Shiny;

namespace MyApp;

public partial class AppShell : ShinyShell
{
    public AppShell()
    {
        InitializeComponent();
    }
}

Important Notes

• Pages defined in AppShell.xaml should use registerRoute: false since Shell already registers them
• Pages navigated to programmatically need route registration (the default behavior)
• All Pages and ViewModels are registered as Transient in DI automatically

Code Generation Instructions

When generating code for Shiny MAUI Shell projects, follow these conventions:

1. ViewModels

All ViewModels must implement INotifyPropertyChanged. Use CommunityToolkit.Mvvm ObservableObject as the base:

[ShellMap<MyPage>("MyRoute")]
public partial class MyViewModel : ObservableObject
{
}

• Use [ShellMap<TPage>("Route")] on every ViewModel class
• The route parameter must be a valid C# identifier — it is used as the generated constant name and method name
• Invalid route names (hyphens, spaces, leading digits) produce a SHINY001 compiler error
• When no route is specified, the page type name without the Page suffix is used as the generated name
• Set registerRoute: false only for pages already declared in AppShell.xaml
• ViewModel classes using source generation should be partial
• Use primary constructors to inject INavigator and other dependencies

2. Navigation Properties

Use [ShellProperty] on ViewModel properties that should be passed as navigation parameters:

[ShellMap<DetailPage>("Detail")]
public partial class DetailViewModel : ObservableObject
{
    [ShellProperty]
    public string ItemId { get; set; }

    [ShellProperty(required: false)]
    public int PageIndex { get; set; }
}

• Properties marked [ShellProperty] are required by default
• Use [ShellProperty(required: false)] for optional parameters
• [ShellProperty] properties are set directly by the source-generated navigation methods — no IQueryAttributable needed
• Source generator creates strongly-typed extension methods on INavigator

3. Lifecycle Interfaces

Implement these interfaces on ViewModels as needed:

Interface	Purpose
IPageLifecycleAware	OnAppearing() / OnDisappearing() hooks
INavigationConfirmation	Task<bool> CanNavigate() - confirm before leaving
INavigationAware	OnNavigatingFrom(IDictionary<string, object>) - mutate args before leaving
IQueryAttributable	ApplyQueryAttributes(IDictionary<string, object>) - receive navigation args (only needed for string-based NavigateTo(route, args) — not needed when using [ShellProperty])
IDisposable	Cleanup when page is removed from navigation stack

4. Navigation Events

INavigator exposes two events for observing navigation:

• Navigating — fires before navigation with the source ViewModel instance
• Navigated — fires after navigation with the destination ViewModel instance

navigator.Navigating += (sender, args) =>
{
    // args.FromUri, args.FromViewModel, args.ToUri, args.NavigationType, args.Parameters
};

navigator.Navigated += (sender, args) =>
{
    // args.ToUri, args.ToViewModel, args.NavigationType, args.Parameters
};

Hook these events in an IMauiInitializeService for cross-cutting concerns like logging or analytics.

5. Navigation

Always use INavigator for navigation, never Shell.Current.GoToAsync directly:

// Route-based navigation with args
await navigator.NavigateTo("Detail", args: [("ItemId", "123"), ("PageIndex", 0)]);

// ViewModel-based navigation with strongly-typed configuration
await navigator.NavigateTo<DetailViewModel>(vm => vm.ItemId = "123");

// Source-generated strongly-typed method (preferred)
await navigator.NavigateToDetail("123", pageIndex: 0);

// Absolute navigation (navigates to root route "//Detail")
await navigator.NavigateTo("Detail", relativeNavigation: false);
await navigator.NavigateTo<DetailViewModel>(relativeNavigation: false);

// Go back with result parameters
await navigator.GoBack(("Result", selectedItem));

// Go back multiple pages
await navigator.GoBack(backCount: 2);

// Pop to root
await navigator.PopToRoot();

// Switch to a different Shell instance
await navigator.SwitchShell(new MainAppShell());

// Switch to a Shell resolved from DI
await navigator.SwitchShell<MainAppShell>();

5a. Navigation Builder

Use INavigationBuilder for multi-segment navigation (pushing multiple pages in a single operation):

// Push a chain of pages: One > Another > Two
await navigator
    .CreateBuilder()
    .Add<OneViewModel>(x => x.Text = "First")
    .Add<AnotherViewModel>(x => x.Arg = "Middle")
    .Add<TwoViewModel>(x => x.Text = "Last")
    .Navigate();

// Pop back 2 pages, then push a new page
await navigator
    .CreateBuilder()
    .PopBack(2)
    .Add<OneViewModel>(x => x.Text = "Replaced")
    .Navigate();

// Add by route name (no configure callback)
await navigator
    .CreateBuilder()
    .Add("Detail")
    .Navigate();

Important Shell constraints for the Navigation Builder:

• All pages used in a builder chain must be globally registered via Routing.RegisterRoute (i.e., registerRoute: true, which is the default). Pages declared as ShellContent in XAML cannot be used in multi-segment relative URIs.
• PopBack() must be called before any Add() calls.
• fromRoot: true on CreateBuilder only works when the target route is a shell-declared route (a ShellContent in XAML), not a globally registered route.

5b. Tab Badges

Use the badge APIs when a route already exists as a tab in the active Shell:

// Route-based badge updates
await navigator.SetTabBadge("Inbox", 3);
await navigator.ClearTabBadge("Inbox");

// ViewModel-based badge updates
await navigator.SetTabBadge<InboxViewModel>(7);
await navigator.ClearTabBadge<InboxViewModel>();

• Badge APIs target existing tabs in the active Shell, not arbitrary pushed pages
• Supported platforms: Android, iOS, Mac Catalyst, Windows
• Unsupported platforms currently throw PlatformNotSupportedException (neutral target, Linux, macOS AppKit)

5c. XAML Navigation

Use Navigate.* attached properties for simple route-based navigation directly from XAML:

<ContentPage
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:shiny="clr-namespace:Shiny;assembly=Shiny.Maui.Shell">
    <ContentPage.ToolbarItems>
        <ToolbarItem Text="Home"
                     shiny:Navigate.Route="MainPage"
                     shiny:Navigate.RelativeNavigation="False" />
    </ContentPage.ToolbarItems>

    <Button Text="Open Detail"
            shiny:Navigate.Route="Detail"
            shiny:Navigate.ParameterKey="ItemId"
            shiny:Navigate.ParameterValue="{Binding SelectedId}" />
</ContentPage>

For multiple parameters:

<Button Text="Open Modal"
        shiny:Navigate.Route="Modal">
    <shiny:Navigate.Parameters>
        <shiny:NavigationParameters>
            <shiny:NavigationParameter Key="Arg1" Value="{Binding NavArg}" />
            <shiny:NavigationParameter Key="Arg2" Value="5" />
        </shiny:NavigationParameters>
    </shiny:Navigate.Parameters>
</Button>

• Supported controls: Button, MenuItem, ToolbarItem
• Navigate.Route accepts the route string passed to INavigator.NavigateTo(...)
• Keep XAML navigation generic; strongly-typed helpers belong in generated C# extensions, not XAML attached properties

5d. AI Tool Navigation

Shiny MAUI Shell generates AI-compatible route metadata and navigation methods for use with Microsoft.Extensions.AI. An AI chat client can discover routes, understand their purpose, and navigate with parameters extracted from natural language.

Describe routes for AI — Add description to [ShellMap] and [ShellProperty]:

public enum WorkOrderPriority { Low, Medium, High, Urgent }

[ShellMap<WorkOrderPage>(description: "Use when the user reports something broken or needing repair")]
public partial class WorkOrderViewModel : ObservableObject
{
    [ShellProperty("Summarize what is broken based on what the user said", required: true)]
    public string Description { get; set; } = string.Empty;

    [ShellProperty("Infer urgency from tone. Must be: Low, Medium, High, or Urgent", required: true)]
    public WorkOrderPriority Priority { get; set; } = WorkOrderPriority.Medium;
}

Generated AI class (AiMauiShellTools):

The source generator produces an AiMauiShellTools class (name configurable via ShinyMauiShell_AiToolsClassName) that takes INavigator via constructor injection and provides:

• Prompt — pre-formatted string describing all AI-applicable routes for seeding AI system messages
• Tools — ready-to-use AITool[] instances for route discovery and navigation
• GetAiToolApplicableGeneratedRoutes() — returns only routes that have a description AND at least one parameter
• NavigateToRoute(route, args) — AI-friendly navigation using switch dispatch to NavigateTo<TViewModel> with direct property setters and automatic type conversion (int, bool, double, enums, DateTime, etc.)