# Extra Attributes via htmltools

# Overview

One of Web Awesome’s strengths is that its components behave like standard HTML elements.

That matters in `shiny.webawesome` too. Even though the package provides R wrappers for Web Awesome components, the rendered output is still HTML. In practice, that means the components can still participate in normal HTML attribute patterns.

Examples of standard attributes you may still want to apply include:

- `title`
- `role`
- `tabindex`
- `aria-label`
- `aria-describedby`
- `lang`
- `data-*` attributes for app- or browser-side hooks

# Why the wrappers do not expose every HTML attribute

The generated wrappers intentionally keep their argument surface focused.

For all components, the wrappers expose the most broadly useful HTML-level attributes directly:

- `class`
- `style`

This keeps the package API smaller and easier to understand. If every wrapper also exposed the full standard HTML attribute surface, the generated API would grow substantially without adding much package-specific value.

The design goal is:

- expose the Web Awesome component API clearly
- expose the most useful common HTML hooks directly
- avoid wrapper-argument bloat for attributes that already belong to normal HTML authoring

# Adding extra attributes

When you need standard HTML attributes beyond `class` and `style`, append them with `htmltools`.

This works because the generated wrappers return normal HTML tag objects.

## Example: accessibility and tooltip attributes

    library(htmltools)
    library(shiny.webawesome)

    button_with_attrs <- tagAppendAttributes(
      wa_button("save_button", "Save"),
      `aria-label` = "Save current form",
      title = "Save"
    )

    cat(as.character(button_with_attrs), sep = "\n")

    ## <wa-button id="save_button" aria-label="Save current form" title="Save">Save</wa-button>

Here is the same attribute pattern in a minimal Shiny app:

    library(htmltools)
    library(shiny)
    library(shiny.webawesome)

    ui <- webawesomePage(
      title = "Extra attributes",
      tagAppendAttributes(
        wa_button("save_button", "Save"),
        `aria-label` = "Save current form",
        title = "Save"
      )
    )

    server <- function(input, output, session) {}

    shinyApp(ui, server)

Here, `wa_button()` stays focused on the component API while `htmltools` provides the extra HTML attributes.

## Example: role, tabindex, and custom data attributes

    library(htmltools)
    library(shiny)
    library(shiny.webawesome)

    ui <- webawesomePage(
      title = "More attributes",
      tagAppendAttributes(
        wa_card("Keyboard focus example"),
        role = "region",
        tabindex = "0",
        `data-section` = "summary"
      )
    )

    server <- function(input, output, session) {}

    shinyApp(ui, server)

This is especially useful when:

- you need accessibility attributes
- you need browser-side hooks for app-local JavaScript
- you need standard HTML semantics that are not worth surfacing as dedicated wrapper arguments

# When to use this pattern

Prefer direct wrapper arguments when the package already exposes the attribute or component field intentionally.

Prefer `tagAppendAttributes()` when:

- the attribute is part of normal HTML rather than a Web Awesome-specific API
- the attribute is app-specific rather than package-wide
- adding a dedicated wrapper argument would add API noise without improving the common case

# Relationship to other package surfaces

This pattern is separate from:

- generated Shiny bindings
- generated update helpers
- the command-layer helpers such as `wa_set_property()` and `wa_call_method()`

Use `htmltools` attribute appending when you are shaping static rendered HTML. Use the command layer when you need live browser-side interaction after the UI has already been rendered.