# maidr

## Overview

maidr (Multimodal Access and Interactive Data Representation) makes data
visualizations accessible to users with visual impairments. It converts
ggplot2 and Base R plots into interactive, accessible HTML/SVG formats
with keyboard navigation, screen reader support, and sonification.

The package provides two main functions:

- [`show()`](https://r.maidr.ai/reference/show.md) displays an
  interactive accessible plot in RStudio Viewer or browser
- [`save_html()`](https://r.maidr.ai/reference/save_html.md) exports a
  plot as a standalone HTML file

## Installation

Install the stable release from CRAN:

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

Or install the development version from GitHub:

``` r
# Using pak (recommended)
pak::pak("xability/r-maidr")

# Alternative: using pacman (auto-installs if missing)
pacman::p_load_gh("xability/r-maidr")
```

## Usage

### ggplot2

``` r
library(maidr)
library(ggplot2)

p <- ggplot(mpg, aes(x = class)) +
  geom_bar(fill = "steelblue") +
  labs(title = "Vehicle Classes", x = "Class", y = "Count")

# Display interactive accessible plot
show(p)

# Or save to file
save_html(p, "vehicle_classes.html")
```

### Base R

``` r
library(maidr)

# Create plot first
barplot(
  table(mtcars$cyl),
  main = "Cars by Cylinder Count",
  xlab = "Cylinders",
  ylab = "Count"
)

# Then call show() without arguments
show()
```

## Supported plot types

maidr supports a wide range of visualization types in both ggplot2 and
Base R:

### Basic Plot Types

| Plot Type           | ggplot2                                                                                                                                                    | Base R                                                                           |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| Bar charts          | [`geom_bar()`](https://ggplot2.tidyverse.org/reference/geom_bar.html), [`geom_col()`](https://ggplot2.tidyverse.org/reference/geom_bar.html)               | [`barplot()`](https://r.maidr.ai/reference/base-r-wrappers.md)                   |
| Grouped/Dodged bars | `position = "dodge"`                                                                                                                                       | `beside = TRUE`                                                                  |
| Stacked bars        | `position = "stack"`                                                                                                                                       | `beside = FALSE`                                                                 |
| Histograms          | [`geom_histogram()`](https://ggplot2.tidyverse.org/reference/geom_histogram.html)                                                                          | [`hist()`](https://r.maidr.ai/reference/base-r-wrappers.md)                      |
| Scatter plots       | [`geom_point()`](https://ggplot2.tidyverse.org/reference/geom_point.html)                                                                                  | [`plot()`](https://r.maidr.ai/reference/base-r-wrappers.md)                      |
| Line plots          | [`geom_line()`](https://ggplot2.tidyverse.org/reference/geom_path.html)                                                                                    | `plot(type = "l")`, [`lines()`](https://r.maidr.ai/reference/base-r-wrappers.md) |
| Box plots           | [`geom_boxplot()`](https://ggplot2.tidyverse.org/reference/geom_boxplot.html)                                                                              | [`boxplot()`](https://r.maidr.ai/reference/base-r-wrappers.md)                   |
| Heatmaps            | [`geom_tile()`](https://ggplot2.tidyverse.org/reference/geom_tile.html)                                                                                    | [`image()`](https://r.maidr.ai/reference/base-r-wrappers.md)                     |
| Violin plots        | [`geom_violin()`](https://ggplot2.tidyverse.org/reference/geom_violin.html)                                                                                | —                                                                                |
| Density/Smooth      | [`geom_smooth()`](https://ggplot2.tidyverse.org/reference/geom_smooth.html), [`geom_density()`](https://ggplot2.tidyverse.org/reference/geom_density.html) | `lines(density())`                                                               |

### Advanced Plot Types

| Plot Type           | ggplot2                                                                                                                                              | Base R                     |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
| Faceted plots       | [`facet_wrap()`](https://ggplot2.tidyverse.org/reference/facet_wrap.html), [`facet_grid()`](https://ggplot2.tidyverse.org/reference/facet_grid.html) | `par(mfrow/mfcol)` + loops |
| Multi-panel layouts | `patchwork` package                                                                                                                                  | `par(mfrow)`, `par(mfcol)` |
| Multi-layered plots | Multiple `geom_*` layers                                                                                                                             | Sequential plot calls      |

See `vignette("plot-types")` for detailed examples of each plot type.

## Accessibility features

- **Keyboard navigation** - explore data points using arrow keys
- **Screen reader support** - full ARIA labels and live announcements
- **Sonification** - hear data patterns through sound
- **Text descriptions** - automatic statistical summaries

## Offline support

By default, maidr auto-detects internet availability and loads the
MAIDR.js library from a CDN. Use the `use_cdn` parameter for explicit
control:

``` r
# Force CDN (requires internet)
show(p, use_cdn = TRUE)

# Force bundled files (works offline)
show(p, use_cdn = FALSE)
save_html(p, "plot.html", use_cdn = FALSE)
```

## Getting help

- Report bugs or request features at [GitHub
  Issues](https://github.com/xability/r-maidr/issues)
- Read the documentation at the [package website](https://r.maidr.ai/)

## Learning more

- [`vignette("getting-started", package = "maidr")`](https://r.maidr.ai/articles/getting-started.md)
  for an introduction
- `vignette("plot-types", package = "maidr")` for supported
  visualizations
- [`vignette("shiny-integration", package = "maidr")`](https://r.maidr.ai/articles/shiny-integration.md)
  for Shiny apps

# Package index

## Main functions

Primary user-facing functions for creating accessible plots

- [`show()`](https://r.maidr.ai/reference/show.md) : Display Interactive
  MAIDR Plot
- [`save_html()`](https://r.maidr.ai/reference/save_html.md) : Save
  Interactive Plot as HTML File

## RMarkdown integration

Functions for enabling accessible plots in RMarkdown documents

- [`maidr_on()`](https://r.maidr.ai/reference/maidr_on.md) : Enable
  MAIDR Plot Interception
- [`maidr_off()`](https://r.maidr.ai/reference/maidr_off.md) : Disable
  MAIDR Plot Interception

## Shiny integration

Functions for using maidr in Shiny applications

- [`render_maidr()`](https://r.maidr.ai/reference/render_maidr.md) :
  Render MAIDR Plot in Shiny Server
- [`maidr_output()`](https://r.maidr.ai/reference/maidr_output.md) :
  MAIDR Output Container for Shiny UI

## Configuration and utilities

Functions for configuring MAIDR behavior and running examples

- [`maidr_set_fallback()`](https://r.maidr.ai/reference/maidr_set_fallback.md)
  : Configure MAIDR Fallback Behavior
- [`maidr_get_fallback()`](https://r.maidr.ai/reference/maidr_get_fallback.md)
  : Get Current MAIDR Fallback Settings
- [`run_example()`](https://r.maidr.ai/reference/run_example.md) : Run
  MAIDR Example Plots

## Internal utilities

Internal functions for package developers

- [`combine_facet_layer_data()`](https://r.maidr.ai/reference/combine_facet_layer_data.md)
  : Combine data from multiple layers in facet processing
- [`combine_facet_layer_selectors()`](https://r.maidr.ai/reference/combine_facet_layer_selectors.md)
  : Combine selectors from multiple layers in facet processing
- [`extract_leaf_plot_layout()`](https://r.maidr.ai/reference/extract_leaf_plot_layout.md)
  : Extract layout from a single leaf ggplot
- [`extract_patchwork_leaves()`](https://r.maidr.ai/reference/extract_patchwork_leaves.md)
  : Recursively extract leaf ggplots in visual order
- [`find_children_by_type()`](https://r.maidr.ai/reference/find_children_by_type.md)
  : Find children matching a type pattern
- [`find_graphics_plot_grob()`](https://r.maidr.ai/reference/find_graphics_plot_grob.md)
  : Utility functions for robust selector generation in Base R plots
- [`find_panel_grob()`](https://r.maidr.ai/reference/find_panel_grob.md)
  : Find the panel grob in a grob tree
- [`find_patchwork_panels()`](https://r.maidr.ai/reference/find_patchwork_panels.md)
  : Discover panels via gtable layout rows named '^panel-\<num\>' or
  '^panel-\<row\>-\<col\>' Returns a data.frame with panel_index, name,
  t, l, row, col
- [`generate_robust_css_selector()`](https://r.maidr.ai/reference/generate_robust_css_selector.md)
  : Generate robust CSS selector from grob name
- [`generate_robust_selector()`](https://r.maidr.ai/reference/generate_robust_selector.md)
  : Generate robust selector for any element type
- [`get_facet_groups()`](https://r.maidr.ai/reference/get_facet_groups.md)
  : Get facet group information for a panel
- [`map_visual_to_dom_panel()`](https://r.maidr.ai/reference/map_visual_to_dom_panel.md)
  : Map visual panel position to DOM panel name
- [`organize_facet_grid()`](https://r.maidr.ai/reference/organize_facet_grid.md)
  : Organize subplots into 2D grid structure
- [`process_facet_panel()`](https://r.maidr.ai/reference/process_facet_panel.md)
  : Process a single facet panel
- [`process_patchwork_panel()`](https://r.maidr.ai/reference/process_patchwork_panel.md)
  : Process a single patchwork panel

# Articles

### All vignettes

- [Examples](https://r.maidr.ai/articles/examples.md):
- [Getting Started with
  MAIDR](https://r.maidr.ai/articles/getting-started.md):
- [Using MAIDR in Shiny
  Applications](https://r.maidr.ai/articles/shiny-integration.md):