quince 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 915108de103a8f53a56eec910ca301b090ad537b2b368f919750283fe7781ae4
-  data.tar.gz: e0ce22c06ac12cc12bf901aac59443e61e587bdf870af52c97faa0fe38cd65fd
+  metadata.gz: 2189200f4bee6758d6a981e3f4ba7b0d8dc558d0e0e2bb66fd421c11b404f954
+  data.tar.gz: 4153ceb85c057cfe7c2e74852aee81b82dde74362aecec53647b485fea191b87
 SHA512:
-  metadata.gz: a7bf3cd3af27f2523d6d2b57ad4bcb121478bfa72cf71ae459f3bafe2a2a5a5ff2826acc645e3e7da3479df7548d32560b572e0bf09fa5101a631e819feb5a03
-  data.tar.gz: f063a5d900d22b5c66a9cbc674782e04873b02a51860bb0c74146fb854e34a53de74dc7200a365bb5bfa85f85caf5b9c0c81ead9c2990066139ebc6e5387f00d
+  metadata.gz: 923689df34d18c7357785812424acc62f38f89a3966c568bfd6e86f03c41eb1a9dd629eebdee4b1ae9321e42e1180d0be65af560613e31543496ebc312c40a30
+  data.tar.gz: 2624224d31f066ef9562333264e6f1cc00275bf72ab35942a1b0b3097864a14c89f04a6d4ebeee7ffb07ce240f22bde8f07939b61ee64a8019017ceceead23c9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quince (0.1.1)
+    quince (0.3.0)
       oj (~> 3.13)
       typed_struct (>= 0.1.4)
 
@@ -9,7 +9,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.4.4)
-    oj (3.13.5)
+    oj (3.13.6)
     rake (13.0.6)
     rbs (1.6.2)
     rspec (3.10.0)

data/README.md

@@ -1,15 +1,162 @@
 # Quince
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/quince`. To experiment with that code, run `bin/console` for an interactive prompt.
+### What is Quince?
 
-TODO: Delete this and the text above, and describe your gem
+Quince is an opinionated framework for building dynamic yet fully server-rendered web apps, with little to no JavaScript.
+
+### Inspired by
+
+React, Turbo, Hotwire amongst others
+
+### Current status
+
+Proof of concept, but [working in production](https://quince-rb.herokuapp.com/), and with decent performance despite few optimisations at this stage
+
+### How it works
+
+- Define some components and `expose` them at certain routes
+- Define some interactions that can take place, which can change the state of the components, and are handled with ruby methods
+- The front end will swap out the updated components with new HTML re-rendered by the back end
+
+## Minimal 'hello world' example
+
+```ruby
+# app.rb
+require "quince_sinatra"
+
+class App < Quince::Component
+    def render
+      html(
+        head,
+        body("hello world")
+      )
+    end
+end
+
+expose App, at: "/"
+```
+
+- Run it via
+```sh
+ruby app.rb
+```
+
+- Visit `localhost:4567/`!
+
+## More complex example
+
+```ruby
+require 'quince_sinatra'
+
+class App < Quince::Component
+    def render
+      Layout(title: "First app") {[
+        Counter()
+      ]}
+    end
+end
+
+class Layout < Quince::Component
+  Props(title: String)
+
+  def render
+      html(
+        head(
+            internal_scripts
+        ),
+        body(
+            h1(props.title),
+            children
+        )
+      )
+  end
+end
+
+class Counter < Quince::Component
+    State(val: Integer)
+
+    def initialize
+      @state = State.new(
+          val: params.fetch(:val, 0),
+      )
+    end
+
+    exposed def increment
+        state.val += 1
+    end
+
+    exposed def decrement
+        state.val -= 1
+    end
+
+    def render
+        div(
+            h2("count is #{state.val}"),
+            button(onclick: method(:increment)) { "++" },
+            button(onclick: method(:decrement)) { "--" }
+        )
+    end
+end
+
+expose App, at: "/"
+```
+
+#### See https://github.com/johansenja/quince-demo and https://quince-rb.herokuapp.com/ for more
+
+## Why Quince?
+
+### Why not?
+
+- You have pre-existing APIs which you want to integrate a front end with
+- You want to share the back end API with a different service
+- You want more offline functionality
+- You need a super complex/custom front end
+
+### Why?
+
+- Lightweight 🪶
+    - Very few dependencies
+    - Just a couple hundred lines of core logic
+    - Fewer than 30 lines (unminified) of JavaScript in the front end
+- Plug and play into multiple back ends 🔌
+- Components > templates 🧩
+    - Write html-like elements, but with strong typo resistence
+    - no special syntax or compilation required
+- Shallow learning curve if you are already familiar with React 📈
+- Just worry about your core business logic and how the app looks 🧪
+    - No need to worry about
+        - routes
+        - controllers
+        - front end -> back end communication/APIs/Data transfer
+        - front end -> back end code sharing
+    - Quince handles these for you
+- No node_modules 📦
+    - No yarn/npm
+    - Minimise bundle size concerns
+    - Manage your dependencies just using bundler & rubygems
+    - Make use of other pre-built Quince components via rubygems
+- Get full use of Ruby's rich and comprehensive standard library 💎
+- Take advantage of Ruby's ability to wrap native libraries (eg. gems using C) ⚡️
+- Fully server-rendered responses 📡
+    - Single source of truth for your app's code (no code-sharing needed)
+    - Better SEO out the box
+    - Know exactly what your user is seeing
+        - Tracking a user's activity on the front end has become a big deal, especially in heavily front-end driven apps/SPAs, in order to be able to see how a user is actually using the app (ie. to track how the state has been changing on the front end)
+        - This normally requires cookies and a premium third party service
+        - But if everything a user sees is generated server-side, it would be easy to reconstruct a user's journey and their state changes
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Quince itself is framework agnostic, so you should use an adaptor which plugs it into an existing framework for handling basic server needs
+
+### Install it via adapters
+
+- [Sinatra](https://github.com/johansenja/quince_sinatra)
+
+Pick one, and add it to your application's Gemfile, eg:
 
 ```ruby
-gem 'quince'
+gem 'quince_sinatra'
 ```
 
 And then execute:
@@ -18,11 +165,30 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install quince
-
-## Usage
-
-TODO: Write usage instructions here
+    $ gem install quince_sinatra
+
+
+## Usage notes
+
+- All HTML tags are available via a method of the same name, eg. `div()`, `section()`, `span()` - **with the exception of `para` standing in for `p` to avoid clashes with Ruby's common `Kernel#p` method**
+- All HTML attributes are available, and are the same as they would be in a regular html document, eg. `onclick` rather than `onClick` - **with the exception of a `Class`, `Max`, `Min`, `Method`** - which start with capital letters to avoid clashes with some internal methods.
+- Type checking is available at runtime for a component's `State` and `Props`, and is done in accordance with [Typed Struct](https://github.com/johansenja/typed_struct)
+- Children can be specified in one of two places, depending on what you would prefer:
+    -  as a block argument, to maintain similar readability with real html elements, where attributes come first
+        ```ruby
+        div(id: :my_div, style: "color: red") { h1("Single child") }
+        div(id: "div2", style: "color: green") {[
+            h2("multiple"),
+            h3("children")
+        ]}
+        ```
+    -  as positional arguments (for convenience and cleanliness when no props are passed)
+        ```ruby
+        div(
+            h1("hello world")
+        )
+        ```
+- A component's `render` method should always return a single top level element, ie. if you wanted to return 2 elements you should wrap them in a `div`
 
 ## Development
 
@@ -32,7 +198,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/quince.
+Bug reports and pull requests are welcome on GitHub at https://github.com/johansenja/quince.
 
 ## License
 

data/lib/quince/attributes_by_element.rb

@@ -11,11 +11,12 @@ module Quince
     t = Quince::Types
     opt_string_sym = Rbs("#{t::OptionalString} | Symbol")
     opt_bool = t::OptionalBoolean
-    opt_method = Rbs("Method | Quince::Types::Undefined")
+    opt_callback = Rbs("Quince::Callback::Interface | Quince::Types::Undefined")
     value = opt_string_sym # for now
 
     ATTRIBUTES_BY_ELEMENT = {
       "A" => {
+        # download: t::Any,
         href: opt_string_sym,
         hreflang: opt_string_sym,
         media: opt_string_sym,
@@ -336,7 +337,7 @@ module Quince
       "Area" => {
         alt: opt_string_sym,
         coords: opt_string_sym,
-        download: t::Any,
+        # download: t::Any,
         href: opt_string_sym,
         hreflang: opt_string_sym,
         media: opt_string_sym,
@@ -467,8 +468,13 @@ module Quince
     }.freeze
 
     DOM_EVENTS = {
-      onclick: opt_method,
-      onsubmit: opt_method,
+      onclick: opt_callback,
+      onsubmit: opt_callback,
+      onblur: opt_callback,
+      onchange: opt_callback,
+      onsearch: opt_callback,
+      onkeyup: opt_callback,
+      onselect: opt_callback,
     }.freeze
   end
 end

data/lib/quince/callback.rb

@@ -0,0 +1,36 @@
+module Quince
+  class Callback
+    module ComponentHelpers
+      protected
+
+      DEFAULT_CALLBACK_OPTIONS = {
+        prevent_default: false,
+        take_form_values: false,
+      # others could include:
+      # debounce: false,
+      }.freeze
+
+      def callback(method_name, **opts)
+        unless self.class.instance_variable_get(:@exposed_actions).member?(method_name)
+          raise "The action you called is not exposed"
+        end
+
+        opts = DEFAULT_CALLBACK_OPTIONS.merge opts
+
+        Callback.new(self, method_name, **opts)
+      end
+    end
+
+    module Interface
+      attr_reader :receiver, :method_name, :prevent_default, :take_form_values
+    end
+
+    include Interface
+
+    def initialize(receiver, method_name, prevent_default:, take_form_values:)
+      @receiver, @method_name = receiver, method_name
+      @prevent_default = prevent_default
+      @take_form_values = take_form_values
+    end
+  end
+end

data/lib/quince/component.rb

@@ -1,3 +1,5 @@
+require_relative "callback"
+
 module Quince
   class Component
     class << self
@@ -29,13 +31,10 @@ module Quince
           verb: meth0d,
           route: route,
         ) do |params|
-          instance = Quince::Serialiser.deserialise params[:component]
+          instance = Quince::Serialiser.deserialise(CGI.unescapeHTML(params[:component]))
+          Quince::Component.class_variable_set :@@params, params
           if @exposed_actions.member? action
-            if instance.method(action).arity.zero?
-              instance.send action
-            else
-              instance.send action, params[:params]
-            end
+            instance.send action
             instance
           else
             raise "The action you called is not exposed"
@@ -45,12 +44,17 @@ module Quince
         route
       end
 
-      def initial_state=(attrs)
-        @initial_state ||= self::State.new(**attrs)
+      def create(*children, **props, &block_children)
+        allocate.tap do |instance|
+          id = SecureRandom.alphanumeric 6
+          instance.instance_variable_set :@__id, id
+          instance.instance_variable_set :@props, initialize_props(self, id, **props)
+          kids = block_children ? block_children.call : children
+          instance.instance_variable_set(:@children, kids)
+          instance.send :initialize
+        end
       end
 
-      attr_reader :initial_state
-
       private
 
       def initialize_props(const, id, **props)
@@ -58,14 +62,12 @@ module Quince
       end
     end
 
-    attr_reader :props, :state, :children
+    include Callback::ComponentHelpers
 
-    def initialize(*children, **props, &block_children)
-      @__id = SecureRandom.alphanumeric(6)
-      @props = self.class.send :initialize_props, self.class, @__id, **props
-      @state = self.class.initial_state
-      @children = block_children || children
-    end
+    # set default
+    @@params = {}
+
+    attr_reader :props, :state, :children
 
     def render
       raise "not implemented"
@@ -77,11 +79,15 @@ module Quince
       self.class.exposed route, meth0d: via
     end
 
+    def params
+      @@params
+    end
+
     private
 
     attr_reader :__id
 
-    HTML_SELECTOR_ATTR = :"data-respid"
+    HTML_SELECTOR_ATTR = :"data-quid"
 
     def html_element_selector
       "[#{HTML_SELECTOR_ATTR}='#{__id}']".freeze

data/lib/quince/html_tag_components.rb

@@ -33,23 +33,22 @@ module Quince
           attrib = case value
             when String, Integer, Float, Symbol
               value.to_s
-            when Method
-              owner = value.owner
+            when Callback::Interface
               receiver = value.receiver
-              name = value.name
+              owner = receiver.class.name
+              name = value.method_name
               selector = receiver.send :html_element_selector
               internal = Quince::Serialiser.serialise receiver
-              payload = { component: internal }.to_json
-              case key
-              when :onclick
-                CGI.escape_html(
-                  "callRemoteEndpoint(`/api/#{owner}/#{name}`,`#{payload}`,`#{selector}`)"
-                )
-              when :onsubmit
-                CGI.escape_html(
-                  "const p = #{payload}; callRemoteEndpoint( `/api/#{owner}/#{name}`, JSON.stringify({...p, params: getFormValues(this)}), `#{selector}`); return false"
-                )
-              end
+              payload = { component: CGI.escapeHTML(internal) }.to_json
+              payload_var_name = "p"
+              stringify_payload = if value.take_form_values
+                  "{...#{payload_var_name}, params: getFormValues(this)}"
+                else
+                  payload_var_name
+                end
+              cb = %Q{const #{payload_var_name} = #{payload}; callRemoteEndpoint(`/api/#{owner}/#{name}`, JSON.stringify(#{stringify_payload}),`#{selector}`)}
+              cb += ";return false" if value.prevent_default
+              CGI.escape_html(cb)
             when true
               return key
             when false, nil, Quince::Types::Undefined

data/lib/quince/serialiser.rb

@@ -2,100 +2,11 @@ module Quince
   class Serialiser
     class << self
       def serialise(obj)
-        val = case obj
-          when Quince::Component
-            {
-              id: serialise(obj.send(:__id)),
-              props: serialise(obj.props),
-              state: serialise(obj.state),
-              children: serialise(obj.children),
-              html_element_selector: serialise(obj.send(:html_element_selector)),
-            }
-          when Array
-            obj.map { |e| serialise e }
-          when TypedStruct, Struct, OpenStruct, Hash
-            result = obj.each_pair.each_with_object({}) do |(k, v), ob|
-              case v
-              when Undefined
-                next
-              else
-                ob[k] = serialise(v)
-              end
-            end
-            if result.empty? && !obj.is_a?(Hash)
-              obj = nil
-              nil
-            else
-              result
-            end
-          when Proc
-            obj = obj.call # is there a more efficient way of doing this?
-            serialise(obj)
-          when String
-            res = obj.gsub "
-", "
-"
-            res.gsub! ?", '\"'
-            res
-          else
-            obj
-          end
-
-        { t: obj.class&.name, v: val }
+        Oj.dump(obj)
       end
 
       def deserialise(json)
-        case json[:t]
-        when "String", "Integer", "Float", "NilClass", "TrueClass", "FalseClass"
-          json[:v]
-        when "Symbol"
-          json[:v].to_sym
-        when "Array"
-          json[:v].map { |e| deserialise e }
-        when "Hash"
-          transform_hash json[:v]
-        when "OpenStruct"
-          OpenStruct.new(**transform_hash(props))
-        when nil
-          nil
-        else
-          klass = Object.const_get(json[:t])
-          if klass < TypedStruct
-            transform_hash_for_struct(json[:v]) || {}
-          elsif klass < Quince::Component
-            instance = klass.allocate
-            val = json[:v]
-            id = deserialise val[:id]
-
-            instance.instance_variable_set :@__id, id
-            instance.instance_variable_set(
-              :@props,
-              klass.send(
-                :initialize_props,
-                klass,
-                id,
-                **(deserialise(val[:props]) || {}),
-              ),
-            )
-            st = deserialise(val[:state])
-            instance.instance_variable_set :@state, klass::State.new(**st) if st
-            instance.instance_variable_set :@children, deserialise(val[:children])
-            instance
-          else
-            klass = Object.const_get(json[:t])
-            klass.new(deserialise(json[:v]))
-          end
-        end
-      end
-
-      private
-
-      def transform_hash(hsh)
-        hsh.transform_values! { |v| deserialise v }
-      end
-
-      def transform_hash_for_struct(hsh)
-        hsh.to_h { |k, v| [k.to_sym, deserialise(v)] }
+        Oj.load(json)
       end
     end
   end

data/lib/quince/singleton_methods.rb

@@ -10,21 +10,23 @@ module Quince
     def middleware=(middleware)
       @middleware = middleware
       Object.define_method(:expose) do |component, at:|
-        component = component.new if component.instance_of? Class
-
         Quince.middleware.create_route_handler(
           verb: :GET,
           route: at,
-          component: component,
-        )
+        ) do |params|
+          component = component.create if component.instance_of? Class
+          Quince::Component.class_variable_set :@@params, params
+          component
+        end
       end
+      Object.send :private, :expose
     end
 
     def define_constructor(const, constructor_name = const.to_s)
       HtmlTagComponents.instance_eval do
         define_method(constructor_name) do |*children, **props, &block_children|
           new_props = { **props, Quince::Component::HTML_SELECTOR_ATTR => __id }
-          const.new(*children, **new_props, &block_children)
+          const.create(*children, **new_props, &block_children)
         end
       end
     end

data/lib/quince/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quince
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/scripts.js

@@ -18,7 +18,11 @@ const callRemoteEndpoint = (endpoint, payload, selector) => {
   })
 }
 
-const getFormValues = (form) => {
+const getFormValues = (elem) => {
+  let form = elem.localName === "form" ? elem : elem.form;
+  if (!form) {
+    throw `element ${elem} should belong to a form`;
+  }
   const fd = new FormData(form);
   return Object.fromEntries(fd.entries());
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quince
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Joseph Johansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-09 00:00:00.000000000 Z
+date: 2021-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typed_struct
@@ -57,6 +57,7 @@ files:
 - bin/setup
 - lib/quince.rb
 - lib/quince/attributes_by_element.rb
+- lib/quince/callback.rb
 - lib/quince/component.rb
 - lib/quince/html_tag_components.rb
 - lib/quince/serialiser.rb