hyper-router 2.4.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d049a9896020bcede09745f990b68f1714b09fe
-  data.tar.gz: 894dd7c5cc038f0dea86f0e39fa05f3832ba91e3
+  metadata.gz: 77e89bd0516ef8221fa2520ca3959c01b3310818
+  data.tar.gz: 33a47f5a63a77de06ab7d13947cdc53d7997dc07
 SHA512:
-  metadata.gz: b6fe35cae68685cbeee3b972c0379b9273aa2a93d8bd90780bb2185011e2f727f500f9eab141156889d9ba850eb118585a800de7d792317dea53bd0617934206
-  data.tar.gz: 52b5511e0343a4279ac9d3510734f7ba2394c1f6d7748c10035ddca5fd784eb8d1d45bb6ae5ed2e184f1bc47c92647cb6c5682582fc0b3cef9ea4de9c40c66cb
+  metadata.gz: 8c78ae7c11bc1942b5f46ba15626cf87f879f4059a4716723d937dc463ef216c1606a845ab9c895b4215ddf22c2163cacf07336c259e4c1c4d92c2a680a6071b
+  data.tar.gz: 164b196fce9e58159800e1dc44ed33830c24dd24e49cc8274a1a0b1f96be6c84401da08be1ec6422f0734d5dd41b2c15902944b33b58e4aa25d8be4ccfad967e

data/README.md

@@ -1,384 +1,446 @@
-#  ![](https://github.com/Serzhenka/hyper-loop-logos/blob/master/hyper-router_150.png)Hyper-router
+## HyperRouter
 
-The Hyperloop Router allows you write and use the React Router in Ruby through Opal.
+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'
 ```
+Or execute:
+```bash
+gem install hyper-router
+```
 
-And then execute:
-
-    $ bundle
-
-## Usage
-
-This is simply a DSL wrapper on [react-router](....)
-
-### DSL
-
-The following DSL:
+Then add this to your components.rb:
+```ruby
+require 'hyper-router'
+```
 
+### Using the included source
+Add this to your component.rb:
 ```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
+require 'hyper-router/react-router-source'
+require 'hyper-router'
 ```
 
-Is equivalent to this route configuration:
+### Using with NPM/Webpack
+react-router has now been split into multiple packages, so make sure they are all installed
+```bash
+npm install react-router react-router-dom history --save
+```
 
+Add these to your webpack js file:
 ```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
-      }]
-    }
-  ]
-}
+ReactRouter = require('react-router')
+ReactRouterDOM = require('react-router-dom')
+History = require('history')
 ```
 
-The basic dsl syntax is designed with the following in mind:
+## Usage
 
-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)
+This is simply a DSL wrapper on [react-router](https://github.com/ReactTraining/react-router)
 
-The above example does not cover all the possible syntax, here are the other methods and options:
+## Warning!!
+The folks over at react-router have gained a reputation for all their API rewrites, so with V4 we have made some changes to follow.
+This version is **incompatible** with previous versions' DSL.
 
-#### enter / leave / change transition hooks
+### DSL
 
-for adding an onEnter or onLeave hook you would say:
+Here is the basic example that is used on the [react-router site](https://reacttraining.com/react-router/)
 
-```ruby
-route("foo").on(:leave) { | t | ... }.on(:enter) { | t |.... }
+```javascript
+import React from 'react'
+import {
+  BrowserRouter as Router,
+  Route,
+  Link
+} from 'react-router-dom'
+
+const BasicExample = () => (
+  <Router>
+    <div>
+      <ul>
+        <li><Link to="/">Home</Link></li>
+        <li><Link to="/about">About</Link></li>
+        <li><Link to="/topics">Topics</Link></li>
+      </ul>
+
+      <hr/>
+
+      <Route exact path="/" component={Home}/>
+      <Route path="/about" component={About}/>
+      <Route path="/topics" component={Topics}/>
+    </div>
+  </Router>
+)
+
+const Home = () => (
+  <div>
+    <h2>Home</h2>
+  </div>
+)
+
+const About = () => (
+  <div>
+    <h2>About</h2>
+  </div>
+)
+
+const Topics = ({ match }) => (
+  <div>
+    <h2>Topics</h2>
+    <ul>
+      <li><Link to={`${match.url}/rendering`}>Rendering with React</Link></li>
+      <li><Link to={`${match.url}/components`}>Components</Link></li>
+      <li><Link to={`${match.url}/props-v-state`}>Props v. State</Link></li>
+    </ul>
+
+    <Route path={`${match.url}/:topicId`} component={Topic}/>
+    <Route exact path={match.url} render={() => (
+      <h3>Please select a topic.</h3>
+    )}/>
+  </div>
+)
+
+const Topic = ({ match }) => (
+  <div>
+    <h3>{match.params.topicId}</h3>
+  </div>
+)
+
+export default BasicExample
 ```
-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
+Here is what it looks like for us:
+```ruby
+class BasicExample < Hyperloop::Router
+  history :browser
+
+  route do
+    DIV do
+      UL do
+        LI { Link('/') { 'Home' } }
+        LI { Link('/about') { 'About' } }
+        LI { Link('/topics') { 'Topics' } }
+      end
 
-The `mounts` option can accept a single component, or a hash which will generate a `components` (plural) react-router prop, as in:
+      Route('/', exact: true, mounts: Home)
+      Route('/about', mounts: About)
+      Route('/topics', mounts: Topics)
+    end
+  end
+end
 
-`route("groups", mounts: {main: Groups, sidebar: GroupsSidebar})` which is equivalent to:
+class Home < Hyperloop::Router::Component
+  render(:div) do
+    H2 { 'Home' }
+  end
+end
 
-`{path: "groups", components: {main: Groups, sidebar: GroupsSidebar}}` (json) or
+class About < Hyperloop::Router::Component
+  render(:div) do
+    H2 { 'About' }
+  end
+end
 
-`<Route path="groups" components={{main: Groups, sidebar: GroupsSidebar}} />` JSX
+class Topics < Hyperloop::Router::Component
+  render(:div) do
+    H2 { 'Topics' }
+    UL() do
+      LI { Link("#{match.url}/rendering") { 'Rendering with React' } }
+      LI { Link("#{match.url}/components") { 'Components' } }
+      LI { Link("#{match.url}/props-v-state") { 'Props v. State' } }
+    end
+    Route("#{match.url}/:topic_id", mounts: Topic)
+    Route(match.url, exact: true) do
+      H3 { 'Please select a topic.' }
+    end
+  end
+end
 
-#### The `mounts` option can also take a `Proc` or be specified as a block
+class Topic < Hyperloop::Router::Component
+  render(:div) do
+    H3 { match.params[:topic_id] }
+  end
+end
+```
 
-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.
+Since react-router migrated back to everything being a component,
+this makes the DSL very easy to follow if you have already used react-router v4.
 
-`route("courses/:courseId", mounts: -> () { Course }`
+### Router
 
-is the same as:
+This is the base Router class, it can either be inherited or included:
+```ruby
+class MyRouter < Hyperloop::Router
+end
 
-```jsx
-<Route path="courses/:courseId" getComponent={(nextState, cb) => {cb(null, Course)}} />
+class MyRouter < React::Component::Base
+  include Hyperloop::Router::Base
+end
 ```
 
-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:
+With the base Router class, you must specify the history you want to use.
 
+This can be done either using a macro:
 ```ruby
-route("courses/:id").mounts do | ct |
-  HTTP.get("validate-user-access/courses/#{ct.next_state[:id]}").then {  Course }
+class MyRouter < Hyperloop::Router
+  history :browser
 end
 ```
+The macro accepts three options: `:browser`, `:hash`, or `:memory`.
 
-*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:
-
+Or defining the `history` method:
 ```ruby
-route("/", mounts: About, index: Home) do
-  index(mounts: MyIndex)
-  route("about")
-  route("privacy-policy")
+class MyRouter < Hyperloop::Router
+  def history
+    self.class.browser_history
+  end
 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.
+### BrowserRouter, HashRouter, MemoryRouter, StaticRouter
 
-#### The `redirect` options
+Using one of these classes automatically takes care of the history for you,
+so you don't need to specify one.
+They also can be used by inheritance or inclusion:
 
-with static arguments:
-
-`redirect("/from/path/spec", to: "/to/path/spec", query: {q1: 123, q2: :abc})`
+```ruby
+class MyRouter < Hyperloop::HashRouter
+end
 
-the `:to` and `:query` options can be Procs which will receive the current state.
+class MyRouter < React::Component::Base
+  include Hyperloop::Router::Hash
+end
+```
 
-Or you can specify the `:to` an `:query` options with blocks:
+### Rendering a Router
 
-`redirect("/from/path/spec/:id").to { |curr_state| "/to/path/spec/#{current_state[:id]}"}.query { {q1: 12} }`
+To render children/routes use the `route` macro, it is the equivalent to `render` of a component.
+```ruby
+class MyRouter < Hyperloop::Router
+  ...
 
-#### The `index_redirect` method
+  route do
+    DIV do
+      H1 { 'Hello world!' }
+    end
+  end
+end
+```
 
-just like `redirect` without the first arg: `index_redirect(to: ... query: ...)`
 
-### The Router Component
+### Routes
 
-A router is defined as a subclass of `Hyperloop::Router` which is itself a `Hyperloop::Component`.
+Routes are no longer defined separately, but are just components you call inside the router/components.
 
 ```ruby
-class Components::Router < Hyperloop::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
+class MyRouter < Hyperloop::Router
+  ...
+
+  route do
+    DIV do
+      Route('/', mounts: HelloWorld)
     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 < Hyperloop::Component
-  render(DIV) do
-    Application::Nav()
-    MAIN do
-      Router()
-    end
+class HelloWorld < React::Component::Base
+  render do
+    H1 { 'Hello world!' }
   end
 end
 ```
 
-#### navigating
+The `Route` method takes a url path, and these options:
+- `mounts: Component` The component you want to mount when routed to
+- `exact: Boolean` When true, the path must match the location exactly
+- `strict: Boolean` When true, the path will only match if the location and path **both** have/don't have a trailing slash
+It can also take a block instead of the `mounts` option.
 
-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
-```
+class MyRouter < Hyperloop::Router
+  ...
 
-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}');`
+  route do
+    DIV do
+      Route('/', exact: true) do
+        H1 { 'Hello world!' }
       end
     end
   end
 end
 ```
-
-
-#### Other router hooks:
-
-There are several other methods that can be redefined to modify the routers behavior
-
-#### history
-
+The block will give you the match, location, and history data:
 ```ruby
-class Router < Hyperloop::Router
-  def history
-  ... return a history object
+class MyRouter < Hyperloop::Router
+  ...
+
+  route do
+    DIV do
+      Route('/:name') do |match, location, history|
+        H1 { "Hello #{match.params[:foo]} from #{location.pathname}, click me to go back!" }
+          .on(:click) { history.go_back }
+      end
+    end
   end
 end
 ```
 
-The two standard history objects are predefined as `browser_history` and `hash_history` so you can say:
-
+It is recommended to inherit from `Hyperloop::Router::Component` for components mounted by routes.
+This automatically sets the `match`, `location`, and `history` params,
+and also gives you instance methods with those names.
+You can use either `params.match` or just `match`.
+and gives you access to the Route method and more.
+This allows you to create inner routes as you need them.
 ```ruby
-...
-  def history
-    browser_history
-  end
-```
-
-or just
+class MyRouter < Hyperloop::Router
+  ...
 
-```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:
+  route do
+    DIV do
+      Route('/:name', mounts: Greet)
+    end
+  end
+end
 
-+ 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
+class Greet < Hyperloop::Router::Component
+  render(DIV) do
+    H1 { "Hello #{match.params[:foo]}!" }
+    Route(match.url, exact: true) do
+      H2 { 'What would you like to do?' }
+    end
+    Route("#{match.url}/:activity", mounts: Activity)
+  end
+end
 
-```ruby
-class Router < Hyperloop::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))
+class Activity < Hyperloop::Router::Component
+  render(DIV) do
+    H2 { params.match.params[:activity] }
   end
 end
 ```
 
-The above could be simplified to:
+Routes will **always** render alongside sibling routes that match as well.
 
 ```ruby
-...
-  def create_element(component, component_params)
-    component_params[:time_stamp] = Time.now
+class MyRouter < Hyperloop::Router
+  ...
+
+  route do
+    DIV do
+      Route('/goodbye', mounts: Goodbye)
+      Route('/:name', mounts: Greet)
+    end
   end
+end
 ```
 
-Just make sure that you return a truthy value otherwise it will ignore any changes to component or params.
+### Switch
 
-Or if you just wanted some kind of logging:
+Going to `/goodbye` would match `/:name` as well and render `Greet` with the `name` param with the value 'goodbye'.
+To avoid this behavior and only render one matching route at a time, use a `Switch` component.
 
 ```ruby
-...
-  def create_element(component, component_params)
-    puts "[#{Time.now}] Rendering: #{component.name}" # puts returns nil, so we are jake mate
+class MyRouter < Hyperloop::Router
+  ...
+
+  route do
+    DIV do
+      Switch do
+        Route('/goodbye', mounts: Goodbye)
+        Route('/:name', mounts: Greet)
+      end
+    end
   end
+end
 ```
 
-The component_params will always contain the following keys as native js objects, and they must stay native js objects:
+Now, going to `/goodbye` would match the `Goodbye` route first and only render that component.
 
-+ `children`
-+ `history`
-+ `location`
-+ `params`
-+ `route`
-+ `route_params`
-+ `routes`
+### Links
 
-We will try to get more fancy with a later version of reactrb-router ;-)
+Links are available to Routers, classes that inherit from `HyperLoop::Router::Component`,
+or by including `Hyperloop::Router::ComponentMethods`.
 
-#### `stringify_query(params_hash)` <- needs work
+The `Link` method takes a url path, and these options:
+- `search: String` adds the specified string to the search query
+- `hash: String` adds the specified string to the hash location
+It can also take a block of children to render inside it.
+```ruby
+class MyRouter < Hyperloop::Router
+  ...
 
-The method used to convert an object from <Link>s or calls to transitionTo to a URL query string.
+  route do
+    DIV do
+      Link('/Gregor Clegane')
 
-```ruby
-class Router < Hyperloop::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...
+      Route('/', exact: true) { H1() }
+      Route('/:name') do |match|
+        H1 { "Will #{match.params[:name]} eat all the chickens?" }
+      end
+    end
   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:
+### NavLinks
 
+NavLinks are the same as Links, but will add styling attributes when it matches the current url
+- `active_class: String` adds the class to the link when the url matches
+- `active_style: String` adds the style to the link when the url matches
+- `active: Proc` A proc that will add extra logic to determine if the link is active
 ```ruby
-  def render
-    # Router.router renders the native router component
-    Router.router(build_params)
+class MyRouter < Hyperloop::Router
+  ...
+
+  route do
+    DIV do
+      NavLink('/Gregor Clegane', active_class: 'active-link')
+      NavLink('/Rodrik Cassel', active_style: { color: 'grey' })
+      NavLink('/Oberyn Martell',
+              active: ->(match, location) {
+                match && match.params[:name] && match.params[:name] =~ /Martell/
+              })
+
+      Route('/', exact: true) { H1() }
+      Route('/:name') do |match|
+        H1 { "Will #{match.params[:name]} eat all the chickens?" }
+      end
+    end
   end
+end
 ```
 
+### Pre-rendering
 
-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.
-
-### Hyperloop::Router::Component
-
-The class Hyperloop::Router::Component is a subclass of Hyperloop::Component that predefines the params that the router will be passing in to your component.  This includes
-
-`params.location`
-
-The current location.
-
-`params.params`
+Pre-rendering has been made extremely simple in this new version.
+Under the hood a StaticRouter is used whenever a Router component is prerendering.
+To prerender correctly though you will need to give it the current path.
+Since there is no DOM, you must pass in the current path from your controller/view as a param.
+There is a special param macro called `prerender_path`,
+which still acts as a normal param but will use that param as the current path in prerendering.
 
-The dynamic segments of the URL.
-
-`params.route`
+```ruby
+class MyController < ApplicationController
+  def show
+    render component: 'MyRouter', props: { current_path: request.path }
+  end
+end
 
-The route that rendered this component.
+class MyRouter < Hyperloop::Router
+  prerender_path :current_path
 
-`params.route_params`
+  route do
+    DIV do
+      Route('/:name', mounts: Greet)
+    end
+  end
+end
+```
 
-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