|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +plotly is an R package for creating interactive web graphics via the plotly.js JavaScript library. It provides two main interfaces: |
| 8 | +- `ggplotly()`: Converts ggplot2 objects to interactive plotly visualizations |
| 9 | +- `plot_ly()`: Direct interface to plotly.js for specialized chart types |
| 10 | + |
| 11 | +## Common Commands |
| 12 | + |
| 13 | +### Running Tests |
| 14 | +```r |
| 15 | +# Run all tests |
| 16 | +devtools::test() |
| 17 | + |
| 18 | +# Run visual tests (requires kaleido via reticulate) |
| 19 | +Sys.setenv("VISUAL_TESTS" = "true") |
| 20 | +devtools::test() |
| 21 | + |
| 22 | +# Run a single test file |
| 23 | +devtools::test(filter = "ggplot-bar") |
| 24 | +``` |
| 25 | + |
| 26 | +### Package Check |
| 27 | +```r |
| 28 | +rcmdcheck::rcmdcheck() |
| 29 | +``` |
| 30 | + |
| 31 | +### Building Documentation |
| 32 | +```r |
| 33 | +devtools::document() |
| 34 | +``` |
| 35 | + |
| 36 | +### Visual Testing via Docker |
| 37 | +For consistent visual test results: |
| 38 | +```shell |
| 39 | +docker run -v $(pwd):/home/plotly --privileged -p 3838:3838 cpsievert/plotly-orca |
| 40 | +``` |
| 41 | +Access the validation Shiny app at http://0.0.0.0:3838 |
| 42 | + |
| 43 | +CI-only visual test run: |
| 44 | +```shell |
| 45 | +docker run -e VMODE="ci" -v $(pwd):/home/plotly --privileged cpsievert/plotly-orca |
| 46 | +``` |
| 47 | + |
| 48 | +## Architecture |
| 49 | + |
| 50 | +### ggplot2 to plotly Conversion Pipeline |
| 51 | + |
| 52 | +The conversion from ggplot2 to plotly follows this flow: |
| 53 | + |
| 54 | +1. **`ggplotly()`** (`R/ggplotly.R`): Entry point that dispatches on input type |
| 55 | +2. **`gg2list()`** (`R/ggplotly.R`): Main conversion function that: |
| 56 | + - Builds the ggplot object to extract computed data |
| 57 | + - Processes each layer through `layers2traces()` |
| 58 | + - Processes layout through `layers2layout()` |
| 59 | +3. **`layers2traces()`** (`R/layers2traces.R`): Converts ggplot2 geom layers to plotly trace objects |
| 60 | +4. **`layers2layout()`** (`R/layers2layout.R`): Converts ggplot2 theme/coordinate settings to plotly layout |
| 61 | + |
| 62 | +### Direct plotly Interface |
| 63 | + |
| 64 | +1. **`plot_ly()`** (`R/plotly.R`): Creates a plotly object with trace attributes |
| 65 | +2. **`add_trace()`** and `add_*()` functions (`R/add.R`): Add traces to existing plots |
| 66 | +3. **`layout()`** (`R/layout.R`): Modify plot layout |
| 67 | +4. **`plotly_build()`** (`R/plotly_build.R`): Evaluates lazy attributes and creates final JSON for plotly.js |
| 68 | + |
| 69 | +### Key Modules |
| 70 | + |
| 71 | +- `R/shiny.R`: Shiny integration and event handling |
| 72 | +- `R/subplots.R`: Combining multiple plots |
| 73 | +- `R/highlight.R`: Linked brushing/crosstalk support |
| 74 | +- `R/animate.R`: Animation support |
| 75 | +- `R/kaleido.R`, `R/orca.R`: Static image export |
| 76 | + |
| 77 | +## Testing Patterns |
| 78 | + |
| 79 | +Tests should check the return value of `plotly_build()`: |
| 80 | +```r |
| 81 | +test_that("example test", { |
| 82 | + p <- plot_ly(x = 1:10, y = 1:10) |
| 83 | + built <- plotly_build(p) |
| 84 | + expect_equal(built$x$data[[1]]$x, 1:10) |
| 85 | +}) |
| 86 | +``` |
| 87 | + |
| 88 | +Visual tests use `expect_doppelganger()` from `tests/testthat/helper-vdiffr.R`: |
| 89 | +```r |
| 90 | +test_that("visual test", { |
| 91 | + p <- plot_ly(x = 1:10, y = 1:10) |
| 92 | + expect_doppelganger(p, "scatter-basic") |
| 93 | +}) |
| 94 | +``` |
| 95 | + |
| 96 | +## Code Style |
| 97 | + |
| 98 | +Follow the tidyverse style guide: http://style.tidyverse.org/ |
0 commit comments