leptos-shadcn-ui/docs/remediation/api-standardization.md

🔧 API Standardization Plan

Priority: 🔴 CRITICAL
Timeline: Week 1-2
Impact: Ensures consistent, type-safe APIs across all components

🚨 Current API Inconsistencies

Type System Issues

// Inconsistent prop types across components:
<Button variant="primary"/>           // Some components use &str
<Input placeholder="Enter text"/>     // Others use MaybeProp<String>

// Inconsistent callback patterns:
on_click=Some(callback)               // Some use Option<Callback<T>>
on_change=callback                    // Others use Callback<T> directly

Signal Management Inconsistencies

// Mixed signal creation patterns:
let (value, set_value) = create_signal(initial);  // Deprecated
let (value, set_value) = signal(initial);         // Current

🎯 Standardization Strategy

Phase 1: Prop Type Standardization

1.1 Standardize String Props

// Standard pattern for all string props:
#[component]
pub fn ComponentName(
    #[prop(into, optional)] placeholder: MaybeProp<String>,
    #[prop(into, optional)] label: MaybeProp<String>,
    #[prop(into, optional)] class: MaybeProp<String>,
) -> impl IntoView {
    // Implementation
}

// Usage with helper macros:
<ComponentName 
    placeholder=prop_string!("Enter text")
    label=prop_string!("Label")
    class=prop_string!("custom-class")
/>

1.2 Standardize Boolean Props

// Standard pattern for all boolean props:
#[component]
pub fn ComponentName(
    #[prop(into, optional)] disabled: MaybeProp<bool>,
    #[prop(into, optional)] required: MaybeProp<bool>,
    #[prop(into, optional)] checked: MaybeProp<bool>,
) -> impl IntoView {
    // Implementation
}

// Usage with helper macros:
<ComponentName 
    disabled=prop_bool!(false)
    required=prop_bool!(true)
    checked=prop_bool!(false)
/>

1.3 Standardize Numeric Props

// Standard pattern for all numeric props:
#[component]
pub fn ComponentName(
    #[prop(into, optional)] min: MaybeProp<i32>,
    #[prop(into, optional)] max: MaybeProp<i32>,
    #[prop(into, optional)] step: MaybeProp<f64>,
) -> impl IntoView {
    // Implementation
}

// Usage:
<ComponentName 
    min=prop_number!(0)
    max=prop_number!(100)
    step=prop_number!(1.0)
/>

Phase 2: Callback Standardization

2.1 Standardize Callback Patterns

// Standard pattern for all callbacks:
#[component]
pub fn ComponentName(
    #[prop(optional)] on_click: Option<Callback<()>>,
    #[prop(optional)] on_change: Option<Callback<String>>,
    #[prop(optional)] on_submit: Option<Callback<FormData>>,
) -> impl IntoView {
    // Implementation
}

// Usage:
<ComponentName 
    on_click=Some(callback)
    on_change=Some(change_callback)
    on_submit=Some(submit_callback)
/>

2.2 Create Callback Helper Macros

// Helper macros for common callback patterns:
#[macro_export]
macro_rules! callback {
    ($closure:expr) => {
        Some(Callback::new($closure))
    };
}

// Usage:
<ComponentName 
    on_click=callback!(|_| println!("Clicked"))
    on_change=callback!(|value| println!("Changed: {}", value))
/>

Phase 3: Signal Management Standardization

3.1 Standardize Signal Creation

// Standard pattern for all signal creation:
use leptos::prelude::*;

// Always use signal() instead of create_signal():
let (value, set_value) = signal(initial_value);
let (is_loading, set_is_loading) = signal(false);
let (items, set_items) = signal(Vec::<String>::new());

3.2 Create Signal Helper Functions

// Helper functions for common signal patterns:
pub fn create_string_signal(initial: &str) -> (Signal<String>, WriteSignal<String>) {
    signal(initial.to_string())
}

pub fn create_bool_signal(initial: bool) -> (Signal<bool>, WriteSignal<bool>) {
    signal(initial)
}

pub fn create_vec_signal<T>(initial: Vec<T>) -> (Signal<Vec<T>>, WriteSignal<Vec<T>>)
where
    T: Clone + 'static,
{
    signal(initial)
}

📋 Implementation Checklist

Week 1: Core Standardization

Day 1-2: Prop Type Standardization

• Create prop helper macros (prop_string!, prop_bool!, prop_number!)
• Update all component prop definitions
• Standardize string prop usage across components
• Test prop type consistency

Day 3-4: Callback Standardization

• Create callback helper macros
• Standardize callback patterns across components
• Update all callback prop definitions
• Test callback consistency

Day 5: Signal Management

• Replace all create_signal with signal()
• Create signal helper functions
• Update all signal creation patterns
• Test signal management consistency

Week 2: Component Updates

Day 6-7: Core Components

• Update button component API
• Update input component API
• Update card component API
• Test core component consistency

Day 8-9: Form Components

• Update form component API
• Update select component API
• Update checkbox component API
• Test form component consistency

Day 10: Advanced Components

• Update dialog component API
• Update popover component API
• Update tooltip component API
• Test advanced component consistency

🧪 Testing Strategy

API Consistency Tests

#[cfg(test)]
mod api_consistency_tests {
    use super::*;
    
    #[test]
    fn test_prop_type_consistency() {
        // Test that all components use consistent prop types
        // Verify MaybeProp<T> usage for optional props
        // Check string literal conversion
    }
    
    #[test]
    fn test_callback_consistency() {
        // Test that all components use consistent callback patterns
        // Verify Option<Callback<T>> usage
        // Check callback creation patterns
    }
    
    #[test]
    fn test_signal_consistency() {
        // Test that all components use signal() instead of create_signal()
        // Verify signal creation patterns
        // Check signal management consistency
    }
}

Integration Tests

#[test]
fn test_component_api_integration() {
    // Test that components work together with standardized APIs
    // Verify prop passing between components
    // Check callback communication
}

📊 Success Criteria

• ✅ Consistent prop types across all components
• ✅ Standardized callback patterns throughout codebase
• ✅ Unified signal management using signal() only
• ✅ Helper macros for common patterns
• ✅ Comprehensive test coverage for API consistency

🚨 Risk Mitigation

Backward Compatibility

• Maintain existing component functionality
• Provide migration guide for API changes
• Test all existing usage patterns

Type Safety

• Ensure all prop types are properly validated
• Test type conversion edge cases
• Verify compile-time type checking

Performance

• Ensure helper macros don't impact performance
• Test signal management efficiency
• Verify callback performance

📁 Related Documents

• Build System Remediation - Fix compilation issues
• Command Component Fix - Example implementation
• Component API Guidelines - Detailed API standards

---

Next Steps: After completing API standardization, proceed to Stub Implementation Plan for completing todo! items.