Nalu.Maui

Nalu.Maui is composed of several specialized modules:

• Navigation: A fluent, type-safe MVVM navigation service. Features include relative/absolute navigation, guards, typed intents, a built-in leak detector, and source-generated page registration via AddPages(). It supports MAUI Shell, NaluShell, and the Scaffold.
• VirtualScroll: A high-performance alternative to CollectionView built on native RecyclerView (Android) and UICollectionView (iOS). It handles thousands of dynamically-sized rows smoothly. Note: This module is dual-licensed (Non-Commercial/Commercial).
• Layouts: Advanced XAML primitives including ToggleTemplate, TemplateBox, SlideBox, ExpanderViewBox, ViewBox, and Magnet (a constraint-based layout system).
• Controls: Specialized cross-platform controls like DurationWheel and InteractableCanvasView.
• Core: Common utilities such as NSUrlBackgroundSessionHttpMessageHandler (iOS background HTTP) and a soft-keyboard manager.

In the current architecture, the navigation bar is no longer a shared strip controlled at the controller level. Instead, the navigation bar is part of each page's individual presentation. It is mounted inside each page's host container, meaning it moves in sync with the page during all scaffold motions (such as push/pop slides, custom ScaffoldPageTransition specs, shared elements, interactive pop, Android predictive back, and modal presentation).

Key characteristics:

• Library-owned chrome: Uses the same ScaffoldNavBarHost, appearance chain, scroll tracker, and default ScaffoldNavBarView (or custom NavBarView).
• No shared strip mode: The concept of a single controller-level strip or virtual bar swap has been removed.
• Page Insets: A page's top inset is derived from its own navigation bar immediately and finally before the page is staged. Page insets are not animated during navigation (though they may animate during same-page visibility toggles).
• Unchanged components: The tab bar (shared bottom chrome), overlays (popups, sheets, panels, flyouts), OverlayEvent, and NavigationEvent remain unchanged.

In Nalu.Maui, Popups are implemented as ContentPages with a transparent background. Nalu provides a PopupPageBase class that simplifies this by automatically creating a modal page with a background scrim (overlay) and a styled container for your content.

To customize the look and feel of all popups in your application, you should define global styles for nalu:PopupScrim (the background overlay) and nalu:PopupContainer (the content box) in your Styles.xaml file.

<!-- Example global styles in Styles.xaml -->
<Style TargetType="nalu:PopupScrim">
    <Setter Property="BackgroundColor" Value="#20000000" />
</Style>

<Style TargetType="nalu:PopupContainer">
    <Setter Property="Background" Value="White" />
    <Setter Property="StrokeShape" Value="RoundRectangle 24" />
    <Setter Property="VerticalOptions" Value="Center" />
    <Setter Property="HorizontalOptions" Value="Center" />
</Style>

Nalu distinguishes between Relative navigation (modifying the current stack) and Absolute navigation (changing the root or shell structure).

Relative Navigation

Used for pushing, popping, or replacing pages within the current stack.

• Push<T>(): Adds a page to the stack.
• Pop(): Removes the top page.
• Pop().Push<T>(): Replaces the current page.

Absolute Navigation

Used for navigating to specific ShellContent items.

• Root<T>(): Switches the entire navigation root to a specific page.
• Root<T>().Add<U>(): Navigates to a root and then pushes a page onto that new stack.

// Relative examples
Navigation.Push<DetailPageModel>(new DetailIntent(42)); // Push with intent
Navigation.Pop(new EditResult(saved: true));           // Pop with result
Navigation.Pop().Push<NewPageModel>();                // Replace

// Absolute examples
Navigation.Root<MainPageModel>();                      // Switch root
Navigation.Root<SettingsPageModel>().Add<DetailPageModel>(); // Root + Push
Navigation.Absolute().Root<MainPageModel>("custom-route"); // Custom route

Nalu is moving to a model where each page has its own dedicated navigation bar. Instead of a single global navigation bar managed by the Scaffold, each page is wrapped in a ScaffoldPageHost.

Key Concepts:

• ScaffoldPageHost: A logical, non-visual Element that acts as the parent of a Page. It manages the page's specific navigation bar (ScaffoldNavBarHost), the bar's context (ScaffoldNavBarContext), and properties like IsNavBarVisible and NavBarOverlapsContent.
• ScaffoldNavBarContext: A per-page object containing navigation state (e.g., CanNavigateBack, IsModal, IsCloseButtonVisible). The Scaffold.NavBarContext property now acts as a forwarder to the current page's context.
• ScaffoldNavBarHost: The UI component that renders the navigation bar for a specific page. It is a logical child of the ScaffoldPageHost and is only present in the element tree when the bar is visible.

Lifecycle:

• A ScaffoldPageHost is created when a page enters the navigation stack (via ScaffoldNavigationStack.Push or setting RootPage) and is disposed when the page leaves the stack.
• Pages remaining in the stack (not currently visible) keep their ScaffoldPageHost alive, allowing their navigation bars to maintain state.

Understanding how Scaffold differs from MAUI Shell:

• Engine-Routed Navigation: Every navigation, including tab taps, is routed through the Nalu engine. This means navigation guards (like ILeavingGuard) will be triggered by tab switches, unlike native Shell behavior.
• Safe Areas: Scaffold automatically manages insets. Page content should use standard SafeAreaEdges per edge. The navigation bar footprint contributes to insets unless NavBarOverlapsContent is set.
• Back Button Handling: Page.OnBackButtonPressed is not supported for hosted pages as it only fires for hardware back. For all leave-path confirmation logic (including on-screen pops), use ILeavingGuard.
• Android Back: Uses the predictive-back dispatcher (compatible with Android 16+).
• State Preservation: Tab switches preserve stacks, scroll offsets, and entry text, matching NaluShell semantics.