htmlforge 0.0.1__py3-none-any.whl

htmlforge/core.py

@@ -0,0 +1,687 @@
+"""webforge core — Elements, Components, and Page."""
+
+from __future__ import annotations
+from typing import Any, Union
+import re
+
+
+# ============================================================
+# Base Element
+# ============================================================
+
+class Element:
+    """Base class for all HTML elements."""
+
+    tag: str = "div"
+    _self_closing: bool = False
+
+    def __init__(self, *children: Union[Element, str],
+                 class_: str = "", id: str = "", style: str = "", **attrs: str):
+        self.children: list[Union[Element, str]] = list(children)
+        self.attrs: dict[str, str] = {}
+        if class_:
+            self.attrs["class"] = class_
+        if id:
+            self.attrs["id"] = id
+        if style:
+            self.attrs["style"] = style
+        for k, v in attrs.items():
+            self.attrs[k.rstrip("_")] = v
+
+    # --- builder API (all chainable) ---
+
+    def add(self, *children: Union[Element, str]) -> Element:
+        """Append child elements or text."""
+        for c in children:
+            self.children.append(c)
+        return self
+
+    def css(self, **props: str) -> Element:
+        """Merge inline CSS properties."""
+        parts = self.attrs.get("style", "").rstrip("; ")
+        new = "; ".join(
+            f"{_to_kebab(k)}: {v}" for k, v in props.items()
+        )
+        self.attrs["style"] = f"{parts}; {new}".strip("; ")
+        return self
+
+    def attr(self, key: str, value: str) -> Element:
+        """Set a single HTML attribute."""
+        self.attrs[key] = value
+        return self
+
+    def remove_attr(self, key: str) -> Element:
+        self.attrs.pop(key, None)
+        return self
+
+    # --- rendering ---
+
+    def _open_tag(self) -> str:
+        parts = [self.tag]
+        for k, v in self.attrs.items():
+            parts.append(f'{k}="{_esc(v)}"')
+        return "<" + " ".join(parts) + ">"
+
+    def render(self, indent: int = 0) -> str:
+        pad = "  " * indent
+        tag_attrs = " ".join(f'{k}="{_esc(v)}"' for k, v in self.attrs.items())
+        open_str = f"<{self.tag}" + (f" {tag_attrs}" if tag_attrs else "") + ">"
+
+        if self._self_closing:
+            return f"{pad}{open_str}"
+
+        if not self.children:
+            return f"{pad}{open_str}</{self.tag}>"
+
+        inner_parts: list[str] = []
+        for c in self.children:
+            if isinstance(c, Element):
+                inner_parts.append(c.render(indent + 1))
+            else:
+                inner_parts.append("  " * (indent + 1) + _esc(str(c)))
+        inner = "\n".join(inner_parts)
+        return f"{pad}{open_str}\n{inner}\n{pad}</{self.tag}>"
+
+    def __str__(self) -> str:
+        return self.render()
+
+    def __repr__(self) -> str:
+        return f"<{self.tag} children={len(self.children)}>"
+
+
+# ============================================================
+# Generic / Structural
+# ============================================================
+
+class Div(Element):
+    tag = "div"
+
+class Section(Element):
+    tag = "section"
+
+class Header(Element):
+    tag = "header"
+
+class Footer(Element):
+    tag = "footer"
+
+class Nav(Element):
+    tag = "nav"
+
+class Main(Element):
+    tag = "main"
+
+class Article(Element):
+    tag = "article"
+
+class Aside(Element):
+    tag = "aside"
+
+class Span(Element):
+    tag = "span"
+
+class Container(Div):
+    """A ``div`` with ``class="container"`` by default."""
+    def __init__(self, *children: Union[Element, str], **attrs: str):
+        attrs.setdefault("class_", "container")
+        super().__init__(*children, **attrs)
+
+
+# ============================================================
+# Text
+# ============================================================
+
+class H1(Element):
+    tag = "h1"
+
+class H2(Element):
+    tag = "h2"
+
+class H3(Element):
+    tag = "h3"
+
+class H4(Element):
+    tag = "h4"
+
+class H5(Element):
+    tag = "h5"
+
+class H6(Element):
+    tag = "h6"
+
+class P(Element):
+    tag = "p"
+
+class Strong(Element):
+    tag = "strong"
+
+class Em(Element):
+    tag = "em"
+
+class Blockquote(Element):
+    tag = "blockquote"
+
+class Small(Element):
+    tag = "small"
+
+class Mark(Element):
+    tag = "mark"
+
+class Sub(Element):
+    tag = "sub"
+
+class Sup(Element):
+    tag = "sup"
+
+class Code(Element):
+    tag = "code"
+
+class Pre(Element):
+    tag = "pre"
+
+
+class Text(Element):
+    """Raw HTML passthrough — ``render()`` returns the string verbatim."""
+    tag = ""
+    _self_closing = True
+
+    def __init__(self, html: str = ""):
+        super().__init__()
+        self._html = html
+
+    def render(self, indent: int = 0) -> str:
+        return "  " * indent + self._html
+
+
+class Link(Element):
+    tag = "a"
+
+    def __init__(self, text: str = "", href: str = "#",
+                 target: str = "", **attrs: str):
+        super().__init__(text, **attrs)
+        self.attrs["href"] = href
+        if target:
+            self.attrs["target"] = target
+
+
+# ============================================================
+# Lists
+# ============================================================
+
+class Ul(Element):
+    tag = "ul"
+
+class Ol(Element):
+    tag = "ol"
+
+class Li(Element):
+    tag = "li"
+
+
+class List(Element):
+    """Convenience: auto-wraps strings in ``<li>`` elements."""
+    tag = "ul"
+
+    def __init__(self, items: list | None = None, ordered: bool = False, **attrs: str):
+        super().__init__(**attrs)
+        self.tag = "ol" if ordered else "ul"
+        for item in (items or []):
+            self.children.append(Li(item) if isinstance(item, str) else item)
+
+
+# ============================================================
+# Media
+# ============================================================
+
+class Img(Element):
+    tag = "img"
+    _self_closing = True
+
+    def __init__(self, src: str = "", alt: str = "", **attrs: str):
+        super().__init__(**attrs)
+        if src:
+            self.attrs["src"] = src
+        if alt:
+            self.attrs["alt"] = alt
+
+
+class Video(Element):
+    tag = "video"
+
+    def __init__(self, src: str = "", controls: bool = True, **attrs: str):
+        super().__init__(**attrs)
+        if src:
+            self.children.append(Element.__new__(Source).__init_tag(src))
+        if controls:
+            self.attrs["controls"] = ""
+
+
+class Audio(Element):
+    tag = "audio"
+
+    def __init__(self, src: str = "", controls: bool = True, **attrs: str):
+        super().__init__(**attrs)
+        if src:
+            self.attrs["src"] = src
+        if controls:
+            self.attrs["controls"] = ""
+
+
+class Source(Element):
+    tag = "source"
+    _self_closing = True
+
+    def __init__(self, src: str = "", type_: str = "", **attrs: str):
+        super().__init__(**attrs)
+        if src:
+            self.attrs["src"] = src
+        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"
+
+    def __init__(self, src: str = "", width: str = "", height: str = "", **attrs: str):
+        super().__init__(**attrs)
+        if src:
+            self.attrs["src"] = src
+        if width:
+            self.attrs["width"] = width
+        if height:
+            self.attrs["height"] = height
+
+
+class Canvas(Element):
+    tag = "canvas"
+
+    def __init__(self, width: str = "", height: str = "", **attrs: str):
+        super().__init__(**attrs)
+        if width:
+            self.attrs["width"] = width
+        if height:
+            self.attrs["height"] = height
+
+
+# ============================================================
+# Table
+# ============================================================
+
+class Table(Element):
+    tag = "table"
+
+    def __init__(self, headers: list[str] | None = None,
+                 rows: list[list[str]] | None = None, **attrs: str):
+        super().__init__(**attrs)
+        if headers:
+            thead = Thead().add(Tr(*[Th(h) for h in headers]))
+            self.children.append(thead)
+        if rows:
+            tbody = Tbody()
+            for row in rows:
+                tbody.add(Tr(*[Td(str(cell)) for cell in row]))
+            self.children.append(tbody)
+
+
+class Thead(Element):
+    tag = "thead"
+
+class Tbody(Element):
+    tag = "tbody"
+
+class Tr(Element):
+    tag = "tr"
+
+class Th(Element):
+    tag = "th"
+
+class Td(Element):
+    tag = "td"
+
+class Caption(Element):
+    tag = "caption"
+
+
+# ============================================================
+# Forms
+# ============================================================
+
+class Form(Element):
+    tag = "form"
+
+    def __init__(self, *children: Union[Element, str],
+                 action: str = "", method: str = "", **attrs: str):
+        super().__init__(*children, **attrs)
+        if action:
+            self.attrs["action"] = action
+        if method:
+            self.attrs["method"] = method
+
+
+class Input(Element):
+    tag = "input"
+    _self_closing = True
+
+    def __init__(self, type_: str = "text", name: str = "",
+                 placeholder: str = "", value: str = "", **attrs: str):
+        super().__init__(**attrs)
+        self.attrs["type"] = type_
+        if name:
+            self.attrs["name"] = name
+        if placeholder:
+            self.attrs["placeholder"] = placeholder
+        if value:
+            self.attrs["value"] = value
+
+
+class Textarea(Element):
+    tag = "textarea"
+
+    def __init__(self, text: str = "", name: str = "",
+                 rows: str = "", cols: str = "", **attrs: str):
+        super().__init__(**attrs)
+        if text:
+            self.children.append(text)
+        if name:
+            self.attrs["name"] = name
+        if rows:
+            self.attrs["rows"] = rows
+        if cols:
+            self.attrs["cols"] = cols
+
+
+class Select(Element):
+    tag = "select"
+
+    def __init__(self, options: list[tuple[str, str]] | None = None,
+                 name: str = "", **attrs: str):
+        super().__init__(**attrs)
+        if name:
+            self.attrs["name"] = name
+        for val, label in (options or []):
+            self.children.append(Option(label, value=val))
+
+
+class Option(Element):
+    tag = "option"
+
+    def __init__(self, text: str = "", value: str = "",
+                 selected: bool = False, **attrs: str):
+        super().__init__(text, **attrs)
+        if value:
+            self.attrs["value"] = value
+        if selected:
+            self.attrs["selected"] = ""
+
+
+class Checkbox(Element):
+    tag = "input"
+    _self_closing = True
+
+    def __init__(self, name: str = "", label: str = "",
+                 checked: bool = False, **attrs: str):
+        super().__init__(**attrs)
+        self.attrs["type"] = "checkbox"
+        if name:
+            self.attrs["name"] = name
+        if checked:
+            self.attrs["checked"] = ""
+        self._label = label
+
+    def render(self, indent: int = 0) -> str:
+        base = super().render(indent)
+        if self._label:
+            return f'{base} <label>{_esc(self._label)}</label>'
+        return base
+
+
+class Radio(Element):
+    tag = "input"
+    _self_closing = True
+
+    def __init__(self, name: str = "", value: str = "",
+                 label: str = "", checked: bool = False, **attrs: str):
+        super().__init__(**attrs)
+        self.attrs["type"] = "radio"
+        if name:
+            self.attrs["name"] = name
+        if value:
+            self.attrs["value"] = value
+        if checked:
+            self.attrs["checked"] = ""
+        self._label = label
+
+    def render(self, indent: int = 0) -> str:
+        base = super().render(indent)
+        if self._label:
+            return f'{base} <label>{_esc(self._label)}</label>'
+        return base
+
+
+class Label(Element):
+    tag = "label"
+
+    def __init__(self, text: str = "", for_: str = "", **attrs: str):
+        super().__init__(text, **attrs)
+        if for_:
+            self.attrs["for"] = for_
+
+
+class Button(Element):
+    tag = "button"
+
+    def __init__(self, text: str = "", type_: str = "button",
+                 onclick: str = "", **attrs: str):
+        super().__init__(text, **attrs)
+        if type_:
+            self.attrs["type"] = type_
+        if onclick:
+            self.attrs["onclick"] = onclick
+
+
+# ============================================================
+# Misc
+# ============================================================
+
+class Hr(Element):
+    tag = "hr"
+    _self_closing = True
+
+class Br(Element):
+    tag = "br"
+    _self_closing = True
+
+class Meta(Element):
+    tag = "meta"
+    _self_closing = True
+
+class Progress(Element):
+    tag = "progress"
+
+    def __init__(self, value: float = 0, max_: float = 100, **attrs: str):
+        super().__init__(**attrs)
+        self.attrs["value"] = str(value)
+        self.attrs["max"] = str(max_)
+
+class Details(Element):
+    tag = "details"
+
+class Summary(Element):
+    tag = "summary"
+
+
+# ============================================================
+# Page
+# ============================================================
+
+class Page:
+    """Top-level HTML document builder.
+
+    Usage::
+
+        page = Page("My Site")
+        page.add(H1("Hello"), P("World"))
+        html = page.render()
+    """
+
+    def __init__(self, title: str = "Untitled", *,
+                 lang: str = "zh", charset: str = "utf-8",
+                 viewport: bool = True):
+        self.title = title
+        self.lang = lang
+        self.charset = charset
+        self.viewport = viewport
+        self.head_elements: list[Element] = []
+        self.body_children: list[Union[Element, str]] = []
+        self._css_rules: list[str] = []
+        self._inline_scripts: list[str] = []
+        self._script_srcs: list[str] = []
+        self._ext_css: list[str] = []
+        self._meta_tags: list[str] = []
+
+    # --- CSS ---
+
+    def add_css(self, css: str) -> Page:
+        """Add raw CSS rules."""
+        self._css_rules.append(css)
+        return self
+
+    def add_stylesheet(self, href: str) -> Page:
+        """Link an external CSS file."""
+        self._ext_css.append(href)
+        return self
+
+    # --- JS ---
+
+    def add_script(self, code: str = "", src: str = "") -> Page:
+        if src:
+            self._script_srcs.append(src)
+        elif code:
+            self._inline_scripts.append(code)
+        return self
+
+    # --- body content ---
+
+    def add(self, *children: Union[Element, str]) -> Page:
+        for c in children:
+            self.body_children.append(c)
+        return self
+
+    def add_raw(self, html: str) -> Page:
+        self.body_children.append(html)
+        return self
+
+    # --- convenience (shortcuts) ---
+
+    def header(self, text: str, level: int = 1, **attrs: str) -> Page:
+        tags = {1: H1, 2: H2, 3: H3, 4: H4, 5: H5, 6: H6}
+        return self.add(tags.get(level, H1)(text, **attrs))
+
+    def paragraph(self, text: str, **attrs: str) -> Page:
+        return self.add(P(text, **attrs))
+
+    def image(self, src: str, alt: str = "", **attrs: str) -> Page:
+        return self.add(Img(src, alt, **attrs))
+
+    def link(self, text: str, href: str, **attrs: str) -> Page:
+        return self.add(Link(text, href, **attrs))
+
+    def button(self, text: str, **attrs: str) -> Page:
+        return self.add(Button(text, **attrs))
+
+    def line_break(self) -> Page:
+        return self.add(Br())
+
+    def horizontal_rule(self) -> Page:
+        return self.add(Hr())
+
+    def divider(self) -> Page:
+        return self.add(Hr())
+
+    def list(self, items: list[str], ordered: bool = False, **attrs: str) -> Page:
+        return self.add(List(items, ordered, **attrs))
+
+    def table(self, headers: list[str], rows: list[list[str]], **attrs: str) -> Page:
+        return self.add(Table(headers, rows, **attrs))
+
+    def code_block(self, code: str, language: str = "") -> Page:
+        code_el = Code(code)
+        if language:
+            code_el.attr("class", f"language-{language}")
+        return self.add(Pre().add(code_el))
+
+    # --- rendering ---
+
+    def render(self) -> str:
+        head: list[str] = [
+            f'<meta charset="{self.charset}">',
+        ]
+        if self.viewport:
+            head.append(
+                '<meta name="viewport" '
+                'content="width=device-width, initial-scale=1.0">'
+            )
+        head.append(f"<title>{_esc(self.title)}</title>")
+
+        for href in self._ext_css:
+            head.append(f'<link rel="stylesheet" href="{_esc(href)}">')
+        for m in self._meta_tags:
+            head.append(m)
+        for el in self.head_elements:
+            head.append(el.render())
+
+        if self._css_rules:
+            css = "\n".join(self._css_rules)
+            head.append(f"<style>\n{css}\n</style>")
+
+        body_parts: list[str] = []
+        for c in self.body_children:
+            if isinstance(c, Element):
+                body_parts.append(c.render())
+            else:
+                body_parts.append(str(c))
+
+        for src in self._script_srcs:
+            body_parts.append(f'<script src="{_esc(src)}"></script>')
+        for code in self._inline_scripts:
+            body_parts.append(f"<script>\n{code}\n</script>")
+
+        head_str = "\n".join(f"  {l}" for l in head)
+        body_str = "\n".join(f"  {l}" for l in body_parts)
+
+        return (
+            f"<!DOCTYPE html>\n"
+            f'<html lang="{self.lang}">\n'
+            f"<head>\n{head_str}\n</head>\n"
+            f"<body>\n{body_str}\n</body>\n"
+            f"</html>"
+        )
+
+    def __str__(self) -> str:
+        return self.render()
+
+
+# ============================================================
+# Helpers
+# ============================================================
+
+def _to_kebab(name: str) -> str:
+    """``backgroundColor`` → ``background-color``."""
+    return re.sub(r"(?<=[a-z])(?=[A-Z])", "-", name).lower().replace("_", "-")
+
+
+def _esc(s: str) -> str:
+    """Escape HTML-special characters in attribute values."""
+    return (
+        str(s)
+        .replace("&", "&amp;")
+        .replace('"', "&quot;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+    )