funicular 0.1.0 → 0.2.0

data/mrblib/html_serializer.rb

@@ -0,0 +1,121 @@
+module Funicular
+  module VDOM
+    # HTMLSerializer is a string-emitting counterpart of VDOM::Renderer.
+    # While Renderer builds a live DOM tree via JS (createElement/appendChild),
+    # HTMLSerializer walks the same VNode tree and produces an HTML string.
+    #
+    # It is pure Ruby with no JS dependency, so it runs under both mruby
+    # (in the browser, if ever needed) and CRuby (on the Rails server for SSR).
+    #
+    # Event handler props (on*) are intentionally skipped: they are Procs that
+    # cannot be serialized. They are re-bound on the client during hydration.
+    class HTMLSerializer
+      # Elements that have no closing tag and no children.
+      VOID_ELEMENTS = %w[
+        area base br col embed hr img input link meta param source track wbr
+      ]
+
+      # Props that must never be emitted as HTML attributes.
+      SKIP_PROPS = %i[ref key children_block]
+
+      def self.serialize(vnode)
+        new.render(vnode)
+      end
+
+      def render(vnode)
+        case vnode&.type
+        when :element
+          # @type var vnode: Funicular::VDOM::Element
+          render_element(vnode)
+        when :text
+          # @type var vnode: Funicular::VDOM::Text
+          render_text(vnode)
+        when :component
+          # @type var vnode: Funicular::VDOM::Component
+          render_component(vnode)
+        when nil
+          ""
+        else
+          raise "Unknown vnode type: #{vnode&.type}"
+        end
+      end
+
+      private
+
+      def render_element(element)
+        tag = element.tag
+        attrs = serialize_props(element.props)
+
+        if VOID_ELEMENTS.include?(tag)
+          "<#{tag}#{attrs}>"
+        else
+          "<#{tag}#{attrs}>#{render_children(element.children)}</#{tag}>"
+        end
+      end
+
+      def render_children(children)
+        parts = [] #: Array[String]
+        children.each do |child|
+          if child.is_a?(VNode)
+            parts << render(child)
+          elsif child.is_a?(String)
+            parts << escape_html(child)
+          elsif child.is_a?(Array)
+            parts << render_children(child)
+          elsif !child.nil?
+            parts << escape_html(child.to_s)
+          end
+        end
+        parts.join
+      end
+
+      def render_text(text)
+        escape_html(text.content)
+      end
+
+      def render_component(component_vnode)
+        instance = component_vnode.component_class.new(component_vnode.props)
+        component_vnode.instance = instance
+        render(instance.build_vdom)
+      end
+
+      def serialize_props(props)
+        parts = [] #: Array[String]
+        props.each do |key, value|
+          key_str = key.to_s
+          next if SKIP_PROPS.include?(key)
+          # Event handlers are bound on the client, never serialized.
+          next if key_str.start_with?("on")
+
+          if URL_ATTRIBUTES.include?(key_str) &&
+             value.to_s.strip.downcase.start_with?("javascript:")
+            # Prevent XSS via javascript: URIs (mirrors Renderer#render_element).
+            next
+          end
+
+          if BOOLEAN_ATTRIBUTES.include?(key_str)
+            # Boolean attributes are absent when false/nil, otherwise present.
+            next if value.nil? || value.to_s == "false"
+            parts << " #{key_str}=\"#{key_str}\""
+          else
+            parts << " #{key_str}=\"#{escape_attr(value.to_s)}\""
+          end
+        end
+        parts.join
+      end
+
+      # Minimal HTML escaping that works the same under mruby and CRuby.
+      # Avoids any dependency on CGI/ERB::Util.
+      def escape_html(str)
+        str.to_s
+           .gsub("&", "&amp;")
+           .gsub("<", "&lt;")
+           .gsub(">", "&gt;")
+      end
+
+      def escape_attr(str)
+        escape_html(str).gsub('"', "&quot;")
+      end
+    end
+  end
+end

data/mrblib/http.rb

@@ -1,5 +1,10 @@
 module Funicular
   module HTTP
+    CACHE_DB_NAME = 'funicular_http_cache'.freeze
+    CACHE_STORE = 'responses'.freeze
+
+    @cache = nil
+
     class Response
       attr_reader :data, :status, :ok
 
@@ -21,23 +26,73 @@ module Funicular
       end
     end
 
-    def self.get(url, &block)
-      request("GET", url, nil, &block)
+    # Open (or reuse) the response cache store. Idempotent and safe to call
+    # multiple times. Falls back to the in-memory backing if browser
+    # IndexedDB is unavailable.
+    def self.cache_init!
+      cache = @cache
+      return cache if cache
+      @cache = IndexedDB::KVS.open(CACHE_DB_NAME, store: CACHE_STORE)
+    end
+
+    # Drop a single cached entry by URL key. No-op if the cache is not
+    # initialized.
+    def self.cache_purge(url)
+      cache = @cache
+      return nil unless cache
+      cache.delete(url)
+      nil
+    end
+
+    # Drop every cached entry. No-op if the cache is not initialized.
+    def self.cache_clear
+      cache = @cache
+      return nil unless cache
+      cache.clear
+      nil
+    end
+
+    # Internal: read the cache for *url*. Returns the parsed entry hash or
+    # nil. Lazily initializes the cache on first use so callers can pass
+    # `cache:` without booting the SPA shell first.
+    def self.cache_lookup(url)
+      cache_init! unless @cache
+      cache = @cache
+      return nil unless cache
+      cache[url]
     end
 
-    def self.post(url, body = nil, &block)
+    # Internal: write *entry* (a Hash with status/data/cached_at) to the
+    # cache. Awaits one extra Promise so the next request reliably hits.
+    def self.cache_write(url, entry)
+      cache_init! unless @cache
+      cache = @cache
+      return nil unless cache
+      cache[url] = entry
+      nil
+    end
+
+    def self.get(url, cache: nil, &block)
+      request("GET", url, nil, cache: cache, &block)
+    end
+
+    def self.post(url, body = nil, cache: nil, &block)
+      warn_unsupported_cache("post") if cache
       request("POST", url, body, &block)
     end
 
-    def self.patch(url, body = nil, &block)
+    def self.patch(url, body = nil, cache: nil, &block)
+      warn_unsupported_cache("patch") if cache
       request("PATCH", url, body, &block)
     end
 
-    def self.delete(url, &block)
+    def self.delete(url, cache: nil, &block)
+      warn_unsupported_cache("delete") if cache
       request("DELETE", url, nil, &block)
     end
 
-    def self.put(url, body = nil, &block)
+    def self.put(url, body = nil, cache: nil, &block)
+      warn_unsupported_cache("put") if cache
       request("PUT", url, body, &block)
     end
 
@@ -46,43 +101,82 @@ module Funicular
     def self.csrf_token
       meta = JS.document.querySelector('meta[name="csrf-token"]')
       if meta
-        # Use getAttribute method (direct method call on JS::Object)
         token_obj = meta.getAttribute('content')
-        # Convert JS::Object to Ruby string
         token_obj ? token_obj.to_s : nil
       else
         nil
       end
     end
 
-    private
+    class << self
+      private
 
-    def self.request(method, url, body, &block)
-      # @type var options: Hash[Symbol, String | Hash[String, String]]
-      options = { method: method, credentials: "include" }
-
-      headers = {} #: Hash[String, String]
+      def warn_unsupported_cache(verb)
+        puts "[Funicular::HTTP] cache: option is GET-only; ignoring on #{verb.upcase}"
+      end
 
-      if body
-        headers["Content-Type"] = "application/json"
-        options[:body] = JSON.generate(body)
+      def now_seconds
+        # JavaScript Date.now() returns ms since epoch
+        ms = JS.global[:Date].now # steep:ignore
+        (ms.to_i / 1000)
       end
 
-      # Add CSRF token for non-GET requests
-      if method != "GET"
-        token = csrf_token
-        headers["X-CSRF-Token"] = token if token
+      def cache_hit?(entry, ttl)
+        return false unless entry.is_a?(Hash)
+        cached_at = entry["cached_at"]
+        return false unless cached_at.is_a?(Integer)
+        (now_seconds - cached_at) <= ttl
       end
 
-      options[:headers] = headers unless headers.empty?
+      def serve_from_cache(entry, &block)
+        status = entry["status"].to_i
+        data = entry["data"]
+        block.call(Response.new(status, data)) if block
+      end
 
-      JS.global.fetch(url, options) do |response|
-        status = response.status.to_i
-        json_text = response.to_binary
-        data = JSON.parse(json_text)
-        # @type var status: Integer
-        http_response = Response.new(status, data)
-        block.call(http_response) if block
+      def request(method, url, body, cache: nil, &block)
+        if method == "GET" && cache.is_a?(Integer) && cache > 0
+          entry = cache_lookup(url)
+          if cache_hit?(entry, cache)
+            serve_from_cache(entry, &block)
+            return
+          end
+        end
+
+        # @type var options: Hash[Symbol, String | Hash[String, String]]
+        options = { method: method, credentials: "include" }
+
+        headers = {} #: Hash[String, String]
+
+        if body
+          headers["Content-Type"] = "application/json"
+          options[:body] = JSON.generate(body)
+        end
+
+        if method != "GET"
+          token = csrf_token
+          headers["X-CSRF-Token"] = token if token
+        end
+
+        options[:headers] = headers unless headers.empty?
+
+        JS.global.fetch(url, options) do |response|
+          status = response.status.to_i
+          json_text = response.to_binary
+          data = JSON.parse(json_text)
+          # @type var status: Integer
+          http_response = Response.new(status, data)
+
+          if method == "GET" && cache.is_a?(Integer) && cache > 0 && http_response.ok
+            cache_write(url, {
+              "status" => status,
+              "data" => data,
+              "cached_at" => now_seconds
+            })
+          end
+
+          block.call(http_response) if block
+        end
       end
     end
   end

data/mrblib/model.rb

@@ -1,5 +1,7 @@
 module Funicular
   class Model
+    include Validations
+
     attr_reader :id
 
     class << self
@@ -22,6 +24,41 @@ module Funicular
             @changed_attributes[name] = value
           end
         end
+
+        # Validations are inlined per attribute by Funicular::Schema.build.
+        register_schema_validations(name => config["validations"]) if config["validations"]
+      end
+
+      # Backward-compatible: a top-level { attr => rules } block also works.
+      register_schema_validations(schema_data["validations"])
+    end
+
+    # validations: { "attr" => { "presence" => true, "length" => { "maximum" => 30 } } }
+    def self.register_schema_validations(validations)
+      return unless validations.is_a?(Hash)
+      validations.each do |attribute, rules|
+        next unless rules.is_a?(Hash)
+        rules.each do |kind, opts|
+          options = normalize_validation_options(kind, opts)
+          add_schema_validator(attribute, kind, options)
+        end
+      end
+    end
+
+    # Turn JSON-shaped validator options into the Ruby options the client
+    # validators expect (notably rebuilding a Regexp for `format`). Integer
+    # Regexp flags are used so this works the same under CRuby and the client
+    # JS RegExp wrapper.
+    def self.normalize_validation_options(kind, opts)
+      return opts unless opts.is_a?(Hash)
+      if kind.to_s == "format" && opts["with"]
+        flags = opts["flags"].to_s
+        bits = 0
+        bits |= Regexp::IGNORECASE if flags.include?("i")
+        bits |= Regexp::MULTILINE if flags.include?("m")
+        { with: Regexp.new(opts["with"], bits) }
+      else
+        opts
       end
     end
 
@@ -70,6 +107,13 @@ module Funicular
       endpoint = @endpoints["create"]
       return unless endpoint
 
+      # Validate on the client before the request (mirrors ActiveRecord#save).
+      candidate = new(attrs)
+      unless candidate.valid?
+        block.call(nil, candidate.errors) if block
+        return
+      end
+
       HTTP.post(endpoint["path"], attrs) do |response|
         if response.error?
           block.call(nil, response.error_message) if block
@@ -101,6 +145,12 @@ module Funicular
         attrs.each { |k, v| send("#{k}=", v) }
       end
 
+      # Validate on the client before the request (mirrors ActiveRecord#save).
+      unless valid?
+        block.call(false, errors) if block
+        return
+      end
+
       return if @changed_attributes.empty?
 
       json_attrs = @changed_attributes.reject do |name, value|

data/mrblib/patcher.rb

@@ -20,7 +20,9 @@ module Funicular
               result = new_element
             end
           when :props
-            update_props(element, patch[1])
+            # Props patches only make sense for Element nodes (text nodes have
+            # no attributes); narrow before delegating.
+            update_props(element, patch[1]) if element.is_a?(JS::Element)
           when :update_and_rebind
             instance, internal_patches, new_vdom = patch[1], patch[2], patch[3]
             old_dom_element = instance.dom_element
@@ -29,7 +31,7 @@ module Funicular
             new_dom_element = Patcher.new(@doc).apply(old_dom_element, internal_patches)
 
             # Update the instance's reference to its root DOM element if it changed
-            if new_dom_element != old_dom_element
+            if new_dom_element != old_dom_element && new_dom_element.is_a?(JS::Element)
               instance.dom_element = new_dom_element
             end
 
@@ -37,11 +39,13 @@ module Funicular
             instance.vdom = new_vdom
 
             # Re-collect refs using the new DOM element
-            instance.collect_refs(new_dom_element, new_vdom)
+            if new_dom_element.is_a?(JS::Element)
+              instance.collect_refs(new_dom_element, new_vdom)
 
-            # Re-bind events using the new DOM element
-            instance.cleanup_events
-            instance.bind_events(new_dom_element, new_vdom)
+              # Re-bind events using the new DOM element
+              instance.cleanup_events
+              instance.bind_events(new_dom_element, new_vdom)
+            end
 
             # Call component_updated on the child instance
             instance.component_updated if instance.respond_to?(:component_updated)
@@ -54,6 +58,64 @@ module Funicular
             old_vnode = patch[1]
             unmount_component(old_vnode)
             element.parentElement&.removeChild(element)
+          when :keyed_children
+            # Composite patch produced by Differ.diff_children_with_keys.
+            # Applied in three phases against `element`:
+            #   1. snapshot DOM children, then remove unmatched keyed old
+            #      children (descending old_index so the snapshot indices
+            #      remain valid as removes happen).
+            #   2. apply content updates to kept children in place. The
+            #      lookup is by snapshot[old_index], so updates are stable
+            #      regardless of subsequent insertions.
+            #   3. insert new children at their new_index using
+            #      insertBefore on the live DOM. Processed in ascending
+            #      new_index order so each insertion fixes its own
+            #      position before later inserts run.
+            ops = patch[1]
+            removes = patch[2]
+
+            child_nodes = element[:childNodes]
+            snapshot = child_nodes.is_a?(JS::Object) ? child_nodes.to_a : [] #: Array[untyped]
+
+            # Phase 1: removes (descending old_index)
+            sorted_removes = removes.sort { |a, b| b[0] <=> a[0] }
+            sorted_removes.each do |entry|
+              old_index = entry[0]
+              old_vnode = entry[1]
+              target = snapshot[old_index]
+              next if target.nil?
+              unmount_component(old_vnode)
+              parent_el = target.parentElement
+              parent_el.removeChild(target) if parent_el
+            end
+
+            # Phase 2: updates against the snapshot (no movement)
+            ops.each do |op|
+              next unless op[0] == :keep
+              old_index = op[1]
+              child_patches = op[3]
+              next if child_patches.empty?
+              target = snapshot[old_index]
+              next if target.nil?
+              apply(target, child_patches)
+            end
+
+            # Phase 3: inserts in ascending new_index order
+            ops.each do |op|
+              next unless op[0] == :insert
+              new_index = op[1]
+              new_vnode = op[2]
+              new_node = create_element(new_vnode)
+              next if new_node.nil?
+              live_nodes = element[:childNodes]
+              live_arr = live_nodes.is_a?(JS::Object) ? live_nodes.to_a : [] #: Array[untyped]
+              ref = live_arr[new_index]
+              if ref.nil?
+                element.appendChild(new_node) if element.is_a?(JS::Element)
+              else
+                element.insertBefore(new_node, ref) if element.is_a?(JS::Element)
+              end
+            end
           when Integer
             child_index = patch[0]
             child_patches = patch[1]
@@ -67,7 +129,7 @@ module Funicular
                 case child_patch[0]
                 when :replace
                   new_child_element = create_element(child_patch[1])
-                  element.appendChild(new_child_element)
+                  element.appendChild(new_child_element) if element.is_a?(JS::Element)
                 when :remove
                   # Nothing to remove if child doesn't exist
                 when Integer
@@ -75,7 +137,9 @@ module Funicular
                   # But if it does, recursively process it
                 end
               end
-            else
+            elsif child_element.is_a?(JS::Object)
+              # Recurse into the child node. apply handles both Element and
+              # text Node cases (the latter only meaningfully via :replace).
               apply(child_element, child_patches)
             end
           end
@@ -91,6 +155,8 @@ module Funicular
       end
 
       def update_props(element, props_patch)
+        return unless element.is_a?(JS::Element)
+
         props_patch.each do |key, value|
           key_str = key.to_s
 

data/mrblib/router.rb

@@ -44,8 +44,22 @@ module Funicular
       @default_route = path
     end
 
+    # Resolve a path to [component_class, params] without any DOM/JS work.
+    # Public entry point used by server-side rendering.
+    def match(path)
+      find_route(path)
+    end
+
     # Start listening to popstate
-    def start
+    #
+    # When hydrate is true and the container already holds server-rendered
+    # markup, the initial route hydrates that DOM instead of mounting fresh.
+    def start(hydrate: false)
+      # No browser history on the server.
+      return if Funicular.server?
+
+      @hydrate_initial = hydrate
+
       # Clean up existing listener if any (prevents duplicate registration)
       if @popstate_callback_id
         JS::Object.removeEventListener(@popstate_callback_id)
@@ -57,8 +71,10 @@ module Funicular
         handle_route_change
       end
 
-      # Handle initial route
-      if current_location_path == '/' && @default_route
+      # Handle initial route. Skip the default-route redirect when hydrating
+      # server content: the server already rendered for the current path.
+      hydrating_now = @hydrate_initial && Funicular.first_element_child(@container)
+      if !hydrating_now && current_location_path == '/' && @default_route
         # Use replaceState to not add a new entry to the history
         JS.global.history.replaceState(JS::Bridge.to_js({}), '', @default_route)
       end
@@ -95,6 +111,11 @@ module Funicular
     def handle_route_change
       path = current_location_path
 
+      # Hydration only applies to the very first navigation. Consume the flag
+      # here so an unmatched initial route does not leave it set for later.
+      hydrate_now = @hydrate_initial
+      @hydrate_initial = false
+
       # Find matching route
       component_class, params = find_route(path)
 
@@ -113,6 +134,22 @@ module Funicular
       @current_path = path
       @current_component = component_class.new(params)
       # @type ivar @current_component: Funicular::Component
+
+      server_root = hydrate_now ? Funicular.first_element_child(@container) : nil
+
+      if server_root
+        begin
+          @current_component.seed_state(Funicular.window_state)
+          @current_component.hydrate(server_root)
+          return
+        rescue => e
+          # Server/client disagreed: discard server DOM and render fresh.
+          puts "[Funicular] Hydration failed, falling back to full render: #{e.message}"
+          @container[:innerHTML] = ''
+          @current_component = component_class.new(params)
+        end
+      end
+
       @current_component.mount(@container)
     end