htmlforge 0.0.2__tar.gz → 0.0.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htmlforge
-Version: 0.0.2
+Version: 0.0.3
 Summary: Build web pages with Python, export to HTML with a single command
 Project-URL: Homepage, https://github.com/htmlforge/htmlforge
 Author: htmlforge contributors
@@ -96,6 +96,7 @@ 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 render <file.py> -s -w` | Serve + watch, browser auto-reloads on change |
 | `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 |
@@ -129,10 +130,84 @@ page.details("Collapsible", "Hidden content...")
 page.nav(("Home", "/"), ("About", "/about"))
 page.divider()
 
-# Layout
+# Row / grid
 page.row(Doc.make_card("A"), Doc.make_card("B"), Doc.make_card("C"))
+
+# Head / SEO
+page.set_meta(description="My site", author="Me", keywords="python, web")
+page.meta("My Site", property="og:title")
+page.favicon("favicon.ico")
+```
+
+## Block-level Markdown
+
+`page.markdown()` renders full Markdown — not just inline — including headings,
+lists, fenced code, tables, blockquotes and rules:
+
+```python
+page.markdown('''
+# Release Notes
+
+- **Fast** rendering
+- Zero dependencies
+
+| Command | Purpose |
+|---------|---------|
+| render  | Build HTML |
+
+> Tip: pull in a whole README with `markdown_file`.
+''')
+
+# Or load straight from a file
+page.markdown_file("README.md")
 ```
 
+## Static Assets
+
+`page.asset()` registers a local file (image / css / js). It returns the URL to
+reference, and `htmlforge render` copies the file into `dist/assets/` so the
+exported site is fully self-contained:
+
+```python
+logo = page.asset("logo.png")          # → "assets/logo.png"
+page.image(logo, "Logo")
+
+page.add_stylesheet(page.asset("theme.css"))
+page.js_file(page.asset("app.js"))
+```
+
+After `htmlforge render site.py`, `dist/` holds both `index.html` and
+`assets/logo.png`.
+
+## Layouts — Share Header / Footer
+
+A `Layout` is a reusable page skeleton: every page built from it shares the
+same head tags, header and footer.
+
+```python
+from htmlforge import Doc, Layout, Div, H1, P
+
+site = Layout(
+    head=lambda doc: doc.set_meta(author="Me"),
+    header=lambda doc: Div(class_="top").add(H1("My Site")),
+    footer=lambda doc: P(f"© 2026 — {doc.title}"),
+)
+
+home = site.page("Home")     # → a Doc with the shared chrome
+home.heading("Welcome")
+
+about = site.page("About")
+about.text("About us...")
+```
+
+```bash
+htmlforge render site.py
+# → dist/home.html, dist/about.html  (both wrapped in the shared header/footer)
+```
+
+Each slot accepts an `Element`, a list of elements, or a callable receiving the
+page — so you can highlight the current nav item, inject the title, and more.
+
 ## JavaScript & DOM Interaction
 
 ### Bind events to elements
@@ -199,6 +274,9 @@ page.remove_class("#el", "hidden")
 page.toggle_class("#menu", "open")
 ```
 
+> **Security:** every selector and value passed to these helpers is
+> automatically escaped, so it is safe to feed them dynamic / user data.
+
 ## Python → JavaScript Transpiler
 
 Use `htmlforge script` to convert Python files to JavaScript:
@@ -318,6 +396,32 @@ htmlforge render site.py
 # → dist/home.html, dist/about.html, dist/blog.html
 ```
 
+## Changelog
+
+### 0.0.3
+
+**Security**
+
+- `_esc` now also escapes single quotes; Markdown links reject
+  `javascript:` / `vbscript:` / `data:text/html` URLs.
+- All DOM helpers (`set_text`, `set_attr`, `set_value`, `add_class`, ...)
+  escape their selectors and values, preventing JS injection and syntax
+  breakage from dynamic data.
+
+**New**
+
+- **SEO / meta:** `page.meta()`, `page.set_meta()`, `page.favicon()`.
+- **Block-level Markdown:** `page.markdown()` / `page.markdown_file()` —
+  headings, lists, fenced code, tables, blockquotes and rules.
+- **Static assets:** `page.asset()` copies local files into `dist/assets/`
+  at build time, so the exported site is self-contained.
+- **Layouts:** reusable `Layout` shares head / header / footer across pages.
+- **Live reload:** `htmlforge render <file> -s -w` auto-refreshes the browser.
+
+**Fixed**
+
+- `Video` builds its `<source>` child correctly (no more fragile `__new__`).
+
 ## License
 
 [MPL-2.0](LICENSE)

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

@@ -78,6 +78,7 @@ 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 render <file.py> -s -w` | Serve + watch, browser auto-reloads on change |
 | `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 |
@@ -111,10 +112,84 @@ page.details("Collapsible", "Hidden content...")
 page.nav(("Home", "/"), ("About", "/about"))
 page.divider()
 
-# Layout
+# Row / grid
 page.row(Doc.make_card("A"), Doc.make_card("B"), Doc.make_card("C"))
+
+# Head / SEO
+page.set_meta(description="My site", author="Me", keywords="python, web")
+page.meta("My Site", property="og:title")
+page.favicon("favicon.ico")
+```
+
+## Block-level Markdown
+
+`page.markdown()` renders full Markdown — not just inline — including headings,
+lists, fenced code, tables, blockquotes and rules:
+
+```python
+page.markdown('''
+# Release Notes
+
+- **Fast** rendering
+- Zero dependencies
+
+| Command | Purpose |
+|---------|---------|
+| render  | Build HTML |
+
+> Tip: pull in a whole README with `markdown_file`.
+''')
+
+# Or load straight from a file
+page.markdown_file("README.md")
 ```
 
+## Static Assets
+
+`page.asset()` registers a local file (image / css / js). It returns the URL to
+reference, and `htmlforge render` copies the file into `dist/assets/` so the
+exported site is fully self-contained:
+
+```python
+logo = page.asset("logo.png")          # → "assets/logo.png"
+page.image(logo, "Logo")
+
+page.add_stylesheet(page.asset("theme.css"))
+page.js_file(page.asset("app.js"))
+```
+
+After `htmlforge render site.py`, `dist/` holds both `index.html` and
+`assets/logo.png`.
+
+## Layouts — Share Header / Footer
+
+A `Layout` is a reusable page skeleton: every page built from it shares the
+same head tags, header and footer.
+
+```python
+from htmlforge import Doc, Layout, Div, H1, P
+
+site = Layout(
+    head=lambda doc: doc.set_meta(author="Me"),
+    header=lambda doc: Div(class_="top").add(H1("My Site")),
+    footer=lambda doc: P(f"© 2026 — {doc.title}"),
+)
+
+home = site.page("Home")     # → a Doc with the shared chrome
+home.heading("Welcome")
+
+about = site.page("About")
+about.text("About us...")
+```
+
+```bash
+htmlforge render site.py
+# → dist/home.html, dist/about.html  (both wrapped in the shared header/footer)
+```
+
+Each slot accepts an `Element`, a list of elements, or a callable receiving the
+page — so you can highlight the current nav item, inject the title, and more.
+
 ## JavaScript & DOM Interaction
 
 ### Bind events to elements
@@ -181,6 +256,9 @@ page.remove_class("#el", "hidden")
 page.toggle_class("#menu", "open")
 ```
 
+> **Security:** every selector and value passed to these helpers is
+> automatically escaped, so it is safe to feed them dynamic / user data.
+
 ## Python → JavaScript Transpiler
 
 Use `htmlforge script` to convert Python files to JavaScript:
@@ -300,6 +378,32 @@ htmlforge render site.py
 # → dist/home.html, dist/about.html, dist/blog.html
 ```
 
+## Changelog
+
+### 0.0.3
+
+**Security**
+
+- `_esc` now also escapes single quotes; Markdown links reject
+  `javascript:` / `vbscript:` / `data:text/html` URLs.
+- All DOM helpers (`set_text`, `set_attr`, `set_value`, `add_class`, ...)
+  escape their selectors and values, preventing JS injection and syntax
+  breakage from dynamic data.
+
+**New**
+
+- **SEO / meta:** `page.meta()`, `page.set_meta()`, `page.favicon()`.
+- **Block-level Markdown:** `page.markdown()` / `page.markdown_file()` —
+  headings, lists, fenced code, tables, blockquotes and rules.
+- **Static assets:** `page.asset()` copies local files into `dist/assets/`
+  at build time, so the exported site is self-contained.
+- **Layouts:** reusable `Layout` shares head / header / footer across pages.
+- **Live reload:** `htmlforge render <file> -s -w` auto-refreshes the browser.
+
+**Fixed**
+
+- `Video` builds its `<source>` child correctly (no more fragile `__new__`).
+
 ## License
 
 [MPL-2.0](LICENSE)

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

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

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

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

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

@@ -19,8 +19,10 @@ import http.server
 import importlib.util
 import os
 import re
+import shutil
 import socketserver
 import sys
+import threading
 import time
 from pathlib import Path
 
@@ -90,20 +92,26 @@ def _do_render(args):
         _err(f"File not found: {filepath}")
         sys.exit(1)
 
+    out_dir = filepath.parent / args.output
+    # Live reload only makes sense when a server is running to poll.
+    livereload = bool(args.serve and args.watch)
+
     # Initial build
-    ok = _build(filepath, args.page, args.output, args.verbose)
+    ok = _build(filepath, args.page, args.output, args.verbose,
+                livereload=livereload)
     if not ok:
         sys.exit(1)
 
     if args.serve:
-        out_dir = filepath.parent / args.output
-        _serve_dir(str(out_dir), args.port)
+        if args.watch:
+            _start_watch_thread(filepath, args.page, args.output, args.verbose)
+        _serve_dir(str(out_dir), args.port, livereload=livereload)
     elif args.watch:
         _watch_loop(filepath, args.page, args.output, args.verbose)
 
 
 def _build(filepath: Path, page_name: str | None,
-           output: str, verbose: bool) -> bool:
+           output: str, verbose: bool, livereload: bool = False) -> bool:
     try:
         mod = _load_module(filepath)
     except Exception as exc:
@@ -131,23 +139,55 @@ def _build(filepath: Path, page_name: str | None,
 
     for name, page in pages.items():
         html = page.render()
+        if livereload:
+            html = _inject_livereload(html)
         fname = "index.html" if len(pages) == 1 else f"{_slug(name)}.html"
         (out_dir / fname).write_text(html, encoding="utf-8")
         _ok(f"  {fname}")
 
+    _copy_assets(filepath.parent, out_dir, pages)
+
+    if livereload:
+        _bump_livereload()
     _info(f"Done. {len(pages)} page(s) → {out_dir}/")
     return True
 
 
+def _copy_assets(base_dir: Path, out_dir: Path, pages: dict):
+    """Copy every file registered via ``page.asset()`` into ``out_dir``."""
+    copied: set = set()
+    for page in pages.values():
+        collect = getattr(page, "_collect_assets", None)
+        if not collect:
+            continue
+        for src, rel in collect():
+            if (src, rel) in copied:
+                continue
+            copied.add((src, rel))
+            src_path = Path(src)
+            if not src_path.is_absolute():
+                src_path = (base_dir / src).resolve()
+            if not src_path.exists():
+                _err(f"  Asset not found, skipped: {src}")
+                continue
+            dst_path = out_dir / rel
+            dst_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_path, dst_path)
+            _ok(f"  {rel}")
+
+
 # ============================================================
 # Serve
 # ============================================================
 
-def _serve_dir(directory: str, port: int):
+def _serve_dir(directory: str, port: int, livereload: bool = False):
     os.chdir(directory)
-    Handler = http.server.SimpleHTTPRequestHandler
+    Handler = _make_handler(livereload)
+    socketserver.TCPServer.allow_reuse_address = True
     with socketserver.TCPServer(("", port), Handler) as httpd:
         _info(f"  Serving at http://localhost:{port}")
+        if livereload:
+            _info("  Live reload on — save the file to refresh the browser.")
         _info("  Press Ctrl+C to stop.")
         try:
             httpd.serve_forever()
@@ -155,12 +195,38 @@ def _serve_dir(directory: str, port: int):
             _info("\n  Server stopped.")
 
 
+def _make_handler(livereload: bool):
+    """HTTP handler; optionally answers ``/__livereload`` with the version."""
+
+    class Handler(http.server.SimpleHTTPRequestHandler):
+        def do_GET(self):
+            path = self.path.split("?", 1)[0]
+            if livereload and path == "/__livereload":
+                body = str(_LIVERELOAD_STATE["version"]).encode("utf-8")
+                self.send_response(200)
+                self.send_header("Content-Type", "text/plain")
+                self.send_header("Cache-Control", "no-store")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+                return
+            super().do_GET()
+
+        def log_message(self, fmt, *fmt_args):
+            # Keep the 1 Hz polling requests out of the console.
+            if livereload and fmt_args and "/__livereload" in str(fmt_args[0]):
+                return
+            super().log_message(fmt, *fmt_args)
+
+    return Handler
+
+
 # ============================================================
 # Watch
 # ============================================================
 
 def _watch_loop(filepath: Path, page_name: str | None,
-                output: str, verbose: bool):
+                output: str, verbose: bool, livereload: bool = False):
     _info("  Watching for changes… (Ctrl+C to stop)")
     last = filepath.stat().st_mtime
     try:
@@ -173,11 +239,62 @@ def _watch_loop(filepath: Path, page_name: str | None,
             if cur != last:
                 last = cur
                 _info(f"  Change detected — {time.strftime('%H:%M:%S')}")
-                _build(filepath, page_name, output, verbose)
+                _build(filepath, page_name, output, verbose,
+                       livereload=livereload)
     except KeyboardInterrupt:
         _info("\n  Watch stopped.")
 
 
+def _start_watch_thread(filepath: Path, page_name: str | None,
+                        output: str, verbose: bool) -> threading.Thread:
+    """Run :func:`_watch_loop` in a daemon thread (used with ``-s -w``)."""
+    t = threading.Thread(
+        target=_watch_loop,
+        args=(filepath, page_name, output, verbose),
+        kwargs={"livereload": True},
+        daemon=True,
+    )
+    t.start()
+    return t
+
+
+# ============================================================
+# Live reload
+# ============================================================
+
+_LIVERELOAD_STATE = {"version": 0}
+
+LIVERELOAD_SNIPPET = """<script>
+(function () {
+  var current = null;
+  function poll() {
+    fetch('/__livereload')
+      .then(function (r) { return r.text(); })
+      .then(function (v) {
+        if (current === null) { current = v; }
+        else if (v !== current) { location.reload(); }
+      })
+      .catch(function () {})
+      .then(function () { setTimeout(poll, 1000); });
+  }
+  poll();
+})();
+</script>"""
+
+
+def _bump_livereload():
+    """Advance the version so connected browsers reload."""
+    _LIVERELOAD_STATE["version"] += 1
+
+
+def _inject_livereload(html: str) -> str:
+    """Insert the polling snippet just before ``</body>``."""
+    idx = html.rfind("</body>")
+    if idx == -1:
+        return html + LIVERELOAD_SNIPPET
+    return html[:idx] + LIVERELOAD_SNIPPET + "\n" + html[idx:]
+
+
 # ============================================================
 # Script (Python → JS)
 # ============================================================

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

@@ -278,7 +278,7 @@ class Video(Element):
     def __init__(self, src: str = "", controls: bool = True, **attrs: str):
         super().__init__(**attrs)
         if src:
-            self.children.append(Element.__new__(Source).__init_tag(src))
+            self.children.append(Source(src))
         if controls:
             self.attrs["controls"] = ""
 
@@ -305,12 +305,6 @@ class Source(Element):
         if type_:
             self.attrs["type"] = type_
 
-    def __init_tag(self, src: str) -> Source:
-        """Internal fast-init used by Video."""
-        self.children = []
-        self.attrs = {"src": src}
-        return self
-
 
 class Iframe(Element):
     tag = "iframe"
@@ -571,6 +565,10 @@ class Page:
         self._script_srcs: list[str] = []
         self._ext_css: list[str] = []
         self._meta_tags: list[str] = []
+        self._head_links: list[str] = []
+        self._assets: list[tuple[str, str]] = []
+        self._body_prefix: list[Union[Element, str]] = []
+        self._body_suffix: list[Union[Element, str]] = []
 
     # --- CSS ---
 
@@ -584,6 +582,75 @@ class Page:
         self._ext_css.append(href)
         return self
 
+    # --- meta / SEO ---
+
+    def meta(self, content: str, *, name: str = "", property: str = "",
+             **attrs: str) -> Page:
+        """Add a ``<meta>`` tag.
+
+        ::
+
+            page.meta("A great site", name="description")
+            page.meta("My Site", property="og:title")
+        """
+        parts: list[str] = []
+        if name:
+            parts.append(f'name="{_esc(name)}"')
+        if property:
+            parts.append(f'property="{_esc(property)}"')
+        for k, v in attrs.items():
+            parts.append(f'{k.rstrip("_")}="{_esc(v)}"')
+        parts.append(f'content="{_esc(content)}"')
+        self._meta_tags.append("<meta " + " ".join(parts) + ">")
+        return self
+
+    def set_meta(self, *, description: str = "", author: str = "",
+                 keywords: str = "") -> Page:
+        """Convenience wrapper for the three most common ``<meta name>`` tags.
+
+        ::
+
+            page.set_meta(description="A great site", author="Me",
+                          keywords="python, web")
+        """
+        if description:
+            self.meta(description, name="description")
+        if author:
+            self.meta(author, name="author")
+        if keywords:
+            self.meta(keywords, name="keywords")
+        return self
+
+    def favicon(self, href: str, type_: str = "") -> Page:
+        """Add a favicon ``<link rel="icon">``."""
+        tag = f'<link rel="icon" href="{_esc(href)}"'
+        if type_:
+            tag += f' type="{_esc(type_)}"'
+        self._head_links.append(tag + ">")
+        return self
+
+    # --- assets ---
+
+    def asset(self, src: str, name: str = "") -> str:
+        """Register a local file to be copied next to the built HTML.
+
+        Returns the relative URL to use in ``src`` / ``href``; the actual
+        copy happens at build time (``htmlforge render``).
+
+        ::
+
+            logo = page.asset("logo.png")   # → "assets/logo.png"
+            page.image(logo, "Logo")
+        """
+        fname = name or _basename(src)
+        rel = f"assets/{fname}"
+        self._assets.append((src, rel))
+        return rel
+
+    def _collect_assets(self) -> list[tuple[str, str]]:
+        """``(source, relative-dest)`` pairs registered via :meth:`asset`."""
+        return list(self._assets)
+
     # --- JS ---
 
     def add_script(self, code: str = "", src: str = "") -> Page:
@@ -658,6 +725,8 @@ class Page:
 
         for href in self._ext_css:
             head.append(f'<link rel="stylesheet" href="{_esc(href)}">')
+        for lnk in self._head_links:
+            head.append(lnk)
         for m in self._meta_tags:
             head.append(m)
         for el in self.head_elements:
@@ -668,7 +737,7 @@ class Page:
             head.append(f"<style>\n{css}\n</style>")
 
         body_parts: list[str] = []
-        for c in self.body_children:
+        for c in self._body_prefix + self.body_children + self._body_suffix:
             if isinstance(c, Element):
                 body_parts.append(c.render())
             else:
@@ -703,12 +772,18 @@ def _to_kebab(name: str) -> str:
     return re.sub(r"(?<=[a-z])(?=[A-Z])", "-", name).lower().replace("_", "-")
 
 
+def _basename(path: str) -> str:
+    """``"a/b/logo.png"`` (or with backslashes) → ``"logo.png"``."""
+    return path.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+
+
 def _esc(s: str) -> str:
-    """Escape HTML-special characters in attribute values."""
+    """Escape HTML-special characters in text and attribute values."""
     return (
         str(s)
         .replace("&", "&amp;")
         .replace('"', "&quot;")
+        .replace("'", "&#39;")
         .replace("<", "&lt;")
         .replace(">", "&gt;")
     )