### Create a guide with arms on all four sides

Source: https://context7.com/teunbrand/legendry/llms.txt

Use compose_crux for the most flexible composition, placing a central guide surrounded by up to four guides on cardinal sides. This example shows a color bar with title annotations above and below.

```r
# Colour bar with title annotations above and below
crux <- compose_crux(
  centre = gizmo_barcap(),
  left   = "axis_base",
  right  = "axis_base",
  top    = primitive_title("A lot"),
  bottom = primitive_title("A little")
)

ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = cty)) +
  guides(colour = crux)
```

--------------------------------

### key_group_split Usage Example

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/key-group.md

Demonstrates the correct usage of key_group_split with a character separator. This function is used for splitting guide labels.

```R
key_group_split(sep = ":")(scale, "colour")
```

--------------------------------

### Install legendry from GitHub

Source: https://github.com/teunbrand/legendry/blob/main/README.md

Install the development version of the legendry package from GitHub using devtools.

```r
# install.packages("devtools")
devtools::install_github("teunbrand/legendry")
```

--------------------------------

### Stack primitive guide with axis guide

Source: https://github.com/teunbrand/legendry/blob/main/README.md

Combines the 'efficient_bracket' primitive guide with a standard axis guide using 'guide_axis_stack' to display a range on the y-axis.

```r
base + guides(y = guide_axis_stack("axis", efficient_bracket))
```

--------------------------------

### Arbitrary Grob as Guide Element (`gizmo_grob`)

Source: https://context7.com/teunbrand/legendry/llms.txt

Use `gizmo_grob` to represent an arbitrary grob (graphics object) as a guide element. Useful for custom visual elements in guides.

```r
circle <- grid::circleGrob()

ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  guides(
    x.sec  = gizmo_grob(circle, hjust = 0.75,
                         width = unit(2, "cm"), height = unit(2, "cm")),
    colour = gizmo_grob(circle, width = unit(1, "cm"), height = unit(1, "cm"))
  )
```

--------------------------------

### Compose a sandwich guide

Source: https://github.com/teunbrand/legendry/blob/main/README.md

Composes a 'sandwich' guide using 'compose_sandwich', featuring a density gizmo in the middle, axis base text, and the 'efficient_bracket' primitive guide on the opposite side.

```r
base +
  scale_colour_viridis_c(
    guide = compose_sandwich(
      middle = gizmo_density(),
      text = "axis_base",
      opposite = efficient_bracket
    )
  )
```

--------------------------------

### Create a primitive bracket guide

Source: https://github.com/teunbrand/legendry/blob/main/README.md

Defines a primitive guide 'efficient_bracket' to display a range on an axis using a manual key and a square bracket. Includes theme adjustments for vertical text.

```r
# A partial guide to display a bracket
efficient_bracket <- primitive_bracket(
  # Keys determine what is displayed
  key = key_range_manual(start = 25, end = Inf, name = "Efficient"),
  bracket = "square",
  # We want vertical text
  theme = theme(
    legend.text = element_text(angle = 90, hjust = 0.5),
    axis.text.y.left = element_text(angle = 90, hjust = 0.5)
  )
)
```

--------------------------------

### guide_colsteps() — Colour steps guide with caps

Source: https://context7.com/teunbrand/legendry/llms.txt

A binned variant of guide_colbar() that supports caps and options for displaying even steps.

```APIDOC
## guide_colsteps() — Colour steps guide with caps

### Description
Binned variant of `guide_colbar()`. Replaces `guide_coloursteps()` with cap support and even-step display options.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
* `key` (object) - Optional - Specifies how bins are generated (e.g., `key_bins(even.steps = TRUE)`).
* `first_guide` (string) - Optional - Controls the first guide display (e.g., "axis_base").
* `second_guide` (string) - Optional - Controls the second guide display (e.g., "axis_base").

### Request Example
```r
p + scale_colour_viridis_b(limits = c(10, 30), breaks = c(10, 20, 25), guide = guide_colsteps(key = key_bins(even.steps = TRUE)))
```

### Response
Not applicable (R function)
```

--------------------------------

### Create a central guide flanked by two parallel guides

Source: https://context7.com/teunbrand/legendry/llms.txt

Use compose_sandwich to place a middle guide, typically a color bar, between two axis guides. This is used internally by guide_colbar() and guide_colsteps(). The 'opposite' argument can specify additional guides.

```r
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = cty)) +
  guides(colour = compose_sandwich(
    middle   = "colourbar",
    text     = "axis_base",
    opposite = primitive_bracket(key = key_range_manual(
      start = c(10, 20), end = c(25, 30), name = c("A", "B")
    ))
  ))
```

--------------------------------

### Convenience Theme Wrapper (`theme_guide`)

Source: https://context7.com/teunbrand/legendry/llms.txt

Use `theme_guide` as a shorthand for styling axis and legend theme elements simultaneously within a guide's `theme` argument.

```r
red_ticks <- theme_guide(ticks = element_line(colour = "red", linewidth = 0.5))

ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  guides(
    colour = guide_colourbar(theme = red_ticks),
    x      = guide_axis(theme = red_ticks)
  )
```

```r
# Style brackets and boxes
ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot() +
  guides(x = "axis_nested") +
  theme_guide(bracket = element_line("red", linewidth = 1))
```

--------------------------------

### Manually compose an axis-like guide

Source: https://context7.com/teunbrand/legendry/llms.txt

Combine primitives like primitive_line, primitive_ticks, primitive_labels, and primitive_title to manually construct an axis-like guide. This offers fine-grained control over the appearance of guide elements.

```r
# Manually compose an axis-like guide
compose_stack(
  primitive_line(),
  primitive_ticks(bidi = TRUE),
  primitive_labels(angle = 45),
  primitive_title("My axis"),
  key = "auto"
)
```

--------------------------------

### Apply custom complete guides

Source: https://github.com/teunbrand/legendry/blob/main/README.md

Applies a custom color bar guide ('colbar') with a limited color scale and a custom axis guide ('guide_axis_base') with bidirectional ticks to the base plot.

```r
base +
  scale_colour_viridis_c(
    limits = c(NA, 30),
    guide = "colbar"
  ) +
  guides(
    x = guide_axis_base(bidi = TRUE)
  )
```

--------------------------------

### Custom Axis Guide with Minor/Log Key Support

Source: https://context7.com/teunbrand/legendry/llms.txt

Use `guide_axis_base` for bidirectional ticks, manual breaks, or logarithmic scales. It composes `primitive_line`, `primitive_ticks`, and `primitive_labels`.

```r
library(legendry)

# Bidirectional ticks + manual breaks on y
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  scale_x_continuous(
    guide = guide_axis_base(key = key_minor())   # minor ticks on x
  ) +
  scale_y_continuous(
    guide = guide_axis_base(
      key  = key_manual(c(20, 25, 30, 40)),
      bidi = TRUE                                # ticks face both ways
    )
  )
```

```r
# Logarithmic axis
ggplot(msleep, aes(bodywt, brainwt)) +
  geom_point(na.rm = TRUE) +
  scale_x_continuous(
    transform = "log10",
    guide = guide_axis_base("log")              # shorthand string
  )
```

```r
# Works in polar coordinates without changes
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()
p + coord_radial()

p + guides(x = guide_axis_base(key = key_minor()))
```

--------------------------------

### guide_colring() — Colour ring / arc guide

Source: https://context7.com/teunbrand/legendry/llms.txt

Displays a continuous colour/fill scale as a ring or arc, suitable for cyclical palettes.

```APIDOC
## guide_colring() — Colour ring / arc guide

### Description
Displays a continuous colour/fill scale as a ring or arc. Best suited for cyclical palettes.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
* `start` (numeric) - Optional - Starting angle for the arc.
* `end` (numeric) - Optional - Ending angle for the arc.
* `inner_guide` (string) - Optional - Controls the inner guide display (e.g., "none").
* `show_labels` (string) - Optional - Controls label display (e.g., "both").

### Request Example
```r
p + guides(colour = guide_colring(start = 1.25 * pi, end = 2.75 * pi))
```

### Response
Not applicable (R function)
```

--------------------------------

### Binned Colour Steps with End Caps (`gizmo_stepcap`)

Source: https://context7.com/teunbrand/legendry/llms.txt

Use `gizmo_stepcap` to create binned color steps with optional end caps for guides. Customize shape and visibility of end caps.

```r
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) + geom_point()

p + scale_colour_viridis_c(limits = c(10, 30), guide = gizmo_stepcap())
```

```r
p + scale_colour_viridis_c(
  oob = scales::oob_squish,
  guide = gizmo_stepcap(shape = "round", show = c(FALSE, TRUE))
)
```

--------------------------------

### guide_colring() - Continuous Colour Ring/Arc Guide

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_colring() to display continuous color scales as a ring or arc, suitable for cyclical palettes. Customize arc extent and tick visibility.

```r
my_pal <- c("black", "tomato", "white", "dodgerblue", "black")
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  scale_colour_gradientn(colours = my_pal)

# Full ring
p + guides(colour = "colring")
```

```r
# Arc (partial ring)
p + guides(colour = guide_colring(start = 1.25 * pi, end = 2.75 * pi))
```

```r
# No inner ticks
p + guides(colour = guide_colring(inner_guide = "none"))
```

```r
# Labels on both inner and outer axis
p + guides(colour = guide_colring(show_labels = "both"))
```

--------------------------------

### guide_axis_dendro()

Source: https://context7.com/teunbrand/legendry/llms.txt

Displays a hierarchical clustering dendrogram as an axis. This guide must be used with `scale_x_dendro()` / `scale_y_dendro()` or with manually ordered discrete limits.

```APIDOC
## guide_axis_dendro() — Dendrogram axis guide

### Description
Displays a hierarchical clustering dendrogram as an axis. Must be used with `scale_x_dendro()` / `scale_y_dendro()` or with manually ordered discrete limits.

### Usage Examples
```r
clust <- hclust(dist(scale(mtcars)), "ave")

p <- ggplot(mtcars, aes(disp, rownames(mtcars))) +
  geom_col() +
  scale_y_discrete(limits = clust$labels[clust$order])

# Basic dendrogram
p + guides(y = guide_axis_dendro(clust))

# With ticks and axis line
p + guides(y = guide_axis_dendro(clust, ticks = "ticks", axis_line = "line")) +
  theme(axis.line = element_line())

# Larger dendrogram area
p + guides(y = guide_axis_dendro(clust, space = unit(4, "cm")))

# Just the dendrogram, labels on secondary axis
p + guides(y = guide_axis_dendro(clust, labels = FALSE), y.sec = "axis")
```
```

--------------------------------

### guide_axis_base()

Source: https://context7.com/teunbrand/legendry/llms.txt

A custom axis guide that supports bidirectional ticks, custom keys (minor breaks, log ticks), subtitles, and radial coordinate systems. It is internally composed from primitive_line, primitive_ticks, and primitive_labels.

```APIDOC
## guide_axis_base() — Custom axis guide with minor/log key support

### Description
A drop-in axis replacement that supports bidirectional ticks, custom keys (minor breaks, log ticks), subtitles, and radial coordinate systems. Internally composed from `primitive_line`, `primitive_ticks`, and `primitive_labels`.

### Usage Examples
```r
library(legendry)

# Bidirectional ticks + manual breaks on y
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  scale_x_continuous(
    guide = guide_axis_base(key = key_minor())   # minor ticks on x
  ) +
  scale_y_continuous(
    guide = guide_axis_base(
      key  = key_manual(c(20, 25, 30, 40)),
      bidi = TRUE                                # ticks face both ways
    )
  )

# Logarithmic axis
ggplot(msleep, aes(bodywt, brainwt)) +
  geom_point(na.rm = TRUE) +
  scale_x_continuous(
    transform = "log10",
    guide = guide_axis_base("log")              # shorthand string
  )

# Works in polar coordinates without changes
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  scale_x_continuous(guide = guide_axis_base(key = key_minor()))
p + coord_radial()
```
```

--------------------------------

### Stack guides vertically or horizontally

Source: https://context7.com/teunbrand/legendry/llms.txt

Use compose_stack to arrange multiple guides sequentially along an axis. This function supports optional side titles for clarity. It can stack regular axes or combine axes with other primitives like bracket annotations.

```r
# Two stacked axes with side labels
ggplot() +
  geom_function(fun = dnorm, xlim = c(-3, 3)) +
  guides(x = compose_stack(
    "axis", "axis",
    side.titles = c("first", "second")
  )) +
  theme(plot.margin = margin(5.5, 5.5, 5.5, 11))
```

```r
# Stack a bracket annotation below a regular axis
ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot() +
  guides(x = compose_stack(
    "axis",
    primitive_bracket(key = "range_auto")
  ))
```

--------------------------------

### Histogram Overlay (`gizmo_histogram`)

Source: https://context7.com/teunbrand/legendry/llms.txt

Add a histogram overlay to guides using `gizmo_histogram`. Can compute histogram from plot data or use pre-computed histogram data.

```r
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() + scale_colour_viridis_c()

# Histogram from plot data
p + guides(colour = gizmo_histogram())
```

```r
# Pre-computed histogram
p + guides(colour = gizmo_histogram(hist = hist(mpg$cty, breaks = 10)))
```

--------------------------------

### Kernel Density Estimate Overlay (`gizmo_density`)

Source: https://context7.com/teunbrand/legendry/llms.txt

Overlay kernel density estimates on guides using `gizmo_density`. Can compute density from plot data, use binned displays, pre-computed densities, or custom values.

```r
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  scale_colour_viridis_c()

# KDE from plot data
p + guides(colour = gizmo_density())
```

```r
# Binned display
p + guides(colour = gizmo_density("bins"))
```

```r
# Pre-computed density
p + guides(colour = gizmo_density(density = density(mpg$cty, adjust = 0.5)))
```

```r
# Custom values for density estimation
p + guides(colour = gizmo_density(density = runif(1000, min = 5, max = 35)))
```

```r
# KDE in a sandwich composition
p + guides(colour = compose_sandwich(
  middle = gizmo_density(just = 0),  # left-aligned
  text   = "axis_base"
))
```

--------------------------------

### key_group_split Error Handling

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/key-group.md

Illustrates an error scenario where key_group_split is called with an invalid input type (a list instead of a character vector) for the guide's label.

```R
Error in `key_group_split()`:
! Cannot split the guide's label.
  i It must be a <character> vector, not a list.
```

--------------------------------

### Cross two aesthetics with a shared guide object

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_legend_cross to share a legend object between multiple aesthetics, allowing them to be displayed together. The 'swap' argument can be used to change the orientation of the legend.

```r
my_guide <- guide_legend_cross(key = "auto", title = "My title")
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = drv, shape = factor(year))) +
  guides(colour = my_guide, shape = my_guide)
```

```r
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = paste(year, drv))) +
  guides(colour = guide_legend_cross(swap = TRUE))
```

--------------------------------

### Rotate text along each side using position_text()

Source: https://context7.com/teunbrand/legendry/llms.txt

Utilizes `position_text()` to define text angles for different positions, useful for rotating labels in guides.

```r
position_text(angle = c(0, -90, 0, 90), hjust = 0.5)
```

--------------------------------

### Dendrogram Axis Guide for Hierarchical Clustering

Source: https://context7.com/teunbrand/legendry/llms.txt

Use `guide_axis_dendro` with `scale_x_dendro()` or manually ordered discrete scales to display a hierarchical clustering dendrogram as an axis. Options include adding ticks, axis lines, and adjusting spacing.

```r
clust <- hclust(dist(scale(mtcars)), "ave")

p <- ggplot(mtcars, aes(disp, rownames(mtcars))) +
  geom_col() +
  scale_y_discrete(limits = clust$labels[clust$order])

# Basic dendrogram
p + guides(y = guide_axis_dendro(clust))
```

```r
# With ticks and axis line
p + guides(y = guide_axis_dendro(clust, ticks = "ticks", axis_line = "line")) +
  theme(axis.line = element_line())
```

```r
# Larger dendrogram area
p + guides(y = guide_axis_dendro(clust, space = unit(4, "cm")))
```

```r
# Just the dendrogram, labels on secondary axis
p + guides(y = guide_axis_dendro(clust, labels = FALSE), y.sec = "axis")
```

--------------------------------

### guide_colsteps() - Binned Colour Steps with Caps

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_colsteps() for binned color scales that support caps and even-step display. It's a binned variant of guide_colbar().

```r
p <- ggplot(mpg, aes(displ, hwy)) + geom_point(aes(colour = cty))

# Default steps with caps
p + scale_colour_viridis_b(limits = c(10, NA), guide = "colsteps")
```

```r
# Evenly spaced steps regardless of break spacing
p + scale_colour_viridis_b(
  limits = c(10, 30), breaks = c(10, 20, 25),
  guide = guide_colsteps(key = key_bins(even.steps = TRUE))
)
```

```r
# Ticks on both sides
p + scale_colour_viridis_b(
  guide = guide_colsteps(
    first_guide  = "axis_base",
    second_guide = "axis_base"
  )
)
```

--------------------------------

### Handle Mismatched Label and Color Sizes in guide_legend_manual()

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/guide-legend-manual.md

If the size of `labels` does not match the size of `colour`, guide_legend_manual() will produce an error indicating the mismatch. Ensure these arguments have compatible lengths.

```r
guide_legend_manual(c("foo", "bar"), colour = c("red", "green", "blue"))
```

--------------------------------

### Specialty Keys for Sequences and Bins

Source: https://context7.com/teunbrand/legendry/llms.txt

Use `key_sequence` to generate a specified number of colors for a gradient, and `key_bins` to create evenly spaced bin intervals for scales.

```r
template <- scale_fill_viridis_c(limits = c(0, 10), breaks = c(2, 4, 6, 8))

key_sequence(n = 15)(template)   # 15-colour gradient sequence
```

```r
key_bins(even.steps = TRUE)(template)  # evenly spaced bin intervals
```

--------------------------------

### guide_colbar() - Continuous Colour Bar with Caps

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_colbar() for continuous color scales that display caps for out-of-bounds values. It's a drop-in replacement for guide_colourbar().

```r
p <- ggplot(mpg, aes(displ, hwy)) + geom_point(aes(colour = cty))

# Caps appear automatically when data exceeds limits
p + scale_colour_viridis_c(limits = c(10, NA), guide = "colbar")
```

```r
# Show how oob values are handled (squish = map to nearest limit colour)
p + scale_colour_viridis_c(
  limits = c(10, NA), oob = scales::oob_squish,
  guide = "colbar"
)
```

```r
# Round caps
p + scale_colour_viridis_c(
  limits = c(10, 30), oob = scales::oob_squish,
  guide = guide_colbar(shape = "round")
)
```

```r
# One-sided ticks only
p + scale_colour_viridis_c(guide = guide_colbar(second_guide = "none"))
```

```r
# Log ticks on a colour bar
ggplot(msleep, aes(sleep_total, sleep_rem)) + 
  geom_point(aes(colour = bodywt), na.rm = TRUE) +
  scale_colour_viridis_c(
    transform = "log10",
    guide = guide_colbar(key = "log")
  )
```

--------------------------------

### Standard Key Extraction

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/aaa.md

Demonstrates the standard extraction of a key from data, showing the resulting structure and values.

```R
standard_extract_key(data.frame(x = 1:3, value = 1:3, label = 1:3), key = "x")
```

--------------------------------

### guide_circles() - Circle Size Legend

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_circles() to represent size aesthetics with nested or stacked circles, ideal for geom_point() with round shapes. Customize orientation and label placement.

```r
p <- ggplot(mtcars, aes(disp, mpg)) +
  geom_point(aes(size = hp), alpha = 0.3) +
  scale_size_area(max_size = 30, limits = c(0, NA), breaks = c(0, 25, 100, 250))

# Standard vertical orientation
p + guides(size = "circles")
```

```r
# Horizontal, labels at bottom
p + guides(size = guide_circles(vjust = 0.5, hjust = 0, text_position = "bottom"))
```

```r
# Labels on top of circles with background mask
p + guides(size = guide_circles(text_position = "ontop", clip_text = TRUE))
```

```r
# Red override colour
p + guides(size = guide_circles(override.aes = aes(colour = "red")))
```

--------------------------------

### Group Keys for Splitting and Mapping

Source: https://context7.com/teunbrand/legendry/llms.txt

Employ `key_group_split` to split compound labels into groups based on a separator, and `key_group_lut` to create a lookup table for grouping.

```r
# Split compound labels to discover groups
values   <- c("group A:value 1", "group A:value 2", "group B:value 1")
template <- scale_colour_hue(limits = values)
key_group_split(sep = ":")(template)
```

```r
# Look-up table
key_group_lut(msleep$name, msleep$order)(
  scale_colour_hue(limits = msleep$name[1:5])
)
```

--------------------------------

### guide_legend_base() — Legend with custom layout design

Source: https://context7.com/teunbrand/legendry/llms.txt

A flexible legend function that allows custom cell layouts specified via a string or matrix.

```APIDOC
## guide_legend_base() — Legend with custom layout design

### Description
Mirrors `guide_legend()` but adds a `design` argument for arbitrary cell layouts, specified as a string or matrix.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
* `design` (string or matrix) - Required - Specifies the layout of the legend cells. Characters represent cells, newlines represent rows, and '#' represents empty cells.

### Request Example
```r

design <- "
  123
  213
  321
"
p + guides(shape = guide_legend_base(design = design))
```

### Response
Not applicable (R function)
```

--------------------------------

### guide_colbar() — Colour bar with caps

Source: https://context7.com/teunbrand/legendry/llms.txt

Creates a continuous colour/fill legend with triangular caps at the ends to indicate out-of-bounds values. It serves as a replacement for guide_colourbar().

```APIDOC
## guide_colbar() — Colour bar with caps

### Description
A continuous colour/fill legend that displays triangular (or custom-shaped) caps at either end to signal out-of-bounds values. Drop-in replacement for `guide_colourbar()`.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
* `shape` (string) - Optional - Shape of the caps (e.g., "round").
* `second_guide` (string) - Optional - Controls the display of the second guide (e.g., "none").

### Request Example
```r
p + scale_colour_viridis_c(limits = c(10, NA), guide = guide_colbar(shape = "round"))
```

### Response
Not applicable (R function)
```

--------------------------------

### Create scale-independent manual legends

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_legend_manual for legends with user-specified labels and aesthetics, independent of any scale. This is useful for custom annotation legends. It supports inline aesthetics and multiple layer types.

```r
p <- ggplot(mtcars, aes(disp, mpg)) + geom_point()

# Inline aesthetics
p + guides(
  some_name = guide_legend_manual(
    label  = c("Bars", "Points"),
    colour = c(NA, "black"),
    fill   = c("grey40", NA),
    layers = geom_col()
  )
)
```

```r
# Multiple layer types
p + guides(
  annotation = guide_legend_manual(
    label  = c("foo", "bar"),
    colour = c("tomato", "dodgerblue"),
    fill   = NA,
    layers = list(geom_col(), geom_point())
  )
)
```

--------------------------------

### guide_legend_base() - Custom Layout Legend

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_legend_base() for legends with custom cell layouts specified via a string or matrix design. It mirrors guide_legend() but adds layout flexibility.

```r
p <- ggplot(data.frame(x = 1:3, type = c("tic", "tac", "toe"))) +
  aes(x, x, shape = type) +
  geom_point(na.rm = TRUE) +
  scale_shape_manual(values = c(1, 4, NA))

# String design: each character = cell, newlines = rows, '#' = empty
design <- "
  123
  213
  321
"
p + guides(shape = guide_legend_base(design = design))
```

```r
# With empty cells
p + guides(shape = guide_legend_base(design = "
  #2#
  1#3
"))
```

--------------------------------

### Configure color bar with optional end caps

Source: https://context7.com/teunbrand/legendry/llms.txt

Use gizmo_barcap for color bars, optionally with end caps when out-of-bounds data exists. Customization includes shape, visibility of caps, size, and theme adjustments for elements like legend key height.

```r
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) + geom_point()

# Caps when out-of-bounds data exists
p + scale_colour_viridis_c(limits = c(10, 30), guide = gizmo_barcap())
```

```r
# Arch-shaped cap, only at upper end, taller bar
p + scale_colour_viridis_c(
  oob = scales::oob_squish,
  guide = gizmo_barcap(
    shape = "arch", show = c(FALSE, TRUE),
    size  = unit(2, "cm"),
    theme = theme(legend.key.height = unit(4, "cm"))
  )
)
```

--------------------------------

### Create a base ggplot

Source: https://github.com/teunbrand/legendry/blob/main/README.md

Sets up a basic ggplot with mpg dataset, mapping displacement to highway miles per gallon and color to city miles per gallon. Includes custom axis labels and theme.

```r
library(legendry)
#> Loading required package: ggplot2

base <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  labs(
    x = "Engine displacement",
    y = "Highway miles per gallon",
    col = "City miles\nper gallon"
  ) +
  theme(axis.line = element_line())
```

--------------------------------

### Apply box-style and fence-style range annotations

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_axis_nested with type="box" for box-style range annotations or type="fence" for fence-style annotations. The theme can be used to customize elements like fence posts and rails.

```r
# Box-style range annotations
ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot() +
  guides(x = guide_axis_nested(type = "box"))
```

```r
# Fence with separate post and rail styling
ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot() +
  guides(x = guide_axis_nested(type = "fence")) +
  theme_guide(
    fence.post = element_line("tomato"),
    fence.rail = element_line("dodgerblue")
  )
```

--------------------------------

### Standard Keys for Ticks and Labels

Source: https://context7.com/teunbrand/legendry/llms.txt

Functions like `key_auto`, `key_manual`, `key_map`, `key_minor`, `key_log`, and `key_none` control how tick marks and labels are generated for scales.

```r
# Auto key (major breaks from scale)
key_auto()(scale_x_continuous(limits = c(0, 10)))
```

```r
# Minor breaks key
key_minor()(scale_x_continuous(limits = c(0, 10)))
```

```r
# Log ticks key
key_log()(scale_x_continuous(transform = "log10", limits = c(0.1, 10)))
```

```r
# Manual values
key_manual(
  aesthetic = 1:5,
  label     = c("one", "two", "three", "four", "five")
)
```

```r
# From data frame
key_map(ToothGrowth, aesthetic = unique(supp))
```

```r
# Empty (suppress all ticks)
key_none()
```

--------------------------------

### guide_circles() — Circle size legend

Source: https://context7.com/teunbrand/legendry/llms.txt

Represents size aesthetics using nested concentric or stacked circles, ideal for point geoms with round shapes.

```APIDOC
## guide_circles() — Circle size legend

### Description
Displays size aesthetics as nested concentric or stacked circles. Designed for `geom_point()` with round shapes.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
* `vjust` (numeric) - Optional - Vertical justification for labels.
* `hjust` (numeric) - Optional - Horizontal justification for labels.
* `text_position` (string) - Optional - Position of the text labels (e.g., "bottom", "ontop").
* `clip_text` (boolean) - Optional - Whether to clip text.
* `override.aes` (list) - Optional - Aesthetics to override for the circles (e.g., `aes(colour = "red")`).

### Request Example
```r
p + guides(size = guide_circles(text_position = "ontop", clip_text = TRUE, override.aes = aes(colour = "red")))
```

### Response
Not applicable (R function)
```

--------------------------------

### guide_legend_group() — Grouped legend with sub-titles

Source: https://context7.com/teunbrand/legendry/llms.txt

Organizes legend entries into named groups, each with its own sub-title, allowing for better organization of complex legends.

```APIDOC
## guide_legend_group() — Grouped legend with sub-titles

### Description
Organises legend entries into named groups, each with its own sub-title. Groups can be inferred by splitting labels or provided via a look-up table.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
* `key` (object) - Optional - A look-up table for grouping labels.
* `nrow` (integer) - Optional - Number of rows for the legend layout.

### Request Example
```r
# Look-up table (can cover more species than currently plotted)
lut <- key_group_lut(msleep$name, msleep$order)
p + aes(colour = name) + guides(colour = guide_legend_group(key = lut, nrow = 1))
```

### Response
Not applicable (R function)
```

--------------------------------

### Dendrogram Scales (`scale_x_dendro`, `scale_y_dendro`)

Source: https://context7.com/teunbrand/legendry/llms.txt

Create dendrogram scales for axes by reordering limits according to hierarchical clustering. Defaults to `guide_axis_dendro()`.

```r
car_clust <- hclust(dist(scale(mtcars)), "ave")
var_clust <- hclust(dist(scale(t(mtcars))), "ave")

long_mtcars <- data.frame(
  car   = rownames(mtcars)[row(mtcars)],
  var   = colnames(mtcars)[col(mtcars)],
  value = as.vector(scale(mtcars))
)

# Heatmap with dendrograms on both axes
ggplot(long_mtcars, aes(var, car, fill = value)) +
  geom_tile() +
  scale_x_dendro(var_clust) +
  scale_y_dendro(car_clust)
```

--------------------------------

### Handle Invalid Layer Input in guide_legend_manual()

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/guide-legend-manual.md

When `layers` is not a list of `LayerInstance` objects, guide_legend_manual() throws an informative error. Ensure all elements in the `layers` list are valid.

```r
guide_legend_manual("foo", layers = list("invalid input"))
```

--------------------------------

### guide_legend_cross() - Cross/Interaction Legend

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_legend_cross() to display the crossing of two variables as a 2-D grid of keys, with optional row and column subtitles. Useful for interaction effects.

```r
# Single aesthetic using pasted compound variable
ggplot(mpg, aes(displ, hwy)) +
  geom_point(aes(colour = paste(year, drv))) +
  guides(colour = "legend_cross")
```

--------------------------------

### guide_legend_cross() — Cross / interaction legend

Source: https://context7.com/teunbrand/legendry/llms.txt

Displays the interaction of two variables as a 2-D grid of keys, with optional row and column subtitles.

```APIDOC
## guide_legend_cross() — Cross / interaction legend

### Description
Displays the crossing of two variables as a 2-D grid of keys, with optional row and column subtitles.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented for this basic usage.

### Request Example
```r
# Single aesthetic using pasted compound variable
ggplot(mpg, aes(displ, hwy)) + geom_point(aes(colour = paste(year, drv))) + guides(colour = "legend_cross")
```

### Response
Not applicable (R function)
```

--------------------------------

### Rejecting Non-ggplot Objects

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/guide-axis-plot.md

guide_axis_plot() expects a ggplot object. Providing a string or other non-ggplot type will result in an error.

```R
guide_axis_plot(plot = "foobar")
```

--------------------------------

### Rejecting Non-linear Coordinate Systems

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/guide-axis-plot.md

guide_axis_plot() does not support non-linear coordinate systems. Use a linear system like `coord_cartesian()` or `coord_fixed()`.

```R
guide_axis_plot(plot + coord_radial())
```

--------------------------------

### Rejecting Faceted Plots

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/guide-axis-plot.md

guide_axis_plot() does not support plots with facets. Only `facet_null()` is compatible.

```R
guide_axis_plot(plot + facet_wrap(~cyl))
```

--------------------------------

### Red text for all positions using position_text()

Source: https://context7.com/teunbrand/legendry/llms.txt

Applies a uniform red color to text elements at all positions using `position_text()`, demonstrating color customization.

```r
position_text(angle = c(0, -90, 180, 90), colour = "red")
```

--------------------------------

### Range Keys for Defining Intervals

Source: https://context7.com/teunbrand/legendry/llms.txt

Use `key_range_auto`, `key_range_manual`, and `key_range_map` to define and manage ranges for discrete or continuous scales, often used with compound labels.

```r
# Auto-infer ranges by splitting discrete labels on separator
template <- scale_x_discrete(limits = c("A 1", "B 1", "C&1", "D&2", "E&2"))
key_range_auto(sep = "&")(template)
```

```r
# Manual ranges
key_range_manual(
  start = c(1, 5, 10),
  end   = c(4, 15, 11),
  level = c(0, 2, 1),
  name  = c("A", "B", "C")
)
```

```r
# From a data frame
key_range_map(presidential, start = start, end = end, name = name)
```

--------------------------------

### guide_legend_group() - Grouped Legend with Sub-titles

Source: https://context7.com/teunbrand/legendry/llms.txt

Use guide_legend_group() to organize legend entries into named groups with sub-titles. Groups can be inferred from labels or provided via a lookup table.

```r
df <- msleep[c(9, 28, 11, 5, 34, 54, 64, 24, 53), ]
p  <- ggplot(df) +
  aes(bodywt, awake, colour = paste(order, name)) +
  geom_point()

# Auto-infer groups from label prefix
p + guides(colour = "legend_group")
```

```r
# Look-up table (can cover more species than currently plotted)
lut <- key_group_lut(msleep$name, msleep$order)
p + aes(colour = name) +
  guides(colour = guide_legend_group(key = lut))
```

```r
# One row per group, horizontal layout
p + guides(colour = guide_legend_group(nrow = 1))
```

```r
# Style sub-titles
p + guides(colour = "legend_group") +
  theme(
    legendry.legend.subtitle.position = "left",
    legendry.legend.subtitle = element_text(
      hjust = 1, vjust = 1, size = rel(0.9),
      margin = margin(t = 5.5, r = 5.5)
    )
  )
```

--------------------------------

### guide_axis_nested()

Source: https://context7.com/teunbrand/legendry/llms.txt

Annotates a position scale with range brackets, boxes, or fences inferred from label nesting or provided manually. It combines primitive_line, primitive_ticks, primitive_labels, and a range primitive.

```APIDOC
## guide_axis_nested() — Nested/grouped axis annotations

### Description
Annotates a position scale with range brackets, boxes, or fences inferred from label nesting (e.g. `interaction()` output) or provided manually. Combines `primitive_line`, `primitive_ticks`, `primitive_labels`, and a range primitive.

### Usage Examples
```r
# Infer nesting from interaction labels (default: bracket style)
p <- ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot()

p + guides(x = "axis_nested")

# Curvy brackets
p + guides(x = guide_axis_nested(bracket = "curvy"))

# Box style with styling
p + guides(x = guide_axis_nested(type = "box")) +
  theme_guide(box = element_rect("limegreen", "forestgreen"))

# Fence style
p + guides(x = guide_axis_nested(type = "fence", rail = "inner")) +
  theme_guide(
    fence.post = element_line("tomato"),
    fence.rail = element_line("dodgerblue")
  )

# Manual range annotation over a regular axis
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  guides(x = guide_axis_nested(
    key         = key_range_manual(start = 2:3, end = 5:6, name = c("A", "B")),
    regular_key = key_manual(c(2, 2.5, 3, 5, 7))
  ))
```
```

--------------------------------

### Nested/Grouped Axis Annotations with Brackets or Boxes

Source: https://context7.com/teunbrand/legendry/llms.txt

Employ `guide_axis_nested` to annotate scales with range brackets, boxes, or fences based on label nesting or manual ranges. Supports different bracket styles and custom theming.

```r
# Infer nesting from interaction labels (default: bracket style)
p <- ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot()

p + guides(x = "axis_nested")
```

```r
# Curvy brackets
p + guides(x = guide_axis_nested(bracket = "curvy"))
```

```r
# Box style with styling
p + guides(x = guide_axis_nested(type = "box")) +
  theme_guide(box = element_rect("limegreen", "forestgreen"))
```

```r
# Fence style
p + guides(x = guide_axis_nested(type = "fence", rail = "inner")) +
  theme_guide(
    fence.post = element_line("tomato"),
    fence.rail = element_line("dodgerblue")
  )
```

```r
# Manual range annotation over a regular axis
ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  guides(x = guide_axis_nested(
    key         = key_range_manual(start = 2:3, end = 5:6, name = c("A", "B")),
    regular_key = key_manual(c(2, 2.5, 3, 5, 7))
  ))
```

--------------------------------

### Apply range bracket annotations

Source: https://context7.com/teunbrand/legendry/llms.txt

Use primitive_bracket for range bracket annotations. It supports auto-inferred ranges or user-defined keys, and can specify bracket shapes like 'square'. This primitive is often used within compositions.

```r
key <- key_range_manual(c(2, 4), c(5, 6), c("Low", "High"))

ggplot(mpg, aes(interaction(drv, year), displ)) +
  geom_point() +
  guides(
    x.sec = primitive_bracket(),                # auto-inferred ranges
    y.sec = primitive_bracket(key = key, bracket = "square")
  )
```

--------------------------------

### guide_axis_plot()

Source: https://context7.com/teunbrand/legendry/llms.txt

Embeds a separate ggplot as an axis, sharing the position scale of the main plot. This is ideal for marginal density or box plots. It is an experimental feature.

```APIDOC
## guide_axis_plot() — Side-plot axis (experimental)

### Description
Embeds a separate ggplot as an axis, sharing the position scale of the main plot. Ideal for marginal density or box plots.

### Usage Examples
```r
main <- ggplot(mpg, aes(displ, hwy, colour = drv)) + geom_point()

x_density <- ggplot(mpg, aes(displ, fill = drv)) + geom_density(alpha = 0.7)
y_box     <- ggplot(mpg, aes(drv, hwy, colour = drv)) + geom_boxplot()

main + guides(
  x = guide_axis_plot(x_density),
  y = guide_axis_plot(y_box, size = unit(4, "cm"))
)

# Include the fill legend from the side plot
main + guides(
  x = guide_axis_plot(x_density, theme = NULL),  # NULL keeps side-plot legends
  y = guide_axis_plot(y_box)
)

# Recursive side-plots
main + guides(x = guide_axis_plot(
  main + guides(x = guide_axis_plot(x_density))
))
```
```

--------------------------------

### Side-Plot Axis for Marginal Plots

Source: https://context7.com/teunbrand/legendry/llms.txt

Embed a separate ggplot as an axis using `guide_axis_plot`. This is experimental and ideal for marginal density or box plots, sharing the main plot's position scale. Side-plot legends can be included by setting `theme = NULL`.

```r
main <- ggplot(mpg, aes(displ, hwy, colour = drv)) + geom_point()

x_density <- ggplot(mpg, aes(displ, fill = drv)) + geom_density(alpha = 0.7)
y_box     <- ggplot(mpg, aes(drv, hwy, colour = drv)) + geom_boxplot()

main + guides(
  x = guide_axis_plot(x_density),
  y = guide_axis_plot(y_box, size = unit(4, "cm"))
)
```

```r
# Include the fill legend from the side plot
main + guides(
  x = guide_axis_plot(x_density, theme = NULL),  # NULL keeps side-plot legends
  y = guide_axis_plot(y_box)
)
```

```r
# Recursive side-plots
main + guides(x = guide_axis_plot(
  main + guides(x = guide_axis_plot(x_density))
))
```

--------------------------------

### Custom fence colours in ggplot2

Source: https://context7.com/teunbrand/legendry/llms.txt

Applies custom colors to fence posts and rails in a ggplot2 boxplot using legendry's theme elements.

```r
ggplot(mpg, aes(interaction(drv, cyl), hwy)) +
  geom_boxplot() +
  guides(x = guide_axis_nested(type = "fence")) +
  theme_guide(
    fence.post = element_line(colour = "tomato"),
    fence.rail = element_line(colour = "dodgerblue")
  )
```

--------------------------------

### Error with Non-linear Coordinates in ggplot_build

Source: https://github.com/teunbrand/legendry/blob/main/tests/testthat/_snaps/guide-axis-plot.md

When using `ggplot_build()`, non-linear coordinates will also cause an error with guide_axis_plot().

```R
ggplot_build(wrong_plot)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.