NXNavigationExtension

To avoid conflicts with the framework and ensure stability, follow these usage rules:

✅ Recommended

• Use a subclass of UINavigationController and register that subclass.
• Register controllers in AppDelegate before modifying appearances.
• Use the framework's methods to handle all navigation bar modifications.

❌ Do Not Use (Avoid these)

• Do not register UINavigationController.self directly.
• Do not use system methods like setNavigationBarHidden:, setNavigationBarHidden:animated:, or setHidden: to show/hide the bar.
• Do not use system properties to modify transparency or appearance related properties.
• Do not use <UIGestureRecognizerDelegate> methods to disable swipe-back gestures; use the framework's provided features instead.
• Do not use edgesForExtendedLayout = UIRectEdge(rawValue: 0) unless specifically instructed by the framework's issue discussions.

Unlike the UIKit version, the SwiftUI version requires you to specify a lookup rule for NXNavigationVirtualWrapperView, which acts as the bridge between SwiftUI and UIKit. You must register the relevant navigation controller classes in your AppDelegate using NXNavigationConfiguration.

For iOS 15+, you should include both SplitViewNavigationController and UIKitNavigationController. For iOS 14, only SplitViewNavigationController is required.

// AppDelegate.swift
var classes: [AnyClass] = []
if #available(iOS 15.0, *) {
    classes = [
        NSClassFromString("SwiftUI.SplitViewNavigationController"),
        NSClassFromString("SwiftUI.UIKitNavigationController"),
    ].compactMap { $0 }
} else {
    classes = [
        NSClassFromString("SwiftUI.SplitViewNavigationController"), // iOS14
    ].compactMap { $0 }
}

let defaultConfiguration = NXNavigationConfiguration.default
defaultConfiguration.registerNavigationControllerClasses(classes) { navigationController, configuration in
    // Configure the bridge using the default rule
    navigationController.nx_applyFilterNavigationVirtualWrapperViewRuleCallback(NXNavigationVirtualView.configureWithDefaultRule(for:))
    return configuration
}

To use the framework, you must first import the module and register your custom navigation controller classes in your AppDelegate. The framework operates on a per-view-controller basis rather than globally managing a UINavigationController, which allows for more granular control.

Registration Steps

1. Import the module: import NXNavigationExtension.
2. Register your custom UINavigationController subclasses in AppDelegate using NXNavigationConfiguration().registerNavigationControllerClasses([...]).

Best Practices

• Do not register UINavigationController.self directly, as this will affect all navigation controllers globally. Instead, create a subclass of UINavigationController and register that.
• Follow the "who uses it, who registers it" principle to avoid polluting other parts of your app.
• Use the registration process before attempting to modify the appearance of view controllers managed by those navigation controllers.

// Register one or multiple custom navigation controller classes
NXNavigationConfiguration().registerNavigationControllerClasses([YourNavigationController.self])

// Or multiple
NXNavigationConfiguration().registerNavigationControllerClasses([YourNavigationController.self, YourNavigationController2.self])

You can use NXNavigationConfiguration.default to apply global settings or provide a closure to dynamically modify the configuration based on the specific UINavigationController or UIViewController being presented.

This allows you to:

1. Apply a default configuration to all registered controllers.
2. Provide specific logic for different UINavigationController subclasses.
3. Provide specific logic for individual UIViewController instances using nx_prepareConfigureViewControllersCallback.

let configuration = NXNavigationConfiguration.default

// Set global defaults
configuration.navigationBarAppearance.tintColor = .customTitle

configuration.registerNavigationControllerClasses([YourNavigationController.self, YourNavigationController2.self]) { navigationController, configuration in
    // Logic for specific UINavigationController subclasses
    if navigationController is YourNavigationController {
        configuration.navigationBarAppearance.backgroundColor = .brown
        
        // Logic for specific UIViewController instances within this controller
        navigationController.nx_prepareConfigureViewControllersCallback { viewController, configuration in
            if viewController is MyViewController {
                configuration.navigationBarAppearance.backgroundColor = .red
            }
        }
    }
    return configuration
}