bootstrap-python 0.1.0__py3-none-any.whl

bootstrap_ui/layout.py

@@ -0,0 +1,260 @@
+"""页面与栅格布局组件：Page / Container / Row / Col / Stack / Hr。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, ClassVar, Literal
+
+from jinja2 import Environment, FileSystemLoader
+from pydantic import Field
+
+from .types import Node, NodeLike, escape, render_children
+
+__all__ = ["Page", "Container", "Row", "Col", "Stack", "Hr", "Box", "Fragment"]
+
+_TEMPLATE_DIR = Path(__file__).parent / "templates"
+
+_env = Environment(
+    loader=FileSystemLoader(_TEMPLATE_DIR),
+    autoescape=False,          # 内容在 Python 侧已经渲染并转义过，这里不能二次转义
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+class Page(Node):
+    """完整的 HTML 页面（``<html>`` 文档），是渲染的入口。"""
+
+    TAG: ClassVar[str | None] = None
+    __default_template_path__: ClassVar[str] = "page.jinja2"
+
+    title: str = "Bootstrap"
+    """浏览器标题"""
+
+    lang: str = "zh-CN"
+    """``<html lang>``"""
+
+    body: list[NodeLike] = Field(default_factory=list)
+    """页面主体内容"""
+
+    navbar: NodeLike | None = None
+    """顶部导航栏（一般传 :class:`~bootstrap.nav.Navbar`）"""
+
+    footer: NodeLike | None = None
+    """页脚内容"""
+
+    toolbar: NodeLike | None = None
+    """主体内容上方的工具条（标题 + 按钮之类）"""
+
+    container: bool = True
+    """是否用容器包裹主体内容"""
+
+    fluid: bool = False
+    """容器是否全宽"""
+
+    body_class: str | None = None
+    """``<body>`` 的 class"""
+
+    theme: Literal["light", "dark", "auto"] | None = None
+    """Bootstrap 5.3 的 ``data-bs-theme``，用于内置暗色模式"""
+
+    version: str = "5.3.3"
+    """Bootstrap 版本号"""
+
+    cdn: str = "https://cdn.jsdelivr.net/npm"
+    """资源 CDN 前缀"""
+
+    icons: bool = True
+    """是否引入 bootstrap-icons"""
+
+    icons_version: str = "1.11.3"
+    """bootstrap-icons 版本号"""
+
+    css: list[str] = Field(default_factory=list)
+    """额外样式表地址"""
+
+    js: list[str] = Field(default_factory=list)
+    """额外脚本地址"""
+
+    custom_css: str | None = None
+    """内联样式"""
+
+    custom_js: str | None = None
+    """内联脚本（在 Bootstrap bundle 之后执行）"""
+
+    head: str | None = None
+    """原样插入 ``<head>`` 末尾的内容"""
+
+    def render(self, template_name: str = "") -> str:
+        """用 jinja2 模板渲染完整页面。"""
+        template = _env.get_template(template_name or self.__default_template_path__)
+        return template.render(
+            lang=escape(self.lang),
+            theme=self.theme,
+            title=escape(self.title),
+            icons=self.icons,
+            icons_version=self.icons_version,
+            cdn=self.cdn.rstrip("/"),
+            version=self.version,
+            css=self.css,
+            page_css=self.custom_css or "",
+            body_class=escape(self.body_class or ""),
+            navbar=self.navbar.render() if isinstance(self.navbar, Node) else "",
+            toolbar=render_children(self.toolbar, "\n") if self.toolbar is not None else "",
+            body=render_children(self.body, "\n"),
+            footer=self.footer.render() if isinstance(self.footer, Node) else "",
+            js=self.js,
+            page_js=self.custom_js or "",
+            container=self.container,
+            container_class="container-fluid" if self.fluid else "container",
+            head=self.head or "",
+        )
+
+    def save(self, path: str | Path, encoding: str = "utf-8") -> Path:
+        """把渲染结果写入文件。"""
+        target = Path(path)
+        target.write_text(self.render(), encoding=encoding)
+        return target
+
+
+class Container(Node):
+    """固定宽度（或响应式）的内容容器。"""
+
+    fluid: bool | Literal["sm", "md", "lg", "xl", "xxl"] = False
+    """``True`` 全宽；字符串表示 ``container-{断点}``"""
+
+    children: list[NodeLike] = Field(default_factory=list)
+
+    def css_classes(self) -> list[str]:
+        if self.fluid is True:
+            return ["container-fluid"]
+        if isinstance(self.fluid, str):
+            return [f"container-{self.fluid}"]
+        return ["container"]
+
+    def render_content(self) -> str:
+        return render_children(self.children, "\n")
+
+
+class Row(Node):
+    """栅格行（``.row``）。"""
+
+    children: list[NodeLike] = Field(default_factory=list)
+
+    gutter: int | str | None = None
+    """列间距，渲染为 ``g-{gutter}``，如 3"""
+
+    align: Literal["start", "center", "end", "baseline", "stretch"] | None = None
+    """垂直对齐（align-items-*）"""
+
+    justify: Literal["start", "center", "end", "between", "around", "evenly"] | None = None
+    """水平分布（justify-content-*）"""
+
+    cols: int | str | None = None
+    """每行固定列数，渲染为 ``row-cols-{cols}``"""
+
+    def css_classes(self) -> list[str]:
+        classes = ["row"]
+        if self.gutter is not None:
+            classes.append(f"g-{self.gutter}")
+        if self.align:
+            classes.append(f"align-items-{self.align}")
+        if self.justify:
+            classes.append(f"justify-content-{self.justify}")
+        if self.cols is not None:
+            classes.append(f"row-cols-{self.cols}")
+        return classes
+
+    def render_content(self) -> str:
+        return render_children(self.children, "\n")
+
+
+class Col(Node):
+    """栅格列（``.col``）。"""
+
+    body: list[NodeLike] = Field(default_factory=list)
+
+    width: int | str | None = None
+    """默认宽度，1-12 或 ``auto``"""
+
+    xs: int | str | None = None
+    sm: int | str | None = None
+    md: int | str | None = None
+    lg: int | str | None = None
+    xl: int | str | None = None
+    xxl: int | str | None = None
+    """各断点下的宽度"""
+
+    offset: int | None = None
+    """左侧偏移列数"""
+
+    align_self: Literal["start", "center", "end", "baseline", "stretch"] | None = None
+    """列自身在行内的垂直对齐"""
+
+    def css_classes(self) -> list[str]:
+        classes: list[str] = []
+        if self.width is not None:
+            classes.append(f"col-{self.width}")
+        for breakpoint in ("xs", "sm", "md", "lg", "xl", "xxl"):
+            item = getattr(self, breakpoint)
+            if item is not None:
+                classes.append(f"col-{breakpoint}-{item}")
+        if self.offset is not None:
+            classes.append(f"offset-{self.offset}")
+        if self.align_self:
+            classes.append(f"align-self-{self.align_self}")
+        if not classes:
+            classes.append("col")
+        return classes
+
+    def render_content(self) -> str:
+        return render_children(self.body, "\n")
+
+
+class Stack(Node):
+    """垂直 / 水平堆叠（``.vstack`` / ``.hstack``）。"""
+
+    direction: Literal["vertical", "horizontal"] = "vertical"
+
+    gap: int | str | None = 3
+    """间距，渲染为 ``gap-{gap}``"""
+
+    children: list[NodeLike] = Field(default_factory=list)
+
+    def css_classes(self) -> list[str]:
+        classes = ["vstack" if self.direction == "vertical" else "hstack"]
+        if self.gap is not None:
+            classes.append(f"gap-{self.gap}")
+        return classes
+
+    def render_content(self) -> str:
+        return render_children(self.children, "\n")
+
+
+class Hr(Node):
+    """分割线。"""
+
+    TAG: ClassVar[str | None] = "hr"
+
+    def css_classes(self) -> list[str]:
+        return ["my-4"]
+
+
+class Box(Node):
+    """通用 div 容器，用来套用工具类或行内样式。"""
+
+    children: list[NodeLike] = Field(default_factory=list)
+
+    def render_content(self) -> str:
+        return render_children(self.children, "\n")
+
+
+class Fragment(Node):
+    """不产生包裹标签的片段，用于把多个节点当成一个整体传入。"""
+
+    TAG: ClassVar[str | None] = None
+
+    children: list[NodeLike] = Field(default_factory=list)
+
+    def render(self) -> str:
+        return render_children(self.children, "\n")

bootstrap_ui/nav.py

@@ -0,0 +1,356 @@
+"""导航类组件：Navbar / Nav / NavItem / Dropdown / Pagination / Breadcrumb。"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Literal
+from uuid import uuid4
+
+from pydantic import Field
+
+from .constants import Color, Size, value as enum_value
+from .content import icon_name
+from .types import Node, NodeLike, escape, render_attrs, render_children
+
+__all__ = [
+    "Navbar",
+    "Nav",
+    "NavItem",
+    "Dropdown",
+    "DropdownItem",
+    "Pagination",
+    "Breadcrumb",
+    "BreadcrumbItem",
+]
+
+
+class NavItem(Node):
+    """导航项，渲染为 ``<li class="nav-item"><a class="nav-link">``。"""
+
+    TAG: ClassVar[str | None] = None
+
+    text: str = ""
+    href: str = "#"
+    icon: str | None = None
+    active: bool = False
+    disabled: bool = False
+
+    def render(self) -> str:
+        classes = ["nav-link"]
+        if self.active:
+            classes.append("active")
+        if self.disabled:
+            classes.append("disabled")
+
+        attrs: dict[str, Any] = {"class": " ".join(classes), "href": self.href}
+        if self.active:
+            attrs["aria-current"] = "page"
+        if self.disabled:
+            attrs["tabindex"] = "-1"
+            attrs["aria-disabled"] = "true"
+        if self.id:
+            attrs["id"] = self.id
+
+        icon = f'<i class="{icon_name(self.icon)} me-1"></i>' if self.icon else ""
+        return f'<li class="nav-item"><a{render_attrs(attrs)}>{icon}{escape(self.text)}</a></li>'
+
+
+class DropdownItem(Node):
+    """下拉菜单项，``divider=True`` 时渲染为分割线。"""
+
+    TAG: ClassVar[str | None] = None
+
+    text: str = ""
+    href: str = "#"
+    active: bool = False
+    disabled: bool = False
+    divider: bool = False
+    icon: str | None = None
+
+    def render(self) -> str:
+        if self.divider:
+            return '<li><hr class="dropdown-divider"></li>'
+
+        classes = ["dropdown-item"]
+        if self.active:
+            classes.append("active")
+        if self.disabled:
+            classes.append("disabled")
+
+        attrs: dict[str, Any] = {"class": " ".join(classes), "href": self.href}
+        if self.disabled:
+            attrs["aria-disabled"] = "true"
+            attrs["tabindex"] = "-1"
+
+        icon = f'<i class="{icon_name(self.icon)} me-2"></i>' if self.icon else ""
+        return f'<li><a{render_attrs(attrs)}>{icon}{escape(self.text)}</a></li>'
+
+
+class Dropdown(Node):
+    """下拉菜单。默认渲染为导航栏中的一项（``<li>`` 包裹）。"""
+
+    TAG: ClassVar[str | None] = None
+
+    text: str = ""
+    items: list[DropdownItem | str] = Field(default_factory=list)
+    color: Color = Color.primary
+    """``as_button=True`` 时的按钮颜色"""
+
+    as_button: bool = False
+    """``True`` 时渲染为按钮样式的下拉菜单"""
+
+    menu_end: bool = True
+    dark: bool = False
+    as_nav_item: bool = True
+
+    def render(self) -> str:
+        toggle_classes = ["dropdown-toggle"]
+        if self.as_button:
+            toggle_classes = ["btn", f"btn-{enum_value(self.color)}", "dropdown-toggle"]
+        else:
+            toggle_classes.insert(0, "nav-link")
+
+        menu_classes = ["dropdown-menu", "dropdown-menu-dark" if self.dark else "dropdown-menu-end" if self.menu_end else ""]
+        menu_class = " ".join(cls for cls in menu_classes if cls)
+
+        toggle = (
+            f'<a class="{" ".join(toggle_classes)}" href="#" role="button" '
+            f'data-bs-toggle="dropdown" aria-expanded="false">{escape(self.text)}</a>'
+        )
+        items = "".join(
+            item.render() if isinstance(item, DropdownItem) else DropdownItem(text=str(item)).render()
+            for item in self.items
+        )
+        menu = f'<ul class="{menu_class}">{items}</ul>'
+
+        if self.as_nav_item:
+            return f'<li class="nav-item dropdown">{toggle}{menu}</li>'
+        return f'<div class="dropdown">{toggle}{menu}</div>'
+
+
+class Nav(Node):
+    """独立导航（``.nav``），可用于侧边栏或标签式导航。"""
+
+    TAG: ClassVar[str | None] = "ul"
+
+    items: list[NavItem | Dropdown | str] = Field(default_factory=list)
+    vertical: bool = False
+    pills: bool = False
+    fill: bool = False
+    justified: bool = False
+
+    def css_classes(self) -> list[str]:
+        classes = ["nav"]
+        if self.vertical:
+            classes.append("flex-column")
+        classes.append("nav-pills" if self.pills else "nav-tabs")
+        if self.fill:
+            classes.append("nav-fill")
+        if self.justified:
+            classes.append("nav-justified")
+        return classes
+
+    def render_content(self) -> str:
+        return render_children(self.items)
+
+
+class Navbar(Node):
+    """顶部导航栏。"""
+
+    TAG: ClassVar[str | None] = "nav"
+
+    brand: str | None = None
+    brand_href: str = "#"
+    brand_icon: str | None = None
+
+    items: list[NavItem | Dropdown | str] = Field(default_factory=list)
+    """左侧导航项"""
+
+    actions: list[NodeLike] = Field(default_factory=list)
+    """右侧操作区（按钮、下拉菜单等）"""
+
+    color: Color | None = None
+    """``bg-{color}``，配合 ``dark=True`` 使用深色文字方案"""
+
+    dark: bool = False
+    expand: Literal["sm", "md", "lg", "xl", "xxl", False] = "lg"
+    sticky: bool = False
+    container: bool = True
+    fluid: bool = True
+    id: str = Field(default_factory=lambda: f"navbar-{uuid4().hex[:6]}")
+
+    def css_classes(self) -> list[str]:
+        classes = ["navbar"]
+        if self.color:
+            classes.append(f"bg-{enum_value(self.color)}")
+        else:
+            classes.append("bg-body-tertiary")
+        if self.dark or self.color in {Color.dark, Color.primary}:
+            classes.append("navbar-dark")
+        if self.sticky:
+            classes.append("sticky-top")
+        if self.expand:
+            classes.append(f"navbar-expand-{self.expand}")
+        else:
+            classes.append("navbar-expand")
+        return classes
+
+    def html_attrs(self) -> dict[str, Any]:
+        attrs = super().html_attrs()
+        attrs.setdefault("data-bs-theme", "dark" if (self.dark or self.color in {Color.dark, Color.primary}) else "light")
+        return attrs
+
+    def render_content(self) -> str:
+        collapse_id = f"{self.id}-nav"
+        brand_icon = f'<i class="{icon_name(self.brand_icon)} me-2"></i>' if self.brand_icon else ""
+        brand = (
+            f'<a class="navbar-brand" href="{escape(self.brand_href)}">{brand_icon}{escape(self.brand)}</a>'
+            if self.brand
+            else ""
+        )
+        toggler = (
+            '<button class="navbar-toggler" type="button" data-bs-toggle="collapse" '
+            f'data-bs-target="#{collapse_id}" aria-controls="{collapse_id}" '
+            'aria-expanded="false" aria-label="切换导航"><span class="navbar-toggler-icon"></span></button>'
+        )
+        items = render_children(self.items)
+        actions = render_children(self.actions)
+        actions_html = f'<div class="d-flex align-items-center gap-2">{actions}</div>' if actions else ""
+
+        inner = (
+            f"{brand}{toggler}"
+            f'<div class="collapse navbar-collapse" id="{collapse_id}">'
+            f'<ul class="navbar-nav me-auto mb-2 mb-lg-0">{items}</ul>'
+            f"{actions_html}</div>"
+        )
+        if self.container:
+            wrapper = "container-fluid" if self.fluid else "container"
+            inner = f'<div class="{wrapper}">{inner}</div>'
+        return inner
+
+
+class BreadcrumbItem(Node):
+    """面包屑中的一项。"""
+
+    TAG: ClassVar[str | None] = None
+
+    text: str = ""
+    href: str | None = None
+    active: bool = False
+
+    def render(self) -> str:
+        classes = ["breadcrumb-item"]
+        if self.active:
+            classes.append("active")
+        if self.href and not self.active:
+            body = f'<a href="{escape(self.href)}">{escape(self.text)}</a>'
+        else:
+            body = escape(self.text)
+        return f'<li class="{" ".join(classes)}">{body}</li>'
+
+
+class Breadcrumb(Node):
+    """面包屑导航。"""
+
+    TAG: ClassVar[str | None] = "nav"
+
+    items: list[BreadcrumbItem | str] = Field(default_factory=list)
+
+    def html_attrs(self) -> dict[str, Any]:
+        attrs = super().html_attrs()
+        attrs.setdefault("aria-label", "breadcrumb")
+        return attrs
+
+    def render_content(self) -> str:
+        nodes: list[str] = []
+        for index, item in enumerate(self.items):
+            if isinstance(item, BreadcrumbItem):
+                node = item
+            else:
+                node = BreadcrumbItem(text=str(item))
+            node.active = node.active or index == len(self.items) - 1
+            nodes.append(node.render())
+        return f'<ol class="breadcrumb mb-0">{"".join(nodes)}</ol>'
+
+
+class Pagination(Node):
+    """分页导航。"""
+
+    TAG: ClassVar[str | None] = "nav"
+
+    current: int = 1
+    total: int = 1
+    href: str = "?page={page}"
+    """页码链接模板，``{page}`` 会被替换"""
+
+    size: Size | None = None
+    max_buttons: int = 7
+    show_edges: bool = True
+    align: Literal["start", "center", "end"] = "center"
+
+    def html_attrs(self) -> dict[str, Any]:
+        attrs = super().html_attrs()
+        attrs.setdefault("aria-label", "分页")
+        return attrs
+
+    def _page_item(self, page: int, label: str, *, active: bool = False, disabled: bool = False) -> str:
+        classes = ["page-item"]
+        if active:
+            classes.append("active")
+        if disabled:
+            classes.append("disabled")
+
+        if active:
+            inner = f'<span class="page-link">{escape(label)}</span>'
+        elif disabled:
+            inner = f'<span class="page-link">{escape(label)}</span>'
+        else:
+            inner = f'<a class="page-link" href="{escape(self.href.format(page=page))}">{escape(label)}</a>'
+        return f'<li class="{" ".join(classes)}">{inner}</li>'
+
+    def _window(self) -> list[int | None]:
+        total = max(self.total, 1)
+        current = min(max(self.current, 1), total)
+        limit = max(self.max_buttons, 5)
+        if total <= limit:
+            return list(range(1, total + 1))
+
+        half = (limit - 3) // 2
+        start = max(2, current - half)
+        end = min(total - 1, start + (limit - 3) - 1)
+        start = max(2, end - (limit - 3) + 1)
+
+        pages: list[int | None] = [1]
+        if start > 2:
+            pages.append(None)
+        pages.extend(range(start, end + 1))
+        if end < total - 1:
+            pages.append(None)
+        pages.append(total)
+        return pages
+
+    def render_content(self) -> str:
+        total = max(self.total, 1)
+        current = min(max(self.current, 1), total)
+        parts: list[str] = []
+
+        if self.show_edges:
+            parts.append(self._page_item(1, "«", disabled=current == 1))
+        parts.append(self._page_item(current - 1, "‹", disabled=current == 1))
+
+        for page in self._window():
+            if page is None:
+                parts.append('<li class="page-item disabled"><span class="page-link">…</span></li>')
+            else:
+                parts.append(self._page_item(page, str(page), active=page == current))
+
+        parts.append(self._page_item(current + 1, "›", disabled=current == total))
+        if self.show_edges:
+            parts.append(self._page_item(total, "»", disabled=current == total))
+
+        size_class = f" pagination-{enum_value(self.size)}" if self.size else ""
+        justify = {
+            "start": "justify-content-start",
+            "center": "justify-content-center",
+            "end": "justify-content-end",
+        }[self.align]
+        return f'<ul class="pagination {justify}{size_class}">{"".join(parts)}</ul>'