pyjoist 0.1.0__py3-none-any.whl

joist/__init__.py

@@ -0,0 +1,41 @@
+"""joist — Build HTML UI with Python dataclasses + Jinja2 templates.
+
+joist gives you a single architectural primitive: Component = dataclass + template.
+Everything else is a consequence of that choice.
+
+You define components as dataclasses, build component trees with plain
+functions (builders), and render them through Jinja2.  The framework stays
+out of your way.
+
+Core exports:
+
+* :class:`Component` — base class for dataclass-driven UI components.
+* :class:`Fragment` — lightweight variant for HTMX partials.
+* :class:`Page` — full HTML document shell.
+* :func:`setup` — configure the Jinja2 environment.
+* :func:`get_env` — access the global Jinja2 environment.
+* :func:`render_component` — render a component to ``Markup``.
+* :func:`render_template` — render a template by name with only context.
+"""
+
+from joist.component import (
+    Component,
+    ComponentError,
+    Fragment,
+    Page,
+    get_env,
+    render_component,
+    render_template,
+    setup,
+)
+
+__all__ = [
+    "Component",
+    "ComponentError",
+    "Fragment",
+    "Page",
+    "get_env",
+    "render_component",
+    "render_template",
+    "setup",
+]

joist/component.py

@@ -0,0 +1,398 @@
+"""joist — Build HTML UI with Python dataclasses + Jinja2 templates.
+
+Architecture
+------------
+
+joist implements a server-side component layer on top of Jinja2, designed
+for HTMX-heavy applications where the same UI fragment can be rendered
+as a full page, a partial swap, or an out-of-band update.
+
+The pattern follows three layers:
+
+    Routes (load data)
+        ↓
+    Builders (assemble component trees)    ← joist lives here
+        ↓
+    Templates (render markup)
+
+- **Routes** handle HTTP, authentication, and data loading. They call
+  builders and return the rendered result.
+- **Builders** are plain functions that create and compose Component
+  instances.  Builders are the primary way to assemble UI from data.
+- **Templates** render markup and place child components.  They receive
+  typed context from the Component's dataclass fields.
+
+Component = ``@dataclass(kw_only=True)`` + Jinja2 template.
+
+This module provides the primitive: :class:`Component`, :class:`Fragment`
+for HTMX partials, :class:`Page` for the document shell, and helpers
+for template environment setup.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any, ClassVar
+
+from jinja2 import Environment, FileSystemLoader
+from markupsafe import Markup
+
+__all__ = [
+    "Component",
+    "Fragment",
+    "Page",
+    "setup",
+    "get_env",
+    "render_component",
+    "render_template",
+]
+
+
+# ── Global Jinja2 environment ──────────────────────────────────────────
+
+_env: Environment | None = None
+
+
+def setup(
+    *,
+    template_dirs: list[str | Path] | None = None,
+    extensions: list[str] | None = None,
+    environment: Environment | None = None,
+    autoescape: bool = True,
+    **env_kwargs: Any,
+) -> Environment:
+    """Configure the global Jinja2 environment.
+
+    Args:
+        template_dirs: Additional directories to search for templates
+                       (built-in templates are included automatically).
+        extensions: Jinja2 extensions to load.
+        environment: An existing Environment to use instead of creating one.
+        autoescape: Enable autoescaping (default True). Ignored when
+                    ``environment`` is provided.
+        **env_kwargs: Additional kwargs passed to ``Environment``.
+                      Ignored when ``environment`` is provided.
+
+    The built-in templates directory is automatically prepended to the
+    loader chain so joist's own templates (e.g. ``Page``) are always
+    resolvable regardless of your project's template directories.
+    """
+    global _env
+    if environment is not None:
+        _env = environment
+        return _env
+
+    builtin_dir = str(Path(__file__).parent / "templates")
+    all_dirs = [builtin_dir]
+    if template_dirs:
+        all_dirs.extend(str(d) for d in template_dirs)
+
+    _env = Environment(
+        loader=FileSystemLoader(all_dirs),
+        autoescape=autoescape,
+        extensions=extensions or [],
+        **env_kwargs,
+    )
+    return _env
+
+
+def get_env() -> Environment:
+    """Return the global Jinja2 environment, creating a default if needed.
+
+    The first call without an explicit ``setup()`` will create a default
+    environment pointing only at joist's built-in templates.  Call
+    ``setup()`` first if you need to add custom template directories.
+    """
+    if _env is None:
+        return setup()
+    return _env
+
+
+# ── Component base class ───────────────────────────────────────────────
+
+
+@dataclass(kw_only=True)
+class Component:
+    """Base class for UI components.
+
+    A component is a typed data contract that maps to a Jinja2 template.
+    Dataclass fields become template context automatically.  Override
+    :meth:`get_props` to add computed properties.  Methods named
+    ``get_*()`` are callable from templates.
+
+    This is the core primitive of the three-layer architecture:
+
+    *Routes* load data and pass it to builders.
+    *Builders* create and compose Component instances into a tree.
+    *Templates* render their own markup and place children.
+
+    Nested ``Component`` instances are automatically pre-rendered to
+    ``Markup`` before reaching the template — you never need ``|safe``
+    or manual ``render()`` calls for children.
+
+    Usage::
+
+        @dataclass(kw_only=True)
+        class Greeting(Component):
+            template_path: ClassVar = "greeting.html"
+            name: str = ""
+            items: list = field(default_factory=list)
+
+            def get_props(self):
+                return {"count": len(self.items)}
+
+    The template at ``greeting.html`` receives ``{{ name }}``,
+    ``{{ items }}``, and ``{{ count }}``.
+    """
+
+    template_path: ClassVar[str] = ""
+    _joist_env: ClassVar[Environment | None] = None
+
+    #: Reserved — excluded from template context.  Pass a request-like
+    #: object when you need URL generation or other request data in
+    #: ``get_props()``.
+    request: Any | None = field(default=None, repr=False)
+
+    # ── introspection ────────────────────────────────────────────────
+
+    @property
+    def has_any(self) -> bool:
+        """Whether the component yields visible content.
+
+        Override to ``False`` when the component should be invisible
+        (e.g. empty list, missing data).  Parent components can check
+        this to decide whether to render a wrapper.
+        """
+        return True
+
+    # ── rendering ───────────────────────────────────────────────────
+
+    def get_props(self) -> dict[str, Any]:
+        """Override to inject computed properties into the template context.
+
+        The returned dict is merged *on top of* the dataclass fields so
+        it can shadow raw field values with formatted versions.
+        """
+        return {}
+
+    def props(self) -> dict[str, Any]:
+        """Return the full template context dict (public, for introspection).
+
+        Order of precedence (later wins):
+          1. Dataclass fields (excluding ``request``, private fields).
+          2. ``get_props()`` computed values.
+          3. ``get_*`` methods (callable from templates, but do not
+             override fields or props).
+
+        You can inspect this dict for debugging or testing without
+        rendering the template.
+        """
+        ctx: dict[str, Any] = {}
+
+        for f in fields(self):
+            if f.name == "request" or f.name.startswith("_"):
+                continue
+            value = getattr(self, f.name)
+            if value is None and f.metadata.get("exclude_if_none") is True:
+                continue
+            ctx[f.name] = _resolve(value)
+
+        ctx.update(self.get_props())
+
+        for method_name, method in inspect.getmembers(
+            self, predicate=inspect.ismethod
+        ):
+            if method_name.startswith("get_") and not method_name.startswith(
+                "_get_"
+            ):
+                if method_name not in ctx:
+                    ctx[method_name] = method
+
+        return ctx
+
+    def render_html(self) -> Markup:
+        """Render the component to safe HTML markup.
+
+        Returns a ``Markup`` object that Jinja2 and other template
+        engines treat as safe — no ``|safe`` filter needed when
+        embedding in parent templates.
+        """
+        if not self.template_path:
+            raise ComponentError(
+                f"{type(self).__name__} has no template_path set"
+            )
+        env = self._resolve_env()
+        template = env.get_template(self.template_path)
+        return Markup(template.render(self.props()))
+
+    def render(self) -> str:
+        """Render to a plain HTML string (same as ``str(component)``)."""
+        return str(self.render_html())
+
+    def __str__(self) -> str:
+        return self.render()
+
+    def __html__(self) -> str:
+        """Jinja2 / MarkupSafe protocol — same as ``render_html()``.
+
+        This allows ``Markup(component)`` and direct embedding in
+        parent templates via the ``|safe`` protocol.
+        """
+        return str(self.render_html())
+
+    # ── utilities ───────────────────────────────────────────────────
+
+    @classmethod
+    def _resolve_env(cls) -> Environment:
+        if cls._joist_env is None:
+            cls._joist_env = get_env()
+        return cls._joist_env
+
+
+# ── Fragment (inline HTMX partial) ─────────────────────────────────────
+
+
+@dataclass(kw_only=True)
+class Fragment(Component):
+    """Lightweight component for HTMX partials.
+
+    Unlike :class:`Component`, ``template_path`` is an *instance* field,
+    which lets you create fragments inline for HTMX partial routes::
+
+        @router.get("/users/{uid}/card")
+        async def user_card(request: Request, uid: str):
+            user = await load_user(uid)
+            return Fragment(
+                template_path="users/_card.html",
+                name=user.name,
+                role=user.role,
+            ).render_html()
+
+    For reusable HTMX partials, subclass with typed fields::
+
+        @dataclass(kw_only=True)
+        class UserRow(Fragment):
+            template_path: str = "users/_row.html"
+            user_id: str = ""
+            name: str = ""
+            role: str = ""
+    """
+
+    template_path: str = ""
+
+
+# ── Page shell ─────────────────────────────────────────────────────────
+
+
+@dataclass(kw_only=True)
+class Page(Component):
+    """Full HTML document shell.
+
+    Wraps content in a ``<!DOCTYPE html>`` document with ``<head>``
+    and ``<body>``.  The default template is minimal — override or
+    subclass for your own layout.
+
+    Designed for the :func:`~joist.htmx.render_page_or_fragment`
+    pattern: direct navigation returns a ``Page``, HTMX requests
+    return just the content component.
+
+    The ``content`` field accepts either pre-rendered ``Markup``
+    (from ``component.render_html()``) or a ``Component`` instance
+    directly.  When a ``Component`` is passed, it is automatically
+    rendered before reaching the template.
+
+    Usage::
+
+        # Explicit (builder pattern — recommended):
+        Page(page_title="Hi", content=card.render_html())
+
+        # Implicit (convenient — works with AI agents):
+        Page(page_title="Hi", content=card)
+
+    The default template produces::
+
+        <!DOCTYPE html>
+        <html lang="zh-CN">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>{{ page_title }}</title>
+          {{ head_extras }}
+        </head>
+        <body>
+          {{ content }}
+        </body>
+        </html>
+    """
+
+    template_path: ClassVar[str] = "joist/page.html"
+
+    page_title: str = ""
+    content: Component | Markup | str = Markup("")
+    head_extras: Markup = Markup("")
+    body_attrs: dict[str, str] = field(default_factory=dict)
+    lang: str = "zh-CN"
+
+    def get_props(self) -> dict[str, Any]:
+        """Ensure content is pre-rendered if a Component was passed.
+
+        This makes ``Page(content=my_component)`` work without an
+        explicit ``.render_html()`` call — convenient when an AI
+        agent or a new user is assembling the page.
+        """
+        if isinstance(self.content, Component):
+            return {"content": self.content.render_html()}
+        return {}
+
+
+# ── Pure helpers ───────────────────────────────────────────────────────
+
+
+def render_component(component: Component) -> Markup:
+    """Render a component to ``Markup``.
+
+    Convenience alias for ``component.render_html()``.
+    """
+    return component.render_html()
+
+
+def render_template(template_name: str, **context: Any) -> Markup:
+    """Render a template directly without a component class.
+
+    Useful for one-off snippets or when migrating existing code.
+
+    Example::
+
+        html = render_template("emails/welcome.html", name="Alice")
+    """
+    env = get_env()
+    return Markup(env.get_template(template_name).render(context))
+
+
+# ── Internals ──────────────────────────────────────────────────────────
+
+
+class ComponentError(Exception):
+    """Raised for component system errors."""
+
+
+def _resolve(value: Any) -> Any:
+    """Recursively render nested ``Component`` instances to ``Markup``.
+
+    This is what makes the component tree work:
+      - A ``Component`` child becomes pre-rendered ``Markup``.
+      - Lists and dicts are traversed recursively.
+      - Everything else passes through unchanged.
+
+    Templates can therefore use ``{{ child }}`` directly instead of
+    ``{{ child.render_html() }}``.
+    """
+    if isinstance(value, Component):
+        return value.render_html()
+    if isinstance(value, dict):
+        return {k: _resolve(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_resolve(v) for v in value]
+    return value

joist/htmx.py

@@ -0,0 +1,234 @@
+"""joist/htmx — HTMX request detection and response utilities.
+
+Provides helpers for the HTMX response pattern:
+
+* :func:`is_hx_request` — detect HTMX requests
+* :class:`HX` — namespace for response header builders
+* :class:`RenderResult` — typed result of rendering a component
+* :func:`render_page_or_fragment` — one path for both HTMX and direct
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from markupsafe import Markup
+
+from joist.component import Component, Page, render_component
+
+__all__ = [
+    "is_hx_request",
+    "HX",
+    "RenderResult",
+    "render_page_or_fragment",
+    "hx_trigger",
+    "hx_retarget",
+    "hx_redirect",
+    "hx_refresh",
+    "hx_push_url",
+    "hx_replace_url",
+    "hx_reselect",
+]
+
+
+def is_hx_request(request: Any) -> bool:
+    """Return ``True`` when *request* is an HTMX request.
+
+    Accepts any object with a ``.headers`` mapping (FastAPI ``Request``,
+    Starlette ``Request``, Django ``HttpRequest``, etc.).
+    """
+    return request.headers.get("HX-Request") == "true"
+
+
+# ── HX-Response-* header builders ──────────────────────────────────────
+
+
+class HX:
+    """Namespace for HTMX response header builders.
+
+    Each method returns a ``dict`` of response headers that can be
+    unpacked into a ``Response`` constructor::
+
+        from joist.htmx import HX
+
+        response = HTMLResponse(content=html, **HX.trigger("toast", "Saved!"))
+    """
+
+    @staticmethod
+    def trigger(
+        name: str, value: Any = None, *, after: str | None = None
+    ) -> dict[str, str]:
+        """Return ``HX-Trigger`` headers.
+
+        Args:
+            name: Event name (e.g. ``"toast"``, ``"reload-table"``).
+            value: Optional JSON-serialisable payload.
+            after: ``"settle"`` or ``"swap"`` — use
+                   ``HX-Trigger-After-Settle`` or
+                   ``HX-Trigger-After-Swap`` instead of ``HX-Trigger``.
+
+        Returns:
+            ``{"HX-Trigger": '...'}`` (or ``-After-Settle`` /
+            ``-After-Swap`` variant).
+
+        A trigger without a payload is emitted as a plain string::
+
+            HX.trigger("toast")                     # HX-Trigger: toast
+
+        A trigger with a payload is serialised as a JSON object::
+
+            HX.trigger("toast", {"msg": "Saved!"})   # HX-Trigger: {"toast": ...}
+        """
+        header = "HX-Trigger"
+        if after == "settle":
+            header = "HX-Trigger-After-Settle"
+        elif after == "swap":
+            header = "HX-Trigger-After-Swap"
+
+        if value is not None:
+            import json
+            raw = json.dumps({name: value}, ensure_ascii=False)
+        else:
+            raw = name
+
+        return {header: raw}
+
+    @staticmethod
+    def retarget(target: str) -> dict[str, str]:
+        """Return ``HX-Retarget`` header to change the swap target.
+
+        Example::
+
+            return HTMLResponse(content=html, **HX.retarget("#toast-container"))
+        """
+        return {"HX-Retarget": target}
+
+    @staticmethod
+    def redirect(url: str) -> dict[str, str]:
+        """Return ``HX-Redirect`` header for client-side redirect."""
+        return {"HX-Redirect": url}
+
+    @staticmethod
+    def refresh() -> dict[str, str]:
+        """Return ``HX-Refresh`` header to refresh the current page."""
+        return {"HX-Refresh": "true"}
+
+    @staticmethod
+    def push_url(url: str) -> dict[str, str]:
+        """Return ``HX-Push-Url`` header to push a new browser history entry."""
+        return {"HX-Push-Url": url}
+
+    @staticmethod
+    def replace_url(url: str) -> dict[str, str]:
+        """Return ``HX-Replace-Url`` header to replace the current URL."""
+        return {"HX-Replace-Url": url}
+
+    @staticmethod
+    def reselect(css_selector: str) -> dict[str, str]:
+        """Return ``HX-Reselect`` header to override the swap target selection."""
+        return {"HX-Reselect": css_selector}
+
+
+# Convenience aliases
+hx_trigger = HX.trigger
+hx_retarget = HX.retarget
+hx_redirect = HX.redirect
+hx_refresh = HX.refresh
+hx_push_url = HX.push_url
+hx_replace_url = HX.replace_url
+hx_reselect = HX.reselect
+
+
+# ── Render result ──────────────────────────────────────────────────────
+
+
+@dataclass
+class RenderResult:
+    """Typed result of rendering a component as an HTMX fragment or
+    full-page document.
+
+    Returned by :func:`render_page_or_fragment`.  Framework integrations
+    (e.g. FastAPI) consume this to produce a proper ``Response``.
+
+    Attributes:
+        content: The rendered HTML string.
+        headers: Response headers (e.g. ``HX-Trigger``).
+        is_fragment: ``True`` when the result is an HTMX fragment
+                     (just the component), ``False`` when it is a
+                     full ``Page`` document.
+    """
+
+    content: str = ""
+    headers: dict[str, str] = field(default_factory=dict)
+    is_fragment: bool = False
+
+
+# ── Render helpers ─────────────────────────────────────────────────────
+
+
+def render_page_or_fragment(
+    request: Any,
+    page_title: str,
+    content: Component,
+    *,
+    page_cls: type[Page] = Page,
+    page_kwargs: dict[str, Any] | None = None,
+    hx_trigger_headers: dict[str, str] | None = None,
+) -> RenderResult:
+    """Render a fragment for HTMX, or a full page for direct navigation.
+
+    HTMX requests receive only the content component's HTML.
+    Direct navigation receives a ``Page`` shell wrapping that content.
+
+    Framework integrations (FastAPI, Starlette) consume the returned
+    ``RenderResult`` to produce a proper ``Response``.  Bare users can
+    use the ``.content`` and ``.headers`` attributes directly.
+
+    Usage with FastAPI::
+
+        @router.get("/users")
+        async def users_page(request: Request):
+            table = UserTable(users=await load_users())
+            result = render_page_or_fragment(request, "Users", table)
+            return HTMLResponse(
+                content=result.content,
+                headers=result.headers or None,
+            )
+
+    Args:
+        request: Incoming request object (must have ``.headers``).
+        page_title: Value for ``<title>``.
+        content: The main content component.
+        page_cls: Page shell class (default :class:`Page`).
+        page_kwargs: Extra kwargs for the ``Page`` constructor.
+        hx_trigger_headers: Additional HTMX trigger headers.
+
+    Returns:
+        A :class:`RenderResult` with ``.content``, ``.headers``,
+        and ``.is_fragment``.
+    """
+    content_html = render_component(content)
+    headers: dict[str, str] = {}
+    if hx_trigger_headers:
+        headers.update(hx_trigger_headers)
+
+    if is_hx_request(request):
+        return RenderResult(
+            content=str(content_html),
+            headers=headers,
+            is_fragment=True,
+        )
+
+    kw = page_kwargs or {}
+    page = page_cls(
+        request=request,
+        page_title=page_title,
+        content=content_html,
+        **kw,
+    )
+    return RenderResult(
+        content=str(page.render_html()),
+        headers=headers,
+        is_fragment=False,
+    )

joist/integrators/__init__.py

@@ -0,0 +1,35 @@
+"""joist FastAPI integration.
+
+Provides :func:`setup_fastapi` to attach joist's rendering to a
+FastAPI application.
+
+Usage::
+
+    from fastapi import FastAPI, Request
+    from joist.integrators import setup_fastapi
+    from joist import Fragment
+
+    app = FastAPI()
+    joist = setup_fastapi(app, template_dirs=["templates"])
+
+    @app.get("/hello")
+    async def hello(request: Request):
+        frag = Fragment(template_path="hello.html", name="World")
+        return joist.response(frag)
+"""
+
+from joist.integrators.fastapi import (
+    Joist,
+    fragment_or_page,
+    html,
+    page,
+    setup_fastapi,
+)
+
+__all__ = [
+    "Joist",
+    "fragment_or_page",
+    "html",
+    "page",
+    "setup_fastapi",
+]