quince 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 057efcbe62deb405120d389ac7186e485961d9b5b258c5ba3934d10dc88d4998
-  data.tar.gz: 7e14d9297e3820d8d501bfd415e5f0891bc5e92b518609c895e1de45d8388605
+  metadata.gz: dcc2582bba48ffba3d17a6bd6efe972db91c70d3680348334342e01ad8506158
+  data.tar.gz: af1dccbf8ea37419b4eb4936ea8f4fa20e60509d5c78a460d21df08ded15698d
 SHA512:
-  metadata.gz: fc197781d667ea003854e622327175332d8ba958fcf87c2385b80f635590aa95f525ed9843c7c496aa6734b2f84d07ce31638d998160e00131a7635ad79fe0e6
-  data.tar.gz: 19678d0fabbe803917ce453e85aed1e6622c6c5729941d0a324323f0cc0e8502bf94d5194755d85fdd3d768ab31011fb4e57c58e39a57611f442569589d7b19e
+  metadata.gz: 7d16ca52523b06dddb32cd22aac945690836c0b094051248394f823d56d35933a0bc163b2250e57fb6ccbcbdbe956db12865da486e16b5024148d83566059d46
+  data.tar.gz: 8550f7c684a827e2c3b714e6e00c6e2b37bfdb2f54f1daf7dfe6f3dde46e4a17859fe0f5a887d3bcd54877db400728acb08037156a0032561f327a42a9e3910f

data/Gemfile.lock

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

@@ -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,

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/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.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quince
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Joseph Johansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-09 00:00:00.000000000 Z
+date: 2021-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typed_struct