quince 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7821a6a97b508f9ad109b4ae7e59d9ccd774b94b2e451a9809eed7fa941e5cba
-  data.tar.gz: 5d5b6137d4089497408776c24152239fb99ac4977d5c31778cfa9bfa21518ee4
+  metadata.gz: f42655bc57603a51bd5231388dc7be387a51a8e912549f6a504fbaeb0e1dbb3e
+  data.tar.gz: ed87a57062ce7343b08409fd8126034a7dbf46e094b1741829fc63fdb9ab1f7d
 SHA512:
-  metadata.gz: cb40eef0228b05bb3a7a05b7c32ec1b3bf47cd261d25a164f7df018e2dc94a5e720565ca7d2fd58edbb39899a481cbf7aacc50f01c97cd73bd815ca7dc95938b
-  data.tar.gz: a6fb31c6d7835f380670ee3be74952786653bf3a3b5f7712c0ac4dd9526b8e2f9564c127d71fe16c12cebbdccf0cd4df9cbcd8a3d243c327323572baa7ebde4a
+  metadata.gz: 7c5358907ee716710a7c0f53c277ede1301ee16c31ab2304a63d33cdd91dff9f80a282f2832637d7b5ad14d4103d65a5f9ce16c4ed02cda14f9a148145263ee5
+  data.tar.gz: 0dc9bad86700382b48810bf70a2c0b0258c7e3383a4b73a37ea84fc46bf8ca174f2e20404c5070723512ffd2c1f0b1a61447bd9ce3da9eec6275e2dc8a003309

data/Gemfile.lock

@@ -1,15 +1,26 @@
 PATH
   remote: .
   specs:
-    quince (0.4.1)
+    quince (0.6.0)
       oj (~> 3.13)
+      rack-contrib (~> 2.3)
+      sinatra (~> 2.1)
+      sinatra-contrib (~> 2.1)
       typed_struct (>= 0.1.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.4.4)
-    oj (3.13.7)
+    multi_json (1.15.0)
+    mustermann (1.1.1)
+      ruby2_keywords (~> 0.0.1)
+    oj (3.13.9)
+    rack (2.2.3)
+    rack-contrib (2.3.0)
+      rack (~> 2.0)
+    rack-protection (2.1.0)
+      rack
     rake (13.0.6)
     rbs (1.6.2)
     rspec (3.10.0)
@@ -25,6 +36,19 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
+    ruby2_keywords (0.0.5)
+    sinatra (2.1.0)
+      mustermann (~> 1.0)
+      rack (~> 2.2)
+      rack-protection (= 2.1.0)
+      tilt (~> 2.0)
+    sinatra-contrib (2.1.0)
+      multi_json
+      mustermann (~> 1.0)
+      rack-protection (= 2.1.0)
+      sinatra (= 2.1.0)
+      tilt (~> 2.0)
+    tilt (2.0.10)
     typed_struct (0.1.4)
       rbs (~> 1.0)
 

data/README.md

@@ -10,7 +10,8 @@ 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
+Early, but [working in production](https://quince-rb.herokuapp.com/). Expect more features and
+optimisations to come, but also potential for big changes between versions in the early stages.
 
 ### How it works
 
@@ -22,7 +23,7 @@ Proof of concept, but [working in production](https://quince-rb.herokuapp.com/),
 
 ```ruby
 # app.rb
-require "quince_sinatra"
+require "quince"
 
 class App < Quince::Component
     def render
@@ -46,7 +47,7 @@ ruby app.rb
 ## More complex example
 
 ```ruby
-require 'quince_sinatra'
+require 'quince'
 
 class App < Quince::Component
     def render
@@ -114,49 +115,23 @@ expose App, at: "/"
 
 ### 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
+- Lightweight 🪶
 - 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
+- Focus on your core business logic, not routes/APIs/data transfer/code sharing 🧪
+- No compilation/node_modules/yarn/js bundle size concerns - just bundler 📦
 - 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
+- Fully server-rendered responses - single source of truth 📡
+- Easy to recreate/rehydrate a pages state (almost nothing is stored in memory from JavaScript - all
+  the state is stored with the HTML document's markup)
 
 ## Installation
 
-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:
+Add this to your application's Gemfile:
 
 ```ruby
-gem 'quince_sinatra'
+gem 'quince'
 ```
 
 And then execute:
@@ -165,7 +140,7 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install quince_sinatra
+    $ gem install quince
 
 
 ## Usage notes

data/lib/quince/attributes_by_element.rb

@@ -4,19 +4,19 @@ require_relative "types"
 
 module Quince
   module HtmlTagComponents
-    referrer_policy = Rbs("'' | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | Quince::Types::Undefined")
+    referrer_policy = Rbs("'' | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url' | nil")
     form_method = Rbs(
-      '"get" | "post" | "GET" | "POST" | :GET | :POST | :get | :post | Quince::Types::Undefined'
+      '"get" | "post" | "GET" | "POST" | :GET | :POST | :get | :post | nil'
     )
     t = Quince::Types
     opt_string_sym = Rbs("#{t::OptionalString} | Symbol")
     opt_bool = t::OptionalBoolean
-    opt_callback = Rbs("Quince::Callback::Interface | Quince::Types::Undefined")
+    opt_callback = Rbs("Quince::Callback::Interface | nil")
     value = opt_string_sym # for now
 
     ATTRIBUTES_BY_ELEMENT = {
       "A" => {
-        # download: t::Any,
+        download: opt_string_sym,
         href: opt_string_sym,
         hreflang: opt_string_sym,
         media: opt_string_sym,
@@ -58,7 +58,7 @@ module Quince
         formnovalidate: opt_bool,
         formtarget: opt_string_sym,
         name: opt_string_sym,
-        type: Rbs("'submit' | 'reset' | 'button' | Quince::Types::Undefined"),
+        type: Rbs("'submit' | 'reset' | 'button' | nil"),
         value: value,
       }.freeze,
       "Canvas" => {
@@ -128,7 +128,7 @@ module Quince
         allowfullscreen: opt_bool,
         allowtransparency: opt_bool,
         height: opt_string_sym,
-        loading: Rbs('"eager" | "lazy" | Quince::Types::Undefined'),
+        loading: Rbs('"eager" | "lazy" | nil'),
         name: opt_string_sym,
         referrerpolicy: referrer_policy,
         sandbox: opt_string_sym,
@@ -192,7 +192,7 @@ module Quince
       "Ol" => {
         reversed: opt_bool,
         start: opt_string_sym,
-        type: Rbs("'1' | 'a' | 'A' | 'i' | 'I' | Quince::Types::Undefined"),
+        type: Rbs("'1' | 'a' | 'A' | 'i' | 'I' | nil"),
       }.freeze,
       "Optgroup" => {
         disabled: opt_bool,
@@ -270,7 +270,7 @@ module Quince
       }.freeze,
       "Tbody" => {}.freeze,
       "Td" => {
-        align: Rbs('"left" | "center" | "right" | "justify" | "char" | Quince::Types::Undefined'),
+        align: Rbs('"left" | "center" | "right" | "justify" | "char" | nil'),
         colspan: opt_string_sym,
         headers: opt_string_sym,
         rowspan: opt_string_sym,
@@ -278,7 +278,7 @@ module Quince
         abbr: opt_string_sym,
         height: opt_string_sym,
         width: opt_string_sym,
-        valign: Rbs('"top" | "middle" | "bottom" | "baseline" | Quince::Types::Undefined'),
+        valign: Rbs('"top" | "middle" | "bottom" | "baseline" | nil'),
       }.freeze,
       "Textarea" => {
         autocomplete: opt_string_sym,
@@ -300,7 +300,7 @@ module Quince
       }.freeze,
       "Tfoot" => {}.freeze,
       "Th" => {
-        align: Rbs('"left" | "center" | "right" | "justify" | "char" | Quince::Types::Undefined'),
+        align: Rbs('"left" | "center" | "right" | "justify" | "char" | nil'),
         colspan: opt_string_sym,
         headers: opt_string_sym,
         rowspan: opt_string_sym,
@@ -337,7 +337,7 @@ module Quince
       "Area" => {
         alt: opt_string_sym,
         coords: opt_string_sym,
-        # download: t::Any,
+        download: opt_string_sym,
         href: opt_string_sym,
         hreflang: opt_string_sym,
         media: opt_string_sym,
@@ -364,10 +364,10 @@ module Quince
       "Hr" => {}.freeze,
       "Img" => {
         alt: opt_string_sym,
-        crossorigin: Rbs('"anonymous" | "use-credentials" | "" | Quince::Types::Undefined'),
-        decoding: Rbs('"async" | "auto" | "sync" | Quince::Types::Undefined'),
+        crossorigin: Rbs('"anonymous" | "use-credentials" | "" | nil'),
+        decoding: Rbs('"async" | "auto" | "sync" | nil'),
         height: Rbs("#{opt_string_sym} | Integer"),
-        loading: Rbs('"eager" | "lazy" | Quince::Types::Undefined'),
+        loading: Rbs('"eager" | "lazy" | nil'),
         referrerpolicy: referrer_policy,
         sizes: opt_string_sym,
         src: opt_string_sym,
@@ -479,5 +479,3 @@ module Quince
     }.freeze
   end
 end
-
-Undefined = Quince::Types::Undefined

data/lib/quince/callback.js.erb

@@ -17,7 +17,8 @@ params: Q.f(this),
 rerender: <%= rerender.to_json %>,
 <% end %>}),
 `<%= rerender&.dig(:selector)&.to_s || selector %>`,
-<% if mode = rerender&.dig(:mode) %>`<%= mode.to_s %>`<% end %>
+`<%= (mode = rerender&.dig(:mode)) ? mode.to_s : "replace" %>`,
+<%= value.handle_errors.to_json %>,
 );
 <% unless push_params_state == "null" %>Q.ps(<%= push_params_state %>);<% end %>
 <% if value.debounce_ms&.positive? %>

data/lib/quince/callback.rb

@@ -11,6 +11,8 @@ module Quince
         debugger: false,
         rerender: nil,
         push_params_state: nil,
+        handle_errors: true,
+        download: false,
       }.freeze
 
       def callback(method_name, **opts)
@@ -28,7 +30,7 @@ module Quince
       attr_reader(
         :receiver,
         :method_name,
-        *ComponentHelpers::DEFAULT_CALLBACK_OPTIONS.keys,
+              *ComponentHelpers::DEFAULT_CALLBACK_OPTIONS.keys,
       )
     end
 

data/lib/quince/component.rb

@@ -1,3 +1,4 @@
+require "forwardable"
 require_relative "callback"
 
 module Quince
@@ -9,7 +10,6 @@ module Quince
 
       def Props(**kw)
         self.const_set "Props", TypedStruct.new(
-          { default: Quince::Types::Undefined },
           Quince::Component::PARENT_SELECTOR_ATTR => String,
           Quince::Component::SELF_SELECTOR => String,
           **kw,
@@ -17,10 +17,7 @@ module Quince
       end
 
       def State(**kw)
-        st = kw.empty? ? nil : TypedStruct.new(
-          { default: Quince::Types::Undefined },
-          **kw,
-        )
+        st = kw.empty? ? nil : TypedStruct.new(**kw)
         self.const_set "State", st
       end
 
@@ -28,18 +25,20 @@ module Quince
         @exposed_actions ||= Set.new
         @exposed_actions.add action
         route = "/api/#{self.name}/#{action}"
-        Quince.middleware.create_route_handler(
+        Quince::SinatraApp.create_route_handler(
           verb: method,
           route: route,
-        ) do |params|
+        ) do |bind|
+          Thread.current[:request_binding] = bind
+          params = bind.receiver.params
+          Thread.current[:params] = params[:params] || {}
           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
+          if params[:rerender]
+            instance.instance_variable_set :@state_container, params[:stateContainer]
+            render_with = params[:rerender][:method].to_sym
+          else
+            render_with = :render
+          end
           instance.instance_variable_set :@render_with, render_with
           instance.instance_variable_set :@callback_event, params[:event]
           if @exposed_actions.member? action
@@ -68,16 +67,18 @@ module Quince
 
       def initialize_props(const, id, **props)
         if const.const_defined?("Props")
-          const::Props.new(PARENT_SELECTOR_ATTR => id, **props, SELF_SELECTOR => id)
+          const::Props.new(
+            PARENT_SELECTOR_ATTR => id,
+            **props,
+            SELF_SELECTOR => id,
+          )
         end
       end
     end
 
+    extend Forwardable
     include Callback::ComponentHelpers
 
-    # set default
-    @@params = {}
-
     attr_reader :props, :state, :children
 
     def render
@@ -91,9 +92,15 @@ module Quince
     end
 
     def params
-      @@params
+      Thread.current[:params]
+    end
+
+    def request_context
+      Thread.current[:request_binding].receiver
     end
 
+    def_delegators :request_context, :attachment, :request, :response, :redirect, :halt
+
     private
 
     attr_reader :__id

data/lib/quince/html_tag_components.rb

@@ -55,7 +55,7 @@ module Quince
               return %Q{#{key}="#{CGI.escape_html(code)}" data-qu-#{key}-state="#{CGI.escapeHTML(internal)}"}
             when true
               return key
-            when false, nil, Quince::Types::Undefined
+            when false, nil
               return nil
             else
               raise "prop type not yet implemented #{value}"
@@ -92,14 +92,35 @@ module Quince
         contents
       }
     end
-  end
 
-  Quince::Component.include HtmlTagComponents
-end
+    ERROR_HANDLING_STYLES = <<~CSS.freeze
+      .quince-err-container {
+        position: absolute;
+        bottom: 32px;
+        width: 300px;
+        height: 50px;
+        background-color: white;
+        border-radius: 4px;
+        border: 1px solid #bbb;
+        z-index: 999;
+        box-shadow: 2px 2px 8px rgba(0,0,0,0.3);
+        padding: 0 24px;
+        left: calc(50vw - 50px);
+      }
 
-# tmp hack
-class TypedStruct < Struct
-  def to_json(*args)
-    to_h.to_json(*args)
+      .quince-err-msg {
+        font-size: 1.2em;
+        text-align: center;
+        margin: auto;
+        color: chocolate;
+      }
+    CSS
+    private_constant :ERROR_HANDLING_STYLES
+
+    def error_message_styles
+      style(ERROR_HANDLING_STYLES)
+    end
   end
+
+  Quince::Component.include HtmlTagComponents
 end

data/lib/quince/sinatra.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+ENV["RACK_ENV"] ||= "development"
+
+require "sinatra/base"
+require "sinatra/reloader" if ENV["RACK_ENV"] == "development"
+require "rack/contrib"
+
+module Quince
+  class SinatraApp < Sinatra::Base
+    configure :development do
+      if Object.const_defined? "Sinatra::Reloader"
+        register Sinatra::Reloader
+        dont_reload __FILE__
+        also_reload $0
+      end
+    end
+    use Rack::JSONBodyParser
+    use Rack::Deflater
+    set :public_folder, File.join(File.dirname(File.expand_path($0)), "public")
+
+    class << self
+      def create_route_handler(verb:, route:, &blck)
+        meth = case verb
+          when :POST, :post
+            :post
+          when :GET, :get
+            :get
+          else
+            raise "invalid verb"
+          end
+
+        public_send meth, route do
+          Quince.to_html(blck.call(binding))
+        ensure
+          Thread.current[:request_binding] = nil
+          Thread.current[:params] = nil
+        end
+      end
+    end
+  end
+end
+
+def expose(component, at:)
+  Quince::SinatraApp.get(at) do
+    Thread.current[:request_binding] = binding
+    Thread.current[:params] = binding.receiver.params
+    comp = component.instance_of?(Class) ? component.create : component
+    comp.instance_variable_set :@render_with, :render
+    Quince.to_html(comp)
+  ensure
+    Thread.current[:request_binding] = nil
+    Thread.current[:params] = nil
+  end
+end
+
+at_exit do
+  if $!.nil? || ($!.is_a?(SystemExit) && $!.success?)
+    if Object.const_defined? "Sinatra::Reloader"
+      app_dir = Pathname(File.expand_path($0)).dirname.to_s
+      $LOADED_FEATURES.each do |f|
+        next unless f.start_with? app_dir
+
+        Quince::SinatraApp.also_reload f
+      end
+    end
+
+    Quince::SinatraApp.run!
+  end
+end

data/lib/quince/singleton_methods.rb

@@ -1,34 +1,29 @@
 module Quince
   class << self
-    attr_reader :middleware
-    attr_accessor :underlying_app
-
-    def optional_string
-      @optional_string ||= Rbs("String?")
-    end
-
-    def middleware=(middleware)
-      @middleware = middleware
-      Object.define_method(:expose) do |component, at:|
-        Quince.middleware.create_route_handler(
-          verb: :GET,
-          route: at,
-        ) 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
+    def define_constructor(const, constructor_name = nil)
+      if const.name
+        parts = const.name.split("::")
+        parent_namespace = Object.const_get(parts[0...-1].join("::")) if parts.length > 1
+        constructor_name ||= parts.last
       end
-      Object.send :private, :expose
-    end
+      constructor_name ||= const.to_s
 
-    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::PARENT_SELECTOR_ATTR => __id }
+        mthd = lambda do |*children, **props, &block_children|
+          new_props = {
+            **props,
+            Quince::Component::PARENT_SELECTOR_ATTR => __id,
+          }
           const.create(*children, **new_props, &block_children)
         end
+
+        if parent_namespace
+          parent_namespace.instance_exec do
+            define_method(constructor_name, &mthd)
+          end
+        else
+          define_method(constructor_name, &mthd)
+        end
       end
     end
 
@@ -64,6 +59,7 @@ module Quince
               var stateContainer = document.querySelector(`#{selector}`);
               stateContainer.dataset.quOn#{event}State = #{updated_state};
             JS
+            output = output.render if output.is_a?(Component)
 
             output += (output.is_a?(String) ? scr : [scr])
           end
@@ -76,3 +72,10 @@ module Quince
     end
   end
 end
+
+############## TODO #############
+# I think you should be able to know when a component is the first to be called in a render method,
+# so you should be able to attach some props to it behind the scenes. Then any consumers of this
+# state just have to know the selector, so they can read from it before passing it to the back end.
+#
+# Also, the front end needs to be updated such that script tags from the back end are always read

data/lib/quince/types.rb

@@ -1,13 +1,8 @@
 module Quince
   module Types
-    class Base; end
-
     # precompiled helper types
-    OptionalString = Rbs("String | Quince::Types::Undefined").freeze
-    OptionalBoolean = Rbs("true | false | Quince::Types::Undefined").freeze
-
-    # no functional value for now, other than constants
-    Undefined = Class.new(Base).new.freeze
-    Any = Class.new(Base).new.freeze
+    OptionalString = Rbs("String?").freeze
+    OptionalBoolean = Rbs("true | false | nil").freeze
+    Any = Rbs("untyped").freeze
   end
 end

data/lib/quince/version.rb

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

data/lib/quince.rb

@@ -5,3 +5,4 @@ require_relative "quince/singleton_methods"
 require_relative "quince/component"
 require_relative "quince/html_tag_components"
 require_relative "quince/version"
+require_relative "quince/sinatra"

data/quince.gemspec

@@ -29,6 +29,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
+  spec.add_dependency "sinatra", "~> 2.1"
+  spec.add_dependency "sinatra-contrib", "~> 2.1"
+  spec.add_dependency "rack-contrib", "~> 2.3"
   spec.add_dependency "typed_struct", ">= 0.1.4"
   spec.add_dependency "oj", "~> 3.13"
 

data/scripts.js

@@ -1,5 +1,5 @@
 const Q = {
-  c: (endpoint, payload, selector, mode = "replace") => {
+  c: (endpoint, payload, selector, mode, handleErrors) => {
     return fetch(
       endpoint,
       {
@@ -9,46 +9,78 @@ const Q = {
         },
         body: payload,
       }
-    ).then(resp => resp.text()).then(html => {
-      const element = document.querySelector(selector);
-      if (!element) {
-        throw `element not found for ${selector}`;
+    ).then(resp => {
+      if (resp.status <= 299) {
+        const cd = resp.headers.get("Content-Disposition");
+        if (cd && cd.trim().startsWith("attachment")) {
+         return resp.blob(); 
+        } else {
+          return resp.text();
+        }
+      } else if (resp.status >= 500) {
+        throw Q.em["500"];
+      } else {
+        let msg = Q.em[`${resp.code}`];
+        
+        if (!msg && resp.code >= 400) msg = Q.em.generic;
+        
+        throw msg;
       }
-
-      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);
+    }).then(data => {
+      switch (true) {
+        case data instanceof Blob:
+          const url = URL.createObjectURL(data);
+          const a = document.createElement('a');
+          a.href = url;
+          a.download = "download";
+          document.body.appendChild(a);
+          a.click();
+          a.remove();
+          break;
+        default: // html
+          const element = document.querySelector(selector);
+          if (!element) {
+            throw `element not found for ${selector}`;
           }
 
-          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`;
+          switch (mode) {
+            case "append_diff":
+              const tmpElem = document.createElement(element.nodeName);
+              tmpElem.innerHTML = data;
+              const newNodes = Array.from(tmpElem.childNodes);
+              const script = newNodes.pop();
+              const existingChildren = element.childNodes;
+              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 = data;
+              break;
+            default:
+              throw `mode ${mode} is not valid`;
+          }
       }
+    }).catch(err => {
+      if (!handleErrors) throw err;
+
+      let msg;
+      if (typeof err === "string") {
+        msg = err;
+      } else if (err.message) {
+        if (err.message.startsWith("NetworkError")) {
+          msg = Q.em.network;
+        } else {
+          msg = err.message;
+        }
+      } else msg = Q.em.generic;
+      Q.e(msg, 2500);
     })
   },
   f: (elem) => {
@@ -79,5 +111,29 @@ const Q = {
       url.searchParams.append(p, stateObj[p]);
     };
     window.history.pushState({}, document.title, url);
+  },
+  e: (msg, durationMs) => {
+    const containerClassName = "quince-err-container";
+    document.querySelectorAll(`.${containerClassName}`).forEach(e => e.remove());
+    const container = document.createElement("div");
+    const strong = document.createElement("strong");
+    strong.innerText = msg;
+    container.className = containerClassName;
+    strong.className = "quince-err-msg";
+    container.appendChild(strong);
+    document.body.insertAdjacentElement("afterbegin", container);
+    setTimeout(() => container.remove(), durationMs);
+  },
+  em: {
+    400: "Bad request",
+    401: "Unauthorised",
+    402: "Payment required",
+    403: "Forbidden",
+    404: "Not found",
+    422: "Unprocessable entity",
+    429: "Too many requests",
+    500: "Internal server error",
+    generic: "An error occurred",
+    network: "Network error", 
   }
 };

metadata

@@ -1,15 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: quince
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Joseph Johansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-24 00:00:00.000000000 Z
+date: 2021-10-17 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: sinatra-contrib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rack-contrib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: typed_struct
   requirement: !ruby/object:Gem::Requirement
@@ -62,6 +104,7 @@ files:
 - lib/quince/component.rb
 - lib/quince/html_tag_components.rb
 - lib/quince/serialiser.rb
+- lib/quince/sinatra.rb
 - lib/quince/singleton_methods.rb
 - lib/quince/types.rb
 - lib/quince/version.rb