HyperChad Renderer

Core rendering abstractions and traits for HyperChad UI frameworks.

Overview

The HyperChad Renderer package provides:

• Renderer Traits: Abstract interfaces for different rendering backends
• Content Types: Structured content representation (View, PartialView, JSON)
• Event System: Renderer event handling and processing
• HTML Generation: HTML tag rendering and CSS generation
• Asset Management: Optional static asset handling
• Canvas Support: Optional canvas rendering capabilities

Features

Core Abstractions

• Renderer Trait: Main rendering interface for backends
• RenderRunner: Application execution and lifecycle management
• ToRenderRunner: Conversion trait for renderer instances
• HtmlTagRenderer: HTML-specific rendering capabilities

Content System

• View: Full page view with immediate and future content
• PartialView: Targeted partial content updates
• Content Enum: Unified content representation
• JSON Support: Optional JSON content handling

Event Handling

• RendererEvent: Event types for renderer communication
• Custom Events: User-defined event processing
• Canvas Events: Optional canvas update events
• Async Events: Async event emission and handling

HTML Rendering

• Tag Generation: HTML element and attribute generation
• CSS Media Queries: Responsive CSS generation
• Root HTML: Complete HTML document generation
• Partial HTML: Fragment HTML generation

Installation

Add this to your Cargo.toml:

[dependencies]
hyperchad_renderer = { path = "../hyperchad/renderer" }

# Enable additional features
hyperchad_renderer = {
    path = "../hyperchad/renderer",
    features = ["json", "canvas", "assets", "viewport"]
}

Usage

Implementing a Renderer

use hyperchad_renderer::{Renderer, View, PartialView, Color, Handle};
use async_trait::async_trait;

struct MyRenderer {
    // Renderer state
}

#[async_trait]
impl Renderer for MyRenderer {
    async fn init(
        &mut self,
        width: f32,
        height: f32,
        x: Option<i32>,
        y: Option<i32>,
        background: Option<Color>,
        title: Option<&str>,
        description: Option<&str>,
        viewport: Option<&str>,
    ) -> Result<(), Box<dyn std::error::Error + Send + 'static>> {
        // Initialize renderer with window properties
        Ok(())
    }

    async fn render(&self, view: View) -> Result<(), Box<dyn std::error::Error + Send + 'static>> {
        // Render full view
        Ok(())
    }

    async fn render_partial(&self, partial: PartialView) -> Result<(), Box<dyn std::error::Error + Send + 'static>> {
        // Render partial content update
        Ok(())
    }

    async fn emit_event(&self, event_name: String, event_value: Option<String>) -> Result<(), Box<dyn std::error::Error + Send + 'static>> {
        // Handle event emission
        Ok(())
    }

    fn add_responsive_trigger(&mut self, name: String, trigger: ResponsiveTrigger) {
        // Add responsive breakpoint trigger
    }
}

Content Creation

use hyperchad_renderer::{Content, View, PartialView};
use hyperchad_transformer::Container;

// Create view content
let view_content = Content::view(View {
    future: None,
    immediate: Container::default(),
});

// Create partial view content
let partial_content = Content::partial_view(
    "#content",
    Container::default()
);

// From string (with HTML parsing)
let string_content: Content = "<div>Hello World</div>".try_into()?;

// From container
let container_content = Content::from(Container::default());

HTML Tag Renderer

use hyperchad_renderer::{HtmlTagRenderer, Color};
use hyperchad_transformer::{Container, ResponsiveTrigger};
use std::collections::HashMap;

struct MyHtmlRenderer {
    responsive_triggers: HashMap<String, ResponsiveTrigger>,
}

impl HtmlTagRenderer for MyHtmlRenderer {
    fn add_responsive_trigger(&mut self, name: String, trigger: ResponsiveTrigger) {
        self.responsive_triggers.insert(name, trigger);
    }

    fn element_attrs_to_html(
        &self,
        f: &mut dyn std::io::Write,
        container: &Container,
        is_flex_child: bool,
    ) -> Result<(), std::io::Error> {
        // Generate HTML attributes for container
        Ok(())
    }

    fn root_html(
        &self,
        headers: &HashMap<String, String>,
        container: &Container,
        content: String,
        viewport: Option<&str>,
        background: Option<Color>,
        title: Option<&str>,
        description: Option<&str>,
    ) -> String {
        format!(r#"
<!DOCTYPE html>
<html>
<head>
    <title>{}</title>
    <meta name="description" content="{}">
    <meta name="viewport" content="{}">
</head>
<body style="background-color: {}">
    {}
</body>
</html>
        "#,
            title.unwrap_or("HyperChad App"),
            description.unwrap_or(""),
            viewport.unwrap_or("width=device-width, initial-scale=1"),
            background.map(|c| c.to_string()).unwrap_or_else(|| "white".to_string()),
            content
        )
    }

    fn partial_html(
        &self,
        headers: &HashMap<String, String>,
        container: &Container,
        content: String,
        viewport: Option<&str>,
        background: Option<Color>,
    ) -> String {
        content
    }
}

Event Handling

use hyperchad_renderer::RendererEvent;

// Handle renderer events
match event {
    RendererEvent::View(view) => {
        // Handle full view update
    }
    RendererEvent::Partial(partial) => {
        // Handle partial content update
    }
    RendererEvent::Event { name, value } => {
        // Handle custom event
        println!("Event: {} = {:?}", name, value);
    }
    #[cfg(feature = "canvas")]
    RendererEvent::CanvasUpdate(update) => {
        // Handle canvas update
    }
}

Canvas Support (with canvas feature)

#[cfg(feature = "canvas")]
use hyperchad_renderer::canvas::CanvasUpdate;

#[cfg(feature = "canvas")]
#[async_trait]
impl Renderer for MyRenderer {
    async fn render_canvas(&self, update: CanvasUpdate) -> Result<(), Box<dyn std::error::Error + Send + 'static>> {
        // Handle canvas rendering
        Ok(())
    }
}

Asset Management (with assets feature)

#[cfg(feature = "assets")]
use hyperchad_renderer::assets::StaticAssetRoute;

#[cfg(feature = "assets")]
{
    let asset_route = StaticAssetRoute {
        route: "/static/style.css".to_string(),
        content_type: "text/css".to_string(),
        content: "body { margin: 0; }".to_string(),
    };
}

Content Types

View

• immediate: Content available immediately
• future: Content that will be available asynchronously
• Container: HyperChad container structure

PartialView

• target: CSS selector for target element
• container: Content to insert/replace

Content Enum

• View: Full page content
• PartialView: Partial content update
• Json: JSON response (with json feature)

Traits

Renderer

Core rendering interface with initialization, rendering, and event handling.

RenderRunner

Application execution interface for running renderer instances.

ToRenderRunner

Conversion trait for creating runner instances from renderers.

HtmlTagRenderer

HTML-specific rendering with CSS generation and document structure.

Feature Flags

• json: Enable JSON content support
• canvas: Enable canvas rendering capabilities
• assets: Enable static asset management
• viewport: Enable viewport utilities

Dependencies

• HyperChad Transformer: UI transformation and container system
• HyperChad Color: Color handling and conversion
• Async Trait: Async trait support
• Switchy Async: Runtime abstraction

Integration

This package is designed for:

• Rendering Backends: Implementation base for different renderers
• UI Frameworks: Core rendering abstractions
• Web Applications: HTML and CSS generation
• Desktop Applications: Native rendering interfaces
• Static Generation: Static site and asset generation