### Install and Check Surveydown Package

Source: https://github.com/surveydown-dev/surveydown/blob/main/CLAUDE.md

Use devtools::install(force = TRUE) to install the package locally and devtools::check() to run R CMD check for package integrity.

```r
# Install package locally
devtools::install(force = TRUE)

# Run R CMD check
devtools::check()
```

--------------------------------

### Install Surveydown Package Locally

Source: https://github.com/surveydown-dev/surveydown/blob/main/CLAUDE.md

After making improvements to the surveydown package, install it locally with force=TRUE to ensure all changes are applied.

```r
devtools::install(force = TRUE)
```

--------------------------------

### Install surveydown Development Version

Source: https://github.com/surveydown-dev/surveydown/blob/main/README.md

Install the latest development version of the surveydown package from GitHub using the 'pak' package manager.

```r
# install.packages("pak")
pak::pak('surveydown-dev/surveydown')
```

--------------------------------

### Install surveydown from CRAN

Source: https://github.com/surveydown-dev/surveydown/blob/main/README.md

Use this command to install the stable version of the surveydown package from CRAN.

```r
install.packages("surveydown")
```

--------------------------------

### Check surveydown Version

Source: https://github.com/surveydown-dev/surveydown/blob/main/README.md

Check the currently installed version of the surveydown package.

```r
surveydown::sd_version()
```

--------------------------------

### Build pkgdown Site for Surveydown

Source: https://github.com/surveydown-dev/surveydown/blob/main/CLAUDE.md

Use pkgdown::build_site() to build the package's documentation website.

```r
# Build pkgdown site
pkgdown::build_site()
```

--------------------------------

### Configure PostgreSQL database connection settings

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

sd_db_config() sets up a local .env file for PostgreSQL credentials and adds it to .gitignore. It can be used interactively or programmatically to set host, port, database name, user, password, and table name.

```r
# Interactive setup (prompts for host, port, dbname, user, password, table)
sd_db_config()
```

```r
# Programmatic setup
sd_db_config(
  host     = "aws-0-us-west-1.pooler.supabase.com",
  port     = "6543",
  dbname   = "postgres",
  user     = "postgres.abcdefghij",
  table    = "survey_responses",
  password = "mysecretpassword"
)
```

```r
# Update only the table name
sd_db_config(table = "new_table_name")
```

--------------------------------

### sd_ui() — Build the survey UI

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Creates the Shiny UI for a surveydown survey. Must be called from `app.R`. Reads theme, progress bar, and footer settings from the `survey.qmd` YAML header, renders the Quarto document on first run (or when changes are detected), and assembles the full page layout.

```APIDOC
## sd_ui()

### Description
Creates the Shiny UI for a surveydown survey. Must be called from `app.R`. Reads theme, progress bar, and footer settings from the `survey.qmd` YAML header, renders the Quarto document on first run (or when changes are detected), and assembles the full page layout.

### Usage
```r
# app.R
library(surveydown)

db <- sd_db_connect(ignore = TRUE)  # Connect to database (or use local mode)

ui <- sd_ui()  # Reads survey.qmd, renders it, builds Shiny UI

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

shiny::shinyApp(ui = ui, server = server)
```

### Returns
A Shiny UI object representing the survey interface.
```

--------------------------------

### Create page navigation buttons with sd_nav

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Renders Previous and/or Next navigation buttons. Can specify target pages, customize labels, and control button visibility. Auto-navigation is enabled if sd_nav() is not explicitly called.

```r
# Default: both buttons, reads show-previous from YAML
sd_nav()
```

```r
# First page: hide Previous button
sd_nav(show_previous = FALSE)
```

```r
# Custom next destination and labels
sd_nav(
  page_next      = "demographics",
  label_previous = "Go Back",
  label_next     = "Continue →"
)
```

```r
# Hide Next button (page requires sd_close or another mechanism)
sd_nav(show_next = FALSE)
```

--------------------------------

### Connect to PostgreSQL database

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

sd_db_connect() establishes a connection pool to a PostgreSQL database using credentials from a .env file. Set ignore = TRUE for local CSV preview. Options like gssencmode can be specified.

```r
# Connect using .env credentials
db <- sd_db_connect()
```

```r
# Local preview mode (no database required)
db <- sd_db_connect(ignore = TRUE)
```

```r
# Disable GSSAPI encryption (needed on some VPNs or secure networks)
db <- sd_db_connect(gssencmode = "disable")
```

```r
# Use in app.R
library(surveydown)
db <- sd_db_connect()   # reads .env automatically

ui <- sd_ui()
server <- function(input, output, session) {
  sd_server(db = db)
}
shiny::shinyApp(ui = ui, server = server)
```

--------------------------------

### Get Citation for surveydown Package

Source: https://github.com/surveydown-dev/surveydown/blob/main/README.md

Use this R function to retrieve the citation details for the surveydown package, including a BibTeX entry for LaTeX users. This is important for academic publications.

```r
citation("surveydown")
#> To cite surveydown in publications use:
#>
#>
#>   Hu P, Bunea B, Helveston J (2025). "surveydown: An open-source,
#>   markdown-based platform for programmable and reproducible surveys."
#>   _PLOS One_, *20*(8). doi:10.1371/journal.pone.0331002
#>   <https://doi.org/10.1371/journal.pone.0331002>.
#>
#> A BibTeX entry for LaTeX users is
#>
#>   @Article{
#>     title = {surveydown: An open-source, markdown-based platform for programmable and reproducible surveys},
#>     author = {Pingfan Hu and Bogdan Bunea and John Paul Helveston},
#>     journal = {PLOS One},
#>     year = {2025},
#>     volume = {20},
#>     number = {8},
#>     doi = {10.1371/journal.pone.0331002},
#>   }
```
```

--------------------------------

### Create Survey with Default Template

Source: https://github.com/surveydown-dev/surveydown/blob/main/inst/template/README.md

Use this command to create a new survey project. The default template is used if no specific template is provided.

```r
surveydown::sd_create_survey(
  #path = "path/to/survey"
)
```

--------------------------------

### Create a new surveydown survey from a template

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Use `sd_create_survey` to scaffold a new project. Specify a template name and a path for the new survey directory. Set `ask = FALSE` to prevent interactive prompts.

```r
library(surveydown)

# Create a default survey in a new folder
sd_create_survey(template = "default", path = "my_survey", ask = FALSE)

# Create a survey showcasing all question types
sd_create_survey(template = "question_types", path = "question_demo", ask = FALSE)
```

--------------------------------

### Load and Document Surveydown Package

Source: https://github.com/surveydown-dev/surveydown/blob/main/CLAUDE.md

During development, use devtools::load_all() to load the package and devtools::document() to generate documentation from roxygen comments.

```r
# Load package during development
devtools::load_all()

# Generate documentation from roxygen comments
devtools::document()
```

--------------------------------

### Run survey server logic with sd_server()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

The `sd_server()` function handles core survey logic including question tracking, navigation, conditional logic, and data persistence. It must be the last function called in the `server` function of `app.R`. Conditional logic functions like `sd_show_if` and `sd_skip_if` must precede `sd_server()`.

```r
# app.R — full working example
library(surveydown)

db <- sd_db_connect(ignore = TRUE)

ui <- sd_ui()

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

  # Conditional logic (must come before sd_server)
  sd_show_if(
    input$has_pet == "yes" ~ "pet_breed"
  )

  sd_skip_if(
    input$consent == "no" ~ "end"
  )

  # All behavior configured via survey.qmd YAML; sd_server() reads it automatically
  sd_server(db = db)
}

shiny::shinyApp(ui = ui, server = server)
```

--------------------------------

### Conditionally show questions or pages with sd_show_if

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Defines reactive display conditions for questions or pages. Elements are hidden by default until conditions are met. Must be called before sd_server().

```r
# In app.R server function:
server <- function(input, output, session) {

  sd_show_if(
    input$has_car    == "yes"  ~ "car_make",      # show question
    input$employed   == "yes"  ~ "job_title",      # show question
    input$age        >= 18     ~ "adult_page"       # show entire page
  )

  sd_server(db = db)
}
```

--------------------------------

### Store options as provided in sd_question()

Source: https://github.com/surveydown-dev/surveydown/blob/main/NEWS.md

The short-hand format for options in `sd_question()`, like `c("Label 1", "Label 2")`, is now stored verbatim for compatibility with special characters.

```R
sd_question(..., option = c("Label 1", "Label 2"))
```

--------------------------------

### sd_server() — Run the survey server logic

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

The core server function that wires up all survey behavior: question tracking, progress bar updates, page navigation, conditional display/skip/stop logic, session/cookie management, database writes, required question enforcement, option shuffling, and exit/rating functionality. Must be the last function call inside the `server` function.

```APIDOC
## sd_server()

### Description
The core server function that wires up all survey behavior: question tracking, progress bar updates, page navigation, conditional display/skip/stop logic, session/cookie management, database writes, required question enforcement, option shuffling, and exit/rating functionality. Must be the **last function call** inside the `server` function. Exposes the `all_data` reactive values list to the parent environment for use in conditional logic.

### Usage
```r
# app.R — full working example
library(surveydown)

db <- sd_db_connect(ignore = TRUE)

ui <- sd_ui()

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

  # Conditional logic (must come before sd_server)
  sd_show_if(
    input$has_pet == "yes" ~ "pet_breed"
  )

  sd_skip_if(
    input$consent == "no" ~ "end"
  )

  # All behavior configured via survey.qmd YAML; sd_server() reads it automatically
  sd_server(db = db)
}

shiny::shinyApp(ui = ui, server = server)
```

### Parameters
- **db** - A database connection object or NULL for local mode.
```

--------------------------------

### sd_db_connect()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Connects to the PostgreSQL database using credentials from the .env file. It can also be used in a preview mode to save responses to a CSV file instead of connecting to a database.

```APIDOC
## sd_db_connect()

### Description
Connects to the database using credentials from the `.env` file (created by `sd_db_config()`) and creates a connection pool. Returns `NULL` in `ignore = TRUE` mode, saving responses to a local `preview_data.csv` instead.

### Method
`sd_db_connect(ignore = FALSE, gssencmode = "prefer")`

### Parameters
- **ignore** (boolean) - If `TRUE`, saves responses to `preview_data.csv` instead of connecting to the database.
- **gssencmode** (string) - GSSAPI encryption mode. Set to `"disable"` if needed on some VPNs or secure networks.

### Request Example
```r
# Connect using .env credentials
db <- sd_db_connect()

# Local preview mode (no database required)
db <- sd_db_connect(ignore = TRUE)

# Disable GSSAPI encryption
db <- sd_db_connect(gssencmode = "disable")

# Use in app.R
library(surveydown)
db <- sd_db_connect()   # reads .env automatically

ui <- sd_ui()
server <- function(input, output, session) {
  sd_server(db = db)
}
shiny::shinyApp(ui = ui, server = server)
```
```

--------------------------------

### sd_create_survey() — Create a new survey from a template

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Scaffolds a new surveydown project by copying template files (`survey.qmd` and `app.R`) into a directory. Supports the built-in default template or any of 16 specialized templates.

```APIDOC
## sd_create_survey()

### Description
Scaffolds a new surveydown project by copying template files (`survey.qmd` and `app.R`) into a directory. Supports the built-in default template or any of 16 specialized templates (conjoint, reactive questions, leaflet maps, live polling, etc.) downloaded automatically from GitHub.

### Usage
```r
library(surveydown)

# Create a default survey in a new folder
sd_create_survey(template = "default", path = "my_survey", ask = FALSE)

# Create a survey showcasing all question types
sd_create_survey(template = "question_types", path = "question_demo", ask = FALSE)
```

### Parameters
- **template** (string) - The name of the template to use. Defaults to "default".
- **path** (string) - The directory path where the new survey project will be created.
- **ask** (boolean) - Whether to prompt the user for confirmation. Defaults to TRUE.
```

--------------------------------

### sd_output()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Renders reactive questions, stored values, option labels, or question labels inline in survey.qmd. The `type` argument controls what is rendered.

```APIDOC
## sd_output()

### Description
Renders reactive questions, stored values, option labels, or question labels inline in `survey.qmd`. The `type` argument controls what is rendered:
- `"question"` — a reactive question created in the server
- `"value"` — the raw stored value of a question or `sd_store_value()` field
- `"label_option"` — the display label of the selected option
- `"label_question"` — the label text of the question
- `NULL` — acts as `shiny::uiOutput()`

### Usage
```r
# In survey.qmd R chunks:
library(surveydown)

# Display a reactive question defined in app.R server
sd_output("dynamic_question", type = "question")

# Show a stored completion code inline (in text)
# "Your code is: `r sd_output('completion_code', type = 'value')`"

# Show the selected option label (e.g., "Adélie" not "adelie")
sd_output("fav_penguin", type = "label_option")

# Show the question text itself
sd_output("fav_penguin", type = "label_question")

# Generic uiOutput for custom UI elements
sd_output("my_custom_ui")
```
```

--------------------------------

### Build the survey UI with sd_ui()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

The `sd_ui()` function generates the Shiny UI for a surveydown survey. It must be called within `app.R` and reads theme, progress bar, and footer settings from the `survey.qmd` YAML header.

```r
# app.R
library(surveydown)

db <- sd_db_connect(ignore = TRUE)  # Connect to database (or use local mode)

ui <- sd_ui()  # Reads survey.qmd, renders it, builds Shiny UI

server <- function(input, output, session) {
  sd_server(db = db)
}
```

--------------------------------

### Create redirect button or link with sd_redirect

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Generates a button or text link that redirects the user to a URL. Supports auto-redirect with a countdown timer and opening in a new tab. Can be used in static or reactive contexts.

```r
# In survey.qmd (static redirect):
sd_redirect(
  id     = "prolific_redirect",
  url    = "https://app.prolific.com/submissions/complete?cc=XXXX",
  label  = "Return to Prolific",
  button = TRUE,
  newtab = FALSE
)
```

```r
# With countdown auto-redirect (5 seconds)
sd_redirect(
  id     = "auto_redirect",
  url    = "https://example.com/thank-you",
  label  = "Redirecting...",
  delay  = 5,
  newtab = FALSE
)
```

```r
# In app.R (reactive redirect based on condition):
server <- function(input, output, session) {
  params <- sd_get_url_pars()
  sd_redirect(
    id  = "custom_url",
    url = paste0("https://example.com?id=", params[["user_id"]])
  )
  sd_server(db = db)
}
```

--------------------------------

### sd_db_config()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Configures database connection settings by writing or updating a local .env file. It can be used interactively or programmatically to set host, port, database name, user, password, and table name.

```APIDOC
## sd_db_config()

### Description
Configures database connection settings by writing or updating a local `.env` file. It can be used interactively (prompts for each setting) or programmatically.

### Method
`sd_db_config()`

### Parameters
#### Interactive
`sd_db_config()`

#### Programmatic
`sd_db_config(host, port, dbname, user, table, password)`

- **host** (string) - Database host address.
- **port** (string) - Database port number.
- **dbname** (string) - Database name.
- **user** (string) - Database username.
- **table** (string) - Name of the survey response table.
- **password** (string) - Database password.

### Request Example
```r
# Interactive setup
sd_db_config()

# Programmatic setup
sd_db_config(
  host     = "aws-0-us-west-1.pooler.supabase.com",
  port     = "6543",
  dbname   = "postgres",
  user     = "postgres.abcdefghij",
  table    = "survey_responses",
  password = "mysecretpassword"
)

# Update only the table name
sd_db_config(table = "new_table_name")
```
```

--------------------------------

### Create survey questions with sd_question()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Use `sd_question()` in `survey.qmd` R chunks to define survey questions. Supports 13 question types and can be rendered dynamically in Shiny using `sd_output()`.

```r
# In survey.qmd R chunks:

# Multiple choice (single selection)
sd_question(
  type   = "mc",
  id     = "fav_penguin",
  label  = "What is your favorite penguin?",
  option = c("Adélie" = "adelie", "Chinstrap" = "chinstrap", "Gentoo" = "gentoo")
)
```

```r
# Multiple choice with buttons (multiple selections)
sd_question(
  type   = "mc_multiple_buttons",
  id     = "hobbies",
  label  = "Select all your hobbies:",
  option = c("Reading" = "reading", "Hiking" = "hiking", "Coding" = "coding")
)
```

```r
# Numeric slider with range
sd_question(
  type    = "slider_numeric",
  id      = "age_range",
  label   = "Select your age range:",
  option  = seq(18, 80, 1),
  default = c(25, 45)   # range slider: two default values
)
```

```r
# Matrix question
sd_question(
  type   = "matrix",
  id     = "satisfaction",
  label  = "Rate each aspect:",
  option = c("Poor" = "1", "Fair" = "2", "Good" = "3", "Excellent" = "4"),
  row    = c("Service" = "service", "Quality" = "quality", "Price" = "price")
)
```

```r
# Date range
sd_question(
  type  = "daterange",
  id    = "trip_dates",
  label = "When did you travel?"
)
```

--------------------------------

### Configure indexed option/subquestion shuffling

Source: https://github.com/surveydown-dev/surveydown/blob/main/NEWS.md

Use indexing syntax within the `question_id` YAML key to specify ranges or lists of options/subquestions for shuffling.

```yaml
question_id: 1-5
```

```yaml
question_id: [1, 2, 4, 7]
```

```yaml
question_id: [1-5, 8-10]
```

--------------------------------

### sd_question() — Create a survey question

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

The primary function for adding questions to `survey.qmd`. Supports 13 question types. When called inside the Shiny server (reactive context), the question is rendered dynamically and displayed via `sd_output()`.

```APIDOC
## sd_question()

### Description
The primary function for adding questions to `survey.qmd`. Supports 13 question types. When called inside the Shiny server (reactive context), the question is rendered dynamically and displayed via `sd_output()`.

### Usage
```r
# In survey.qmd R chunks:

# Multiple choice (single selection)
sd_question(
  type   = "mc",
  id     = "fav_penguin",
  label  = "What is your favorite penguin?",
  option = c("Adélie" = "adelie", "Chinstrap" = "chinstrap", "Gentoo" = "gentoo")
)

# Multiple choice with buttons (multiple selections)
sd_question(
  type   = "mc_multiple_buttons",
  id     = "hobbies",
  label  = "Select all your hobbies:",
  option = c("Reading" = "reading", "Hiking" = "hiking", "Coding" = "coding")
)

# Numeric slider with range
sd_question(
  type    = "slider_numeric",
  id      = "age_range",
  label   = "Select your age range:",
  option  = seq(18, 80, 1),
  default = c(25, 45)   # range slider: two default values
)

# Matrix question
sd_question(
  type   = "matrix",
  id     = "satisfaction",
  label  = "Rate each aspect:",
  option = c("Poor" = "1", "Fair" = "2", "Good" = "3", "Excellent" = "4"),
  row    = c("Service" = "service", "Quality" = "quality", "Price" = "price")
)

# Date range
sd_question(
  type  = "daterange",
  id    = "trip_dates",
  label = "When did you travel?"
)
```

### Parameters
- **type** (string) - The type of question (e.g., "mc", "slider_numeric", "matrix", "daterange").
- **id** (string) - A unique identifier for the question.
- **label** (string) - The text displayed as the question prompt.
- **option** (vector) - A named vector of options for multiple-choice or matrix questions.
- **row** (vector, optional) - A named vector of row labels for matrix questions.
- **default** (vector, optional) - Default value(s) for the question.
```

--------------------------------

### sd_add_page()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

An RStudio addin helper that inserts a page div template at the cursor position in the active `survey.qmd` document. Use `page_id = "end"` for a closing thank-you page with `sd_close()`.

```APIDOC
## sd_add_page(page_id)

### Description
An RStudio addin helper that inserts a page div template at the cursor position in the active `survey.qmd` document. Use `page_id = "end"` for a closing thank-you page with `sd_close()`.

### Parameters
* `page_id` (string) - The identifier for the page.

### Usage
```r
# In RStudio, inserts a page template at cursor
sd_add_page(page_id = "demographics")

# Insert an end/thank-you page template
sd_add_page(page_id = "end")
```
```

--------------------------------

### Include Folders for Static Assets with sd_include_folder

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Makes a custom folder accessible for serving static files within the Shiny app. The package automatically includes common folders like images/, css/, js/, and www/.

```R
# In app.R, before shinyApp():
library(surveydown)
library(shiny)

# Create a folder and include it in the resource path
dir.create("custom_assets")
sd_include_folder("custom_assets")

# Files in custom_assets/ are now accessible as /custom_assets/filename.ext
# In survey.qmd: ![](custom_assets/banner.png)
```

--------------------------------

### sd_add_question()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

An RStudio addin helper that inserts a question code template at the cursor position in the active document. It replaces the function call itself with the generated template code.

```APIDOC
## sd_add_question(type, id, label, chunk = FALSE)

### Description
An RStudio addin helper that inserts a question code template at the cursor position in the active document. Replaces the function call itself with the generated template code.

### Parameters
* `type` (string) - The type of question (e.g., "mc" for multiple choice, "slider_numeric").
* `id` (string) - The unique identifier for the question.
* `label` (string) - The text of the question presented to the user.
* `chunk` (boolean) - If TRUE, inserts the template inside an R chunk wrapper.

### Usage
```r
# In RStudio console or script — inserts template at cursor:
sd_add_question("mc", id = "fav_color", label = "What is your favorite color?")

# Insert a slider template inside an R chunk wrapper
sd_add_question("slider_numeric", id = "satisfaction", chunk = TRUE)
```
```

--------------------------------

### Create survey exit/finish button with sd_close

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Renders the finish button on the last page. Optionally shows a rating modal, includes a Restart button, and can display a Previous button.

```r
# Simple exit button
sd_close()
```

```r
# With custom label
sd_close(label_close = "Finish Survey")
```

```r
# With restart option (allows re-taking the survey)
sd_close(
  show_restart   = TRUE,
  label_restart  = "Take Again",
  clear_cookies  = TRUE
)
```

```r
# With previous button
sd_close(show_previous = TRUE, label_previous = "← Go Back")
```

--------------------------------

### Accessing Question Values with `all_data`

Source: https://github.com/surveydown-dev/surveydown/blob/main/CLAUDE.md

Use the `all_data` reactive values list for direct and robust access to question responses in server logic, including conditional logic and custom reactive expressions.

```r
# Direct access with $ notation
age_value <- all_data$age

# In conditional logic
sd_skip_if(
  all_data$age < 18 ~ "parental_consent",
  all_data$employed == "yes" ~ "employment_questions"
)

sd_show_if(
  all_data$has_children == "yes" ~ "num_children"
)

# In custom reactive expressions
output$custom_message <- renderText({
  paste("Hello", all_data$name, "from", all_data$country)
})
```

--------------------------------

### Run All and Specific Tests in Surveydown

Source: https://github.com/surveydown-dev/surveydown/blob/main/CLAUDE.md

Execute all automated tests using devtools::test() or run a specific test file with testthat::test_file().

```r
# Run all tests
devtools::test()

# Run a specific test file
testthat::test_file("tests/testthat/test-reserved-ids.R")
```

--------------------------------

### sd_redirect()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Generates a button or text link that redirects the user to a specified URL. It supports auto-redirect with a countdown timer and the option to open the URL in a new tab. This function can be used in both static and reactive contexts.

```APIDOC
## `sd_redirect()` — Create a redirect button or link

Generates a button or text link that redirects the user to a URL. Supports auto-redirect with a countdown timer and opening in a new tab. Can be used in both static (survey.qmd) and reactive (app.R) contexts.

```r
# In survey.qmd (static redirect):
sd_redirect(
  id     = "prolific_redirect",
  url    = "https://app.prolific.com/submissions/complete?cc=XXXX",
  label  = "Return to Prolific",
  button = TRUE,
  newtab = FALSE
)

# With countdown auto-redirect (5 seconds)
sd_redirect(
  id     = "auto_redirect",
  url    = "https://example.com/thank-you",
  label  = "Redirecting...",
  delay  = 5,
  newtab = FALSE
)

# In app.R (reactive redirect based on condition):
server <- function(input, output, session) {
  params <- sd_get_url_pars()
  sd_redirect(
    id  = "custom_url",
    url = paste0("https://example.com?id=", params[["user_id"]])
  )
  sd_server(db = db)
}
```
```

--------------------------------

### Configure option/subquestion shuffling in survey YAML

Source: https://github.com/surveydown-dev/surveydown/blob/main/NEWS.md

Enable shuffling for 'mc', 'mc_buttons', 'mc_multiple', 'mc_multiple_buttons' question types and 'matrix' subquestions using `shuffled` or `all-shuffled` keys in the survey YAML.

```yaml
shuffled: [question_id_1, question_id_2]
all-shuffled: true
```

--------------------------------

### Load question from questions.yml

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Reads question details like type, label, and options from a questions.yml file.

```r
sd_question(id = "city")  # reads type, label, options from questions.yml
```

--------------------------------

### sd_include_folder()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Makes a custom folder accessible for serving static files within the Shiny app. The package automatically includes several default folders.

```APIDOC
## sd_include_folder()

### Description
Makes a custom folder (e.g., `images/`, `videos/`) accessible for serving static files within the Shiny app. The package automatically includes `_survey/`, `images/`, `css/`, `js/`, and `www/` on attach.

### Usage
```r
# In app.R, before shinyApp():
library(surveydown)
library(shiny)

# Create a folder and include it in the resource path
dir.create("custom_assets")
sd_include_folder("custom_assets")

# Files in custom_assets/ are now accessible as /custom_assets/filename.ext
# In survey.qmd: ![](custom_assets/banner.png)
```
```

--------------------------------

### Store and Display Reactive Values with sd_reactive and sd_output

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Use sd_reactive to store reactive values computed in the server function. Display these values in survey.qmd using sd_output with type = 'value'.

```R
server <- function(input, output, session) {

  # Store the product of two numeric inputs as a survey column
  product <- sd_reactive("product", {
    as.numeric(input$num_a) * as.numeric(input$num_b)
  })

  # Use the reactive value in outputs
  output$product_display <- renderText({
    paste("Product:", product())
  })

  # Display in survey.qmd:
  # Result: `r sd_output("product", type = "value")`

  sd_server(db = db)
}
```

--------------------------------

### Conditionally skip to a page with sd_skip_if

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Defines forward-only skip conditions. If a condition is TRUE when the user clicks Next, navigation jumps directly to the target page, bypassing intermediate pages. Evaluated in the app.R server function.

```r
# In app.R server function:
server <- function(input, output, session) {

  sd_skip_if(
    input$consent  == "no"   ~ "end",
    input$age      < 18      ~ "underage_page",
    input$country  == "CA"   ~ "canada_specific"
  )

  sd_server(db = db)
}
```

--------------------------------

### Insert Page Template in RStudio

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

An RStudio addin to insert page div templates into `survey.qmd` files. Supports standard pages and a closing page with `sd_close()`.

```r
# In RStudio, inserts a page template at cursor
sd_add_page(page_id = "demographics")

# Insert an end/thank-you page template
sd_add_page(page_id = "end")

# Launch interactive gadget to enter page ID via GUI
sd_page_gadget()
```

--------------------------------

### Update survey settings in YAML header

Source: https://github.com/surveydown-dev/surveydown/blob/main/NEWS.md

Survey settings like `required` and `all-required` should now be configured in the YAML header of `survey.qmd`, replacing parameters previously in `sd_server()`.

```yaml
required: [question_id_1, question_id_2]
all-required: true
```

--------------------------------

### Render Survey Elements with sd_output

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

sd_output renders reactive questions, stored values, option labels, or question labels inline in survey.qmd. Use the 'type' argument to control what is rendered.

```R
library(surveydown)

# Display a reactive question defined in app.R server
sd_output("dynamic_question", type = "question")

# Show a stored completion code inline (in text)
# "Your code is: `r sd_output('completion_code', type = 'value')`"

# Show the selected option label (e.g., "Adélie" not "adelie")
sd_output("fav_penguin", type = "label_option")

# Show the question text itself
sd_output("fav_penguin", type = "label_question")

# Generic uiOutput for custom UI elements
sd_output("my_custom_ui")
```

--------------------------------

### Create custom widget question with sd_question_custom

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Wraps any Shiny widget as a survey question, capturing its reactive value. Requires leaflet and surveydown libraries. The output is rendered in the app.R server function.

```r
library(surveydown)
library(leaflet)

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

  output$usa_map <- renderLeaflet({
    leaflet() |>
      addTiles() |
      setView(lng = -98.5795, lat = 39.8283, zoom = 4)
  })

  selected_location <- reactiveVal(NULL)

  observeEvent(input$usa_map_click, {
    click <- input$usa_map_click
    selected_location(sprintf("%.4f, %.4f", click$lat, click$lng))
  })

  sd_question_custom(
    id     = "clicked_location",
    label  = "Click on your location on the map:",
    output = leafletOutput("usa_map", height = "400px"),
    value  = selected_location
  )

  sd_server(db = db)
}
```

--------------------------------

### sd_nav()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Creates page navigation buttons (Previous and/or Next) at the bottom of a survey page. It can specify the target page, customize labels, and control button visibility. Auto-navigation is enabled if `sd_nav()` is not explicitly called.

```APIDOC
## `sd_nav()` — Create page navigation buttons

Renders Previous and/or Next navigation buttons at the bottom of a survey page. Replaces the deprecated `sd_next()`. Can specify the target page, customize labels, and control button visibility. Auto-navigation is added when `sd_nav()` is not explicitly called on a page.

```r
# In survey.qmd R chunks:

# Default: both buttons, reads show-previous from YAML
sd_nav()

# First page: hide Previous button
sd_nav(show_previous = FALSE)

# Custom next destination and labels
sd_nav(
  page_next      = "demographics",
  label_previous = "Go Back",
  label_next     = "Continue →"
)

# Hide Next button (page requires sd_close or another mechanism)
sd_nav(show_next = FALSE)
```
```

--------------------------------

### Insert Question Template in RStudio

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

An RStudio addin to insert question code templates at the cursor. Can be used directly or via a GUI gadget.

```r
# In RStudio console or script — inserts template at cursor:
sd_add_question("mc", id = "fav_color", label = "What is your favorite color?")

# Insert a slider template inside an R chunk wrapper
sd_add_question("slider_numeric", id = "satisfaction", chunk = TRUE)

# Launch an interactive gadget to choose type, ID, and label via GUI
sd_question_gadget()
```

--------------------------------

### sd_version()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Checks for updates to the surveydown package by comparing the local version with the latest version on GitHub. Prints update instructions if a newer version is available.

```APIDOC
## sd_version()

### Description
Compares the locally installed version of surveydown against the latest version on GitHub and prints update instructions if a newer version is available.

### Usage
```r
library(surveydown)

sd_version()
```

### Example Output
```
surveydown (local):  1.1.3
surveydown (latest): 1.1.3

surveydown is up to date.
```
```

--------------------------------

### Load surveydown Package

Source: https://github.com/surveydown-dev/surveydown/blob/main/README.md

Load the surveydown package into your R session to use its functions.

```r
library(surveydown)
```

--------------------------------

### Add restart button to sd_close()

Source: https://github.com/surveydown-dev/surveydown/blob/main/NEWS.md

The `sd_close()` function now supports adding a 'restart' button to allow respondents to submit another response with proper cookie handling.

```R
sd_close(..., restart = TRUE)
```

--------------------------------

### sd_copy_value()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Creates a copy of an input's value accessible via sd_output(). Useful for displaying the same answer in multiple places without asking the question again.

```APIDOC
## sd_copy_value()

### Description
Creates a copy of an input's value accessible via `sd_output()`. Useful for displaying the same answer in multiple places in the survey without asking the question again.

### Usage
```r
# In app.R server function:
server <- function(input, output, session) {

  # Copy the "name" input to a new output ID "name_display"
  sd_copy_value(id = "name", id_copy = "name_display")

  # Then in survey.qmd, display it:
  # "Hello, `r sd_output('name_display', type = 'value')`!"

  sd_server(db = db)
}
```
```

--------------------------------

### sd_get_data()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Fetches all survey responses from the database. In a reactive context, it returns a reactive expression that can auto-refresh at a specified interval.

```APIDOC
## sd_get_data()

### Description
Retrieves all rows from the survey response table. In a reactive (Shiny) context with `refresh_interval`, returns a reactive expression that auto-refreshes at the specified interval—useful for live dashboards.

### Method
`sd_get_data(db, refresh_interval = NULL)`

### Parameters
- **db** (Pool or NULL) - A database connection pool object created by `sd_db_connect()`. If `NULL`, it attempts to connect using default settings.
- **refresh_interval** (numeric, optional) - The interval in seconds for auto-refreshing the data in a Shiny reactive context.

### Request Example
```r
library(surveydown)

db <- sd_db_connect()

# Non-reactive context: returns a data frame
responses <- sd_get_data(db)
head(responses)
# session_id  time_start           fav_penguin  age
# abc123      2024-01-15 10:23:45  adelie       25

# Reactive Shiny dashboard with auto-refresh every 10 seconds
server <- function(input, output, session) {
  data <- sd_get_data(db, refresh_interval = 10)

  output$response_table <- renderTable({
    data()   # reactive expression – call with ()
  })

  output$n_responses <- renderText({
    nrow(data())
  })
}
```
```

--------------------------------

### sd_show_if()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Defines reactive display conditions for survey questions or pages. An element is shown only when its associated condition evaluates to TRUE. This function must be called before `sd_server()` and hides elements by default until conditions are met.

```APIDOC
## `sd_show_if()` — Conditionally show questions or pages

Defines reactive display conditions: a question or page is shown only when the condition is `TRUE`. Must be called before `sd_server()`. Hides elements by default until conditions are met.

```r
# In app.R server function:
server <- function(input, output, session) {

  sd_show_if(
    input$has_car    == "yes"  ~ "car_make",      # show question
    input$employed   == "yes"  ~ "job_title",      # show question
    input$age        >= 18     ~ "adult_page"       # show entire page
  )

  sd_server(db = db)
}
```
```

--------------------------------

### YAML for Shuffling Survey Questions

Source: https://github.com/surveydown-dev/surveydown/blob/main/CLAUDE.md

Configure specific questions or all eligible questions to have their options or rows randomized using YAML settings in survey.qmd.

```yaml
survey-settings:
  shuffled: [question_id1, question_id2]  # Specific questions to shuffle
  all-shuffled: yes  # Or shuffle all eligible questions
```

--------------------------------

### sd_skip_if()

Source: https://context7.com/surveydown-dev/surveydown/llms.txt

Defines forward-only skip conditions for survey navigation. If a condition is TRUE when the user attempts to proceed, navigation jumps directly to the specified target page, bypassing any intermediate pages.

```APIDOC
## `sd_skip_if()` — Conditionally skip to a page

Defines forward-only skip conditions: if the condition is `TRUE` when the user clicks Next, navigation jumps directly to the target page, bypassing intermediate pages.

```r
# In app.R server function:
server <- function(input, output, session) {

  sd_skip_if(
    input$consent  == "no"   ~ "end",
    input$age      < 18      ~ "underage_page",
    input$country  == "CA"   ~ "canada_specific"
  )

  sd_server(db = db)
}
```
```