htmlforge 0.0.1__tar.gz → 0.0.3__tar.gz

htmlforge-0.0.3/PKG-INFO

@@ -0,0 +1,427 @@
+Metadata-Version: 2.5
+Name: htmlforge
+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
+License-Expression: MPL-2.0
+License-File: LICENSE
+Keywords: builder,html,page,static-site,web
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# htmlforge
+
+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
+htmlforge   script   app.py        →  js
+```
+
+## Installation
+
+```bash
+pip install htmlforge
+```
+
+## Quick Start
+
+### 1. Write a Python page script `mysite.py`
+
+```python
+from htmlforge import Doc
+
+page = Doc("My Site")
+
+# 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)")
+
+# Build the page
+page.heading("Welcome to My Site")
+page.text("Built with **htmlforge**, supports *Markdown* syntax")
+
+page.card("Features",
+    "40+ HTML components",
+    "Generate styles with Python code",
+    "Export HTML with one command",
+)
+
+page.table(
+    ["Feature", "Description"],
+    [
+        ["Components", "40+ HTML components"],
+        ["Built-in theme", "Works out of the box"],
+        ["CLI tools", "render / serve / watch / script"],
+    ],
+)
+
+page.button("Click me", on_click="alert('Hello!')", color="#4CAF50")
+```
+
+### 2. Run the command to export HTML
+
+```bash
+# Basic render
+htmlforge render mysite.py
+
+# Specify output directory
+htmlforge render mysite.py -o build
+
+# Render and start a local server
+htmlforge render mysite.py -s
+
+# Watch for file changes and auto-rebuild
+htmlforge render mysite.py -w
+
+# Render a specific page (when file has multiple pages)
+htmlforge render mysite.py MyPage
+```
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `htmlforge render <file.py>` | Render all pages to `dist/` |
+| `htmlforge render <file.py> -o <dir>` | Specify output directory |
+| `htmlforge render <file.py> <page>` | Render only the specified page |
+| `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 |
+
+## Doc API — Ultra Simple
+
+`Doc` is a high-level API designed for Python programmers who don't know HTML. It comes with a built-in theme — no CSS required to build great-looking pages.
+
+```python
+from htmlforge import Doc
+
+page = Doc("Title")
+
+# Generate styles with Python kwargs (no CSS strings!)
+page.style("body", background="linear-gradient(135deg, #667eea, #764ba2)", color="white")
+page.style("h1", font_size="3rem", text_align="center")
+page.style(".py-card", background="rgba(255,255,255,.15)", backdrop_filter="blur(10px)")
+
+# Content (supports **Markdown** syntax)
+page.heading("Hello World")
+page.text("Supports **bold**, *italic*, `code`, [links](url)")
+
+page.card("Card Title", "Card content, **supports Markdown**")
+page.list(["Item A", "Item B", "Item C"])
+page.table(["Col 1", "Col 2"], [["a", "b"], ["c", "d"]])
+page.button("Button", on_click="alert('hi')", color="#e74c3c")
+page.input("Type here...", name="name")
+page.select(["Option A", "Option B", "Option C"])
+page.code("print('hello')", lang="python")
+page.details("Collapsible", "Hidden content...")
+page.nav(("Home", "/"), ("About", "/about"))
+page.divider()
+
+# 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
+
+```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")
+```
+
+> **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:
+
+```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:
+
+```python
+from htmlforge import Page, H1, P, Div, Table, Button
+
+page = Page("Title", lang="en")
+page.add_css("body { font-family: sans-serif; }")
+page.add(
+    H1("Welcome"),
+    P("Hello World"),
+    Div(class_="card").add(
+        H1("Features", level=2),
+        P("Content..."),
+    ),
+)
+```
+
+### Element — Chainable API
+
+```python
+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
+```
+
+### Components
+
+| Category | Components |
+|---|---|
+| **Structure** | `Div`, `Section`, `Header`, `Footer`, `Nav`, `Main`, `Article`, `Aside`, `Span`, `Container` |
+| **Text** | `H1`-`H6`, `P`, `Strong`, `Em`, `Blockquote`, `Code`, `Pre`, `Small`, `Mark` |
+| **Links/Media** | `Link`, `Img`, `Video`, `Audio`, `Iframe`, `Canvas` |
+| **Lists** | `Ul`, `Ol`, `Li`, `List` |
+| **Tables** | `Table`, `Thead`, `Tbody`, `Tr`, `Th`, `Td`, `Caption` |
+| **Forms** | `Form`, `Input`, `Textarea`, `Select`, `Option`, `Checkbox`, `Radio`, `Label`, `Button` |
+| **Other** | `Hr`, `Br`, `Text`, `Progress`, `Details`, `Summary` |
+
+## Example: Multi-page Site
+
+```python
+# site.py
+from htmlforge import Doc
+
+home = Doc("Home")
+home.heading("Home")
+home.text("Welcome to the home page")
+
+about = Doc("About")
+about.heading("About Us")
+about.text("This is the about page")
+
+blog = Doc("Blog")
+blog.heading("Blog")
+blog.text("Latest posts...")
+```
+
+```bash
+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)