htmui 0.1.0__tar.gz

htmui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Volf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

htmui-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.1
+Name: htmui
+Version: 0.1.0
+Summary: htmy component library
+Requires-Python: >=3.12
+Requires-Dist: fastapi[standard]>=0.136.3
+Requires-Dist: holm>=0.10.0
+Requires-Dist: htmy[lxml]>=0.13.1
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: typer>=0.27.1
+Requires-Dist: uvicorn>=0.52.1
+Description-Content-Type: text/markdown
+
+![Linters](https://github.com/volfpeter/htmui/actions/workflows/linters.yml/badge.svg)
+
+**Source code**: [https://github.com/volfpeter/htmui](https://github.com/volfpeter/htmui)
+
+**Live demo**: [https://htmui.vercel.app](https://htmui.vercel.app)
+
+# htmui
+
+Python UI components for [htmy](https://volfpeter.github.io/htmy/), wrapping [BasecoatUI](https://basecoatui.com/) and [Tailwind CSS](https://tailwindcss.com/).
+
+`htmui` is designed with hypermedia applications, and specifically [HTMX](https://htmx.org/), in mind. Components reproduce Basecoat's documented markup so Basecoat's runtime can enhance them.
+
+`htmy` and `holm` have built-in Jinja support. If you use another templating engine, converting the components is straightforward, because `htmy` mimics HTML.
+
+## Key features
+
+- **Vendored**: copy the components you need into your project and adapt them.
+- **`htmui init` CLI** that copies selected components, their dependencies, and shared utilities.
+- **BasecoatUI** components as typed `htmy` functions: buttons, dialogs, sidebars, forms, and more.
+- Extra helpers such as `codeblock` that are not part of Basecoat.
+- Works anywhere `htmy` works, including [holm](https://volfpeter.github.io/holm/).
+
+## Prerequisites
+
+You need [htmy](https://volfpeter.github.io/htmy/) in your project:
+
+```bash
+pip install htmy
+```
+
+For the best developer experience, it is recommended to use [holm](https://volfpeter.github.io/holm/). It brings built-in `htmy` and HTMX support, and is built around FastAPI.
+
+The copied components also need [BasecoatUI](https://basecoatui.com/) and [Tailwind CSS](https://tailwindcss.com/) on the page. CDN snippets are included (see [Assets](#assets)).
+
+## Usage
+
+`htmui` is designed to be vendored. You do not install it as a runtime dependency. Instead, you copy the components you need into your project and adjust them.
+
+```bash
+uvx htmui init
+```
+
+This copies the full catalog into `./components`. Use `-c` to copy only the components you need. Dependencies are included automatically:
+
+```bash
+uvx htmui init -c dialog -c select
+```
+
+Useful options:
+
+```bash
+uvx htmui init --src                  # install into src/components/
+uvx htmui init -p ui                  # install into ./ui
+uvx htmui init -c dialog --dry-run    # print the plan, write nothing
+uvx htmui init --force                # overwrite existing files
+uvx htmui init --skip-existing        # keep existing files
+uvx htmui version                     # package and per-component versions
+```
+
+You can also copy files from `htmui/basecoat/` by hand.
+
+### Example
+
+After `htmui init`:
+
+```python
+from htmy import ComponentType, html
+
+from components.alert import alert
+from components.button import button
+
+
+def saved() -> ComponentType:
+    return html.div(
+        alert("Your changes have been saved.", title="Saved"),
+        button("Continue"),
+    )
+```
+
+Every component has a live example and its Python source in the sidebar.
+
+## Assets
+
+You can add the CDN snippets from `cdn` to your document head:
+
+```python
+from htmy import ComponentType, html
+
+from components import cdn
+
+
+def head() -> ComponentType:
+    return html.head(
+        cdn.css,
+        cdn.tailwind_css,
+        cdn.js,
+    )
+```
+
+Some Basecoat classes may not work with the Tailwind CDN setup, so a local JS/CSS setup is recommended for production. The [demo application](https://github.com/volfpeter/htmui/tree/main/app) shows one such setup.
+
+`codeblock` includes optional [Highlight.js](https://highlightjs.org/) helpers for syntax highlighting.
+
+## Related projects
+
+- [htmy](https://volfpeter.github.io/htmy/): async Python server-side rendering.
+- [holm](https://volfpeter.github.io/holm/): Next.js-like developer experience on FastAPI, `htmy`, and FastHX.
+- [FastHX](https://volfpeter.github.io/fasthx/): HTMX rendering for FastAPI.
+- [BasecoatUI](https://basecoatui.com/): the design system these components wrap.
+
+## Support
+
+Consider supporting the project through [sponsoring](https://buymeacoffee.com/volfpeter), or reach out for [consulting](https://www.volfp.com/contact?subject=Consulting%20-%20htmui) so you can get the most out of the library.
+
+## Development
+
+Python:
+
+- `uv` for project and dependency management.
+- `poethepoet` for tasks. Run `uv run poe` to see them.
+- `mypy` for static analysis.
+- `ruff` for formatting and linting.
+
+JavaScript:
+
+- `npm` for the demo app's Tailwind and Basecoat tooling.
+
+To get started:
+
+```bash
+uv sync
+npm install
+honcho start
+```
+
+`honcho start` runs the demo app and the Tailwind watcher together. You can also run `uv run poe dev` and `uv run poe build-dev-css --watch` separately.
+
+The index page of the demo is generated from this README (`uv run poe build-content`).
+
+## License
+
+The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).
+
+## Credits
+
+This project wouldn't exist without the components and documentation of [BasecoatUI](https://basecoatui.com/).

htmui-0.1.0/README.md

@@ -0,0 +1,146 @@
+![Linters](https://github.com/volfpeter/htmui/actions/workflows/linters.yml/badge.svg)
+
+**Source code**: [https://github.com/volfpeter/htmui](https://github.com/volfpeter/htmui)
+
+**Live demo**: [https://htmui.vercel.app](https://htmui.vercel.app)
+
+# htmui
+
+Python UI components for [htmy](https://volfpeter.github.io/htmy/), wrapping [BasecoatUI](https://basecoatui.com/) and [Tailwind CSS](https://tailwindcss.com/).
+
+`htmui` is designed with hypermedia applications, and specifically [HTMX](https://htmx.org/), in mind. Components reproduce Basecoat's documented markup so Basecoat's runtime can enhance them.
+
+`htmy` and `holm` have built-in Jinja support. If you use another templating engine, converting the components is straightforward, because `htmy` mimics HTML.
+
+## Key features
+
+- **Vendored**: copy the components you need into your project and adapt them.
+- **`htmui init` CLI** that copies selected components, their dependencies, and shared utilities.
+- **BasecoatUI** components as typed `htmy` functions: buttons, dialogs, sidebars, forms, and more.
+- Extra helpers such as `codeblock` that are not part of Basecoat.
+- Works anywhere `htmy` works, including [holm](https://volfpeter.github.io/holm/).
+
+## Prerequisites
+
+You need [htmy](https://volfpeter.github.io/htmy/) in your project:
+
+```bash
+pip install htmy
+```
+
+For the best developer experience, it is recommended to use [holm](https://volfpeter.github.io/holm/). It brings built-in `htmy` and HTMX support, and is built around FastAPI.
+
+The copied components also need [BasecoatUI](https://basecoatui.com/) and [Tailwind CSS](https://tailwindcss.com/) on the page. CDN snippets are included (see [Assets](#assets)).
+
+## Usage
+
+`htmui` is designed to be vendored. You do not install it as a runtime dependency. Instead, you copy the components you need into your project and adjust them.
+
+```bash
+uvx htmui init
+```
+
+This copies the full catalog into `./components`. Use `-c` to copy only the components you need. Dependencies are included automatically:
+
+```bash
+uvx htmui init -c dialog -c select
+```
+
+Useful options:
+
+```bash
+uvx htmui init --src                  # install into src/components/
+uvx htmui init -p ui                  # install into ./ui
+uvx htmui init -c dialog --dry-run    # print the plan, write nothing
+uvx htmui init --force                # overwrite existing files
+uvx htmui init --skip-existing        # keep existing files
+uvx htmui version                     # package and per-component versions
+```
+
+You can also copy files from `htmui/basecoat/` by hand.
+
+### Example
+
+After `htmui init`:
+
+```python
+from htmy import ComponentType, html
+
+from components.alert import alert
+from components.button import button
+
+
+def saved() -> ComponentType:
+    return html.div(
+        alert("Your changes have been saved.", title="Saved"),
+        button("Continue"),
+    )
+```
+
+Every component has a live example and its Python source in the sidebar.
+
+## Assets
+
+You can add the CDN snippets from `cdn` to your document head:
+
+```python
+from htmy import ComponentType, html
+
+from components import cdn
+
+
+def head() -> ComponentType:
+    return html.head(
+        cdn.css,
+        cdn.tailwind_css,
+        cdn.js,
+    )
+```
+
+Some Basecoat classes may not work with the Tailwind CDN setup, so a local JS/CSS setup is recommended for production. The [demo application](https://github.com/volfpeter/htmui/tree/main/app) shows one such setup.
+
+`codeblock` includes optional [Highlight.js](https://highlightjs.org/) helpers for syntax highlighting.
+
+## Related projects
+
+- [htmy](https://volfpeter.github.io/htmy/): async Python server-side rendering.
+- [holm](https://volfpeter.github.io/holm/): Next.js-like developer experience on FastAPI, `htmy`, and FastHX.
+- [FastHX](https://volfpeter.github.io/fasthx/): HTMX rendering for FastAPI.
+- [BasecoatUI](https://basecoatui.com/): the design system these components wrap.
+
+## Support
+
+Consider supporting the project through [sponsoring](https://buymeacoffee.com/volfpeter), or reach out for [consulting](https://www.volfp.com/contact?subject=Consulting%20-%20htmui) so you can get the most out of the library.
+
+## Development
+
+Python:
+
+- `uv` for project and dependency management.
+- `poethepoet` for tasks. Run `uv run poe` to see them.
+- `mypy` for static analysis.
+- `ruff` for formatting and linting.
+
+JavaScript:
+
+- `npm` for the demo app's Tailwind and Basecoat tooling.
+
+To get started:
+
+```bash
+uv sync
+npm install
+honcho start
+```
+
+`honcho start` runs the demo app and the Tailwind watcher together. You can also run `uv run poe dev` and `uv run poe build-dev-css --watch` separately.
+
+The index page of the demo is generated from this README (`uv run poe build-content`).
+
+## License
+
+The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).
+
+## Credits
+
+This project wouldn't exist without the components and documentation of [BasecoatUI](https://basecoatui.com/).

htmui-0.1.0/htmui/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

htmui-0.1.0/htmui/basecoat/accordion.py

@@ -0,0 +1,76 @@
+from htmy import ComponentType, PropertyValue, SafeStr, XBool, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/accordion/"
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/accordion.min.js" defer></script>'
+)
+
+accordion_icon = SafeStr(
+    '<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" '
+    'stroke="currentColor">'
+    '<path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5" /></svg>'
+)
+"""`chevron-down` icon from https://heroicons.com/."""
+
+
+def accordion_item(
+    *content: ComponentType,
+    summary: ComponentType,
+    open: bool = False,
+    disabled: bool = False,
+    icon: ComponentType | None = accordion_icon,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Accordion item.
+
+    Arguments:
+        *content: The content of the accordion item.
+        summary: The summary (trigger) of the item.
+        open: Whether the item is open by default.
+        disabled: Whether the item is disabled.
+        icon: Optional trailing icon in the summary. Defaults to a chevron icon.
+        class_: Extra CSS classes for the root component.
+        **kwargs: Extra attributes for the root component.
+    """
+    if open:
+        kwargs["open"] = XBool.true
+    if disabled:
+        kwargs["aria_disabled"] = "true"
+
+    return html.details(
+        html.summary(summary, icon),
+        html.section(*content),
+        class_=class_,
+        **kwargs,
+    )
+
+
+def accordion(
+    *children: ComponentType,
+    multiple: bool = False,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Accordion root. Children are usually created with `accordion_item()`.
+
+    Arguments:
+        *children: Accordion items.
+        multiple: Allow more than one item open at a time.
+        class_: Extra CSS classes for the root component.
+        **kwargs: Extra attributes for the root component.
+    """
+    if multiple:
+        kwargs["data_multiple"] = ""
+
+    return html.section(
+        *children,
+        class_=join_classes("accordion", class_),
+        **kwargs,
+    )

htmui-0.1.0/htmui/basecoat/alert.py

@@ -0,0 +1,44 @@
+from htmy import ComponentType, PropertyValue, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/alert/"
+
+
+def alert(
+    *children: ComponentType,
+    title: ComponentType,
+    icon: ComponentType = None,
+    footer: ComponentType | None = None,
+    class_: str | None = None,
+    content_class: str | None = None,
+    title_class: str | None = None,
+    destructive: bool = False,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Alert component with optional icon, description, and action region.
+
+    Arguments:
+        *children: Optional content below the title.
+        title: Alert title.
+        icon: Optional icon.
+        footer: Optional footer, typically an `html.footer(...)`.
+        class_: Extra CSS classes for the root element.
+        content_class: Extra CSS classes for the description section.
+        title_class: Extra CSS classes for the title.
+        destructive: Whether to use the destructive variant.
+        **kwargs: Extra attributes for the root element.
+    """
+    if destructive:
+        kwargs["data_variant"] = "destructive"
+
+    return html.div(
+        icon,
+        html.h2(title, class_=title_class),
+        html.section(*children, class_=content_class) if len(children) > 0 else None,
+        footer,
+        class_=join_classes("alert", class_),
+        **kwargs,
+    )

htmui-0.1.0/htmui/basecoat/avatar.py

@@ -0,0 +1,52 @@
+from typing import Literal, TypeAlias
+
+from htmy import ComponentType, PropertyValue, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/avatar/"
+
+AvatarSize: TypeAlias = Literal["sm", "lg"]
+
+
+def avatar(
+    *children: ComponentType,
+    size: AvatarSize | None = None,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Avatar component.
+
+    Arguments:
+        *children: Avatar content.
+        size: Avatar size.
+        class_: Extra CSS classes for the avatar.
+        **kwargs: Extra attributes for the avatar.
+    """
+    if size is not None:
+        kwargs["data_size"] = size
+
+    return html.span(*children, class_=join_classes("avatar", class_), **kwargs)
+
+
+def avatar_group(
+    *children: ComponentType,
+    count: ComponentType | str | None = None,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Group of overlapping avatars with an optional trailing count indicator.
+
+    Arguments:
+        *children: Avatar components.
+        count: Content of the trailing `data-count` indicator.
+        class_: Extra CSS classes for the group.
+        **kwargs: Extra attributes for the root element.
+    """
+    if count is not None:
+        children = (*children, html.span(count, data_count=""))
+
+    return html.div(*children, class_=join_classes("avatar-group", class_), **kwargs)

htmui-0.1.0/htmui/basecoat/badge.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from htmy import html
+from htmy.utils import join
+
+if TYPE_CHECKING:
+    from htmy import ComponentType, PropertyValue
+
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/badge/"
+
+BadgeVariant = Literal["secondary", "destructive", "outline", "ghost"]
+
+
+def badge(
+    *children: ComponentType,
+    variant: BadgeVariant | None = None,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    if variant is not None:
+        kwargs["data_variant"] = variant
+    return html.span(
+        *children,
+        class_=join("badge", class_),
+        **kwargs,
+    )

htmui-0.1.0/htmui/basecoat/breadcrumb.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from htmy import ComponentType, PropertyValue, SafeStr, html
+from htmy.utils import join, join_components
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/breadcrumb/"
+
+chevron_right_icon = SafeStr(
+    '<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" '
+    'stroke="currentColor" class="size-4"><path stroke-linecap="round" stroke-linejoin="round" '
+    'd="m8.25 4.5 7.5 7.5-7.5 7.5" /></svg>'
+)
+"""`chevron-right` icon from https://heroicons.com/ with small adjustments."""
+
+
+def breadcrumb(
+    *children: ComponentType,
+    separator: ComponentType = chevron_right_icon,
+    class_: str | None = None,
+    aria_label: str = "Breadcrumb",
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Breadcrumb navigation component.
+
+    Arguments:
+        *children: Breadcrumb items.
+        separator: Separator to be inserted between items.
+        class_: Extra CSS classes for the root element.
+        aria_label: Accessible name for the breadcrumb.
+        **kwargs: Extra attributes for the root element.
+    """
+    return html.nav(
+        html.ol(
+            *join_components(
+                tuple(html.li(child) for child in children if child is not None),
+                html.li(separator, aria_hidden="true"),
+            ),
+        ),
+        class_=join("breadcrumb", class_),
+        aria_label=aria_label,
+        **kwargs,
+    )

htmui-0.1.0/htmui/basecoat/button.py

@@ -0,0 +1,36 @@
+from typing import Literal, TypeAlias
+
+from htmy import ComponentType, PropertyValue, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/button/"
+
+ButtonVariant: TypeAlias = Literal["outline", "secondary", "ghost", "destructive", "link"]
+
+ButtonSize: TypeAlias = Literal["xs", "sm", "default", "lg", "icon", "icon-xs", "icon-sm", "icon-lg"]
+
+
+def button(
+    *children: ComponentType,
+    variant: ButtonVariant | None = None,
+    size: ButtonSize | None = None,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Button component.
+
+    Arguments:
+        *children: Button content.
+        variant: Button variant.
+        size: Button size.
+        class_: Extra CSS classes for the button.
+        **kwargs: Extra attributes for the button.
+    """
+    if variant is not None:
+        kwargs["data_variant"] = variant
+    if size is not None:
+        kwargs["data_size"] = size
+    return html.button(*children, class_=join_classes("btn", class_), type_="button", **kwargs)

htmui-0.1.0/htmui/basecoat/button_group.py

@@ -0,0 +1,22 @@
+from htmy import ComponentType, PropertyValue, html
+from htmy.utils import join
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/button-group/"
+
+
+def button_group(
+    *children: ComponentType,
+    class_: str = "",
+    vertical: bool = False,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    if "role" not in kwargs:
+        kwargs["role"] = "group"
+
+    if vertical:
+        kwargs["data-orientation"] = "vertical"
+
+    return html.div(*children, class_=join("button-group", class_), **kwargs)

htmui-0.1.0/htmui/basecoat/card.py

@@ -0,0 +1,32 @@
+from typing import Literal
+
+from htmy import ComponentType, PropertyValue, html
+from htmy.utils import join
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/card/"
+
+CardSize = Literal["sm"]
+
+
+def card(
+    *children: ComponentType,
+    class_: str | None = None,
+    size: CardSize | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Card container.
+
+    Arguments:
+        *children: Card content.
+        class_: Extra CSS classes for the root element.
+        size: Optional denser layout size.
+        **kwargs: Extra attributes for the root element.
+    """
+    if size is not None:
+        kwargs["data_size"] = size
+
+    return html.div(*children, class_=join("card", class_), **kwargs)