htmui 0.1.0__py3-none-any.whl

htmui/basecoat/tabs.py

@@ -0,0 +1,109 @@
+from typing import Literal, TypeAlias
+
+from htmy import ComponentSequence, ComponentType, PropertyValue, SafeStr, html, join_classes
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/tabs/"
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/tabs.min.js" defer></script>'
+)
+
+Orientation: TypeAlias = Literal["horizontal", "vertical"]
+
+TabsVariant: TypeAlias = Literal["line"]
+
+
+def tab_button(
+    *children: ComponentType,
+    id: str,
+    panel_id: str,
+    selected: bool = False,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Tab button.
+
+    Arguments:
+        *children: Button content.
+        id: Button ID.
+        panel_id: The ID of the controlled tab panel.
+        selected: Whether this tab is active.
+        class_: Extra CSS classes for the button.
+        **kwargs: Extra attributes for the button.
+    """
+    return html.button(
+        *children,
+        type="button",
+        role="tab",
+        id=id,
+        aria_controls=panel_id,
+        aria_selected="true" if selected else "false",
+        tabindex="0" if selected else "-1",
+        class_=class_,
+        **kwargs,
+    )
+
+
+def tab_panel(
+    *children: ComponentType,
+    id: str,
+    button_id: str,
+    selected: bool = False,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Tab panel.
+
+    Arguments:
+        *children: Panel content.
+        id: Panel ID.
+        button_id: The ID of the button that controls this tab panel.
+        selected: Whether this panel is active.
+        class_: Extra CSS classes for the panel.
+        **kwargs: Extra attributes for the panel.
+    """
+    if not selected:
+        kwargs["hidden"] = ""
+
+    return html.div(
+        *children,
+        role="tabpanel",
+        id=id,
+        aria_labelledby=button_id,
+        tabindex="-1",
+        aria_selected="true" if selected else "false",
+        class_=class_,
+        **kwargs,
+    )
+
+
+def tabs(
+    *panels: ComponentType,
+    buttons: ComponentSequence,
+    orientation: Orientation = "horizontal",
+    variant: TabsVariant | None = None,
+    class_: str | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Tabs root with a tablist and panels.
+
+    Arguments:
+        *panels: Tab panels.
+        buttons: Sequence of tab buttons.
+        orientation: Tablist orientation.
+        variant: Optional tablist style.
+        class_: Extra CSS classes for the root element.
+        **kwargs: Extra attributes for the root element.
+    """
+    return html.div(
+        html.nav(*buttons, role="tablist", aria_orientation=orientation, data_variant=variant),
+        *panels,
+        class_=join_classes("tabs", class_),
+        **kwargs,
+    )

htmui/basecoat/theme_switcher.py

@@ -0,0 +1,58 @@
+from htmy import ComponentType, SafeStr, html
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/theme-switcher/"
+
+
+light_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="M12 3v2.25m6.364.386-1.591 1.591M21 12h-2.25m-.386 6.364-1.591-1.591M12 '
+    "18.75V21m-4.773-4.227-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 "
+    '12a3.75 3.75 0 1 1-7.5 0 3.75 3.75 0 0 1 7.5 0Z" /></svg>'
+)
+"""`sun` icon from https://heroicons.com/."""
+
+dark_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.752 15.002A9.72 9.72 0 0 1 18 15.75c-5.385 0-9.75-4.365-9.75-9.75 '
+    "0-1.33.266-2.597.748-3.752A9.753 9.753 0 0 0 3 11.25C3 16.635 7.365 21 "
+    '12.75 21a9.753 9.753 0 0 0 9.002-5.998Z" /></svg>'
+)
+"""`moon` icon from https://heroicons.com/."""
+
+js = SafeStr(
+    """<script>
+  (() => {
+    try {
+      const stored = localStorage.getItem("themeMode");
+      if (stored ? stored === "dark" : matchMedia("(prefers-color-scheme: dark)").matches) {
+        document.documentElement.classList.add("dark");
+      }
+    } catch (_) {}
+  })();
+</script>"""
+)
+
+
+def theme_switcher(
+    *,
+    class_: str = "btn size-8",
+    variant: str = "outline",
+    size: str = "icon",
+) -> ComponentType:
+    return html.button(
+        html.span(light_icon, class_="hidden dark:block"),
+        html.span(dark_icon, class_="block dark:hidden"),
+        type="button",
+        aria_label="Toggle theme",
+        class_=class_,
+        data_tooltip="Toggle theme",
+        data_side="bottom",
+        data_size=size,
+        data_variant=variant,
+        onclick="window.basecoat.theme.toggle()",
+    )

htmui/basecoat/toast.py

@@ -0,0 +1,97 @@
+from typing import Literal
+
+from htmy import ComponentType, Fragment, PropertyValue, SafeStr, html, join_classes
+
+from .typing import Align
+
+__version__ = "0.2.0"
+__framework__ = "BasecoatUI"
+__framework_version__ = "1"
+__framework_url__ = "https://basecoatui.com/components/toast/"
+
+ToastCategory = Literal["success", "info", "warning", "error"]
+
+js = SafeStr(
+    '<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1/dist/js/toast.min.js" defer></script>'
+)
+
+
+def toaster(
+    *children: ComponentType,
+    id: str,
+    class_: str | None = None,
+    align: Align | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Toast container.
+
+    Arguments:
+        *children: Initial toasts rendered inside the container.
+        id: The unique identifier of the component.
+        class_: Extra CSS classes for the container.
+        align: Horizontal alignment of the toaster.
+        **kwargs: Extra attributes for the root element.
+    """
+    if align is not None:
+        kwargs["data-align"] = align
+
+    return html.div(*children, class_=join_classes("toaster", class_), id=id, **kwargs)
+
+
+def toast(
+    *children: ComponentType,
+    category: ToastCategory | None = None,
+    class_: str | None = None,
+    duration: int | None = None,
+    **kwargs: PropertyValue,
+) -> ComponentType:
+    """
+    Toast item.
+
+    Arguments:
+        *children: Toast content. Use `toast_content()` for the standard toast layout.
+        category: Semantic category that controls styling.
+        class_: Optional CSS classes for the toast.
+        duration: Timeout in milliseconds. Use `-1` to keep the toast open.
+        **kwargs: Extra attributes for the root element.
+    """
+    if category is not None:
+        kwargs["data-category"] = category
+    if duration is not None:
+        kwargs["data-duration"] = duration
+
+    return html.div(
+        html.div(*children, class_="toast-content"),
+        class_=join_classes("toast", class_),
+        role="alert" if category == "error" else "status",
+        aria_atomic="true",
+        aria_hidden="false",
+        **kwargs,
+    )
+
+
+def toast_content(
+    description: ComponentType,
+    *,
+    title: ComponentType | None = None,
+    icon: ComponentType | None = None,
+    footer: ComponentType | None = None,
+) -> ComponentType:
+    """
+    Standard toast content layout.
+
+    Arguments:
+        description: Toast description.
+        title: Optional toast title.
+        icon: Optional icon.
+        footer: Optional footer element, typically an `html.footer(...)`.
+    """
+    return Fragment(
+        icon,
+        html.section(
+            None if title is None else html.h2(title),
+            html.p(description),
+        ),
+        footer,
+    )

htmui/basecoat/typing.py

@@ -0,0 +1,21 @@
+from typing import Literal, Protocol, TypeAlias
+
+from htmy import PropertyValue
+
+Align: TypeAlias = Literal["start", "center", "end"]
+
+HorizontalSide: TypeAlias = Literal["left", "right"]
+
+Side: TypeAlias = HorizontalSide | Literal["top", "bottom"]
+
+InlineSide: TypeAlias = Literal["inline-start", "inline-end"]
+
+FloatingSide: TypeAlias = Side | InlineSide
+
+
+class IdToProperty(Protocol):
+    """Callable protocol for building a property value from an HTML element ID."""
+
+    def __call__(self, id: str, /) -> PropertyValue:
+        """Returns the property value for the given ID."""
+        ...

htmui/cli.py

@@ -0,0 +1,257 @@
+"""htmui command-line interface."""
+
+import ast
+import shutil
+import sys
+from pathlib import Path
+from typing import Annotated, Literal, TypeAlias
+
+import typer
+
+SOURCE_DIR = Path(__file__).parent / "basecoat"
+UTILITIES = {"cdn", "typing"}
+INIT_STEM = "__init__"
+
+_Action: TypeAlias = Literal["new", "overwrite", "skip", "prompt"]
+
+app = typer.Typer(name="htmui", no_args_is_help=True)
+
+
+@app.command()
+def init(
+    src: Annotated[
+        bool, typer.Option("--src", help="Install under src/<package>/ instead of <package>/.")
+    ] = False,
+    package: Annotated[
+        str, typer.Option("-p", "--package", help="Target package directory name.")
+    ] = "components",
+    components: Annotated[
+        list[str] | None, typer.Option("-c", "--component", help="Component to install (repeatable).")
+    ] = None,
+    force: Annotated[
+        bool, typer.Option("-f", "--force", help="Overwrite existing files without asking.")
+    ] = False,
+    skip_existing: Annotated[
+        bool, typer.Option("--skip-existing", help="Skip existing files without asking.")
+    ] = False,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Show what would be done; write nothing.")
+    ] = False,
+) -> None:
+    """
+    Install basecoat components into the current project.
+
+    Copies the selected components, or the full catalog if none are given, plus
+    their dependencies and shared utilities. Existing `__init__.py` is never
+    overwritten.
+    """
+    if force and skip_existing:
+        typer.echo("Error: --force and --skip-existing are mutually exclusive.", err=True)
+        raise typer.Exit(1)
+
+    catalog = _selectable_catalog()
+    catalog_set = set(catalog)
+
+    requested = list(dict.fromkeys([] if components is None else components))
+    unknown = [c for c in requested if c not in catalog_set]
+    if len(unknown) > 0:
+        typer.echo(f"Error: unknown component(s): {', '.join(unknown)}", err=True)
+        typer.echo(f"Available components: {', '.join(catalog)}", err=True)
+        raise typer.Exit(1)
+
+    base = (Path.cwd() / "src" / package) if src else (Path.cwd() / package)
+    if base.exists() and base.is_file():
+        typer.echo(f"Error: {base} exists and is a file, not a directory.", err=True)
+        raise typer.Exit(1)
+
+    selection = requested if len(requested) > 0 else list(catalog)
+    resolved, added = _resolve(selection, catalog_set)
+    for dep, dependant in added:
+        typer.echo(f"+ {dep} (dependency of {dependant})")
+
+    plans = _plan_install(resolved, base, force=force, skip_existing=skip_existing)
+
+    if dry_run:
+        _print_plan(base, plans)
+        raise typer.Exit(0)
+
+    prompt_count = sum(1 for _s, _d, action in plans if action == "prompt")
+    if prompt_count > 0:
+        if not sys.stdin.isatty():
+            typer.echo(
+                f"Error: {prompt_count} existing file(s) in {base}; pass --force or --skip-existing.",
+                err=True,
+            )
+            raise typer.Exit(1)
+        choice: _Action = (
+            "overwrite"
+            if typer.confirm(f"Overwrite {prompt_count} existing file(s) in {base}?")
+            else "skip"
+        )
+        plans = [(source, dest, choice if action == "prompt" else action) for source, dest, action in plans]
+
+    installed, overwritten, skipped = _write_plans(plans, base)
+    typer.echo(f"installed {installed}, overwritten {overwritten}, skipped {skipped} in {base}")
+
+
+@app.command()
+def version() -> None:
+    """Print the htmui version and per-component versions."""
+    from htmui import __version__ as htmui_version
+
+    typer.echo(f"htmui {htmui_version}")
+    for name, ver, framework, fw_ver in _component_versions():
+        line = f"  {name} {ver}"
+        if len(framework) > 0:
+            line += f"  [{framework} {fw_ver}]" if len(fw_ver) > 0 else f"  [{framework}]"
+        typer.echo(line)
+
+
+def _selectable_catalog() -> list[str]:
+    """Sorted installable component names, excluding `__init__` and utilities."""
+    return sorted(
+        p.stem for p in SOURCE_DIR.glob("*.py") if p.stem != INIT_STEM and p.stem not in UTILITIES
+    )
+
+
+def _sibling_imports(path: Path, catalog: set[str]) -> set[str]:
+    """Relative-import modules from `path` that are in `catalog`."""
+    tree = ast.parse(path.read_text(), filename=str(path))
+    out: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.level == 1 and node.module:
+            out.add(node.module)
+    return out & catalog
+
+
+def _resolve(selection: list[str], catalog: set[str]) -> tuple[list[str], list[tuple[str, str]]]:
+    """
+    `selection` plus transitive relative-import dependencies within `catalog`.
+
+    The second item is `(dependency, dependant)` for each name not already in
+    `selection`.
+    """
+    added_log: list[tuple[str, str]] = []
+    stack = list(selection)
+    seen = set(selection)
+    while stack:
+        cur = stack.pop()
+        for dep in _sibling_imports(SOURCE_DIR / f"{cur}.py", catalog):
+            if dep not in seen:
+                added_log.append((dep, cur))
+                seen.add(dep)
+                stack.append(dep)
+    return sorted(seen), added_log
+
+
+def _plan_install(
+    resolved: list[str],
+    base: Path,
+    *,
+    force: bool,
+    skip_existing: bool,
+) -> list[tuple[Path, Path, _Action]]:
+    """
+    Source, destination, and action for installing `resolved` into `base`.
+
+    Always includes `__init__.py` and the utility modules. An existing
+    `__init__.py` is skipped. Other existing files are overwritten if `force`,
+    skipped if `skip_existing`, otherwise marked `prompt`.
+    """
+    plans: list[tuple[Path, Path, _Action]] = []
+    for name in [INIT_STEM, *sorted(UTILITIES), *resolved]:
+        source = SOURCE_DIR / f"{name}.py"
+        dest = base / f"{name}.py"
+        if dest.exists() and name == INIT_STEM:
+            action: _Action = "skip"
+        elif not dest.exists():
+            action = "new"
+        elif force:
+            action = "overwrite"
+        elif skip_existing:
+            action = "skip"
+        else:
+            action = "prompt"
+        plans.append((source, dest, action))
+    return plans
+
+
+def _action_line(dest: Path, action: _Action) -> str:
+    name = dest.name
+    if action == "skip" and dest.stem == INIT_STEM:
+        return f"  skip      {name}  (existing __init__.py preserved)"
+    if action == "new":
+        return f"  new       {name}"
+    if action == "overwrite":
+        return f"  overwrite {name}"
+    if action == "skip":
+        return f"  skip      {name}"
+    return f"  ask       {name}"
+
+
+def _print_plan(base: Path, plans: list[tuple[Path, Path, _Action]]) -> None:
+    """Print `plans` and a count summary for `base`."""
+    typer.echo(f"Dry-run plan for {base}:")
+    would_install = would_overwrite = would_skip = would_ask = 0
+    for _source, dest, action in plans:
+        typer.echo(_action_line(dest, action))
+        if action == "new":
+            would_install += 1
+        elif action == "overwrite":
+            would_overwrite += 1
+        elif action == "prompt":
+            would_ask += 1
+        else:
+            would_skip += 1
+    typer.echo(
+        f"would install {would_install}, overwrite {would_overwrite}, skip {would_skip}, ask {would_ask}"
+    )
+
+
+def _write_plans(plans: list[tuple[Path, Path, _Action]], base: Path) -> tuple[int, int, int]:
+    """Write `plans` under `base`. Returns `(installed, overwritten, skipped)`."""
+    base.mkdir(parents=True, exist_ok=True)
+    installed = 0
+    overwritten = 0
+    skipped = 0
+    for source, dest, action in plans:
+        if action in ("new", "overwrite"):
+            shutil.copyfile(source, dest)
+            if action == "overwrite":
+                overwritten += 1
+            else:
+                installed += 1
+        else:
+            skipped += 1
+        typer.echo(_action_line(dest, action))
+    return installed, overwritten, skipped
+
+
+def _component_versions() -> list[tuple[str, str, str, str]]:
+    """
+    `(name, version, framework, framework_version)` for each module with `__version__`.
+
+    Missing framework attributes are empty strings.
+    """
+    import importlib.util
+
+    names = sorted(p.stem for p in SOURCE_DIR.glob("*.py") if p.stem != INIT_STEM)
+    rows: list[tuple[str, str, str, str]] = []
+    for name in names:
+        path = SOURCE_DIR / f"{name}.py"
+        spec = importlib.util.spec_from_file_location(f"htmui.basecoat.{name}", path)
+        if spec is None or spec.loader is None:
+            continue
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        ver = getattr(mod, "__version__", None)
+        if ver is None:
+            continue
+        framework = getattr(mod, "__framework__", "")
+        fw_ver = getattr(mod, "__framework_version__", "")
+        rows.append((name, ver, framework, fw_ver))
+    return rows
+
+
+if __name__ == "__main__":
+    app()

htmui-0.1.0.dist-info/METADATA

@@ -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/).