slots

jpsca · jpsca · commit 03db96fa5afa · 2025-08-28T15:16:24.000-05:00
diff --git a/README.md b/README.md
@@ -12,3 +12,38 @@ Super components powers for your Jinja templates.
 From chaos to clarity: The power of components in your server-side-rendered Python web app.
 
 <!-- Documentation: https://jx.scaletti.dev/ -->
+
+## How It Works
+
+Jx is a Python library for creating reusable template components with Jinja2. It works by pre-parsing the template source and replacing TitleCased HTML tags with Jinja calls that render the component.
+
+### Component Definition
+
+Components are defined as regular Jinja2 templates (.jinja files) with special metadata comments:
+
+- `{# def parameter1 parameter2=default_value #}` - Defines required and optional parameters
+- `{# import "path/to/component.jinja" as ComponentName #}` - Imports other components
+- `{# css "/path/to/style.css" #}` - Includes CSS files
+- `{# js "/path/to/script.js" #}` - Includes JavaScript files
+
+Example component:
+
+```jinja
+{# def message #}
+{# import "button.jinja" as Button #}
+
+<div class="greeting">{{ message }}</div>
+<Button text="OK" />
+```
+
+### Usage Example
+
+```python
+from jx import Catalog
+
+# Create a catalog and add a components folder
+catalog = Catalog("templates/components")
+
+# Render a component with parameters
+html = catalog.render("card.jinja", title="Hello", content="This is a card")
+```
diff --git a/src/jx/attrs.py b/src/jx/attrs.py
@@ -155,6 +155,8 @@ def set(self, **kw) -> None:
         - The underscores in the names will be translated automatically to dashes,
           so `aria_selected` becomes the attribute `aria-selected`.
 
+        TODO: vue-style
+
         Example:
 
             ```python
diff --git a/src/jx/catalog.py b/src/jx/catalog.py
@@ -27,6 +27,7 @@ class CData:
     imports: dict[str, str] = field(default_factory=dict)  # { name: relpath }
     css: tuple[str, ...] = ()
     js: tuple[str, ...] = ()
+    slots: tuple[str, ...] = ()
 
 
 class Catalog:
@@ -217,7 +218,7 @@ def get_component_data(self, relpath: str) -> CData:
             source=source,
             components=list(meta.imports.keys())
         )
-        parsed_source = parser.parse()
+        parsed_source, slots = parser.parse()
         code = self.jinja_env.compile(
             source=parsed_source,
             name=relpath,
@@ -230,6 +231,7 @@ def get_component_data(self, relpath: str) -> CData:
         cdata.imports = meta.imports
         cdata.css = meta.css
         cdata.js = meta.js
+        cdata.slots = slots
         return cdata
 
     def get_component(self, relpath: str) -> Component:
@@ -256,9 +258,10 @@ def get_component(self, relpath: str) -> Component:
             get_component=self.get_component,
             required=cdata.required,
             optional=cdata.optional,
+            imports=cdata.imports,
             css=cdata.css,
             js=cdata.js,
-            imports=cdata.imports
+            slots=cdata.slots,
         )
         return co
 
diff --git a/src/jx/component.py b/src/jx/component.py
@@ -22,9 +22,10 @@ class Component:
         "get_component",
         "required",
         "optional",
+        "imports",
         "css",
         "js",
-        "imports",
+        "slots",
         "globals",
     )
 
@@ -36,9 +37,10 @@ def __init__(
         get_component: Callable[[str], "Component"],
         required: tuple[str, ...] = (),
         optional: dict[str, t.Any] | None = None,
+        imports: dict[str, str] | None = None,
         css: tuple[str, ...] = (),
         js: tuple[str, ...] = (),
-        imports: dict[str, str] | None = None,
+        slots: tuple[str, ...] = (),
     ) -> None:
         """
         Internal object that represents a Jx component.
@@ -54,12 +56,14 @@ def __init__(
                 A tuple of required attribute names.
             optional:
                 A dictionary of optional attributes and their default values.
+            imports:
+                A dictionary of imported component names as "name": "relpath" pairs.
             css:
                 A tuple of CSS file URLs.
             js:
                 A tuple of JS file URLs.
-            imports:
-                A dictionary of imported component names as "name": "relpath" pairs.
+            slots:
+                A tuple of slot names.
 
         """
         self.relpath = relpath
@@ -68,9 +72,10 @@ def __init__(
 
         self.required = required
         self.optional = optional or {}
+        self.imports = imports or {}
         self.css = css
         self.js = js
-        self.imports = imports or {}
+        self.slots = slots
 
         self.globals: dict[str, t.Any] = {}
 
@@ -79,10 +84,10 @@ def render(
         *,
         content: str | None = None,
         attrs: Attrs | dict[str, t.Any] | None = None,
-        caller: Callable[[], str] | None = None,
+        caller: Callable[[str], str] | None = None,
         **params: t.Any
     ) -> Markup:
-        content = content if content is not None else caller() if caller else ""
+        content = content if content is not None else caller("") if caller else ""
         attrs = attrs.as_dict if isinstance(attrs, Attrs) else attrs or {}
         params = {**attrs, **params}
         props, attrs = self.filter_attrs(params)
@@ -91,6 +96,14 @@ def render(
         globals.setdefault("attrs", Attrs(attrs))
         globals.setdefault("content", content)
 
+        slots = {}
+        if caller:
+            for name in self.slots:
+                body = caller(name)
+                if body != content:
+                    slots[name] = body
+        props["_slots"] = slots
+
         html = self.tmpl.render({**props, **globals}).lstrip()
         return Markup(html)
 
diff --git a/src/jx/parser.py b/src/jx/parser.py
@@ -12,7 +12,7 @@
 from .utils import logger
 
 
-BLOCK_CALL = '{% call _get("[TAG]").render([ATTRS]) -%}[CONTENT]{%- endcall %}'
+BLOCK_CALL = '{% call(_slot="") _get("[TAG]").render([ATTRS]) -%}[CONTENT]{%- endcall %}'
 INLINE_CALL = '{{ _get("[TAG]").render([ATTRS]) }}'
 
 re_raw = r"\{%-?\s*raw\s*-?%\}.+?\{%-?\s*endraw\s*-?%\}"
@@ -33,6 +33,17 @@
 """
 RX_ATTR = re.compile(re_attr, re.VERBOSE | re.DOTALL)
 
+RE_LSTRIP = r"\s*(?P<lstrip>-?)%}"
+RE_RSTRIP = r"{%(?P<rstrip>-?)\s*"
+
+RE_SLOT_OPEN = r"{%-?\s*slot\s+(?P<name>[0-9A-Za-z_.:$-]+)" + RE_LSTRIP
+RE_SLOT_CLOSE = RE_RSTRIP + r"endslot\s*-?%}"
+RX_SLOT = re.compile(rf"{RE_SLOT_OPEN}(?P<default>.*?)({RE_SLOT_CLOSE})", re.DOTALL)
+
+RE_FILL_OPEN = r"{%-?\s*fill\s+(?P<name>[0-9A-Za-z_.:$-]+)" + RE_LSTRIP
+RE_FILL_CLOSE = RE_RSTRIP + r"endfill\s*-?%}"
+RX_FILL = re.compile(rf"{RE_FILL_OPEN}(?P<body>.*?)({RE_FILL_CLOSE})", re.DOTALL)
+
 
 def escape(s: t.Any, /) -> Markup:
     return Markup(
@@ -72,7 +83,7 @@ def __init__(
         self.source = source
         self.components = components
 
-    def parse(self, *, validate_tags: bool = True) -> str:
+    def parse(self, *, validate_tags: bool = True) -> tuple[str, tuple[str, ...]]:
         """
         Parses the template source code.
 
@@ -81,7 +92,8 @@ def parse(self, *, validate_tags: bool = True) -> str:
                 Whether to raise an error for unknown TitleCased tags.
 
         Returns:
-            The transformed template source code.
+            - The transformed template source code
+            - The list of slot names.
 
         Raises:
             TemplateSyntaxError:
@@ -92,8 +104,9 @@ def parse(self, *, validate_tags: bool = True) -> str:
         source = self.source
         source, raw_blocks = self.replace_raw_blocks(source)
         source = self.process_tags(source, validate_tags=validate_tags)
+        source, slots = self.process_slots(source)
         source = self.restore_raw_blocks(source, raw_blocks)
-        return source
+        return source, slots
 
     def replace_raw_blocks(self, source: str) -> tuple[str, dict[str, str]]:
         """
@@ -202,10 +215,93 @@ def replace_tag(
             content = source[end:index]
             end = index + len(close_tag)
 
+        if content:
+            content = self.process_fills(content)
+
         attrs = self._parse_attrs(raw_attrs)
         repl = self._build_call(tag, attrs, content)
         return f"{source[:start]}{repl}{source[end:]}"
 
+    def process_slots(self, source: str) -> tuple[str, tuple[str, ...]]:
+        """
+        Extracts slot content from the template source code.
+
+        Arguments:
+            source:
+                The template source code
+
+        Returns:
+            - The transformed template source code
+            - The list of slot names.
+
+        """
+        slots = {}
+        while True:
+            match = RX_SLOT.search(source)
+            if not match:
+                break
+            start, end = match.span(0)
+            slot_name = match.group("name")
+            slot_default = match.group("default") or ""
+            lstrip = match.group("lstrip") == "-"
+            rstrip = match.group("rstrip") == "-"
+            if lstrip:
+                slot_default = slot_default.lstrip()
+            if rstrip:
+                slot_default = slot_default.rstrip()
+
+            slot_expr = "".join([
+                "{% if _slots.get('", slot_name,
+                "') %}{{ _slots['", slot_name,
+                "'] }}{% else %}", slot_default,
+                "{% endif %}"
+            ])
+            source = f"{source[:start]}{slot_expr}{source[end:]}"
+            slots[slot_name] = 1
+
+        return source, tuple(slots.keys())
+
+    def process_fills(self, source: str) -> str:
+        """
+        Processes `{% fill slot_name %}...{% endfill %}` blocks in the template source code.
+
+        Arguments:
+            source:
+                The template source code.
+
+        Returns:
+            The modified source code prepended by fill contents as `if` statements.
+
+        """
+        fills = {}
+
+        while True:
+            match = RX_FILL.search(source)
+            if not match:
+                break
+            start, end = match.span(0)
+            fill_name = match.group("name")
+            fill_body = match.group("body") or ""
+            lstrip = match.group("lstrip") == "-"
+            rstrip = match.group("rstrip") == "-"
+            if lstrip:
+                fill_body = fill_body.lstrip()
+            if rstrip:
+                fill_body = fill_body.rstrip()
+            fills[fill_name] = fill_body
+            source = f"{source[:start]}{source[end:]}"
+
+        if not fills:
+            return source
+
+        ifs = []
+        for fill_name, fill_body in fills.items():
+            ifs.append(f"{{% elif _slot == '{fill_name}' %}}{fill_body}")
+        # Replace the first occurrence of "elif" with "if"
+        str_ifs = f"\n{{% {''.join(ifs)[5:]}"
+
+        return f"{str_ifs}{{% else -%}}\n{source.strip()}\n{{%- endif %}}\n"
+
     # Private
 
     def _parse_opening_tag(
diff --git a/tests/test_parser.py b/tests/test_parser.py
diff --git a/tests/test_slots.py b/tests/test_slots.py
