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

Author: catmando

docs/dsl-client/hyper-component.md

@@ -1430,6 +1430,154 @@ However it gets a little tricky if you are using the react-rails gem.  Each vers
 npm install [email protected] [email protected] --save
 ```  
 
+## Single Page Application CRUD example
+
+Rails famously used scaffolding for Model CRUD (Create, Read, Update and Delete). There is no scaffolding in Hyperstack today, so here is an example which demonstrates how those simple Rails pages would work in Hyperstack.
+
+This example uses components from the [Material UI](https://material-ui.com/) framework, but the principals would be similar for any framework (or just HTML elements).
+
+In this example, we will have a table of users and the ability to add new users or edit a user from the list. As the user edits the values in the UserDialog, they will appear in the underlying table. You can avoid this behaviour if you choose by copying the values in the `before_mount` of the UserDialog, so you are not interacting with the model directly.
+Firstly the table of users:
+
+
+```ruby
+class UserIndex < HyperComponent
+  render(DIV, class: 'mo-page') do
+    UserDialog(user: User.new) # this will render as a button to add users
+    Table do
+      TableHead do
+        TableRow do
+          TableCell { 'Name' }
+          TableCell { 'Gender' }
+          TableCell { 'Edit' }
+        end
+      end
+      TableBody do
+        user_rows
+      end
+    end
+  end
+
+  def user_rows
+    User.each do |user| # note User is a Hyperstack model (see later in the Isomorphic section)
+      TableRow do
+        TableCell { "#{user.first_name} #{user.last_name}" }
+        TableCell { user.is_female ? 'Female' : 'Male' }
+        # note the use of key so React knows which Component this refers to
+        # this is very important for performance and to ensure the component is used
+        TableCell { UserDialog(user: user, key: user.id) } # this will render as an edit button
+      end
+    end
+  end
+end
+```
+
+Then we need the actual Dialog (Modal) component:
+
+```ruby
+class UserDialog < HyperComponent
+  param :user
+
+  before_mount do
+    @open = false
+  end
+
+  render do
+    if @open
+      render_dialog
+    else
+      edit_or_new_button.on(:click) { mutate @open = true }
+    end
+  end
+
+  def render_dialog
+    Dialog(open: @open, fullWidth: false) do
+      DialogTitle do
+        'User'
+      end
+      DialogContent do
+        content
+        error_messages if @User.errors.any?
+      end
+      DialogActions do
+        actions
+      end
+    end
+  end
+
+  def edit_or_new_button
+    if @User.new?
+      Fab(size: :small, color: :primary) { Icon { 'add' } }
+    else
+      Fab(size: :small, color: :secondary) { Icon { 'settings' } }
+    end
+  end
+
+  def content
+    FormGroup(row: true) do
+      # note .to_s to specifically cast to a String
+      TextField(label: 'First Name', value: @User.first_name.to_s).on(:change) do |e|
+        @User.first_name = e.target.value
+      end
+      TextField(label: 'Last Name', value: @User.last_name.to_s).on(:change) do |e|
+        @User.last_name = e.target.value
+      end
+    end
+
+    BR()
+
+    FormLabel(component: 'legend') { 'Gender' }
+    RadioGroup(row: true) do
+      FormControlLabel(label: 'Male',
+                       control: Radio(value: false, checked: !is_checked(@User.is_female)).as_node.to_n)
+      FormControlLabel(label: 'Female',
+                       control: Radio(value: true, checked: is_checked(@User.is_female)).as_node.to_n)
+    end.on(:change) do |e|
+      @User.is_female = e.target.value
+    end
+  end
+
+  def is_checked value
+    # we need a true or false and not an object
+    value ? true : false
+  end
+
+  def actions
+    Button { 'Cancel' }.on(:click) { cancel }
+
+    if @User.changed? && validate_content
+      Button(color: :primary, variant: :contained, disabled: (@User.saving? ? true : false)) do
+        'Save'
+      end.on(:click) { save }
+    end
+  end
+
+  def save
+    @User.save(validate: true).then do |result|
+      mutate @open = false if result[:success]
+    end
+  end
+
+  def cancel
+    @User.revert
+    mutate @open = false
+  end
+
+  def error_messages
+    @User.errors.full_messages.each do |message|
+      Typography(variant: :h6, color: :secondary) { message }
+    end
+  end
+
+  def validate_content
+    return false if @User.first_name.to_s.empty?
+    return false if @User.last_name.to_s.empty?
+    return false if @User.is_female.nil?
+
+    true
+  end
+end
+```
 
 ## Elements and Rendering
 

docs/dsl-client/hyper-store.md

@@ -1,7 +1,6 @@
 # Stores
 
-**Work in progress - ALPHA (docs and code)**
-**These docs are out of date**
+**These docs are out of date - please ignore this section until it is updated**
 
 Hyperstack **Stores** are implemented in the **HyperStore Gem**.
 

docs/installation/upgrading.md

@@ -1,5 +1,214 @@
 # Upgrading from legacy Hyperloop
 
-These instructions are subject to change as the project matures.
+This guide sets out to provide the steps necessary to move an existing project from legacy Hyperloop to Hyperstack. There are a number of changes which need to be considered.
 
-TBD
+## Summary of changes
+
++ Creating a new Hyperstack Rails application
++ New Hyperstack gems
++ Renamed folders
++ Hyperstack configuration
++ Hyperloop classes have been renamed Hyperstack
++ There is a new concept of a base `HyperComponent` and `HyperStore` base class
++ State syntax has changed
++ Param syntax has changed
++ The Router DSL has changed slightly
+
+## Creating a new Hyperstack Rails application
+
+In Hyperstack we are using Rails templates to create new applications.
+
++ Follow these instructions: https://github.com/hyperstack-org/hyperstack/tree/edge/install
++ See the template for an understanding of the installation steps: https://github.com/hyperstack-org/hyperstack/blob/edge/install/rails-webpacker.rb
+
+**If you are not upgrading an existing Hyoperloop application, you do not need to follow the rest of these instructions.**
+
+## Hyperstack gem
+
+Hyperstack (with Rails) requires just one Gem:
+
+```ruby
+# gem 'webpacker' # if you are using webpacker
+gem 'rails-hyperstack'
+```
+
+Delete all Hyperloop gems from your gemfile and do a `bundle update`.
+
+## Renamed folders
+
++ `app/hyperloop` has become `app/hyperstack`
++ The sub-folder structure has not changed (components, models, stores, etc)
+
+## Hyperstack configuration
+
++ `config/initializers/hyperloop.rb` has been renamed `config/initializers/hyperstack.rb`
+
+The configuration initialiser has changed a little. Please see this page for details: https://github.com/hyperstack-org/hyperstack/blob/edge/docs/installation/config.md
+
+## Hyperloop classes have been renamed Hyperstack
+
+In all cases, `Hyperloop` has been replaced with `Hyperstack`. For example:
+
+In Hyperloop:
+
+```ruby
+Hyperloop::Application.acting_user_id
+```
+In Hyperstack becomes:
+
+```ruby
+Hyperstack::Application.acting_user_id
+```
+
+The simplest way to implement this change is a global search and replace in your project.
+
+## There is a new concept of a base HyperComponent and HyperStore base class
+
+In Hyperloop, all Components and Stores inherited from a base `Hyperloop::Component` class. In HyperStack (following the new Rails convention), we do not provide the base class but encourage you to create your own. This is very useful for containing methods that all your Components share.
+
+To implement this change, you need to create your HyperComponent class:
+
+```ruby
+class HyperComponent
+  include Hyperstack::Component
+  include Hyperstack::State::Observable # if you are using state
+  include Hyperstack::Router::Helpers # if you are using the router
+
+  def some_shared_method
+    # a helper method that all your Component might need
+  end
+end
+```
+
+Then you need to do a search and replace on all your `Hyperloop::Component` classes and replace them with `HyperComponent`. For example:
+
+In Hyperloop:
+
+```ruby
+class MyComp < Hyperloop::Component
+  render do
+    ...
+  end
+end
+```
+
+In Hyperstack becomes:
+
+```ruby
+class MyComp < HyperComponent
+  render do
+    ...
+  end
+end
+```
+
+`HyperComponent` is explained here: https://github.com/hyperstack-org/hyperstack/blob/edge/docs/dsl-client/hyper-component.md#hypercomponent
+
+
+**The same is true for `Hyperloop::Store` to `HyperStore`**.
+
+You will need to create a `HyperStore` class and make the same changes as above.
+
+Note that in Hyperstack, any ruby class can be a store by merely including the `include Hyperstack::State::Observable` mixin.
+
+For example:
+
+```ruby
+class StoresAreUs
+  include Hyperstack::State::Observable
+
+  def store_something thing
+    mutate @thing = thing # note the new mutate syntax
+  end
+end
+```
+
+## State syntax has changed
+
+In Hyperloop you mutated state like this:
+
+```ruby
+mutate.something true
+```
+
+In Hyperstack becomes:
+
+```ruby
+mutate @something = true
+```
+
+You also use reference in a different way:
+
+In Hyperloop:
+
+```ruby
+H1 { 'Yay' } if state.something
+```
+
+In Hyperstack becomes:
+
+```ruby
+H1 { 'Yay' } if @something
+```
+
+There are several advantages to this new approach:
+
++ It is significantly faster (ask Mitch)
++ It feels more natural to think about state variables as normal instance variables
++ You only use the `mutate` method when you want React to re-render based on the change to state. This gives you more control.
++ You can string mutations together. For example:
+
+```ruby
+mutate @something = true, @amount = 100, @living = :good
+```
+
+You can read more about state here: https://github.com/hyperstack-org/hyperstack/blob/edge/docs/dsl-client/hyper-component.md#state
+
+## Param syntax has changed
+
+The syntax for using params has changed:
+
+In Hyperloop:
+
+```ruby
+class SayHello < Hyper::Component
+  param :first_name
+
+  render do
+    H1 { "Hello #{params.first_name}" }
+  end
+```
+
+In Hyperstack becomes:
+
+```ruby
+class SayHello < HyperComponent
+  param :first_name
+
+  render do
+    H1 { "Hello #{@FirstName}" } # Note the conversion of snake_case to CamelCase
+  end
+```
+
+This change has been made to underline that params are immutable. (Though this is not true for Models, but they get the same CamelCase treatment).
+
+You can read more about this here: https://github.com/hyperstack-org/hyperstack/blob/edge/docs/dsl-client/hyper-component.md#params
+
+## The Router DSL has changed slightly
+
+Routers are now normal Components with a render method.
+
+A Hyperstack router looks like this:
+
+```ruby
+class MainFrame < HyperComponent
+  include Hyperstack::Router # note the inclusion of the Router mixin
+
+  render(DIV) do # note the render method
+    Switch do
+      Route('/', exact: true, mounts: HomeIndex)
+      Route('/app', exact: true, mounts: AppIndex)
+    end
+  end
+end
+```