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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4.5
)
```

```{r setup}
library(glyph)
```

This vignette walks through glyph's grammar with live, interactive output.
Every plot below is a real `glyph_spec` built with the package and rendered
to an actual D3-backed htmlwidget — not a screenshot. Hover, click, brush,
and zoom them right here in the page.

One thing worth knowing up front: printing a `glyph_spec` at the console
auto-renders it (like a ggplot2 plot), but that auto-render only fires in an
interactive R session. Inside a vignette or pkgdown article the code runs
non-interactively, so each example below ends the pipeline with an explicit
[`render()`](https://josh45-source.github.io/glyph/reference/render.html) call to produce the widget.

All examples use `mtcars` so you can copy-paste and run them yourself.

## 1. Tooltips and hover, declared in the pipeline

Interactivity is grammar, not glue. [`interact()`](https://josh45-source.github.io/glyph/reference/interact.html)
turns on tooltips and a hover effect right where the plot is built, and
[`titles()`](https://josh45-source.github.io/glyph/reference/titles.html) adds a title in the same pipe — no
`ggplotly()` conversion step, no lost formatting.

```{r}
glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  interact(tooltip = TRUE, hover = "enlarge") |>
  titles(title = "Motor Trend Cars") |>
  render()
```

Hover over a point to see it enlarge; pause on it to see the tooltip.

## 2. Animated bar chart

[`animate()`](https://josh45-source.github.io/glyph/reference/animate.html) declares a transition as part of
the spec. `stagger` offsets each bar's entrance animation so they draw in
sequence rather than all at once.

```{r}
glyph(mtcars, x = cyl, y = mpg) |>
  mark_bar() |>
  animate(transition = "slide", stagger = 50) |>
  render()
```

Reload this page (or re-run the chunk in an R session) to see the bars
slide in.

## 3. Token-based dark theme

Instead of ggplot2's dozens of individual `theme()` arguments,
[`theme_tokens()`](https://josh45-source.github.io/glyph/reference/theme_tokens.html) takes a small preset (or
individual tokens like `bg`, `font`, `accent`) and cascades foreground, grid,
and title colors automatically for contrast.

```{r}
glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  interact(tooltip = TRUE) |>
  theme_tokens(preset = "dark") |>
  titles(title = "Dark Theme Example") |>
  render()
```

## 4. Point labels with automatic collision avoidance

[`mark_text()`](https://josh45-source.github.io/glyph/reference/mark_text.html) draws a label per point, and
`smart_repel = TRUE` nudges overlapping labels apart so they stay readable —
a first-class feature instead of a separate `ggrepel` dependency. `mtcars`
stores car names as row names, so we promote them to a real column first.

```{r}
mtcars_named <- data.frame(model = rownames(mtcars), mtcars, row.names = NULL)

glyph(mtcars_named, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  mark_text(label = model, smart_repel = TRUE) |>
  render()
```

## 5. Linked panels with crossfilter brushing

[`compose()`](https://josh45-source.github.io/glyph/reference/compose.html) arranges multiple `glyph_spec`
objects into a single layout — here, two scatterplots side by side — without
reaching for `patchwork` or `cowplot`. With `interact(brush = TRUE)` on each
panel and `linked_selections = TRUE` on the composed layout, brushing points
in one panel highlights the *same rows* in the other.

```{r}
p1 <- glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  interact(brush = TRUE)

p2 <- glyph(mtcars, x = hp, y = mpg) |>
  mark_point(color = cyl) |>
  interact(brush = TRUE)

compose(p1, p2, type = "hstack", linked_selections = TRUE) |>
  render()
```

Drag a rectangle over a few points in either panel — the corresponding cars
highlight in both.

## 6. Faceting

[`facet()`](https://josh45-source.github.io/glyph/reference/facet.html) splits a plot into small multiples by
one or two variables, each with its own panel — like ggplot2's
`facet_wrap()`, built into the same pipeline instead of a separate layer.

```{r}
glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  facet(cols = cyl) |>
  render()
```

## 7. Marginal distributions

[`marginals()`](https://josh45-source.github.io/glyph/reference/marginals.html) adds histograms, density
curves, or boxplots along the axes — a common pattern that normally needs
`ggExtra` or manual grid manipulation in ggplot2.

```{r}
glyph(mtcars, x = wt, y = mpg) |>
  mark_point(color = cyl) |>
  marginals(x = "histogram", y = "density") |>
  render()
```

## 8. Inset plots

[`inset()`](https://josh45-source.github.io/glyph/reference/inset.html) places a second, smaller glyph_spec
inside a corner of the main plot — useful for a detail view or a different
breakdown of the same data, without any manual viewport math.

```{r}
main_plot <- glyph(mtcars, x = wt, y = mpg) |> mark_point(color = cyl)
detail_plot <- glyph(mtcars, x = cyl, y = mpg) |> mark_bar()

inset(main_plot, detail_plot, position = "top-right") |>
  render()
```

## 9. Keyframe ("morph") animation

`animate(by = ..., transition = "morph")` cycles the plot through subsets of
the data grouped by a field, transitioning marks smoothly between states —
similar in spirit to `gganimate::transition_states()`, but with a built-in
play/pause control and no rendering-to-GIF step.

```{r}
glyph(mtcars, x = wt, y = mpg) |>
  mark_point(size = hp, color = cyl) |>
  animate(by = gear, transition = "morph", duration = 800) |>
  render()
```

Use the play/pause button to step through each `gear` group.

## Where to next

- Browse the [function reference](https://josh45-source.github.io/glyph/reference/index.html) for every mark,
  scale, and layout primitive glyph provides.
- Read [glyph vs ggplot2: Side-by-Side Comparison](comparison.html) for a
  broader tour of how the two grammars differ, including more live examples.