---
title: "Quickstart"
output: rmarkdown::html_vignette
resource_files:
  - figures/goldenviz-report.html
vignette: >
  %\VignetteIndexEntry{Quickstart}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(message = FALSE, warning = FALSE)
```

GoldenVizR is a review layer for `ggplot2` charts. You create the chart as
usual, then call `analyze_plot()` to get structured feedback.

## Basic workflow

```{r quickstart-basic}
library(ggplot2)
library(GoldenVizR)

p <- ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
  geom_point() +
  labs(
    title = "Fuel economy by weight",
    subtitle = "Motor Trend cars",
    x = "Weight",
    y = "Miles per gallon",
    colour = "Cylinders",
    caption = "Source: mtcars"
  )

report <- analyze_plot(p)
report$summary
```

## What the report contains

A GoldenVizR report is a list with four stable fields:

| Field | Meaning |
|---|---|
| `plot_summary` | Basic metadata extracted from the `ggplot2` object, including title, axis labels, geoms, layers, data size, facets, and coordinates. |
| `rule_results` | One row per GoldenViz rule, with the rule id, family, name, status, message, and suggestion column. |
| `status_counts` | Counts of `PASS`, `WARNING`, `FAIL`, and `INFO`. |
| `summary` | One-row overview with checked rules, implemented checks, status counts, and report status. |

Inspect rules that need attention:

```{r quickstart-attention}
subset(report$rule_results, status != "PASS")
```

## Manual analysis

Manual analysis means passing a specific `ggplot2` object to `analyze_plot()`
and inspecting the returned report yourself. This is useful in notebooks,
teaching material, package tests, dashboards, or review workflows where you
want explicit control over which chart is checked.

```{r quickstart-manual-one-plot}
manual_plot <- ggplot(mtcars, aes(factor(cyl), mpg)) +
  geom_boxplot() +
  labs(
    title = "Fuel economy by cylinder count",
    x = "Cylinders",
    y = "Miles per gallon",
    caption = "Source: mtcars"
  )

manual_report <- analyze_plot(manual_plot)
manual_report$summary
```

Inspect the full rule table:

```{r quickstart-manual-rules}
manual_report$rule_results
```

Most workflows start by filtering to rows that are not `PASS`:

```{r quickstart-manual-issues}
subset(manual_report$rule_results, status != "PASS")
```

You can also inspect a specific rule family:

```{r quickstart-manual-family}
subset(manual_report$rule_results, family == "Integrity")
```

Because the report is structured, it can be used programmatically:

```{r quickstart-manual-programmatic}
any(manual_report$rule_results$status == "FAIL")
manual_report$status_counts
```

## Render an HTML report

Use `render_report()` when you want a formatted HTML version of the same
structured review.

```{r quickstart-render-report, eval=FALSE}
html_report <- render_report(report)
html_report
```

In an R Markdown document, the rendered report can be printed from a code chunk.
To save the same report as a standalone HTML file, use `save_report()`:

```{r quickstart-save-report, eval=FALSE}
save_report(report, "goldenviz-report.html")
```

If your installed version includes `view_report()`, use it for quick local
inspection:

```{r quickstart-view-report, eval=FALSE}
view_report(report)
```

The HTML report is expected to include the same core sections as the structured
object:

```{r quickstart-expected-report}
names(report)
```

The report can also be embedded directly inside documentation, notebooks, and
HTML reports:

<iframe
  class="gv-report-frame"
  src="figures/goldenviz-report.html"
  title="Embedded GoldenVizR HTML report"
  loading="lazy">
</iframe>

The main areas of the report are annotated below:

```{r quickstart-report-annotated, echo=FALSE, out.width="100%"}
knitr::include_graphics("figures/goldenviz-report-annotated.png")
```

## How to read statuses

| Status | Meaning |
|---|---|
| `PASS` | The available evidence satisfied the rule. |
| `WARNING` | GoldenVizR found a likely issue or improvement opportunity. |
| `FAIL` | GoldenVizR found a stronger integrity, scale, or accessibility issue. |
| `INFO` | The plot object did not contain enough evidence for a responsible check. |

GoldenVizR is intentionally heuristic. It helps catch common issues early, but
it does not replace human judgment.