Add Shiny bindings and adopt htmlwidgets for visualization rendering

[cpsievert]

Summary

• Adds ggsqlOutput() / renderGgsql() / ggsql_session_reader() for
  embedding ggsql visualizations in Shiny apps.
• Replaces the hand-rolled inline <script> + sprintf() HTML generation in
  the knitr engine with an htmlwidgets widget
  (ggsql_vega), which now handles all HTML rendering contexts: knitr chunks,
  print(), and Shiny.

Why htmlwidgets?

The old vegalite_html() path generated standalone JavaScript blobs for every
visualization — each one loaded Vega from a CDN, managed its own script
deduplication via a global promise, and implemented responsive scaling inline.
This worked for simple static documents but couldn't participate in Shiny's
output binding protocol, and the CDN dependency meant visualizations didn't
render offline or inside networks that block external scripts.

htmlwidgets gives us a standard rendering surface that works everywhere R
produces HTML. Vega, Vega-Lite, and Vega-Embed are now vendored as
htmlDependency objects under inst/htmlwidgets/lib/, so dependency
deduplication and script loading are handled by htmltools automatically. The
Shiny output binding comes for free from the htmlwidgets framework.

Shiny API

ggsqlOutput(outputId) / renderGgsql(expr) — standard Shiny
output/render pair. renderGgsql() accepts either a raw ggsql query string or
a pre-computed Spec. Query strings can use r:varname data references, which
resolve against the render expression's environment (not just knit_global()).

ggsql_session_reader(reader) — registers a session-scoped default reader
so you don't have to pass one to every renderGgsql() call. Cleaned up
automatically when the session ends.

library(shiny)
library(ggsql)

ui <- fluidPage(
  ggsqlOutput("chart")
)

server <- function(input, output, session) {
  ggsql_session_reader(duckdb_reader())

  output$chart <- renderGgsql({
    "SELECT * FROM r:mtcars VISUALISE mpg AS x, disp AS y DRAW point"
  })
}

shinyApp(ui, server)

Widget runtime

The browser-side code lives in srcts/ as TypeScript and is built to
inst/htmlwidgets/ggsql_vega.js. It handles:

• Rendering Vega-Lite specs via vegaEmbed with responsive resize.
• Compound sizing for multi-view and faceted specs, allocating viewport
  dimensions across sub-plots so they fill the host container.
• Scale-to-fit when the container is narrower than the chart's minimum width.

Dropped: fig.cap and fig.align for interactive output

The old inline-HTML path supported fig.cap (wrapping output in a <figure> /
<figcaption>) and fig.align (CSS margin alignment) for the vegalite
writer. These are dropped for interactive HTML output, consistent with how
htmlwidgets are treated generally.

In practice, the previous fig.cap approach didn't work in Quarto anyway, since
Quarto manages figure environments and captions at a higher level and the raw
<figure> wrapper was invisible to it. The vegalite_svg and vegalite_png
writers still support fig.cap since their output passes through knitr's normal
graphics pipeline.

The engine now emits a warning if fig.cap is set with the vegalite writer,
directing users to the SVG/PNG writers for captioned figures.

Changes to knitr engine output

The engine's vegalite writer path now returns an htmlwidgets object instead of
a raw HTML string. This means sizing, dependency management, and responsive
behavior are delegated to the htmlwidgets framework and its sizing policy rather
than being implemented ad-hoc in inline JavaScript.

resolve_data_refs() gained an envir parameter (defaulting to
knit_global() in the engine, the render expression's environment in Shiny) so
the same resolution logic works in both contexts.

[thomasp85]

This looks good - thanks a bunch. I did some work on the engine in the meantime to better support native knitr sizing options so you'll have to incorporate that. Otherwise it LGTM

[cpsievert]

FWIW, the next release of htmlwidgets will move rmarkdown from Suggests to Import

[thomasp85]

hmm... I guess this is not too horrible given the prevalence of RMarkdown and the fact that this package provides a knitr engine for it

[cpsievert]

@thomasp85 ok, ready for your eyes now

[thomasp85]

Thanks for your work on this, Carson