waddling-errors 0.7.3

//! Navigation Component
//!
//! Handles URL routing, page resolution, deep linking, and navigation state.
//! This component covers user-facing navigation errors that can be used
//! as teaching opportunities.

use crate::primaries::Primary;
use waddling_errors::ComponentIdDocumented;
use waddling_errors::prelude::*;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Navigation;

impl ComponentId for Navigation {
    fn as_str(&self) -> &'static str {
        "Navigation"
    }
}

impl ComponentIdDocumented for Navigation {
    fn description(&self) -> Option<&'static str> {
        Some(
            "Navigation and routing system. Handles URL routing, page resolution, \
             deep linking, breadcrumbs, and navigation state management.",
        )
    }

    fn examples(&self) -> &'static [&'static str] {
        &[
            "E.Navigation.Page.021: Requested page does not exist (404)",
            "E.Navigation.Route.003: Invalid route pattern",
            "W.Navigation.Redirect.001: Redirect chain detected",
        ]
    }

    fn tags(&self) -> &'static [&'static str] {
        &["routing", "url", "navigation", "user-experience"]
    }
}

// ============================================================================
// Error Code Definitions
// ============================================================================

/// Page not found - the requested page does not exist (.021 = NOT_FOUND)
/// This is the classic 404 error, but presented as a learning opportunity! 🦆
pub const ERR_PAGE_NOT_FOUND: Code<Navigation, Primary> =
    Code::error(Navigation, Primary::Page, 21);

/// Invalid route pattern (.003 = INVALID)
pub const ERR_ROUTE_INVALID: Code<Navigation, Primary> = Code::error(Navigation, Primary::Route, 3);

/// Redirect chain detected (.001 = MISSING) - warning about redirect hops
pub const WARN_REDIRECT_DETECTED: Code<Navigation, Primary> =
    Code::warning(Navigation, Primary::Redirect, 1);

// ============================================================================
// Component Registration
// ============================================================================

#[cfg(feature = "doc-gen")]
pub fn register_component(generator: &mut waddling_errors::doc_generator::DocRegistry) {
    use waddling_errors::Role;

    generator.register_component(
        "Navigation",
        Some("Navigation and routing system. Handles URL routing, page resolution, deep linking, breadcrumbs, and navigation state management. Designed with user experience in mind - even errors become learning opportunities!"),
        &[
            "URL routing and pattern matching",
            "Page resolution and 404 handling",
            "Deep linking support",
            "Breadcrumb generation",
            "Navigation state persistence",
            "Redirect chain management",
        ],
        &["routing", "url", "navigation", "user-experience", "404"]);

    // PUBLIC: Example usage for documentation
    generator.register_component_location_with_role(
        "Navigation",
        "examples/complete_system/components/navigation.rs",
        Some(Role::Public),
    );
}

/// Demo navigation errors
pub fn demo() {
    println!("🧭 Navigation Errors:");
    println!("  {} - Page not found (404)", ERR_PAGE_NOT_FOUND);
    println!("  {} - Invalid route pattern", ERR_ROUTE_INVALID);
    println!("  {} - Redirect chain detected", WARN_REDIRECT_DETECTED);
}

#[cfg(feature = "doc-gen")]
pub fn register_errors(generator: &mut waddling_errors::doc_generator::DocRegistry) {
    use waddling_errors::Role;

    // E.Navigation.Page.NOT_FOUND - The classic 404, reimagined! 🦆
    generator
        .register_code_extended(
            &ERR_PAGE_NOT_FOUND,
            "The requested page could not be found",
            &[
                "Double-check the URL for typos",
                "Try using the search function",
                "Navigate from the homepage",
                "Check if the page was recently moved",
            ],
            &["routing", "404", "user-experience", "navigation"],
            Some(Role::Public),
            &["E.Navigation.Route.003", "W.Navigation.Redirect.001"], // related_codes
            None,                                                     // deprecated
            &[],                                                      // see_also
        )
        .expect("Valid code: E.Navigation.Page.021")
        .add_snippet_for_role(
            "Public - Error Page Example",
            "html",
            r#"<div class="error-page">
  <h1>🦆 Page Not Found</h1>
  <p>We couldn't find what you're looking for.</p>
  <a href="/">Go to Homepage</a>
</div>"#
                .to_string(),
            Role::Public,
        );

    // E.Navigation.Route.INVALID
    generator
        .register_code_extended(
            &ERR_ROUTE_INVALID,
            "Invalid route pattern specified",
            &[
                "Remove special characters from URL",
                "Use hyphens instead of spaces",
                "Validate path against route schema",
            ],
            &["routing", "validation", "url"],
            Some(Role::Public),
            &["E.Navigation.Page.021"], // related_codes
            None,                       // deprecated
            &[],                        // see_also
        )
        .expect("Valid code: E.Navigation.Route.003");

    // W.Navigation.Redirect.DETECTED
    generator
        .register_code_extended(
            &WARN_REDIRECT_DETECTED,
            "Redirect chain detected - consider updating links",
            &[
                "Update your bookmark to the current URL",
                "Check for circular redirect potential",
            ],
            &["routing", "seo", "performance"],
            Some(Role::Public),
            &["E.Navigation.Page.021"], // related_codes
            None,                       // deprecated
            &[],                        // see_also
        )
        .expect("Valid code: W.Navigation.Redirect.001");
}