Merge branch 'enhancements' of https://github.com/react-R/reactR into enhancements

Author: timelyportfolio

DESCRIPTION

@@ -14,6 +14,12 @@ Authors@R: c(
         , role = c("aut", "cre")
         , comment = "R interface"
         , email = "kent.russell@timelyportfolio.com"
+      ),
+      person(
+        "Alan", "Dipert"
+        , role = c("aut")
+        , comment = "R interface"
+        , email = "alan@rstudio.com"
       )
     )
 Maintainer: Kent Russell <kent.russell@timelyportfolio.com>

NAMESPACE

@@ -11,4 +11,5 @@ export(html_dependency_corejs)
 export(html_dependency_react)
 export(html_dependency_reacttools)
 export(reactData)
+export(scaffoldReactWidget)
 importFrom(htmltools,htmlDependency)

R/reacttools.R

@@ -2,10 +2,37 @@ isUpper <- function(s) {
   grepl("^[[:upper:]]+$", s)
 }
 
+#' React component builder functions
+#'
+#' Functions for creating React component, HTML, and SVG trees to send to the
+#' browser for rendering.
+#'
+#' The \code{\link{component}} function creates a representation of a React
+#' component instance to send to the browser for rendering. It is analagous to
+#' \code{\link[htmltools]{tag}}.
+#'
+#' The \code{\link{React}} list is a special object that supports
+#' \link[=InternalMethods]{extraction} syntax for creating React components.
+#'
+#' Once a component or tag has been created in R, it must be passed to
+#' \code\{\link{reactData}} before being sent to the browser. In the case of
+#' htmlwidgets, the return value of \code{reactData} should be passed as the
+#' \code{x} argument of \code{\link{htmlwidgets::createWidget}}.
+#'
+#' Any React components named by \code{component} or \code{React} must have been
+#' installed on the client using \code{reactR.reactWidget}. Alternatively, the
+#' JSON representing the tag can be converted to a React component tree with
+#' \code{reactR.hydrate}.
+#'
+#' @name builder
+NULL
+
 #' Create a React component
 #'
-#' @param name Name of the React component, which must start with an upper-case character.
-#' @param ... Attributes and children of the element to pass along to \code{\link[htmltools]{tag}} as varArgs.
+#' @param name Name of the React component, which must start with an upper-case
+#'   character.
+#' @param varArgs Attributes and children of the element to pass along to
+#'   \code{\link[htmltools]{tag}} as \code{varArgs}.
 #'
 #' @return An htmltools \code{\link[htmltools]{tag}} object
 #' @export
@@ -26,8 +53,32 @@ component <- function(name, varArgs = list()) {
   htmltools::tag(name, varArgs)
 }
 
+#' React component builder.
+#'
+#' \code{React} is a syntactically-convenient way to create instances of React
+#' components that can be sent to the browser for display. It is a list for
+#' which \link[=InternalMethods]{extract methods} are defined, allowing
+#' object creation syntax like \code{React$MyComponent(x = 1)} where
+#' \code{MyComponent} is a React component you have exposed to Shiny in
+#' JavaScript.
+#'
+#' Internally, the \code{\link{component}} function is used to create the
+#' component instance.
+#'
+#' @examples
+#' # Create an instance of ParentComponent with two children,
+#' # ChildComponent and OtherChildComponent.
+#' React$ParentComponent(
+#'   x = 1,
+#'   y = 2,
+#'   React$ChildComponent(),
+#'   React$OtherChildComponent()
+#' )
 #' @export
-React <- structure(list(), class = "react_component_builder")
+React <- structure(
+  list(),
+  class = "react_component_builder"
+)
 
 #' @export
 `$.react_component_builder` <- function(x, name) {
@@ -47,9 +98,9 @@ React <- structure(list(), class = "react_component_builder")
 #' @export
 `[[<-.react_component_builder` <- `$<-.react_component_builder`
 
-#' Create a data object for transporting a React component to the client.
+#' Create a data object for sending a React component to the client.
 #'
-#' @param tag
+#' @param tag React component or \code{\link[htmltools]{tag}}
 #'
 #' @return
 #' @export

R/scaffold.R

@@ -0,0 +1,133 @@
+#' Create implementation scaffolding for a React.js-based HTML widget
+#'
+#' Add the minimal code required to implement a React.js-based HTML widget to an
+#' R package.
+#'
+#' @param name Name of widget
+#' @param npmPkg Optional \href{https://npmjs.com/}{NPM} package upon which this
+#'   widget is based, as a two-element character vector of name and
+#'   \href{https://docs.npmjs.com/files/package.json#dependencies}{version
+#'   range}. If you specify this parameter the package will be added to the
+#'   \code{dependency} section of the generated \code{package.json}.
+#' @param edit Automatically open the widget's JavaScript source file after
+#'   creating the scaffolding.
+#'
+#' @note This function must be executed from the root directory of the package
+#'   you wish to add the widget to.
+#'
+#' @export
+scaffoldReactWidget <- function(name, npmPkg = NULL, edit = interactive()){
+  if (!file.exists('DESCRIPTION')){
+    stop(
+      "You need to create a package to house your widget first!",
+      call. = F
+    )
+  }
+  if (!file.exists('inst')){
+    dir.create('inst')
+  }
+  package <- read.dcf('DESCRIPTION')[[1,"Package"]]
+  addWidgetConstructor(name, package, edit)
+  addWidgetYAML(name, edit)
+  addPackageJSON(toDepJSON(npmPkg))
+  addWebpackConfig(name)
+  addWidgetJS(name, edit)
+}
+
+toDepJSON <- function(npmPkg) {
+  if (is.null(npmPkg)) {
+    ""
+  } else {
+    do.call(sprintf, as.list(c('"%s": "%s"', npmPkg)))
+  }
+}
+
+slurp <- function(file) {
+  paste(readLines(
+    system.file(file, package = 'reactR')
+  ), collapse = "\n")
+}
+
+addWidgetConstructor <- function(name, package, edit){
+  tpl <- slurp('templates/widget_r.txt')
+
+  capName = function(name){
+    paste0(toupper(substring(name, 1, 1)), substring(name, 2))
+  }
+  if (!file.exists(file_ <- sprintf("R/%s.R", name))){
+    cat(
+      sprintf(tpl, name, name, package, name, name, name, name, name, name, package, name, capName(name), name, name, name),
+      file = file_
+    )
+    message('Created boilerplate for widget constructor ', file_)
+  } else {
+    message(file_, " already exists")
+  }
+  if (edit) fileEdit(file_)
+}
+
+addWidgetYAML <- function(name, edit){
+  tpl <- "# (uncomment to add a dependency)
+# dependencies:
+#  - name:
+#    version:
+#    src:
+#    script:
+#    stylesheet:
+"
+  if (!file.exists('inst/htmlwidgets')){
+    dir.create('inst/htmlwidgets')
+  }
+  if (!file.exists(file_ <- sprintf('inst/htmlwidgets/%s.yaml', name))){
+    cat(tpl, file = file_)
+    message('Created boilerplate for widget dependencies at ',
+            sprintf('inst/htmlwidgets/%s.yaml', name)
+    )
+  } else {
+    message(file_, " already exists")
+  }
+  if (edit) fileEdit(file_)
+}
+
+addPackageJSON <- function(npmPkg) {
+  tpl <- sprintf(slurp('templates/widget_package.json.txt'), npmPkg)
+  if (!file.exists('package.json')) {
+    cat(tpl, file = 'package.json')
+  } else {
+    message("package.json already exists")
+  }
+}
+
+addWebpackConfig <- function(name) {
+  tpl <- sprintf(slurp('templates/widget_webpack.config.js.txt'), name, name)
+  if (!file.exists('webpack.config.js')) {
+    cat(tpl, file = 'webpack.config.js')
+  } else {
+    message("webpack.config.js already exists")
+  }
+}
+
+addWidgetJS <- function(name, edit){
+  tpl <- paste(readLines(
+    system.file('templates/widget_js.txt', package = 'reactR')
+  ), collapse = "\n")
+  if (!file.exists('srcjs')){
+    dir.create('srcjs')
+  }
+  if (!file.exists(file_ <- sprintf('srcjs/%s.js', name))){
+    cat(sprintf(tpl, name), file = file_)
+    message('Created boilerplate for widget javascript bindings at ',
+            sprintf('srcjs/%s.js', name)
+    )
+  } else {
+    message(file_, " already exists")
+  }
+  if (edit) fileEdit(file_)
+}
+
+# invoke file.edit in a way that will bind to the RStudio editor
+# when running inside RStudio
+fileEdit <- function(file) {
+  fileEditFunc <- eval(parse(text = "file.edit"), envir = globalenv())
+  fileEditFunc(file)
+}