funicular 0.1.0 → 0.2.0

data/lib/generators/funicular/chat/templates/funicular_chat_controller.rb.tt

@@ -0,0 +1,4 @@
+class FunicularChatController < ApplicationController
+  def show
+  end
+end

data/lib/generators/funicular/chat/templates/funicular_chat_message.rb.tt

@@ -0,0 +1,13 @@
+class FunicularChatMessage < ApplicationRecord
+  validates :name, presence: true, length: { maximum: 40 }
+  validates :body, presence: true, length: { maximum: 500 }
+
+  def as_json(*)
+    {
+      id: id,
+      name: name,
+      body: body,
+      created_at: created_at.iso8601
+    }
+  end
+end

data/lib/generators/funicular/chat/templates/funicular_chat_messages_controller.rb.tt

@@ -0,0 +1,23 @@
+class FunicularChatMessagesController < ApplicationController
+  def index
+    messages = FunicularChatMessage.order(:created_at).last(50)
+    render json: messages
+  end
+
+  def create
+    message = FunicularChatMessage.new(message_params)
+
+    if message.save
+      ActionCable.server.broadcast("funicular_chat", message.as_json)
+      render json: message, status: :created
+    else
+      render json: { errors: message.errors.full_messages }, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def message_params
+    params.require(:message).permit(:name, :body)
+  end
+end

data/lib/generators/funicular/chat/templates/initializer.rb.tt

@@ -0,0 +1,4 @@
+Funicular.start(container: "app") do |router|
+  router.get("/funicular_chat", to: FunicularChatComponent, as: "funicular_chat")
+  router.set_default("/funicular_chat")
+end

data/lib/generators/funicular/chat/templates/show.html.erb.tt

@@ -0,0 +1,6 @@
+<%% content_for :head do %>
+  <%%= stylesheet_link_tag "funicular_chat", "data-turbo-track": "reload" %>
+<%% end %>
+
+<%%= funicular_app_container %>
+<script type="application/x-mrb" src="<%%= asset_path("app.mrb") %>"></script>

data/lib/tasks/funicular.rake

@@ -4,6 +4,7 @@ namespace :funicular do
   desc "Compile Funicular Ruby files to .mrb format"
   task compile: :environment do
     require "funicular/compiler"
+    require "funicular/plugin"
 
     source_dir = Rails.root.join("app", "funicular")
     output_file = Rails.root.join("app", "assets", "builds", "app.mrb")
@@ -15,13 +16,20 @@ namespace :funicular do
     end
 
     begin
+      plugin_registry = Funicular::Plugin::Registry.new(Rails.root)
+      plugin_registry.validate!
+      plugin_registry.sync_assets
       compiler = Funicular::Compiler.new(
         source_dir: source_dir,
         output_file: output_file,
-        debug_mode: debug_mode
+        debug_mode: debug_mode,
+        prepend_source_files: plugin_registry.local_source_files
       )
       compiler.compile
-    rescue Funicular::Compiler::PicorbcNotFoundError => e
+    rescue Funicular::Plugin::Error => e
+      puts "ERROR: #{e.message}"
+      exit 1
+    rescue Funicular::Compiler::PicorbcMissingError => e
       puts "ERROR: #{e.message}"
       exit 1
     rescue => e
@@ -46,8 +54,8 @@ namespace :funicular do
     end
   end
 
-  desc "Install Funicular debug assets and PicoRuby.wasm artifacts into a Rails app"
-  task install: ["install:debug_assets", "install:wasm"] do
+  desc "Install Funicular debug assets, PicoRuby.wasm artifacts, and test support into a Rails app"
+  task install: ["install:debug_assets", "install:wasm", "install:test"] do
     puts ""
     puts "All Funicular assets installed."
     puts ""
@@ -64,6 +72,10 @@ namespace :funicular do
     puts '         <%= javascript_include_tag "funicular_debug", "data-turbo-track": "reload" %>'
     puts '         <%= stylesheet_link_tag "funicular_debug", "data-turbo-track": "reload" %>'
     puts '       <% end %>'
+    puts ""
+    puts "  4. Run `npm install` if package.json was created or updated."
+    puts "     Client-side Funicular tests live under test/funicular/client/**/*_picotest.rb"
+    puts "     and run through `bin/rails test`."
   end
 
   namespace :install do
@@ -126,6 +138,77 @@ namespace :funicular do
         puts "Installed PicoRuby #{variant} build to #{dst}"
       end
     end
+
+
+    desc "Install Funicular client test support"
+    task :test do
+      require "fileutils"
+      require "json"
+
+      test_dir = Rails.root.join("test")
+      funicular_test_dir = test_dir.join("funicular")
+      client_test_dir = funicular_test_dir.join("client")
+      FileUtils.mkdir_p(client_test_dir)
+
+      test_helper = test_dir.join("test_helper.rb")
+      unless File.exist?(test_helper)
+        File.write(test_helper, <<~TEST_HELPER)
+          ENV["RAILS_ENV"] ||= "test"
+
+          require_relative "../config/environment"
+          require "rails/test_help"
+        TEST_HELPER
+        puts "Installed #{test_helper}"
+      end
+
+      application_test = funicular_test_dir.join("application_test.rb")
+      unless File.exist?(application_test)
+        File.write(application_test, <<~APPLICATION_TEST)
+          require_relative "../test_helper"
+          require "funicular/testing"
+
+          class FunicularApplicationTest < ActiveSupport::TestCase
+            test "client-side Funicular tests" do
+              result = Funicular::Testing.run!(timeout_ms: 10_000)
+              Funicular::Testing.assert_picotests(self, result)
+            end
+          end
+        APPLICATION_TEST
+        puts "Installed #{application_test}"
+      end
+
+      keep_file = client_test_dir.join(".keep")
+      FileUtils.touch(keep_file) unless File.exist?(keep_file)
+
+      package_json = Rails.root.join("package.json")
+      package = if File.exist?(package_json)
+                  JSON.parse(File.read(package_json))
+                else
+                  { "private" => true }
+                end
+      package["devDependencies"] ||= {}
+      package["devDependencies"]["jsdom"] ||= "^26.1.0"
+      File.write(package_json, JSON.pretty_generate(package) + "\n")
+      puts "Updated #{package_json}"
+
+      gitignore = Rails.root.join(".gitignore")
+      if File.exist?(gitignore)
+        content = File.read(gitignore)
+        unless content.lines.any? { |line| line.chomp == "/node_modules" }
+          File.open(gitignore, "a") do |f|
+            f.puts
+            f.puts "# Ignore Node dependencies."
+            f.puts "/node_modules"
+          end
+          puts "Updated #{gitignore}"
+        end
+      end
+
+      puts "Installed Funicular test support:"
+      puts "  - #{application_test}"
+      puts "  - #{client_test_dir}"
+      puts "  - jsdom dev dependency in #{package_json}"
+    end
   end
 end
 

data/minitest/fixtures/funicular_app/components/greeting_component.rb

@@ -0,0 +1,16 @@
+class GreetingComponent < Funicular::Component
+  def initialize_state
+    { title: "Default Title", items: [] }
+  end
+
+  def render
+    div(class: "greeting") do
+      h1 { state.title }
+      ul do
+        state.items.each do |item|
+          li(key: item["id"]) { item["name"] }
+        end
+      end
+    end
+  end
+end

data/minitest/fixtures/funicular_app/initializer.rb

@@ -0,0 +1,5 @@
+Funicular.start(container: "app") do |router|
+  router.get("/greet", to: GreetingComponent, as: "greet")
+  router.get("/greet/:id", to: GreetingComponent, as: "greet_item")
+  router.set_default("/greet")
+end

data/minitest/hydration_test.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Exercises the hydration mismatch guard under CRuby. The structural decision
+# (`hydration_match?`) and the dev warning (`warn_hydration_mismatch`) are pure
+# Ruby, so they are tested here without a DOM. The actual recovery swap done by
+# `full_render_fallback` (Renderer + replaceChild) is JS-only and is covered by
+# the browser/manual verification step, not here.
+#
+# A plain Hash stands in for the server DOM node: hydration_match? only reads
+# `dom_element[:tagName]`, which a Hash answers the same way a JS::Element does.
+class HydrationMatchTest < Minitest::Test
+  def setup
+    Funicular::SSR::Runtime.load_framework!
+    Funicular.env = "development"
+  end
+
+  def teardown
+    Funicular.env = "development"
+  end
+
+  # Builds the probe at runtime (Class.new) so the suite matches its picotest
+  # twin and never references Funicular::Component at load time. render is never
+  # invoked here (we feed vnodes directly); it only satisfies the abstract API.
+  def probe
+    klass = Class.new(Funicular::Component) do
+      def render
+        div { "x" }
+      end
+
+      def match?(vnode, dom)
+        hydration_match?(vnode, dom)
+      end
+
+      def warn_for(vnode, dom)
+        warn_hydration_mismatch(vnode, dom)
+      end
+    end
+    klass.new
+  end
+
+  def el(tag)
+    Funicular::VDOM::Element.new(tag, {}, ["x"])
+  end
+
+  # --- hydration_match? (the decision that drives the fallback) ---------
+
+  def test_matches_when_root_tags_agree
+    assert_equal true, probe.match?(el("div"), { tagName: "DIV" })
+  end
+
+  def test_detects_mismatched_root_tag
+    assert_equal false, probe.match?(el("div"), { tagName: "SPAN" })
+  end
+
+  def test_tag_comparison_is_case_insensitive
+    assert_equal true, probe.match?(el("h1"), { tagName: "H1" })
+  end
+
+  def test_non_element_vnode_is_treated_as_match
+    assert_equal true, probe.match?(Funicular::VDOM::Text.new("hi"), { tagName: "DIV" })
+  end
+
+  def test_missing_dom_tag_name_is_treated_as_match
+    assert_equal true, probe.match?(el("div"), {})
+  end
+
+  # --- warn_hydration_mismatch (dev-only diagnostics) -------------------
+
+  def test_warning_fires_in_development
+    out, _err = capture_io do
+      probe.warn_for(el("div"), { tagName: "SPAN" })
+    end
+    assert_includes out, "Hydration mismatch"
+    assert_includes out, "<div>"
+    assert_includes out, "<span>"
+  end
+
+  def test_warning_is_silent_in_production
+    Funicular.env = "production"
+    out, _err = capture_io do
+      probe.warn_for(el("div"), { tagName: "SPAN" })
+    end
+    assert_equal "", out
+  end
+end

data/minitest/plugin_test.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+require_relative "test_helper"
+
+class PluginTest < Minitest::Test
+  def test_registry_resolves_funicular_group_gems_and_syncs_assets
+    Dir.mktmpdir do |dir|
+      rails_root = File.join(dir, "app")
+      gem_root = File.join(dir, "funicular-datepicker")
+      FileUtils.mkdir_p(File.join(gem_root, "lib", "components"))
+      FileUtils.mkdir_p(File.join(gem_root, "assets"))
+      File.write(File.join(gem_root, "lib", "date_picker.rb"), "# plugin entry\n")
+      File.write(File.join(gem_root, "lib", "components", "date_picker_component.rb"), "# component\n")
+      File.write(File.join(gem_root, "assets", "date_picker.css"), "/* css */\n")
+
+      spec = Gem::Specification.new do |s|
+        s.name = "funicular-datepicker"
+        s.version = "0.1.0"
+        s.full_gem_path = gem_root
+      end
+
+      registry = Funicular::Plugin::Registry.new(rails_root)
+      registry.define_singleton_method(:funicular_specs) { [spec] }
+      registry.sync_assets
+
+      synced_css = File.join(
+        rails_root,
+        "app",
+        "assets",
+        "builds",
+        "funicular",
+        "plugins",
+        "funicular_datepicker",
+        "date_picker.css"
+      )
+      assert File.exist?(synced_css)
+
+      entries = registry.asset_entries
+      assert_equal 1, entries.size
+      assert_equal "css", entries.first["type"]
+      assert_equal "funicular/plugins/funicular_datepicker/date_picker.css", entries.first["logical_path"]
+      assert_equal [
+        File.join(gem_root, "lib", "components", "date_picker_component.rb"),
+        File.join(gem_root, "lib", "date_picker.rb")
+      ], registry.local_source_files
+    end
+  end
+end

data/minitest/schema_test.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "active_model"
+
+# Exercises Funicular::Schema.validations_for: deriving client validation rules
+# from an ActiveModel class, honoring the attribute allowlist and the per-kind
+# denylist, skipping unsupported/conditional validators, and translating the
+# `format` regexp for the JS RegExp engine.
+class SchemaDerivationTest < Minitest::Test
+  class Account
+    include ActiveModel::Validations
+    attr_accessor :name, :email, :age, :role, :code, :score
+
+    # Custom validator (kind :even) stands in for any non-standard validator
+    # the client has no counterpart for; it must be skipped during derivation.
+    class EvenValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value); end
+    end
+
+    validates :name, presence: true, length: { maximum: 30 }
+    validates :email, format: { with: /\A[^@\s]+@[^@\s]+\z/ }
+    validates :age, numericality: { only_integer: true, greater_than: 0 }
+    validates :role, inclusion: { in: %w[admin user] }
+    validates :code, presence: true, if: -> { false }      # conditional -> skipped
+    validates :score, even: true                           # unsupported kind -> skipped
+  end
+
+  def derive(attrs, except: {})
+    Funicular::Schema.validations_for(Account, attrs, except: except)
+  end
+
+  def test_presence_and_length
+    result = derive(["name"])
+    assert_equal({ "presence" => true, "length" => { "maximum" => 30 } }, result["name"])
+  end
+
+  def test_only_listed_attributes_are_introspected
+    result = derive(["name"])
+    assert_equal ["name"], result.keys
+  end
+
+  def test_numericality_and_inclusion
+    result = derive(["age", "role"])
+    assert_equal({ "only_integer" => true, "greater_than" => 0 }, result["age"]["numericality"])
+    assert_equal({ "in" => %w[admin user] }, result["role"]["inclusion"])
+  end
+
+  def test_format_translates_ruby_anchors
+    result = derive(["email"])
+    fmt = result["email"]["format"]
+    # \A and \z become ^ and $ for JS RegExp.
+    assert_equal "^[^@\\s]+@[^@\\s]+$", fmt["with"]
+  end
+
+  def test_denylist_suppresses_a_kind
+    result = derive(["name"], except: { name: [:length] })
+    assert_equal({ "presence" => true }, result["name"])
+  end
+
+  def test_conditional_validator_is_skipped
+    result = derive(["code"])
+    assert_nil result["code"]
+  end
+
+  def test_unsupported_kind_is_skipped
+    result = derive(["score"])
+    assert_nil result["score"]
+  end
+
+  def test_build_inlines_validations_into_attributes
+    schema = Funicular::Schema.build(
+      Account,
+      attributes: {
+        "display_name" => { type: "string", readonly: false },
+        "name" => { type: "string", readonly: false }
+      },
+      endpoints: { "update" => { method: "PATCH", path: "/x/:id" } },
+      except: { name: [:length] }
+    )
+    # Attribute with no validators is untouched.
+    assert_equal({ type: "string", readonly: false }, schema[:attributes]["display_name"])
+    # Validators are merged inline; denylist drops :length here.
+    assert_equal(
+      { type: "string", readonly: false, validations: { "presence" => true } },
+      schema[:attributes]["name"]
+    )
+    assert_equal({ "update" => { method: "PATCH", path: "/x/:id" } }, schema[:endpoints])
+  end
+
+  def test_extended_regexp_is_skipped
+    klass = Class.new do
+      include ActiveModel::Validations
+      def self.name; "Extended"; end
+      attr_accessor :token
+      validates :token, format: { with: /
+        \A \d+ \z   # an integer, written with x-mode whitespace
+      /x }
+    end
+    result = nil
+    capture_io do  # silence the skip warning
+      result = Funicular::Schema.validations_for(klass, ["token"])
+    end
+    assert_nil result["token"]
+  end
+end

data/minitest/ssr_test.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Exercises the SSR half of Funicular under CRuby: the shared HTMLSerializer
+# and the full path of loading the mrblib runtime + a fixture app, then
+# rendering a routed component to HTML with injected state.
+class SSRTest < Minitest::Test
+  APP_DIR = File.expand_path("fixtures/funicular_app", __dir__)
+
+  def setup
+    Funicular::SSR::Runtime.load_framework!
+  end
+
+  # --- HTMLSerializer (pure Ruby) ---------------------------------------
+
+  def serialize(vnode)
+    Funicular::VDOM::HTMLSerializer.serialize(vnode)
+  end
+
+  def el(tag, props = {}, children = [])
+    Funicular::VDOM::Element.new(tag, props, children)
+  end
+
+  def test_serializes_element_with_attributes
+    assert_equal '<div class="box" id="x"></div>',
+                 serialize(el("div", { class: "box", id: "x" }))
+  end
+
+  def test_escapes_text_content
+    assert_equal "<p>a &amp; b &lt;c&gt;</p>",
+                 serialize(el("p", {}, ["a & b <c>"]))
+  end
+
+  def test_escapes_attribute_values
+    assert_equal '<div title="&quot;hi&quot;"></div>',
+                 serialize(el("div", { title: '"hi"' }))
+  end
+
+  def test_skips_event_handlers
+    html = serialize(el("button", { onclick: :handle }, ["Go"]))
+    assert_equal "<button>Go</button>", html
+  end
+
+  def test_boolean_attribute_present_and_absent
+    assert_equal '<input disabled="disabled">',
+                 serialize(el("input", { disabled: true }))
+    assert_equal "<input>",
+                 serialize(el("input", { disabled: false }))
+  end
+
+  def test_void_element_self_closes
+    assert_equal "<br>", serialize(el("br"))
+    assert_equal '<img src="/a.png">', serialize(el("img", { src: "/a.png" }))
+  end
+
+  def test_blocks_javascript_uri
+    assert_equal "<a>x</a>",
+                 serialize(el("a", { href: "javascript:alert(1)" }, ["x"]))
+  end
+
+  # --- Full SSR render (runtime + fixture app) --------------------------
+
+  def test_render_injects_server_state
+    result = Funicular::SSR.render(
+      path: "/greet",
+      state: { title: "Channels", items: [{ "id" => 1, "name" => "general" },
+                                          { "id" => 2, "name" => "random" }] },
+      source_dir: APP_DIR
+    )
+
+    assert_includes result[:html], "<h1>Channels</h1>"
+    assert_includes result[:html], "general"
+    assert_includes result[:html], "random"
+    assert_equal GreetingComponent, result[:component]
+  end
+
+  def test_render_uses_initialize_state_without_injection
+    result = Funicular::SSR.render(path: "/greet", source_dir: APP_DIR)
+    assert_includes result[:html], "<h1>Default Title</h1>"
+  end
+
+  def test_render_unmatched_route_returns_empty
+    result = Funicular::SSR.render(path: "/no/such/path", source_dir: APP_DIR)
+    assert_equal "", result[:html]
+    assert_nil result[:component]
+  end
+
+  def test_route_params_become_props
+    # Renders without raising; :id from the path is passed as a prop.
+    result = Funicular::SSR.render(path: "/greet/42", source_dir: APP_DIR)
+    assert_includes result[:html], "greeting"
+  end
+end