htmui 0.1.0__py3-none-any.whl

htmui/__init__.py

@@ -0,0 +1 @@
+__version__ = "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/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/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/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/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/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/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/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)

htmui/basecoat/cdn.py

@@ -0,0 +1,14 @@
+from htmy import SafeStr
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com"
+
+css = SafeStr(
+    '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/basecoat.cdn.min.css" />'
+)
+
+js = SafeStr('<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/all.min.js" defer></script>')
+
+tailwind_css = SafeStr('<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>')

htmui/basecoat/chart.py

@@ -0,0 +1,86 @@
+import json
+from typing import Any, Protocol
+
+from htmy import ComponentType, Fragment, PropertyValue, SafeStr, html
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/chart/"
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/chart.min.js" defer></script>'
+)
+
+chart_js = SafeStr('<script src="https://cdn.jsdelivr.net/npm/chart.js/dist/chart.umd.min.js"></script>')
+"""Chart.js CDN script."""
+
+
+class ChartInitScriptFactory(Protocol):
+    """
+    Callable protocol for building a chart initialization script element
+    from a canvas ID and a chart config.
+    """
+
+    def __call__(self, id: str, config: dict[str, Any], /) -> ComponentType:
+        """
+        Returns the script element that initializes the chart for
+        the given ID with the given chart config.
+        """
+        ...
+
+
+class handle_chart_init:
+    @staticmethod
+    def default(id: str, config: dict[str, Any], /) -> ComponentType:
+        """
+        Default `ChartInitScriptFactory` which initializes the chart once
+        the Basecoat runtime is ready.
+        """
+        config_json = json.dumps(config, separators=(",", ":")).replace("</", "<\\/")
+        return html.script(
+            SafeStr(
+                f"""(() => {{
+  const canvas = document.getElementById({json.dumps(id)});
+  if (!canvas) return;
+  const init = () => window.basecoat?.chart?.(canvas, {config_json});
+  if (document.readyState === "loading") {{
+    document.addEventListener("DOMContentLoaded", init, {{ once: true }});
+  }} else {{
+    init();
+  }}
+}})();"""
+            )
+        )
+
+
+def chart(
+    *,
+    id: str,
+    config: dict[str, Any] | None = None,
+    class_: str | None = None,
+    script: ChartInitScriptFactory | None = handle_chart_init.default,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Chart.js canvas themed with Basecoat defaults.
+
+    Arguments:
+        id: Canvas element ID.
+        config: Optional JSON-serializable config for `basecoat.chart()`.
+            See the Basecoat Chart documentation for details.
+        class_: Extra CSS classes for the canvas element.
+        script: Optional callback that receives the canvas ID and `config` and
+            returns the initialization script element. Defaults to
+            `handle_chart_init.default`.
+        **kwargs: Extra attributes for the canvas element.
+    """
+    canvas = html.canvas(
+        id=id,
+        class_=class_,
+        **kwargs,
+    )
+    if config is None or script is None:
+        return canvas
+
+    return Fragment(canvas, script(id, config))

htmui/basecoat/codeblock.py

@@ -0,0 +1,109 @@
+from htmy import ComponentType, SafeStr, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/"
+
+
+copy_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-6"><path stroke-linecap="round" stroke-linejoin="round" '
+    'd="M8.25 7.5V6.108c0-1.135.845-2.098 1.976-2.192.373-.03.748-.057 1.123-.08M15.75 18H18a2.25 '
+    "2.25 0 0 0 2.25-2.25V6.108c0-1.135-.845-2.098-1.976-2.192a48.424 48.424 0 0 0-1.123-.08M15.75 "
+    "18.75v-1.875a3.375 3.375 0 0 0-3.375-3.375h-1.5a1.125 1.125 0 0 1-1.125-1.125v-1.5A3.375 3.375 "
+    "0 0 0 6.375 7.5H5.25m11.9-3.664A2.251 2.251 0 0 0 15 2.25h-1.5a2.251 2.251 0 0 0-2.15 1.586m5.8 "
+    "0c.065.21.1.433.1.664v.75h-6V4.5c0-.231.035-.454.1-.664M6.75 7.5H4.875c-.621 0-1.125.504-1.125 "
+    '1.125v12c0 .621.504 1.125 1.125 1.125h9.75c.621 0 1.125-.504 1.125-1.125V16.5a9 9 0 0 0-9-9Z" /></svg>'
+)
+"""`clipboard-document` icon from https://heroicons.com/."""
+
+
+copy_button_click_handler = SafeStr("""
+const button = this;
+const code = this.parentElement.querySelector('pre code');
+if (!code) return;
+const clickedClass = 'text-green-700';
+const svg = this.parentElement.querySelector('svg');
+navigator.clipboard.writeText(code.textContent || '').then(() => {
+  svg?.classList.add(clickedClass);
+  setTimeout(() => {
+    svg?.classList.remove(clickedClass);
+  }, 2000);
+}).catch(err => {
+  console.error('Failed to copy text: ', err);
+});""")
+"""JavaScript for handling copy button click events."""
+
+
+def copy_button(icon: ComponentType = copy_icon) -> ComponentType:
+    return html.button(
+        icon,
+        onclick=copy_button_click_handler,
+        class_="btn size-8 absolute right-2.5 top-2 group hover:text-foreground text-muted-foreground",
+        data_variant="ghost",
+        data_size="icon",
+    )
+
+
+def codeblock(code: str, *, code_class: str | None = None) -> ComponentType:
+    return html.pre(
+        html.code(code, class_=join_classes(code_class, "!bg-muted/40 !p-3.5")),
+        copy_button(),
+        class_="grid text-sm max-h-[650px] overflow-y-auto rounded-xl scrollbar relative",
+    )
+
+
+_default_hljs_version = "11.11.1"
+
+
+def highlightjs_theme(theme: str = "default", *, version: str = _default_hljs_version) -> SafeStr:
+    return SafeStr(
+        f'<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/{version}/styles/{theme}.min.css">'
+    )
+
+
+def highlightjs_js(*, version: str = _default_hljs_version) -> SafeStr:
+    return SafeStr(
+        f'<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/{version}/highlight.min.js"></script>'
+    )
+
+
+def highlightjs_languages(*languages: str, version: str = _default_hljs_version) -> SafeStr:
+    return SafeStr(
+        "\n".join(
+            (
+                f'<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/{version}/languages/{lang}.min.js"></script>'
+                for lang in languages
+            )
+        )
+    )
+
+
+class highlightjs_events:
+    dom_content_loaded = "DOMContentLoaded"
+    htmx_after_swap = "htmx:after:swap"
+
+
+def highlightjs_on_load(*events: str) -> SafeStr:
+    return SafeStr(
+        "\n".join(
+            (
+                "<script>",
+                "const highlight = () => {",
+                "  if (!window.hljs) return;",
+                "  document",
+                "  .querySelectorAll(",
+                "    'pre code:not([data-highlighted]), code.highlight:not([data-highlighted])'",
+                ")",
+                "  .forEach(el => window.hljs.highlightElement(el));",
+                "};",
+                "",
+                "if (!window._hljsInit) {",
+                "  window._hljsInit = true;",
+                *(f"  document.addEventListener('{event}', highlight);" for event in events),
+                "}",
+                "</script>",
+            )
+        )
+    )