quince 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 057efcbe62deb405120d389ac7186e485961d9b5b258c5ba3934d10dc88d4998
-  data.tar.gz: 7e14d9297e3820d8d501bfd415e5f0891bc5e92b518609c895e1de45d8388605
+  metadata.gz: '0039bd9ca9658cfebba4048cc84fdbb095d8f2e656930501528f420c4dfa3bba'
+  data.tar.gz: a9720e7b11db54113fd56f1e09e43c980893297bbd5d3f46b1cdd0fc8ea2b61e
 SHA512:
-  metadata.gz: fc197781d667ea003854e622327175332d8ba958fcf87c2385b80f635590aa95f525ed9843c7c496aa6734b2f84d07ce31638d998160e00131a7635ad79fe0e6
-  data.tar.gz: 19678d0fabbe803917ce453e85aed1e6622c6c5729941d0a324323f0cc0e8502bf94d5194755d85fdd3d768ab31011fb4e57c58e39a57611f442569589d7b19e
+  metadata.gz: 6117b88cd23184b2072adae7b3b99ca868197119ffac9344477e6048519c735c7daa498067a4b96a92b60d68ce8fb5e0cc5a40529734c5c01c3b49e58317002d
+  data.tar.gz: f7952f3eea1cee2ef4153cbe4be1a5c709d777130f7eaa3be3ec0f5fa728da3550b81713766fcea6003673d8a65dd8a92aaae4ee3b1fb599b773463a67c5f05d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quince (0.1.2)
+    quince (0.4.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.7)
     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: callback(:increment)) { "++" },
+            button(onclick: callback(: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,14 @@ 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,
+      onscroll: opt_callback,
     }.freeze
   end
 end

data/lib/quince/callback.js.erb

@@ -0,0 +1,30 @@
+const p = this.dataset[`quOn<%= key.to_s[2..-1] %>State`];
+<% if value.debugger %>debugger;<% end %>
+<% if value.if %>
+if (<%= value.if %>) {
+<% end %>
+<% if value.debounce_ms %>
+if (!window[`<%= fn_name %>`]) window[`<%= fn_name %>`] = Q.d((p) => {
+<% end %>
+Q.c(
+`<%= endpoint %>`,
+JSON.stringify(
+{component: p, event: `<%= key.to_s[2..-1]  %>`,stateContainer: `<%= state_container %>`,
+<% if value.take_form_values %>
+params: Q.f(this),
+<% end %>
+<% if rerender %>
+rerender: <%= rerender.to_json %>,
+<% end %>}),
+`<%= rerender&.dig(:selector)&.to_s || selector %>`,
+<% if mode = rerender&.dig(:mode) %>`<%= mode.to_s %>`<% end %>
+);
+<% if value.debounce_ms&.positive? %>
+}, <%= value.debounce_ms %>); window[`<%= fn_name %>`](p)
+<% end %>
+<% if value.if %>
+};
+<% end %>
+<% if value.prevent_default %>
+;return false;
+<% end %>

data/lib/quince/callback.rb

@@ -0,0 +1,47 @@
+module Quince
+  class Callback
+    module ComponentHelpers
+      protected
+
+      DEFAULT_CALLBACK_OPTIONS = {
+        prevent_default: false,
+        take_form_values: false,
+        debounce_ms: nil,
+        if: nil,
+        debugger: false,
+        rerender: nil,
+      }.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,
+        *ComponentHelpers::DEFAULT_CALLBACK_OPTIONS.keys,
+      )
+    end
+
+    include Interface
+
+    def initialize(
+      receiver,
+      method_name,
+      **opts
+    )
+      @receiver, @method_name = receiver, method_name
+      ComponentHelpers::DEFAULT_CALLBACK_OPTIONS.each_key do |opt|
+        instance_variable_set :"@#{opt}", opts.fetch(opt)
+      end
+    end
+  end
+end

data/lib/quince/component.rb

@@ -1,3 +1,5 @@
+require_relative "callback"
+
 module Quince
   class Component
     class << self
@@ -8,7 +10,8 @@ module Quince
       def Props(**kw)
         self.const_set "Props", TypedStruct.new(
           { default: Quince::Types::Undefined },
-          Quince::Component::HTML_SELECTOR_ATTR => String,
+          Quince::Component::PARENT_SELECTOR_ATTR => String,
+          Quince::Component::SELF_SELECTOR => String,
           **kw,
         )
       end
@@ -21,21 +24,26 @@ module Quince
         self.const_set "State", st
       end
 
-      def exposed(action, meth0d: :POST)
+      def exposed(action, method: :POST)
         @exposed_actions ||= Set.new
         @exposed_actions.add action
         route = "/api/#{self.name}/#{action}"
         Quince.middleware.create_route_handler(
-          verb: meth0d,
+          verb: method,
           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
+          render_with = if params[:rerender]
+                          instance.instance_variable_set :@state_container, params[:stateContainer]
+                          params[:rerender][:method].to_sym
+                        else
+                          :render
+                        end
+          instance.instance_variable_set :@render_with, render_with
+          instance.instance_variable_set :@callback_event, params[:event]
           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,27 +53,32 @@ 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)
-        const::Props.new(HTML_SELECTOR_ATTR => id, **props) if const.const_defined?("Props")
+        if const.const_defined?("Props")
+          const::Props.new(PARENT_SELECTOR_ATTR => id, **props, SELF_SELECTOR => id)
+        end
       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"
@@ -74,17 +87,26 @@ module Quince
     protected
 
     def to(route, via: :POST)
-      self.class.exposed route, meth0d: via
+      self.class.exposed route, method: via
+    end
+
+    def params
+      @@params
     end
 
     private
 
     attr_reader :__id
 
-    HTML_SELECTOR_ATTR = :"data-respid"
+    PARENT_SELECTOR_ATTR = :"data-quid-parent"
+    SELF_SELECTOR = :"data-quid"
+
+    def html_parent_selector
+      "[#{PARENT_SELECTOR_ATTR}='#{__id}']".freeze
+    end
 
-    def html_element_selector
-      "[#{HTML_SELECTOR_ATTR}='#{__id}']".freeze
+    def html_self_selector
+      "[#{SELF_SELECTOR}='#{props[SELF_SELECTOR]}']".freeze
     end
   end
 end

data/lib/quince/html_tag_components.rb

@@ -1,9 +1,13 @@
 require "oj"
 require_relative "attributes_by_element"
 require_relative "serialiser"
+require "erb"
 
 module Quince
   module HtmlTagComponents
+    CALLBACK_TEMPLATE = File.read(File.join(__dir__, "callback.js.erb")).delete!("\n").freeze
+    CALLBACK_ERB_INSTANCE = ERB.new(CALLBACK_TEMPLATE)
+
     def self.define_html_tag_component(const_name, attrs, self_closing: false)
       klass = Class.new(Quince::Component) do
         Props(
@@ -17,9 +21,12 @@ module Quince
               props.each_pair.map { |k, v| to_html_attr(k, v) }.compact.join(" ")
             end
           result = "<#{tag_name}"
-          result << " #{attrs}>" unless attrs.empty?
-
-          return result if self_closing?
+          if !attrs.empty?
+            result << " #{attrs}>"
+            return result if self_closing?
+          elsif attrs.empty? && self_closing?
+            return result << ">"
+          end
 
           result << Quince.to_html(children)
           result << "</#{tag_name}>"
@@ -33,27 +40,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
-              selector = receiver.send :html_element_selector
+              owner = receiver.class.name
+              name = value.method_name
+              endpoint = "/api/#{owner}/#{name}"
+              selector = receiver.send :html_parent_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
+              fn_name = "_Q_#{key}_#{receiver.send(:__id)}"
+              rerender = value.rerender
+              state_container = html_self_selector
+              code = CALLBACK_ERB_INSTANCE.result(binding)
+              return %Q{#{key}="#{CGI.escape_html(code)}" data-qu-#{key}-state="#{CGI.escapeHTML(internal)}"}
             when true
               return key
             when false, nil, Quince::Types::Undefined
-              return ""
+              return nil
             else
               raise "prop type not yet implemented #{value}"
             end

data/lib/quince/serialiser.rb

@@ -2,98 +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 "\n", '\n'
-            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,24 @@ 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.instance_variable_set :@render_with, :render
+          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)
+          new_props = { **props, Quince::Component::PARENT_SELECTOR_ATTR => __id }
+          const.create(*children, **new_props, &block_children)
         end
       end
     end
@@ -42,12 +45,30 @@ module Quince
           output = to_html(output.call)
         when NilClass
           output = ""
-        else
+        when Component
           tmp = output
-          output = output.render
-          if output.is_a?(Array)
-            raise "#render in #{tmp.class} should not return multiple elements. Consider wrapping it in a div"
+          render_with = output.instance_variable_get(:@render_with) || :render
+          output = output.send render_with
+          case render_with
+          when :render
+            if output.is_a?(Array)
+              raise "#render in #{tmp.class} should not return multiple elements. Consider wrapping it in a div"
+            end
+          else
+            internal = Quince::Serialiser.serialise tmp
+            updated_state = CGI.escapeHTML(internal).to_json
+            selector = tmp.instance_variable_get :@state_container
+            event = tmp.instance_variable_get :@callback_event
+
+            scr = to_html(HtmlTagComponents::Script.create(<<~JS, type: "text/javascript"))
+              var stateContainer = document.querySelector(`#{selector}`);
+              stateContainer.dataset.quOn#{event}State = #{updated_state};
+            JS
+
+            output += (output.is_a?(String) ? scr : [scr])
           end
+        else
+          raise "don't know how to render #{output.class} (#{output.inspect})"
         end
       end
 

data/lib/quince/version.rb

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

data/scripts.js

@@ -1,24 +1,75 @@
-const callRemoteEndpoint = (endpoint, payload, selector) => {
-  fetch(
-    endpoint,
-    {
-      method: `POST`,
-      headers: {
-        "Content-Type": `application/json;charset=utf-8`
-      },
-      body: payload,
-    }
-  ).then(resp => resp.text()).then(html => {
-    const element = document.querySelector(selector);
-    if (!element) {
-      throw `element not found for ${selector}`;
-    }
+const Q = {
+  c: (endpoint, payload, selector, mode = "replace") => {
+    return fetch(
+      endpoint,
+      {
+        method: `POST`,
+        headers: {
+          "Content-Type": `application/json;charset=utf-8`
+        },
+        body: payload,
+      }
+    ).then(resp => resp.text()).then(html => {
+      const element = document.querySelector(selector);
+      if (!element) {
+        throw `element not found for ${selector}`;
+      }
 
-    element.outerHTML = html
-  })
-}
+      switch (mode) {
+        case "append_diff":
+          const tmpElem = document.createElement(element.nodeName);
+          tmpElem.innerHTML = html;
+          const newNodes = Array.from(tmpElem.childNodes);
+          const script = newNodes.pop();
+          const existingChildren = element.childNodes;
+          // This comparison doesn't currently work because of each node's unique id (data-quid).
+          // maybe it would be possible to use regex replace to on the raw html, but it could also
+          // be overkill
+          // let c = 0;
+          // for (; c < existingChildren.length; c++) {
+          //   if (existingChildren[c].isEqualNode(newNodes[c]))
+          //     continue;
+          //   else
+          //     break;
+          // }
+          // for the time being, we can just assume that we can just take the extra items
+          let c = existingChildren.length;
+          for (const node of newNodes.slice(c)) {
+            element.appendChild(node);
+          }
+
+          const newScript = document.createElement("script");
+          newScript.dataset.quid = script.dataset.quid;
+          newScript.innerHTML = script.innerHTML;
+          document.head.appendChild(newScript);
+          break;
+        case "replace": 
+          element.outerHTML = html;
+          break;
+        default:
+          throw `mode ${mode} is not valid`;
+      }
+    })
+  },
+  f: (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());
+  },
+  d: (func, wait_ms) => {
+    let timer = null;
 
-const getFormValues = (form) => {
-  const fd = new FormData(form);
-  return Object.fromEntries(fd.entries());
-}
+    return (...args) => {
+      clearTimeout(timer);
+      return new Promise((resolve) => {
+        timer = setTimeout(
+          () => resolve(func(...args)),
+          wait_ms,
+        );
+      });
+    };
+  },
+};

metadata

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