leptos-shadcn-ui/docs/architecture/signal-management-api.md

Signal Management API Documentation

Overview

The leptos-shadcn-signal-management crate provides comprehensive utilities for managing Leptos 0.8.8 signals with advanced memory management, performance optimization, and component migration capabilities.

Core Modules

1. Signal Lifecycle Management (lifecycle)

TailwindSignalManager

Central manager for Tailwind CSS signal lifecycle management.

use leptos_shadcn_signal_management::TailwindSignalManager;

let manager = TailwindSignalManager::new();

Key Methods:

• theme() -> ArcRwSignal<Theme> - Get theme signal (Light/Dark)
• variant() -> ArcRwSignal<Variant> - Get variant signal (Primary/Secondary/Destructive)
• size() -> ArcRwSignal<Size> - Get size signal (Small/Medium/Large)
• responsive() -> ArcRwSignal<ResponsiveConfig> - Get responsive configuration
• track_signal<T>(signal: ArcRwSignal<T>) - Track signal for lifecycle management
• track_memo<T>(memo: ArcMemo<T>) - Track memo for lifecycle management
• tracked_signals_count() -> usize - Get count of tracked signals
• tracked_memos_count() -> usize - Get count of tracked memos
• apply_lifecycle_optimization() - Apply lifecycle optimizations

Example Usage:

let manager = TailwindSignalManager::new();

// Track signals for lifecycle management
let button_state = ArcRwSignal::new(ButtonState::default());
manager.track_signal(button_state.clone());

// Track computed values
let button_class = ArcMemo::new(move |_| {
    format!("btn btn-{}", button_state.get().variant)
});
manager.track_memo(button_class);

// Apply optimizations
manager.apply_lifecycle_optimization();

SignalCleanup

Automatic cleanup utilities for signal lifecycle management.

use leptos_shadcn_signal_management::SignalCleanup;

let cleanup = SignalCleanup::new();
cleanup.cleanup_signals(&signals);

2. Memory Management (memory_management)

SignalMemoryManager

Advanced memory management for signal collections.

use leptos_shadcn_signal_management::SignalMemoryManager;

let manager = SignalMemoryManager::new();

Key Methods:

• get_stats() -> ArcRwSignal<MemoryStats> - Get memory statistics
• detect_memory_pressure() -> Option<MemoryPressureLevel> - Detect memory pressure
• perform_automatic_cleanup() -> bool - Perform automatic cleanup
• predict_memory_usage(signal_count: usize, memo_count: usize) -> usize - Predict memory usage
• collect_performance_metrics() -> HashMap<String, f64> - Collect performance metrics
• deduplicate_signals<T>(signals: Vec<ArcRwSignal<T>>) -> Vec<ArcRwSignal<T>> - Deduplicate signals
• analyze_memory_fragmentation() -> f64 - Analyze memory fragmentation
• enable_adaptive_management() - Enable adaptive memory management

Example Usage:

let manager = SignalMemoryManager::new();

// Monitor memory pressure
if let Some(pressure) = manager.detect_memory_pressure() {
    if pressure > MemoryPressureLevel::High {
        manager.perform_automatic_cleanup();
    }
}

// Predict memory usage
let predicted_usage = manager.predict_memory_usage(1000, 500);
println!("Predicted memory usage: {} bytes", predicted_usage);

// Collect performance metrics
let metrics = manager.collect_performance_metrics();
println!("Signal creation time: {:?}", metrics.get("signal_creation_time"));

SignalGroup

Group signals for organized memory management.

use leptos_shadcn_signal_management::SignalGroup;

let group = SignalGroup::new("button_group".to_string());

MemoryLeakDetector

Detect and prevent memory leaks.

use leptos_shadcn_signal_management::MemoryLeakDetector;

let detector = MemoryLeakDetector::new();
detector.enable_leak_prevention();

3. Batched Updates (batched_updates)

BatchedSignalUpdater

Efficient batched signal updates for better performance.

use leptos_shadcn_signal_management::BatchedSignalUpdater;

let updater = BatchedSignalUpdater::new();

Key Methods:

• max_batch_size() -> usize - Get maximum batch size
• auto_tune_batch_size() - Auto-tune batch size for optimal performance

BatchedUpdaterManager

Manage multiple batched updaters.

use leptos_shadcn_signal_management::BatchedUpdaterManager;

let manager = BatchedUpdaterManager::new();
manager.add_updater(updater);

4. Component Migration (component_migration)

ComponentMigrator

Migrate existing components to new signal patterns.

use leptos_shadcn_signal_management::ComponentMigrator;

let migrator = ComponentMigrator::new();

Key Methods:

• mark_migrated(component_name: &str) - Mark component as migrated
• is_migrated(component_name: &str) -> bool - Check if component is migrated
• status() -> ArcRwSignal<MigrationStatus> - Get migration status
• progress_percentage() -> f64 - Get migration progress percentage

Example Usage:

let migrator = ComponentMigrator::new();

// Mark components as migrated
migrator.mark_migrated("button");
migrator.mark_migrated("input");

// Check migration status
let status = migrator.status().get();
println!("Migrated: {}, Failed: {}", status.migrated_count, status.failed_count);

// Get progress
let progress = migrator.progress_percentage();
println!("Migration progress: {:.1}%", progress);

Migration Helper Functions

• create_migrated_button_component() -> Option<()> - Create migrated button component
• create_migrated_input_component() -> Option<()> - Create migrated input component
• create_migrated_card_component() -> Option<()> - Create migrated card component
• validate_all_component_migrations() -> MigrationStatus - Validate all migrations

Data Types

Enums

Theme

pub enum Theme {
    Light,
    Dark,
}

Variant

pub enum Variant {
    Primary,
    Secondary,
    Destructive,
    Outline,
    Ghost,
    Link,
}

Size

pub enum Size {
    Small,
    Medium,
    Large,
}

MemoryPressureLevel

pub enum MemoryPressureLevel {
    Low,
    Medium,
    High,
    Critical,
}

Structs

ResponsiveConfig

pub struct ResponsiveConfig {
    pub sm: Option<String>,
    pub md: Option<String>,
    pub lg: Option<String>,
    pub xl: Option<String>,
}

MemoryStats

pub struct MemoryStats {
    pub total_signals: usize,
    pub total_memos: usize,
    pub memory_usage: usize,
    pub peak_memory_usage: usize,
    pub signal_creation_time: f64,
    pub memo_creation_time: f64,
}

MigrationStatus

pub struct MigrationStatus {
    pub all_migrated: bool,
    pub migrated_count: usize,
    pub failed_count: usize,
}

Performance Considerations

Signal Creation Performance

• ArcRwSignal: ~226ns (very fast)
• ArcMemo: ~336ns (fast)
• Regular Signal: ~294ns (fast)

Signal Access Performance

• ArcRwSignal get/set: ~70ns (extremely fast)
• ArcMemo access: ~187ns (fast)
• Regular Signal access: ~120ns (fast)

Memory Management

• Automatic cleanup when memory pressure is detected
• Signal deduplication to reduce memory usage
• Adaptive memory management for optimal performance

Best Practices

1. Signal Lifecycle Management

// Always track signals for lifecycle management
let manager = TailwindSignalManager::new();
manager.track_signal(my_signal);

// Apply lifecycle optimizations
manager.apply_lifecycle_optimization();

2. Memory Management

// Monitor memory pressure
let manager = SignalMemoryManager::new();
if let Some(pressure) = manager.detect_memory_pressure() {
    if pressure > MemoryPressureLevel::High {
        manager.perform_automatic_cleanup();
    }
}

3. Component Migration

// Use migration utilities for systematic migration
let migrator = ComponentMigrator::new();
migrator.mark_migrated("component_name");

// Validate migration progress
let status = validate_all_component_migrations();

4. Performance Optimization

// Use batched updates for better performance
let updater = BatchedSignalUpdater::new();
updater.auto_tune_batch_size();

Error Handling

The crate uses SignalManagementError for error handling:

pub enum SignalManagementError {
    MemoryLimitExceeded,
    InvalidSignal,
    MigrationFailed,
    CleanupFailed,
}

Testing

The crate includes comprehensive tests:

• 42 total tests covering all functionality
• Performance benchmarks with criterion
• cargo nextest integration for fast testing
• WASM-specific tests for browser environments

Dependencies

• leptos = "0.8" - Core Leptos framework
• serde = "1.0" - Serialization support
• chrono = "0.4" - Date/time handling
• js-sys = "0.3" - WASM bindings
• criterion = "0.5" - Performance benchmarking
• wasm-bindgen-test = "0.3" - WASM testing