porous 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 764d087181654089e95897a26692efd6bf2b3302f36a1917695c9e5e7ba3c088
-  data.tar.gz: 7eb52c0975ce2611e1e0b57591cd0da848c639a0873785a3e6023e3506852a18
+  metadata.gz: 605209154f6a44bc2c7a84934bf661de4c721a2a5ed5f3b9c21556064ac1672e
+  data.tar.gz: 27eb154e0be5f0b524e723355c1544541b26207f36e49eb372cea7d06e24cdd5
 SHA512:
-  metadata.gz: 5ca6f72a3d234ca0e368da80f7c4c839fd6d80b5577ef3eca7df9f2c0788bbb3891a099bb62568eaa3357f3940c8e6c6cd65f5dfd42d25713cb85ea812696df7
-  data.tar.gz: e16772a071f6cf91395774bac8b01374173624f5fff38e97539fbe3b72c6586538b2f716a851093cb46ee9aaa583ef1e713ed2baae042f305812ff14afd067ab
+  metadata.gz: f4244bbc93b9c53b55e486d52420653ce8ffd5ee5e8d642b91e25aafc439ea2c48b5622c84167083b93c05ef424f5ea2b5964b7a4696665e92ffab68d13a43b9
+  data.tar.gz: 58e28a76335c29b19f57c8b68e9c1c6bd00136b753025b230bcabf4a041a872e0efe8a8ebf233a15c7249de018662f4de9c240b27c10701989faeb71231bc866

data/.rubocop.yml

@@ -1,13 +1,32 @@
 AllCops:
   TargetRubyVersion: 3.0
+  NewCops: enable
 
 Style/StringLiterals:
   Enabled: true
-  EnforcedStyle: double_quotes
+  EnforcedStyle: single_quotes
 
 Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
 
+Style/Documentation:
+  Enabled: false
+
+Style/GlobalVars:
+  Enabled: false
+
 Layout/LineLength:
   Max: 120
+
+Metrics/BlockLength:
+  AllowedMethods:
+    - render
+Metrics/MethodLength:
+  Max: 15
+  AllowedMethods:
+  - render
+
+require:
+  - rubocop-rake
+  - rubocop-rspec

data/CHANGELOG.md

@@ -1,12 +1,21 @@
 ## [Planned]
 
-- Server-side hot reloading
-- Dynamic page metadata
-- Client-side component rendering
-- Client-side routing
-- Websockets support
+- WebSockets support
+- Production mode
+
+## [0.2.0] - 18 February 2024
+
+- Server-side hot reloading (browser reloads on changes)
+- Dynamic page metadata (title and description)
+- Less noisy logging (silence logging for Rack::Static)
+- Client-side component rendering (sans SVG support)
+- Client-side routing / navigation
 - Client-side hot reloading
 
+## [0.1.1] - 17 February 2024
+
+- Server-side reloading (server requests reflect changes)
+
 ## [0.1.0] - 15 February 2024
 
 - `porous server` to run apps

data/README.md

@@ -1,11 +1,19 @@
-# Porous
+# 🧽 Porous
 
-Porous is a web engine that uses isomorphic Ruby components to build a Progressive Web App. Its use is analogous to a web framework, but the approach is entirely different.
+Porous is a web engine that uses isomorphic Ruby components to build a Progressive Web App. Its use is analogous to a web framework, but the approach is entirely different. You write only
 
 This project is a work-in-progress and is not yet even in the Proof of Concept phase. However, if you are interested in a full-stack, everything included solution, that only requires you to use one language (that is arguably easy and enjoyable to write) then feel free to follow this project.
 
 The closest thing to this I could find was [Volt](https://github.com/voltrb/volt) or [Silica](https://github.com/youchan/silica), neither of which are active or match the overall development flow I'm looking for.
 
+## Current Features
+
+- 🙅 No bundled runtime (only code unique to your app needs to be in your repository)
+- 🖥️ Server-side rendering (server responds with the entire initial page populated for SEO)
+- 💻 Client-side rendering (application bundle is served and interactions and subsequent pages are rendered client-side)
+- 🌄 Serves static files (from `static` folder)
+- 🔥 Hot reloading (via HTTP polling and browser refresh)
+
 ## Design
 
 Applications are composed of `Page`s which are in turn composed of `Component`s. Data is persisted as `Entity`s in configurable store options (memory, disk, database). Client-server communication occurs as `Event`s over WebSockets.
@@ -16,7 +24,7 @@ A page is conceptually similar to what would be rendered when visiting a specifi
 
 ### Components
 
-A component is any composable unit of code responsible for rendering markup, potentially based on some state. This is somewhat equivalent to Web Components, in that it can also have some behaviour attached. But it can also simply be based to remove code duplication. Essentially any markup that has behaviour attached or would otherwise create code duplication should probably be in a Components.
+A component is any composable unit of code responsible for rendering markup, potentially based on some state. This is somewhat equivalent to Web Components, in that it can also have some behaviour attached. But it can also simply be used to remove code duplication. Essentially any markup that has behaviour attached or would otherwise create code duplication should probably be in Components.
 
 ### Entities
 
@@ -36,11 +44,13 @@ Porous is not a framework. You don't build an application with it as a dependenc
 
 Porous is still pre-alpha and so is not ready for usage yet, but the general idea is that you would define your application's entities, pages, components and events in Ruby scripts structured in a specific way. Then you would simply run `porous` while pointing it to that folder and it will spin up a Rack-compatible web server for you to use.
 
-To start a new Porous project simply `gem install porous` using whichever Ruby environment you want to use (Ruby 3.0 minimum). Then change to that directory and run:
+> ⚠️ Expect any and all APIs to change radically until version 1.0! Hence why it won't be documented or properly tested until things settle to a more stable state.
+
+To start a new Porous project simply `gem install porous` using whichever Ruby environment you want to use (Ruby 3.0+). Then change to that directory and run:
 
     $ porous server
 
-By default Porous will run at `loclahost:9292`. Now you can edit `pages/home.rb` or add more pages. Finally restart the server and refresh the page. Hot-reloading will be coming later.
+By default Porous will run at `localhost:9292`. Now you can edit `pages/home.rb` or add more pages. Files you modify will be hot-reloaded so you can simply open the page in your browser and edit the file. Hot-reloading will be improved once WebSockets support is implemented.
 
 ### Running examples
 
@@ -66,4 +76,4 @@ Everyone interacting in the Porous project's codebases, issue trackers, chat roo
 
 ## Acknowledgements
 
-The work done by Michał Kalbarczyk ([fazibear](https://github.com/fazibear)) on [Inesita](https://github.com/inesita-rb/inesita) and his [VirtualDOM wrapper](https://github.com/fazibear/opal-virtual-dom) which served as the starting point for my implementation of Porous.
+I'd like to thank Michał Kalbarczyk ([fazibear](https://github.com/fazibear)) for his work done on [Inesita](https://github.com/inesita-rb/inesita) and his [VirtualDOM wrapper](https://github.com/fazibear/opal-virtual-dom) which served as the starting point for my implementation of Porous. While my final approach may deviate significantly from theirs, having code to review and a workable starting point was invaluable.

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/exe/porous

@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require 'porous/cli'
 
 Porous::CLI.start ARGV

data/lib/porous/application.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Porous
+  class Application
+    include Porous::Component
+
+    # rubocop:disable Metrics/AbcSize
+    def render
+      html do
+        head do
+          meta charset: 'UTF-8'
+          meta name: 'viewport', content: 'width=device-width, initial-scale=1.0'
+
+          if props[:title]
+            title do
+              text props[:title]
+            end
+          end
+          meta name: 'description', content: props[:description] if props[:description]
+
+          script src: '/static/dist/application.js'
+          script src: '/static/dist/reload.js'
+          script src: 'https://cdn.tailwindcss.com'
+        end
+
+        body class: 'bg-gray-50 dark:bg-gray-900' do
+          component Porous::Router, props: { path: props[:path], query: props[:query] }
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize
+  end
+end

data/lib/porous/cli/build.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   class CLI < Thor
     include Thor::Actions
@@ -6,17 +8,51 @@ module Porous
 
     namespace :build
 
-    desc 'build', 'Build static assets'
+    def self.exit_on_failure?
+      true
+    end
 
+    desc 'build', 'Build static assets'
     def build
-      empty_directory 'static/dist', force: options[:force]
+      empty_directory 'static/dist', verbose: false, force: options[:force]
       transpile
+      live_reload
     end
 
+    # rubocop:disable Metrics/BlockLength
     no_commands do
       def transpile
-        # TODO: Use Opal::Builder to generate pages, components and entities into static/dist
+        components = Dir.glob(File.join('{components,pages}', '**', '*.rb')).map do |relative_path|
+          "require '#{relative_path}'"
+        end
+        build_string = "require 'porous'; #{components.join ";"}".gsub '.rb', ''
+        builder = Opal::Builder.new
+        builder.build_str build_string, '(inline)'
+        File.binwrite "#{Dir.pwd}/static/dist/application.js", builder.to_s
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def live_reload
+        timestamp = Time.now.to_i.to_s
+        File.write "#{Dir.pwd}/static/dist/timestamp", timestamp
+        builder = Opal::Builder.new
+        script = <<-BROWSER
+          $document.ready do
+            every 0.1 do
+              Browser::HTTP.get('/static/dist/timestamp').then do |response|
+                return unless response.success?
+                timestamp = response.text.to_i
+                TIMESTAMP ||= timestamp
+                $document.location.reload if TIMESTAMP < timestamp
+              end
+            end
+          end
+        BROWSER
+        builder.build_str script, '(inline)'
+        File.binwrite "#{Dir.pwd}/static/dist/reload.js", builder.to_s
       end
+      # rubocop:enable Metrics/MethodLength
     end
+    # rubocop:enable Metrics/BlockLength
   end
 end

data/lib/porous/cli/new.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   class CLI < Thor
     include Thor::Actions

data/lib/porous/cli/server.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   class CLI < Thor
     check_unknown_options!
@@ -14,13 +16,32 @@ module Porous
     method_option :host,
                   aliases: :h,
                   type: :string,
-                  default: '127.0.0.1',
+                  default: 'localhost',
                   desc: 'The host address Porous will bind to'
 
+    MONITORING = %w[components pages].freeze
+
     def server
-      Rackup::Server.start environment: 'development', builder: <<-BUILDER
-        run Porous::Server.new
-      BUILDER
+      MONITORING.each { |path| FileUtils.mkdir_p path }
+      build
+      start_live_reload
+      Rackup::Server.start environment: 'none', app: Porous::Server.new
+    end
+
+    no_commands do
+      def start_live_reload
+        opts = { only: /\.rb$/, relative: true }
+        @listener = Listen.to(*MONITORING, opts) do |modified, added, _removed|
+          # Load for server
+          (modified + added).each do |file|
+            load File.expand_path("#{Dir.pwd}/#{file}")
+          end
+          # Rebuild for browser
+          Thread.new { build }
+        end
+        @listener.start
+        at_exit { @listener.stop }
+      end
     end
   end
 end

data/lib/porous/cli/template/pages/home.rb

@@ -1,15 +1,20 @@
+# frozen_string_literal: true
+
 class Home
   include Porous::Page
   include Porous::Component
 
   def route = '/'
+  def page_title = 'Porous Web | Home'
+  def page_description = 'Landing page generated by Porous'
 
+  # rubocop:disable Metrics, Layout/LineLength
   def render
     div class: 'container p-8 mx-auto lg:h-full xl:px-0 flex flex-wrap' do
       div class: 'flex items-center w-full lg:w-1/2' do
         div class: 'max-w-2xl mb-8' do
           h1 class: 'text-4xl font-bold leading-snug tracking-tight text-gray-800 lg:text-4xl lg:leading-tight xl:text-6xl xl:leading-tight dark:text-white' do
-            span class: "bg-gradient-to-br from-pink-500 to-violet-500 bg-clip-text text-transparent box-decoration-clone" do
+            span class: 'bg-gradient-to-br from-pink-500 to-violet-500 bg-clip-text text-transparent box-decoration-clone' do
               text 'Welcome to Porous!'
             end
           end
@@ -19,10 +24,10 @@ class Home
 
           div class: 'flex flex-col items-start space-y-3 sm:space-x-4 sm:space-y-0 sm:items-center sm:flex-row' do
             a href: 'https://github.com/exastencil/porous', target: '_blank', rel: 'noopener',
-              class: "group relative inline-flex h-12 items-center justify-center overflow-hidden rounded-md bg-indigo-600 px-6 font-medium text-neutral-200 transition hover:scale-110" do
-              span 'Get Started'
-              div class: "absolute inset-0 flex h-full w-full justify-center [transform:skew(-12deg)_translateX(-100%)] group-hover:duration-1000 group-hover:[transform:skew(-12deg)_translateX(100%)]" do
-                div class: "relative h-full w-8 bg-white/20"
+              class: 'group relative inline-flex h-12 items-center justify-center overflow-hidden rounded-md bg-indigo-600 px-6 font-medium text-neutral-200 transition hover:scale-110' do
+              span 'Get Started 🧽'
+              div class: 'absolute inset-0 flex h-full w-full justify-center [transform:skew(-12deg)_translateX(-100%)] group-hover:duration-1000 group-hover:[transform:skew(-12deg)_translateX(100%)]' do
+                div class: 'relative h-full w-8 bg-white/20'
               end
             end
             a href: 'https://github.com/exastencil/porous', target: '_blank', rel: 'noopener',
@@ -45,4 +50,5 @@ class Home
       end
     end
   end
+  # rubocop:enable Metrics, Layout/LineLength
 end

data/lib/porous/cli.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'thor'
 
 require 'porous'

data/lib/porous/component/class_methods.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   module Component
     module ClassMethods

data/lib/porous/component/render.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   module Component
     module Render
@@ -5,8 +7,7 @@ module Porous
         raise Error, "Implement #render in #{self.class} component"
       end
 
-      def before_render
-      end
+      def before_render; end
 
       def render_virtual_dom
         before_render

data/lib/porous/component/virtual.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   module Component
     module Virtual

data/lib/porous/component.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   module Component
     include VirtualDOM::DOM
@@ -15,7 +17,6 @@ module Porous
       init_injections
       inject
       @virtual_dom = render_virtual_dom
-      self
     end
 
     def props

data/lib/porous/injection.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   module Injection
     def init; end
@@ -20,16 +22,14 @@ module Porous
 
     def init_injections
       @injections ||= {}
-      self.class.injections.each do |name, clazz|
-        if clazz.included_modules.include?(Porous::Injection)
-          @injections[name] = clazz
-                              .new
-                              .with_root_component(@root_component)
-        else
-          raise Error, "Invalid #{clazz} class, should mixin Porous::Injection"
+      self.class.injections.each do |name, klass|
+        unless klass.included_modules.include?(Porous::Injection)
+          raise Error, "Invalid #{klass} class, should mixin Porous::Injection"
         end
+
+        @injections[name] = klass.new.with_root_component(@root_component)
       end
-      @injections.each do |key, instance|
+      @injections.each_value do |instance|
         instance.inject
         instance.init
       end

data/lib/porous/logger.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Porous
+  class Logger < Rack::CommonLogger
+    def log(env, status, response_headers, began_at)
+      super unless env['PATH_INFO'].start_with? 'static'
+    end
+  end
+end

data/lib/porous/page.rb

@@ -1,11 +1,16 @@
+# frozen_string_literal: true
+
 module Porous
   module Page
     # Define the route according to the Router::Routes rules
     def route!
       path = route
-      @routes ||= Routes.new.tap do |routes|
+      @route ||= Routes.new.tap do |routes|
         routes.route path, to: self.class
       end
     end
+
+    def page_title = 'Porous Web'
+    def page_description = nil
   end
 end

data/lib/porous/router.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Porous
-  module Router
+  class Router
     include Porous::Component
 
     attr_reader :params
@@ -23,6 +25,10 @@ module Porous
       parse_url_params
     end
 
+    def routes
+      @routes.routes
+    end
+
     def self.included(base)
       base.extend(Porous::Component::ClassMethods)
     end
@@ -34,7 +40,8 @@ module Porous
 
         return @route = route
       end
-      raise Error, "Can't find route for url"
+      available_routes = @routes.routes.map { |r| "  #{r[:path]} => #{r[:component]}" }.join
+      raise InvalidRouteError, "Unknown route for: #{path}\n\nAvailable routes:\n\n#{available_routes}"
     end
 
     def find_component(route)
@@ -50,9 +57,9 @@ module Porous
     def call_on_enter_callback(route)
       return unless route[:on_enter]
 
-      if route[:on_enter].respond_to?(:call)
-        route[:on_enter].call
-      end
+      return unless route[:on_enter].respond_to?(:call)
+
+      route[:on_enter].call
     end
 
     def go_to(path)
@@ -66,14 +73,16 @@ module Porous
 
     def parse_url_params
       @params = component_url_params
-      query[1..-1].split('&').each do |param|
+      return if query.empty?
+
+      query[1..].split('&').each do |param|
         key, value = param.split('=')
         @params[key] = value
-      end unless query.empty?
+      end
     end
 
     def component_url_params
-      Hash[@route[:params].zip(path.match(@route[:regex])[1..-1])]
+      @route[:params].zip(path.match(@route[:regex])[1..]).to_h
     end
 
     def url_for(name, params = nil)
@@ -91,11 +100,11 @@ module Porous
     end
 
     def query
-      @props ? @props[:query] : '' # Browser.query
+      @props ? @props[:query] : ''
     end
 
     def path
-      @props ? @props[:path] : '/' # @props[:path] # Browser.path
+      @props ? @props[:path] : '/'
     end
 
     def current_url?(name)
@@ -104,9 +113,9 @@ module Porous
 
     def url_with_params(route, params)
       path = route[:path]
-      params.each do |key, value|
-        path = path.gsub(":#{key}", "#{value}")
-      end if params
+      params&.each do |key, value|
+        path = path.gsub(":#{key}", value.to_s)
+      end
       path
     end
   end

data/lib/porous/routes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Porous
   class Routes
     attr_reader :routes
@@ -7,8 +9,9 @@ module Porous
       @routes = []
     end
 
+    # rubocop:disable Metrics/AbcSize
     def route(*params, &block)
-      path = params.first.gsub(/^\//, '')
+      path = params.first.gsub(%r{^/}, '')
       path = @parent ? "#{@parent}/#{path}" : "/#{path}"
 
       add_subroutes(path, &block) if block_given?
@@ -19,12 +22,15 @@ module Porous
         add_route(params.last[:as], path, params.last[:to], params.last[:props], params.last[:on_enter])
       end
     end
+    # rubocop:enable Metrics/AbcSize
 
     def validate_component(component)
       raise Error, 'Component not exists' unless component
 
+      return if component.include?(Porous::Component)
+
       raise Error,
-            "Invalid #{component} class, should mixin Porous::Component" unless component.include?(Porous::Component)
+            "Invalid #{component} class, should mixin Porous::Component"
     end
 
     def add_redirect(path, redirect_to)
@@ -51,6 +57,7 @@ module Porous
       @routes += subroutes.routes
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def build_params_and_regex(path)
       regex = ['^']
       params = []
@@ -62,10 +69,10 @@ module Porous
         regex << '\/'
         case part[0]
         when ':'
-          params << part[1..-1]
+          params << part[1..]
           regex << '([^\/]+)'
         when '*'
-          params << part[1..-1]
+          params << part[1..]
           regex << '(.*)'
           break
         else
@@ -78,6 +85,7 @@ module Porous
         params: params
       }
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def combine(other)
       @routes += other.routes