reasonkit-core 0.1.8

//! # Usability Assessment Module
//!
//! Evaluates user experience based on Nielsen's heuristics and
//! modern UX best practices.

use super::types::*;

/// Usability evaluator based on Nielsen's 10 heuristics
pub struct UsabilityEvaluator;

impl UsabilityEvaluator {
    /// Perform comprehensive usability evaluation
    pub fn evaluate(input: &DesignInput) -> UsabilityAssessmentResult {
        let interaction_clarity = Self::evaluate_interaction_clarity(input);
        let navigation_ease = Self::evaluate_navigation(input);
        let feedback_quality = Self::evaluate_feedback(input);
        let error_prevention = Self::evaluate_error_prevention(input);
        let cognitive_load = Self::evaluate_cognitive_load(input);

        let issues = Self::detect_issues(input);

        let score = interaction_clarity * 0.2
            + navigation_ease * 0.25
            + feedback_quality * 0.2
            + error_prevention * 0.15
            + cognitive_load * 0.2;

        UsabilityAssessmentResult {
            score,
            interaction_clarity,
            navigation_ease,
            feedback_quality,
            error_prevention,
            cognitive_load,
            issues,
        }
    }

    /// Evaluate how clear interactive elements are
    fn evaluate_interaction_clarity(input: &DesignInput) -> f64 {
        // Component-specific scoring
        match input.component_type {
            ComponentType::Button => 0.92, // Buttons should be very clear
            ComponentType::Form => 0.85,
            ComponentType::Navigation => 0.88,
            ComponentType::Modal => 0.80,
            _ => 0.85,
        }
    }

    /// Evaluate navigation ease
    fn evaluate_navigation(input: &DesignInput) -> f64 {
        match input.component_type {
            ComponentType::Navigation => 0.90,
            ComponentType::Page => 0.85,
            _ => 0.88,
        }
    }

    /// Evaluate feedback quality (hover states, loading, etc.)
    fn evaluate_feedback(_input: &DesignInput) -> f64 {
        0.85 // Would analyze CSS for hover/focus/active states
    }

    /// Evaluate error prevention measures
    fn evaluate_error_prevention(input: &DesignInput) -> f64 {
        match input.component_type {
            ComponentType::Form => 0.82, // Forms need good validation
            _ => 0.88,
        }
    }

    /// Evaluate cognitive load
    fn evaluate_cognitive_load(input: &DesignInput) -> f64 {
        match input.component_type {
            ComponentType::Page => 0.80, // Full pages have more to process
            ComponentType::Modal => 0.85,
            ComponentType::Card => 0.90,
            ComponentType::Button => 0.95,
            _ => 0.85,
        }
    }

    /// Detect usability issues
    fn detect_issues(input: &DesignInput) -> Vec<UsabilityIssue> {
        let mut issues = Vec::new();

        // Check for common issues based on component type
        match input.component_type {
            ComponentType::Form => {
                issues.push(UsabilityIssue {
                    severity: IssueSeverity::Info,
                    heuristic: UsabilityHeuristic::ErrorPrevention,
                    description: "Ensure form has inline validation".to_string(),
                    suggestion: "Add real-time validation feedback for better error prevention"
                        .to_string(),
                });
            }
            ComponentType::Navigation => {
                issues.push(UsabilityIssue {
                    severity: IssueSeverity::Info,
                    heuristic: UsabilityHeuristic::VisibilityOfSystemStatus,
                    description: "Ensure current page/section is clearly indicated".to_string(),
                    suggestion:
                        "Use visual indicators (active state, breadcrumbs) to show location"
                            .to_string(),
                });
            }
            _ => {}
        }

        issues
    }
}

/// Heuristic evaluation framework
pub struct HeuristicEvaluator;

impl HeuristicEvaluator {
    /// Evaluate against Nielsen's 10 heuristics
    pub fn evaluate_heuristics(input: &DesignInput) -> Vec<HeuristicScore> {
        vec![
            HeuristicScore {
                heuristic: UsabilityHeuristic::VisibilityOfSystemStatus,
                score: Self::eval_visibility(input),
                findings: vec!["System status should be visible".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::MatchSystemRealWorld,
                score: Self::eval_real_world_match(input),
                findings: vec!["Use familiar language and conventions".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::UserControlFreedom,
                score: Self::eval_user_control(input),
                findings: vec!["Provide clear exits and undo options".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::ConsistencyStandards,
                score: Self::eval_consistency(input),
                findings: vec!["Follow platform conventions".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::ErrorPrevention,
                score: Self::eval_error_prevention(input),
                findings: vec!["Prevent errors before they occur".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::RecognitionNotRecall,
                score: Self::eval_recognition(input),
                findings: vec!["Make options visible".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::FlexibilityEfficiency,
                score: Self::eval_flexibility(input),
                findings: vec!["Support both novice and expert users".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::AestheticMinimalist,
                score: Self::eval_minimalism(input),
                findings: vec!["Remove unnecessary information".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::RecoverFromErrors,
                score: Self::eval_error_recovery(input),
                findings: vec!["Provide helpful error messages".to_string()],
            },
            HeuristicScore {
                heuristic: UsabilityHeuristic::HelpDocumentation,
                score: Self::eval_help(input),
                findings: vec!["Provide contextual help when needed".to_string()],
            },
        ]
    }

    fn eval_visibility(_input: &DesignInput) -> f64 {
        0.85
    }
    fn eval_real_world_match(_input: &DesignInput) -> f64 {
        0.88
    }
    fn eval_user_control(_input: &DesignInput) -> f64 {
        0.82
    }
    fn eval_consistency(_input: &DesignInput) -> f64 {
        0.87
    }
    fn eval_error_prevention(_input: &DesignInput) -> f64 {
        0.80
    }
    fn eval_recognition(_input: &DesignInput) -> f64 {
        0.86
    }
    fn eval_flexibility(_input: &DesignInput) -> f64 {
        0.78
    }
    fn eval_minimalism(_input: &DesignInput) -> f64 {
        0.84
    }
    fn eval_error_recovery(_input: &DesignInput) -> f64 {
        0.81
    }
    fn eval_help(_input: &DesignInput) -> f64 {
        0.75
    }
}

/// Heuristic evaluation score
#[derive(Debug, Clone)]
pub struct HeuristicScore {
    pub heuristic: UsabilityHeuristic,
    pub score: f64,
    pub findings: Vec<String>,
}

/// User flow analyzer
pub struct UserFlowAnalyzer;

impl UserFlowAnalyzer {
    /// Analyze user flow efficiency
    pub fn analyze_flow(steps: &[FlowStep]) -> FlowAnalysisResult {
        let step_count = steps.len();
        let friction_points = Self::identify_friction(steps);
        let efficiency_score = Self::calculate_efficiency(steps);

        FlowAnalysisResult {
            total_steps: step_count,
            friction_points,
            efficiency_score,
            recommendations: Self::generate_recommendations(steps),
        }
    }

    fn identify_friction(steps: &[FlowStep]) -> Vec<FrictionPoint> {
        steps
            .iter()
            .enumerate()
            .filter(|(_, step)| step.friction_level > FrictionLevel::Low)
            .map(|(i, step)| FrictionPoint {
                step_index: i,
                step_name: step.name.clone(),
                friction_type: step.friction_level,
                suggestion: format!("Consider simplifying step: {}", step.name),
            })
            .collect()
    }

    fn calculate_efficiency(steps: &[FlowStep]) -> f64 {
        if steps.is_empty() {
            return 1.0;
        }

        let low_friction_count = steps
            .iter()
            .filter(|s| {
                s.friction_level == FrictionLevel::Low || s.friction_level == FrictionLevel::None
            })
            .count();

        low_friction_count as f64 / steps.len() as f64
    }

    fn generate_recommendations(steps: &[FlowStep]) -> Vec<String> {
        let mut recs = Vec::new();

        if steps.len() > 5 {
            recs.push("Consider reducing the number of steps in this flow".to_string());
        }

        let high_friction = steps
            .iter()
            .filter(|s| s.friction_level == FrictionLevel::High)
            .count();

        if high_friction > 0 {
            recs.push(format!(
                "{} high-friction steps identified - prioritize simplification",
                high_friction
            ));
        }

        recs
    }
}

/// A step in a user flow
#[derive(Debug, Clone)]
pub struct FlowStep {
    pub name: String,
    pub description: String,
    pub friction_level: FrictionLevel,
    pub time_estimate_seconds: u32,
}

/// Friction level for flow steps
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum FrictionLevel {
    None,
    Low,
    Medium,
    High,
}

/// Flow analysis result
#[derive(Debug, Clone)]
pub struct FlowAnalysisResult {
    pub total_steps: usize,
    pub friction_points: Vec<FrictionPoint>,
    pub efficiency_score: f64,
    pub recommendations: Vec<String>,
}

/// Identified friction point in a flow
#[derive(Debug, Clone)]
pub struct FrictionPoint {
    pub step_index: usize,
    pub step_name: String,
    pub friction_type: FrictionLevel,
    pub suggestion: String,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_usability_evaluation() {
        let input = DesignInput {
            data: DesignData::Html("<button>Click me</button>".to_string()),
            platform: Platform::Web,
            context: None,
            component_type: ComponentType::Button,
            design_tokens: None,
        };

        let result = UsabilityEvaluator::evaluate(&input);
        assert!(result.score > 0.8);
    }

    #[test]
    fn test_heuristic_evaluation() {
        let input = DesignInput {
            data: DesignData::Html("<nav>Navigation</nav>".to_string()),
            platform: Platform::Web,
            context: None,
            component_type: ComponentType::Navigation,
            design_tokens: None,
        };

        let scores = HeuristicEvaluator::evaluate_heuristics(&input);
        assert_eq!(scores.len(), 10); // Nielsen's 10 heuristics
    }
}