htmui 0.1.0__py3-none-any.whl

htmui/basecoat/select.py

@@ -0,0 +1,190 @@
+import json
+from typing import Any, Literal
+
+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/select/"
+
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/select.min.js" defer></script>'
+)
+
+
+# `chevron-down` icon, matching the BasecoatUI reference markup.
+_trigger_icon = SafeStr(
+    '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" '
+    'fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" '
+    'class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0">'
+    '<path d="m6 9 6 6 6-6" /></svg>'
+)
+
+
+def option(
+    *children: ComponentType,
+    value: str | None = None,
+    label: str | None = None,
+    disabled: bool = False,
+    selected: bool = False,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    `div` with `role="option"` for `select`.
+
+    Arguments:
+        value: Maps to `data-value`.
+        label: Optional `data-label` overriding the trigger/display text.
+        disabled: Whether the option is disabled.
+        selected: Whether the option is selected.
+        **kwargs: Other attributes passed directly to the element.
+    """
+    kwargs["role"] = "option"
+    if value is not None:
+        kwargs["data-value"] = value
+    if label is not None:
+        kwargs["data-label"] = label
+    if disabled:
+        kwargs["aria-disabled"] = "true"
+    if selected:
+        kwargs["aria-selected"] = "true"
+    return html.div(*children, **kwargs)
+
+
+def group(
+    *items: ComponentType,
+    heading: ComponentType,
+    heading_id: str,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    `div` with `role="group"`, containing options with a linked heading.
+
+    Arguments:
+        label: Group heading content.
+        heading_id: Id of the heading span; also used as `aria-labelledby`.
+        **kwargs: Other attributes passed through to the root element.
+    """
+    kwargs["role"] = "group"
+    kwargs["aria-labelledby"] = heading_id
+    return html.div(
+        html.span(heading, role="heading", id=heading_id),
+        *items,
+        **kwargs,
+    )
+
+
+def select(  # noqa: C901
+    *items: ComponentType,
+    name: str,
+    placeholder: str | None = None,
+    multiple: bool = False,
+    close_on_select: bool = False,
+    format: Literal["object"] | None = None,
+    value: str | list[Any] | None = None,
+    disabled: bool = False,
+    invalid: bool = False,
+    trigger_class: str | None = None,
+    listbox_class: str | None = None,
+    popover_class: str | None = None,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Select component root.
+
+    It contains a hidden input, which is submitted under `name`. Internal element IDs
+    are derived from `name` automatically.
+
+    Arguments:
+        name: The name of the hidden input.
+        placeholder: Text shown in the trigger when nothing is selected.
+        multiple: Allow selecting multiple options.
+        close_on_select: Whether to close the select after selecting an option.
+            It only applies to the multi-select case.
+        format: Value format submitted by the hidden input. Use `"object"` to
+            send the full option object.
+        value: Initially selected value. Pass a string for single select or
+            a list for multiple select.
+        disabled: Disable the trigger button.
+        invalid: Mark the select as invalid for accessibility and validation.
+        trigger_class: Additional classes for the trigger button.
+        listbox_class: Additional classes for the listbox popup.
+        popover_class: Additional classes for the popover wrapper.
+        class_: Additional classes for the root element.
+        **kwargs: Extra attributes for the root element.
+    """
+    id = f"{name}-root"
+    trigger_id = f"{id}-trigger"
+    popover_id = f"{id}-popover"
+    listbox_id = f"{id}-listbox"
+
+    root_attrs: dict[str, PropertyValue] = dict(kwargs)
+    if placeholder is not None:
+        root_attrs["data-placeholder"] = placeholder
+    if multiple and close_on_select:
+        root_attrs["data-close-on-select"] = "true"
+    if format is not None:
+        root_attrs["data-format"] = format
+
+    trigger_attrs: dict[str, PropertyValue] = {
+        "type": "button",
+        "id": trigger_id,
+        "aria-haspopup": "listbox",
+        "aria-expanded": "false",
+        "aria-controls": listbox_id,
+    }
+    if disabled:
+        trigger_attrs["disabled"] = XBool.true
+    if invalid:
+        trigger_attrs["aria-invalid"] = "true"
+    trigger_attrs["class"] = trigger_class
+
+    popover_attrs: dict[str, PropertyValue] = {
+        "id": popover_id,
+        "data-popover": "",
+        "aria-hidden": "true",
+    }
+    if popover_class:
+        popover_attrs["class"] = popover_class
+
+    listbox_attrs: dict[str, PropertyValue] = {
+        "role": "listbox",
+        "id": listbox_id,
+        "aria-orientation": "vertical",
+        "aria-labelledby": trigger_id,
+    }
+    if multiple:
+        listbox_attrs["aria-multiselectable"] = "true"
+    if listbox_class:
+        listbox_attrs["class"] = listbox_class
+
+    effective_value: str
+    if value is None:
+        effective_value = ""
+    elif isinstance(value, (list, tuple)):
+        effective_value = json.dumps(list(value))
+    else:
+        effective_value = str(value)
+
+    return html.div(
+        html.button(
+            html.span(placeholder or "", class_="truncate"),
+            _trigger_icon,
+            **trigger_attrs,
+        ),
+        html.div(
+            html.div(*items, **listbox_attrs),
+            **popover_attrs,
+        ),
+        html.input_(
+            type="hidden",
+            name=name,
+            value=effective_value,
+        ),
+        id=id,
+        class_=join_classes("select", class_),
+        **root_attrs,
+    )

htmui/basecoat/separator.py

@@ -0,0 +1,8 @@
+from htmy import html
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/"
+
+separator = html.hr(role="separator")

htmui/basecoat/sidebar.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from htmy import (
+    ComponentType,
+    PropertyValue,
+    SafeStr,
+    Tag,
+    XBool,
+    as_component_sequence,
+    html,
+    join_classes,
+)
+
+from .button import ButtonSize, ButtonVariant
+from .typing import HorizontalSide
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/sidebar/"
+
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/sidebar.min.js" defer></script>'
+)
+
+
+SidebarItemVariant = Literal["default", "outline"]
+"""Visual variant for menu items and submenu summaries."""
+
+SidebarItemSize = Literal["default", "sm", "lg"]
+"""Size for menu items and submenu summaries."""
+
+
+menu_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="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5"/></svg>'
+)
+"""`bars-3` icon from https://heroicons.com/."""
+
+
+def sidebar(
+    *children: ComponentType,
+    id: str,
+    aria_label: str | None = None,
+    header: ComponentType | None = None,
+    footer: ComponentType | None = None,
+    side: HorizontalSide = "left",
+    initial_open: bool = True,
+    initial_mobile_open: bool = False,
+    class_: str | None = None,
+    nav_class: str | None = None,
+    section_class: str | None = "scrollbar-sm",
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Sidebar component.
+
+    Arguments:
+        *children: The content of the sidebar.
+        id: The sidebar's ID.
+        aria_label: Accessibility label for the sidebar's navigation component.
+        header: Optional content at the top of the sidebar.
+        footer: Optional content at the bottom of the sidebar.
+        side: Side of the viewport the sidebar attaches to.
+        initial_open: Whether the sidebar starts open on desktop. When `False`,
+            the sidebar starts hidden and inert.
+        initial_mobile_open: Whether the sidebar starts open below the
+            mobile breakpoint.
+        class_: Additional classes for the root element.
+        nav_class: Additional classes for the nav element.
+        section_class: Additional classes for the scrollable content section.
+        **kwargs: Extra attributes for the root element.
+    """
+    if not initial_open:
+        kwargs["data_initial_open"] = "false"
+        kwargs["aria_hidden"] = "true"
+        kwargs["inert"] = XBool.true
+
+    if initial_mobile_open:
+        kwargs["data_initial_mobile_open"] = "true"
+
+    return html.aside(
+        html.nav(
+            None if header is None else html.header(*as_component_sequence(header)),
+            html.section(*children, class_=section_class),
+            None if footer is None else html.footer(*as_component_sequence(footer)),
+            **({"aria_label": aria_label} if aria_label else {}),
+            class_=nav_class,
+        ),
+        id=id,
+        class_=join_classes("sidebar", class_),
+        data_side=side,
+        **kwargs,
+    )
+
+
+def sidebar_group(
+    *children: ComponentType,
+    label: ComponentType | None = None,
+    label_id: str | None = None,
+    group_class: str | None = None,
+    list_class: str | None = None,
+    heading_tag: str = "h3",
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Named navigation group inside the sidebar.
+
+    Arguments:
+        *children: The content of the sidebar group.
+        label: Optional group heading content.
+        label_id: Id of the heading element; also used as `aria-labelledby`.
+        group_class: Additional classes for the group wrapper.
+        list_class: Additional classes for the list element.
+        heading_tag: Tag name for the heading element.
+        **kwargs: Attributes passed directly to the group wrapper.
+    """
+    if label_id is not None:
+        kwargs["aria_labelledby"] = label_id
+
+    return html.div(
+        None if label is None else Tag(heading_tag)(label, id=label_id),
+        html.ul(*children, class_=list_class),
+        class_=group_class,
+        role="group",
+        **kwargs,
+    )
+
+
+def sidebar_item(
+    label: ComponentType,
+    *,
+    href: str | None = None,
+    icon: ComponentType | None = None,
+    current: bool = False,
+    variant: SidebarItemVariant | None = None,
+    size: SidebarItemSize | None = None,
+    active: bool = False,
+    disabled: bool = False,
+    keep_mobile_open: bool = False,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Sidebar item.
+
+    Arguments:
+        label: The label of the item.
+        href: Optional destination URL. When omitted, an action button is rendered.
+        icon: Optional content rendered before the label.
+        current: Whether this is the current page.
+        variant: Visual variant of the item.
+        size: The size of the item.
+        active: Whether the item is in an active state.
+        disabled: Whether the item is non-interactive.
+        keep_mobile_open: Keep the mobile sidebar open when this item is
+            clicked, instead of closing it.
+       **kwargs: Attributes passed directly to the item.
+    """
+    if variant is not None:
+        kwargs["data_variant"] = variant
+    if size is not None:
+        kwargs["data_size"] = size
+    if active:
+        kwargs["data_active"] = "true"
+    if keep_mobile_open:
+        kwargs["data_keep_mobile_sidebar_open"] = "true"
+
+    if href is None:
+        if disabled:
+            kwargs["disabled"] = XBool.true
+
+        return html.li(html.button(icon, html.span(label), type="button", **kwargs))
+
+    if current:
+        kwargs["aria_current"] = "page"
+    if disabled:
+        kwargs["aria_disabled"] = "true"
+    return html.li(html.a(icon, html.span(label), href=href, **kwargs))
+
+
+def submenu(
+    *children: ComponentType,
+    label: ComponentType,
+    id: str | None = None,
+    icon: ComponentType | None = None,
+    open: bool = False,
+    active: bool = False,
+    variant: SidebarItemVariant | None = None,
+    size: SidebarItemSize | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Sidebar submenu.
+
+    Arguments:
+        *children: Items wrapped by the submenu.
+        label: Text label shown after the optional icon.
+        icon: Optional content rendered before the label.
+        open: Whether the submenu starts expanded.
+        id: The ID of the element.
+        variant: Visual variant for the summary control.
+        size: Size for the summary control.
+        active: Whether the summary control is in an active state.
+        **kwargs: Attributes passed directly to the summary element.
+    """
+    content_id = None if id is None else f"{id}-content"
+    if variant is not None:
+        kwargs["data_variant"] = variant
+    if size is not None:
+        kwargs["data_size"] = size
+    if active:
+        kwargs["data_active"] = "true"
+    if content_id is not None:
+        kwargs["aria_controls"] = content_id
+
+    details_props: dict[str, PropertyValue] = {}
+    if id is not None:
+        details_props["id"] = id
+    if open:
+        details_props["open"] = XBool.true
+
+    return html.li(
+        html.details(
+            html.summary(
+                icon,
+                html.span(label),
+                **kwargs,
+            ),
+            html.ul(*children, id=content_id),
+            **details_props,
+        )
+    )
+
+
+def sidebar_toggle(
+    content: ComponentType = menu_icon,
+    *,
+    sidebar_id: str,
+    class_: str | None = None,
+    variant: ButtonVariant | None = None,
+    size: ButtonSize | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Button that toggles the sidebar with the given ID.
+
+    Arguments:
+        content: Button content. Defaults to `menu_icon`.
+        sidebar_id: Id of the sidebar to toggle.
+        variant: Button variant.
+        size: Button size.
+        **kwargs: Other attributes passed directly to the button.
+    """
+    if class_ is not None:
+        kwargs["class_"] = class_
+    if variant is not None:
+        kwargs["data_variant"] = variant
+    if size is not None:
+        kwargs["data_size"] = size
+    return html.button(
+        content,
+        type="button",
+        onclick=f"document.getElementById('{sidebar_id}')?.toggle()",
+        **kwargs,
+    )

htmui/basecoat/slider.py

@@ -0,0 +1,50 @@
+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/slider/"
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/range.min.js" defer></script>'
+)
+
+
+def slider(
+    *,
+    start_label: ComponentType | None = None,
+    middle_label: ComponentType | None = None,
+    end_label: ComponentType | None = None,
+    disabled: bool = False,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Range input styled as a slider, with optional labels.
+
+    Arguments:
+        start_label: Optional label shown at the start of a row above the slider.
+        middle_label: Optional label shown in the middle of the row above the slider.
+        end_label: Optional label shown at the end of the row above the slider.
+        disabled: Whether the slider is disabled.
+        class_: Extra CSS classes for the input element.
+        **kwargs: Extra attributes for the input element.
+    """
+    if disabled:
+        kwargs["disabled"] = XBool.true
+
+    input_ = html.input_(type="range", class_=join_classes("input", class_), **kwargs)
+
+    if start_label is None and middle_label is None and end_label is None:
+        return input_
+
+    return html.div(
+        html.div(
+            start_label if start_label is not None else html.label(),
+            middle_label if middle_label is not None else html.label(),
+            end_label if end_label is not None else html.label(),
+            class_="flex items-center justify-between gap-2",
+        ),
+        input_,
+        class_="grid w-full gap-1",
+    )

htmui/basecoat/spinner.py

@@ -0,0 +1,43 @@
+from htmy import ComponentType, PropertyValue, SafeStr, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/spinner/"
+
+spinner_path = SafeStr('<path d="M21 12a9 9 0 1 1-6.219-8.56" />')
+"""Path for the `loader-circle` icon from https://lucide.dev."""
+
+
+def spinner(
+    *children: ComponentType,
+    aria_label: str = "Loading",
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Animated spinner.
+
+    Arguments:
+        *children: SVG children (typically `<path>` elements).
+            Defaults to `spinner_path`.
+        aria_label: Accessible label for the spinner.
+        class_: Extra CSS classes for the root SVG.
+        **kwargs: Extra attributes for the SVG.
+    """
+    return html.svg(
+        *(children if len(children) > 0 else (spinner_path,)),
+        xmlns="http://www.w3.org/2000/svg",
+        width="24",
+        height="24",
+        viewBox="0 0 24 24",
+        fill="none",
+        stroke="currentColor",
+        stroke_width="2",
+        stroke_linecap="round",
+        stroke_linejoin="round",
+        role="status",
+        aria_label=aria_label,
+        class_=join_classes("animate-spin", class_),
+        **kwargs,
+    )

htmui/basecoat/switch.py

@@ -0,0 +1,50 @@
+from typing import Literal
+
+from htmy import ComponentType, PropertyValue, XBool, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/switch/"
+
+SwitchSize = Literal["sm"]
+
+
+def switch(
+    *,
+    name: str,
+    checked: bool = False,
+    disabled: bool = False,
+    invalid: bool = False,
+    size: SwitchSize | None = None,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Checkbox input styled as a switch.
+
+    Arguments:
+        name: The name of the input.
+        checked: Whether the switch is initially checked.
+        disabled: Whether the switch is disabled.
+        invalid: Whether to mark the switch as invalid.
+        size: Optional size variant.
+        class_: Extra CSS classes for the input element.
+        **kwargs: Extra attributes for the input element.
+    """
+    if checked:
+        kwargs["checked"] = XBool.true
+    if disabled:
+        kwargs["disabled"] = XBool.true
+    if invalid:
+        kwargs["aria_invalid"] = "true"
+    if size is not None:
+        kwargs["data_size"] = size
+
+    return html.input_(
+        type="checkbox",
+        role="switch",
+        name=name,
+        class_=join_classes("input", class_),
+        **kwargs,
+    )

htmui/basecoat/table.py

@@ -0,0 +1,38 @@
+from htmy import ComponentType, PropertyValue, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/table/"
+
+
+def table(
+    *children: ComponentType,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Table component.
+
+    Arguments:
+        *children: Table content.
+        class_: Extra CSS classes for the table.
+        **kwargs: Extra attributes for the table element.
+    """
+    return html.table(*children, class_=join_classes("table", class_), **kwargs)
+
+
+def table_container(
+    *children: ComponentType,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Horizontally scrollable wrapper for wide tables.
+
+    Arguments:
+        *children: Container content, usually a single `table`.
+        class_: Extra CSS classes for the container.
+        **kwargs: Extra attributes for the container.
+    """
+    return html.div(*children, class_=join_classes("table-container", class_), **kwargs)