htmlforge 0.0.1__tar.gz → 0.0.2__tar.gz

{htmlforge-0.0.1 → htmlforge-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htmlforge
-Version: 0.0.1
+Version: 0.0.2
 Summary: Build web pages with Python, export to HTML with a single command
 Project-URL: Homepage, https://github.com/htmlforge/htmlforge
 Author: htmlforge contributors
@@ -21,8 +21,9 @@ Description-Content-Type: text/markdown
 Build web pages with Python, export to HTML with a single command — like manim generates videos.
 
 ```
-manim   scene.py MyScene  →  mp4
-htmlforge    page.py  MyPage   →  html
+manim       scene.py MyScene       →  mp4
+htmlforge   page.py  MyPage        →  html
+htmlforge   script   app.py        →  js
 ```
 
 ## Installation
@@ -31,12 +32,6 @@ htmlforge    page.py  MyPage   →  html
 pip install htmlforge
 ```
 
-Development install:
-
-```bash
-pip install -e ".[dev]"
-```
-
 ## Quick Start
 
 ### 1. Write a Python page script `mysite.py`
@@ -46,7 +41,7 @@ from htmlforge import Doc
 
 page = Doc("My Site")
 
-# Generate styles with Python code (no CSS needed!)
+# Generate styles with Python kwargs (no CSS strings!)
 page.style("body", background="#f5f5f5", font_family="sans-serif")
 page.style(".py-card", border_radius="12px", box_shadow="0 2px 8px rgba(0,0,0,.1)")
 
@@ -65,7 +60,7 @@ page.table(
     [
         ["Components", "40+ HTML components"],
         ["Built-in theme", "Works out of the box"],
-        ["CLI tools", "render / serve / watch"],
+        ["CLI tools", "render / serve / watch / script"],
     ],
 )
 
@@ -101,6 +96,9 @@ htmlforge render mysite.py MyPage
 | `htmlforge render <file.py> -s` | Start HTTP server after render |
 | `htmlforge render <file.py> -s -p 3000` | Specify server port |
 | `htmlforge render <file.py> -w` | Watch for changes and auto-rebuild |
+| `htmlforge script <file.py>` | Convert Python file to JavaScript |
+| `htmlforge script <file.py> -o app.js` | Specify output JS filename |
+| `htmlforge script <file.py> --helpers` | Include DOM helper functions |
 
 ## Doc API — Ultra Simple
 
@@ -135,6 +133,124 @@ page.divider()
 page.row(Doc.make_card("A"), Doc.make_card("B"), Doc.make_card("C"))
 ```
 
+## JavaScript & DOM Interaction
+
+### Bind events to elements
+
+```python
+from htmlforge import Button
+
+btn = Button("Click me")
+
+# Bind raw JavaScript
+btn.on("click", "alert('hello')")
+btn.on("mouseover", "this.style.color='red'")
+
+# Bind Python code (auto-converted to JS)
+btn.on_py("click", "print('clicked!')")
+# → onclick="console.log('clicked!');"
+```
+
+### Add JavaScript to the page
+
+```python
+# Raw JavaScript
+page.js("document.title = 'Dynamic'")
+page.js("function greet() { alert('hello'); }")
+
+# External JS file
+page.js_file("app.js")
+
+# Python code → JavaScript (auto-converted)
+page.py_script('''
+def greet(name):
+    print(f"Hello {name}")
+greet("World")
+''')
+
+# Run on page load (DOMContentLoaded)
+page.on_ready("console.log('Page loaded!')")
+page.on_ready_py('print("Ready!")')
+```
+
+### DOM manipulation helpers
+
+```python
+# Get element properties (returns JS expressions)
+val   = page.get_attr("#input", "value")   # → document.querySelector('#input').getAttribute('value')
+text  = page.get_text("#title")            # → document.querySelector('#title').textContent
+html  = page.get_html("#content")          # → document.querySelector('#content').innerHTML
+value = page.get_value("#myInput")         # → document.querySelector('#myInput').value
+
+# Set element properties (generates JS scripts)
+page.set_attr("#el", "class", "active")
+page.set_text("#title", "New Title")
+page.set_html("#content", "<b>bold</b>")
+page.set_value("#input", "hello")
+
+# Visibility
+page.show("#modal")
+page.hide("#loading")
+page.toggle("#sidebar")
+
+# CSS class manipulation
+page.add_class("#el", "active")
+page.remove_class("#el", "hidden")
+page.toggle_class("#menu", "open")
+```
+
+## Python → JavaScript Transpiler
+
+Use `htmlforge script` to convert Python files to JavaScript:
+
+```bash
+htmlforge script app.py            # → app.js
+htmlforge script app.py -o out.js  # → out.js
+htmlforge script app.py --helpers  # include DOM helpers ($, $$, getAttr, setAttr, ...)
+```
+
+Or use it programmatically:
+
+```python
+from htmlforge import py_to_js, convert_file
+
+# Convert Python source string to JS
+js = py_to_js("""
+def greet(name):
+    print(f"Hello {name}")
+
+for i in range(10):
+    greet("World")
+""")
+
+# Convert a file
+convert_file("app.py", "app.js")
+```
+
+### Supported Python → JS conversions
+
+| Python | JavaScript |
+|---|---|
+| `print(...)` | `console.log(...)` |
+| `input(...)` | `prompt(...)` |
+| `def f(x):` | `function f(x) {` |
+| `class Foo(Bar):` | `class Foo extends Bar {` |
+| `self.x` | `this.x` |
+| `if/elif/else:` | `if/else if/else {` |
+| `for i in range(n):` | `for (let i = 0; i < n; i++) {` |
+| `for x in items:` | `for (let x of items) {` |
+| `while cond:` | `while (cond) {` |
+| `try/except/finally:` | `try/catch/finally {` |
+| `True / False / None` | `true / false / null` |
+| `and / or / not` | `&& / \|\| / !` |
+| `a // b` | `Math.floor(a / b)` |
+| `a ** b` | `Math.pow(a, b)` |
+| `len(x)` | `x.length` |
+| `f"Hello {name}"` | `` `Hello ${name}` `` |
+| `lambda x: x + 1` | `(x) => x + 1` |
+| `x in items` | `items.includes(x)` |
+| `sorted(items)` | `[...items].sort()` |
+
 ## Page API — Fine-grained Control
 
 Use `Page` + the component system when you need more control:
@@ -161,6 +277,8 @@ div = Div(id="main", class_="wrapper")
 div.add(H1("Title"), P("Content"))          # Add child elements
 div.css(color="red", font_size="16px")      # Set inline styles (camelCase → kebab-case)
 div.attr("data-id", "123")                  # Set attributes
+div.on("click", "alert('clicked')")         # Bind JS event
+div.on_py("click", "print('clicked')")      # Bind Python event (auto-converted)
 html = div.render()                          # → HTML string
 ```
 

{htmlforge-0.0.1 → htmlforge-0.0.2}/README.md

@@ -3,8 +3,9 @@
 Build web pages with Python, export to HTML with a single command — like manim generates videos.
 
 ```
-manim   scene.py MyScene  →  mp4
-htmlforge    page.py  MyPage   →  html
+manim       scene.py MyScene       →  mp4
+htmlforge   page.py  MyPage        →  html
+htmlforge   script   app.py        →  js
 ```
 
 ## Installation
@@ -13,12 +14,6 @@ htmlforge    page.py  MyPage   →  html
 pip install htmlforge
 ```
 
-Development install:
-
-```bash
-pip install -e ".[dev]"
-```
-
 ## Quick Start
 
 ### 1. Write a Python page script `mysite.py`
@@ -28,7 +23,7 @@ from htmlforge import Doc
 
 page = Doc("My Site")
 
-# Generate styles with Python code (no CSS needed!)
+# Generate styles with Python kwargs (no CSS strings!)
 page.style("body", background="#f5f5f5", font_family="sans-serif")
 page.style(".py-card", border_radius="12px", box_shadow="0 2px 8px rgba(0,0,0,.1)")
 
@@ -47,7 +42,7 @@ page.table(
     [
         ["Components", "40+ HTML components"],
         ["Built-in theme", "Works out of the box"],
-        ["CLI tools", "render / serve / watch"],
+        ["CLI tools", "render / serve / watch / script"],
     ],
 )
 
@@ -83,6 +78,9 @@ htmlforge render mysite.py MyPage
 | `htmlforge render <file.py> -s` | Start HTTP server after render |
 | `htmlforge render <file.py> -s -p 3000` | Specify server port |
 | `htmlforge render <file.py> -w` | Watch for changes and auto-rebuild |
+| `htmlforge script <file.py>` | Convert Python file to JavaScript |
+| `htmlforge script <file.py> -o app.js` | Specify output JS filename |
+| `htmlforge script <file.py> --helpers` | Include DOM helper functions |
 
 ## Doc API — Ultra Simple
 
@@ -117,6 +115,124 @@ page.divider()
 page.row(Doc.make_card("A"), Doc.make_card("B"), Doc.make_card("C"))
 ```
 
+## JavaScript & DOM Interaction
+
+### Bind events to elements
+
+```python
+from htmlforge import Button
+
+btn = Button("Click me")
+
+# Bind raw JavaScript
+btn.on("click", "alert('hello')")
+btn.on("mouseover", "this.style.color='red'")
+
+# Bind Python code (auto-converted to JS)
+btn.on_py("click", "print('clicked!')")
+# → onclick="console.log('clicked!');"
+```
+
+### Add JavaScript to the page
+
+```python
+# Raw JavaScript
+page.js("document.title = 'Dynamic'")
+page.js("function greet() { alert('hello'); }")
+
+# External JS file
+page.js_file("app.js")
+
+# Python code → JavaScript (auto-converted)
+page.py_script('''
+def greet(name):
+    print(f"Hello {name}")
+greet("World")
+''')
+
+# Run on page load (DOMContentLoaded)
+page.on_ready("console.log('Page loaded!')")
+page.on_ready_py('print("Ready!")')
+```
+
+### DOM manipulation helpers
+
+```python
+# Get element properties (returns JS expressions)
+val   = page.get_attr("#input", "value")   # → document.querySelector('#input').getAttribute('value')
+text  = page.get_text("#title")            # → document.querySelector('#title').textContent
+html  = page.get_html("#content")          # → document.querySelector('#content').innerHTML
+value = page.get_value("#myInput")         # → document.querySelector('#myInput').value
+
+# Set element properties (generates JS scripts)
+page.set_attr("#el", "class", "active")
+page.set_text("#title", "New Title")
+page.set_html("#content", "<b>bold</b>")
+page.set_value("#input", "hello")
+
+# Visibility
+page.show("#modal")
+page.hide("#loading")
+page.toggle("#sidebar")
+
+# CSS class manipulation
+page.add_class("#el", "active")
+page.remove_class("#el", "hidden")
+page.toggle_class("#menu", "open")
+```
+
+## Python → JavaScript Transpiler
+
+Use `htmlforge script` to convert Python files to JavaScript:
+
+```bash
+htmlforge script app.py            # → app.js
+htmlforge script app.py -o out.js  # → out.js
+htmlforge script app.py --helpers  # include DOM helpers ($, $$, getAttr, setAttr, ...)
+```
+
+Or use it programmatically:
+
+```python
+from htmlforge import py_to_js, convert_file
+
+# Convert Python source string to JS
+js = py_to_js("""
+def greet(name):
+    print(f"Hello {name}")
+
+for i in range(10):
+    greet("World")
+""")
+
+# Convert a file
+convert_file("app.py", "app.js")
+```
+
+### Supported Python → JS conversions
+
+| Python | JavaScript |
+|---|---|
+| `print(...)` | `console.log(...)` |
+| `input(...)` | `prompt(...)` |
+| `def f(x):` | `function f(x) {` |
+| `class Foo(Bar):` | `class Foo extends Bar {` |
+| `self.x` | `this.x` |
+| `if/elif/else:` | `if/else if/else {` |
+| `for i in range(n):` | `for (let i = 0; i < n; i++) {` |
+| `for x in items:` | `for (let x of items) {` |
+| `while cond:` | `while (cond) {` |
+| `try/except/finally:` | `try/catch/finally {` |
+| `True / False / None` | `true / false / null` |
+| `and / or / not` | `&& / \|\| / !` |
+| `a // b` | `Math.floor(a / b)` |
+| `a ** b` | `Math.pow(a, b)` |
+| `len(x)` | `x.length` |
+| `f"Hello {name}"` | `` `Hello ${name}` `` |
+| `lambda x: x + 1` | `(x) => x + 1` |
+| `x in items` | `items.includes(x)` |
+| `sorted(items)` | `[...items].sort()` |
+
 ## Page API — Fine-grained Control
 
 Use `Page` + the component system when you need more control:
@@ -143,6 +259,8 @@ div = Div(id="main", class_="wrapper")
 div.add(H1("Title"), P("Content"))          # Add child elements
 div.css(color="red", font_size="16px")      # Set inline styles (camelCase → kebab-case)
 div.attr("data-id", "123")                  # Set attributes
+div.on("click", "alert('clicked')")         # Bind JS event
+div.on_py("click", "print('clicked')")      # Bind Python event (auto-converted)
 html = div.render()                          # → HTML string
 ```
 

{htmlforge-0.0.1 → htmlforge-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "htmlforge"
-version = "0.0.1"
+version = "0.0.2"
 description = "Build web pages with Python, export to HTML with a single command"
 readme = "README.md"
 license = "MPL-2.0"

{htmlforge-0.0.1 → htmlforge-0.0.2}/src/htmlforge/__init__.py

@@ -1,8 +1,9 @@
 """htmlforge — Build web pages with Python, export to HTML."""
 
-__version__ = "0.0.1"
+__version__ = "0.0.2"
 
 from htmlforge.simple import Doc
+from htmlforge.transpiler import py_to_js, convert_file, JS_HELPERS
 
 from htmlforge.core import (
     # Base

{htmlforge-0.0.1 → htmlforge-0.0.2}/src/htmlforge/cli.py

@@ -4,10 +4,12 @@ Commands:
     htmlforge render <file.py> [page]  -o <dir>    Render pages to HTML
     htmlforge render <file.py>         -p <port>   Render and serve locally
     htmlforge render <file.py>         -w          Watch and auto-rebuild
+    htmlforge script <file.py> [-o <file.js>]      Convert Python to JavaScript
 
 Workflow is modelled after *manim*:
     manim scene.py MyScene -qh  →  mp4
     htmlforge  page.py  MyPage  -o dist  →  html
+    htmlforge script app.py -o app.js    →  js
 """
 
 from __future__ import annotations
@@ -24,6 +26,7 @@ from pathlib import Path
 
 from htmlforge.core import Page
 from htmlforge.simple import Doc
+from htmlforge.transpiler import convert_file as _convert_py_to_js
 
 
 # ============================================================
@@ -36,27 +39,45 @@ def render():
         prog="htmlforge",
         description="htmlforge — Build web pages with Python",
     )
-    ap.add_argument(
-        "command", nargs="?", default="render",
-        help="Command: render (default)",
-    )
-    ap.add_argument("file", help="Python file containing Page objects")
-    ap.add_argument(
-        "page", nargs="?", default=None,
-        help="Specific page variable or class name to render",
-    )
-    ap.add_argument("-o", "--output", default="dist", help="Output directory (default: dist)")
-    ap.add_argument("-p", "--port", type=int, default=8080, help="Server port (default: 8080)")
-    ap.add_argument("-w", "--watch", action="store_true", help="Watch file for changes")
-    ap.add_argument("-s", "--serve", action="store_true", help="Start HTTP server after build")
-    ap.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
+    sub = ap.add_subparsers(dest="command", help="Command to run")
+    sub.required = False
+
+    # ---- render ----
+    render_p = sub.add_parser("render", help="Render pages to HTML")
+    render_p.add_argument("file", help="Python file containing Page objects")
+    render_p.add_argument("page", nargs="?", default=None,
+                          help="Specific page variable or class name to render")
+    render_p.add_argument("-o", "--output", default="dist",
+                          help="Output directory (default: dist)")
+    render_p.add_argument("-p", "--port", type=int, default=8080,
+                          help="Server port (default: 8080)")
+    render_p.add_argument("-w", "--watch", action="store_true",
+                          help="Watch file for changes")
+    render_p.add_argument("-s", "--serve", action="store_true",
+                          help="Start HTTP server after build")
+    render_p.add_argument("-v", "--verbose", action="store_true",
+                          help="Verbose output")
+
+    # ---- script ----
+    script_p = sub.add_parser("script", help="Convert Python file to JavaScript")
+    script_p.add_argument("file", help="Python file to convert")
+    script_p.add_argument("-o", "--output", default=None,
+                          help="Output JS file (default: same name .js)")
+    script_p.add_argument("--helpers", action="store_true",
+                          help="Include DOM helper functions")
 
     args = ap.parse_args()
 
     if args.command == "render":
         _do_render(args)
+    elif args.command == "script":
+        _do_script(args)
     else:
-        ap.print_help()
+        # Backward compat: first positional arg is a file
+        if hasattr(args, 'file') and args.file:
+            _do_render(args)
+        else:
+            ap.print_help()
 
 
 # ============================================================
@@ -157,6 +178,34 @@ def _watch_loop(filepath: Path, page_name: str | None,
         _info("\n  Watch stopped.")
 
 
+# ============================================================
+# Script (Python → JS)
+# ============================================================
+
+def _do_script(args):
+    filepath = Path(args.file).resolve()
+    if not filepath.exists():
+        _err(f"File not found: {filepath}")
+        sys.exit(1)
+
+    output = args.output
+    if output is None:
+        output = str(filepath.with_suffix(".js"))
+
+    try:
+        from htmlforge.transpiler import py_to_js, JS_HELPERS
+        source = filepath.read_text(encoding="utf-8")
+        js_code = py_to_js(source)
+        if args.helpers:
+            js_code = JS_HELPERS + "\n\n" + js_code
+        Path(output).write_text(js_code, encoding="utf-8")
+        _ok(f"  {filepath.name} → {Path(output).name}")
+        _info(f"Done. JavaScript written to {output}")
+    except Exception as exc:
+        _err(f"Conversion failed: {exc}")
+        sys.exit(1)
+
+
 # ============================================================
 # Helpers
 # ============================================================

{htmlforge-0.0.1 → htmlforge-0.0.2}/src/htmlforge/core.py

@@ -54,6 +54,33 @@ class Element:
         self.attrs.pop(key, None)
         return self
 
+    def on(self, event: str, handler: str) -> Element:
+        """Bind an event handler (raw JS code).
+
+        ::
+
+            btn.on("click", "alert('hello')")
+            btn.on("mouseover", "this.style.color='red'")
+        """
+        attr_name = f"on{event}"
+        existing = self.attrs.get(attr_name, "")
+        if existing:
+            self.attrs[attr_name] = f"{existing}; {handler}"
+        else:
+            self.attrs[attr_name] = handler
+        return self
+
+    def on_py(self, event: str, py_code: str) -> Element:
+        """Bind an event handler written in Python (converted to JS).
+
+        ::
+
+            btn.on_py("click", "print('clicked')")
+        """
+        from htmlforge.transpiler import py_to_js
+        js_code = py_to_js(py_code)
+        return self.on(event, js_code)
+
     # --- rendering ---
 
     def _open_tag(self) -> str:

{htmlforge-0.0.1 → htmlforge-0.0.2}/src/htmlforge/simple.py

@@ -304,6 +304,126 @@ class Doc:
         """Add a horizontal rule."""
         return self.add(Hr())
 
+    # ---- JavaScript & DOM helpers ----
+
+    def js(self, code: str) -> Doc:
+        """Add raw JavaScript code to the page.
+
+        ::
+
+            page.js("document.title = 'Dynamic'")
+            page.js("function greet() { alert('hello'); }")
+        """
+        self._page.add_script(code=code)
+        return self
+
+    def js_file(self, src: str) -> Doc:
+        """Link an external JavaScript file."""
+        self._page.add_script(src=src)
+        return self
+
+    def py_script(self, code: str) -> Doc:
+        """Add Python code that gets converted to JavaScript.
+
+        ::
+
+            page.py_script('def greet(name): print(name)')
+        """
+        from htmlforge.transpiler import py_to_js
+        js_code = py_to_js(code)
+        self._page.add_script(code=js_code)
+        return self
+
+    def on_ready(self, js_code: str) -> Doc:
+        """Run JS code when the page loads (DOMContentLoaded)."""
+        wrapped = f"document.addEventListener('DOMContentLoaded', function() {{\n{js_code}\n}});"
+        self._page.add_script(code=wrapped)
+        return self
+
+    def on_ready_py(self, py_code: str) -> Doc:
+        """Run Python code (converted to JS) when the page loads."""
+        from htmlforge.transpiler import py_to_js
+        js_code = py_to_js(py_code)
+        return self.on_ready(js_code)
+
+    # ---- DOM attribute helpers (generate JS) ----
+
+    def get_attr(self, selector: str, attr: str) -> str:
+        """Return JS expression to get an element's attribute.
+
+        ::
+
+            page.js(f"let val = {page.get_attr('#myInput', 'value')}")
+        """
+        return f"document.querySelector('{selector}').getAttribute('{attr}')"
+
+    def set_attr(self, selector: str, attr: str, value: str) -> Doc:
+        """Add JS code to set an element's attribute."""
+        self.js(f"document.querySelector('{selector}').setAttribute('{attr}', '{value}');")
+        return self
+
+    def get_text(self, selector: str) -> str:
+        """Return JS expression to get element's text content."""
+        return f"document.querySelector('{selector}').textContent"
+
+    def set_text(self, selector: str, text: str) -> Doc:
+        """Add JS code to set element's text content."""
+        self.js(f"document.querySelector('{selector}').textContent = '{text}';")
+        return self
+
+    def get_html(self, selector: str) -> str:
+        """Return JS expression to get element's innerHTML."""
+        return f"document.querySelector('{selector}').innerHTML"
+
+    def set_html(self, selector: str, html: str) -> Doc:
+        """Add JS code to set element's innerHTML."""
+        self.js(f"document.querySelector('{selector}').innerHTML = `{html}`;")
+        return self
+
+    def get_value(self, selector: str) -> str:
+        """Return JS expression to get an input's value."""
+        return f"document.querySelector('{selector}').value"
+
+    def set_value(self, selector: str, value: str) -> Doc:
+        """Add JS code to set an input's value."""
+        self.js(f"document.querySelector('{selector}').value = '{value}';")
+        return self
+
+    def show(self, selector: str) -> Doc:
+        """Add JS code to show an element."""
+        self.js(f"document.querySelector('{selector}').style.display = '';")
+        return self
+
+    def hide(self, selector: str) -> Doc:
+        """Add JS code to hide an element."""
+        self.js(f"document.querySelector('{selector}').style.display = 'none';")
+        return self
+
+    def toggle(self, selector: str) -> Doc:
+        """Add JS code to toggle an element's visibility."""
+        self.js(f"""
+(function() {{
+  var el = document.querySelector('{selector}');
+  el.style.display = el.style.display === 'none' ? '' : 'none';
+}})();
+""")
+        return self
+
+    def add_class(self, selector: str, cls: str) -> Doc:
+        """Add JS code to add a CSS class."""
+        self.js(f"document.querySelector('{selector}').classList.add('{cls}');")
+        return self
+
+    def remove_class(self, selector: str, cls: str) -> Doc:
+        """Add JS code to remove a CSS class."""
+        self.js(f"document.querySelector('{selector}').classList.remove('{cls}');")
+        return self
+
+    def toggle_class(self, selector: str, cls: str) -> Doc:
+        """Add JS code to toggle a CSS class."""
+        self.js(f"document.querySelector('{selector}').classList.toggle('{cls}');")
+        return self
+
     # ---- style (programmatic CSS) ----
 
     def style(self, selector: str, **props: str) -> Doc: