# Components Foundation Catalog

Complete reference of all available components in the foundation library.

## Navigation Components

### BrandHeader
Main application header with branding and navigation.

```rust
use components::navigation::BrandHeader;

view! {
    <BrandHeader 
        brand_name="My App"
        logo_url="/logo.svg"
        class="custom-header"
    >
        // Optional: Custom header content
        <nav>
            <SpaLink href="/">"Home"</SpaLink>
            <SpaLink href="/about">"About"</SpaLink>
        </nav>
    </BrandHeader>
}
```

**Props**:
- `brand_name?: String` - Application brand name
- `logo_url?: String` - Logo image URL
- `class?: String` - Additional CSS classes
- `children?: Children` - Custom header content

### Footer
Application footer with links and information.

```rust
use components::navigation::Footer;

view! {
    <Footer copyright="© 2024 My Company">
        <div class="footer-links">
            <SpaLink href="/privacy">"Privacy"</SpaLink>
            <SpaLink href="/terms">"Terms"</SpaLink>
        </div>
    </Footer>
}
```

**Props**:
- `copyright?: String` - Copyright text
- `class?: String` - Additional CSS classes  
- `children?: Children` - Custom footer content

### NavMenu
Flexible navigation menu component.

```rust
use components::navigation::NavMenu;

view! {
    <NavMenu 
        orientation="horizontal"
        active_path="/current-page"
    >
        <SpaLink href="/">"Home"</SpaLink>
        <SpaLink href="/blog">"Blog"</SpaLink>
        <SpaLink href="/contact">"Contact"</SpaLink>
    </NavMenu>
}
```

**Props**:
- `orientation?: "horizontal" | "vertical"` - Menu layout
- `active_path?: String` - Currently active path
- `class?: String` - Additional CSS classes
- `children: Children` - Menu items

### LanguageSelector
Language switching component for i18n applications.

```rust
use components::navigation::LanguageSelector;

view! {
    <LanguageSelector 
        current_lang="en"
        available_langs=vec!["en", "es", "fr"]
        on_change=move |new_lang| {
            // Handle language change
        }
    />
}
```

**Props**:
- `current_lang: String` - Currently selected language
- `available_langs: Vec<String>` - Available language codes
- `on_change: impl Fn(String) + 'static` - Language change handler
- `class?: String` - Additional CSS classes

## Content Components

### UnifiedContentCard
Flexible content card for displaying structured content.

```rust
use components::content::UnifiedContentCard;

view! {
    <UnifiedContentCard 
        title="Card Title"
        subtitle="Optional subtitle"
        image_url="/image.jpg"
        class="custom-card"
    >
        <p>"Card content goes here"</p>
        <SpaLink href="/read-more">"Read More"</SpaLink>
    </UnifiedContentCard>
}
```

**Props**:
- `title: String` - Card title
- `subtitle?: String` - Optional subtitle
- `image_url?: String` - Header image URL
- `class?: String` - Additional CSS classes
- `children: Children` - Card content

### ContentManager  
Dynamic content loading and management component.

```rust
use components::content::ContentManager;

view! {
    <ContentManager 
        content_type="blog"
        filter="featured"
        limit=5
        layout="grid"
    />
}
```

**Props**:
- `content_type: String` - Type of content to load
- `filter?: String` - Content filter criteria
- `limit?: usize` - Maximum items to display
- `layout?: "list" | "grid" | "cards"` - Display layout
- `class?: String` - Additional CSS classes

### HtmlContent
Safe HTML content rendering with sanitization.

```rust
use components::content::HtmlContent;

view! {
    <HtmlContent 
        html=r#"<p>Safe <strong>HTML</strong> content</p>"#
        sanitize=true
        class="prose"
    />
}
```

**Props**:
- `html: String` - HTML content to render
- `sanitize?: bool` - Enable HTML sanitization (default: true)
- `allowed_tags?: Vec<String>` - Custom allowed HTML tags
- `class?: String` - Additional CSS classes

### SimpleContentGrid
Grid layout for content collections.

```rust
use components::content::SimpleContentGrid;

view! {
    <SimpleContentGrid 
        columns=3
        gap="1rem"
        responsive=true
    >
        <UnifiedContentCard title="Item 1" />
        <UnifiedContentCard title="Item 2" />
        <UnifiedContentCard title="Item 3" />
    </SimpleContentGrid>
}
```

**Props**:
- `columns?: usize` - Number of grid columns (default: 3)
- `gap?: String` - Grid gap spacing
- `responsive?: bool` - Enable responsive behavior
- `class?: String` - Additional CSS classes
- `children: Children` - Grid items

## UI Components

### SpaLink
SPA-aware navigation link with active state management.

```rust
use components::ui::SpaLink;

view! {
    <SpaLink 
        href="/about"
        class="nav-link"
        active_class="active"
        exact=true
    >
        "About Us"
    </SpaLink>
}
```

**Props**:
- `href: String` - Navigation URL
- `class?: String` - Base CSS classes
- `active_class?: String` - Active state CSS class
- `exact?: bool` - Exact path matching for active state
- `children: Children` - Link content

### MobileMenu
Mobile-responsive slide-out menu.

```rust
use components::ui::{MobileMenu, MobileMenuToggle};

let (menu_open, set_menu_open) = create_signal(false);

view! {
    <MobileMenuToggle 
        is_open=menu_open
        on_toggle=move |_| set_menu_open.update(|open| *open = !*open)
    />
    
    <MobileMenu 
        is_open=menu_open
        on_close=move |_| set_menu_open.set(false)
        position="left"
    >
        <SpaLink href="/">"Home"</SpaLink>
        <SpaLink href="/about">"About"</SpaLink>
    </MobileMenu>
}
```

**MobileMenu Props**:
- `is_open: ReadSignal<bool>` - Menu visibility state
- `on_close: impl Fn() + 'static` - Close handler
- `position?: "left" | "right"` - Menu slide direction
- `class?: String` - Additional CSS classes
- `children: Children` - Menu content

**MobileMenuToggle Props**:
- `is_open: ReadSignal<bool>` - Current menu state
- `on_toggle: impl Fn() + 'static` - Toggle handler
- `class?: String` - Additional CSS classes

### PageTransition
Smooth page transition effects.

```rust
use components::ui::{PageTransition, TransitionStyle};

view! {
    <PageTransition 
        style=TransitionStyle::FadeSlide
        duration=300
        class="page-wrapper"
    >
        // Page content
        <div>"Current page content"</div>
    </PageTransition>
}
```

**Props**:
- `style?: TransitionStyle` - Transition animation style
- `duration?: u32` - Transition duration in milliseconds
- `class?: String` - Additional CSS classes
- `children: Children` - Page content

## Theme Components

### ThemeProvider
Global theme context provider.

```rust
use components::theme::{ThemeProvider, ThemeConfig};

let theme_config = ThemeConfig::builder()
    .primary_color("#007acc")
    .secondary_color("#f0f8ff")
    .font_family("Inter")
    .build();

view! {
    <ThemeProvider config=theme_config>
        <App />
    </ThemeProvider>
}
```

**Props**:
- `config?: ThemeConfig` - Theme configuration
- `children: Children` - App content

### DarkModeToggle
Theme mode switching component.

```rust
use components::theme::DarkModeToggle;

view! {
    <DarkModeToggle 
        class="theme-toggle"
        light_label="☀️"
        dark_label="🌙"
    />
}
```

**Props**:
- `class?: String` - Additional CSS classes
- `light_label?: String` - Light mode indicator
- `dark_label?: String` - Dark mode indicator

### ThemeUtils Hook
Access current theme in components.

```rust
use components::theme::use_theme;

#[component]
fn ThemedComponent() -> impl IntoView {
    let theme = use_theme();
    
    view! {
        <div style=format!(
            "color: {}; background: {}; font-family: {}",
            theme.text_color(),
            theme.background_color(),
            theme.font_family()
        )>
            "Themed content"
        </div>
    }
}
```

**Theme Methods**:
- `primary_color() -> String`
- `secondary_color() -> String`
- `background_color() -> String`
- `text_color() -> String`
- `text_muted() -> String`
- `font_family() -> String`
- `font_size_base() -> String`
- `border_radius() -> String`
- `is_dark_mode() -> bool`

## Filter Components

### UnifiedCategoryFilter
Multi-category content filtering component.

```rust
use components::filter::{UnifiedCategoryFilter, FilterItem};

let filter_items = vec![
    FilterItem::new("all", "All Items"),
    FilterItem::new("blog", "Blog Posts"), 
    FilterItem::new("news", "News"),
];

view! {
    <UnifiedCategoryFilter 
        items=filter_items
        on_filter=move |category| {
            // Handle filter change
        }
        class="content-filter"
    />
}
```

**Props**:
- `items: Vec<FilterItem>` - Available filter categories
- `on_filter: impl Fn(String) + 'static` - Filter change handler
- `class?: String` - Additional CSS classes

### FilterItem
Filter category definition.

```rust
use components::filter::FilterItem;

let item = FilterItem::new("tech", "Technology")
    .with_count(15)
    .with_description("Tech articles and tutorials");
```

**Methods**:
- `new(id: &str, label: &str) -> Self`
- `with_count(count: usize) -> Self`
- `with_description(desc: &str) -> Self`

## Admin Components

### AdminLayout
Admin panel layout structure.

```rust
use components::admin::AdminLayout;

view! {
    <AdminLayout 
        title="Dashboard"
        subtitle="Admin Panel"
        breadcrumbs=vec!["Home", "Admin", "Dashboard"]
    >
        // Admin content
        <div>"Dashboard content"</div>
    </AdminLayout>
}
```

**Props**:
- `title: String` - Page title
- `subtitle?: String` - Page subtitle
- `breadcrumbs?: Vec<String>` - Breadcrumb navigation
- `class?: String` - Additional CSS classes
- `children: Children` - Page content

### AdminCard
Admin content card component.

```rust
use components::admin::AdminCard;

view! {
    <AdminCard 
        title="User Statistics"
        icon="📊"
        actions=view! {
            <button>"Export"</button>
            <button>"Refresh"</button>
        }
    >
        // Card content
        <div>"Statistics content"</div>
    </AdminCard>
}
```

**Props**:
- `title: String` - Card title
- `icon?: String` - Title icon
- `actions?: View` - Header action buttons
- `class?: String` - Additional CSS classes
- `children: Children` - Card content

### AdminHeader
Admin page header component.

```rust
use components::admin::AdminHeader;

view! {
    <AdminHeader 
        title="User Management"
        actions=view! {
            <button class="btn btn-primary">"Add User"</button>
        }
    />
}
```

**Props**:
- `title: String` - Header title
- `actions?: View` - Header action elements
- `class?: String` - Additional CSS classes

## Logo Components

### Logo
Application logo component.

```rust
use components::logo::Logo;

view! {
    <Logo 
        src="/logo.svg"
        alt="Company Logo"
        width=120
        height=40
        class="brand-logo"
    />
}
```

**Props**:
- `src: String` - Logo image source
- `alt: String` - Alt text
- `width?: u32` - Image width
- `height?: u32` - Image height
- `class?: String` - Additional CSS classes

### LogoLink
Clickable logo component.

```rust
use components::logo::LogoLink;

view! {
    <LogoLink 
        href="/"
        src="/logo.svg"
        alt="Home"
        class="logo-link"
    />
}
```

**Props**:
- `href: String` - Navigation URL
- `src: String` - Logo image source
- `alt: String` - Alt text
- `width?: u32` - Image width
- `height?: u32` - Image height
- `class?: String` - Additional CSS classes

## Component Features

### SSR Support
All components support server-side rendering:
```toml
[features]
ssr = ["leptos/ssr"]
```

### Hydration Support
Client-side hydration capabilities:
```toml
[features]  
hydrate = ["leptos/hydrate"]
```

### Accessibility
Components include ARIA attributes and keyboard navigation support by default.

### Responsive Design
Components are mobile-first responsive with breakpoint utilities.

### Theming Integration
All components integrate with the theme system for consistent styling.

## Usage Tips

1. **Import Selectively**: Only import components you use to minimize bundle size
2. **Use Theme Context**: Leverage `use_theme()` for consistent styling
3. **Compose Components**: Combine simple components to create complex layouts
4. **Handle Loading States**: Use `Suspense` for async content loading
5. **Add Error Boundaries**: Wrap components with `ErrorBoundary` for robustness
