funicular 0.1.0 → 0.2.1

data/mrblib/funicular.rb

@@ -15,12 +15,28 @@ rescue LoadError
 end
 
 module Funicular
-  VERSION = '0.1.0'
+  # Guard against redefinition: when the mrblib runtime is loaded into a
+  # CRuby/Rails process for SSR, lib/funicular/version.rb has already defined
+  # VERSION for the CRuby gem. In the wasm build VERSION is undefined here.
+  VERSION = '0.1.0' unless Funicular.const_defined?(:VERSION)
 
   def self.version
     VERSION
   end
 
+  # True when the runtime is loaded under CRuby on the server (SSR) rather
+  # than running as PicoRuby.wasm in the browser. JS-dependent entry points
+  # become no-ops in this mode. Defaults to false (browser).
+  @server = false
+
+  def self.server?
+    @server
+  end
+
+  def self.server=(value)
+    @server = value ? true : false
+  end
+
   def self.env
     @env ||= EnvironmentInquirer.new(ENV['FUNICULAR_ENV'] || ENV['RAILS_ENV'] || 'development')
   end
@@ -44,12 +60,57 @@ module Funicular
     @router
   end
 
+  # Read the SSR state embedded by the server (funicular_state_tag) as a
+  # Ruby Hash with string keys. Returns {} when absent or on the server.
+  # Goes through JSON.stringify/parse for a reliable JS->Ruby conversion.
+  def self.window_state
+    return {} if server?
+    win = JS.global[:window]
+    # @type var win: JS::Object?
+    return {} unless win
+    raw = win[:__FUNICULAR_STATE__]
+    return {} if raw.nil?
+    json = JS.global[:JSON]
+    # @type var json: untyped
+    json_str = json.stringify(raw)
+    JSON.parse(json_str.to_s)
+  rescue => e
+    puts "[Funicular] Failed to read window state: #{e.message}"
+    {}
+  end
+
+  # True when the server embedded hydration state on the page.
+  def self.has_ssr_state?
+    return false if server?
+    win = JS.global[:window]
+    # @type var win: JS::Object?
+    return false unless win
+    !win[:__FUNICULAR_STATE__].nil?
+  rescue
+    false
+  end
+
+  # The first element child of a container, or nil. Used to find the
+  # server-rendered root for hydration.
+  def self.first_element_child(container_element)
+    child = container_element[:firstElementChild]
+    child.is_a?(JS::Element) ? child : nil
+  end
+
   # Load schemas for models
   # Usage:
   #   Funicular.load_schemas({ User => "user", Session => "session" }) do
   #     Funicular.start(container: 'app') { |router| ... }
   #   end
   def self.load_schemas(models, &block)
+    # On the server there is no fetch and no need for client-side schemas:
+    # SSR injects plain data into component state directly. Just run the
+    # block so route registration (Funicular.start) still happens.
+    if server?
+      block.call if block
+      return
+    end
+
     schemas_loaded = 0
     total_schemas = models.size
 
@@ -78,7 +139,20 @@ module Funicular
   # Usage:
   #   Funicular.start(MyComponent, container: 'app')
   #   Funicular.start(MyComponent, container: 'app', props: { name: 'John' })
-  def self.start(component_class = nil, container: 'app', props: {}, &block)
+  def self.start(component_class = nil, container: 'app', props: {}, hydrate: false, &block)
+    # On the server we only need route registration so SSR can resolve a
+    # path to a component. Skip all DOM/JS work (container lookup, popstate
+    # listener, debug export).
+    if server?
+      if block
+        router = Router.new(nil)
+        @router = router
+        block.call(router)
+        return router
+      end
+      return nil
+    end
+
     # Export debug configuration to JavaScript
     export_debug_config
 
@@ -91,23 +165,33 @@ module Funicular
       container
     end
 
-    unless container_element
+    unless container_element.is_a?(JS::Element)
       raise "Container element not found: #{container}"
     end
 
+    # Hydrate automatically when the server embedded state, unless the caller
+    # explicitly opted out.
+    hydrate = true if hydrate == false && has_ssr_state?
+
     # If block is given, use router mode
     if block
       router = Router.new(container_element)
       @router = router
       block.call(router)
-      router.start
+      router.start(hydrate: hydrate)
       return router
     end
 
     # Otherwise, mount single component (backward compatible)
     if component_class
       instance = component_class.new(props)
-      instance.mount(container_element)
+      server_root = hydrate ? first_element_child(container_element) : nil
+      if server_root
+        instance.seed_state(window_state)
+        instance.hydrate(server_root)
+      else
+        instance.mount(container_element)
+      end
       return instance
     end
 
@@ -123,11 +207,15 @@ module Funicular
     attr_accessor :form_builder_config
 
     def configure_forms
+      # Defaults are semantic class names whose CSS the gem ships and injects
+      # via picoruby_include_tag (see assets/funicular.css).
       @form_builder_config ||= {
-        error_class: "text-red-600 text-sm mt-1",
-        field_error_class: "border-red-500"
+        error_class: "funicular-error",
+        field_error_class: "funicular-field-error"
       }
-      yield @form_builder_config if block_given?
+      config = @form_builder_config
+      # @type var config: Hash[Symbol, String]
+      yield config if block_given?
     end
   end
 
@@ -149,6 +237,7 @@ module Funicular
 
   # Export debug_color to JavaScript global variable
   def self.export_debug_config
+    return if server?
     if JS.global[:window]
       JS.global[:window][:FUNICULAR_DEBUG_COLOR] = @debug_color # steep:ignore
     end

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|