---
title: "Layout Utilities"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Layout Utilities}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Overview

`shiny.webawesome` is primarily a generated wrapper package, but it also
includes a small set of package-level helpers for common layout and page
scaffolding tasks.

The two main layout helpers are:

- `webawesomePage()`, which creates a minimal page scaffold for Shiny apps using the
  package
- `wa_container()`, which creates a plain container element that is convenient
  for layouts and utility-class usage

Neither helper is a generated wrapper for an upstream Web Awesome component.
They are package-level conveniences that make it easier to build Shiny apps
that use Web Awesome components and utilities.

# `webawesomePage()`

`webawesomePage()` creates a minimal full-page HTML scaffold and attaches the
`shiny.webawesome` dependency once at page level.

This is useful because it keeps the page-level setup explicit and avoids
relying on dependency attachment from an individual component deeper in the UI
tree.

```{r layout-utilities-executed}
library(shiny.webawesome)

layout_preview <- wa_container(
  class = "wa-stack",
  wa_card("First card"),
  wa_card("Second card")
)

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

Here is the same idea in a minimal full Shiny page scaffold:

```{r wa-page-basic, eval = FALSE}
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Layout utilities",
  wa_container(
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_card("Hello from Web Awesome")
  )
)

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

shinyApp(ui, server)
```

`webawesomePage()` is especially useful when you want a small, explicit page helper
rather than composing your own `<html>`, `<head>`, and `<body>` scaffolding
manually.

## A slightly richer page

The page helper works naturally with generated components and package-level
layout helpers together:

```{r wa-page-richer, eval = FALSE}
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Page example",
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_card("Top card"),
    wa_button(
      "primary_action",
      "Continue",
      appearance = "filled",
      style = "width: 10rem;"
    ),
    wa_card("Bottom card")
  )
)

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

shinyApp(ui, server)
```

# `wa_container()`

`wa_container()` creates a plain `<div>` container and attaches the package
dependency. It is useful when you want layout structure or Web Awesome
utility-class usage without introducing a generated component wrapper solely to
carry the dependency.

Because it is a normal container helper, it pairs naturally with Web Awesome
layout and utility classes such as `wa-grid`, `wa-stack`, `wa-align-*`, and
`wa-justify-*`, along with small layout groupings and inline style adjustments.

```{r wa-container-basic, eval = FALSE}
library(shiny.webawesome)

wa_container(
  class = "wa-stack",
  wa_card("First card"),
  wa_card("Second card")
)
```

## When to use `wa_container()`

Typical uses include:

- grouping related components in a plain container
- applying Web Awesome layout or alignment utility classes to a shared wrapper
- attaching the package dependency when the UI subtree does not yet contain a
  generated component wrapper of its own

# Examples

## A simple stacked layout

```{r layout-example-stack, eval = FALSE}
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Stacked layout",
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_card("Profile"),
    wa_card("Recent activity"),
    wa_button(
      "refresh",
      "Refresh",
      appearance = "outlined",
      style = "width: 10rem;"
    )
  )
)

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

shinyApp(ui, server)
```

## A mixed page with layout helper boundaries

```{r layout-example-mixed, eval = FALSE}
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Mixed layout",
  wa_container(
    class = "wa-cluster",
    wa_badge("Beta"),
    wa_tag("Preview")
  ),
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_card("Main content"),
    wa_card("Secondary content")
  )
)

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

shinyApp(ui, server)
```

# Notes

Use `webawesomePage()` when you want the package to own the full page scaffold.

Use `wa_container()` when you need a plain layout wrapper inside a page or UI
subtree.

For introductory context, start with the Getting Started with
shiny.webawesome guide.
