funicular 0.1.0 → 0.2.0

data/lib/funicular/compiler.rb

@@ -11,13 +11,28 @@ module Funicular
     PICORBC_DIR = File.expand_path("vendor/picorbc", __dir__)
     PICORBC_JS  = File.join(PICORBC_DIR, "picorbc.js")
 
-    attr_reader :source_dir, :output_file, :debug_mode, :logger
+    # Ordered list of application source files under app/funicular/.
+    # Order matters: models -> stores -> components -> initializer, so that
+    # later files can reference classes defined earlier. Shared by the .mrb
+    # compiler (client build) and the SSR runtime (server class loading).
+    def self.source_files(source_dir)
+      models_files = Dir.glob(File.join(source_dir, "models", "**", "*.rb")).sort
+      stores_files = Dir.glob(File.join(source_dir, "stores", "**", "*.rb")).sort
+      components_files = Dir.glob(File.join(source_dir, "components", "**", "*.rb")).sort
+      initializer_files = Dir.glob(File.join(source_dir, "*_initializer.rb")).sort +
+                          Dir.glob(File.join(source_dir, "initializer.rb")).sort
+
+      models_files + stores_files + components_files + initializer_files
+    end
 
-    def initialize(source_dir:, output_file:, debug_mode: false, logger: nil)
+    attr_reader :source_dir, :output_file, :debug_mode, :logger, :prepend_source_files
+
+    def initialize(source_dir:, output_file:, debug_mode: false, logger: nil, prepend_source_files: [])
       @source_dir = source_dir
       @output_file = output_file
       @debug_mode = debug_mode
       @logger = logger
+      @prepend_source_files = prepend_source_files.map(&:to_s)
     end
 
     def compile
@@ -66,13 +81,7 @@ module Funicular
     end
 
     def gather_source_files
-      models_files = Dir.glob(File.join(source_dir, "models", "**", "*.rb")).sort
-      components_files = Dir.glob(File.join(source_dir, "components", "**", "*.rb")).sort
-      initializer_files = Dir.glob(File.join(source_dir, "*_initializer.rb")).sort +
-                          Dir.glob(File.join(source_dir, "initializer.rb")).sort
-
-      # Order: models -> components -> initializer
-      all_files = models_files + components_files + initializer_files
+      all_files = self.class.source_files(source_dir)
 
       if all_files.empty?
         raise "No Ruby files found in #{source_dir}"
@@ -84,15 +93,13 @@ module Funicular
         f.puts "ENV['FUNICULAR_ENV'] = '#{Rails.env}'"
       end
 
-      @source_files = all_files
+      @source_files = prepend_source_files + all_files
       @env_file = env_file
     end
 
     def log(message)
       if logger
         logger.info(message)
-        # Also output to stdout so logs are visible in terminal during development
-        puts message if debug_mode
       else
         puts message
       end
@@ -102,14 +109,15 @@ module Funicular
       output_dir = File.dirname(output_file)
       FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
 
-      all_files = @source_files + [@env_file]
+      all_files = @source_files.dup
+      all_files << @env_file if @env_file
       argv = [node_command, PICORBC_JS]
       argv << "-g" if debug_mode
       argv += ["-o", output_file.to_s]
       argv += all_files.map(&:to_s)
 
-      log "Compiling Funicular application..."
-      log "  Source: #{source_dir}"
+      log "Compiling Funicular Ruby..."
+      log "  Source: #{source_dir}" if source_dir
       log "  Input files:"
       all_files.each do |file|
         log "    - #{file}"

data/lib/funicular/helpers/picoruby_helper.rb

@@ -11,6 +11,14 @@ module Funicular
         local_dist:  "/picoruby/dist/init.iife.js"
       }.freeze
 
+      # Minimal CSS the gem ships for class names it emits itself (e.g.
+      # FormBuilder error states). Read once; see assets/funicular.css.
+      BASE_CSS_PATH = File.expand_path("../assets/funicular.css", __dir__)
+
+      def self.base_css
+        @base_css ||= File.read(BASE_CSS_PATH)
+      end
+
       # Renders a <script> tag that bootstraps PicoRuby.wasm.
       #
       # The source is determined by Funicular.configuration based on the
@@ -20,11 +28,65 @@ module Funicular
       #   <%= picoruby_include_tag source: :cdn %>
       #   <%= picoruby_include_tag source: :local_dist, defer: true %>
       #
-      # Any extra options are passed straight through as HTML attributes.
-      def picoruby_include_tag(source: nil, **options)
+      # Also emits Funicular's small base stylesheet (so gem-emitted class names
+      # such as form error states render without host-CSS setup); pass
+      # base_styles: false to skip it. Any extra options become HTML attributes
+      # on the <script> tag.
+      def picoruby_include_tag(source: nil, base_styles: true, **options)
         resolved_source = source ? source.to_sym : Funicular.configuration.source_for(Rails.env)
         src = picoruby_src_for(resolved_source)
-        tag.script("", src: src, **options)
+        script = tag.script("", src: src, **options)
+        return script unless base_styles
+
+        style = tag.style(PicorubyHelper.base_css.html_safe, "data-funicular-base": "")
+        safe_join([style, script])
+      end
+
+      # Renders the SSR #app container with the server-rendered HTML inside.
+      #
+      #   <%= funicular_app_container(@ssr[:html]) %>
+      #
+      # On the client, Funicular hydrates this element instead of rebuilding
+      # it. Pass an empty string (the default) to fall back to plain CSR.
+      def funicular_app_container(html = "", id: "app", **options)
+        content_tag(:div, raw(html.to_s), { id: id }.merge(options))
+      end
+
+      # Emits the initial state for client hydration as a global JS variable.
+      #
+      #   <%= funicular_state_tag(@ssr[:state]) %>
+      #   # => <script>window.__FUNICULAR_STATE__ = {...};</script>
+      #
+      # The JSON is escaped so it cannot break out of the <script> element.
+      def funicular_state_tag(state = {})
+        json = JSON.generate(state || {})
+        # Escape characters that could break out of the <script> element or
+        # confuse the HTML parser, using JS unicode escapes that remain valid
+        # JSON/JS string content.
+        safe = json.gsub("<", "\\u003c").gsub(">", "\\u003e").gsub("&", "\\u0026")
+        raw("<script>window.__FUNICULAR_STATE__ = #{safe};</script>")
+      end
+
+      # Renders registered Funicular plugin browser assets.
+      #
+      # Plugins are gems in the Gemfile :funicular group. Their Ruby sources
+      # are compiled into app.mrb before the application sources; this helper
+      # emits browser assets such as CSS.
+      def funicular_plugin_include_tags
+        registry = Funicular::Plugin::Registry.new(Rails.root)
+        tags = registry.asset_entries.map do |entry|
+          logical_path = entry.fetch("logical_path")
+          if entry["type"] == "css"
+            stylesheet_link_tag(logical_path, "data-turbo-track": "reload")
+          else
+            tag.script("", type: "application/x-mrb", src: asset_path(logical_path), data: { funicular_plugin: true })
+          end
+        end
+        safe_join(tags)
+      rescue Funicular::Plugin::Error => e
+        raise e if Rails.env.production?
+
+        tag.comment("Funicular plugin assets skipped: #{e.message}")
       end
 
       private

data/lib/funicular/middleware.rb

@@ -49,13 +49,17 @@ module Funicular
 
       begin
         Rails.logger.info "Funicular: Source files changed, recompiling..."
-        compiler = Compiler.new(
-          source_dir: @source_dir,
-          output_file: @output_file,
-          debug_mode: true,
-          logger: Rails.logger
-        )
-        compiler.compile
+        plugin_registry = build_plugins
+        if Dir.exist?(@source_dir)
+          compiler = Compiler.new(
+            source_dir: @source_dir,
+            output_file: @output_file,
+            debug_mode: true,
+            logger: Rails.logger,
+            prepend_source_files: plugin_registry.local_source_files
+          )
+          compiler.compile
+        end
         self.class.last_mtime = current_mtime
         invalidate_asset_pipeline_cache
       rescue => e
@@ -90,9 +94,30 @@ module Funicular
 
     def latest_source_mtime
       source_files = Dir.glob(File.join(@source_dir, "**", "*.rb"))
-      return Time.at(0) if source_files.empty?
+      plugin_files = plugin_source_files
+      all_files = source_files + plugin_files
+      return Time.at(0) if all_files.empty?
 
-      source_files.map { |f| File.mtime(f) }.max
+      all_files.map { |f| File.mtime(f) }.max
+    end
+
+    def build_plugins
+      registry = Plugin::Registry.new(Rails.root)
+      return registry if registry.specs.empty?
+
+      registry.validate!
+      registry.sync_assets
+      registry
+    rescue Plugin::Error => e
+      Rails.logger.error "Funicular plugin compilation failed: #{e.message}"
+      Plugin::Registry.new(Rails.root)
+    end
+
+    def plugin_source_files
+      registry = Plugin::Registry.new(Rails.root)
+      registry.local_source_files + registry.specs.flat_map { |spec| spec.css_paths.map(&:to_s) }
+    rescue Plugin::Error
+      []
     end
   end
 end

data/lib/funicular/plugin.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Funicular
+  module Plugin
+    BUILD_DIR = "app/assets/builds/funicular/plugins"
+    GROUP = :funicular
+
+    class Error < StandardError; end
+
+    class Project
+      attr_reader :root
+
+      def initialize(root)
+        @root = Pathname(root).expand_path
+      end
+
+      def assets_dir
+        root.join("assets")
+      end
+
+      def source_dir
+        root.join("lib")
+      end
+
+      def source_files
+        nested = Dir.glob(source_dir.join("*", "**", "*.rb").to_s).sort
+        top_level = Dir.glob(source_dir.join("*.rb").to_s).sort
+        nested + top_level
+      end
+
+      def css_paths
+        Dir.glob(assets_dir.join("*.css").to_s).sort.map { |path| Pathname(path) }
+      end
+    end
+
+    class Spec
+      attr_reader :bundler_spec
+
+      def initialize(bundler_spec)
+        @bundler_spec = bundler_spec
+      end
+
+      def root
+        @root ||= Pathname(bundler_spec.full_gem_path).expand_path
+      end
+
+      def project
+        @project ||= Project.new(root)
+      end
+
+      def name
+        bundler_spec.name
+      end
+
+      def css_paths
+        project.css_paths
+      end
+
+      def validate!
+        raise Error, "Missing Funicular plugin gem: #{root}" unless root.exist?
+        raise Error, "No Ruby source files found in #{project.source_dir}" if project.source_files.empty?
+
+        self
+      end
+    end
+
+    class Registry
+      attr_reader :rails_root
+
+      def initialize(rails_root)
+        @rails_root = Pathname(rails_root).expand_path
+      end
+
+      def specs
+        @specs ||= funicular_specs.map { |spec| Spec.new(spec) }
+      end
+
+      def sync_assets
+        build_root = rails_root.join(BUILD_DIR)
+        FileUtils.mkdir_p(build_root)
+
+        validated_specs.each do |spec|
+          target_dir = build_root.join(Plugin.safe_name(spec.name))
+          FileUtils.rm_rf(target_dir)
+          FileUtils.mkdir_p(target_dir)
+          spec.css_paths.each do |path|
+            FileUtils.cp(path, target_dir.join(File.basename(path))) if path.exist?
+          end
+        end
+      end
+
+      def local_source_files
+        validated_specs.flat_map { |spec| spec.project.source_files }
+      end
+
+      def asset_entries
+        validated_specs.flat_map do |spec|
+          safe_name = Plugin.safe_name(spec.name)
+          css = spec.css_paths.map { |path| File.basename(path) }
+          css.map { |file| { "type" => "css", "logical_path" => "funicular/plugins/#{safe_name}/#{file}" } }
+        end
+      end
+
+      def validate!
+        specs.each(&:validate!)
+      end
+
+      private
+
+      def funicular_specs
+        names = bundler_dependencies
+                .select { |dependency| dependency.groups.include?(GROUP) }
+                .map(&:name)
+        return [] if names.empty?
+
+        bundler_specs.select { |spec| names.include?(spec.name) }
+      end
+
+      def bundler_dependencies
+        require "bundler"
+
+        Bundler.definition.dependencies
+      rescue LoadError
+        raise Error, "Bundler is required to resolve Funicular plugin gems"
+      end
+
+      def bundler_specs
+        require "bundler"
+
+        Bundler.load.specs
+      rescue LoadError
+        raise Error, "Bundler is required to resolve Funicular plugin gems"
+      end
+
+      def validated_specs
+        specs.map(&:validate!)
+      end
+    end
+
+    def self.safe_name(name)
+      name.to_s.split("/").last.gsub(/[^a-zA-Z0-9]+/, "_").gsub(/\A_+|_+\z/, "").downcase
+    end
+  end
+end

data/lib/funicular/schema.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Funicular
+  # Derives client-side validation rules from an ActiveModel/ActiveRecord
+  # class so they can be embedded in the JSON returned by a schema controller
+  # and reused by Funicular::Model on the client.
+  #
+  # Security model: validations are derived ONLY for the attribute names the
+  # caller passes (the schema's existing attribute allowlist), so nothing
+  # outside the already-public schema is ever introspected. A per-attribute
+  # `except` denylist suppresses specific validator kinds.
+  module Schema
+    # Validator kinds that have a client-side counterpart in
+    # Funicular::Model::Validations. Others (notably :uniqueness, which needs
+    # the database, and any custom validator) are skipped.
+    SUPPORTED_KINDS = %i[
+      presence absence length format numericality
+      inclusion exclusion acceptance confirmation
+    ].freeze
+
+    # Build a full schema hash, merging derived validations inline into each
+    # attribute entry (the shape Funicular::Model.load_schema consumes):
+    #
+    #   Funicular::Schema.build(User,
+    #     attributes: { "display_name" => { type: "string", readonly: false } },
+    #     endpoints:  { "update" => { method: "PATCH", path: "/users/:id" } },
+    #     except:     { username: [:format] })
+    #   # => { attributes: { "display_name" => { type:, readonly:,
+    #   #        validations: { "presence" => true, "length" => {...} } } },
+    #   #      endpoints: {...} }
+    #
+    # Only the attributes you declare are introspected (allowlist); `except`
+    # drops specific kinds per attribute (denylist).
+    def self.build(model_class, attributes:, endpoints: {}, except: {})
+      merged = {}
+      attributes.each do |name, definition|
+        rules = rules_for(model_class, name, except_kinds(except, name))
+        merged[name] = rules.empty? ? definition : definition.merge(validations: rules)
+      end
+      { attributes: merged, endpoints: endpoints }
+    end
+
+    # Returns { "attr" => { "presence" => true, "length" => { "maximum" => 30 } } }
+    # for the given attribute names only. Useful when emitting validations as a
+    # separate block rather than inline (see #build for the inline form).
+    def self.validations_for(model_class, attribute_names, except: {})
+      result = {}
+      attribute_names.each do |name|
+        rules = rules_for(model_class, name, except_kinds(except, name))
+        result[name.to_s] = rules unless rules.empty?
+      end
+      result
+    end
+
+    # Derive the { kind => options } rules for a single attribute.
+    def self.rules_for(model_class, name, skip_kinds)
+      attr = name.to_sym
+      rules = {}
+      model_class.validators_on(attr).each do |validator|
+        kind = validator.kind
+        next unless SUPPORTED_KINDS.include?(kind)
+        next if skip_kinds.include?(kind)
+        # Conditional/context validators can't be evaluated on the client.
+        next if conditional?(validator.options)
+
+        serialized = serialize(kind, validator.options)
+        next if serialized.nil?
+        rules[kind.to_s] = serialized
+      end
+      rules
+    end
+
+    def self.except_kinds(except, name)
+      Array(except[name.to_sym] || except[name.to_s]).map(&:to_sym)
+    end
+
+    def self.conditional?(options)
+      options.key?(:if) || options.key?(:unless) || options.key?(:on)
+    end
+
+    def self.serialize(kind, options)
+      case kind
+      when :presence, :absence, :acceptance, :confirmation
+        true
+      when :length
+        serialize_length(options)
+      when :numericality
+        serialize_numericality(options)
+      when :inclusion, :exclusion
+        serialize_set(options)
+      when :format
+        RegexpTranslator.translate(options[:with])
+      end
+    end
+
+    def self.serialize_length(options)
+      opts = {}
+      [:minimum, :maximum, :is].each do |k|
+        opts[k.to_s] = options[k] if options[k].is_a?(Integer)
+      end
+      if (range = options[:in] || options[:within]).is_a?(Range)
+        opts["minimum"] = range.min
+        opts["maximum"] = range.max
+      end
+      opts.empty? ? nil : opts
+    end
+
+    def self.serialize_numericality(options)
+      opts = {}
+      opts["only_integer"] = true if options[:only_integer]
+      [:greater_than, :greater_than_or_equal_to, :equal_to,
+       :less_than, :less_than_or_equal_to, :other_than].each do |k|
+        opts[k.to_s] = options[k] if options[k].is_a?(Numeric)
+      end
+      opts.empty? ? true : opts
+    end
+
+    def self.serialize_set(options)
+      list = options[:in] || options[:within]
+      list = list.to_a if list.is_a?(Range)
+      return nil unless list.is_a?(Array)
+      return nil unless list.all? { |v| json_scalar?(v) }
+      { "in" => list }
+    end
+
+    def self.json_scalar?(value)
+      value.is_a?(String) || value.is_a?(Numeric) ||
+        value == true || value == false || value.nil?
+    end
+
+    # Best-effort translation of a Ruby Regexp into a JS-RegExp-compatible
+    # source. The client runs Regexp as a JS RegExp wrapper, so Ruby-only
+    # constructs are either translated (\A, \z, \Z anchors) or, when they have
+    # no safe JS equivalent, the validator is skipped with a warning.
+    module RegexpTranslator
+      # Substrings that JS RegExp cannot accept; presence means "skip".
+      INCOMPATIBLE = ['[[:', '\\h', '\\H', '\\G', '(?>'].freeze
+
+      def self.translate(regexp)
+        return nil unless regexp.is_a?(Regexp)
+
+        if (regexp.options & Regexp::EXTENDED) != 0
+          return skip("extended (x) mode")
+        end
+
+        source = regexp.source
+        if INCOMPATIBLE.any? { |token| source.include?(token) }
+          return skip("uses a construct unsupported by JS RegExp")
+        end
+
+        js_source = source.gsub('\\A', '^').gsub('\\z', '$').gsub('\\Z', '$')
+
+        flags = +''
+        flags << 'i' if (regexp.options & Regexp::IGNORECASE) != 0
+        flags << 'm' if (regexp.options & Regexp::MULTILINE) != 0
+
+        { 'with' => js_source, 'flags' => flags }
+      end
+
+      def self.skip(reason)
+        warn "[Funicular::Schema] skipping a format validator: #{reason}; " \
+             "declare it directly in the Funicular::Model if needed"
+        nil
+      end
+    end
+  end
+end

data/lib/funicular/ssr/runtime.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../compiler"
+
+module Funicular
+  module SSR
+    # Loads the PicoRuby (mrblib) framework runtime and the application's
+    # component classes into the CRuby process so the server can build VDOM
+    # and serialize it to HTML.
+    #
+    # The mrblib runtime is plain Ruby; the only JS access happens inside
+    # methods that SSR never calls (mount, patcher, fetch, history, ...).
+    # `Funicular.server = true` makes the few JS-touching entry points
+    # (Funicular.start, Router#start, FileUpload.mount, Debug) no-ops.
+    module Runtime
+      MRBLIB_DIR = File.expand_path("../../../mrblib", __dir__)
+
+      # Load order is by dependency at *class-body* evaluation time. Most
+      # files reference JS / other classes only inside methods, so only a
+      # few real dependencies exist (vdom before html_serializer; styles and
+      # vdom before component; component before error_boundary).
+      LOAD_ORDER = %w[
+        environment_inquirer
+        vdom
+        html_serializer
+        differ
+        patcher
+        styles
+        debug
+        component
+        error_boundary
+        router
+        0_validations
+        1_validators
+        model
+        store
+        store_singleton
+        store_collection
+        form_builder
+        http
+        cable
+        file_upload
+        funicular
+      ].freeze
+
+      class << self
+        # Load the framework runtime once. Idempotent.
+        def load_framework!
+          return if @framework_loaded
+
+          LOAD_ORDER.each do |name|
+            require File.join(MRBLIB_DIR, "#{name}.rb")
+          end
+          Funicular.server = true
+          @framework_loaded = true
+        end
+
+        # Load the application's component/model/store/initializer files in the
+        # canonical order. Running the initializer registers routes into
+        # Funicular.router (server-safe: Funicular.start skips all DOM work).
+        #
+        # Funicular model files are loaded so that the constants they define
+        # (e.g. Channel, Session) are available when the initializer evaluates
+        # `load_schemas({ Channel => "channel", ... })`. If a Funicular model
+        # shares a name with a same-named ActiveRecord model that Rails has
+        # already auto-loaded, Ruby raises TypeError (superclass mismatch).
+        # In that case we rescue and continue: the AR constant is already defined
+        # and is all that load_schemas needs (it ignores the hash on the server).
+        #
+        # Loaded once per process. Restart the server to pick up changes.
+        def boot!(source_dir)
+          load_framework!
+          return if @app_loaded
+
+          files = Funicular::Compiler.source_files(source_dir.to_s)
+          files.each do |file|
+            begin
+              Kernel.load(file)
+            rescue TypeError => e
+              # Funicular model name conflicts with an already-loaded AR model.
+              # The constant is already defined; safe to skip.
+              warn "[Funicular SSR] Skipped #{File.basename(file)}: #{e.message}"
+            end
+          end
+          @app_loaded = true
+        end
+
+        # Test/escape hatch: forget loaded application state so a different
+        # app (or a reload) can be booted. Does not unload the framework.
+        def reset_app!
+          @app_loaded = false
+        end
+
+        def framework_loaded?
+          !!@framework_loaded
+        end
+      end
+    end
+  end
+end

data/lib/funicular/ssr.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "ssr/runtime"
+
+module Funicular
+  # Server-side rendering entry point.
+  #
+  # Usage (typically from a Rails controller / view helper):
+  #
+  #   result = Funicular::SSR.render(
+  #     path: request.path,
+  #     state: { channels: Channel.all.as_json }
+  #   )
+  #   # result[:html]  -> HTML string for the #app container
+  #   # result[:state] -> data to embed as window.__FUNICULAR_STATE__
+  #
+  module SSR
+    # Render the component mapped to `path` to an HTML string, seeding it with
+    # server-provided `state`. Returns a hash:
+    #   { html:, state:, component: }
+    # When no route matches, html is "" so the caller can fall back to plain
+    # client-side rendering (empty #app container).
+    def self.render(path:, state: {}, props: {}, source_dir: nil)
+      Runtime.boot!(source_dir || default_source_dir)
+
+      router = Funicular.router
+      raise "Funicular router is not configured; check app/funicular/initializer.rb" unless router
+
+      component_class, params = router.match(path)
+      return { html: "", state: {}, component: nil } unless component_class
+
+      instance = component_class.new(symbolize_keys(params).merge(props))
+      instance.seed_state(state)
+      html = Funicular::VDOM::HTMLSerializer.serialize(instance.build_vdom)
+
+      { html: html, state: state, component: component_class }
+    end
+
+    def self.default_source_dir
+      raise "source_dir is required outside Rails" unless defined?(Rails) && Rails.respond_to?(:root)
+      Rails.root.join("app", "funicular")
+    end
+
+    def self.symbolize_keys(hash)
+      return {} unless hash
+      out = {}
+      hash.each { |k, v| out[k.to_sym] = v }
+      out
+    end
+  end
+end