Merge branch 'enhancements' into htmlwidgets-vignette

Author: alandipert

DESCRIPTION

@@ -2,7 +2,7 @@ Package: reactR
 Type: Package
 Title: React Helpers
 Version: 0.3.0
-Date: 2019-01-03
+Date: 2019-01-11
 Authors@R: c(
       person(
         "Facebook", "Inc"
@@ -23,8 +23,8 @@ Authors@R: c(
       )
     )
 Maintainer: Kent Russell <[email protected]>
-Description: Make it easy to use 'React' in R with helper
-              dependency functions, embedded 'Babel' 'transpiler',
+Description: Make it easy to use 'React' in R with 'htmlwidget' scaffolds,
+              helper dependency functions, an embedded 'Babel' 'transpiler',
               and examples.
 URL: https://github.com/react-R/reactR
 BugReports: https://github.com/react-R/reactR/issues

R/dependencies.R

@@ -73,10 +73,9 @@ html_dependency_corejs <- function() {
 
 #' Adds window.reactR.exposeComponents and window.reactR.hydrate
 #'
-#' @return
+#' @return \code{\link[htmltools]{htmlDependency}}
+#' @importFrom htmltools htmlDependency
 #' @export
-#'
-#' @examples
 html_dependency_reacttools <- function(){
   htmltools::htmlDependency(
     name = "reactwidget",

R/reacttools.R

@@ -25,7 +25,8 @@ 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)
+  component <- htmltools::tag(name, varArgs)
+  structure(component, class = c("reactR_component", oldClass(component)))
 }
 
 #' React component builder.
@@ -76,16 +77,18 @@ React <- structure(
 #' Prepare data that represents a single-element character vector, a React
 #' component, or an htmltools tag for sending to the client.
 #'
+#' Tag lists as returned by \code{\link[htmltools]{tagList}} are not currently
+#' supported.
+#'
 #' @param tag character vector or React component or
 #'   \code{\link[htmltools]{tag}}
 #'
-#' @return
+#' @return A reactR markup object suitable for being passed to
+#'   \code{\link[htmlwidgets]{createWidget}} as widget instance data.
 #' @export
-#'
-#' @examples
 reactMarkup <- function(tag) {
-  stopifnot(class(tag) == "shiny.tag"
+  stopifnot(inherits(tag, "shiny.tag")
             || (is.character(tag) && length(tag) == 1))
-  list(tag = tag, class = "reactR.markup")
+  list(tag = tag, class = "reactR_markup")
 }
 

README.md

@@ -1,28 +1,33 @@
 [![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/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"/>
+<img height="150px" alt="react-R logo" src="https://github.com/react-R/reactR/raw/enhancements/assets/logos/reactR-logo.png"/>
 
 # reactR
 
-A set of convenience function with local dependencies for using [`React`](https://facebook.github.io/react) in `R`.  This is modeled after the `html_dependency_*` functions from RStudio's [`rmarkdown`](https://github.com/rstudio/rmarkdown) package.
+`reactR` provides a set of convenience functions for using [`React`](https://facebook.github.io/react) in `R` with `htmlwidget` constructor templates and local JavaScript dependencies.  The `React` ecosystem is rich with comoponents that can enhance `R` web and shiny apps.  `scaffoldWidget` helps build `htmlwidgets` to integrate these `React` components as `R` `htmlwidgets`.  The local dependency functions are modeled after the `html_dependency_*` functions from RStudio's [`rmarkdown`](https://github.com/rstudio/rmarkdown) package.
 
 ## Installation
 
-You can install reactR from github with:
+You can install reactR from CRAN with `install.packages("reactR")`.  For the development version, please use `devtools` as shown below.
 
 ```R
 # install.packages("devtools")
 devtools::install_github("react-R/reactR")
 ```
 
-## Example
+## Creating htmlwidgets with React Components
+
+To wrap a `React` component as an `htmlwidget`, please see the tutorial [htmlwidgets with reactR](https://react-r.github.io/reactR/articles/intro_htmlwidgets.html).  Also, there are a variety of examples in the [react-R Github organization](https://github.com/react-R).
+
+## Examples
 
 ```R
 library(reactR)
 library(htmltools)
 
 browsable(tagList(
+  tags$div(id = "app"),
   tags$script(
   "
     ReactDOM.render(
@@ -31,7 +36,7 @@ browsable(tagList(
         null,
         'Powered by React'
       ),
-      document.body
+      document.getElementById('app')
     )
   "
   ),
@@ -41,16 +46,17 @@ browsable(tagList(
 ))
 ```
 
-`reactR` also uses `V8` if available to transform `JSX` and `ES2015` code.
+`reactR` also uses the `V8` package if available to transform `JSX` and `ES2015` code.
 
 ```R
 library(reactR)
 library(htmltools)
 
 browsable(
   tagList(
+    tags$div(id = "app"),
     tags$script(
-      babel_transform('ReactDOM.render(<h1>Powered By React/JSX</h1>,document.body)')
+      babel_transform('ReactDOM.render(<h1>Powered By React/JSX</h1>,document.getElementById("app"))')
     ),
     # add core-js shim first for React in RStudio Viewer
     html_dependency_corejs(),
@@ -61,4 +67,4 @@ browsable(
 
 ## Contributing and Code of Conduct
 
-I welcome contributors.  Help make this package great.  Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.
+We welcome contributors and would love your participation.  Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by the terms.

inst/templates/widget_r.txt

@@ -52,7 +52,7 @@ render${capName} <- function(expr, env = parent.frame(), quoted = FALSE) {
 #' Called by HTMLWidgets to produce the widget's root element.
 #' @rdname ${name}-shiny
 ${name}_html <- function(id, style, class, ...) {
-  tagList(
+  htmltools::tagList(
     # Necessary for RStudio viewer version < 1.2
     reactR::html_dependency_corejs(),
     reactR::html_dependency_react(),

man/builder.Rd

@@ -44,6 +44,9 @@ To create a new widget you can call `scaffoldReactWidget` to generate the basic
 The following R code will create a package named **sparklines**, then provide the templating for creating an htmlwidget powered by the `react-sparklines` npm package:
 
 ```{r}
+# Set the current working directory to your home directory. The new widget will
+# be created in ~/sparklines
+setwd("~")
 # Create a directory 'sparklines' and populate it with skeletal package
 # If run within RStudio, this will create a new RStudio session
 usethis::create_package("sparklines")
@@ -120,6 +123,8 @@ data = sampleData,
 sparklinesLine(color = "#56b45d"),
 sparklinesSpots(style = list(fill = "#56b45d"))
 )
+=======
+reactWidget('reactSparklines', 'output', SparklinesComponents, {});
 ```
 
 The following sections show how to implement this R interface from our scaffolded widget.