diff --git a/docs/README.md b/docs/README.md index d9d8614..eade700 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,6 +25,13 @@ Component library reference: - [Accessibility Guide](./components/accessibility/) - [Theming Guide](./components/theming/) +### πŸŽ“ [Tutorials](./tutorials/README.md) +Step-by-step video and written tutorials: +- [Getting Started Series](./tutorials/video-tutorials/getting-started/) - Installation, first component, forms, theming +- [Component Series](./tutorials/video-tutorials/components/) - Form components, layouts, navigation +- [Advanced Patterns](./tutorials/video-tutorials/advanced/) - State management, validation, performance +- [Video Production Guide](./tutorials/video-tutorials/production-guide.md) - Create your own tutorials + ### πŸ§ͺ [Testing](./testing/README.md) Comprehensive testing documentation: - [Testing Strategy](./testing/test-strategy.md) @@ -58,8 +65,9 @@ How to contribute to the project: ### For New Users 1. Start with [Getting Started](./getting-started/README.md) -2. Try the [Basic Examples](./getting-started/examples/) -3. Read the [Component API Reference](./components/api-reference/) +2. Watch the [Video Tutorials](./tutorials/README.md) +3. Try the [Basic Examples](./getting-started/examples/) +4. Read the [Component API Reference](./components/api-reference/) ### For Developers 1. Review [Architecture Overview](./architecture/README.md) diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 0000000..741bf9f --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,94 @@ +# Video Tutorials + +Welcome to the leptos-shadcn-ui video tutorial series. These step-by-step video walkthroughs demonstrate common component usage patterns, best practices, and real-world implementation examples. + +## Tutorial Series + +### πŸš€ Getting Started Series +Perfect for developers new to Leptos or shadcn-ui components. + +- [Installation & Setup](video-tutorials/getting-started/01-installation.md) - Set up your development environment +- [Your First Component](video-tutorials/getting-started/02-first-component.md) - Build your first interactive component +- [Basic Form Patterns](video-tutorials/getting-started/03-basic-forms.md) - Create forms with validation +- [Styling & Theming](video-tutorials/getting-started/04-styling-theming.md) - Customize component appearance + +### 🧩 Component Series +Deep dives into specific component categories and patterns. + +- [Form Components](video-tutorials/components/01-form-components.md) - Buttons, Inputs, Labels, and more +- [Layout Components](video-tutorials/components/02-layout-components.md) - Cards, Tabs, Accordions, and grids +- [Navigation Components](video-tutorials/components/03-navigation-components.md) - Menus, Breadcrumbs, Pagination +- [Overlay Components](video-tutorials/components/04-overlay-components.md) - Dialogs, Popovers, Tooltips +- [Data Display Components](video-tutorials/components/05-data-display.md) - Tables, Calendars, Progress indicators + +### 🎯 Advanced Patterns Series +Advanced techniques for building production-ready applications. + +- [State Management](video-tutorials/advanced/01-state-management.md) - Managing complex application state +- [Form Validation](video-tutorials/advanced/02-form-validation.md) - Advanced validation patterns +- [Accessibility Patterns](video-tutorials/advanced/03-accessibility.md) - WCAG compliance techniques +- [Performance Optimization](video-tutorials/advanced/04-performance.md) - Optimizing render performance +- [Testing Strategies](video-tutorials/advanced/05-testing.md) - Testing components effectively + +### πŸ—οΈ Real-World Projects +Complete application walkthroughs. + +- [Building a Dashboard](video-tutorials/advanced/06-dashboard-project.md) - Complete admin dashboard +- [Building a Form-Heavy App](video-tutorials/advanced/07-form-app.md) - Multi-step form wizard +- [Building a Data Table App](video-tutorials/advanced/08-data-table.md) - Sortable, filterable tables + +## How to Use These Tutorials + +### Prerequisites +- Basic knowledge of Rust programming language +- Familiarity with Web fundamentals (HTML, CSS) +- Understanding of reactive programming concepts (helpful but not required) + +### Recommended Learning Path + +1. **Start Here**: Complete the Getting Started Series in order +2. **Build Foundations**: Work through Component Series that match your project needs +3. **Master Advanced**: Explore Advanced Patterns for production techniques +4. **Learn by Example**: Follow Real-World Projects to see everything in action + +### Alongside Video Tutorials + +Each video tutorial includes: +- **Written Transcript**: Full text transcript with timestamps +- **Code Examples**: Complete, runnable code snippets +- **Interactive Exercises**: Hands-on challenges to reinforce learning +- **Related Documentation**: Links to detailed component documentation + +### Practice While Watching + +We recommend: +- Follow along with the code examples in your own project +- Pause the video to experiment with variations +- Complete the suggested exercises before continuing +- Reference the written documentation for deeper understanding + +## Video Resources + +- **Transcripts**: Available in each tutorial folder +- **Source Code**: Complete examples in `/examples/` directory +- **Interactive Demo**: Explore live examples at [comprehensive-demo](../../comprehensive-demo/) +- **Community**: Join discussions in our GitHub Issues + +## Contributing + +Have an idea for a new tutorial? We'd love to hear from you! + +1. Check our [Contributing Guide](../contributing/README.md) +2. Review our [Video Production Guide](video-tutorials/production-guide.md) +3. Submit your tutorial idea via GitHub Issue + +## Additional Learning Resources + +- [Component API Reference](../components/README.md) +- [Getting Started Guide](../getting-started/README.md) +- [Architecture Documentation](../architecture/README.md) +- [Testing Guide](../testing/README.md) + +--- + +**Next**: Start with [Installation & Setup](video-tutorials/getting-started/01-installation.md) diff --git a/docs/tutorials/video-tutorials/advanced/01-state-management.md b/docs/tutorials/video-tutorials/advanced/01-state-management.md new file mode 100644 index 0000000..6c784c2 --- /dev/null +++ b/docs/tutorials/video-tutorials/advanced/01-state-management.md @@ -0,0 +1,758 @@ +# Tutorial: Advanced State Management + +**Video Length**: ~28 minutes | **Difficulty**: Advanced | **Series**: Advanced Patterns + +## Overview + +Learn advanced patterns for managing application state in Leptos with shadcn-ui components. This tutorial covers global state, data fetching, caching, and state synchronization patterns. + +## What You'll Learn + +- Global state management with signals +- Server state integration and caching +- Optimistic UI updates +- State persistence and recovery +- Cross-component state sharing +- Performance optimization techniques + +## Prerequisites + +- Completed Getting Started and Component series +- Strong understanding of signals and reactivity +- Familiarity with async operations + +## Video Outline + +**[0:00]** Introduction to state management +**[2:30]** Local vs. global state patterns +**[6:00]** Building a store system +**[10:00]** Server state and data fetching +**[14:00]** Caching and invalidation strategies +**[17:30]** Optimistic updates +**[20:00]** State persistence +**[23:00]** State synchronization patterns +**[26:00]** Performance considerations +**[27:00]** Summary and resources + +## Global State with Signals + +### Basic Store Pattern + +```rust +use leptos::*; +use std::rc::Rc; + +/// Simple global store using signals +#[derive(Clone)] +pub struct AppState { + pub user: ReadSignal>, + pub set_user: WriteSignal>, + pub theme: ReadSignal, + pub set_theme: WriteSignal, + pub notifications: ReadSignal>, + pub add_notification: WriteSignal, + pub clear_notifications: WriteSignal<()>, +} + +impl AppState { + pub fn new() -> Self { + let (user, set_user) = create_signal(None); + let (theme, set_theme) = create_signal(Theme::Light); + let (notifications, set_notifications) = create_signal(Vec::new()); + + // Auto-clear old notifications + create_effect(move |_| { + let notifs = notifications.get(); + if notifs.len() > 5 { + set_notifications.update(|n| { + n.truncate(5); + }); + } + }); + + AppState { + user, + set_user, + theme, + set_theme, + notifications: notifications.clone(), + add_notification: create_signal_from(notifications, |n, notif| { + n.push(notif); + }), + clear_notifications: create_signal_from(notifications, |n, _| { + n.clear(); + }), + } + } + + pub fn login(&self, email: String, password: String) { + // API call to login + self.set_user.set(Some(User { + id: "1".to_string(), + email, + name: "User".to_string(), + })); + } + + pub fn logout(&self) { + self.set_user.set(None); + } +} + +fn create_signal_from( + signal: ReadSignal, + mut updater: impl FnMut(&mut T, U) + 'static, +) -> WriteSignal { + // Create a write signal that modifies the original signal + // Implementation depends on your leptos version + unimplemented!() +} + +// Type definitions +#[derive(Clone, Debug)] +pub struct User { + pub id: String, + pub email: String, + pub name: String, +} + +#[derive(Clone, Copy, Debug, PartialEq)] +pub enum Theme { + Light, + Dark, + System, +} + +#[derive(Clone, Debug)] +pub struct Notification { + pub id: String, + pub title: String, + pub message: String, + pub variant: NotificationVariant, +} + +#[derive(Clone, Copy, Debug)] +pub enum NotificationVariant { + Info, + Success, + Warning, + Error, +} +``` + +### Context Provider Pattern + +```rust +use leptos::*; +use leptos_shadcn_button::Button; +use leptos_shadcn_card::Card; + +/// Context key for app state +pub static APP_STATE: crate::context::ContextState> = + crate::context::ContextState::new(); + +#[component] +pub fn App() -> impl IntoView { + // Create app state + let state = Rc::new(AppState::new()); + + view! { + // Provide state to all children + + +
+ +
+ + + } +} + +#[component] +pub fn AppBar() -> impl IntoView { + let state = use_context(APP_STATE).expect("AppState not found"); + + view! { +
+
+

"My App"

+ +
+ // Theme toggle + + + // User menu + {move || { + state.user.get().map(|user| { + view! { +
+ {user.name} + +
+ } + }) + }} +
+
+
+ } +} + +#[component] +pub fn NotificationCenter() -> impl IntoView { + let state = use_context(APP_STATE).expect("AppState not found"); + + view! { +
+ {move || { + state.notifications.get().into_iter().map(|notif| { + view! { + "border-l-blue-500", + NotificationVariant::Success => "border-l-green-500", + NotificationVariant::Warning => "border-l-yellow-500", + NotificationVariant::Error => "border-l-red-500", + } + )> +
{notif.title}
+
{notif.message}
+ + } + }).collect_view() + }} +
+ } +} +``` + +## Server State Management + +### Data Fetching Hook + +```rust +use leptos::*; +use leptos_query::*; +use std::time::Duration; + +/// Query for fetching user data +pub fn use_user_query(user_id: impl Fn() -> String + 'static) { + use_query( + user_id, + |id| async move { + // Simulate API call + tokio::time::sleep(Duration::from_millis(500)).await; + Ok(User { + id: id.clone(), + email: format!("{}@example.com", id), + name: format!("User {}", id), + }) + }, + QueryOptions { + default_value: None, + refetch_on_mount: true, + stale_time: Duration::from_secs(60), + cache_time: Duration::from_secs(300), + ..Default::default() + }, + ) +} + +#[component] +pub fn UserProfile(user_id: String) -> impl IntoView { + let query = use_user_query(move || user_id.clone()); + + view! { + + {move || { + match query.data.get() { + Some(Ok(user)) => { + view! { +
+
+
"Name"
+
{user.name.clone()}
+
+
+
"Email"
+
{user.email.clone()}
+
+ +
+ }.into_any() + } + Some(Err(_)) => { + view! { +
+ "Failed to load user data" + +
+ }.into_any() + } + None => { + view! { +
"Loading..."
+ }.into_any() + } + } + }} + + } +} +``` + +### Optimistic Updates + +```rust +#[component] +pub fn TodoList() -> impl IntoView { + // Local state for optimistic updates + let (todos, set_todos) = create_signal(Vec::::new()); + let (is_adding, set_is_adding) = create_signal(false); + let (new_todo, set_new_todo) = create_signal(String::new()); + + // Add todo optimistically + let add_todo = move |_| { + let title = new_todo.get(); + if title.is_empty() { + return; + } + + let temp_id = format!("temp-{}", uuid::Uuid::new_v4()); + + // Optimistic update + set_todos.update(|todos| { + todos.push(Todo { + id: temp_id.clone(), + title: title.clone(), + completed: false, + status: TodoStatus::Pending, + }); + }); + + set_new_todo.set(String::new()); + set_is_adding.set(true); + + // Send to server + spawn_local(async move { + // Simulate API call + tokio::time::sleep(Duration::from_secs(1)).await; + + // Update with real ID + set_todos.update(|todos| { + if let Some(todo) = todos.iter_mut().find(|t| t.id == temp_id) { + todo.id = "real-id".to_string(); + todo.status = TodoStatus::Complete; + } + }); + set_is_adding.set(false); + }); + }; + + // Toggle todo optimistically + let toggle_todo = move |id: String| { + let previous_state = todos.get() + .iter() + .find(|t| t.id == id) + .map(|t| t.completed); + + // Optimistic update + set_todos.update(|todos| { + if let Some(todo) = todos.iter_mut().find(|t| t.id == id) { + todo.completed = !todo.completed; + } + }); + + // Send to server + spawn_local(async move { + // Simulate API call + tokio::time::sleep(Duration::from_millis(500)).await; + + // On error, rollback + if let Some(previous) = previous_state { + set_todos.update(|todos| { + if let Some(todo) = todos.iter_mut().find(|t| t.id == id) { + todo.completed = previous; + } + }); + } + }); + }; + + view! { + +

"Todos"

+ + // Add todo form +
+ + +
+ + // Todo list +
+ {move || { + todos.get().into_iter().map(|todo| { + let todo_id = todo.id.clone(); + view! { +
+ + + {todo.title} + +
+ } + }).collect_view() + }} +
+ + } +} + +#[derive(Clone, Debug)] +pub struct Todo { + pub id: String, + pub title: String, + pub completed: bool, + pub status: TodoStatus, +} + +#[derive(Clone, Copy, Debug, PartialEq)] +pub enum TodoStatus { + Complete, + Pending, +} +``` + +## State Persistence + +### LocalStorage Hook + +```rust +use leptos::*; +use serde::{Deserialize, Serialize}; + +/// Hook for persisting state to localStorage +pub fn use_persistent_signal( + key: impl Fn() -> String + 'static, + default_value: impl Fn() -> T + 'static, +) -> (ReadSignal, WriteSignal) +where + T: Serialize + DeserializeOwned + Clone + 'static, +{ + // Load from localStorage on mount + let initial = { + let key = key(); + window() + .local_storage() + .ok() + .flatten() + .and_then(|storage| storage.get(&key).ok()) + .flatten() + .and_then(|json| serde_json::from_str(&json).ok()) + .unwrap_or_else(default_value) + }; + + let (signal, set_signal) = create_signal(initial); + + // Save to localStorage on change + create_effect(move |_| { + let value = signal.get(); + let key = key(); + + if let Ok(json) = serde_json::to_string(&value) { + if let Some(storage) = window().local_storage().ok().flatten() { + let _ = storage.set(&key, &json); + } + } + }); + + // Listen for storage events (sync across tabs) + window().add_event_listener(move |event: StorageEvent| { + if event.key().as_deref() == Some(&key()) { + if let Some(new_value) = event.new_value() { + if let Ok(value) = serde_json::from_str(&new_value) { + set_signal.set(value); + } + } + } + }); + + (signal, set_signal) +} + +#[component] +pub fn PersistentSettings() -> impl IntoView { + let (theme, set_theme) = use_persistent_signal( + || "theme".to_string(), + || "light".to_string(), + ); + + let (language, set_language) = use_persistent_signal( + || "language".to_string(), + || "en".to_string(), + ); + + let (sidebar_collapsed, set_sidebar_collapsed) = use_persistent_signal( + || "sidebar-collapsed".to_string(), + || false, + ); + + view! { + +

"Settings"

+ +
+
+ + +
+ +
+ + +
+ +
+
+ +

+ "Show collapsed sidebar by default" +

+
+ +
+
+ + } +} +``` + +## Complete Example: Application State Manager + +```rust +use leptos::*; +use std::sync::Arc; +use tokio::sync::RwLock; + +/// Application state manager with persistence and sync +#[derive(Clone)] +pub struct StateManager { + inner: Arc>, +} + +struct StateInner { + user: Option, + settings: Settings, + cache: HashMap, +} + +#[derive(Clone, Debug)] +pub struct Settings { + pub theme: String, + pub language: String, + pub notifications_enabled: bool, +} + +#[derive(Clone, Debug)] +pub struct CachedData { + pub data: String, + pub timestamp: i64, + pub ttl: i64, // Time to live in seconds +} + +impl StateManager { + pub async fn new() -> Self { + // Load from persistence + let settings = Self::load_settings().await; + + Self { + inner: Arc::new(RwLock::new(StateInner { + user: None, + settings, + cache: HashMap::new(), + })), + } + } + + async fn load_settings() -> Settings { + // Load from localStorage or API + Settings { + theme: "light".to_string(), + language: "en".to_string(), + notifications_enabled: true, + } + } + + pub async fn get_user(&self) -> Option { + self.inner.read().await.user.clone() + } + + pub async fn set_user(&self, user: Option) { + let mut inner = self.inner.write().await; + inner.user = user; + // Persist to localStorage + } + + pub async fn get_cached(&self, key: &str) -> Option { + let inner = self.inner.read().await; + let cached = inner.cache.get(key)?; + + // Check TTL + let now = chrono::Utc::now().timestamp(); + if now - cached.timestamp > cached.ttl { + return None; + } + + Some(cached.data.clone()) + } + + pub async fn set_cache(&self, key: String, data: String, ttl: i64) { + let mut inner = self.inner.write().await; + inner.cache.insert(key, CachedData { + data, + timestamp: chrono::Utc::now().timestamp(), + ttl, + }); + } +} +``` + +## Performance Optimization + +### Memoization + +```rust +#[component] +pub fn OptimizedComponent() -> impl IntoView { + let (items, set_items) = create_signal(vec![ + Item { id: 1, name: "Item 1".to_string(), value: 100 }, + Item { id: 2, name: "Item 2".to_string(), value: 200 }, + ]); + + // Memoized computed values + let total_value = create_memo(move |_| { + items.get().into_iter().map(|i| i.value).sum() + }); + + let expensive_computation = create_memo(move |_| { + // Only recalculates when items change + items.get() + .into_iter() + .map(|i| complex_calculation(i)) + .collect::>() + }); + + // Filtered list (also memoized) + let expensive_items = create_memo(move |_| { + items.get() + .into_iter() + .filter(|i| i.value > 150) + .collect::>() + }); + + view! { +
+
"Total: "{total_value}
+
"Expensive: "{expensive_computation.get().len()}
+
+ } +} +``` + +## Exercise + +1. Create a global state manager for a shopping cart +2. Implement optimistic updates for cart operations +3. Add persistence with localStorage +4. Create a state synchronization system for multiple tabs +5. Implement a caching layer for API responses + +## What's Next? + +- [Form Validation Patterns](02-form-validation.md) - Advanced form techniques +- [Performance Optimization](04-performance.md) - Rendering optimization +- [Real-time Data](06-realtime.md) - WebSockets and live updates + +--- + +**Previous**: [Component Series](../components/01-form-components.md) | **Next**: [Form Validation](02-form-validation.md) diff --git a/docs/tutorials/video-tutorials/components/01-form-components.md b/docs/tutorials/video-tutorials/components/01-form-components.md new file mode 100644 index 0000000..0cd17a0 --- /dev/null +++ b/docs/tutorials/video-tutorials/components/01-form-components.md @@ -0,0 +1,867 @@ +# Tutorial: Form Components Deep Dive + +**Video Length**: ~25 minutes | **Difficulty**: Intermediate | **Series**: Component Series + +## Overview + +A comprehensive guide to form components in leptos-shadcn-ui. Learn advanced patterns, composition techniques, and best practices for building robust forms. + +## What You'll Learn + +- Advanced input patterns (masked, formatted, validated) +- Building custom form controls +- Form validation architecture +- Composing complex forms +- Accessible form layouts +- Integrating with backend APIs + +## Prerequisites + +- Completed Getting Started series +- Understanding of signals and reactivity +- Familiarity with basic forms + +## Video Outline + +**[0:00]** Introduction to form components ecosystem +**[2:00]** Input component deep dive +**[5:00]** Textarea and rich text inputs +**[7:30]** Select and combobox patterns +**[10:00]** Checkbox and radio groups +**[12:30]** Switch and toggle controls +**[14:30]** Date and time pickers +**[17:00]** Form validation architecture +**[19:30]** Building a multi-step form +**[22:00]** Form accessibility patterns +**[24:00]** Summary and resources + +## Component Library + +### Input Component + +The Input component supports various types and configurations: + +```rust +use leptos::*; +use leptos_shadcn_input::Input; +use leptos_shadcn_label::Label; + +#[component] +pub fn InputExamples() -> impl IntoView { + let (text_value, set_text_value) = create_signal(String::new()); + let (email_value, set_email_value) = create_signal(String::new()); + let (password_value, set_password_value) = create_signal(String::new()); + let (number_value, set_number_value) = create_signal(0); + + view! { +
+ // Text input with icon +
+ +
+ + "πŸ”" + + +
+
+ + // Email input with validation +
+ + +
+ + // Password input with visibility toggle +
+ + +
+ + // Number input +
+ + +
+
+ } +} +``` + +### Custom Password Input Component + +```rust +#[component] +pub fn PasswordInput( + id: String, + value: ReadSignal, + on_change: WriteSignal, + #[prop(default = false)] + required: bool, +) -> impl IntoView { + let (show_password, set_show_password) = create_signal(false); + + view! { +
+ + +
+ } +} +``` + +### Textarea Component + +```rust +use leptos_shadcn_textarea::Textarea; + +#[component] +pub fn TextareaExamples() -> impl IntoView { + let (message, set_message) = create_signal(String::new()); + let char_count = move || message.get().chars().count(); + + view! { +
+ // Basic textarea +
+ +