Add Quarto and Jupyter (R kernel) rendering support (#39)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: yihui <163582+yihui@users.noreply.github.com>
Co-authored-by: Yihui Xie <xie@yihui.name>

Author: Copilot

.Rbuildignore

@@ -8,3 +8,6 @@
 ^package-lock\.json$
 ^examples$
 ^G2$
+^tests/.*\.qmd$
+^tests/.*\.ipynb$
+^tests/.*\.py$

.github/copilot-instructions.md

@@ -191,10 +191,46 @@ Before submitting changes:
     appears more than once, factor it into a shared helper function. This
     applies to expressions, patterns, and multi-line blocks alike.
 
-### Variables Are Character Strings
+### Variables and Formula Interface
 
-gglite does **NOT** use non-standard evaluation (NSE). Variables are specified
-as character strings, e.g., `g2(mtcars, x = 'mpg', y = 'hp')`.
+gglite does **NOT** use non-standard evaluation (NSE). Variables can be
+specified either as character strings (`x = 'mpg'`) or via the formula
+interface (`y ~ x`). **Prefer the formula interface** in examples and
+documentation because it is more concise and readable:
+
+```r
+# Preferred: formula interface
+g2(mtcars, hp ~ mpg)
+
+# Also valid: character strings
+g2(mtcars, x = 'mpg', y = 'hp')
+```
+
+For single-variable distributions, omit the LHS:
+```r
+g2(mtcars, ~ mpg)   # histogram
+g2(mtcars, ~ cyl)   # histogram (cyl is numeric in mtcars)
+```
+
+The formula interface also works for other aesthetic channels by passing a
+one-sided formula as a named argument:
+```r
+g2(iris, Sepal.Length ~ Sepal.Width, color = ~ Species)
+g2(mtcars, hp ~ mpg, color = ~ cyl, size = ~ wt)
+g2(iris, Sepal.Length ~ Sepal.Width, shape = ~ Species)
+```
+
+**Drop explicit marks that can be automatically inferred.** gglite's
+`auto_mark()` detects the appropriate mark from the data types. Only specify
+a mark explicitly when you need a non-default one:
+
+```r
+# Preferred: auto-inferred scatter plot
+g2(mtcars, hp ~ mpg)
+
+# Only do this when you need something non-default
+g2(mtcars, hp ~ mpg) |> mark_line()
+```
 
 ### Testing Conventions
 

.github/workflows/test-quarto-jupyter.yml

@@ -0,0 +1,98 @@
+name: Test Quarto and Jupyter examples
+
+on:
+  schedule:
+    - cron: '0 0 * * 0'  # weekly on Sunday at midnight UTC
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'tests/*.qmd'
+      - 'tests/*.ipynb'
+      - 'tests/*.py'
+  pull_request:
+    paths:
+      - 'tests/*.qmd'
+      - 'tests/*.ipynb'
+      - 'tests/*.py'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@HEAD
+
+      - uses: r-lib/actions/setup-r@HEAD
+        with:
+          use-public-rspm: true
+
+      - uses: yihui/actions/setup-r-dependencies@HEAD
+        with:
+          extra-packages: . IRkernel rmarkdown
+
+      - name: Install Quarto
+        uses: quarto-dev/quarto-actions/setup@HEAD
+
+      - name: Install Jupyter and IRkernel
+        run: |
+          pip install jupyter nbconvert playwright
+          python -m playwright install chromium
+          Rscript -e "IRkernel::installspec()"
+
+      - name: Render Quarto example
+        run: quarto render tests/test-gglite.qmd
+
+      - name: Execute Jupyter notebook
+        run: |
+          jupyter nbconvert --to notebook --execute tests/test-gglite.ipynb \
+            --output /tmp/test-gglite-executed.ipynb
+
+      - name: Browser-test Quarto output
+        run: python tests/test-quarto.py tests/test-gglite.html
+        env:
+          SCREENSHOT_PATH: /tmp/quarto-test.png
+
+      - name: Browser-test Jupyter output
+        run: python tests/test-jupyter.py /tmp/test-gglite-executed.ipynb
+        env:
+          SCREENSHOT_PATH: /tmp/jupyter-test.png
+
+      - name: Open PR to update notebook if outputs changed (main only)
+        if: github.ref == 'refs/heads/main'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python tests/normalize-notebook.py \
+            /tmp/test-gglite-executed.ipynb /tmp/test-gglite-normalized.ipynb
+          if diff -q tests/test-gglite.ipynb /tmp/test-gglite-normalized.ipynb > /dev/null 2>&1; then
+            echo "Notebook outputs unchanged."
+          else
+            cp /tmp/test-gglite-normalized.ipynb tests/test-gglite.ipynb
+            BRANCH="auto/update-notebook-${{ github.run_id }}"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git config user.name "github-actions[bot]"
+            git checkout -b "$BRANCH"
+            git add tests/test-gglite.ipynb
+            git commit -m "Update notebook outputs"
+            git push origin "$BRANCH"
+            gh pr create \
+              --title "Update notebook outputs" \
+              --body "Automated update of notebook cell outputs after execution on main." \
+              --base main --head "$BRANCH"
+          fi
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@HEAD
+        with:
+          name: test-outputs
+          path: |
+            /tmp/*.png
+            tests/test-gglite.html
+            /tmp/test-gglite-executed.ipynb

.gitignore

@@ -9,3 +9,5 @@ examples/*.html
 G2/
 node_modules/
 vignettes/*.html
+tests/*.html
+tests/*_files/

DESCRIPTION

@@ -1,11 +1,12 @@
 Package: gglite
 Title: Lightweight Data Visualization via the Grammar of Graphics
-Version: 0.0.21
+Version: 0.0.22
 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
-    library with a ggplot2-style API. Supports rendering in R Markdown, Shiny,
-    and standalone HTML previews. Depends only on 'xfun' for JSON serialization.
+    library with a ggplot2-style API. Supports rendering in litedown, R Markdown,
+    Quarto, Jupyter notebooks (via the R kernel), Shiny, and standalone HTML
+    previews.
 License: MIT + file LICENSE
 URL: https://github.com/yihui/gglite
 BugReports: https://github.com/yihui/gglite/issues
@@ -16,6 +17,7 @@ Suggests:
     htmltools,
     litedown,
     knitr,
+    repr,
     shiny,
     testit
 VignetteBuilder: litedown

R/render.R

@@ -69,7 +69,9 @@ auto_mark = function(data, aesthetics, ts = FALSE) {
     list(list(type = 'line'))
   } else if (xt == 'numeric' && yt == 'none') {
     list(list(
-      type = 'interval', transform = list(list(type = 'binX', y = 'count'))
+      type = 'rect',
+      transform = list(list(type = 'binX', y = 'count')),
+      style = list(stroke = 'white')
     ))
   } else if (xt == 'categorical' && yt == 'none') {
     list(list(
@@ -303,45 +305,77 @@ cdn_scripts = function() {
   sprintf('<script src="%s" defer></script>', c(g2_cdn(), g2_patches_cdn))
 }
 
+g2_html_page = function(body) {
+  paste(c(
+    '<!DOCTYPE html>', '<html>', '<head>',
+    '<meta charset="utf-8">',
+    cdn_scripts(),
+    '</head>', '<body>',
+    body,
+    '</body>', '</html>'
+  ), collapse = '\n')
+}
+
 #' Preview a Chart in the Viewer or Browser
 #'
 #' @param x A `g2` object.
 #' @param ... Additional arguments passed to [chart_html()].
 #' @return The chart object (invisibly).
 #' @export
 print.g2 = function(x, ...) {
-  body = chart_html(x, ...)
-  html = c(
-    '<!DOCTYPE html>', '<html>', '<head>',
-    '<meta charset="utf-8">',
-    cdn_scripts(),
-    '</head>', '<body>',
-    body,
-    '</body>', '</html>'
-  )
   #TODO: xfun >= 0.57.3 no longer needs paste()
-  xfun::html_view(paste(html, collapse = '\n'))
+  xfun::html_view(g2_html_page(chart_html(x, ...)))
   invisible(x)
 }
 
+# Document-scoped flag stored in opts_knit to include CDN scripts only once per
+# knit session. opts_knit is restored between documents, so the flag resets
+# automatically, which also allows Quarto (which rejects non-disk-based
+# htmltools::htmlDependency sources).
+.knitr.flag = 'gglite.scripts_added'
+
 #' Custom Printing in Knitr
 #'
 #' @param x A `g2` object.
 #' @param ... Ignored.
 #' @return A `knit_asis` character vector.
 knit_print.g2 = function(x, ...) {
-  if (requireNamespace('htmltools', quietly = TRUE)) {
-    dep = htmltools::htmlDependency(
-      name = 'antv-g2', version = '5',
-      src = c(href = ''),
-      head = paste(cdn_scripts(), collapse = '\n')
-    )
-    knitr::knit_meta_add(list(dep))
-    structure(chart_html(x), class = c('knit_asis', 'html'))
-  } else {
-    out = paste(c(cdn_scripts(), chart_html(x)), collapse = '\n')
-    structure(out, class = c('knit_asis', 'html'))
+  html = chart_html(x)
+  if (!isTRUE(knitr::opts_knit$get(.knitr.flag))) {
+    knitr::opts_knit$set(setNames(list(TRUE), .knitr.flag))
+    html = paste(c(cdn_scripts(), html), collapse = '\n')
   }
+  structure(html, class = c('knit_asis', 'html'))
+}
+
+#' HTML Representation for Jupyter Notebooks
+#'
+#' Called by the `repr` package (used by IRkernel) to render g2 charts in
+#' Jupyter notebooks. Returns a complete HTML page so the chart is displayed
+#' inside a sandboxed output cell.
+#'
+#' @param obj A `g2` object.
+#' @param ... Ignored.
+#' @return A character string of complete HTML.
+#' @noRd
+repr_html.g2 = function(obj, ...) g2_html_page(chart_html(obj))
+
+#' Text Representation for Jupyter Notebooks
+#'
+#' Returns a brief text description so IRkernel's MIME bundle includes a
+#' non-empty `text/plain` entry, which is required before any rich display
+#' (including HTML) is sent to the Jupyter frontend.
+#'
+#' @param obj A `g2` object.
+#' @param ... Ignored.
+#' @return A character string.
+#' @noRd
+repr_text.g2 = function(obj, ...) {
+  n = if (is.data.frame(obj$data)) nrow(obj$data) else NULL
+  marks = paste(vapply(obj$layers, `[[`, '', 'type'), collapse = ', ')
+  if (!nzchar(marks)) marks = 'auto'
+  n_str = if (is.null(n)) 'no data' else as.character(n)
+  sprintf('G2 chart (%s; %s rows)', marks, n_str)
 }
 
 #' @importFrom xfun record_print
@@ -350,11 +384,24 @@ record_print.g2 = function(x, ...) {
   xfun::new_record(c(cdn_scripts(), chart_html(x, ...), ''), 'asis')
 }
 
-register_knit_print = function() {
-  registerS3method('knit_print', 'g2', knit_print.g2, envir = asNamespace('knitr'))
+register_methods = function(pkgs, generics) {
+  for (i in seq_along(pkgs)) local({
+    pkg = pkgs[[i]]; generic = generics[[i]]
+    hook = function(...) {
+      registerS3method(
+        generic, 'g2',
+        asNamespace('gglite')[[paste0(generic, '.g2')]],
+        envir = asNamespace(pkg)
+      )
+    }
+    if (isNamespaceLoaded(pkg)) hook()
+    setHook(packageEvent(pkg, 'onLoad'), hook)
+  })
 }
 
 .onLoad = function(...) {
-  if (isNamespaceLoaded('knitr')) register_knit_print()
-  setHook(packageEvent('knitr', 'onLoad'), function(...) register_knit_print())
+  register_methods(
+    c('knitr', 'repr', 'repr'),
+    c('knit_print', 'repr_html', 'repr_text')
+  )
 }

tests/normalize-notebook.py

@@ -0,0 +1,27 @@
+"""Normalize and copy an executed Jupyter notebook.
+
+Strips execution metadata (execution counts, timestamps) that change between
+runs and copies the normalized notebook to the target path. Used by CI to
+produce a clean diff when deciding whether to open a PR.
+
+Usage: python tests/normalize-notebook.py <source.ipynb> <target.ipynb>
+"""
+import json, sys
+
+
+def normalize(nb: dict) -> None:
+    for cell in nb.get('cells', []):
+        cell['execution_count'] = None
+        cell.get('metadata', {}).pop('execution', None)
+        for out in cell.get('outputs', []):
+            out.pop('execution_count', None)
+
+
+if __name__ == '__main__':
+    src, dst = sys.argv[1], sys.argv[2]
+    with open(src) as f:
+        nb = json.load(f)
+    normalize(nb)
+    with open(dst, 'w') as f:
+        json.dump(nb, f, indent=1)
+        f.write('\n')