Rustelo/examples/plugin-example-theme/README.md

# Example Analytics Theme Plugin

A complete, production-ready example plugin for the Rustelo website framework demonstrating Level 5 (Compile-Time) plugin architecture.

## 🎯 Purpose

This plugin serves as a reference implementation showing how to:

1. **Create a plugin crate** with proper structure and dependencies
2. **Implement ResourceContributor** trait for providing themes and translations
3. **Embed configuration** using `include_str!()` macros
4. **Write comprehensive tests** for plugin functionality
5. **Document thoroughly** with examples and usage instructions
6. **Follow best practices** for Rust plugin development

## 📦 What This Plugin Provides

### Themes
- **analytics-dashboard** - A professional theme optimized for analytics dashboards
  - High-contrast color scheme for readability
  - Professional color palette (blues, teals, ambers)
  - Comprehensive spacing and typography rules
  - Responsive breakpoints and animation definitions

### Translations
- **English (en)** - Complete English UI strings
  - Dashboard labels and metrics
  - Chart titles and legends
  - Action button labels
  - Status messages and tooltips

- **Spanish (es)** - Complete Spanish translations
  - Full parity with English strings
  - Localized terminology for analytics

## 🚀 Quick Start

### 1. Add to Your Project

In your main Rustelo project's `Cargo.toml`:

```toml
[dependencies]
plugin-example-theme = { path = "./crates/plugin-example-theme" }
```

### 2. Register the Plugin

In your server-side resources initialization (`src/resources.rs`):

```rust
use plugin_example_theme::ExampleThemeContributor;

pub fn initialize() -> Result<(), Box<dyn std::error::Error>> {
    // Register your own resources
    rustelo_core_lib::register_contributor(&WebsiteResourceContributor)?;

    // Register the example plugin
    rustelo_core_lib::register_contributor(&ExampleThemeContributor)?;

    // Load all resources from configuration
    rustelo_core_lib::load_resources_from_config()?;

    Ok(())
}
```

### 3. Use the Plugin's Theme

In your application's CSS/styling configuration, reference the `analytics-dashboard` theme:

```css
/* Your CSS can now use the theme variables */
:root {
  --color-primary: #2563EB;
  --color-secondary: #14B8A6;
  --color-accent: #F59E0B;
  /* ... etc ... */
}
```

## 📁 Project Structure

```
plugin-example-theme/
├── Cargo.toml                           # Plugin manifest
├── README.md                            # This file
├── src/
│   ├── lib.rs                          # Public API and initialization
│   └── resources.rs                    # ResourceContributor implementation
├── config/
│   ├── themes/
│   │   └── analytics-dashboard.toml   # Theme configuration
│   └── i18n/
│       ├── en.ftl                     # English translations
│       └── es.ftl                     # Spanish translations
└── examples/
    └── integration_test.rs             # Integration test example
```

## 🧪 Testing

### Run All Tests

```bash
cd crates/plugin-example-theme
cargo test
```

### Expected Output

```
running 10 tests

test resources::test_contributor_is_clone_and_copy ... ok
test resources::test_contributor_name ... ok
test resources::test_fluent_files_are_not_empty ... ok
test resources::test_fluent_files_are_provided ... ok
test resources::test_menus_and_footers_are_empty ... ok
test resources::test_theme_content_is_not_empty ... ok
test resources::test_theme_is_provided ... ok
test resources::test_theme_is_valid_toml ... ok
test tests::test_plugin_can_be_initialized ... ok
test tests::test_plugin_exports_public_api ... ok

test result: ok. 10 passed; 0 failed; 0 ignored
```

### Test Coverage

The plugin includes tests for:
- ✅ Contributor name and identity
- ✅ Theme availability and content
- ✅ TOML syntax validation
- ✅ Translation files (fluent) availability
- ✅ Empty menus/footers (correctly not provided)
- ✅ Copy/Clone trait implementation
- ✅ Plugin initialization
- ✅ Public API exports

## 🎨 Theme Details

### Color Palette

| Purpose | Color | Hex |
|---------|-------|-----|
| Primary | Blue | `#2563EB` |
| Secondary | Teal | `#14B8A6` |
| Accent | Amber | `#F59E0B` |
| Success | Green | `#10B981` |
| Warning | Amber | `#FBBF24` |
| Error | Red | `#EF4444` |
| Info | Blue | `#3B82F6` |

### Typography

- **Heading Font:** Inter, system-ui, sans-serif
- **Body Font:** Inter, system-ui, sans-serif
- **Monospace Font:** JetBrains Mono, Monaco, monospace
- **Scale Factor:** 1.125 (12.5% increase per step)

### Responsive Breakpoints

- Mobile: 320px
- Tablet: 768px
- Desktop: 1024px
- Wide: 1280px
- Ultra-wide: 1536px

### Spacing System

- Base unit: 8px
- Step multiplier: 1.5x
- Increments: 8px, 12px, 18px, 27px, ...

## 📝 Implementation Details

### How It Works

1. **Compile Time:** During `cargo build`, this plugin is compiled into your application
2. **Static Embedding:** Theme and i18n files are embedded via `include_str!()` macros
3. **Initialization:** When the application starts, the plugin is registered via `initialize()`
4. **Resource Loading:** The framework loads the embedded resources into memory
5. **Runtime:** The framework makes resources available to components via registries

### Why This Design?

- ✅ **No Conditional Compilation:** Framework doesn't know about plugins
- ✅ **Self-Contained:** Plugin is a complete, standalone crate
- ✅ **Type Safe:** Rust compiler validates all resource references
- ✅ **Performance:** Zero runtime overhead (fully inlined at compile time)
- ✅ **Maintainable:** Clean separation between plugin and framework
- ✅ **Scalable:** Add unlimited plugins without increasing complexity

## 🔧 Customizing This Plugin

### Modify the Theme

1. Edit `config/themes/analytics-dashboard.toml`
2. Change colors, fonts, spacing, or animations
3. Rebuild: `cargo build`

### Add Translations

1. Edit or create files in `config/i18n/`
2. Use ISO 639-1 language codes (e.g., `fr.ftl` for French)
3. Update `src/resources.rs` to include new files
4. Rebuild: `cargo build`

### Extend with More Resources

To add menus or footers:

```rust
fn menus(&self) -> HashMap<String, String> {
    let mut menus = HashMap::new();

    let menu_content = include_str!("../config/menus/my-menu.toml");
    menus.insert("my-menu".to_string(), menu_content.to_string());

    menus
}
```

## 📚 Learning Resources

### For Plugin Developers

- **PHASE3-PLUGIN-DEVELOPMENT-GUIDE.md** - Comprehensive guide to plugin development
- **PHASE1-COMPLETE.md** - Architecture foundation documentation
- **PHASE2-IMPLEMENTATION-SUMMARY.md** - Build-time code generation details

### For Framework Users

- **RUST_CODE_STYLE.md** - Rust coding standards for Rustelo
- **Framework API Docs** - ResourceContributor trait documentation

## 🎓 Architecture Level

This plugin implements **Level 5 (Compile-Time Plugins)** of the Rustelo plugin architecture:

```
Level 5: Compile-Time Plugins
├─ Trait-based registration
├─ Static code generation at build time
├─ No conditional compilation
├─ Plugin crate is self-contained
└─ Registration at application startup
```

**Future Evolution to Level 8:** The same trait interfaces can support runtime plugin loading without breaking changes.

## ✅ Quality Checklist

- ✅ Implements `ResourceContributor` trait
- ✅ Has comprehensive documentation with examples
- ✅ Includes 10+ unit tests (100% trait method coverage)
- ✅ Configuration files are valid TOML/FTL
- ✅ No hardcoded paths (uses `include_str!()`)
- ✅ No unsafe code
- ✅ No unwrap() or expect() in production code
- ✅ Cargo.toml has clear version and dependencies
- ✅ README explains purpose and usage
- ✅ Examples show typical integration
- ✅ Error handling is robust
- ✅ Performance optimized (no unnecessary allocations)

## 🤝 Contributing

To extend this example plugin:

1. Create a feature branch: `git checkout -b feature/your-feature`
2. Make changes following RUST_CODE_STYLE.md
3. Add tests for new functionality
4. Ensure all tests pass: `cargo test --all`
5. Submit pull request with clear description

## 📄 License

This example plugin is provided as part of the Rustelo framework and follows the same license terms.

## 🆘 Troubleshooting

### Plugin doesn't load

**Check:**
1. Is the plugin added to Cargo.toml?
2. Is `initialize()` called in your resources module?
3. Are there any compilation errors?

### Translations not showing

**Check:**
1. Are language codes correct (en, es, etc)?
2. Are FTL files valid Fluent syntax?
3. Is the framework loading translations?

### Theme colors not applying

**Check:**
1. Is the theme registered: `analytics-dashboard` in registry?
2. Are CSS variables using correct names?
3. Are there conflicting theme registrations?

## 📞 Support

For questions or issues with this plugin:

1. Check **PHASE3-PLUGIN-DEVELOPMENT-GUIDE.md** for comprehensive documentation
2. Review the source code comments in `src/`
3. Run tests to verify functionality
4. Check framework documentation for trait specifications

---

**Created:** 2024-11-02
**Status:** Production Ready
**Version:** 0.1.0
**Compatibility:** Rustelo Level 5+