faststrap 0.2.2__py3-none-any.whl

faststrap/__init__.py

@@ -0,0 +1,61 @@
+"""FastStrap - Modern Bootstrap 5 components for FastHTML.
+
+Build beautiful web UIs in pure Python with zero JavaScript knowledge.
+"""
+
+__version__ = "0.2.0"  # ← Update version!
+__author__ = "FastStrap Contributors"
+__license__ = "MIT"
+
+# Core functionality
+# Display
+from .components.display import Badge, Card
+
+# Feedback
+from .components.feedback import Alert, Modal, Toast, ToastContainer
+
+# Forms
+from .components.forms import Button, ButtonGroup, ButtonToolbar
+
+# Layout
+from .components.layout import Col, Container, Row
+
+# Navigation
+from .components.navigation import Drawer, Navbar
+from .core.assets import add_bootstrap, get_assets
+from .core.base import merge_classes
+
+# Utils
+from .utils.icons import Icon
+
+__all__ = [
+    # Core
+    "add_bootstrap",
+    "get_assets",
+    "merge_classes",
+    # Forms
+    "Button",
+    "ButtonGroup",
+    "ButtonToolbar",
+    # Display
+    "Badge",
+    "Card",
+    # Feedback
+    "Alert",
+    "Toast",
+    "ToastContainer",
+    "Modal",
+    # Layout
+    "Container",
+    "Row",
+    "Col",
+    # Navigation
+    "Drawer",
+    "Navbar",
+    # Utils
+    "Icon",
+    # Metadata
+    "__version__",
+    "__author__",
+    "__license__",
+]

faststrap/components/__init__.py

@@ -0,0 +1,37 @@
+"""FastStrap components."""
+
+# Forms
+# Display
+from .display import Badge, Card
+
+# Feedback
+from .feedback import Alert, Modal, Toast, ToastContainer
+from .forms import Button, ButtonGroup, ButtonToolbar
+
+# Layout
+from .layout import Col, Container, Row
+
+# Navigation
+from .navigation import Drawer, Navbar
+
+__all__ = [
+    # Forms
+    "Button",
+    "ButtonGroup",
+    "ButtonToolbar",
+    # Display
+    "Badge",
+    "Card",
+    # Feedback
+    "Alert",
+    "Toast",
+    "ToastContainer",
+    "Modal",
+    # Layout
+    "Container",
+    "Row",
+    "Col",
+    # Navigation
+    "Drawer",
+    "Navbar",
+]

faststrap/components/display/__init__.py

@@ -0,0 +1,6 @@
+"""Form components."""
+
+from .badge import Badge
+from .card import Card
+
+__all__ = ["Badge", "Card"]

faststrap/components/display/badge.py

@@ -0,0 +1,82 @@
+"""Bootstrap Badge component for status indicators and labels."""
+
+from typing import Any, Literal
+
+from fasthtml.common import Span
+
+from ...core.base import merge_classes
+from ...utils.attrs import convert_attrs
+
+VariantType = Literal[
+    "primary",
+    "secondary",
+    "success",
+    "danger",
+    "warning",
+    "info",
+    "light",
+    "dark",
+]
+
+
+def Badge(
+    *children: Any,
+    variant: VariantType = "primary",
+    pill: bool = False,
+    **kwargs: Any,
+) -> Span:
+    """Bootstrap Badge component for status indicators and labels.
+
+    Args:
+        *children: Badge content (text, numbers, icons)
+        variant: Bootstrap color variant
+        pill: Use rounded pill style
+        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)
+
+    Returns:
+        FastHTML Span element with badge classes
+
+    Example:
+        Basic usage:
+        >>> Badge("New", variant="success")
+
+        Pill style:
+        >>> Badge("99+", variant="danger", pill=True)
+
+        With icon:
+        >>> Badge(Icon("check"), "Verified", variant="info")
+
+        In button:
+        >>> Button("Messages ", Badge("4", variant="danger"))
+
+        With HTMX:
+        >>> Badge("Live", variant="warning", hx_get="/status", hx_trigger="every 5s")
+
+    Note:
+        Badges scale to match their immediate parent's font size.
+        Use text-bg-* classes for colored backgrounds with contrasting text.
+
+    See Also:
+        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/badge/
+    """
+    # Build base classes
+    classes = ["badge"]
+
+    # Add variant background
+    classes.append(f"text-bg-{variant}")
+
+    # Add pill style if requested
+    if pill:
+        classes.append("rounded-pill")
+
+    # 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}
+
+    # Convert remaining kwargs
+    attrs.update(convert_attrs(kwargs))
+
+    return Span(*children, **attrs)

faststrap/components/display/card.py

@@ -0,0 +1,140 @@
+"""Bootstrap Card component with header, body, footer support."""
+
+from typing import Any
+
+from fasthtml.common import H5, Div, Img
+
+from ...core.base import merge_classes
+from ...utils.attrs import convert_attrs
+
+
+def Card(
+    *children: Any,
+    title: str | None = None,
+    subtitle: str | None = None,
+    header: Any | None = None,
+    footer: Any | None = None,
+    img_top: str | None = None,
+    img_bottom: str | None = None,
+    img_overlay: bool = False,
+    **kwargs: Any,
+) -> Div:
+    """Bootstrap Card component for flexible content containers.
+
+    Args:
+        *children: Card body content
+        title: Card title (styled with card-title)
+        subtitle: Card subtitle (styled with card-subtitle)
+        header: Card header content (separate section above body)
+        footer: Card footer content (separate section below body)
+        img_top: Image URL for top of card
+        img_bottom: Image URL for bottom of card
+        img_overlay: Use image as background with overlay text
+        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)
+
+    Returns:
+        FastHTML Div element with card structure
+
+    Example:
+        Basic card:
+        >>> Card("Card content", title="Card Title")
+
+        With header and footer:
+        >>> Card(
+        ...     "Main content",
+        ...     title="Title",
+        ...     header="Featured",
+        ...     footer="Last updated 3 mins ago"
+        ... )
+
+        With image:
+        >>> Card(
+        ...     "Beautiful landscape description",
+        ...     title="Mountain View",
+        ...     img_top="mountain.jpg"
+        ... )
+
+        Image overlay:
+        >>> Card(
+        ...     "Overlay text",
+        ...     title="Title on Image",
+        ...     img_top="bg.jpg",
+        ...     img_overlay=True
+        ... )
+
+        With HTMX:
+        >>> Card(
+        ...     "Click to load more",
+        ...     title="Dynamic Card",
+        ...     hx_get="/more",
+        ...     hx_trigger="click"
+        ... )
+
+    Note:
+        Cards are flexible containers with minimal required markup.
+        Use the grid system for layouts with multiple cards.
+
+    See Also:
+        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/card/
+    """
+    # Build base classes
+    classes = ["card"]
+
+    # 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))
+
+    # Build card structure
+    parts = []
+
+    # Add header if provided
+    if header:
+        parts.append(Div(header, cls="card-header"))
+
+    # Add top image
+    if img_top and not img_overlay:
+        parts.append(Img(src=img_top, cls="card-img-top", alt=""))
+
+    # Build body content
+    body_content = []
+
+    # Add image for overlay mode
+    if img_overlay and img_top:
+        parts.append(Img(src=img_top, cls="card-img", alt=""))
+        body_cls = "card-img-overlay"
+    else:
+        body_cls = "card-body"
+
+    # Add title
+    if title:
+        body_content.append(H5(title, cls="card-title"))
+
+    # Add subtitle
+    if subtitle:
+        body_content.append(Div(subtitle, cls="card-subtitle mb-2 text-muted"))
+
+    # Add main content
+    if children:
+        # If there's a title/subtitle, wrap content in P for better semantics
+        if title or subtitle:
+            body_content.append(Div(*children, cls="card-text"))
+        else:
+            body_content.extend(children)
+
+    # Add body
+    if body_content:
+        parts.append(Div(*body_content, cls=body_cls))
+
+    # Add bottom image
+    if img_bottom and not img_overlay:
+        parts.append(Img(src=img_bottom, cls="card-img-bottom", alt=""))
+
+    # Add footer
+    if footer:
+        parts.append(Div(footer, cls="card-footer text-muted"))
+
+    return Div(*parts, **attrs)

faststrap/components/feedback/__init__.py

@@ -0,0 +1,7 @@
+"""Feedback components."""
+
+from .alert import Alert
+from .modal import Modal
+from .toast import Toast, ToastContainer
+
+__all__ = ["Alert", "Toast", "ToastContainer", "Modal"]

faststrap/components/feedback/alert.py

@@ -0,0 +1,112 @@
+"""Bootstrap Alert component for contextual feedback messages."""
+
+from typing import Any, Literal
+
+from fasthtml.common import Button, Div, Span
+
+from ...core.base import merge_classes
+from ...utils.attrs import convert_attrs
+
+VariantType = Literal[
+    "primary",
+    "secondary",
+    "success",
+    "danger",
+    "warning",
+    "info",
+    "light",
+    "dark",
+]
+
+
+def Alert(
+    *children: Any,
+    variant: VariantType = "primary",
+    dismissible: bool = False,
+    heading: str | None = None,
+    **kwargs: Any,
+) -> Div:
+    """Bootstrap Alert component for contextual feedback messages.
+
+    Args:
+        *children: Alert content
+        variant: Bootstrap color variant
+        dismissible: Add close button to dismiss alert
+        heading: Optional heading text (styled with alert-heading)
+        **kwargs: Additional HTML attributes (cls, id, hx-*, data-*, etc.)
+
+    Returns:
+        FastHTML Div element with alert classes
+
+    Example:
+        Basic usage:
+        >>> Alert("Operation successful!", variant="success")
+
+        With heading:
+        >>> Alert(
+        ...     "Check your inbox for confirmation.",
+        ...     variant="info",
+        ...     heading="Email Sent"
+        ... )
+
+        Dismissible:
+        >>> Alert(
+        ...     "This alert can be closed.",
+        ...     variant="warning",
+        ...     dismissible=True
+        ... )
+
+        With HTMX:
+        >>> Alert(
+        ...     "Loading...",
+        ...     variant="info",
+        ...     hx_get="/status",
+        ...     hx_trigger="load"
+        ... )
+
+    Note:
+        Dismissible alerts require Bootstrap's JavaScript.
+        The alert will fade out when the close button is clicked.
+
+    See Also:
+        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/alerts/
+    """
+    # Build base classes
+    classes = ["alert", f"alert-{variant}"]
+
+    # Add dismissible class if needed
+    if dismissible:
+        classes.append("alert-dismissible fade show")
+
+    # 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, "role": "alert"}
+
+    # Convert remaining kwargs
+    attrs.update(convert_attrs(kwargs))
+
+    # Build content
+    content = []
+
+    # Add heading if provided
+    if heading:
+        content.append(Div(heading, cls="alert-heading h4"))
+
+    # Add main content
+    content.extend(children)
+
+    # Add close button if dismissible
+    if dismissible:
+        close_btn = Button(
+            Span("×", aria_hidden="true"),
+            type="button",
+            cls="btn-close",
+            data_bs_dismiss="alert",
+            aria_label="Close",
+        )
+        content.append(close_btn)
+
+    return Div(*content, **attrs)

faststrap/components/feedback/modal.py

@@ -0,0 +1,167 @@
+"""Bootstrap Modal component for dialog boxes."""
+
+from typing import Any, Literal
+
+from fasthtml.common import H5, Button, Div
+
+from ...core.base import merge_classes
+from ...utils.attrs import convert_attrs
+
+SizeType = Literal["sm", "lg", "xl"]
+
+
+# @register(category="feedback", requires_js=True)
+def Modal(
+    *children: Any,
+    modal_id: str,  # Using modal_id to avoid conflict
+    title: str | None = None,
+    footer: Any | None = None,
+    size: SizeType | None = None,
+    centered: bool = False,
+    scrollable: bool = False,
+    fullscreen: bool | Literal["sm-down", "md-down", "lg-down", "xl-down", "xxl-down"] = False,
+    static_backdrop: bool = False,
+    fade: bool = True,
+    **kwargs: Any,
+) -> Div:
+    """Bootstrap Modal component for dialog boxes and overlays.
+
+    Args:
+        *children: Modal body content
+        modal_id: Unique ID for the modal (required for Bootstrap JS)
+        title: Modal header title
+        footer: Modal footer content (buttons, text, etc.)
+        size: Modal size (sm, lg, xl)
+        centered: Vertically center modal
+        scrollable: Make modal body scrollable
+        fullscreen: Full-screen modal (True or breakpoint like "md-down")
+        static_backdrop: Clicking backdrop doesn't close modal
+        **kwargs: Additional HTML attributes (cls, hx-*, data-*, etc.)
+
+    Returns:
+        FastHTML Div element with modal structure
+
+    Example:
+        Basic modal:
+        >>> Modal(
+        ...     P("Are you sure you want to delete this?"),
+        ...     modal_id="deleteModal",
+        ...     title="Confirm Delete",
+        ...     footer=Div(
+        ...         Button("Cancel", variant="secondary", data_bs_dismiss="modal"),
+        ...         Button("Delete", variant="danger")
+        ...     )
+        ... )
+
+        Large centered modal:
+        >>> Modal(
+        ...     "Modal content here",
+        ...     modal_id="largeModal",
+        ...     title="Large Modal",
+        ...     size="lg",
+        ...     centered=True
+        ... )
+
+        Scrollable modal:
+        >>> Modal(
+        ...     "Very long content...",
+        ...     modal_id="scrollModal",
+        ...     title="Scrollable",
+        ...     scrollable=True
+        ... )
+
+        Full-screen on mobile:
+        >>> Modal(
+        ...     "Content",
+        ...     modal_id="fullModal",
+        ...     title="Full Screen",
+        ...     fullscreen="md-down"
+        ... )
+
+    Note:
+        To trigger a modal, use Bootstrap's data attributes:
+        >>> Button("Open Modal", data_bs_toggle="modal", data_bs_target="#deleteModal")
+
+        Or use HTMX to load modal content dynamically:
+        >>> Button("Load Modal", hx_get="/modal-content", hx_target="#modalContainer")
+
+    See Also:
+        Bootstrap docs: https://getbootstrap.com/docs/5.3/components/modal/
+    """
+    # Build modal dialog classes
+    dialog_classes = ["modal-dialog"]
+
+    if size:
+        dialog_classes.append(f"modal-{size}")
+
+    if centered:
+        dialog_classes.append("modal-dialog-centered")
+
+    if scrollable:
+        dialog_classes.append("modal-dialog-scrollable")
+
+    if fullscreen:
+        if fullscreen is True:
+            dialog_classes.append("modal-fullscreen")
+        else:
+            dialog_classes.append(f"modal-fullscreen-{fullscreen}")
+
+    # Build modal attributes
+    modal_classes = ["modal"]
+    if fade:
+        modal_classes.append("fade")
+
+    user_cls = kwargs.pop("cls", "")
+    all_modal_classes = merge_classes(" ".join(modal_classes), user_cls)
+
+    attrs: dict[str, Any] = {
+        "cls": all_modal_classes,
+        "tabindex": "-1",
+        "aria_labelledby": f"{modal_id}Label",
+        "aria_hidden": "true",
+    }
+
+    # Static backdrop
+    if static_backdrop:
+        attrs["data_bs_backdrop"] = "static"
+        attrs["data_bs_keyboard"] = "false"
+
+    # Convert remaining kwargs (excluding modal_id)
+    converted_kwargs = convert_attrs({k: v for k, v in kwargs.items() if k != "modal_id"})
+    attrs.update(converted_kwargs)
+
+    # Build modal structure
+    content_parts = []
+
+    # Header
+    if title:
+        header = Div(
+            H5(title, cls="modal-title", id=f"{modal_id}Label"),
+            Button(
+                type="button",
+                cls="btn-close",
+                data_bs_dismiss="modal",
+                aria_label="Close",
+            ),
+            cls="modal-header",
+        )
+        content_parts.append(header)
+
+    # Body
+    body = Div(*children, cls="modal-body")
+    content_parts.append(body)
+
+    # Footer
+    if footer:
+        footer_div = Div(footer, cls="modal-footer")
+        content_parts.append(footer_div)
+
+    # Assemble modal
+    modal_content = Div(*content_parts, cls="modal-content")
+    modal_dialog = Div(modal_content, cls=" ".join(dialog_classes))
+
+    # Assemble modal
+    modal_content = Div(*content_parts, cls="modal-content")
+    modal_dialog = Div(modal_content, cls=" ".join(dialog_classes))
+
+    return Div(modal_dialog, id=modal_id, **attrs)