funicular 0.0.1 → 0.2.0

data/mrblib/funicular.rb

@@ -0,0 +1,245 @@
+# The 'js' gem (picoruby-wasm) provides JavaScript interop and is only
+# available in wasm builds. During test builds, picoruby-wasm is excluded
+# from dependencies (see mrbgem.rake), so `require 'js'` raises LoadError.
+#
+# Additionally, gem init order is not guaranteed to be stable. A dummy
+# `require` in picoruby-mruby/mrblib/require.rb exists to suppress
+# LoadError during picogem_init, but if picoruby-require initializes
+# before this gem, the real `require` (which raises LoadError) will
+# already be active. Rescuing LoadError here makes the code robust
+# regardless of init order.
+begin
+  require 'js'
+rescue LoadError
+  # not available outside wasm environment
+end
+
+module Funicular
+  # 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
+
+  def self.env=(environment)
+    case environment
+    when EnvironmentInquirer
+      @env = environment
+    when nil
+      @env = nil
+    else
+      @env = EnvironmentInquirer.new(environment)
+    end
+    # @type ivar @env: EnvironmentInquirer?
+    @env
+  end
+
+  @router = nil
+
+  def self.router
+    @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
+
+    check_completion = -> {
+      if schemas_loaded >= total_schemas
+        puts "[Funicular] All schemas loaded (#{schemas_loaded}/#{total_schemas})"
+        block.call if block
+      end
+    }
+
+    models.each do |model_class, schema_name|
+      HTTP.get("/api/schema/#{schema_name}") do |response|
+        if response.error?
+          puts "[Schema] Failed to load #{schema_name} schema: #{response.error_message}"
+        else
+          model_class.load_schema(response.data)
+          puts "[Schema] #{schema_name} model initialized"
+          schemas_loaded += 1
+          check_completion.call
+        end
+      end
+    end
+  end
+
+  # Start Funicular application
+  # Usage:
+  #   Funicular.start(MyComponent, container: 'app')
+  #   Funicular.start(MyComponent, container: 'app', props: { name: 'John' })
+  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
+
+    # Initialize debug module in development mode
+    Funicular::Debug.expose_to_global if Funicular.env.development?
+
+    container_element = if container.is_a?(String)
+      JS.document.getElementById(container)
+    else
+      container
+    end
+
+    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(hydrate: hydrate)
+      return router
+    end
+
+    # Otherwise, mount single component (backward compatible)
+    if component_class
+      instance = component_class.new(props)
+      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
+
+    raise "Either component_class or block must be provided"
+  rescue => e
+    puts "Exception in Funicular.start: #{e.message}"
+    puts e.backtrace
+    raise e
+  end
+
+  # Form builder configuration
+  class << self
+    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: "funicular-error",
+        field_error_class: "funicular-field-error"
+      }
+      config = @form_builder_config
+      # @type var config: Hash[Symbol, String]
+      yield config if block_given?
+    end
+  end
+
+  # Initialize default form configuration
+  configure_forms
+
+  # Debug highlighter configuration
+  class << self
+    attr_accessor :debug_color
+
+    def configure_debug
+      @debug_color = 'green'
+      yield self if block_given?
+    end
+  end
+
+  # Initialize default debug configuration
+  configure_debug
+
+  # 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
+  end
+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

@@ -0,0 +1,183 @@
+module Funicular
+  module HTTP
+    CACHE_DB_NAME = 'funicular_http_cache'.freeze
+    CACHE_STORE = 'responses'.freeze
+
+    @cache = nil
+
+    class Response
+      attr_reader :data, :status, :ok
+
+      def initialize(status, data)
+        @status = status
+        @ok = @status >= 200 && @status < 300
+        @data = data
+      end
+
+      def error?
+        return true unless @ok
+        return false unless @data.is_a?(Hash)
+        @data["error"] || @data["errors"]
+      end
+
+      def error_message
+        return nil unless @data.is_a?(Hash)
+        @data["error"] || (@data["errors"].is_a?(Array) ? @data["errors"].join(", ") : @data["errors"])
+      end
+    end
+
+    # 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
+
+    # 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, cache: nil, &block)
+      warn_unsupported_cache("patch") if cache
+      request("PATCH", url, body, &block)
+    end
+
+    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, cache: nil, &block)
+      warn_unsupported_cache("put") if cache
+      request("PUT", url, body, &block)
+    end
+
+    # Get CSRF token from meta tag
+    # Note: Don't cache the token - Rails may rotate it after each request
+    def self.csrf_token
+      meta = JS.document.querySelector('meta[name="csrf-token"]')
+      if meta
+        token_obj = meta.getAttribute('content')
+        token_obj ? token_obj.to_s : nil
+      else
+        nil
+      end
+    end
+
+    class << self
+      private
+
+      def warn_unsupported_cache(verb)
+        puts "[Funicular::HTTP] cache: option is GET-only; ignoring on #{verb.upcase}"
+      end
+
+      def now_seconds
+        # JavaScript Date.now() returns ms since epoch
+        ms = JS.global[:Date].now # steep:ignore
+        (ms.to_i / 1000)
+      end
+
+      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
+
+      def serve_from_cache(entry, &block)
+        status = entry["status"].to_i
+        data = entry["data"]
+        block.call(Response.new(status, data)) if block
+      end
+
+      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
+end