htmlforge 0.0.1__py3-none-any.whl

htmlforge/simple.py

@@ -0,0 +1,331 @@
+"""htmlforge simple — High-level API with built-in themes.
+
+Designed for Python programmers who don't know HTML.
+Everything looks great out of the box — no CSS required.
+
+Usage::
+
+    from htmlforge import Doc
+
+    page = Doc("My Site")
+    page.heading("Hello World")
+    page.text("Some **bold** and *italic* text")
+    page.button("Click me", on_click="alert('hi')")
+"""
+
+from __future__ import annotations
+from typing import Union
+import re
+
+from htmlforge.core import (
+    Page, Element, Div, Hr, Text,
+    H1, H2, H3, P, Strong, Em, Link,
+    Ul, Ol, Li, Img,
+    Table, Thead, Tbody, Tr, Th, Td,
+    Input, Textarea, Select, Option, Button as _Button,
+    Details, Summary, Code, Pre, _to_kebab,
+)
+
+
+# ============================================================
+# Default Theme — clean, modern, responsive
+# ============================================================
+
+_DEFAULT_CSS = """
+*, *::before, *::after { box-sizing: border-box; }
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+                 'Helvetica Neue', Arial, sans-serif;
+    line-height: 1.7; max-width: 52rem;
+    margin: 0 auto; padding: 2rem 1.5rem;
+    color: #1d1d1f; background: #fff;
+}
+h1 { font-size: 2.2rem; font-weight: 700; margin: 2rem 0 .8rem; }
+h2 { font-size: 1.6rem; font-weight: 600; margin: 1.8rem 0 .6rem; }
+h3 { font-size: 1.25rem; font-weight: 600; margin: 1.4rem 0 .5rem; }
+p  { margin: 0 0 1rem; }
+a  { color: #0066cc; text-decoration: none; }
+a:hover { text-decoration: underline; }
+img { max-width: 100%; height: auto; border-radius: 8px; }
+/* ---- button ---- */
+.py-btn {
+    display: inline-block; padding: .55rem 1.4rem;
+    font-size: .95rem; font-weight: 500;
+    border: 2px solid #0066cc; border-radius: 8px;
+    background: #0066cc; color: #fff;
+    cursor: pointer; transition: all .2s;
+    margin: .25rem .25rem .25rem 0;
+}
+.py-btn:hover { background: #0052a3; border-color: #0052a3; }
+/* ---- table ---- */
+table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
+th, td { padding: .6rem .8rem; text-align: left;
+          border-bottom: 1px solid #e5e7eb; }
+th { background: #f8f9fa; font-weight: 600; }
+tr:hover td { background: #f5f7fa; }
+/* ---- card ---- */
+.py-card {
+    border: 1px solid #e5e7eb; border-radius: 12px;
+    padding: 1.4rem; margin: 1rem 0;
+    transition: box-shadow .2s;
+}
+.py-card:hover { box-shadow: 0 4px 16px rgba(0,0,0,.06); }
+.py-card h3:first-child,
+.py-card h2:first-child { margin-top: 0; }
+/* ---- grid ---- */
+.py-grid { display: flex; gap: 1rem; flex-wrap: wrap; }
+.py-grid > * { flex: 1 1 16rem; min-width: 0; }
+/* ---- input / textarea ---- */
+.py-input, .py-textarea {
+    display: block; width: 100%;
+    padding: .5rem .75rem; font-size: .95rem;
+    border: 1px solid #d1d5db; border-radius: 8px;
+    margin: .4rem 0; outline: none;
+    transition: border-color .2s;
+}
+.py-input:focus, .py-textarea:focus { border-color: #0066cc; }
+/* ---- select ---- */
+.py-select {
+    display: block; width: 100%;
+    padding: .5rem .75rem; font-size: .95rem;
+    border: 1px solid #d1d5db; border-radius: 8px;
+    margin: .4rem 0;
+}
+/* ---- code ---- */
+pre { background: #f4f4f5; padding: 1rem; border-radius: 8px;
+      overflow-x: auto; font-size: .9rem; }
+code { font-family: 'Cascadia Code', 'Fira Code', Consolas, monospace; }
+p code { background: #f4f4f5; padding: .15rem .3rem; border-radius: 4px; }
+/* ---- list ---- */
+ul, ol { padding-left: 1.5rem; margin: 0 0 1rem; }
+li { margin: .2rem 0; }
+/* ---- details ---- */
+details { margin: .5rem 0; }
+details > summary {
+    cursor: pointer; font-weight: 500;
+    padding: .5rem 0; user-select: none;
+}
+details > summary:hover { color: #0066cc; }
+/* ---- nav ---- */
+.py-nav {
+    display: flex; gap: 1.5rem; padding: .5rem 0;
+    margin-bottom: 1rem; border-bottom: 1px solid #e5e7eb;
+}
+/* ---- hr ---- */
+hr { border: none; border-top: 1px solid #e5e7eb; margin: 2rem 0; }
+""".strip()
+
+
+# ============================================================
+# Markdown inline helpers
+# ============================================================
+
+def _md(s: str) -> str:
+    """Convert inline Markdown to HTML."""
+    s = re.sub(r'`(.+?)`',  r'<code>\1</code>',  s)
+    s = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', s)
+    s = re.sub(r'\*(.+?)\*',     r'<em>\1</em>',         s)
+    s = re.sub(r'\[(.+?)\]\((.+?)\)', r'<a href="\2">\1</a>', s)
+    return s
+
+
+# ============================================================
+# Doc — the high-level page builder
+# ============================================================
+
+class Doc:
+    """Build a styled web page using only Python — no HTML needed.
+
+    Comparison::
+
+        # Low-level (core.py)                # High-level (simple.py)
+        page = Page("Site")                  page = Doc("Site")
+        page.add_css("body{...}")            # theme built-in
+        page.add(H1("Hi"))                   page.heading("Hi")
+        page.add(P("text"))                  page.text("text")
+    """
+
+    def __init__(self, title: str = "Untitled", *,
+                 lang: str = "zh", theme: bool = True):
+        self._page = Page(title, lang=lang)
+        if theme:
+            self._page.add_css(_DEFAULT_CSS)
+
+    # ---- delegate to Page ----
+
+    def add_css(self, css: str) -> Doc:
+        """Add extra CSS rules."""
+        self._page.add_css(css)
+        return self
+
+    def add_script(self, code: str = "", src: str = "") -> Doc:
+        """Add JavaScript (inline code or external src)."""
+        self._page.add_script(code, src)
+        return self
+
+    def add_raw(self, html: str) -> Doc:
+        """Insert raw HTML string."""
+        self._page.add_raw(html)
+        return self
+
+    def add(self, *children: Union[Element, str]) -> Doc:
+        """Add raw Elements or text (auto-wraps strings in <p>)."""
+        for c in children:
+            if isinstance(c, str):
+                self._page.add(P(Text(_md(c))))
+            else:
+                self._page.add(c)
+        return self
+
+    # ---- text & headings ----
+
+    def heading(self, text: str, level: int = 1) -> Doc:
+        """Add a heading (level 1-6)."""
+        tags = {1: H1, 2: H2, 3: H3}
+        return self.add(tags.get(level, H3)(text))
+
+    def text(self, content: str) -> Doc:
+        """Add a paragraph. Supports **bold**, *italic*, `code`, [link](url)."""
+        self._page.add(P(Text(_md(content))))
+        return self
+
+    def link(self, text: str, url: str) -> Doc:
+        """Add a hyperlink."""
+        return self.add(Link(text, url))
+
+    def image(self, src: str, alt: str = "") -> Doc:
+        """Add an image (auto-responsive)."""
+        return self.add(Img(src, alt))
+
+    # ---- layout ----
+
+    def card(self, title: str = "", *content: Union[Element, str]) -> Doc:
+        """Add a card with optional title and content."""
+        return self.add(self.make_card(title, *content))
+
+    @staticmethod
+    def make_card(title: str = "", *content: Union[Element, str]) -> Div:
+        """Create a card element (use with ``row`` / ``grid``)."""
+        d = Div(class_="py-card")
+        if title:
+            d.add(H3(title))
+        for c in content:
+            if isinstance(c, str):
+                d.add(P(Text(_md(c))))
+            else:
+                d.add(c)
+        return d
+
+    def row(self, *children: Element) -> Doc:
+        """Arrange elements side-by-side in a flex row."""
+        return self.add(Div(class_="py-grid").add(*children))
+
+    def grid(self, *children: Element, cols: int = 0) -> Doc:
+        """Responsive grid layout. ``cols=0`` means auto-fit."""
+        d = Div(class_="py-grid")
+        if cols:
+            d.css(gridTemplateColumns=f"repeat({cols}, 1fr)")
+        d.add(*children)
+        return self.add(d)
+
+    # ---- interactive ----
+
+    def button(self, label: str, on_click: str = "", *,
+               color: str = "") -> Doc:
+        """Add a button. Set ``color`` for custom background."""
+        btn = _Button(class_="py-btn")
+        btn.add(label)
+        if color:
+            btn.css(background=color, borderColor=color)
+        if on_click:
+            btn.attr("onclick", on_click)
+        return self.add(btn)
+
+    def input(self, placeholder: str = "", *,
+              type: str = "text", name: str = "") -> Doc:
+        """Add a text input field."""
+        return self.add(Input(type_=type, name=name,
+                              placeholder=placeholder, class_="py-input"))
+
+    def textarea(self, placeholder: str = "", *,
+                 rows: str = "4", name: str = "") -> Doc:
+        """Add a multi-line text area."""
+        return self.add(Textarea(placeholder, name=name,
+                                 rows=rows, class_="py-textarea"))
+
+    def select(self, options: list[str], *,
+               name: str = "") -> Doc:
+        """Add a dropdown. ``options`` is a list of label strings."""
+        pairs = [(o, o) for o in options]
+        return self.add(Select(options=pairs, name=name, class_="py-select"))
+
+    # ---- data ----
+
+    def list(self, items: list[str], *, ordered: bool = False) -> Doc:
+        """Add a bullet list (or numbered if ``ordered=True``)."""
+        cls: type = Ol if ordered else Ul
+        el = cls()
+        for item in items:
+            el.add(Li(item))
+        return self.add(el)
+
+    def table(self, headers: list[str],
+              rows: list[list[str]]) -> Doc:
+        """Add a table."""
+        return self.add(Table(headers, rows))
+
+    def code(self, source: str, *, lang: str = "") -> Doc:
+        """Add a code block."""
+        c = Code(source)
+        if lang:
+            c.attr("class", f"language-{lang}")
+        return self.add(Pre().add(c))
+
+    # ---- extras ----
+
+    def details(self, summary: str, *content: Union[Element, str]) -> Doc:
+        """Add a collapsible section."""
+        det = Details().add(Summary(summary))
+        for c in content:
+            if isinstance(c, str):
+                det.add(P(Text(_md(c))))
+            else:
+                det.add(c)
+        return self.add(det)
+
+    def nav(self, *links: tuple[str, str]) -> Doc:
+        """Add a navigation bar. Each arg is ``(text, url)``."""
+        n = Div(class_="py-nav")
+        for label, url in links:
+            n.add(Link(label, url))
+        return self.add(n)
+
+    def divider(self) -> Doc:
+        """Add a horizontal rule."""
+        return self.add(Hr())
+
+    # ---- style (programmatic CSS) ----
+
+    def style(self, selector: str, **props: str) -> Doc:
+        """Add a CSS rule using Python kwargs.
+
+        ::
+
+            page.style("body", background="#f0f0f0", font_family="sans-serif")
+            page.style("h1", color="navy", font_size="2rem")
+            page.style(".card", border_radius="12px", padding="1rem")
+            page.style("button:hover", background="darkblue")
+        """
+        decls = "; ".join(
+            f"{_to_kebab(k)}: {v}" for k, v in props.items()
+        )
+        self._page.add_css(f"{selector} {{ {decls} }}")
+        return self
+
+    # ---- rendering ----
+
+    def render(self) -> str:
+        return self._page.render()
+
+    def __str__(self) -> str:
+        return self.render()

htmlforge-0.0.1.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: htmlforge
+Version: 0.0.1
+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
+```
+
+## Installation
+
+```bash
+pip install htmlforge
+```
+
+Development install:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Write a Python page script `mysite.py`
+
+```python
+from htmlforge import Doc
+
+page = Doc("My Site")
+
+# Generate styles with Python code (no CSS needed!)
+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"],
+    ],
+)
+
+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 |
+
+## 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()
+
+# Layout
+page.row(Doc.make_card("A"), Doc.make_card("B"), Doc.make_card("C"))
+```
+
+## 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
+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
+```
+
+## License
+
+[MPL-2.0](LICENSE)

htmlforge-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+htmlforge/__init__.py,sha256=om4GflxTfsgUBh4DWnbUhpASW5sXrlddrqPkzYZWFN0,725
+htmlforge/__main__.py,sha256=I2IO0PQiXvzFeSkTADZYK3wjwCZocQqqZz-MGESrg14,104
+htmlforge/cli.py,sha256=lrGhEaRqLaFeQybORduNSJOTmvrm2V777-GAbjoFZKI,6171
+htmlforge/core.py,sha256=5i0Mxi3w0Pp6SvR8OYixP5PGF8x51DN8UCxFALc3Gl8,18731
+htmlforge/simple.py,sha256=S3iXOWtneiUWJZUBaLqlrxtyTj84OpIMdQlVkyNvOt4,11487
+htmlforge-0.0.1.dist-info/METADATA,sha256=Gy8a4RZEtmsQb85QT0mnMLmxJ5TS3NXwLTgPJRbP64A,5749
+htmlforge-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+htmlforge-0.0.1.dist-info/entry_points.txt,sha256=4NFQHme4dPb8WjKirGaMRPa2jBE6X8WpZwZTwi7gqUQ,51
+htmlforge-0.0.1.dist-info/licenses/LICENSE,sha256=H_SFL1HRjJcNiNCqq5FQPxzPKE9FL_A5qfYcPz9rdqg,36
+htmlforge-0.0.1.dist-info/RECORD,,

htmlforge-0.0.1.dist-info/WHEEL

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

htmlforge-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+htmlforge = htmlforge.cli:render

htmlforge-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1 @@
+Mozilla Public License Version 2.0