proofed docs/client-dsl

Author: catmando

.rubocop.yml

@@ -151,3 +151,7 @@ Layout/MultilineMethodCallIndentation:
   Exclude:
     - 'bin/yarn'
     - app/hyperstack/components
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - !ruby/regexp /_spec\.rb$/

docs/README.md

@@ -25,10 +25,10 @@ In the code above, if the `good_books` scope changed \(even on the server\), the
 
 <img align="left" width="100" height="100" style="margin-right: 20px" src="https://github.com/hyperstack-org/hyperstack/blob/edge/docs/wip.png?raw=true">
 
-While we have over 1000 specs passing, in 3 different configurations, and several large apps using Hyperstack, documentation is a lagging.  If you see this icon it means we are working hard to
+While we have over 1000 specs passing in 3 different configurations, and several large apps using Hyperstack, documentation is lagging.  If you see this icon it means we are working hard to
 get the docs up to the same state as the code.
 
-Chapters without the work-in-progress flag, are still draft, and any issues are greatly appreciated, or better yet follow the `Edit on Github` link make your propsed corrections, and submit a pull request.
+Chapters without the work-in-progress flag are still draft, and any issues are greatly appreciated, or better yet follow the `Edit on Github` link, make your proposed corrections, and submit a pull request.
 
 ## Setup and installation
 
@@ -46,7 +46,7 @@ Hyperstack is supported by a friendly, helpful community, both for users, and co
 
 ## Roadmap
 
-We are currently driving towards our 1.0 release.  Currently we are at 1.0.alpha1.5 release candidate.  There is a list of 163 open issues including some bugs, many requested enhancements.  The plan is to triage the issues, and do a weekly release until the issues are closed as deemed not needed for a 1.0 release.  
+We are currently driving towards our 1.0 release.  Currently we are at 1.0.alpha1.5 release candidate.  There is a list of 163 open issues including some bugs, documentation issues and many requested enhancements.  The plan is to triage the issues and do a weekly release until the issues are closed or deemed not needed for a 1.0 release.  
 
 Please consider contributing by grabbing a "good first issue", or just adding your thoughts, thumbs up, or down on any issues that interest you.
 
@@ -55,8 +55,6 @@ Please consider contributing by grabbing a "good first issue", or just adding yo
 In general, if you would like to help in any way, please read the [CONTRIBUTING](https://github.com/hyperstack-org/hyperstack/blob/edge/CONTRIBUTING.md) file for suggestions.  
 System setup for the development of Hyperstack itself is documented in this file.
 
-More specifically, we have a [Feature Matrix](https://github.com/hyperstack-org/hyperstack/blob/edge/docs/feature_matrix.md) that needs to be filled with missing features. The idea is that you can check here what the implementation status is of a Ruby \(on Rails\) feature. And if you have the time and skill you're more then encouraged to implement or fix one or two. But if you're not in a position to contribute code, just expanding and maintaining this table would be excellent.
-
 ## Links
 
 * Rubygems: [https://rubygems.org/profiles/hyperstack](https://rubygems.org/profiles/hyperstack)

docs/client-dsl/component-basics.md

@@ -38,7 +38,7 @@ end
 
 To create a component instance, you reference its class name as a method call from another component. This creates a new instance, passes any parameters and proceeds with the component lifecycle.
 
-> **[The actual type created is an Element read on for details...](/notes.html#component_instances)**
+> **[The actual type created is an Element read on for details...](notes.md#component-instances)**
 
 ```ruby
 class FirstComponent < HyperComponent
@@ -80,7 +80,7 @@ Components can receive new params, causing the component to update.  **[More on
 
 ## Component State
 
-Component also have *state*, which is stored in instance variables.  You signal a state change using the `mutate` method. Component state is a fundamental concept covered **[here](state.md)**.
+Components also have *state*, which is stored in instance variables.  You signal a state change using the `mutate` method. Component state is a fundamental concept covered **[here](state.md)**.
 
 
 ## Life Cycle Callbacks
@@ -101,7 +101,7 @@ class Clock < HyperComponent
 end
 ```
 
-The complete list of life cycle methods and their syntax is discussed in detail in the **[Lifecycle Methods](/lifecycle-methods)** section.
+The complete list of life cycle methods and their syntax is discussed in detail in the **[Lifecycle Methods](lifecycle-methods.md)** section.
 
 ## Events, Event Handlers, and Component Callbacks
 

docs/client-dsl/elements-and-rendering.md

@@ -13,14 +13,14 @@ The only major difference between the systems is that JSX compiles directly to R
 As each React element is generated it is stored by Hyperstack in a *rendering buffer*, and when the component finishes the rendering block, the buffer is returned as the result of the components render callback.  If the expression has a child block (like `DIV { 'hello' }`) the block is passed to the `createElement` as a the child function the same
 as JSX would do.
 
-When an expression like this is evaluated (**[see the full example in the section on params...](/params#named-child-components-as-params)**)
+When an expression like this is evaluated (**[see the full example in the section on params...](../params#named-child-components-as-params)**)
 ```ruby
   Reveal(content: DIV { 'I came from the App' })
 ```
 we need to *remove* the generated `DIV` element *out* of the rendering buffer before passing it to `Reveal`.  This is done automatically by applying the `~` (remove) operator to the
 `DIV` as it is passed on.
 
-In general will never have to manually use the remove (`~`) operator, as React's declarative nature makes storing elements for later use not as helpful in more
+In general you will never have to manually use the remove (`~`) operator, as React's declarative nature makes storing elements for later use not as necessary as in more
 procedural frameworks.
 
 #### Creating Elements Programmatically

docs/client-dsl/events-and-callbacks.md

@@ -115,14 +115,14 @@ no reason not use the `on` method to attach handlers.  Both will keep your code
 The notation `on(:click)` is short for passing a proc to a param named `on_click`.  In general `on(:xxx)` will pass the
 given block as the `on_xxx` parameter in a Hyperstack component and `onXxx` in a JS component.  
 
-All the built-in events and many React libraries follow the `on_xxx` (or `onXxx` in JS.)  However even if a library does not use
+All the built-in events and many React libraries follow the `on_xxx` (or `onXxx` in JS) convention. However even if a library does not use
 this convention you can still attach the handler using `on('<name-of-param>')`.  Whatever string is inside the `<..>` brackets will
 be used as the param name.
 
 Likewise the `fires` method is shorthand for creating a `Proc` param following the `on_xxx` naming convention:
 
 `fires :foo` is short for  
-`param :foo, type: Proc, alias: :foo!`
+`param :on_foo, type: Proc, alias: :foo!`
 
 ### The `Event` Object
 
@@ -147,7 +147,7 @@ Besides the UI there are several other sources of events:
 The way you receive events from these sources depends on the event.  Typically though the method will either take a block, or callback proc, or in many cases will return a Promise.
 Regardless the event handler will do one of three things:  mutate some state within the component, fire an event to a higher level component, or update some shared store.
 
-> For details on updating shared stores, which is often the best answer **[see the chapter on HyperState...](/hyper-state.md)**
+> For details on updating shared stores, which is often the best answer **[see the chapter on HyperState...](../hyper-state.md)**
 
 You have seen the `every` method used to create events throughout this chapter, here is an example with an HTTP post (which returns a promise.)
 

docs/client-dsl/javascript-components.md

@@ -2,9 +2,9 @@
 
 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 Opal-Ruby; this includes passing parameters between Ruby and JavaScript and even passing Ruby methods as JavaScript callbacks. See the JavaScript section for more information.
+Everything you can do in JavaScript is simple to do in Opal-Ruby; this includes passing parameters between Ruby and JavaScript and even passing Ruby methods as JavaScript callbacks.
 
-> **[For more information on writing Javascript within your Ruby code...](/notes.md#Javascript)**
+> **[For more information on writing Javascript within your Ruby code...](notes.md#javascript)**
 
 ## Importing Javascript or React Libraries
 
@@ -64,7 +64,7 @@ Libraries used often with Hyperstack projects:
 
 ### Making Custom Wrappers - WORK IN PROGRESS ...
 
-Hyperstack will automatically import Javascript components and component libraries as discussed above.  Sometimes for
+<img align="left" width="100" height="100" style="margin-right: 20px" src="https://github.com/hyperstack-org/hyperstack/blob/edge/docs/wip.png?raw=true"> Hyperstack will automatically import Javascript components and component libraries as discussed above.  Sometimes for
 complex libraries that you will use a lot it is useful to add some syntactic sugar to the wrapper.
 
 This can be done using the `imports` directive and the `Hyperstack::Component::NativeLibrary` superclass.
@@ -134,7 +134,7 @@ finally require it in your hyper_component.rb file:
 
 require 'hyperstack/component/jquery'
 ```
-You can access jQuery anywhere in your code using the `Element` or the `jQ` methods.
+You can access jQuery anywhere in your code using the `jQ` method.
 For details see https://github.com/opal/opal-jquery
 
 > Note most of the time you will not need to manipulate the dom directly.

docs/client-dsl/lifecycle-methods.md

@@ -10,7 +10,7 @@ A component may define lifecycle methods for each phase of the components lifecy
 * `render` will be called again here
 * `after_update`
 * `before_unmount`
-* `rescues` The `rescues` callback is described **[here...](/error-recovery.md)**
+* `rescues` The `rescues` callback is described **[here...](error-recovery.md)**
 
 All the Component Lifecycle methods (except `render`) may take a block or the name(s) of instance method(s) to be called.  The `render` method always takes a block.
 
@@ -21,7 +21,7 @@ class MyComponent < HyperComponent
   end
 
   render do
-    # return some elements 
+    # return some elements
   end
 
   before_unmount :cleanup  # call the cleanup method before unmounting

docs/client-dsl/methods.md

@@ -5,7 +5,7 @@ class.  You may also use any other Ruby constructs such as method definition as
 you would in any Ruby class.
 
 **Interface Definition**
-These methods define the signature of the components params.
+These methods define the signature of the component's params.
 + `param(*args)` - specifies params and creates accessor methods
 + `fires(name, alias: internal_name)` - specifies an event call-back
 + `others(name)` accessor method that collects all params not otherwise specified
@@ -27,16 +27,16 @@ define multiple handlers for each callback.
 + `rescues(*klasses_to_rescue, &block)`
 
 **State Management**
-Each component instance has internal state represented by the contents of instance variables,
-changes to the state is signaled using the instance `mutate` method.  The following methods
-define instance methods that access state with builtin calls to the mutate method.
+Each component instance has internal state represented by the contents of instance variables:
+changes to the state is signaled using the `mutate` method.  The following methods
+define additional instance methods that access state with built-in calls to the mutate method.
 + `mutator` defines an *instance* method with a built-in mutate.
 + `state_reader` creates an *instance* state read only accessor method.
 + `state_writer` creates an *instance* state write only accessor method.
 + `state_accessor` creates *instance* reader and writer methods.
 
 **Other Class Level Methods**
-+ `mounted_components` - returns array of all currently mounted components of this class and subclasses
++ `mounted_components` - returns an array of all currently mounted components of this class and subclasses
 + `force_update!` forces all components in this class and its subclasses to update
 + `create_element(*params, &children)` - create an element from this class
 + `insert_element(*params, &children)` - create and insert an element into the rendering buffer

docs/client-dsl/notes.md

@@ -295,3 +295,20 @@ You may also turn off the autoimport function if necessary in your `hyperstack.r
 # do not use the auto-import module
 Hyperstack.cancel_import    'hyperstack/component/auto-import'
 ```
+
+### The Enter Event
+```ruby
+class YouSaid < HyperComponent
+  state_accessor :value
+  render(DIV) do
+    INPUT(value: value)
+    .on(:enter) do
+      alert "You said: #{value}"
+      self.value = ""
+    end
+    .on(:change) do |e|
+      self.value = e.target.value
+    end
+  end
+end
+```

docs/client-dsl/params.md

@@ -84,6 +84,7 @@ class App < HyperComponent
   end
 end
 ```
+[see the spec...](https://github.com/hyperstack-org/hyperstack/blob/24131990ea1cdacfc9efc328d4994a7c2d86a0f4/docs/specs/spec/client-dsl/params_spec.rb#L4-L25)
 
 `render` is used to render the child components. **[For details ...](component-details.md#rendering-children)**
 
@@ -163,7 +164,7 @@ end
 Even though we have not gotten to event handlers yet, you can see what is going on:  When we click the update button we call `force_update!`
 which will force the `App` component to rerender.
 > By the way `force_update!` is almost never used, but we are using it here
-just to make the example clear.)
+just to make the example clear.  Its also one of the reasons this example gets into trouble. Read on!
 
 Will `Comp2` rerender?  No - because even though we are creating a new hash, the old hash and new hash are equal in value.
 
@@ -194,5 +195,5 @@ So when we compare *old* verses *new* we are comparing the same object, so the v
 
 That does not seem like a very happy ending, but the case we used was not very realistic.  If you stick to passing simple scalars, or hashes and arrays
 whose values don't change after they have been passed, things will work fine.  And for situations where you do need to store and
-manipulate complex data, you can use the **[the Hyperstack::Observable module](/hyper-state/README.md)** to build safe classes that don't
+manipulate complex data, you can use the **[the Hyperstack::Observable module](../hyper-state/README.md)** to build safe classes that don't
 have the problems seen above.