HTMLWidget and Shiny input integration helpers

.Rbuildignore

@@ -1,7 +1,12 @@
+^node_modules$
 ^.*\.Rproj$
 ^\.Rproj\.user$
 ^\build
 ^CONDUCT\.md$
 ^cran-comments\.md$
 ^docs$
 ^\.travis\.yml$
+^\assets
+^karma\.conf\.js$
+^package\.json$
+^yarn\.lock$

.gitignore

@@ -3,3 +3,6 @@
 .RData
 .Ruserdata
 inst/doc
+node_modules
+reactR.Rcheck
+reactR_*.tar.gz

.travis.yml

@@ -1,8 +1,15 @@
-# R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
-
-language: R
-sudo: required
-cache: packages
-
-before_install:
-  - sudo apt-get install -y libv8-dev
+matrix:
+  include:
+    # R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
+    - language: r
+      r:
+        - release
+      sudo: required
+      cache: packages
+      before_install:
+        - sudo apt-get install -y libv8-dev
+    - language: node_js
+      node_js:
+        - "11.4.0"
+      addons:
+        - chrome: stable

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: reactR
 Type: Package
 Title: React Helpers
-Version: 0.2.1
-Date: 2018-10-23
+Version: 0.3.0
+Date: 2019-01-03
 Authors@R: c(
       person(
         "Facebook", "Inc"
@@ -14,16 +14,23 @@ Authors@R: c(
         , role = c("aut", "cre")
         , comment = "R interface"
         , email = "[email protected]"
+      ),
+      person(
+        "Alan", "Dipert"
+        , role = c("aut")
+        , comment = "R interface"
+        , email = "[email protected]"
       )
     )
 Maintainer: Kent Russell <[email protected]>
 Description: Make it easy to use 'React' in R with helper
               dependency functions, embedded 'Babel' 'transpiler',
               and examples.
-URL: https://github.com/timelyportfolio/reactR
-BugReports: https://github.com/timelyportfolio/reactR/issues
+URL: https://github.com/react-R/reactR
+BugReports: https://github.com/react-R/reactR/issues
 License: MIT + file LICENSE
 LazyData: TRUE
+Encoding: UTF-8
 Imports:
     htmltools
 Suggests:
@@ -32,5 +39,5 @@ Suggests:
     shiny,
     V8,
     knitr
-RoxygenNote: 6.0.1
+RoxygenNote: 6.1.1
 VignetteBuilder: knitr

NAMESPACE

@@ -1,6 +1,15 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method("$",react_component_builder)
+S3method("$<-",react_component_builder)
+S3method("[[",react_component_builder)
+S3method("[[<-",react_component_builder)
+export(React)
 export(babel_transform)
+export(component)
 export(html_dependency_corejs)
 export(html_dependency_react)
+export(html_dependency_reacttools)
+export(reactMarkup)
+export(scaffoldReactWidget)
 importFrom(htmltools,htmlDependency)

R/dependencies.R

@@ -70,3 +70,19 @@ html_dependency_corejs <- function() {
     script = "shim.min.js"
   )
 }
+
+#' Adds window.reactR.exposeComponents and window.reactR.hydrate
+#'
+#' @return
+#' @export
+#'
+#' @examples
+html_dependency_reacttools <- function(){
+  htmltools::htmlDependency(
+    name = "reactwidget",
+    src = "www/react-tools",
+    version = "1.0.0",
+    package = "reactR",
+    script = c("react-tools.js")
+  )
+}

R/meta.R

@@ -1,3 +1,3 @@
 #'@keywords internal
-react_version <- function(){'16.6.0'}
+react_version <- function(){'16.7.0'}
 babel_version <- function(){'6.26.0'}

R/reacttools.R

@@ -0,0 +1,91 @@
+isUpper <- function(s) {
+  grepl("^[[:upper:]]+$", s)
+}
+
+#' Create a React component
+#'
+#' @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
+#'
+#' @examples
+#' component("ParentComponent",
+#'   list(
+#'     x = 1,
+#'     y = 2,
+#'     component("ChildComponent"),
+#'     component("OtherChildComponent")
+#'   )
+#' )
+component <- function(name, varArgs = list()) {
+  if (length(name) == 0 || !isUpper(substring(name, 1, 1))) {
+    stop("Component name must be specified and start with an upper case character")
+  }
+  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"
+)
+
+#' @export
+`$.react_component_builder` <- function(x, name) {
+  function(...) {
+    component(name, list(...))
+  }
+}
+
+#' @export
+`[[.react_component_builder` <- `$.react_component_builder`
+
+#' @export
+`$<-.react_component_builder` <- function(x, name, value) {
+  stop("Assigning to a component constructor is not allowed")
+}
+
+#' @export
+`[[<-.react_component_builder` <- `$<-.react_component_builder`
+
+#' Prepare data that represents a single-element character vector, a React
+#' component, or an htmltools tag for sending to the client.
+#'
+#' @param tag character vector or React component or
+#'   \code{\link[htmltools]{tag}}
+#'
+#' @return
+#' @export
+#'
+#' @examples
+reactMarkup <- function(tag) {
+  stopifnot(class(tag) == "shiny.tag"
+            || (is.character(tag) && length(tag) == 1))
+  list(tag = tag, class = "reactR.markup")
+}
+

R/scaffold.R

@@ -0,0 +1,157 @@
+#' 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)
+  addExampleApp(name)
+  message("To install dependencies from npm run: yarn install")
+  message("To build JavaScript run: yarn run webpack --mode=development")
+}
+
+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")
+}
+
+# Perform a series of pattern replacements on str.
+# Example: renderTemplate("foo ${x} bar ${y} baz ${x}", list(x = 1, y = 2))
+# Produces: "foo 1 bar 2 baz 1"
+renderTemplate <- function(str, substitutions) {
+  Reduce(function(str, name) {
+    gsub(paste0("\\$\\{", name, "\\}"), substitutions[[name]], str)
+  }, names(substitutions), str)
+}
+
+capName = function(name){
+  paste0(toupper(substring(name, 1, 1)), substring(name, 2))
+}
+
+addWidgetConstructor <- function(name, package, edit){
+  tpl <- slurp('templates/widget_r.txt')
+  if (!file.exists(file_ <- sprintf("R/%s.R", name))){
+    cat(
+      renderTemplate(tpl, list(name = name, package = package, capName = capName(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 <- renderTemplate(slurp('templates/widget_package.json.txt'), list(npmPkg = npmPkg))
+  if (!file.exists('package.json')) {
+    cat(tpl, file = 'package.json')
+    message('Created package.json')
+  } else {
+    message("package.json already exists")
+  }
+}
+
+addWebpackConfig <- function(name) {
+  tpl <- renderTemplate(slurp('templates/widget_webpack.config.js.txt'), list(name = name))
+  if (!file.exists('webpack.config.js')) {
+    cat(tpl, file = 'webpack.config.js')
+    message('Created 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(renderTemplate(tpl, list(name = 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_)
+}
+
+addExampleApp <- function(name) {
+  tpl <- renderTemplate(slurp('templates/widget_app.R.txt'), list(name = name, capName = capName(name)))
+  if (!file.exists('app.R')) {
+    cat(tpl, file = 'app.R')
+    message('Created example app.R')
+  } else {
+    message("app.R already exists")
+  }
+}
+
+# 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)
+}

README.md

@@ -1,5 +1,7 @@
 [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/reactR)](https://cran.r-project.org/package=reactR)
-[![Travis-CI Build Status](https://travis-ci.org/timelyportfolio/reactR.svg?branch=master)](https://travis-ci.org/timelyportfolio/reactR)
+[![Travis-CI Build Status](https://travis-ci.org/react-R/reactR.svg?branch=master)](https://travis-ci.org/react-R/reactR)
+
+<img height="150px" alt="react-R logo" src="assets/logos/reactR-logo.png"/>
 
 # reactR
 
@@ -11,7 +13,7 @@ You can install reactR from github with:
 
 ```R
 # install.packages("devtools")
-devtools::install_github("timelyportfolio/reactR")
+devtools::install_github("react-R/reactR")
 ```
 
 ## Example