pydzn 0.1.3__tar.gz → 0.1.4__tar.gz

pydzn-0.1.4/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: pydzn
+Version: 0.1.4
+Summary: Build complex websites in pure python with pydzn layout builder, semantic css classes and an extendable components library for server-side rendering.
+Author-email: Ryan Kirkish <ryan@foo.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/anthonyrka/pydzn
+Project-URL: Repository, https://github.com/anthonyrka/pydzn
+Project-URL: Issues, https://github.com/anthonyrka/pydzn/issues
+Keywords: design-system,css,utility-classes,jinja2,components,grid,htmx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Flask
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Jinja2>=3.1
+Provides-Extra: flask
+Requires-Dist: Flask>=2.3; extra == "flask"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: black>=24; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# pydzn
+*Pronounced:* **[paɪ dɪˈzaɪn]** — “**pie design**” (aka **py-design**)
+
+Build full websites in Python with server-side components, a design system that leverages semantic classes, and a grid layout builder.
+
+## What is pydzn
+pydzn or "py design" is a lightweight python library that makes it easy to design, build and serve complex websites all in python. It provides an api into CSS-grid for designing layouts and serves as a light-weight website builder with a built-in, and extendable, component library as well as a library for setting CSS semantic classes.
+
+
+## Examples
+- For examples see: [pydzn-website](https://github.com/anthonyrka/pydzn-website)
+
+## References
+- See [PyPI](https://pypi.org/project/pydzn/)
+
+
+## A website builder for python developers (not front-end developers)
+The layout builder contains a debug mode allowing you to visualize the structure of your layout. Each named region is a slot which can be passed a sub-layout or a component in the layout's render function.
+
+<p align="center">
+  <img src="docs/website_builder_sortof.gif" alt="mobile" width="640">
+</p>
+
+## Responsive is built-in
+Build responsive layouts with pydzn
+
+<p align="center">
+  <img src="docs/pydzn_responsive.gif" alt="mobile" width="640">
+</p>
+
+The above layouts are combined desktop and mobile versions:
+```python
+
+from pydzn.grid_builder import layout_builder
+
+# This is the Main App layout structure we've created below for DESKTOP
+"""
+                    column::left_column    column::main_column
+row:header_row      region:left_sidebar    region:appbar
+row:content_row     region:left_sidebar    region:content
+
+The layout accepts the following components in render function signature: left_sidebar, appbar, content
+"""
+AppMainLayout = (
+    layout_builder()
+    .fill_height("100vh", property="height") # sets up the page to restrict height to view height
+    .columns(left_column=LEFT_SIDEBAR_WIDTH, main_column="1fr") # split the main layout into two columns: sidebar and main
+    .rows(header_row=HEADER_HEIGHT, content_row="1fr") # add 2 rows: a header section and a content section stacked 
+    .region("left_sidebar", col="left_column", row="header_row", row_span=2) # place the sidebar into the left_sidebar column in the first row and span both rows
+    .region("appbar", col="main_column", row="header_row", col_span=1) # Add the appbar to the right of sidebar in the main section and span the last row
+    .region("content", col="main_column", row="content_row") # declare the empty content section which is the last row in main
+    .build(name="AppMainLayout")
+)
+
+# This is the Main App layout structure we've created below for MOBILE
+"""
+                    column::main_column
+row:header_row      region:appbar
+row:content_row     region:content
+
+The layout accepts the following components in render function signature: appbar, content
+"""
+AppMainMobileLayout = (
+    layout_builder()
+    .fill_height("100vh", property="height")
+    .columns(main_column="1fr")
+    .rows(header_row=HEADER_HEIGHT_MOBILE, content_row="1fr")
+    .region("appbar",  col="main_column", row="header_row")
+    .region("content", col="main_column", row="content_row")
+    .build(name="AppMainMobileLayout")
+)
+
+# ----- App header menu slots -----#
+AppHeaderMenuLayout = (
+    layout_builder()
+    # make the inner grid fill the parent (the appbar row), not the viewport
+    .fill_height("100%", property="height") # was min-height:100vh (implicit default)
+    .columns(brand=BRAND_WIDTH, spacer="1fr", tasks=APP_MENU_WIDTH, customers=APP_MENU_WIDTH, orders=APP_MENU_WIDTH, notifications=APP_MENU_WIDTH, user_profile=APP_MENU_WIDTH)
+    .rows(app_header_main=f"minmax({HEADER_HEIGHT}px, auto)") # these items don't take up the full height of the app header unless you set it here
+    .region("brand", col="brand", row="app_header_main")
+    .region("spacer", col="spacer", row="app_header_main") # empty; pushes the rest right
+    .region("tasks", col="tasks", row="app_header_main")
+    .region("customers", col="customers", row="app_header_main")
+    .region("orders", col="orders", row="app_header_main")
+    .region("notifications", col="notifications", row="app_header_main")
+    .region("user_profile", col="user_profile", row="app_header_main")
+    .build(name="AppHeaderMenuLayout")
+)
+
+# ----- App header mobile menu layout ----#
+AppHeaderMobileMenuLayout = (
+    layout_builder()
+    .fill_height("100%", property="height")
+    .columns(brand_col=BRAND_WIDTH, spacer_col="1fr", hamburger_menu_col=100)
+    .rows(app_header_mobile_row=f"minmax({HEADER_HEIGHT_MOBILE}px, auto)") # this container holds the app header for mobile layout so height must match
+    .region("brand", col="brand_col", row="app_header_mobile_row")
+    .region("hamburger_menu", col="hamburger_menu_col", row="app_header_mobile_row")
+    .build(name="AppHeaderMobileMenuLayout")
+)
+
+```
+
+These layouts contain render functions with a signature containing the named slots for variables, in the case of AppMainMobileLayout, the hamburger_menu slot is passed a built-in hamburger menu component:
+
+```python
+from pydzn.components import NavItem, Text, HamburgerMenu
+
+# Right-side full-height drawer
+menu_btn = HamburgerMenu(
+    mode="right",
+    drawer_width=320,
+    show_backdrop=True,
+    children=drop_down_mobile,
+    dzn="bg-[white]",   # forwarded to the panel automatically
+    panel_dzn="p-[24px]" # this is how you set the semantic css classes for the drawer (panel)
+).render()
+
+
+mobile_html = AppHeaderMobileMenuLayout(
+    debug=debug,
+    region_dzn = {
+        "brand": "flex justify-center items-center",
+        "hamburger_menu": "flex justify-center items-center"
+    }
+).render(
+    brand=brand,
+    hamburger_menu=menu_btn
+)
+```
+
+
+

pydzn-0.1.4/README.md

@@ -0,0 +1,132 @@
+# pydzn
+*Pronounced:* **[paɪ dɪˈzaɪn]** — “**pie design**” (aka **py-design**)
+
+Build full websites in Python with server-side components, a design system that leverages semantic classes, and a grid layout builder.
+
+## What is pydzn
+pydzn or "py design" is a lightweight python library that makes it easy to design, build and serve complex websites all in python. It provides an api into CSS-grid for designing layouts and serves as a light-weight website builder with a built-in, and extendable, component library as well as a library for setting CSS semantic classes.
+
+
+## Examples
+- For examples see: [pydzn-website](https://github.com/anthonyrka/pydzn-website)
+
+## References
+- See [PyPI](https://pypi.org/project/pydzn/)
+
+
+## A website builder for python developers (not front-end developers)
+The layout builder contains a debug mode allowing you to visualize the structure of your layout. Each named region is a slot which can be passed a sub-layout or a component in the layout's render function.
+
+<p align="center">
+  <img src="docs/website_builder_sortof.gif" alt="mobile" width="640">
+</p>
+
+## Responsive is built-in
+Build responsive layouts with pydzn
+
+<p align="center">
+  <img src="docs/pydzn_responsive.gif" alt="mobile" width="640">
+</p>
+
+The above layouts are combined desktop and mobile versions:
+```python
+
+from pydzn.grid_builder import layout_builder
+
+# This is the Main App layout structure we've created below for DESKTOP
+"""
+                    column::left_column    column::main_column
+row:header_row      region:left_sidebar    region:appbar
+row:content_row     region:left_sidebar    region:content
+
+The layout accepts the following components in render function signature: left_sidebar, appbar, content
+"""
+AppMainLayout = (
+    layout_builder()
+    .fill_height("100vh", property="height") # sets up the page to restrict height to view height
+    .columns(left_column=LEFT_SIDEBAR_WIDTH, main_column="1fr") # split the main layout into two columns: sidebar and main
+    .rows(header_row=HEADER_HEIGHT, content_row="1fr") # add 2 rows: a header section and a content section stacked 
+    .region("left_sidebar", col="left_column", row="header_row", row_span=2) # place the sidebar into the left_sidebar column in the first row and span both rows
+    .region("appbar", col="main_column", row="header_row", col_span=1) # Add the appbar to the right of sidebar in the main section and span the last row
+    .region("content", col="main_column", row="content_row") # declare the empty content section which is the last row in main
+    .build(name="AppMainLayout")
+)
+
+# This is the Main App layout structure we've created below for MOBILE
+"""
+                    column::main_column
+row:header_row      region:appbar
+row:content_row     region:content
+
+The layout accepts the following components in render function signature: appbar, content
+"""
+AppMainMobileLayout = (
+    layout_builder()
+    .fill_height("100vh", property="height")
+    .columns(main_column="1fr")
+    .rows(header_row=HEADER_HEIGHT_MOBILE, content_row="1fr")
+    .region("appbar",  col="main_column", row="header_row")
+    .region("content", col="main_column", row="content_row")
+    .build(name="AppMainMobileLayout")
+)
+
+# ----- App header menu slots -----#
+AppHeaderMenuLayout = (
+    layout_builder()
+    # make the inner grid fill the parent (the appbar row), not the viewport
+    .fill_height("100%", property="height") # was min-height:100vh (implicit default)
+    .columns(brand=BRAND_WIDTH, spacer="1fr", tasks=APP_MENU_WIDTH, customers=APP_MENU_WIDTH, orders=APP_MENU_WIDTH, notifications=APP_MENU_WIDTH, user_profile=APP_MENU_WIDTH)
+    .rows(app_header_main=f"minmax({HEADER_HEIGHT}px, auto)") # these items don't take up the full height of the app header unless you set it here
+    .region("brand", col="brand", row="app_header_main")
+    .region("spacer", col="spacer", row="app_header_main") # empty; pushes the rest right
+    .region("tasks", col="tasks", row="app_header_main")
+    .region("customers", col="customers", row="app_header_main")
+    .region("orders", col="orders", row="app_header_main")
+    .region("notifications", col="notifications", row="app_header_main")
+    .region("user_profile", col="user_profile", row="app_header_main")
+    .build(name="AppHeaderMenuLayout")
+)
+
+# ----- App header mobile menu layout ----#
+AppHeaderMobileMenuLayout = (
+    layout_builder()
+    .fill_height("100%", property="height")
+    .columns(brand_col=BRAND_WIDTH, spacer_col="1fr", hamburger_menu_col=100)
+    .rows(app_header_mobile_row=f"minmax({HEADER_HEIGHT_MOBILE}px, auto)") # this container holds the app header for mobile layout so height must match
+    .region("brand", col="brand_col", row="app_header_mobile_row")
+    .region("hamburger_menu", col="hamburger_menu_col", row="app_header_mobile_row")
+    .build(name="AppHeaderMobileMenuLayout")
+)
+
+```
+
+These layouts contain render functions with a signature containing the named slots for variables, in the case of AppMainMobileLayout, the hamburger_menu slot is passed a built-in hamburger menu component:
+
+```python
+from pydzn.components import NavItem, Text, HamburgerMenu
+
+# Right-side full-height drawer
+menu_btn = HamburgerMenu(
+    mode="right",
+    drawer_width=320,
+    show_backdrop=True,
+    children=drop_down_mobile,
+    dzn="bg-[white]",   # forwarded to the panel automatically
+    panel_dzn="p-[24px]" # this is how you set the semantic css classes for the drawer (panel)
+).render()
+
+
+mobile_html = AppHeaderMobileMenuLayout(
+    debug=debug,
+    region_dzn = {
+        "brand": "flex justify-center items-center",
+        "hamburger_menu": "flex justify-center items-center"
+    }
+).render(
+    brand=brand,
+    hamburger_menu=menu_btn
+)
+```
+
+
+

{pydzn-0.1.3 → pydzn-0.1.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pydzn"
-version = "0.1.3"
-description = "Tiny design-system utilities (Tailwind-like), composable HTML components, and a grid layout builder for Python/Jinja apps."
+version = "0.1.4"
+description = "Build complex websites in pure python with pydzn layout builder, semantic css classes and an extendable components library for server-side rendering."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }

{pydzn-0.1.3 → pydzn-0.1.4}/src/pydzn/components/__init__.py

@@ -1,8 +1,10 @@
 from .button.component import Button
+from .card.component import Card
 from .text.component import Text
 from .drawer.component import Drawer
 from .sidebar.component import Sidebar
 from .nav_item.component import NavItem
+from .hamburger_menu.component import HamburgerMenu
 
 
-__all__ = ["Button", "Text", "Drawer", "Sidebar", "NavItem"]
+__all__ = ["Button", "Card", "Text", "Drawer", "Sidebar", "NavItem", "HamburgerMenu"]

pydzn-0.1.4/src/pydzn/components/button/component.py

@@ -0,0 +1,88 @@
+from pydzn.base_component import BaseComponent
+from pydzn.variants import VariantSupport
+
+
+class Button(VariantSupport, BaseComponent):
+    """
+    Server-rendered Button with pluggable variants/sizes.
+
+    - Built-in variants keep colors inline so it works without a theme pack.
+    - You can add external libraries and select with namespace, e.g. variant="acme:glass".
+    """
+
+    # visual “structures” (kept color-aware so no theme pack needed)
+    VARIANTS = {
+        # solid
+        "solid-primary": (
+            "rounded-sm border border-transparent "
+            "bg-[#2563eb] text-[white] "
+            "shadow-md hover:shadow-lg"
+        ),
+        # outline
+        "outline-primary": (
+            "rounded-sm border-2 border-blue-500 "
+            "bg-[transparent] text-[#2563eb] "
+            "shadow-sm hover:shadow-md"
+        ),
+        # ghost (neutral)
+        "ghost-neutral": (
+            "rounded-sm border-0 "
+            "bg-[transparent] text-body "
+            "shadow-none hover:bg-[rgba(15,23,42,.06)]"
+        ),
+        # linky button
+        "link-primary": (
+            "rounded-none border-0 "
+            "bg-[transparent] text-[#2563eb] "
+            "shadow-none hover:underline"
+        ),
+    }
+
+    # density
+    SIZES = {
+        "sm": "px-3 py-1",
+        "md": "px-5 py-2",
+        "lg": "px-6 py-3",
+        "xl": "px-8 py-4",
+    }
+
+    # tones are optional here; variants carry color already
+    TONES = {}
+
+    # project-wide defaults can be overridden via VariantSupport.set_default_choices(Button, ...)
+    DEFAULTS = {
+        "variant": "outline-primary",
+        "size": "md",
+        "tone": "",
+    }
+
+    def __init__(
+        self,
+        text: str = "",
+        children: str | None = None,
+        *,
+        tag: str = "button",
+        # variant system
+        variant: str | None = None,
+        size: str | None = None,
+        tone: str | None = None,
+        # raw utility escape hatch (merged last)
+        dzn: str | None = None,
+        **attrs,
+    ):
+        # allow stray attrs["dzn"] too
+        extra_dzn = dzn or attrs.pop("dzn", None)
+
+        # resolve VARIANT + SIZE (+ optional TONE) + extra_dzn
+        effective_dzn = self._resolve_variant_dzn(
+            variant=variant,
+            size=size,
+            tone=tone,
+            extra_dzn=extra_dzn,
+        )
+
+        super().__init__(children=children, tag=tag, dzn=effective_dzn, **attrs)
+        self.text = text
+
+    def context(self) -> dict:
+        return {"text": self.text}

pydzn-0.1.4/src/pydzn/components/card/component.py

@@ -0,0 +1,93 @@
+from pydzn.base_component import BaseComponent
+from pydzn.variants import VariantSupport
+
+
+class Card(VariantSupport, BaseComponent):
+    """
+    Server-rendered Card with pluggable variants/sizes/tones.
+    Variants focus on layout/structure; tones mainly adjust border color.
+    """
+
+    # visual “structures”
+    VARIANTS = {
+        "panel": (
+            "flex flex-col gap-4 p-4 rounded-xl "
+            "border border-subtle bg-elevated shadow-sm"
+        ),
+        "plain": (
+            "flex flex-col gap-3 p-4 rounded-md "
+            "border border-subtle bg-surface shadow-none"
+        ),
+        "elevated": (
+            "flex flex-col gap-4 p-4 rounded-xl "
+            "border border-transparent bg-elevated shadow-lg"
+        ),
+        "outlined": (
+            "flex flex-col gap-4 p-4 rounded-lg "
+            "border-2 border-slate-300 bg-[transparent] shadow-none"
+        ),
+        "soft": (
+            "flex flex-col gap-4 p-4 rounded-xl "
+            "border-0 bg-[rgba(15,23,42,.03)] shadow-sm"
+        ),
+        "glass": (
+            "flex flex-col gap-4 p-4 rounded-xl "
+            "border border-[rgba(255,255,255,.25)] bg-[rgba(255,255,255,.08)] shadow-md"
+        ),
+        "ghost": (
+            "flex flex-col gap-4 p-4 rounded-md "
+            "border-0 bg-[transparent] shadow-none"
+        ),
+    }
+
+    # density
+    SIZES = {
+        "xs": "p-2 gap-2 rounded-sm",
+        "sm": "p-3 gap-2 rounded-md",
+        "md": "p-4 gap-3 rounded-lg",
+        "lg": "p-6 gap-4 rounded-xl",
+        "xl": "p-8 gap-5 rounded-2xl",
+    }
+
+    # tones mainly drive border color (kept subtle by default)
+    TONES = {
+        "neutral": "border-subtle",
+        "primary": "border-blue-500",
+        "success": "border-green-500",
+        "danger":  "border-red-500",
+    }
+
+    # project-wide defaults can be overridden at runtime:
+    #   Card.set_default_choices(variant="...", size="...", tone="...")
+    DEFAULTS = {
+        "variant": "panel",
+        "size": "md",
+        "tone": "neutral",
+    }
+
+    def __init__(
+        self,
+        children: str | None = None,
+        *,
+        tag: str = "div",
+        # variant system
+        variant: str | None = None,
+        size: str | None = None,
+        tone: str | None = None,
+        # raw utility escape hatch (merged last)
+        dzn: str | None = None,
+        **attrs,
+    ):
+        extra_dzn = dzn or attrs.pop("dzn", None)
+
+        effective_dzn = self._resolve_variant_dzn(
+            variant=variant,
+            size=size,
+            tone=tone,
+            extra_dzn=extra_dzn,
+        )
+
+        super().__init__(children=children, tag=tag, dzn=effective_dzn, **attrs)
+
+    def context(self) -> dict:
+        return {}