pakyow-ui 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: efeadfe62f8a75592def0245762f51a0ed6810d0
+  data.tar.gz: 9cc0f94cdeac4337d04dae90c43172d50dca1c81
+SHA512:
+  metadata.gz: 456f564c2ce44a45f96e1374db0441a6ae764ef5dbaef49506f4a6dd9a16fdc7fac9f61b07929d274ade2ee3c44b91d22d112572be419d8a054896e9f4c03797
+  data.tar.gz: 6ab2b517de51cc4b2310b4f6517c39ad7ba0cdb60497be90dfbf638b6cdb6dcf0f8ad9a09cee3af87c30e5a9e75feb5e3342220830cb65acdb2d246df06e6812

data/pakyow-ui/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.10.0 (to be released)
+
+  * Initial release

data/pakyow-ui/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 Bryan Powell
+
+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/pakyow-ui/README.md

@@ -0,0 +1,325 @@
+# PakyowUI
+
+Auto-Updating UIs for Pakyow, without moving to the client.
+
+## Rationale
+
+We wanted a way to build modern apps in a traditional backend-driven
+manner while still reaping the benefits of modern, live updating
+UIs. The existing approaches to building live UIs tend to *replace*
+backend-driven architecture rather than *extend* it.
+
+Instead of replacing traditional architecture, PakyowUI adds a layer
+on top of it. This allows Pakyow apps to have live UIs out of the box
+without any additional work by the developer, while remaining accessible
+and fully usable in the absence of WebSockets, JavaScript, etc.
+
+The PakyowUI approach stays true to the fundamental nature of the web.
+It aims to be the real-time web expressed as progressive enhancement.
+It allows for any aspect of a website or web app to be updated in
+real-time, without any additional work by the developer.
+
+## Overview
+
+At a high level, PakyowUI keeps rendered views (meaning views that
+are currently rendered by a client in the browser) in sync with the
+current state of the data.
+
+During the initial request/response cycle, Pakyow keeps track of what
+view is rendered and sent back to the client, along with the underlying
+data used to render those views.
+
+When the data changes in the future, a set of transformation
+instructions are sent to the client(s) who possess views with that
+data. The transformations are then applied to the existing views by a
+JavaScript client library so that the view not reflects the current
+app state. The app *does not* push re-rendered views back down to the
+client, nor does any JavaScript transcompilation occur.
+
+---
+
+Let's look at an example. Say during the initial request/response cycle
+Pakyow rendered a view that presents a user's name:
+
+```html
+<div data-scope="user" data-id="1">
+  <h3 data-prop="name">
+    Bob Dylan
+  </h3>
+</div>
+```
+
+When the name changes, PakyowUI builds up an instruction like this:
+
+```ruby
+[[:bind, { name: 'Thelonius Monk' }]]
+```
+
+This instruction is routed to the client(s) that present a view
+containing data for user 1. Once received, the intructions are applied.
+
+Predictably, the updated view reflects the new state:
+
+```html
+<div data-scope="user" data-id="1">
+  <h3 data-prop="name">
+    Thelonius Monk
+  </h3>
+</div>
+```
+
+PakyowUI builds on the [pakyow-realtime
+library](https://github.com/pakyow/pakyow/tree/master/pakyow-realtime),
+so all of the communication between client and server occurs over a
+WebSocket. If WebSockets aren't supported by the client (or for some
+reason aren't working) the app will continue to work, just without live
+updates. You get this graceful degradation for free without developing
+with progressive enhancement in mind.
+
+---
+
+By expressing view transformations as data, they can be applied to
+any view by any interpreter; be it on the server or the client. To
+accomplish this, view rendering must be expressed separately from
+the view and in context of the data being presented by the view. The
+rendering itself also is expressed independently of how to fetch
+the data necessary to perform the render, giving PakyowUI all the
+information it needs to automatically perform the rendering again at
+some point in the future.
+
+## Data - Mutables
+
+PakyowUI introduces a concept called **mutables**. A mutable wraps a
+data model and defines two things:
+
+1. Actions that can occur on the model that cause state mutations.
+2. Queries that define how particular data is to be fetched.
+
+Here's how a mutable is defined:
+
+```ruby
+class User < Sequel::Model; end
+
+Pakyow::App.mutable :user do
+  model User
+
+  action :create do |object|
+    User.create(object)
+  end
+
+  query :all do
+    User.all
+  end
+
+  query :find do |id|
+    User[id]
+  end
+end
+```
+
+From a route, we can use the mutable to query for data:
+
+```ruby
+# get all the users
+data(:user).all
+
+# get a specific user
+data(:user).find(1)
+```
+
+We can also change data through the mutable:
+
+```ruby
+data(:user).create(params[:user])
+```
+
+Mutables are the first step in making the route declarative (what)
+rather than imperative (how). All of the *how* is wrapped up in the
+mutable itself, letting us express only *what* should happen from the
+route. This is important.
+
+## View - Mutators
+
+The second concept introduced by PakyowUI is **mutators**. A mutator
+describes *how* to render a particular view with some particular data.
+
+Here's a mutator for rendering a list of users:
+
+```ruby
+Pakyow::Mutators :user do
+  mutator :list do |view, users|
+    view.apply(users)
+  end
+end
+```
+
+From a route, you could invoke the mutator on a view like this:
+
+```ruby
+view.scope(:user).mutate(:list, with: data(:user).all)
+```
+
+Notice that we're mutating with the data from our mutable user. Pakyow
+will fetch the data using the `all` query and pass it to the `list`
+mutation where the view is rendered.
+
+***NOTE:*** One important caveat here is that the individual data
+passed to the mutate method needs to respond to the `to_hash` method,
+which should return a hash of all relevant attributes. E.g. For
+ActiveRecord models could define `to_hash` like this:
+
+```
+class User < ActiveRecord::Base
+  def to_hash
+    attributes
+  end
+end
+```
+
+At this point we've effectively turned view rendering into a declarative
+action from the route's point of view. We only have to describe *what*
+we want to happen and Pakyow takes care of the rest.
+
+This becomes useful when you want to subscribe the mutation to future
+changes in state. You can do this by calling `subscribe`:
+
+```ruby
+view.scope(:user).mutate(:list, with: data(:user).all).subscribe
+```
+
+The view is rendered in the intial request/response cycle exactly like
+it was before, but now it's also subscribed to any future state change
+that affects the rendered view.
+
+Let's mutate our state:
+
+```ruby
+data(:user).create(params[:user])
+```
+
+Pakyow knows that we've mutated our user state; it also knows what
+clients are currently rendering the mutated user state. It automatically
+pushes down instructions over a WebSocket describing how the client
+should update their view to match the current state.
+
+Our rendered views now keep themselves up to date with the current state
+of the application; and we as the developer don't have to do anything
+but write the initial rendering code! We don't have to move any part of
+our app to the client. Our app retains a backend-driven architecture
+while still behaving like a modern app with live updates.
+
+## Ring - Client Library
+
+PakyowUI ships with a client library called Ring, effectively
+bringing Pakyow's view transformation API to the client. In addition
+to applying view transformations, Pakyow.js also ships with several
+components, including:
+
+- Mutation Detection: Watches user-interaction with the rendered view and can
+		interpret which interactions cause a mutation in state (e.g. submitting a
+		form). Once detected, the mutation is sent to the server by calling the REST
+		endpoint through the open WebSocket. The mutation is then validated by the
+		server, persisted (if necessary), and broadcast to all other clients.
+
+You can use Ring to build custom front-end components that emit
+their own mutations or otherwise communicate with your app's HTTP routes
+over a WebSocket.
+
+Ring is available here:
+
+- http://github.com/pakyow/ring).
+
+## Channels
+
+Pakyow keeps track of what clients should receive what state mutations
+with channels. Here's how a channel is structured:
+
+```
+scope:{name};mutation{name}::{qualifiers}
+```
+
+In the example from the Mutators section, the subscribed channel name is:
+
+```
+scope:user;mutation:list
+```
+
+This means that any client who rendered any user data with the `list`
+mutation will receive future updates in user state. Read the next
+section to understand how to better control this.
+
+## Qualifiers
+
+You might be curious about how to exercise fine-grained control over
+clients and the mutations they receive. PakyowUI handles this with
+*qualifiers*.
+
+For example, you can subscribe a view to only update with the current
+user's data:
+
+```ruby
+view.scope(:user).mutate(:list, with:
+	data(:user).for_user(current_user)).subscribe({
+  user_id: current_user.id
+})
+```
+
+The `user_id` qualifier is added to the channel name, so when future
+mutations occur, the result will only be pushed down to that particular
+client. Here's the subscribed channel name:
+
+    scope:user;mutation:present::user_id:1
+
+You can also qualify mutators. Here's how you would express that you
+want a particular user's mutations to be sent only to clients that
+render that state:
+
+```ruby
+Pakyow::Mutators :user do
+  mutator :present, qualify: [:id] do |view, user|
+    view.bind(user)
+  end
+end
+
+view.scope(:user).mutate(:present, with: data(:user).find(1)).subscribe
+```
+
+The value for the qualifier will be pulled from the user's id and added to the
+channel name. Now only client's who currently render the user with id of 1 will
+receive future state changes about that user. Here's the subscribed channel
+name:
+
+```
+scope:user;mutation:present::id:1
+```
+
+# Download
+
+The latest version of Pakyow UI can be installed with RubyGems:
+
+```
+gem install pakyow-ui
+```
+
+Source code can be downloaded as part of the Pakyow project on Github:
+
+- https://github.com/pakyow/pakyow/tree/master/pakyow-ui
+
+# License
+
+Pakyow UI is released free and open-source under the [MIT
+License](http://opensource.org/licenses/MIT).
+
+# Support
+
+Documentation is available here:
+
+- http://pakyow.org/docs/live-views
+
+Found a bug? Tell us about it here:
+
+- https://github.com/pakyow/pakyow/issues
+
+We'd love to have you in the community:
+
+- http://pakyow.org/get-involved

data/pakyow-ui/lib/pakyow-ui/base.rb

@@ -0,0 +1,35 @@
+require_relative 'helpers'
+require_relative 'ui'
+require_relative 'mutator'
+require_relative 'mutation_set'
+require_relative 'mutable'
+require_relative 'mutate_context'
+require_relative 'ui_view'
+require_relative 'channel_builder'
+require_relative 'fetch_view_handler'
+require_relative 'mutation_store'
+require_relative 'registries/simple_mutation_registry'
+require_relative 'registries/redis_mutation_registry'
+require_relative 'config'
+require_relative 'ui_component'
+require_relative 'ui_instructable'
+
+require_relative 'ext/app'
+require_relative 'ext/app_context'
+require_relative 'ext/view_context'
+
+Pakyow::App.before :init do
+  @ui = Pakyow::UI::UI.new
+end
+
+Pakyow::App.after :load do
+  @ui.load(mutators, mutables)
+end
+
+Pakyow::App.before :route do
+  # setup a new ui context to work in
+  #
+  ui_dup = @ui.dup
+  ui_dup.context = self
+  @context.ui = ui_dup
+end

data/pakyow-ui/lib/pakyow-ui/channel_builder.rb

@@ -0,0 +1,54 @@
+module Pakyow
+  module UI
+    # Helpers for building channel names.
+    #
+    # @api private
+    module ChannelBuilder
+      PARTS = [:scope, :mutation, :component]
+
+      def self.build(qualifiers: [], data: [], qualifications: {}, **args)
+        channel = []
+        channel_extras = []
+
+        PARTS.each do |part|
+          add_part(part, args[part], channel)
+        end
+
+        add_qualifiers(qualifiers, data, channel_extras)
+        add_qualifications(qualifications, channel_extras)
+
+        channel = channel.join(';')
+
+        return channel if channel_extras.empty?
+        channel << "::#{channel_extras.join(';')}"
+      end
+
+      private
+
+      def self.add_part(part, value, channel)
+        return if value.nil?
+        channel << "#{part}:#{value}"
+      end
+
+      def self.add_qualifiers(qualifiers, data, channel_extras)
+        qualifiers = Array.ensure(qualifiers)
+
+        data = data.data if data.is_a?(Pakyow::UI::MutableData)
+        return if qualifiers.empty? || data.empty?
+
+        datum = Array.ensure(data).first
+
+        qualifiers.each do |qualifier|
+          channel_extras << "#{qualifier}:#{datum[qualifier]}"
+        end
+      end
+
+      def self.add_qualifications(qualifications, channel_extras)
+        qualifications.each do |name, value|
+          next if value.nil?
+          channel_extras << "#{name}:#{value}"
+        end
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/config.rb

@@ -0,0 +1,13 @@
+require_relative 'registries/simple_mutation_registry'
+require_relative 'registries/redis_mutation_registry'
+
+Pakyow::Config.register(:ui) { |config|
+  # The registry to use when keeping up with connections.
+  config.opt :registry, Pakyow::UI::SimpleMutationRegistry
+}.env(:development) { |opts|
+  opts.registry = Pakyow::UI::SimpleMutationRegistry
+}.env(:staging) { |opts|
+  opts.registry = Pakyow::UI::RedisMutationRegistry
+}.env(:production) { |opts|
+  opts.registry = Pakyow::UI::RedisMutationRegistry
+}

data/pakyow-ui/lib/pakyow-ui/ext/app.rb

@@ -0,0 +1,50 @@
+module Pakyow
+  class App
+    class << self
+      # Defines mutators for a scope.
+      #
+      # @api public
+      def mutators(scope = nil, &block)
+        @mutators ||= {}
+
+        if scope && block
+          @mutators[scope] = block
+        else
+          @mutators || {}
+        end
+      end
+
+      # Defines a mutable object.
+      #
+      # @api public
+      def mutable(scope, &block)
+        @mutables ||= {}
+        @mutables[scope] = block
+      end
+
+      # @api private
+      def mutables
+        @mutables || {}
+      end
+    end
+
+    # Convenience method for defining mutators on an app instance.
+    #
+    # @api public
+    def mutators(scope = nil, &block)
+      self.class.mutators(scope, &block)
+    end
+
+    # Convenience method for defining a mutable on an app instance.
+    #
+    # @api public
+    def mutable(scope, &block)
+      self.class.mutable(scope, &block)
+    end
+
+    # @api private
+    def mutables
+      self.class.mutables
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/ext/app_context.rb

@@ -0,0 +1,5 @@
+module Pakyow
+  class AppContext
+    attr_accessor :ui
+  end
+end

data/pakyow-ui/lib/pakyow-ui/ext/view_context.rb

@@ -0,0 +1,30 @@
+module Pakyow
+  module Presenter
+    class ViewContext
+      MSG_NONCOMPONENT = 'Cannot subscribe a non-component view'
+
+      # Mutates a view with a registered mutator.
+      #
+      # @api public
+      def mutate(mutator, data: nil, with: nil)
+        Pakyow::UI::Mutator.instance.mutate(mutator, self, data || with || [])
+      end
+
+      # Subscribes a view and sets the `data-channel` attribute.
+      #
+      # @api public
+      def subscribe(qualifications = {})
+        fail ArgumentError, MSG_NONCOMPONENT unless component?
+
+        channel = Pakyow::UI::ChannelBuilder.build(
+          component: component_name,
+          qualifications: qualifications
+        )
+
+        context.socket.subscribe(channel)
+        attrs.send(:'data-channel=', channel)
+        self
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/fetch_view_handler.rb

@@ -0,0 +1,67 @@
+require_relative 'no_op_view'
+
+# Makes it possible to fetch a particular part of a view for a path. Calls a
+# route with all view actions becoming no-ops. Then a query is run against the
+# final view, pulling out the part that was requested.
+#
+# Expects the following in the message:
+#
+# - uri: the route to call
+# - lookup: the view query
+#
+# Lookup currently supports the following keys:
+#
+# - channel
+# - version
+# - container
+# - partial
+# - scope
+# - prop
+#
+Pakyow::Realtime.handler :'fetch-view' do |message, session, response|
+  env = Rack::MockRequest.env_for(message['uri'])
+  env['rack.session'] = session
+
+  app = Pakyow.app.dup
+
+  def app.view
+    Pakyow::Presenter::NoOpView.new(
+      Pakyow::Presenter::ViewContext.new(@presenter.view, self),
+      self
+    )
+  end
+
+  app_response = app.process(env)
+
+  body = ''
+  lookup = message['lookup']
+  view = app.presenter.view
+
+  channel = lookup['channel']
+
+  if channel
+    unqualified_channel = channel.split('::')[0]
+    view_for_channel = view.composed.doc.channel(unqualified_channel)
+
+    if view_for_channel
+      view_for_channel.set_attribute(:'data-channel', channel)
+      body = view_for_channel.to_html
+    end
+  else
+    lookup.each_pair do |key, value|
+      next if key == 'version'
+      view = view.send(key.to_sym, value.to_sym)
+    end
+
+    if view.is_a?(Pakyow::Presenter::ViewVersion)
+      body = view.use(lookup['version'] || :default).to_html
+    else
+      body = view.to_html
+    end
+  end
+
+  response[:status]  = app_response[0]
+  response[:headers] = app_response[1]
+  response[:body] = body
+  response
+end

data/pakyow-ui/lib/pakyow-ui/helpers.rb

@@ -0,0 +1,11 @@
+module Pakyow
+  module Helpers
+    def ui
+      context.ui
+    end
+
+    def data(scope)
+      ui.mutator.mutable(scope, self)
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/mock_mutation_eval.rb

@@ -0,0 +1,25 @@
+module Pakyow
+  module Presenter
+    # Used by NoOpView to perform mutations in a no-op manner.
+    #
+    # @api private
+    class MockMutationEval
+      def initialize(mutation_name, relation_name, view)
+        @mutation_name = mutation_name
+        @relation_name = relation_name
+        @view = view
+      end
+
+      # NOTE we don't care about qualifiers here since we're just getting
+      # the proper view template; not actually setting it up with data
+      def subscribe(*_args)
+        channel = Pakyow::UI::ChannelBuilder.build(
+          scope: @view.scoped_as,
+          mutation: @mutation_name
+        )
+
+        @view.attrs.send(:'data-channel=', channel)
+      end
+    end
+  end
+end