faststrap 0.2.2__tar.gz

faststrap-0.2.2/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.sesskey
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Distribution
+*.tar.gz
+*.whl

faststrap-0.2.2/BUILDING_COMPONENTS.md

@@ -0,0 +1,347 @@
+# Building FastStrap Components - Complete Guide
+
+**For contributors, LLMs, and developers building new components.**
+
+---
+
+## 🎯 Quick Start (30 seconds)
+
+1. Copy an existing component from `src/faststrap/components/` as template
+2. Follow the patterns below
+3. Add tests to `tests/test_components/`
+4. Submit PR
+
+**Best templates to copy:**
+- Simple component: `badge.py`
+- Complex component: `card.py`
+- Interactive (Bootstrap JS): `modal.py`
+
+---
+
+## 📋 Component Checklist
+
+Before submitting, ensure:
+
+- [ ] File in correct directory (`forms/`, `display/`, `feedback/`, `navigation/`, `layout/`)
+- [ ] Function uses Python 3.10+ type hints (`str | None` not `Optional[str]`)
+- [ ] Includes `_convert_attrs()` helper for HTMX support
+- [ ] Uses `merge_classes()` from `core.base` for CSS
+- [ ] Comprehensive docstring with examples
+- [ ] Test file with 8-15 tests
+- [ ] Exported in `__init__.py` files
+- [ ] Works with `to_xml()` (not just `str()`)
+
+---
+
+## 🏗️ Component Structure Template
+
+```python
+"""Bootstrap [ComponentName] for [purpose]."""
+
+from typing import Any, Literal
+
+from fasthtml.common import Div  # Or appropriate FT type
+
+from ...core.base import merge_classes
+from ...utils.attrs import convert_attrs
+
+# Type aliases
+VariantType = Literal["primary", "secondary", "success", "danger", "warning", "info", "light", "dark"]
+
+
+def ComponentName(
+    *children: Any,
+    variant: VariantType = "primary",
+    **kwargs: Any,
+) -> Div:
+    """Bootstrap [ComponentName] component.
+
+    Args:
+        *children: Component content
+        variant: Bootstrap color variant
+        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)
+
+    Returns:
+        FastHTML Div element
+
+    Example:
+        Basic:
+        >>> ComponentName("Content", variant="success")
+
+        With HTMX:
+        >>> ComponentName("Load", hx_get="/api", hx_target="#result")
+
+        Custom styling:
+        >>> ComponentName("Custom", cls="mt-3 shadow")
+
+    See Also:
+        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/[name]/
+    """
+    # Build classes
+    classes = ["component-base", f"component-{variant}"]
+
+    # Merge with user classes
+    user_cls = kwargs.pop("cls", "")
+    all_classes = merge_classes(" ".join(classes), user_cls)
+
+    # Build attributes
+    attrs: dict[str, Any] = {"cls": all_classes}
+    attrs.update(convert_attrs(kwargs))
+
+    return Div(*children, **attrs)
+```
+
+---
+
+## 🔧 Critical Patterns
+
+### 1. **Type Hints (Python 3.10+)**
+
+```python
+# ✅ CORRECT
+from typing import Any, Literal
+
+def Component(
+    *children: Any,
+    size: Literal["sm", "lg"] | None = None,
+    **kwargs: Any
+) -> Div:
+    ...
+
+# ❌ WRONG (old style)
+from typing import Optional, Union
+
+def Component(
+    size: Optional[Union[str, None]] = None
+) -> Div:
+    ...
+```
+
+### 2. **Class Merging**
+
+```python
+from ...core.base import merge_classes
+
+# Always merge user classes
+user_cls = kwargs.pop("cls", "")
+all_classes = merge_classes("btn btn-primary", user_cls)
+```
+
+### 3. **HTMX Attribute Conversion**
+
+```python
+# Always include _convert_attrs() function
+attrs.update(_convert_attrs(kwargs))
+
+# This allows:
+Button("Save", hx_post="/save", hx_target="#result")
+# To become: <button hx-post="/save" hx-target="#result">Save</button>
+```
+
+### 4. **Bootstrap Variants**
+
+```python
+# Standard variants
+VariantType = Literal[
+    "primary", "secondary", "success", "danger",
+    "warning", "info", "light", "dark"
+]
+
+# Apply as:
+classes.append(f"btn-{variant}")  # OR
+classes.append(f"text-bg-{variant}")  # For colored backgrounds
+```
+
+### 5. **Component IDs (Special Handling)**
+
+If your component requires an `id` (like Modal, Drawer):
+
+```python
+def Modal(
+    *children: Any,
+    modal_id: str,  # ← Use custom param name, NOT "id"
+    **kwargs: Any
+) -> Div:
+    # Build component first
+    result = Div(*parts, **attrs)
+    
+    # Set id AFTER creation (bypasses FastHTML quirk)
+    result.attrs['id'] = modal_id
+    
+    return result
+```
+
+**Why:** FastHTML's `str()` has a bug with `id` parameter. Use `modal_id`/`drawer_id`/etc.
+
+---
+
+## 🧪 Test File Template
+
+```python
+"""Tests for ComponentName."""
+
+from fasthtml.common import to_xml  # ← IMPORTANT: Use to_xml(), not str()
+
+from faststrap.components.category import ComponentName
+
+
+def test_component_basic():
+    """Component renders correctly."""
+    comp = ComponentName("Test")
+    html = to_xml(comp)  # ← Use to_xml()
+    
+    assert "Test" in html
+    assert "component-base" in html
+
+
+def test_component_variants():
+    """Component supports all variants."""
+    variants = ["primary", "secondary", "success", "danger"]
+    
+    for variant in variants:
+        comp = ComponentName("Test", variant=variant)
+        html = to_xml(comp)
+        assert f"component-{variant}" in html
+
+
+def test_component_custom_classes():
+    """Component merges custom classes."""
+    comp = ComponentName("Test", cls="custom-class mt-3")
+    html = to_xml(comp)
+    
+    assert "component-base" in html
+    assert "custom-class" in html
+    assert "mt-3" in html
+
+
+def test_component_htmx():
+    """Component supports HTMX."""
+    comp = ComponentName("Load", hx_get="/api", hx_target="#result")
+    html = to_xml(comp)
+    
+    assert 'hx-get="/api"' in html
+    assert 'hx-target="#result"' in html
+
+
+def test_component_data_attributes():
+    """Component handles data attributes."""
+    comp = ComponentName("Test", data_id="123", data_type="info")
+    html = to_xml(comp)
+    
+    assert 'data-id="123"' in html
+    assert 'data-type="info"' in html
+```
+
+**CRITICAL:** Always use `to_xml(component)`, **never** `str(component)` due to FastHTML bug.
+
+---
+
+## 📁 File Structure
+
+```
+src/faststrap/components/
+├── display/          # Visual elements (Badge, Card, Avatar)
+│   ├── __init__.py
+│   └── component.py
+├── feedback/         # User feedback (Alert, Toast, Modal)
+├── forms/            # Form inputs (Button, Input, Select)
+├── layout/           # Layout helpers (Container, Row, Col)
+└── navigation/       # Navigation (Navbar, Tabs, Breadcrumb)
+
+tests/test_components/
+└── test_component.py
+```
+
+---
+
+## 🎨 Bootstrap Component Reference
+
+When building a component, reference Bootstrap docs:
+
+**Base URL:** `https://getbootstrap.com/docs/5.3/components/[name]/`
+
+**Key classes to know:**
+- Variants: `btn-primary`, `alert-success`, `text-bg-danger`
+- Sizes: `btn-sm`, `btn-lg`, `form-control-lg`
+- States: `disabled`, `active`, `show`, `fade`
+- Utilities: `d-flex`, `gap-2`, `mt-3`, `shadow`
+
+---
+
+## 🚀 Component Priority List
+
+### **Phase 2 (Next):**
+1. Tabs
+2. Dropdown
+3. Input (text, email, password)
+4. Select
+5. Breadcrumb
+6. Pagination
+7. Spinner
+8. Progress
+
+### **Phase 3:**
+9. Table
+10. Accordion
+11. Carousel
+12. ListGroup
+13. Tooltip
+14. Popover
+15. Checkbox/Radio/Switch
+16. Range
+17. FileInput
+18. FormValidation
+
+---
+
+## 💡 Tips for LLMs
+
+When asking an LLM to build a component:
+
+**Good prompt:**
+> "Build the Tabs component for FastStrap following BUILDING_COMPONENTS.md. Use Badge.py as template. Include nav-tabs, nav-pills, and content panes. Add 10 tests using to_xml(). Reference: https://getbootstrap.com/docs/5.3/components/navs-tabs/"
+
+**Include:**
+- This guide
+- An existing component as reference
+- Bootstrap docs link
+- Specific test count
+
+---
+
+## 🤝 Getting Help
+
+- **Questions:** Open GitHub Discussion
+- **Bugs:** Open GitHub Issue
+- **PRs:** We review within 48 hours
+- **Discord:** Join FastHTML community
+
+---
+
+## ✅ Submission Checklist
+
+Before submitting PR:
+
+```bash
+# 1. Run tests
+pytest tests/test_components/test_yourcomponent.py -v
+
+# 2. Check coverage
+pytest --cov=faststrap.components.category.yourcomponent
+
+# 3. Type check
+mypy src/faststrap/components/category/yourcomponent.py
+
+# 4. Format
+black src/faststrap/components/category/yourcomponent.py
+ruff check src/faststrap/components/category/yourcomponent.py
+
+# 5. Test example
+python examples/demo_yourcomponent.py
+```
+
+All checks pass? Submit PR! 🎉
+
+---
+
+**Ready to build? Pick a component from Phase 2 and start coding!**

faststrap-0.2.2/CHANGE_LOG.md

@@ -0,0 +1,250 @@
+# Changelog
+
+All notable changes to FastStrap will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] - 2025-12-09
+
+### Added
+- Interactive demo with HTMX theme toggle (no custom JavaScript)
+- HTMX-powered toast trigger button
+- Complete showcase of all 12 components with real interactions
+
+### Improved
+- Demo now proves components work without custom JavaScript
+- Theme switching via HTMX POST request
+- Toast notifications via HTMX GET request
+- Better documentation of HTMX integration
+
+### Technical
+- Added `/toggle-theme` route for theme switching
+- Added `/show-toast` route for toast notifications
+- Minimal Bootstrap JS usage (only built-in features)
+
+---
+
+## [0.2.0] - 2025-12-08
+
+### 🎉 Phase 1 + Phase 2 Complete - Production Ready!
+
+This is the first production-ready release of FastStrap, featuring 12 fully-tested Bootstrap 5 components for FastHTML.
+
+### Added
+
+#### **Components (12 total)**
+
+**Forms (2):**
+- `Button` - Fully-featured button with variants, sizes, icons, loading states, and outline styles
+- `ButtonGroup` - Group buttons together with vertical/horizontal orientation and toolbar support
+- `ButtonToolbar` - Organize multiple button groups
+
+**Display (2):**
+- `Badge` - Status indicators and labels with pill style option
+- `Card` - Flexible content container with header, footer, image support, and overlay mode
+
+**Feedback (3):**
+- `Alert` - Contextual feedback messages with dismissible option and custom headings
+- `Toast` - Auto-dismissing notifications with positioning via ToastContainer
+- `Modal` - Dialog boxes with multiple sizes, centering, scrollable content, and fullscreen modes
+
+**Layout (3):**
+- `Container` - Fixed-width or fluid responsive containers
+- `Row` - Grid rows with responsive column counts
+- `Col` - Grid columns with responsive sizing and offsets
+
+**Navigation (2):**
+- `Navbar` - Responsive navigation bar with brand, collapse, and theming
+- `Drawer` (Offcanvas) - Sliding side panels with multiple placements and backdrop control
+
+**Utils (1):**
+- `Icon` - Bootstrap Icons helper for easy icon integration
+
+#### **Core Features**
+- Asset management system with CDN and local file support
+- Theme system supporting light, dark, and auto modes
+- Base component classes and protocols for consistent API
+- HTMX attribute conversion (`hx_get` → `hx-get`)
+- Class merging utility for combining Bootstrap and custom classes
+- Python 3.10+ type hints throughout
+
+#### **Infrastructure**
+- Complete test suite with 121 tests
+- 84% code coverage
+- Type checking with MyPy
+- Code formatting with Black and Ruff
+- GitHub Actions CI/CD pipeline
+- Automatic PyPI publishing on release
+
+#### **Documentation**
+- Comprehensive README with quick start guide
+- Component specification guide (COMPONENT_SPEC.md)
+- Contributor guide (BUILDING_COMPONENTS.md)
+- Development roadmap (ROADMAP.md)
+- Example applications demonstrating all components
+- Inline documentation with usage examples
+
+### Fixed
+- FastHTML `id` parameter handling using `modal_id`/`drawer_id` workaround
+- Test suite updated to use `to_xml()` instead of `str()` (FastHTML 0.12.33 bug workaround)
+- HTMX attribute conversion for proper HTML rendering
+- Class merging to prevent duplicate Bootstrap classes
+- Theme application via `htmlkw` for proper Bootstrap theming
+
+### Technical Details
+- **Python Version:** 3.10+
+- **FastHTML Version:** 0.6.0+
+- **Bootstrap Version:** 5.3.3
+- **Bootstrap Icons Version:** 1.11.3
+- **Type Checking:** MyPy strict mode
+- **Linting:** Ruff + Black
+- **Testing:** pytest with coverage reporting
+
+---
+
+## [0.1.0] - 2025-12-05
+
+### 🌟 Initial Development Release
+
+First internal release establishing the foundation of FastStrap.
+
+### Added
+
+#### **Phase 1 Components (5):**
+- `Button` - Basic button implementation with variants and sizes
+- `Badge` - Simple badge component with color variants
+- `Alert` - Alert component with dismissible functionality
+- `Card` - Card container with header and footer
+- Grid system (`Container`, `Row`, `Col`) - Responsive layout system
+
+#### **Core Infrastructure**
+- Project structure and build configuration
+- Asset management for Bootstrap CSS/JS
+- Base component classes and utilities
+- Initial test framework setup
+- GitHub repository initialization
+
+### Development Notes
+- Established component development patterns
+- Created test templates and examples
+- Set up CI/CD pipeline
+- Documented contribution guidelines
+
+---
+
+## [Unreleased]
+
+### 🚀 Coming in v0.3.0 (Phase 2 - Q1 2025)
+
+#### **Planned Components (8):**
+- `Tabs` - Navigation tabs and pills
+- `Dropdown` - Contextual dropdown menus
+- `Input` - Text input controls with validation
+- `Select` - Dropdown selection controls
+- `Breadcrumb` - Navigation breadcrumbs
+- `Pagination` - Page navigation controls
+- `Spinner` - Loading indicators
+- `Progress` - Progress bars with labels and animations
+
+#### **Planned Features:**
+- Enhanced form validation helpers
+- Additional theme customization options
+- Component playground documentation site
+- Video tutorials and examples
+- Performance optimizations
+
+See [ROADMAP.md](ROADMAP.md) for complete future plans.
+
+---
+
+## Release Statistics
+
+### v0.2.0 Metrics
+- **Components:** 12
+- **Tests:** 121
+- **Coverage:** 84%
+- **Lines of Code:** ~1,500
+- **Contributors:** 2
+- **Development Time:** 2 weeks
+
+---
+
+## Migration Guides
+
+### Migrating from 0.1.0 to 0.2.0
+
+**Breaking Changes:**
+- None - First public release
+
+**New Features:**
+- 7 new components added (Toast, Modal, Drawer, Navbar, ButtonGroup)
+- HTMX integration now fully supported
+- Theme system implemented
+- All components now production-ready
+
+**Deprecations:**
+- None
+
+---
+
+## Version History Summary
+
+| Version | Release Date | Components | Tests | Coverage | Status |
+|---------|--------------|------------|-------|----------|--------|
+| 0.2.0   | 2025-12-08   | 12         | 121   | 84%      | ✅ Stable |
+| 0.1.0   | 2025-12-06   | 5          | 56    | 75%      | 🔒 Internal |
+
+---
+
+## Contributing
+
+We welcome contributions! See:
+- [BUILDING_COMPONENTS.md](BUILDING_COMPONENTS.md) - How to build components
+- [ROADMAP.md](ROADMAP.md) - What needs to be built
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
+
+### Reporting Issues
+Found a bug? [Open an issue](https://github.com/Evayoung/Faststrap/issues/new)
+
+### Requesting Features
+Want a new component? [Start a discussion](https://github.com/Evayoung/Faststrap/discussions/new)
+
+---
+
+## Acknowledgments
+
+### v0.2.0 Contributors
+- **Olorundare Micheal** (@Evayoung) - Lead Developer
+- **Claude (Anthropic)** - AI Development Assistant
+- FastHTML Community - Testing and feedback
+
+### Special Thanks
+- **Jeremy Howard** - Creator of FastHTML
+- **Answer.AI Team** - FastHTML development
+- **Bootstrap Team** - Amazing CSS framework
+- All early testers and contributors
+
+---
+
+## License
+
+FastStrap is released under the [MIT License](LICENSE).
+
+Copyright (c) 2024 FastStrap Contributors
+
+---
+
+## Links
+
+- **Homepage:** https://github.com/Evayoung/Faststrap
+- **Documentation:** [BUILDING_COMPONENTS.md](BUILDING_COMPONENTS.md)
+- **PyPI:** https://pypi.org/project/faststrap/
+- **Issues:** https://github.com/Evayoung/Faststrap/issues
+- **Discussions:** https://github.com/Evayoung/Faststrap/discussions
+
+---
+
+*For older releases and detailed commit history, see [GitHub Releases](https://github.com/Evayoung/Faststrap/releases).*
+
+**Last Updated:** December 8, 2025