# Getting Started with shiny.webawesome

## Overview

`shiny.webawesome` provides an R and Shiny interface to the Web Awesome
component library.

Most component wrappers are generated from the upstream Web Awesome
metadata file `custom-elements.json`. The package aims to stay close to
upstream Web Awesome names and component APIs while adopting normal R
conventions such as snake_case argument names. The package also bundles
the Web Awesome runtime it needs, so you do not need to install Web
Awesome assets separately in your app. To report the bundled Web Awesome
version in your current installation, use
[`wa_version()`](https://www.shiny-webawesome.org/reference/wa_version.md).

Because Web Awesome lives in the browser and Shiny spans both server and
client, the package includes more than generated wrappers alone. In
practice, there are four core areas to know:

- basic wrapper usage
- Shiny bindings
- the command API
- package options

This guide introduces each one briefly and points to the longer-form
documentation for deeper coverage.

``` r
library(shiny.webawesome)

wa_version()
```

    #> [1] "3.5.0"

``` r
button <- shiny.webawesome::wa_button("preview_button", "Preview")
cat(as.character(button), sep = "\n")
```

    #> <wa-button id="preview_button">Preview</wa-button>

## Basic Wrapper Usage

At the simplest level, you use generated wrappers as ordinary Shiny UI
functions. Wrapper names follow the Web Awesome component names with the
`wa_` prefix, and kebab-case attributes become snake_case arguments.

There are two common ways to do that in an app:

- use individual Web Awesome components inside an ordinary Shiny page
  helper such as
  [`fluidPage()`](https://rdrr.io/pkg/shiny/man/fluidPage.html)
- use
  [`webawesomePage()`](https://www.shiny-webawesome.org/reference/webawesomePage.md)
  when Web Awesome is the main page environment

If you are adding a few Web Awesome components to an otherwise ordinary
Shiny app, using them inside
[`fluidPage()`](https://rdrr.io/pkg/shiny/man/fluidPage.html) is
supported and the package will attach its runtime dependency
automatically.

``` r
library(shiny)
library(shiny.webawesome)

ui <- fluidPage(
  h2("Mixed Shiny page"),
  wa_card(
    header = "Status",
    wa_badge("Beta", appearance = "filled"),
    "This card is rendered inside fluidPage()."
  )
)

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

shinyApp(ui, server)
```

That mixed approach is useful when you want to adopt Web Awesome
gradually or only need a small number of components in an existing
Bootstrap-based app. The components will work, but you should still
check the rendered page for spacing, typography, color, or theme/style
mismatches between the surrounding Bootstrap layout and the Web Awesome
components.

If Web Awesome is the main UI system for the app, prefer
[`webawesomePage()`](https://www.shiny-webawesome.org/reference/webawesomePage.md).
It builds a minimal full-page scaffold and attaches the package
dependency once at page level.

``` r
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Basic wrappers",
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_button(
      "save_button",
      "Save",
      appearance = "filled",
      style = "width: 10rem;"
    ),
    wa_card("A simple card body")
  )
)

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

shinyApp(ui, server)
```

Two package-level helpers appear here:

- [`webawesomePage()`](https://www.shiny-webawesome.org/reference/webawesomePage.md)
  creates a minimal full-page scaffold and attaches the package
  dependency once at page level
- [`wa_container()`](https://www.shiny-webawesome.org/reference/wa_container.md)
  creates a plain container element that is convenient for layout
  patterns and utility-class usage

For fuller layout examples, see the `Layout Utilities` article.

## Shiny Bindings

Some components expose generated Shiny bindings. These bindings are
curated to fit Shiny’s reactive model rather than mirroring every
browser event emitted by the underlying Web Component.

For example,
[`wa_select()`](https://www.shiny-webawesome.org/reference/wa_select.md)
can participate directly in ordinary Shiny input flows:

``` r
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Bindings",
  wa_select(
    "favorite_letter",
    wa_option("A", value = "a"),
    wa_option("B", value = "b"),
    wa_option("C", value = "c")
  ),
  verbatimTextOutput("selected_value")
)

server <- function(input, output, session) {
  output$selected_value <- renderPrint({
    input$favorite_letter
  })
}

shinyApp(ui, server)
```

The details of binding categories and reactive semantics are covered in
the `Shiny Bindings` article.

## Command API

Generated bindings and update helpers cover the most common
component-side interactions, but sometimes a browser-side property or
method still needs to be driven explicitly from the server.

For those cases, the package provides a narrow command/helper layer.

``` r
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Command API",
  actionButton("open_dialog", "Open dialog"),
  wa_dialog(
    "dialog",
    "Dialog body"
  )
)

server <- function(input, output, session) {
  observeEvent(input$open_dialog, {
    wa_call_method("dialog", "show", session = session)
  })
}

shinyApp(ui, server)
```

When you need app-local browser glue that is easier to express in
JavaScript,
[`wa_js()`](https://www.shiny-webawesome.org/reference/wa_js.md) lets
you inject a small inline snippet and pair it with ordinary Shiny inputs
via `Shiny.setInputValue()`.

For more detailed guidance for choosing between generated bindings,
update helpers, command helpers, and
[`wa_js()`](https://www.shiny-webawesome.org/reference/wa_js.md), please
see the `Command API` article.

## Package Options

The package currently documents its warning and diagnostic controls
through the package option `shiny.webawesome.warnings`, which should be
a named list.

Known keys currently include:

- `missing_tree_item_id`
- `command_layer`
- `command_layer_debug`

For example, you can enable additional command-layer diagnostics during
development with:

``` r
options(
  shiny.webawesome.warnings = list(
    command_layer_debug = TRUE
  )
)
```

These options are described in more detail in the `Package Options`
article and summarized in the package help page
[`?shiny.webawesome`](https://www.shiny-webawesome.org/reference/shiny.webawesome-package.md).

## Next Steps

After this guide, the most relevant longer-form docs are:

- Layout Utilities
- Styling and Theming
- Shiny Bindings
- Command API
- Package Options
- Examples