---
title: "Getting Started with ViewR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with ViewR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  eval     = FALSE   # examples require an interactive Shiny session
)
```

## Overview

**ViewR** brings spreadsheet-style data exploration directly into your R
workflow. A single function call opens a polished, popup-based interface
that lets you filter, sort, search, edit, and understand any `data.frame`
— and automatically writes the equivalent `dplyr` code so you never lose
reproducibility.

```{r, eval=FALSE}
library(ViewR)
ViewR(mtcars)
```

---

## The `ViewR()` function

The entire interface is controlled through one function:

```{r signature}
ViewR(
  data,
  edit          = FALSE,   # enable Excel-like editing
  popup         = TRUE,    # open as modal dialog
  labels        = NULL,    # named vector of variable labels
  title         = NULL,    # custom window title
  viewer        = "dialog",# "dialog", "browser", or "pane"
  generate_code = TRUE,    # show R Code tab
  theme         = "flatly",# Bootstrap theme
  max_display   = 50000L,  # row cap for rendering
  return_data   = TRUE     # return (possibly edited) data on close
)
```

`ViewR()` is **pipe-friendly** and returns the (possibly modified) data
frame invisibly when the user clicks *Done*:

```{r pipe}
library(dplyr)

clean_data <- mtcars |>
  filter(cyl >= 4) |>
  ViewR(edit = TRUE)   # open popup; result assigned on Done
```

---

## Walkthrough of the interface

### Sidebar

The left-hand sidebar provides three action panels that update the data
display in real time.

#### Filters

Click the green **+** button to add a filter condition. Each row has:

| Control  | Options |
|----------|---------|
| Column   | any column in the data |
| Operator | `==`, `!=`, `>`, `>=`, `<`, `<=`, *contains*, *starts with*, *ends with*, *is NA*, *is not NA* |
| Value    | free-text input |
| Logic    | **AND** (default) or **OR** (shown from the second row onward) |

You can add as many filter rows as you need. Click **Clear all** to
remove all filters at once.

#### Sort

Add one or more sort levels. Each level has a column and a direction
(ascending ↑ or descending ↓). Levels are applied in order — the first
is the primary sort key, the second is the tiebreaker, and so on.

#### Columns

Tick or untick columns to show or hide them. The **All** / **None**
links act as bulk toggles.

---

### Main tabs

#### Data

The main data table is powered by the **DT** package. It supports:

- **Global search** (top-right of the table)
- **Per-column filter boxes** below each header
- Clickable column headers for one-click ascending/descending sort
- Configurable page length (use the *Rows per page* slider in the
  sidebar)

If you supply `labels` (or use a dataset imported with **haven**), each
column header will show an ⓘ tooltip with the full label when you hover.

#### Edit *(requires `edit = TRUE`)*

An Excel-like grid powered by **rhandsontable**. You can:

- Click any cell and type to edit its value directly
- Right-click a row header for insert / remove options
- Use the **Add Row** button to append a blank row
- **Undo** and **Redo** (unlimited) step through the change history

Changes are committed to the returned data frame when you click **Done**.

> **Tip:** Clear all filters and sorts before editing to ensure row
> positions map correctly back to the original data.

#### Find & Replace

Search for any text pattern — literal or regex — and replace it in one
or all columns. The workflow is:

1. Choose a column (or *All columns*) from the dropdown.
2. Type the **Find** string and the **Replace with** string.
3. Optionally tick *Case sensitive*, *Regex*, or *Exact cell match*.
4. Click **Preview** to see a diff table of affected cells.
5. Click **Apply** to commit the replacement.

#### Variable Info

A summary table for every column in the current working data:

| Column | Description |
|--------|-------------|
| Type   | R class (character, integer, numeric, …) |
| N      | Count of non-missing values |
| Missing | Count of NA values |
| Missing % | Percentage missing (colour-bar visualised) |
| Unique | Number of distinct values |
| Min / Max | For numeric columns |
| Sample values | Up to 4 example values |

#### R Code

Every action you perform — filtering, sorting, showing/hiding columns,
find-and-replace — is translated into a **dplyr** pipeline and displayed
here in real time:

```r
library(dplyr)

mtcars_result <- mtcars |>
  filter(
    `cyl` == "6"
  ) |>
  arrange(desc(`mpg`)) |>
  select(`mpg`, `cyl`, `hp`, `wt`)
```

Click **Copy to clipboard** to paste the code directly into your script.
Click **Reset** to clear the history of find-replace and edit operations
(filter/sort/column code is always live and cannot be cleared
independently).

---

## Variable labels

ViewR automatically reads variable labels stored as column attributes, as
produced by **haven**, **labelled**, or **Hmisc**:

```{r labels-auto}
# df <- haven::read_sav("my_survey.sav")
# ViewR(df)   # labels appear as tooltips automatically
```

You can also supply labels manually:

```{r labels-manual}
ViewR(mtcars,
      labels = c(
        mpg  = "Miles per Gallon",
        cyl  = "Number of Cylinders",
        disp = "Displacement (cu.in.)",
        hp   = "Gross Horsepower",
        wt   = "Weight (1000 lbs)"
      ))
```

---

## Themes

Choose from any Bootstrap theme supported by **shinythemes**:

```{r themes}
ViewR(iris, theme = "darkly")    # dark
ViewR(iris, theme = "cerulean")  # light blue
ViewR(iris, theme = "cosmo")     # clean & minimal
ViewR(iris, theme = "sandstone") # warm beige
```

---

## Opening in the browser or Viewer pane

By default ViewR opens as a modal dialog inside RStudio. Use the
`viewer` argument to change this:

```{r viewer}
# Open in the system browser (useful for large datasets)
ViewR(iris, viewer = "browser")

# Open in the RStudio Viewer pane
ViewR(iris, viewer = "pane")

# Or equivalently, set popup = FALSE (defaults to browser)
ViewR(iris, popup = FALSE)
```

---

## Editing data and returning results

When `edit = TRUE`, clicking **Done** returns the modified data frame:

```{r editing}
# Open the editor; assign the result
corrected <- ViewR(survey_data, edit = TRUE)

# 'corrected' now contains all inline edits + any find-replace operations
head(corrected)
```

If you click **Cancel**, the original unmodified data frame is returned.

---

## Full example: survey data workflow

```{r survey-workflow}
library(ViewR)

# Load a dataset (here we use the built-in survey proxy)
data(Titanic)
titanic_df <- as.data.frame(Titanic)

# Step 1 — Explore: inspect variable info and browse the data
ViewR(titanic_df,
      labels = c(Class    = "Passenger Class",
                 Sex      = "Passenger Sex",
                 Age      = "Age Group",
                 Survived = "Survival Status",
                 Freq     = "Count"),
      theme  = "flatly")

# Step 2 — Clean: use Find & Replace inside the popup to
#   standardise "Male" -> "M", "Female" -> "F"

# Step 3 — Filter & export: the R Code tab will have generated:
#   titanic_df_result <- titanic_df |>
#     filter(`Survived` == "Yes") |>
#     arrange(desc(`Freq`))
# Copy, paste, and run!

# Step 4 — Edit specific cells if needed
titanic_clean <- ViewR(titanic_df, edit = TRUE)
```

---

## Session info

```{r session, eval=TRUE}
sessionInfo()
```