quince 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cb965782c941f40df31a058388f1c7e30864c5a1cf708f2840340bf014a3b16
-  data.tar.gz: 235e3aa8b1a759799f996f2d2170582f628ac32a80a69bd4fab2838d91dd3a03
+  metadata.gz: 1b5c0ef933d95f7026239bcfc5685e4aeb1582382056725b245cd37838540bf4
+  data.tar.gz: c790f0bc40602888167f46bf9636c55a739d5191645fd43e3614c78e381c6d1f
 SHA512:
-  metadata.gz: 8de7ca420355f54e90e5dc16517f670a6009ebf0d02f6fa45bbeddf2b92fb8eb9e05f8b1e1f9eec584aa6e283b9063146b8980b4b6c2b1463b4b104f6c967865
-  data.tar.gz: 0ac305e40cab122d9865e030572c704897a8daa5f2fa1dbb6222976834690be58efe1c4a5e1049b3f1e86846af584795ff41c2eb547490783d626544db677100
+  metadata.gz: d7f561f03a959ed9fb221d0462f8901fe9f0cb20bda9e80ede4757a6a5cf89c979da5f80c135054454ef64ad5ddec09751a23088fe08762084b13c097c56db3c
+  data.tar.gz: 47f28845aad32b4ba53f76acf4fab7695c903cb8d94197b6ac0096f16a2f048684f5677d35edeaa0c06554ae19d32152294f878e5ef5e8cbd9eccd581671389a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quince (0.1.0)
+    quince (0.2.1)
       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

@@ -16,6 +16,7 @@ module Quince
 
     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,
@@ -469,6 +470,11 @@ module Quince
     DOM_EVENTS = {
       onclick: opt_method,
       onsubmit: opt_method,
+      onblur: opt_method,
+      onchange: opt_method,
+      onsearch: opt_method,
+      onkeyup: opt_method,
+      onselect: opt_method,
     }.freeze
   end
 end

data/lib/quince/component.rb

@@ -30,12 +30,9 @@ module Quince
           route: route,
         ) do |params|
           instance = Quince::Serialiser.deserialise 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 +42,16 @@ 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)
+          instance.instance_variable_set(:@children, block_children || children)
+          instance.send :initialize
+        end
       end
 
-      attr_reader :initial_state
-
       private
 
       def initialize_props(const, id, **props)
@@ -58,14 +59,10 @@ module Quince
       end
     end
 
-    attr_reader :props, :state, :children
+    # set default
+    @@params = {}
 
-    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
+    attr_reader :props, :state, :children
 
     def render
       raise "not implemented"
@@ -77,6 +74,10 @@ module Quince
       self.class.exposed route, meth0d: via
     end
 
+    def params
+      @@params
+    end
+
     private
 
     attr_reader :__id

data/lib/quince/html_tag_components.rb

@@ -45,10 +45,13 @@ module Quince
                 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"
-                )
+              when :onsubmit, :onchange, :onblur, :onsearch, :onkeyup, :onselect
+                ev = "const p = #{payload}; callRemoteEndpoint( `/api/#{owner}/#{name}`, JSON.stringify({...p, params: getFormValues(this)}), `#{selector}`)"
+                case key
+                when :onsubmit
+                  ev += "; return false"
+                end
+                CGI.escape_html(ev)
               end
             when true
               return key

data/lib/quince/serialiser.rb

@@ -32,9 +32,7 @@ module Quince
             obj = obj.call # is there a more efficient way of doing this?
             serialise(obj)
           when String
-            res = obj.gsub "
-", "
-"
+            res = obj.gsub "\n", '\n'
             res.gsub! ?", '\"'
             res
           else

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.0"
+  VERSION = "0.2.1"
 end

data/lib/quince.rb

@@ -4,3 +4,4 @@ require "cgi"
 require_relative "quince/singleton_methods"
 require_relative "quince/component"
 require_relative "quince/html_tag_components"
+require_relative "quince/version"

data/scripts.js

@@ -0,0 +1,28 @@
+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}`;
+    }
+
+    element.outerHTML = html
+  })
+}
+
+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.0
+  version: 0.2.1
 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
@@ -64,6 +64,7 @@ files:
 - lib/quince/types.rb
 - lib/quince/version.rb
 - quince.gemspec
+- scripts.js
 homepage: https://github.com/johansenja/quince
 licenses:
 - MIT