Rename *_of() API to trailing-underscore convention with helper wrappers; move padding to g2()

.github/copilot-instructions.md

@@ -121,17 +121,17 @@ you cannot solve it.
 - `gglite.R` - Core: package doc, CDN URLs, `g2()`, `encode()`,
   `annotate_df()`
 - `mark.R` - All 35 mark (geometry) functions
-- `scale.R` - `scale_of()`
-- `coordinate.R` - `coordinate()`, `coord_transpose()`
+- `scale.R` - `scale_()` and helpers (`scale_x()`, `scale_y()`, etc.)
+- `coordinate.R` - `coord_()`, `coord_transpose()`
 - `interact.R` - `interact()`
-- `theme.R` - `theme_of()`
-- `transform.R` - `transform_of()`
+- `theme.R` - `theme_()` and theme shortcuts
+- `transform.R` - `transform_()`
 - `facet.R` - `facet_rect()`, `facet_circle()`
 - `animate.R` - `animate()`
-- `component.R` - `axis_of()`, `legend_of()`, `title_of()`, `tooltip_of()`,
-  `labels_of()`, `style_mark()`, `slider_of()`, `scrollbar_of()`
-- `render.R` - `build_config()`, `chart_html()`, `preview()`, `print.g2()`,
-  `knit_print.g2()`, `record_print.g2()`, `render_shiny()`
+- `component.R` - `axis_()`, `legend_()`, `title_()`, `tooltip_()`,
+  `labels_()`, `style_mark()`, `slider_()`, `scrollbar_()` and helpers
+- `render.R` - `build_config()`, `chart_html()`, `print.g2()`,
+  `knit_print.g2()`, `record_print.g2()`
 
 **Tests** (`tests/`):
 - `test-all.R` - Entry point
@@ -226,7 +226,7 @@ component functions:
 ```r
 g2(mtcars, x = 'mpg', y = 'hp') |>
   mark_point() |>
-  scale_of('x', type = 'log') |>
-  theme_of('dark') |>
-  title_of('Motor Trend Cars')
+  scale_x(type = 'log') |>
+  theme_('dark') |>
+  title_('Motor Trend Cars')
 ```

.gitignore

@@ -3,5 +3,5 @@ package.json
 package-lock.json
 *.Rcheck/
 test-all.mjs
-gglite_*.tar.gz
+*.tar.gz
 .Rproj.user

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: gglite
 Title: Lightweight Data Visualization via the Grammar of Graphics
-Version: 0.0.4
+Version: 0.0.5
 Authors@R: person("Yihui", "Xie", role = c("aut", "cre"), email = "xie@yihui.name",
     comment = c(ORCID = "0000-0003-0645-5666"))
 Description: A lightweight R interface to the AntV G2 JavaScript visualization

NAMESPACE

@@ -3,24 +3,31 @@
 S3method(print,g2)
 S3method(record_print,g2)
 export(animate)
-export(axis_of)
+export(axis_)
+export(axis_x)
+export(axis_y)
 export(chart_html)
+export(coord_)
 export(coord_helix)
 export(coord_parallel)
 export(coord_polar)
 export(coord_radar)
 export(coord_radial)
 export(coord_theta)
 export(coord_transpose)
-export(coordinate)
 export(encode)
 export(facet_circle)
 export(facet_rect)
 export(g2)
 export(g2Output)
 export(interact)
-export(labels_of)
-export(legend_of)
+export(labels_)
+export(legend_)
+export(legend_color)
+export(legend_opacity)
+export(legend_shape)
+export(legend_size)
+export(mark_)
 export(mark_area)
 export(mark_box)
 export(mark_boxplot)
@@ -56,20 +63,29 @@ export(mark_tree)
 export(mark_treemap)
 export(mark_vector)
 export(mark_word_cloud)
-export(padding_of)
 export(renderG2)
-export(scale_of)
-export(scrollbar_of)
-export(slider_of)
+export(scale_)
+export(scale_color)
+export(scale_opacity)
+export(scale_shape)
+export(scale_size)
+export(scale_x)
+export(scale_y)
+export(scrollbar_)
+export(scrollbar_x)
+export(scrollbar_y)
+export(slider_)
+export(slider_x)
+export(slider_y)
 export(style_mark)
+export(theme_)
 export(theme_academy)
 export(theme_classic)
 export(theme_classicDark)
 export(theme_dark)
 export(theme_light)
-export(theme_of)
-export(title_of)
-export(tooltip_of)
-export(transform_of)
+export(title_)
+export(tooltip_)
+export(transform_)
 importFrom(utils,modifyList)
 importFrom(xfun,record_print)

R/component.R

@@ -1,25 +1,3 @@
-#' Set Chart Padding
-#'
-#' Set padding around the chart plotting area. This is useful when axis
-#' labels or titles are cut off.
-#'
-#' @param chart A `g2` object.
-#' @param top,right,bottom,left Padding in pixels for each side.
-#' @return The modified `g2` object.
-#' @export
-#' @examples
-#' g2(mtcars, x = 'mpg', y = 'hp') |>
-#'   mark_point() |>
-#'   padding_of(top = 30)
-padding_of = function(chart, top = NULL, right = NULL, bottom = NULL,
-                      left = NULL) {
-  if (!is.null(top)) chart$padding$paddingTop = top
-  if (!is.null(right)) chart$padding$paddingRight = right
-  if (!is.null(bottom)) chart$padding$paddingBottom = bottom
-  if (!is.null(left)) chart$padding$paddingLeft = left
-  chart
-}
-
 #' Configure an Axis
 #'
 #' Customise the axis for a positional channel (`'x'` or `'y'`). Set to
@@ -34,9 +12,9 @@ padding_of = function(chart, top = NULL, right = NULL, bottom = NULL,
 #' @examples
 #' g2(mtcars, x = 'mpg', y = 'hp') |>
 #'   mark_point() |>
-#'   axis_of('x', title = 'Miles per Gallon') |>
-#'   axis_of('y', title = 'Horsepower')
-axis_of = function(chart, channel, ...) {
+#'   axis_('x', title = 'Miles per Gallon') |>
+#'   axis_('y', title = 'Horsepower')
+axis_ = function(chart, channel, ...) {
   args = list(...)
   if (length(args) == 1 && is.logical(args[[1]])) {
     chart$axes[[channel]] = args[[1]]
@@ -46,6 +24,26 @@ axis_of = function(chart, channel, ...) {
   chart
 }
 
+#' Configure the X Axis
+#'
+#' @inheritParams axis_
+#' @export
+#' @examples
+#' g2(mtcars, x = 'mpg', y = 'hp') |>
+#'   mark_point() |>
+#'   axis_x(title = 'Miles per Gallon')
+axis_x = function(chart, ...) axis_(chart, 'x', ...)
+
+#' Configure the Y Axis
+#'
+#' @inheritParams axis_
+#' @export
+#' @examples
+#' g2(mtcars, x = 'mpg', y = 'hp') |>
+#'   mark_point() |>
+#'   axis_y(title = 'Horsepower')
+axis_y = function(chart, ...) axis_(chart, 'y', ...)
+
 #' Configure a Legend
 #'
 #' Customise the legend for a visual channel (`'color'`, `'size'`, `'shape'`,
@@ -60,8 +58,8 @@ axis_of = function(chart, channel, ...) {
 #' @examples
 #' g2(iris, x = 'Sepal.Width', y = 'Sepal.Length', color = 'Species') |>
 #'   mark_point() |>
-#'   legend_of('color', position = 'right')
-legend_of = function(chart, channel, ...) {
+#'   legend_('color', position = 'right')
+legend_ = function(chart, channel, ...) {
   args = list(...)
   if (length(args) == 1 && is.logical(args[[1]])) {
     chart$legends[[channel]] = args[[1]]
@@ -71,6 +69,46 @@ legend_of = function(chart, channel, ...) {
   chart
 }
 
+#' Configure the Color Legend
+#'
+#' @inheritParams legend_
+#' @export
+#' @examples
+#' g2(iris, x = 'Sepal.Width', y = 'Sepal.Length', color = 'Species') |>
+#'   mark_point() |>
+#'   legend_color(position = 'right')
+legend_color = function(chart, ...) legend_(chart, 'color', ...)
+
+#' Configure the Size Legend
+#'
+#' @inheritParams legend_
+#' @export
+#' @examples
+#' g2(mtcars, x = 'mpg', y = 'hp', size = 'wt') |>
+#'   mark_point() |>
+#'   legend_size(position = 'bottom')
+legend_size = function(chart, ...) legend_(chart, 'size', ...)
+
+#' Configure the Shape Legend
+#'
+#' @inheritParams legend_
+#' @export
+#' @examples
+#' g2(iris, x = 'Sepal.Width', y = 'Sepal.Length', shape = 'Species') |>
+#'   mark_point() |>
+#'   legend_shape(position = 'bottom')
+legend_shape = function(chart, ...) legend_(chart, 'shape', ...)
+
+#' Configure the Opacity Legend
+#'
+#' @inheritParams legend_
+#' @export
+#' @examples
+#' g2(mtcars, x = 'mpg', y = 'hp', opacity = 'wt') |>
+#'   mark_point() |>
+#'   legend_opacity(position = 'bottom')
+legend_opacity = function(chart, ...) legend_(chart, 'opacity', ...)
+
 #' Set the Chart Title
 #'
 #' @param chart A `g2` object.
@@ -81,8 +119,8 @@ legend_of = function(chart, channel, ...) {
 #' @examples
 #' g2(mtcars, x = 'mpg', y = 'hp') |>
 #'   mark_point() |>
-#'   title_of('Motor Trend Cars', subtitle = 'mpg vs hp')
-title_of = function(chart, text, ...) {
+#'   title_('Motor Trend Cars', subtitle = 'mpg vs hp')
+title_ = function(chart, text, ...) {
   dots = list(...)
   if (length(dots)) {
     chart$chart_title = c(list(title = text), dots)
@@ -105,8 +143,8 @@ title_of = function(chart, text, ...) {
 #' @examples
 #' g2(mtcars, x = 'mpg', y = 'hp') |>
 #'   mark_point() |>
-#'   tooltip_of(crosshairs = TRUE)
-tooltip_of = function(chart, ...) {
+#'   tooltip_(crosshairs = TRUE)
+tooltip_ = function(chart, ...) {
   args = list(...)
   if (length(args) == 1 && is.logical(args[[1]])) {
     chart$tooltip_config = args[[1]]
@@ -130,8 +168,8 @@ tooltip_of = function(chart, ...) {
 #' df = data.frame(x = c('A', 'B', 'C'), y = c(3, 7, 2))
 #' g2(df, x = 'x', y = 'y') |>
 #'   mark_interval() |>
-#'   labels_of(text = 'y', position = 'inside')
-labels_of = function(chart, ...) {
+#'   labels_(text = 'y', position = 'inside')
+labels_ = function(chart, ...) {
   n = length(chart$layers)
   if (n == 0) stop('add a mark before setting labels')
   chart$layers[[n]]$labels = c(chart$layers[[n]]$labels, list(list(...)))
@@ -168,14 +206,34 @@ style_mark = function(chart, ...) {
 #' @examples
 #' g2(mtcars, x = 'mpg', y = 'hp') |>
 #'   mark_point() |>
-#'   slider_of('x')
-slider_of = function(chart, channel, ...) {
+#'   slider_('x')
+slider_ = function(chart, channel, ...) {
   if (is.null(chart$sliders)) chart$sliders = list()
   args = list(...)
   chart$sliders[[channel]] = if (length(args)) args else TRUE
   chart
 }
 
+#' Add an X Slider
+#'
+#' @inheritParams slider_
+#' @export
+#' @examples
+#' g2(mtcars, x = 'mpg', y = 'hp') |>
+#'   mark_point() |>
+#'   slider_x()
+slider_x = function(chart, ...) slider_(chart, 'x', ...)
+
+#' Add a Y Slider
+#'
+#' @inheritParams slider_
+#' @export
+#' @examples
+#' g2(mtcars, x = 'mpg', y = 'hp') |>
+#'   mark_point() |>
+#'   slider_y()
+slider_y = function(chart, ...) slider_(chart, 'y', ...)
+
 #' Add a Scrollbar
 #'
 #' @param chart A `g2` object.
@@ -187,10 +245,32 @@ slider_of = function(chart, channel, ...) {
 #' df = data.frame(x = 1:100, y = cumsum(rnorm(100)))
 #' g2(df, x = 'x', y = 'y') |>
 #'   mark_line() |>
-#'   scrollbar_of('x')
-scrollbar_of = function(chart, channel, ...) {
+#'   scrollbar_('x')
+scrollbar_ = function(chart, channel, ...) {
   if (is.null(chart$scrollbars)) chart$scrollbars = list()
   args = list(...)
   chart$scrollbars[[channel]] = if (length(args)) args else TRUE
   chart
 }
+
+#' Add an X Scrollbar
+#'
+#' @inheritParams scrollbar_
+#' @export
+#' @examples
+#' df = data.frame(x = 1:100, y = cumsum(rnorm(100)))
+#' g2(df, x = 'x', y = 'y') |>
+#'   mark_line() |>
+#'   scrollbar_x()
+scrollbar_x = function(chart, ...) scrollbar_(chart, 'x', ...)
+
+#' Add a Y Scrollbar
+#'
+#' @inheritParams scrollbar_
+#' @export
+#' @examples
+#' df = data.frame(x = 1:100, y = cumsum(rnorm(100)))
+#' g2(df, x = 'x', y = 'y') |>
+#'   mark_line() |>
+#'   scrollbar_y()
+scrollbar_y = function(chart, ...) scrollbar_(chart, 'y', ...)