Validation UI Component

Validation UI Component

A comprehensive, color-coded UI component for displaying validation errors from AGTree-parsed filter rules.

Features

✨ Color-Coded Error Types - Each error type has a unique color scheme for instant recognition 🎨 Syntax Highlighting - Filter rules are syntax-highlighted based on their type 🌳 AST Visualization - Interactive AST tree view with color-coded node types 🔍 Error Filtering - Filter by severity (All, Errors, Warnings) 📊 Summary Statistics - Visual cards showing validation metrics 📥 Export Capability - Download validation reports as JSON 🌙 Dark Mode - Full support for light and dark themes 📱 Responsive Design - Works on all screen sizes

Quick Start

Include the Script

<script src="validation-ui.js"></script>

Display a Validation Report

const report = {
    totalRules: 1000,
    validRules: 950,
    invalidRules: 50,
    errorCount: 45,
    warningCount: 5,
    infoCount: 0,
    errors: [
        {
            type: 'unsupported_modifier',
            severity: 'error',
            ruleText: '||example.com^$popup',
            message: 'Unsupported modifier: popup',
            details: 'Supported modifiers: important, ~important, ctag...',
            lineNumber: 42,
            sourceName: 'Custom Filter'
        }
    ]
};

ValidationUI.showReport(report);

Color Coding Guide

Error Types

Error Type	Color	Hex Code
Parse Error	Red	#dc3545
Syntax Error	Red	#dc3545
Unsupported Modifier	Orange	#fd7e14
Invalid Hostname	Pink	#e83e8c
IP Not Allowed	Purple	#6610f2
Pattern Too Short	Yellow	#ffc107
Public Suffix Match	Light Red	#ff6b6b
Invalid Characters	Magenta	#d63384
Cosmetic Not Supported	Cyan	#0dcaf0

AST Node Types

Node Type	Color	Hex Code
Network Category	Blue	#0d6efd
Network Rule	Light Blue	#0dcaf0
Host Rule	Purple	#6610f2
Cosmetic Rule	Pink	#d63384
Modifier	Orange	#fd7e14
Comment	Gray	#6c757d
Invalid Rule	Red	#dc3545

Syntax Highlighting

Rules are automatically syntax-highlighted:

Network Rules

flowchart LR
    separators["||<br/>Separators (gray)"] --> domain["example.com<br/>Domain (blue)"] --> terminator["^<br/>Separator (gray)"] --> modifiers["$third-party<br/>Modifiers (orange)"]

Exception Rules

flowchart LR
    exception["@@<br/>Exception marker (green)"] --> pattern["||example.com^<br/>Pattern (blue)"]

Host Rules

flowchart LR
    ip["0.0.0.0<br/>IP address (purple)"] --> domain["example.com<br/>Domain (blue)"]

API Reference

ValidationUI.showReport(report)

Display a validation report.

Parameters:

• report (ValidationReport) - The validation report to display

Example:

ValidationUI.showReport({
    totalRules: 100,
    validRules: 95,
    invalidRules: 5,
    errorCount: 4,
    warningCount: 1,
    infoCount: 0,
    errors: [...]
});

ValidationUI.hideReport()

Hide the validation report section.

Example:

ValidationUI.hideReport();

ValidationUI.renderReport(report, container)

Render a validation report in a specific container element.

Parameters:

• report (ValidationReport) - The validation report
• container (HTMLElement) - Container element to render in

Example:

const container = document.getElementById('my-container');
ValidationUI.renderReport(report, container);

ValidationUI.downloadReport()

Download the current validation report as JSON.

Example:

// Add a button to trigger download
button.addEventListener('click', () => {
    ValidationUI.downloadReport();
});

Data Structures

ValidationReport

interface ValidationReport {
    errorCount: number;
    warningCount: number;
    infoCount: number;
    errors: ValidationError[];
    totalRules: number;
    validRules: number;
    invalidRules: number;
}

ValidationError

interface ValidationError {
    type: ValidationErrorType;
    severity: ValidationSeverity;
    ruleText: string;
    lineNumber?: number;
    message: string;
    details?: string;
    ast?: AnyRule;
    sourceName?: string;
}

ValidationErrorType

enum ValidationErrorType {
    parse_error = 'parse_error',
    syntax_error = 'syntax_error',
    unsupported_modifier = 'unsupported_modifier',
    invalid_hostname = 'invalid_hostname',
    ip_not_allowed = 'ip_not_allowed',
    pattern_too_short = 'pattern_too_short',
    public_suffix_match = 'public_suffix_match',
    invalid_characters = 'invalid_characters',
    cosmetic_not_supported = 'cosmetic_not_supported',
    modifier_validation_failed = 'modifier_validation_failed',
}

ValidationSeverity

enum ValidationSeverity {
    error = 'error',
    warning = 'warning',
    info = 'info',
}

Visual Examples

Summary Cards

The UI displays summary statistics in color-coded cards:

flowchart LR
    total["Total Rules<br/>1000<br/>(purple)"] --> valid["Valid Rules<br/>950<br/>(green)"] --> invalid["Invalid Rules<br/>50<br/>(red)"]

Error List Item

Each error is displayed with:

flowchart TD
    header["[ERROR] Unsupported Modifier (Line 42) [Custom Filter]"] --> detail["Unsupported modifier: popup"]
    detail --> supported["Supported modifiers: important, ctag, dnstype..."]
    supported --> rule["||example.com^$popup<br/>Domain and modifier highlighted in red"]
    rule --> action["Show AST"]

AST Visualization

Expandable AST tree with color-coded nodes:

flowchart TD
    rule["NetworkRule<br/>(light blue badge)"] --> pattern["pattern: ||example.com^<br/>(blue text)"]
    rule --> exception["exception: false<br/>(red text)"]
    rule --> modifiers["ModifierList<br/>(orange badge)"]
    modifiers --> modifier["Modifier[0]<br/>(orange badge)"]
    modifier --> name["name: popup<br/>(blue text)"]

Integration with Compiler

To integrate with the bloqr-backend:

// In your compilation workflow
const validator = new ValidateTransformation(false);
validator.setSourceName('My Filter List');

const validRules = validator.executeSync(rules);
const report = validator.getValidationReport(
    rules.length,
    validRules.length
);

// Display in UI
ValidationUI.showReport(report);

Demo Page

A demo page is included (validation-demo.html) that shows:

• Color legend for error types
• Color legend for AST node types
• Sample validation reports
• Dark mode toggle
• Interactive examples

To view:

1. Open validation-demo.html in a browser
2. Click “Load Sample Report” to see examples
3. Toggle dark mode to see theme adaptation
4. Click on AST buttons to explore parsed structures

Browser Compatibility

• Chrome/Edge: ✅ Full support
• Firefox: ✅ Full support
• Safari: ✅ Full support
• Mobile browsers: ✅ Responsive design

Styling

The component uses CSS custom properties for theming:

:root {
    --alert-error-bg: #f8d7da;
    --alert-error-text: #721c24;
    --alert-error-border: #dc3545;
    --log-warn-bg: #fff3cd;
    --log-warn-text: #856404;
    --log-warn-border: #ffc107;
    /* ... etc */
}

Override these in your stylesheet to customize colors.

Contributing

When adding new error types:

1. Add the error type to ValidationErrorType enum
2. Add color scheme in getErrorTypeColor() method
3. Add syntax highlighting logic in highlightRule() if needed
4. Update documentation and demo

License

Part of the bloqr-backend project. See main project LICENSE.