pyjinhx 0.2.2__py3-none-any.whl

pyjinhx-0.2.2.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: pyjinhx
+Version: 0.2.2
+Summary: UI components for Python using Pydantic and Jinja2 templates
+Project-URL: Homepage, https://github.com/paulomtts/pyjinhx
+Author-email: Paulo Mattos <paulomtts@outlook.com>
+License: MIT
+License-File: LICENSE.txt
+Keywords: ,components,jinja2,pydantic,templates,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: markupsafe>=3.0.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pytest>=9.0.1
+Description-Content-Type: text/markdown
+
+# PyJinHx
+
+Build reusable, type-safe UI components for template-based web apps in Python. PyJinHx combines Pydantic models with Jinja2 templates to give you template discovery, component composition, and JavaScript bundling.
+
+- **Automatic Template Discovery**: Place templates next to component files—no manual paths
+- **JavaScript Bundling**: Automatically collects and bundles `.js` files from component directories
+- **Composability**: Nest components easily—works with single components, lists, and dictionaries
+- **Flexible**: Use Python classes for reusable components, HTML syntax for quick page composition
+- **Type Safety**: Pydantic models provide validation and IDE support
+
+## Installation
+
+```bash
+pip install pyjinhx
+```
+
+## Example
+
+This single example shows the full setup (Python classes + templates) and both ways to render:
+
+- Python-side: instantiate a component class and call `.render()`.
+- Template-side: render an HTML-like string with custom tags via `Renderer`.
+
+### Step 1: Define component classes
+
+```python
+# components/ui/button.py
+from pyjinhx import BaseComponent
+
+
+class Button(BaseComponent):
+    id: str
+    text: str
+    variant: str = "default"
+```
+
+```python
+# components/ui/card.py
+from pyjinhx import BaseComponent
+from components.ui.button import Button
+
+
+class Card(BaseComponent):
+    id: str
+    title: str
+    action_button: Button
+```
+
+```python
+# components/ui/page.py
+from pyjinhx import BaseComponent
+from components.ui.card import Card
+
+
+class Page(BaseComponent):
+    id: str
+    title: str
+    main_card: Card
+```
+
+### Step 2: Create templates (auto-discovered next to the class files)
+
+```html
+<!-- components/ui/button.html -->
+<button id="{{ id }}" class="btn btn-{{ variant }}">{{ text }}</button>
+```
+
+```html
+<!-- components/ui/card.html -->
+<div id="{{ id }}" class="card">
+  <h2>{{ title }}</h2>
+  <div class="action">{{ action_button }}</div>
+</div>
+```
+
+```html
+<!-- components/ui/page.html -->
+<main id="{{ id }}">
+  <h1>{{ title }}</h1>
+  {{ main_card }}
+</main>
+```
+
+### Step 3A: Python-side rendering (`BaseComponent.render()`)
+
+```python
+from components.ui.button import Button
+from components.ui.card import Card
+from components.ui.page import Page
+
+page = Page(
+    id="home",
+    title="Welcome",
+    main_card=Card(
+        id="hero",
+        title="Get Started",
+        action_button=Button(id="cta", text="Sign up", variant="primary"),
+    ),
+)
+
+html = page.render()
+```
+
+### Step 3B: Template-side rendering (`Renderer(...).render(source)`)
+
+```python
+from pyjinhx import Renderer
+
+renderer = Renderer("./components", auto_id=True)
+
+html = renderer.render(
+    """
+    <Page title="Welcome">
+      <Card title="Get Started">
+        <Button text="Sign up" variant="primary"/>
+      </Card>
+    </Page>
+    """
+)
+```
+
+Template-side rendering supports:
+
+- Type safety for registered classes: if `Button(BaseComponent)` exists, its fields are validated when `<Button .../>` is instantiated.
+- Generic tags: if there is no registered class, a generic `BaseComponent` is used as long as the template file can be found.
+
+## JavaScript & extra assets
+
+- Component-local JS: if a component class `MyWidget` has a sibling file `my-widget.js`, it is auto-collected and injected once at the root render level.
+- Extra JS: pass `js=[...]` with file paths; missing files are ignored.
+- Extra HTML files: pass `html=[...]` with file paths; they are rendered and exposed in the template context by filename stem (e.g. `extra_content.html` → `extra_content.html` wrapper). Missing files raise `FileNotFoundError`.
+
+## FastAPI + HTMX example
+
+### Component class
+
+```python
+# components/ui/button.py
+from pyjinhx import BaseComponent
+
+
+class Button(BaseComponent):
+    id: str
+    text: str
+```
+
+### Component template (with HTMX)
+
+```html
+<!-- components/ui/button.html -->
+<button
+  id="{{ id }}"
+  hx-post="/clicked"
+  hx-vals='{"button_id": "{{ id }}"}'
+  hx-target="#click-result"
+  hx-swap="innerHTML"
+>
+  {{ text }}
+</button>
+```
+
+### FastAPI app (two routes)
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+
+from components.ui.button import Button
+
+app = FastAPI()
+
+
+@app.get("/button", response_class=HTMLResponse)
+def button() -> str:
+    return (
+        Button(id="save-btn", text="Click me").render()
+        + '<div id="click-result"></div>'
+    )
+
+
+@app.post("/clicked", response_class=HTMLResponse)
+def clicked(button_id: str = "unknown") -> str:
+    return f"Clicked: {button_id}"
+```

pyjinhx-0.2.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyjinhx/__init__.py,sha256=A5rqiFbZmPs1Jn4839YAn4dQvCA0Sqp2xNX1uMRpTbg,284
+pyjinhx/base.py,sha256=izBK3nDs0Sz2KNzMEJ1687TxftUduqSIcrRoC08p80s,6205
+pyjinhx/dataclasses.py,sha256=0I-CxvF0uw3x8mGBQXyUNtBy8NEBlgAAYSfjNzW_Mn8,598
+pyjinhx/finder.py,sha256=q6jBwO6MXmL__lNV9h4Ok6JROkAIjfTLwDvxGddaOo4,8370
+pyjinhx/parser.py,sha256=doXdz9Nmru93sUVbT4zGOg_LdxL9SLUiz7Oxgyfl_Jo,2522
+pyjinhx/registry.py,sha256=hSaf5DL0vcHBMj2ptyxh4-CizoFaFzWQXBPIho76ARs,2936
+pyjinhx/renderer.py,sha256=bH2C5uVM0tyAaQJUgaHiBuobVqcNNcSYRopxtNxOO6Y,14790
+pyjinhx/utils.py,sha256=PjMRM6tN7mq4LqegPaLKldqmdSPGXuzVl99hPb5up4Q,3136
+pyjinhx-0.2.2.dist-info/METADATA,sha256=Xz172df41cPQi7s6U52BPE9TpZZUzhp-eU6HIHWbcto,5250
+pyjinhx-0.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pyjinhx-0.2.2.dist-info/licenses/LICENSE.txt,sha256=D-n1hyHpOIRpR8OPEIOPNW_PrynmPjkNVilwGo2J104,1068
+pyjinhx-0.2.2.dist-info/RECORD,,

pyjinhx-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyjinhx-0.2.2.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paulo Mattos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.