htmui 0.1.0__py3-none-any.whl

htmui/basecoat/combobox.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/combobox/"
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/combobox.min.js" defer></script>'
+)
+
+dropdown_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-5"><path stroke-linecap="round" stroke-linejoin="round" '
+    'd="M8.25 15 12 18.75 15.75 15m-7.5-6L12 5.25 15.75 9" /></svg>'
+)
+"""`chevron-up-down` icon from https://heroicons.com/."""
+
+
+def option(
+    *children: ComponentType,
+    value: str | None = None,
+    label: str | None = None,
+    filter: str | None = None,
+    force: bool = False,
+    disabled: bool = False,
+    keywords: str | None = None,
+    selected: bool = False,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Search option for `combobox`.
+
+    Arguments:
+        value: The value submitted by the hidden input.
+        label: Optional label that overrides the option content in
+            the displayed input when the `option` is selected.
+        filter: Optional filter text.
+        force: When `true`, the option always stays visible.
+        disabled: Whether the option is disabled and non-selectable.
+        keywords: Optional keywords for filtering.
+        selected: Whether the option is initially 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 keywords is not None:
+        kwargs["data-keywords"] = keywords
+    if filter is not None:
+        kwargs["data-filter"] = filter
+    if force:
+        kwargs["data-force"] = "true"
+    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:
+        heading: Group heading content.
+        heading_id: Id of the heading element; 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 combobox(  # noqa: C901
+    *items: ComponentType,
+    name: str,
+    value: str | list[Any] | None = None,
+    placeholder: str | None = None,
+    disabled: bool = False,
+    invalid: bool = False,
+    empty_message: str | None = None,
+    class_: str | None = None,
+    multi: bool = False,
+    auto_highlight: bool = False,
+    close_on_select: bool = False,
+    data_format: Literal["object"] | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Combobox component root.
+
+    The component is input-first: the visible text input filters the list of
+    options, while a hidden input stores the value submitted under `name`.
+
+    Internal element IDs are derived from `name` automatically.
+
+    Arguments:
+        name: The name of the hidden input.
+        value: The value of the combobox.
+        placeholder: Placeholder text for the visible input.
+        disabled: Disables the combobox.
+        invalid: Mark the input as invalid for accessibility and validation.
+        empty_message: Optional message shown when the filter matches nothing.
+        class_: Additional classes for the root element.
+        multi: Whether multi-selection is enabled.
+        auto_highlight: Make the first visible option active when the list opens
+            or filters, so Enter can select it without arrowing first.
+        close_on_select: Whether to close the popover after selecting an option
+            in multi-selection mode.
+        data_format: Submitted value format. Use `"object"` to serialize selected
+            values as `{ value, label }` objects.
+        **kwargs: Extra attributes for the root element.
+    """
+    root_id = f"{name}-root"
+    input_id = f"{root_id}-input"
+    popover_id = f"{root_id}-popover"
+    listbox_id = f"{root_id}-listbox"
+
+    if multi and close_on_select:
+        kwargs["data-close-on-select"] = "true"
+    if auto_highlight:
+        kwargs["data-auto-highlight"] = "true"
+    if data_format is not None:
+        kwargs["data-format"] = data_format
+
+    input_attrs: dict[str, PropertyValue] = {
+        "type": "text",
+        "role": "combobox",
+        "placeholder": placeholder,
+        "autocomplete": "off",
+        "autocorrect": "off",
+        "spellcheck": "false",
+        "aria-autocomplete": "list",
+        "aria-expanded": "false",
+        "aria-controls": listbox_id,
+        "id": input_id,
+    }
+    if disabled:
+        input_attrs["disabled"] = XBool.true
+    if invalid:
+        input_attrs["aria-invalid"] = "true"
+
+    listbox_attrs: dict[str, PropertyValue] = {
+        "role": "listbox",
+        "id": listbox_id,
+        "aria-labelledby": input_id,
+        "aria-orientation": "vertical",
+    }
+    if multi:
+        listbox_attrs["aria-multiselectable"] = "true"
+    if empty_message is not None:
+        listbox_attrs["data-empty"] = empty_message
+
+    effective_value: str
+    if value is None:
+        effective_value = "" if not multi else "[]"
+    elif isinstance(value, (list, tuple)):
+        effective_value = json.dumps(list(value))
+    else:
+        effective_value = str(value)
+
+    return html.div(
+        html.input_(**input_attrs),
+        dropdown_icon,
+        html.div(
+            html.div(*items, **listbox_attrs),
+            id=popover_id,
+            data_popover=XBool.true,
+            aria_hidden="true",
+        ),
+        html.input_(type="hidden", name=name, value=effective_value),
+        id=root_id,
+        class_=join_classes("combobox", class_),
+        **kwargs,
+    )

htmui/basecoat/command.py

@@ -0,0 +1,128 @@
+from typing import Any
+
+from htmy import ComponentType, PropertyValue, SafeStr, html, join_classes
+
+from .menu import menu_item
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/command/"
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/command.min.js" defer></script>'
+)
+
+
+search_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="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" /></svg>'
+)
+"""`magnifying-glass` icon from https://heroicons.com/."""
+
+
+def command(
+    *items: ComponentType,
+    id: str,
+    input_icon: ComponentType = None,
+    input_placeholder: str = "Type a command or search...",
+    aria_label: str | None = "Command menu",
+    no_results_message: str = "No results found.",
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """Basecoat v1 command menu.
+
+    Items should be created with `menu_item(..., filter=..., keywords=...)` from
+    `htmui.basecoat.menu`. The `filter` text is required for the command JavaScript
+    to match the item while typing.
+    """
+    menu_id = f"{id}-menu"
+    root_props: dict[str, Any] = {"id": id}
+    if aria_label is not None:
+        root_props["aria_label"] = aria_label
+
+    return html.div(
+        html.header(
+            input_icon,
+            html.input_(
+                type="text",
+                id=f"{id}-input",
+                role="combobox",
+                autocomplete="off",
+                autocorrect="off",
+                placeholder=input_placeholder,
+                spellcheck="false",
+                aria_autocomplete="list",
+                aria_expanded="true",
+                aria_controls=menu_id,
+            ),
+        ),
+        html.div(
+            *items,
+            id=menu_id,
+            role="menu",
+            aria_orientation="vertical",
+            data_empty=no_results_message,
+        ),
+        class_=join_classes("command", class_),
+        **root_props,
+        **kwargs,
+    )
+
+
+def command_item(
+    *children: ComponentType,
+    filter: str,
+    keywords: str | None = None,
+    shortcut: str | None = None,
+    indicator: ComponentType | None = None,
+    disabled: bool = False,
+    force: bool = False,
+    keep_open: bool = False,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """Basecoat v1 command item (`filter` is required for the command JS to match it)."""
+    return menu_item(
+        *children,
+        filter=filter,
+        keywords=keywords,
+        shortcut=shortcut,
+        shortcut_kind="command",
+        indicator=indicator,
+        disabled=disabled,
+        force=force,
+        keep_open=keep_open,
+        class_=class_,
+        **kwargs,  # type: ignore[arg-type]
+    )
+
+
+def command_dialog(
+    *items: ComponentType,
+    id: str,
+    input_icon: ComponentType = None,
+    input_placeholder: str = "Type a command or search...",
+    aria_label: str | None = "Command menu",
+    no_results_message: str = "No results found.",
+    onclick: str | None = "if (event.target === this) this.close()",
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """Basecoat v1 command palette wrapped in `<dialog class="command-dialog">`."""
+    return html.dialog(
+        command(
+            *items,
+            id=f"{id}-command",
+            input_icon=input_icon,
+            input_placeholder=input_placeholder,
+            aria_label=None,
+            no_results_message=no_results_message,
+        ),
+        id=id,
+        class_="command-dialog",
+        aria_label=aria_label,
+        onclick=onclick,
+        **kwargs,
+    )

htmui/basecoat/dialog.py

@@ -0,0 +1,165 @@
+from typing import Literal
+
+from htmy import ComponentType, PropertyValue, SafeStr, html, join_classes
+
+from .button import ButtonSize, ButtonVariant
+from .typing import IdToProperty
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/dialog/"
+
+
+class handle_close_button_click:
+    close: str = "this.closest('dialog').close()"
+    delete: str = "this.closest('dialog').delete()"
+
+
+close_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-5">'
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" />'
+    "</svg>"
+)
+"""`x-mark` icon from https://heroicons.com/."""
+
+
+def close_button(
+    icon: ComponentType = close_icon,
+    *,
+    onclick: str = handle_close_button_click.close,
+    aria_label: str = "Close dialog",
+    class_: str | None = None,
+    size: ButtonSize | None = "icon-sm",
+    variant: ButtonVariant | None = "ghost",
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """Close button for dialogs."""
+    if variant is not None:
+        kwargs["data_variant"] = variant
+    if size is not None:
+        kwargs["data_size"] = size
+    return html.button(
+        icon,
+        type="button",
+        class_=join_classes("btn", class_),
+        onclick=onclick,
+        aria_label=aria_label,
+        **kwargs,
+    )
+
+
+AlertDialogSize = Literal["sm"]
+
+
+class handle_click:
+    close: str = "if (event.target === this) this.close()"
+    delete: str = "if (event.target === this) this.delete()"
+
+
+def dialog(
+    *children: ComponentType,
+    id: str,
+    title: ComponentType,
+    description: ComponentType | None = None,
+    footer: ComponentType | None = None,
+    close_button: ComponentType | None = close_button(),  # noqa: B008
+    figure: ComponentType | None = None,
+    alert: bool = False,
+    size: AlertDialogSize | None = None,
+    class_: str | None = None,
+    content_class: str | None = None,
+    onclick: str = handle_click.close,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Dialog or alert-dialog modal.
+
+    Arguments:
+        *children: Dialog body content.
+        id: Dialog element id.
+        title: Dialog title.
+        description: Optional description shown under the title.
+        footer: Optional footer. Should be an `html.footer(...)` when provided.
+        close_button: Optional close button.
+        figure: Optional media to show in a `figure` in the header.
+        alert: Whether this is an alert dialog.
+        size: Dialog size.
+        class_: Extra CSS classes for the root `dialog` element.
+        content_class: Extra CSS classes for the inner content.
+        onclick: Click handler for the root `dialog` element. Ignored for alert dialogs.
+        **kwargs: Extra attributes for the `dialog` element.
+    """
+    title_id = f"{id}-title"
+    description_id = f"{id}-description"
+    kwargs["aria_labelledby"] = title_id
+    if not alert:
+        kwargs["onclick"] = onclick
+    if size is not None:
+        kwargs["data_size"] = size
+    if description is not None:
+        kwargs["aria_describedby"] = description_id
+
+    return html.dialog(
+        html.div(
+            html.header(
+                html.figure(figure) if figure is not None else None,
+                html.h2(title, id=title_id),
+                html.p(description, id=description_id) if description is not None else None,
+            ),
+            html.section(*children) if len(children) > 0 else None,
+            footer,
+            close_button,
+            class_=content_class,
+        ),
+        id=id,
+        class_=join_classes("alert-dialog" if alert else "dialog", class_),
+        **kwargs,
+    )
+
+
+class handle_show_button_click:
+    @staticmethod
+    def show_modal(dialog_id: str) -> PropertyValue:
+        return f"document.getElementById('{dialog_id}').showModal()"
+
+
+def show_dialog_button(
+    title: ComponentType,
+    *,
+    dialog_id: str | None = None,
+    onclick: IdToProperty | None = handle_show_button_click.show_modal,
+    class_: str | None = None,
+    variant: ButtonVariant | None = "outline",
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Button that opens a dialog.
+
+    Arguments:
+        title: Button content.
+        dialog_id: Target dialog ID. Required when `onclick` is not `None`.
+        onclick: Optional callback that receives `dialog_id` and returns the value of
+            the `onclick` property. Defaults to `handle_show_button_click.show_modal()`.
+        class_: Extra CSS classes for the button.
+        variant: Button variant.
+        **kwargs: Extra attributes for the button.
+    """
+    if onclick is not None:
+        if dialog_id is None:
+            raise ValueError("dialog_id is required when onclick is set")
+
+        click = onclick(dialog_id)
+        if click is not None:
+            kwargs["onclick"] = click
+
+    if variant is not None:
+        kwargs["data_variant"] = variant
+
+    return html.button(
+        title,
+        class_=join_classes("btn", class_),
+        type="button",
+        **kwargs,
+    )

htmui/basecoat/drawer.py

@@ -0,0 +1,66 @@
+from htmy import ComponentType, PropertyValue, SafeStr, html, join_classes
+
+from .typing import Side
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/drawer/"
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/drawer.min.js" defer></script>'
+)
+
+
+def drawer(
+    *children: ComponentType,
+    id: str,
+    title: ComponentType | None = None,
+    description: ComponentType | None = None,
+    footer: ComponentType | None = None,
+    side: Side | None = None,
+    class_: str | None = None,
+    content_class: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Drawer component.
+
+    Arguments:
+        *children: Drawer body content.
+        id: Drawer element ID.
+        title: Optional title.
+        description: Optional description shown under the title.
+        footer: Optional footer. Should be an `html.footer()` when provided.
+        side: On which side the drawer should appear.
+        class_: Extra CSS classes for the root element.
+        content_class: Extra CSS classes for the inner content.
+        **kwargs: Extra attributes for the root element.
+    """
+    title_id = f"{id}-title"
+    description_id = f"{id}-description"
+    if title is not None:
+        kwargs["aria_labelledby"] = title_id
+    if description is not None:
+        kwargs["aria_describedby"] = description_id
+    if side is not None:
+        kwargs["data_side"] = side
+
+    header = None
+    if title is not None or description is not None:
+        header = html.header(
+            html.h2(title, id=title_id) if title is not None else None,
+            html.p(description, id=description_id) if description is not None else None,
+        )
+
+    return html.dialog(
+        html.article(
+            header,
+            html.section(*children) if len(children) > 0 else None,
+            footer,
+            class_=content_class,
+        ),
+        id=id,
+        class_=join_classes("drawer", class_),
+        **kwargs,
+    )

htmui/basecoat/dropdown_menu.py

@@ -0,0 +1,59 @@
+from htmy import ComponentType, PropertyValue, SafeStr, html, join_classes
+
+from .button import ButtonVariant
+from .typing import Align, FloatingSide
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/dropdown-menu/"
+
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/dropdown-menu.min.js" defer></script>'
+)
+
+
+def dropdown_menu(
+    *items: ComponentType,
+    id: str,
+    button_content: ComponentType,
+    button_class: str | None = None,
+    button_variant: ButtonVariant | None = "outline",
+    class_: str | None = None,
+    popover_class: str | None = None,
+    popover_align: Align | None = None,
+    popover_side: FloatingSide | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    menu_id = f"{id}-menu"
+    button_id = f"{menu_id}-button"
+
+    return html.div(
+        html.button(
+            button_content,
+            type="button",
+            id=button_id,
+            aria_controls=menu_id,
+            aria_expanded="false",
+            aria_haspopup="menu",
+            class_=join_classes("btn", button_class),
+            **({"data_variant": button_variant} if button_variant else {}),
+        ),
+        html.div(
+            html.div(
+                *items,
+                id=menu_id,
+                role="menu",
+                aria_labelledby=button_id,
+            ),
+            data_popover="",
+            aria_hidden="true",
+            class_="min-w-56" if popover_class is None else popover_class,
+            data_align=popover_align,
+            data_side=popover_side,
+        ),
+        class_=join_classes("dropdown-menu", class_),
+        id=id,
+        **kwargs,
+    )

htmui/basecoat/field.py

@@ -0,0 +1,91 @@
+from typing import Literal
+
+from htmy import ComponentType, PropertyValue, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/field/"
+
+FieldOrientation = Literal["horizontal", "responsive"]
+
+
+def fieldset(
+    *children: ComponentType,
+    title: ComponentType | None = None,
+    subtitle: ComponentType | None = None,
+    class_: str | None = None,
+    title_class: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Fieldset that groups related fields.
+
+    Arguments:
+        *children: Fields and other content inside the fieldset.
+        title: Optional title.
+        subtitle: Optional description, shown after the title.
+        class_: Extra CSS classes for the root element.
+        title_class: Extra CSS classes for the title.
+        **kwargs: Extra attributes for the root element.
+    """
+    return html.fieldset(
+        html.legend(title, class_=title_class) if title is not None else None,
+        subtitle,
+        *children,
+        class_=join_classes("fieldset", class_),
+        **kwargs,
+    )
+
+
+def field(
+    *children: ComponentType,
+    orientation: FieldOrientation | None = None,
+    invalid: bool = False,
+    disabled: bool = False,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Single field.
+
+    Arguments:
+        *children: Field content (label, control, description, etc.).
+        orientation: Layout orientation.
+        invalid: Whether to mark the field as invalid.
+        disabled: Whether to mark the field as disabled.
+        class_: Extra CSS classes for the root element.
+        **kwargs: Extra attributes for the root element.
+    """
+    if orientation is not None:
+        kwargs["data_orientation"] = orientation
+    if invalid:
+        kwargs["data_invalid"] = "true"
+    if disabled:
+        kwargs["data_disabled"] = "true"
+
+    return html.div(*children, class_=join_classes("field", class_), role="group", **kwargs)
+
+
+def field_separator(
+    label: ComponentType | None = None,
+    *,
+    class_: str | None = None,
+    label_class: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Separator between field groups.
+
+    Arguments:
+        label: Optional label rendered over the separator.
+        class_: Extra CSS classes for the root element.
+        label_class: Extra CSS classes for the label element.
+        **kwargs: Extra attributes for the root element.
+    """
+    return html.div(
+        html.hr(role="separator"),
+        html.span(label, class_=label_class) if label is not None else None,
+        class_=join_classes("field-separator", class_),
+        **kwargs,
+    )