hyper-router 1.0.alpha1.5 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 6ea9c2324b2513fc2c1e52621e49f5e78cebaa1d42cc5bec7f4b1acc82793b0f
-  data.tar.gz: 04dab8146079a46ce5f3d9b9912f960f06de8ee07f77933375f9287f1b91f18f
+SHA1:
+  metadata.gz: 42539f6d1b24ec189cee24a5fa1bef54ab185b20
+  data.tar.gz: 7cde99e5959c6c002100afc45f37c1bee5296e8f
 SHA512:
-  metadata.gz: 03272c353f3f21cd38c437aa130b0c0bd4ecd1f750868c3643ff4851323895c4bb1657e20bcb40a5e4ca9e8d38c27afa2e379660740994d2e62d5bd4b673b2ff
-  data.tar.gz: 545c37f9186f8d24400d70edd0e8fb36878ecdd5707645f13f231d9f3576ff9e7299afb4521d3e5a2efad141132539a6b2725439f53124a9850d409a074d6038
+  metadata.gz: ee4d5bee2df7fed2d2ee91cb622cd639105d2e5990f3b81ac9045192e4499a6ca41cc37dfbd7744ce9a660de536b7ca8ac4c62dea32681a3c777ea0933edaa03
+  data.tar.gz: 94fea592a8cb1bee3c186dc5ce3d3acfd14b556bc456e355d56e257807cafb9766bb36e1a3cf4673484a13fcd71e21a0b5a39baf0153a1fe5438b8d5bcf4616f

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 catprintlabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,393 @@
+## HyperRouter
+
+HyperRouter allows you write and use the React Router in Ruby through Opal.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hyper-router'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+This is simply a DSL wrapper on [react-router](....)
+
+### DSL
+
+The following DSL:
+
+```ruby
+route("/", mounts: App, index: Home) do
+  route("about")
+  route("inbox") do
+    redirect('messages/:id').to { | params | "/messages/#{params[:id]}" }
+  end
+  route(mounts: Inbox) do
+    route("messages/:id")
+  end
+end
+```
+
+Is equivalent to this route configuration:
+
+```javascript
+const routes = {
+  path: '/',
+  component: App,
+  indexRoute: { component: Dashboard },
+  childRoutes: [
+    { path: 'about', component: About },
+    {
+      path: 'inbox',
+      component: Inbox,
+      childRoutes: [{
+        path: 'messages/:id',
+        onEnter: ({ params }, replace) => replace(`/messages/${params.id}`)
+      }]
+    },
+    {
+      component: Inbox,
+      childRoutes: [{
+        path: 'messages/:id', component: Message
+      }]
+    }
+  ]
+}
+```
+
+The basic dsl syntax is designed with the following in mind:
+
+1. Most routes have a path so that is the assumed first argument.
+2. Use `mounts` rather than component (reads better?)
+3. Convention over configuration, given a path, the component name can be derived.
+4. Redirect takes the path, and a block (similar to the JSX DSL)
+5. The first param to route can be skipped per the documentation
+6. Use standard ruby lower case method names instead of caps (reserve those for components)
+
+The above example does not cover all the possible syntax, here are the other methods and options:
+
+#### enter / leave / change transition hooks
+
+for adding an onEnter or onLeave hook you would say:
+
+```ruby
+route("foo").on(:leave) { | t | ... }.on(:enter) { | t |.... }
+```
+which follows the react.rb event handler convention.
+
+A `TransitionContext` object will be passed to the handler, which has the following methods:
+
+| method | available on | description |
+|-----------|------------------|-----------------|
+| `next_state` | `:change`, `:enter` | returns the next state object |
+| `prev_state` | `:change` | returns the previous state object |
+| `replace` | `:change`, `:enter` | pass `replace` a new path |
+| `promise` | `:change`, `:enter` | returns a new promise.  multiple calls returns the same promise |
+
+If you return a promise from the `:change` or `:enter` hooks, the transition will wait till the promise is resolved before proceeding.  For simplicity you can call the promise method, but you can also use some other method to define the promise.
+
+The hooks can also be specified as proc values to the `:on_leave`, `:on_enter`, `:on_change` options.
+
+#### multiple component mounting
+
+The `mounts` option can accept a single component, or a hash which will generate a `components` (plural) react-router prop, as in:
+
+`route("groups", mounts: {main: Groups, sidebar: GroupsSidebar})` which is equivalent to:
+
+`{path: "groups", components: {main: Groups, sidebar: GroupsSidebar}}` (json) or
+
+`<Route path="groups" components={{main: Groups, sidebar: GroupsSidebar}} />` JSX
+
+#### The `mounts` option can also take a `Proc` or be specified as a block
+
+The proc is passed a TransitionContext (see **Hooks** above) and may either return a react component to be mounted, or return a promise.  If a promise is returned the transition will wait till the promise is either resolved with a component, or rejected.
+
+`route("courses/:courseId", mounts: -> () { Course }`
+
+is the same as:
+
+```jsx
+<Route path="courses/:courseId" getComponent={(nextState, cb) => {cb(null, Course)}} />
+```
+
+Also instead of a proc, a block can be specified with the `mounts` method:
+
+`route("courses/:courseId").mounts { Course }`
+
+Which generates the same route as the above.
+
+More interesting would be something like this:
+
+```ruby
+route("courses/:id").mounts do | ct |
+  HTTP.get("validate-user-access/courses/#{ct.next_state[:id]}").then {  Course }
+end
+```
+
+*Note that the above works because of promise chaining.*
+
+You can use the `mount` method multiple times with different arguments as an alternative to passing the the `mount` option a hash:
+
+`route("foo").mount(:baz) { Comp1 }.mount(:bar) { Comp2 }.mount(:bomb)`
+
+Note that if no block is given (as in `:bomb` above) the component name will be inferred from the argument (`Bomb` in this case.)
+
+#### The index component can be specified as a proc
+
+Same deal as mount...
+
+`route("foo", index: -> { MyIndex })`
+
+#### The index method
+
+Instead of specifying the index component as a param to the parent route, it can be specified as a child using the
+index method:
+
+```ruby
+route("/", mounts: About, index: Home) do
+  index(mounts: MyIndex)
+  route("about")
+  route("privacy-policy")
+end
+```
+
+This is useful because the index method has all the features of a route except that it does not take a path or children.
+
+#### The `redirect` options
+
+with static arguments:
+
+`redirect("/from/path/spec", to: "/to/path/spec", query: {q1: 123, q2: :abc})`
+
+the `:to` and `:query` options can be Procs which will receive the current state.
+
+Or you can specify the `:to` an `:query` options with blocks:
+
+`redirect("/from/path/spec/:id").to { |curr_state| "/to/path/spec/#{current_state[:id]}"}.query { {q1: 12} }`
+
+#### The `index_redirect` method
+
+just like `redirect` without the first arg: `index_redirect(to: ... query: ...)`
+
+### The Router Component
+
+A router is defined as a subclass of `React::Router` which is itself a `React::Component::Base`.
+
+```ruby
+class Components::Router < React::Router
+  def routes # define your routes (there is no render method)
+    route("/", mounts: About, index: Home) do
+      route("about")
+      route("inbox") do
+        redirect('messages/:id').to { | params | "/messages/#{params[:id]}" }
+      end
+      route(mounts: Inbox) do
+        route("messages/:id")
+      end
+    end
+  end  
+end
+```
+#### Mounting your Router
+You will mount this component the usual way (i.e. via `render_component`, `Element#render`, `react_render`, etc) or even by mounting it within a higher level application component.
+
+```ruby
+class Components::App < React::Component::Base
+  render(DIV) do
+    Application::Nav()
+    MAIN do
+      Router()
+    end
+  end
+end
+```
+
+#### navigating
+
+Create links to your routes with `Router::Link`
+```ruby
+#Application::Nav
+  LI.nav_link { TestRouter::Link("/") { "Home" } }
+  LI.nav_link { TestRouter::Link("/about") { "About" } }
+  params.messsages.each do |msg|
+    LI.nav_link { TestRouter::Link("/inbox/messages/#{msg.id}") { msg.title } }
+  end
+```
+
+Additionally, you can manipulate the history with by passing JS as so
+```ruby
+# app/views/components/app_links.rb
+class Components::AppLinks
+  class << self
+    if RUBY_ENGINE == 'opal'
+      def inbox
+        `window.ReactRouter.browserHistory.push('/inbox');`
+      end
+      def message(id)
+        `window.ReactRouter.browserHistory.push('/messages/#{id}');`
+      end
+    end
+  end
+end
+```
+
+
+#### Other router hooks:
+
+There are several other methods that can be redefined to modify the routers behavior
+
+#### history
+
+```ruby
+class Router < React::Router
+  def history
+  ... return a history object
+  end
+end
+```
+
+The two standard history objects are predefined as `browser_history` and `hash_history` so you can say:
+
+```ruby
+...
+  def history
+    browser_history
+  end
+```
+
+or just
+
+```ruby
+...
+  alias_method :history :browser_history
+```
+
+#### create_element
+
+`create_element` (if defined) is passed the component that the router will render, and its params.  Use it to intercept, inspect and/or modify the component behavior.
+
+`create_element` can return any of these values:
+
++ Any falsy value: indicating that rendering should continue with no modification to behavior.
++ A `React::Element`, or a native `React.Element` which will be used for rendering.
++ Any truthy value: indicating that a new Element should be created using the (probably modified) params
+
+```ruby
+class Router < React::Router
+  def create_element(component, component_params)
+    # add the param :time_stamp to each element as its rendered
+    React.create_element(component, component_params.merge(time_stamp: Time.now))
+  end
+end
+```
+
+The above could be simplified to:
+
+```ruby
+...
+  def create_element(component, component_params)
+    component_params[:time_stamp] = Time.now
+  end
+```
+
+Just make sure that you return a truthy value otherwise it will ignore any changes to component or params.
+
+Or if you just wanted some kind of logging:
+
+```ruby
+...
+  def create_element(component, component_params)
+    puts "[#{Time.now}] Rendering: #{component.name}" # puts returns nil, so we are jake mate
+  end
+```
+
+The component_params will always contain the following keys as native js objects, and they must stay native js objects:
+
++ `children`
++ `history`
++ `location`
++ `params`
++ `route`
++ `route_params`
++ `routes`
+
+We will try to get more fancy with a later version of reactrb-router ;-)
+
+#### `stringify_query(params_hash)` <- needs work
+
+The method used to convert an object from <Link>s or calls to transitionTo to a URL query string.
+
+```ruby
+class Router < React::Router
+  def stringify_query(params_hash)
+    # who knows doc is a little unclear on this one...is it being passed the full params_hash or just
+    # the query portion.... we shall see...
+  end
+end
+```
+
+#### `parse_query_string(string)` <- needs work
+
+The method used to convert a query string into the route components's param hash
+
+#### `on_error(data)`
+
+While the router is matching, errors may bubble up, here is your opportunity to catch and deal with them. Typically these will come when promises are rejected (see the DSL above for returning promises to handle async behaviors.)
+
+#### `on_update`
+
+Called whenever the router updates its state in response to URL changes.
+
+#### `render`
+
+A `Router` default `render` looks like this:
+
+```ruby
+  def render
+    # Router.router renders the native router component
+    Router.router(build_params)
+  end
+```
+
+
+This is primarily for integrating with other libraries that need to participate in rendering before the route components are rendered. It defaults to render={(props) => <RouterContext {...props} />}.
+
+Ensure that you render a <RouterContext> at the end of the line, passing all the props passed to render.
+
+### React::Router::Component
+
+The class React::Router::Component is a subclass of React::Component::Base that predefines the params that the router will be passing in to your component.  This includes
+
+`params.location`
+
+The current location.
+
+`params.params`
+
+The dynamic segments of the URL.
+
+`params.route`
+
+The route that rendered this component.
+
+`params.route_params`
+
+The subset of `params.params` that were directly specified in this component's route. For example, if the route's path is `users/:user_id` and the URL is /users/123/portfolios/345 then `params.route_params` will be `{user_id: '123'}`, and `params.params` will be `{user_id: '123', portfolio_id: 345}`.
+
+## Development
+
+`bundle exec rake` runs test suite
+
+## Contributing
+
+1. Fork it ( https://github.com/ruby-hyperloop/reactrb-router/tree/hyper-router/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -1,11 +1,32 @@
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+require 'bundler'
+Bundler.require
+Bundler::GemHelper.install_tasks
 
-namespace :spec do
-  task :prepare do
-  end
+
+require 'rspec/core/rake_task'
+require 'opal/rspec/rake_task'
+
+RSpec::Core::RakeTask.new('ruby:rspec') do |s|
+  s.rspec_opts = "--tag ruby"
+end
+Opal::RSpec::RakeTask.new('opal:rspec') do |s|
+  s.append_path 'spec/vendor'
+  s.index_path = 'spec/index.html.erb'
+end
+
+task :test do
+  Rake::Task['ruby:rspec'].invoke
+  Rake::Task['opal:rspec'].invoke
+end
+
+require 'generators/reactive_ruby/test_app/test_app_generator'
+desc "Generates a dummy app for testing"
+task :test_app do
+  ReactiveRuby::TestAppGenerator.start
+  puts "Setting up test app database..."
+  system("bundle exec rake db:drop db:create db:migrate > #{File::NULL}")
 end
 
-task :default => :spec
+task default: [ :test ]