Merge branch 'edge' of github.com:hyperstack-org/hyperstack into edge

Author: catmando

docs/dsl-client/hyper-component.md

@@ -1212,8 +1212,6 @@ Event names:
 
 ## Javascript Components
 
-**TODO - improve this section**
-
 Hyperstack gives you full access to the entire universe of JavaScript libraries and components directly within your Ruby code.
 
 Everything you can do in JavaScript is simple to do in Ruby; this includes passing parameters between Ruby and JavaScript and even passing Ruby methods as JavaScript callbacks. See the JavaScript section for more information.
@@ -1222,9 +1220,9 @@ While it is quite possible to develop large applications purely in Hyperstack Co
 
 Either way you are going to need to import Javascript components into the Hyperstack namespace. Hyperstack provides both manual and automatic mechanisms to do this depending on the level of control you need.
 
-### Importing Components
+### Importing React Components
 
-Lets say you have an existing React Component written in javascript that you would like to access from Hyperstack.  
+Let's say you have an existing React Component written in Javascript that you would like to access from Hyperstack.  
 
 Here is a simple hello world component:
 
@@ -1254,75 +1252,70 @@ end
 
 The `imports` directive takes a string (or a symbol) and will simply evaluate it and check to make sure that the value looks like a React component, and then set the underlying native component to point to the imported component.
 
-### The dom_node method
+### Importing Javascript or React Libraries
 
-Returns the HTML dom_node that this component instance is mounted to.  Typically used in the `after_mount` method to setup linkages to external libraries.
+Importing and using React libraries from inside Hyperstack is very simple and very powerful. Any JavaScript or React based library can be accessible in your Ruby code.
 
-Example:
+Using Webpacker (or Webpack) there are just a few simple steps:
 
-TODO
++ Add the library source to your project using `yarn` or `npm`
++ Import the JavaScript objects you require
++ Package your bundle with `webpack`
++ Use the JavaScript or React component as if it were a Ruby class
 
-### Importing Libraries
+Here is an example of setting up [Material UI](https://material-ui.com/):
 
-Many React components come in libraries.  The `ReactBootstrap` library is one example.  You can import the whole library at once using the `React::NativeLibrary` class.  Assuming that you have initialized `ReactBootstrap` elsewhere, this is how you would bring it into Hyperstack.
+Firstly, you install the library:
 
-```ruby
-class RBS < React::NativeLibrary
-  imports 'ReactBootstrap'
-end
+```
+// with yarn
+yarn add @material-ui/core
+
+// or with npm
+npm install @material-ui/core
 ```
 
-We can now access our bootstrap components as components defined within the RBS scope:
+Next you import the objects you plan to us (or you can import the whole library)
 
 ```ruby
-class Show < HyperComponent
+# app/javascript/packs/hyperstack.js
 
-  def say_hello(i)
-    alert "Hello from number #{i}"
-  end
+# to import the whole library
+import * as Mui from '@material-ui/core';
+global.Mui = Mui;
 
-  render RBS::Navbar, bsStyle: :inverse do
-    RBS::Nav() do
-      RBS::NavbarBrand() do
-        A(href: '#') { 'Hyperstack Showcase' }
-      end
-      RBS::NavDropdown(eventKey: 1, title: 'Things', id: :drop_down) do
-        (1..5).each do |n|
-          RBS::MenuItem(href: '#', key: n, eventKey: "1.#{n}") do
-            "Number #{n}"
-          end.on(:click) { say_hello(n) }
-        end
-      end
-    end
-  end
-end
+# or if you just want one component from the library
+import Button from '@material-ui/core/Button';
+global.Button = Button;
 ```
 
-Besides the `imports` directive, `React::NativeLibrary` also provides a rename directive that takes pairs in the form `oldname => newname`.  For example:
+The run webpack to build your bundle:
 
-```ruby
-  rename 'NavDropdown' => 'NavDD', 'Navbar' => 'NavBar', 'NavbarBrand' => 'NavBarBrand'
+```
+bin/webpack
 ```
 
-`React::NativeLibrary` will import components that may be deeply nested in the library.  For example consider a component was defined as `MyLibrary.MySubLibrary.MyComponent`:
+Now you can use Material UI Components in your Ruby code:
 
 ```ruby
-class MyLib < React::NativeLibrary
-  imports 'MyLibrary'
+# if you imported the whole library
+Mui.Button(variant: :contained, color: :primary) { "Click me" }.on(:click) do
+  alert 'you clicked the button!'
 end
 
-class App < React::NativeLibrary
-  render do  
-    ...
-    MyLib::MySubLibrary::MyComponent ...
-    ...
-  end
+# if you just imported the Button component
+Button(variant: :contained, color: :primary) { "Click me" }.on(:click) do
+  alert 'you clicked the button!'
 end
 ```
 
-Note that the `rename` directive can be used to rename both components and sublibraries, giving you full control over the ruby names of the components and libraries.
+Libraries used often with Hyperstack projects:
 
-### Importing Webpack Images
++ [Material UI](https://material-ui.com/) Google's Material UI as React components
++ [Semantic UI](https://react.semantic-ui.com/) A React wrapper for the Semantic UI stylesheet
++ [ReactStrap](https://reactstrap.github.io/) Bootstrap 4 React wrapper
+
+### Importing Image Assets via Webpack
 
 If you store your images in app/javascript/images directory and want to display them in components, please add the following code to app/javascript/packs/application.js
 
@@ -1354,7 +1347,7 @@ Add the following helper
 
 module ImagesImport
   def img_src(filepath)
-    img_map = Native(`webpackImagesMap`) 
+    img_map = Native(`webpackImagesMap`)
     img_map["./#{filepath}"]
   end
 end
@@ -1377,22 +1370,55 @@ IMG(src: img_src('logo.png'))               # app/javascript/images/logo.png
 IMG(src: img_src('landing/some_image.png')) # app/javascript/images/landing/some_image.png
 ```
 
+### The dom_node method
+
+Returns the HTML dom_node that this component instance is mounted to.  Typically used in the `after_mount` method to setup linkages to external libraries.
+
+Example:
+
+TODO - write example
 
-### Auto Import
+### The `as_node` and `to_n` methods
 
-If you use a lot of libraries and are using a Javascript tool chain with Webpack, having to import the libraries in both Hyperstack and Webpack is redundant and just hard work.
+Sometimes you need to create a Component without rendering it so you can pass it as a parameter of a method. This model is used often in the React world.
 
-Instead you can opt-in for *auto importing* Javascript components into Hyperstack as you need them.  Simply `require hyper-react/auto-import` immediately after you `require hyper-react`.  
+The example below is taken from Semantic UI, building a [Tab Component](https://react.semantic-ui.com/modules/tab/#types-basic) with multiple tabs:
 
-Now you do not have to use component `imports` directive or `React::NativeLibrary` unless you need to rename a component.
+Here is the Javascript example:
 
-In Ruby all module and class names normally begin with an uppercase letter.  However in Javascript this is not always the case, so the auto import will first try the Javascript name that exactly matches the Ruby name, and if that fails it will try the same name with the first character downcased.  For example
+```javascript
+import React from 'react'
+import { Tab } from 'semantic-ui-react'
 
-`MyComponent` will first try `MyComponent` in the Javascript name space, then `myComponent`.
+const panes = [
+  { menuItem: 'Tab 1', render: () => <Tab.Pane>Tab 1 Content</Tab.Pane> },
+  { menuItem: 'Tab 2', render: () => <Tab.Pane>Tab 2 Content</Tab.Pane> },
+]
 
-Likewise MyLib::MyComponent would match any of the following in the Javascript namespace: `MyLib.MyComponent`, `myLib.MyComponent`, `MyLib.myComponent`, `myLib.myComponent`
+const TabExampleBasic = () => <Tab panes={panes} />
+
+export default TabExampleBasic
+```
 
-*How it works:  The first time Ruby hits a native library or component name, the constant value will not be defined.  This will trigger a lookup in the javascript name space for the matching component or library name.  This will generate either a new subclass of HyperComponent or React::NativeLibrary that imports the javascript object, and no further lookups will be needed.*
+And here is the same example converted to Ruby:
+
+```ruby
+# notice we use .as_node to create the Component without rendering it
+tab_1 = Sem.TabPane do
+  P { 'Tab 1 Content' }
+end.as_node
+
+tab_2 = Sem.TabPane do
+  P { 'Tab 2 Content' }
+end.as_node
+
+# notice how we use .to_n to convert the Ruby component to a native JS object
+panes = [ {menuItem: 'Tab 1', render: -> { tab_1.to_n } },
+          {menuItem: 'Tab 2', render: -> { tab_2.to_n } }
+]
+
+Sem.Tab(panes: panes.to_n )
+```
 
 ### Including React Source  
 
@@ -1404,12 +1430,6 @@ However it gets a little tricky if you are using the react-rails gem.  Each vers
 npm install [email protected] [email protected] --save
 ```  
 
-### Using Webpack
-
-Just a word on Webpack: If you a Ruby developer who is new to using Javascript libraries then we recommend using Webpack to manage javascript component dependencies.  Webpack is essentially bundler for Javascript. Please see our Tutorials section for more information.
-
-There are also good tutorials on integrating Webpack with existing rails apps a google search away.
-
 
 ## Elements and Rendering
 

readme.md

@@ -52,6 +52,7 @@ Hyperstack is evolving; we are improving it all the time. As much as we love Rub
 Please see the  [ROADMAP][] file for more information.
 
 [roadmap]: ROADMAP.md
+[current status]: current-status.md
 
 ## Contributing