ovto 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b5c09cd1d638ce54f7aea489477c059ac6935704ae284c5fdae49c7b45b7cdd
+  data.tar.gz: 2c83538298b032f336e035dc7ad48ea71114bb8f6ece4054accd9d3a593db5e6
+SHA512:
+  metadata.gz: 316292a3ef746099b7c1eb5054d34830771b428122325972c91a5c1924123a544f5016e0eab4904120df56d16be5c70c50cb4c4dedd43a5e821eecd53c5aafbb
+  data.tar.gz: 478d66e8ce0c82f40b258c9490baa64b617b4d66f772931f7c1c5cbd52f2d0a70073d62c98ec0863954de6d6436725c4adad988d85d3ef98754fc00aef70f584

data/.gitignore

@@ -0,0 +1 @@
+/.yardoc

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "opal-rspec"]
+	path = opal-rspec
+	url = git://github.com/opal/opal-rspec.git

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+## v0.2.0 2018-11-01
+
+New features
+
+- First gem release!
+- `Ovto.fetch`
+- Calling another action from actions
+- Allow `o "div#id.class"` or `o "div.class#id"`
+- Sub component can access the app state by adding `state:` keyword to `render`
+- `App#actions`, `App#setup`
+- `State#==`
+- `console.log`
+
+Fixes
+
+- Skip rendering if app state is not changed by an action
+- `o "div.main", class: 'hovered'` should yield `<div class='main hovered'>`
+- Cannot pass falsy value when rendering a child component
+
+## v0.1.0 2018-06-01
+
+- Initial release

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+gem "opal"
+gem 'opal-rspec', path: './opal-rspec'
+gem 'opal-sprockets', github: 'opal/opal-sprockets'
+gem 'rake'
+gem 'ovto', path: '.'
+gem 'yard'

data/Gemfile.lock

@@ -0,0 +1,57 @@
+GIT
+  remote: git://github.com/opal/opal-sprockets.git
+  revision: 8a8faeb1cfbc51cfa2e71ddb6cf219bd4a14f333
+  specs:
+    opal-sprockets (0.4.2.0.11.0.3.1)
+      opal (~> 0.11.0)
+      sprockets (~> 3.1)
+      tilt (>= 1.4)
+
+PATH
+  remote: .
+  specs:
+    ovto (0.2.0)
+      opal (~> 0.11)
+
+PATH
+  remote: opal-rspec
+  specs:
+    opal-rspec (0.7.0.dev)
+      opal (>= 0.10.0, < 0.12)
+      opal-sprockets
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    concurrent-ruby (1.0.5)
+    hike (1.2.3)
+    opal (0.11.3)
+      ast (>= 2.3.0)
+      hike (~> 1.2)
+      parser (= 2.3.3.1)
+      sourcemap (~> 0.1.0)
+    parser (2.3.3.1)
+      ast (~> 2.2)
+    rack (2.0.5)
+    rake (12.3.1)
+    sourcemap (0.1.1)
+    sprockets (3.7.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    tilt (2.0.8)
+    yard (0.9.16)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  opal
+  opal-rspec!
+  opal-sprockets!
+  ovto!
+  rake
+  yard
+
+BUNDLED WITH
+   1.16.1

data/LICENSE.txt

@@ -0,0 +1,44 @@
+The MIT License (MIT)
+
+Copyright (c) 2018-present Yutaka HARA
+
+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.
+
+----
+License of Hyperapp (in lib/ovto/runtime.rb):
+
+Copyright © 2017-present [Jorge Bucaran](https://github.com/jorgebucaran)
+
+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,84 @@
+# Ovto
+
+Client-side web framework for Opal, inspired by hyperapp
+
+## Documents
+
+- [Book](https://yhara.github.io/ovto/)
+- [yardoc](https://yhara.github.io/ovto/api/)
+
+## Example
+
+![screenshot](screenshot.png)
+
+```rb
+require 'ovto'
+
+class MyApp < Ovto::App
+  class State < Ovto::State
+    item :celsius, default: 0
+
+    def fahrenheit
+      (celsius * 9 / 5.0) + 32
+    end
+  end
+
+  class Actions < Ovto::Actions
+    def set_celsius(state:, value:)
+      return {celsius: value}
+    end
+
+    def set_fahrenheit(state:, value:)
+      new_celsius = (value - 32) * 5 / 9.0
+      return {celsius: new_celsius}
+    end
+  end
+
+  class View < Ovto::Component
+    def render(state:)
+      o 'div' do
+        o 'span', 'Celcius:'
+        o 'input', {
+          type: 'text',
+          onchange: ->(e){ actions.set_celsius(value: e.target.value.to_i) },
+          value: state.celsius
+        }
+        o 'span', 'Fahrenheit:'
+        o 'input', {
+          type: 'text',
+          onchange: ->(e){ actions.set_fahrenheit(value: e.target.value.to_i) },
+          value: state.fahrenheit
+        }
+      end
+    end
+  end
+end
+
+MyApp.run(id: 'ovto-view')
+```
+
+See the [book](https://yhara.github.io/ovto/guides/tutorial.html) for details.
+
+## Setup
+
+### Static
+
+[./example/static](./example/static) demonstrates how to convert Ovto app
+into a .js file.
+
+### Ovto + Sinatra
+
+[./example/sinatra](./example/sinatra) demonstrates how to serve Ovto app
+from Sinatra.
+
+### Ovto + Rails
+
+[yhara/vision](https://github.com/yhara/vision) is a working example of using Ovto with Rails 5.
+
+## Acknowledgements
+
+- [hyperapp](https://github.com/hyperapp/hyperapp)
+
+## Contact
+
+https://github.com/yhara/ovto/issues

data/Rakefile

@@ -0,0 +1,41 @@
+require 'opal/rspec/rake_task'
+Opal.append_path "./opal"
+Opal.append_path "./spec"
+Opal.use_gem "ovto"
+
+Opal::RSpec::RakeTask.new(:default) do |server, task|
+  task.pattern = 'spec/**/*_spec.rb'
+end
+
+namespace :docs do
+  desc "build docs"
+  task :build do
+    cd "book" do
+      sh "gitbook build . ../docs"
+    end
+    sh "yardoc -o docs/api"
+  end
+
+  desc "start gitbook server"
+  task :serve do
+    cd "book" do
+      sh "gitbook serve"
+    end
+  end
+end
+
+namespace :release do
+  task :prepare_commit do
+    sh "git ci -am v#{Ovto::VERSION}"
+    sh "git tag v#{Ovto::VERSION}"
+  end
+
+  task :push_commit do
+    sh "git push origin master --tags"
+  end
+
+  task :push_gem do
+    sh "gem build ovto"
+    sh "gem push ovto-#{Ovto::VERSION}.gem"
+  end
+end

data/book/README.md

@@ -0,0 +1 @@
+book/../README.md

data/book/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+- [Introduction](README.md)
+- [Getting Started](guides/tutorial.md)
+- API
+  - [Ovto::App](api/app.md)
+  - [Ovto::State](api/state.md)
+  - [Ovto::Actions](api/actions.md)
+  - [Ovto::Component](api/component.md)
+  - [Ovto.fetch](api/fetch.md)
+- Guides
+  - [Debugging](guides/debugging.md)
+  - [Development](guides/development.md)

data/book/api/actions.md

@@ -0,0 +1,77 @@
+# Ovto::Actions
+
+Actions are the only way to change the state. Actions must be defined as methods of
+the `Actions` class. Here is some more conventions:
+
+- You must use keyword arguments
+- You must provide `state:` keyword to receive the app state
+- You must return state updates as a Hash. It will be merged into the app state.
+
+Example:
+
+```rb
+require 'opal'
+require 'ovto'
+
+class MyApp < Ovto::App
+  class State < Ovto::State
+    item :count, 0
+  end
+
+  class Actions < Ovto::Actions
+    def increment(state:, by:)
+      return {count: state.count + by}
+    end
+  end
+
+  class View < Ovto::Component
+    def render(state:)
+      o 'span', state.count
+      o 'button', onclick: ->{ actions.increment(by: 1) }
+    end
+  end
+end
+
+MyApp.run(id: 'ovto-view')
+```
+
+## Calling actions
+
+Actions can be called from components via `actions` method. This is an instance of
+`Ovto::WiredActions` and has methods of the same name as your `Actions` class.
+
+      o 'button', onclick: ->{ actions.increment(by: 1) }
+
+Arguments are almost the same as the original but you don't need to provide `state`;
+it is automatically passed by `Ovto::WiredActions` class. It also updates the app
+state with the return value of the action, and schedules rendering the view.
+
+## Skipping state update
+
+An action may return `nil` when no app state changes are needed.
+
+Promises are also special values which does not cause state changes (see the next section).
+
+## Async actions
+
+When calling server apis, you cannot tell how the app state will change until the server responds.
+In such cases, you can call another action via `actions` to tell Ovto to reflect the api result to the app state.
+
+Example:
+
+```rb
+  class Actions < Ovto::Actions
+    def fetch_tasks(state:)
+      Ovto.fetch('/tasks.json').then {|tasks_json|
+        actions.receive_tasks(tasks: tasks_json)
+      }.fail {|e|
+        console.log("failed:", e)
+      }
+    end
+
+    def receive_tasks(state:, tasks_json:)
+      tasks = tasks_json.map{|item| Task.new(**item)}
+      return {tasks: tasks}
+    end
+  end
+```

data/book/api/app.md

@@ -0,0 +1,86 @@
+# Ovto::App
+
+First of all, you need to define a subclass of `Ovto::App` and define `class State`,
+`class Actions` and `class View` in it.
+
+## Example
+
+This is a smallest Ovto app.
+
+```rb
+require 'opal'
+require 'ovto'
+
+class MyApp < Ovto::App
+  class State < Ovto::State
+  end
+
+  class Actions < Ovto::Actions
+  end
+
+  class View < Ovto::Component
+    def render(state:)
+      o 'input', type: 'button', value: 'Hello'
+    end
+  end
+end
+
+MyApp.run(id: 'ovto-view')
+```
+
+It renders a button and does nothing else. Let's have some fun:
+
+```rb
+require 'opal'
+require 'ovto'
+
+class MyApp < Ovto::App
+  COLORS = ["red", "blue", "green"]
+
+  class State < Ovto::State
+    item :color_idx, default: 0
+  end
+
+  class Actions < Ovto::Actions
+    def update_color(state:)
+      new_idx = (state.color_idx + 1) % COLORS.length
+      return {color_idx: new_idx}
+    end
+  end
+
+  class View < Ovto::Component
+    def render(state:)
+      o 'input', {
+        type: 'button',
+        value: 'Hello',
+        style: {background: COLORS[state.color_idx]},
+        onclick: ->{ actions.update_color },
+      }
+    end
+  end
+end
+
+MyApp.run(id: 'ovto-view')
+```
+
+Here we added `color_idx` to app state and `update_color` action to change it.
+The button is updated to have the color indicated by `color_idx` and
+now has `onclick` event handler which executes the action.
+
+## Calling actions on startup
+
+To invoke certain actions on app startup, define `MyApp#setup` and use `MyApp#actions`.
+
+Example:
+
+```rb
+class MyApp < Ovto::App
+  def setup
+    actions.fetch_data()
+  end
+
+  ...
+end
+
+MyApp.run(id: 'ovto-view')
+```

data/book/api/component.md

@@ -0,0 +1,175 @@
+# Ovto::Component
+
+Your app must have a `View` class, a subclass of `Ovto::Component`.
+
+## 'render' method
+
+`render` is the only method you need to define in the `View` class.
+It must take the global app state as a keyword argument `state:`.
+
+```rb
+  class View < Ovto::Component
+    def render(state:)
+      o 'div' do
+        o 'h1', 'Your todos'
+        o 'ul' do
+          state.todos.each do |todo|
+            o 'li', todo.title
+          end
+        end
+      end
+    end
+  end
+```
+
+### MoreThanOneNode error
+
+If you missed the surrounding 'div' tag, Ovto raises an `MoreThanOneNode` error. `render` must create a single DOM node.
+
+```rb
+    def render(state:)
+      o 'h1', 'Your todos'
+      o 'ul' do
+        state.todos.each do |todo|
+          o 'li', todo.title
+        end
+      end
+    end
+
+#=> $MoreThanOneNode {name: "MoreThanOneNode", message: "MyApp::View#render must generate a single DOM node. Please wrap the tags with a 'div' or something.", stack: "MoreThanOneNode: MyApp::View#render must generate …opbox/proj/ovto/example/tutorial/app.js:22887:18)"}
+```
+
+## The 'o' method
+
+<a name='the-o-method' />
+
+`Ovto::Component#o` describes your app's view. For example:
+
+```rb
+o 'div'
+#=> <div></div>
+
+o 'div', 'Hello.'
+#=> <div>Hello.</div>
+```
+
+You can pass attributes with a Hash.
+
+```rb
+o 'div', class: 'main', 'Hello.'
+#=> <div class='main'>Hello.</div>
+```
+
+There are shorthand notations for classes and ids.
+
+```rb
+o 'div.main'
+#=> <div class='main'>Hello.</div>
+
+o 'div#main'
+#=> <div id='main'>Hello.</div>
+```
+
+You can also give a block to specify its content.
+
+```rb
+o 'div' do
+  'Hello.'
+end
+#=> <div>Hello.</div>
+
+o 'div' do
+  o 'h1', 'Hello.'
+end
+#=> <div><h1>Hello.</h1></div>
+```
+
+### Special attribute: `style`
+
+<a name='special-attributes' />
+
+There are some special keys for the attributes Hash. `style:` key takes a hash as 
+its value and specifies styles of the tag.
+
+```rb
+o 'div', style: {color: 'red'}, 'Hello.'
+#=> <div style='color: red;'>Hello.</div>
+```
+
+### Special attribute: `onxx`
+
+An attribute starts with `"on"` specifies an event handler.
+
+For example:
+
+```rb
+o 'input', {
+  type: 'button',
+  onclick: ->(e){ p e.target.value },
+  value: 'Hello.'
+}
+```
+
+The argument `e` is an instance of Opal::Native and wraps the JavaScript event object.
+You can get the input value with `e.target.value` here.
+
+#### Lifecycle events
+
+There are special events `oncreate`, `onupdate`, `onremove`, `ondestroy`.
+
+https://github.com/hyperapp/hyperapp#lifecycle-events
+
+### Special attribute: `key`
+
+https://github.com/hyperapp/hyperapp#keys
+
+## Sub components
+
+`o` can take another component class to render.
+
+```rb
+  # Sub component
+  class TodoList < Ovto::Component
+    def render(todos:)
+      o 'ul' do
+        todos.each do |todo|
+          o 'li', todo.title
+        end
+      end
+    end
+  end
+
+  # Main View class
+  class View < Ovto::Component
+    def render(state:)
+      o 'div' do
+        o 'h1', 'Your todos'
+        o TodoList, todos: state.todos
+      end
+    end
+  end
+```
+
+For sub components, the `state:` keyword of `render` method is optional. 
+
+## Text node
+
+Sometimes you may want to create a text node.
+
+```rb
+#=> <div>Age: <span class='age'>12</a></div>
+#        ~~~~~
+#          |
+#          +--Raw text (not enclosed by an inner tag)
+```
+
+`o` generates a text node when `'text'` is specified as tag name. The above
+HTML could be described like this.
+
+```rb
+o 'div' do
+  o 'text', 'Age:'
+  o 'span', '12'
+end
+```
+

data/book/api/fetch.md

@@ -0,0 +1,42 @@
+# Ovto.fetch
+
+Ovto provides wrapper of [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch), for convenience of calling typical server-side APIs (eg. those generated by `rails scaffold` command.)
+
+`Ovto.fetch` returns Opal's Promise object that calls the API with the specified parameters.
+
+## Examples
+
+GET
+
+```rb
+Ovto.fetch('/api/tasks'){|json_data|
+  p json_data
+}.fail{|e|  # Network error, 404 Not Found, JSON parse error, etc.
+  p e
+}
+```
+
+POST
+
+```rb
+Ovto.fetch('/api/new_task', 'POST', {title: "do something"}){|json_data|
+  p json_data
+}.fail{|e|  # Network error, 404 Not Found, JSON parse error, etc.
+  p e
+}
+
+```
+
+PUT
+
+```rb
+Ovto.fetch('/api/tasks/1', 'PUT', {title: "do something"}){|json_data|
+  p json_data
+}.fail{|e|  # Network error, 404 Not Found, JSON parse error, etc.
+  p e
+}
+```
+
+## CSRF tokens
+
+You don't need to care about CSRF tokens if the server is a Rails app because `Ovto.fetch` automatically send `X-CSRF-Token` header if the page contains a meta tag like `<meta name='csrf-token' content='....' />`.