feat(components): enhance documentation for various components with detailed argument descriptions and return types

Author: dakixr

src/htpy_uikit/components/_utils.py

@@ -3,11 +3,28 @@
 
 
 def merge_classes(base_classes: str, class_: str | None = None) -> str:
-    """Merge base classes with optional additional classes."""
+    """Merge ``base_classes`` with optional ``class_`` string.
+
+    Args:
+        base_classes: Default Tailwind utility classes.
+        class_: Optional user-supplied classes appended to the base.
+
+    Returns:
+        str: Combined class string without extra whitespace.
+    """
     if class_:
         return f"{base_classes} {class_}"
     return base_classes
 
 
 def random_string(n: int) -> str:
+    """Return a pseudo-random alpha string of length ``n``.
+
+    Args:
+        n: Desired number of characters.
+
+    Returns:
+        str: Random uppercase/lowercase ASCII letters combined via ``random.choices``.
+    """
+
     return "".join(random.choices(string.ascii_letters, k=n))

src/htpy_uikit/components/accordion.py

@@ -19,21 +19,16 @@ def accordion(
     class_: str | None = None,
     **attrs,
 ) -> Renderable:
-    """
-    Basecoat-style accordion component.
-
-    Based on Basecoat UI accordion implementation.
-    Note: Basecoat doesn't have a dedicated accordion component,
-    this uses standard HTML details/summary elements with accordion styling.
+    """Render a Basecoat-style accordion using native ``<details>`` elements.
 
     Args:
-        items: List of AccordionItem dictionaries with title, content, and expanded flag
-        default_value: Title of item to expand by default
-        class_: Additional CSS classes
-        **attrs: Additional HTML attributes
+        items: Sequence of accordion item definitions containing ``title`` and ``content``.
+        default_value: Title whose panel should be expanded initially.
+        class_: Additional CSS classes appended to the wrapping section.
+        **attrs: Extra HTML attributes forwarded to the section element.
 
     Returns:
-        htpy.section: Accordion component
+        Renderable: Section element containing the accordion items.
     """
 
     # Add class to attrs
@@ -105,14 +100,32 @@ def accordion(
 def accordion_single(
     title: str, content: Node | str, expanded: bool = False, **kwargs
 ) -> Renderable:
-    """Single item accordion."""
+    """Render a one-item accordion helper.
+
+    Args:
+        title: Accordion heading.
+        content: Body content node or string.
+        expanded: Whether the single item starts open.
+        **kwargs: Additional keyword arguments forwarded to ``accordion``.
+
+    Returns:
+        Renderable: Section element wrapping the single accordion entry.
+    """
     items: list[AccordionItem] = [{"title": title, "content": content, "expanded": expanded}]
     return accordion(items, default_value=title if expanded else None, **kwargs)
 
 
 # Convenience function for FAQ accordion
 def accordion_faq(questions_answers: list[tuple[str, str]], **kwargs) -> Renderable:
-    """FAQ accordion with questions and answers."""
+    """Render an FAQ-style accordion.
+
+    Args:
+        questions_answers: Sequence of (question, answer) tuples.
+        **kwargs: Additional keyword arguments forwarded to ``accordion``.
+
+    Returns:
+        Renderable: Section element containing an accordion with FAQ entries.
+    """
     items: list[AccordionItem] = [
         {"title": question, "content": p[answer], "expanded": False}
         for question, answer in questions_answers

src/htpy_uikit/components/alert.py

@@ -20,14 +20,19 @@ def alert(
     target_id: str | None = None,
     class_: str | None = None,
 ) -> Renderable:
-    """Basecoat-style alert with intent-based variants.
+    """Render a Basecoat-style alert with optional icon and description.
 
-    Structure matches the reference:
-      <div class="alert[ -destructive]">
-        <svg/> (optional)
-        <h2/>
-        <section/> (optional)
-      </div>
+    Args:
+        title: Primary alert text.
+        description: Optional supporting description.
+        variant: Visual variant; controls tone and icon (e.g., ``\"destructive\"``).
+        show_icon: Whether to render a contextual icon.
+        icon: Override icon renderable (takes precedence over ``variant`` default).
+        target_id: Optional id and HTMX swap target when replacing alerts dynamically.
+        class_: Additional CSS classes appended to the alert container.
+
+    Returns:
+        Renderable: ``<div role=\"alert\">`` tree that matches Basecoat styling.
     """
 
     # Inline Basecoat alert classes so the component is self-contained.

src/htpy_uikit/components/alert_dialog.py

@@ -22,6 +22,7 @@
 
 
 class AlertDialogTriggerAttrs(TypedDict):
+    """Attributes applied to buttons that toggle the native dialog."""
     type: Literal["button"]
     onclick: str
 
@@ -182,11 +183,20 @@ def alert_dialog_destructive(
     trigger_btn_variant: ButtonVariant = "outline",
     **kwargs,
 ) -> Node:
-    """Render a destructive alert dialog; optionally include an external trigger.
+    """Render a destructive alert dialog and optional trigger button.
 
-    If `with_trigger` is True this will also render a trigger button next to
-    the dialog. An `id` will be generated if not provided in kwargs so the
-    trigger can reference the dialog.
+    Args:
+        children: Dialog body content.
+        title: Dialog title.
+        description: Optional description text.
+        with_trigger: Whether to render an accompanying trigger button.
+        trigger_label: Label for the trigger button.
+        trigger_attrs: Extra attributes applied to the trigger button.
+        trigger_btn_variant: Variant passed to ``button_component`` for the trigger.
+        **kwargs: Additional keyword arguments forwarded to ``alert_dialog``.
+
+    Returns:
+        Node: Dialog renderable, optionally paired with a trigger button.
     """
     # ensure an id is present so trigger can open the dialog
     dialog_id = kwargs.get("id") or f"alert-dialog-{random_string(6)}"
@@ -223,7 +233,22 @@ def confirm_dialog(
     trigger_btn_variant: ButtonVariant = "outline",
     **kwargs,
 ) -> Node:
-    """Simple confirmation dialog; optionally render an external trigger."""
+    """Render a confirmation dialog with optional trigger button.
+
+    Args:
+        message: Dialog body text.
+        title: Dialog title.
+        confirm_text: Label for the confirm action button.
+        cancel_text: Label for the cancel button.
+        with_trigger: Whether to render an accompanying trigger button.
+        trigger_label: Label for the trigger button.
+        trigger_attrs: Extra attributes applied to the trigger button.
+        trigger_btn_variant: Button variant for the trigger.
+        **kwargs: Additional keyword arguments forwarded to ``alert_dialog``.
+
+    Returns:
+        Node: Dialog renderable (and trigger button when requested).
+    """
     dialog_id = kwargs.get("id") or f"alert-dialog-{random_string(6)}"
     kwargs["id"] = dialog_id
 

src/htpy_uikit/components/avatar.py

@@ -23,22 +23,17 @@ def avatar(
     class_: str | None = None,
     **attrs,
 ) -> Renderable:
-    """
-    Basecoat-style avatar component.
-
-    Based on Basecoat UI avatar implementation.
-    Note: Basecoat doesn't have a dedicated avatar component,
-    this uses standard img elements with avatar styling.
+    """Render an image avatar with Basecoat sizing tokens.
 
     Args:
-        src: Image source URL
-        alt: Image alt text
-        size: Avatar size
-        class_: Additional CSS classes
-        **attrs: Additional HTML attributes
+        src: Image source URL.
+        alt: Alt text describing the avatar.
+        size: Size token mapping to Tailwind ``size-*`` classes.
+        class_: Extra CSS classes appended to the ``img`` element.
+        **attrs: Additional HTML attributes forwarded to the ``img`` tag.
 
     Returns:
-        htpy.img: Avatar image element
+        Renderable: Configured ``<img>`` node.
     """
 
     # Base classes - following basecoat avatar styling
@@ -63,13 +58,16 @@ def avatar(
 def avatar_text(
     initials: str, *, size: AvatarSize = "md", class_: str | None = None, **attrs
 ) -> Renderable:
-    """Render an initials avatar (fallback) as a centered rounded span.
+    """Render an initials avatar fallback as a rounded ``<span>``.
 
     Args:
-        initials: Text to show inside the avatar (e.g. "CN")
-        size: Avatar size key (xs, sm, md, lg, xl)
-        class_: Extra classes to append
-        **attrs: Additional attributes for the span
+        initials: Text or initials displayed inside the avatar.
+        size: Size token controlling the diameter.
+        class_: Extra CSS classes appended to the span.
+        **attrs: Additional HTML attributes forwarded to the span.
+
+    Returns:
+        Renderable: Styled ``<span>`` element with initials.
     """
 
     base = f"{_size_classes[size]} shrink-0 bg-muted flex items-center justify-center rounded-full text-sm font-medium"
@@ -90,9 +88,18 @@ def avatar_group(
     hover_expand: bool = False,
     class_: str | None = None,
 ) -> Renderable:
-    """Render a stacked avatar group.
+    """Render overlapping avatar images with optional rings and hover expansion.
 
-    images may be list of src strings or AvatarImage dictionaries with src and alt.
+    Args:
+        images: List of avatar URLs or ``AvatarImage`` dicts with ``src``/``alt``.
+        size: Size token applied to each child avatar.
+        ring: Whether to render rings (via ``ring-2``) around each avatar.
+        grayscale: Whether to desaturate avatars.
+        hover_expand: Whether to animate spacing on hover.
+        class_: Extra CSS classes appended to the container ``div``.
+
+    Returns:
+        Renderable: Stacked avatar ``<div>`` containing ``<img>`` children.
     """
     selectors = []
     # ring styles applied to child imgs