Added ExternalVar

Closes #80

Author: japgolly

doc/CHANGELOG-0.8.md

@@ -1,6 +1,7 @@
 # 0.8.1
 
 * Added `ReactComponentB.static` to quickly create components with unchanging content.
+* Added `ExternalVar` to `extra` module. ([Live demo](http://japgolly.github.io/scalajs-react/))
 
 ##### Scalatags
 

extra/README.md

@@ -6,6 +6,7 @@ A collection of functionality that provides benefit when using scalajs-react.
 - [Router](https://github.com/japgolly/scalajs-react/blob/master/extra/ROUTER.md)
 - Component Mixins:
   - [Broadcaster and Listenable](#broadcaster-and-listenable)
+  - [ExternalVar](#externalvar)
   - [LogLifecycle](#loglifecycle)
   - [OnUnmount](#onunmount)
   - [SetInterval](#setinterval)
@@ -38,6 +39,14 @@ object HelloBroadcaster extends Broadcaster[String] {
 * `Broadcaster`: Provides a `protected def broadcast(a: A): Unit` for easy message broadcasting.
 
 
+ExternalVar
+===========
+Provides a component with safe R/W access to an external variable.
+
+A live demo with accompanying code is available on
+[http://japgolly.github.io/scalajs-react](http://japgolly.github.io/scalajs-react/).
+
+
 LogLifecycle
 ============
 This will cause logging to occur at React component lifecycle stages.

extra/src/main/scala/japgolly/scalajs/react/extra/ExternalVar.scala

@@ -0,0 +1,29 @@
+package japgolly.scalajs.react.extra
+
+import japgolly.scalajs.react._, ScalazReact._
+import monocle.Lens
+import scalaz.effect.IO
+
+/**
+ * Provides a component with safe R/W access to an external variable.
+ */
+final class ExternalVar[A](val value: A, val set: A => IO[Unit]) {
+
+  def mod(f: A => A): IO[Unit] =
+    set(f(value))
+
+  def setL[B](l: Lens[A, B]): B => IO[Unit] =
+    b => set(l.set(b)(value))
+
+  def modL[B](l: Lens[A, B])(f: B => B): IO[Unit] =
+    set(l.modify(f)(value))
+}
+
+
+object ExternalVar {
+  @inline def apply[A](value: A)(set: A => IO[Unit]): ExternalVar[A] =
+    new ExternalVar(value, set)
+
+  @inline def state[S]($: ComponentStateFocus[S]): ExternalVar[S] =
+    new ExternalVar($.state, $.setStateIO(_))
+}

gh-pages/src/main/scala/ghpages/examples/ExternalVarExample.scala

@@ -0,0 +1,66 @@
+package ghpages.examples
+
+import ghpages.examples.util.SingleSide
+import japgolly.scalajs.react._, vdom.prefix_<^._, ScalazReact._, MonocleReact._
+import japgolly.scalajs.react.extra.ExternalVar
+import monocle.macros._
+
+object ExternalVarExample {
+
+  def content = SingleSide.Content(source, Main())
+
+  val source =
+    """
+      |@Lenses
+      |case class Name(firstName: String, surname: String)
+      |
+      |val Main = ReactComponentB[Unit]("ExternalVar example")
+      |  .initialState(Name("John", "Wick"))
+      |  .render { $ =>
+      |    val name = $.state
+      |    val firstNameEV = ExternalVar.state($.focusStateL(Name.firstName))
+      |    val surnameEV   = ExternalVar.state($.focusStateL(Name.surname))
+      |    <.div(
+      |      <.label("First name:", NameChanger(firstNameEV)),
+      |      <.label("Surname:",    NameChanger(surnameEV  )),
+      |      <.p(s"My name is ${name.surname}, ${name.firstName} ${name.surname}."))
+      |  }
+      |  .build
+      |
+      |val NameChanger = ReactComponentB[ExternalVar[String]]("Name changer")
+      |  .render { evar =>
+      |    def onChange = (event: ReactEventI) => evar.set(event.target.value)
+      |    <.input(
+      |      ^.`type`    := "text",
+      |      ^.value     := evar.value,
+      |      ^.onChange ~~> onChange)
+      |  }
+      |  .build""".stripMargin
+
+
+  @Lenses
+  case class Name(firstName: String, surname: String)
+
+  val Main = ReactComponentB[Unit]("ExternalVar example")
+    .initialState(Name("John", "Wick"))
+    .render { $ =>
+      val name = $.state
+      val firstNameEV = ExternalVar.state($.focusStateL(Name.firstName))
+      val surnameEV   = ExternalVar.state($.focusStateL(Name.surname))
+      <.div(
+        <.label("First name:", NameChanger(firstNameEV)),
+        <.label("Surname:",    NameChanger(surnameEV  )),
+        <.p(s"My name is ${name.surname}, ${name.firstName} ${name.surname}."))
+    }
+    .buildU
+
+  val NameChanger = ReactComponentB[ExternalVar[String]]("Name changer")
+    .render { evar =>
+      def onChange = (event: ReactEventI) => evar.set(event.target.value)
+      <.input(
+        ^.`type`    := "text",
+        ^.value     := evar.value,
+        ^.onChange ~~> onChange)
+    }
+    .build
+}

gh-pages/src/main/scala/ghpages/pages/ExamplesPage.scala

@@ -17,8 +17,9 @@ object Example {
   case object Animation    extends Example("Animation",          AnimationExample.content)
   case object PictureApp   extends Example("AjaxPictureApp",     PictureAppExample.content)
   case object Scalaz       extends Example("Todo List (Scalaz)", ScalazExample.content)
+  case object ExternalVar  extends Example("ExternalVar",        ExternalVarExample.content)
 
-  val values = Vector[Example](Hello, Timer, Todo, Scalaz, Refs, ProductTable, Animation, PictureApp)
+  val values = Vector[Example](Hello, Timer, Todo, Scalaz, Refs, ExternalVar, ProductTable, Animation, PictureApp)
 }
 
 object ExamplesPage {

project/Build.scala

@@ -88,6 +88,9 @@ object ScalajsReact extends Build {
   def extModuleName(shortName: String): PE =
     _.settings(name := s"ext-$shortName")
 
+  def macroParadisePlugin =
+    compilerPlugin("org.scalamacros" % "paradise" % "2.0.1" cross CrossVersion.full)
+
   // ==============================================================================================
   lazy val root = Project("root", file("."))
     .aggregate(core, test, scalaz71, monocle, extra, ghpages)
@@ -128,21 +131,24 @@ object ScalajsReact extends Build {
   lazy val monocle = project
     .configure(commonSettings, publicationSettings, extModuleName("monocle"))
     .dependsOn(core, scalaz71)
-    .settings(
-      libraryDependencies += "com.github.japgolly.fork.monocle" %%% "monocle-core" % "1.0.1")
+    .settings(libraryDependencies += monocleLib("core"))
+
+  def monocleLib(name: String) =
+    "com.github.japgolly.fork.monocle" %%%! s"monocle-$name" % "1.0.1"
 
   // ==============================================================================================
   lazy val extra = project
     .configure(commonSettings, publicationSettings)
-    .dependsOn(core, scalaz71)
-    .settings(
-      name := "extra")
+    .dependsOn(core, scalaz71, monocle)
+    .settings(name := "extra")
 
   // ==============================================================================================
   lazy val ghpages = Project("gh-pages", file("gh-pages"))
     .dependsOn(core, scalaz71, extra, monocle)
     .configure(commonSettings, useReactJs(), preventPublication)
     .settings(
+      libraryDependencies += monocleLib("macro"),
+      addCompilerPlugin(macroParadisePlugin),
       emitSourceMaps := false,
       artifactPath in (Compile, fullOptJS) := file("gh-pages/res/ghpages.js"))
 }