funicular 0.0.1 → 0.2.0

data/lib/funicular/assets/funicular_debug.js

@@ -0,0 +1,183 @@
+// Funicular Component Highlighter - Development Mode Only
+// Highlights components with data-component attributes for easier debugging
+
+(function() {
+  'use strict';
+
+  //console.log('[Funicular Debug] Script loaded');
+
+  // Color themes
+  const COLORS = {
+    green: '#00ff00',      // Fluorescent green (default)
+    yellow: '#ffff00',     // Lemon yellow
+    pink: '#ff69b4',       // Hot pink
+    cyan: '#00ffff'        // Cyan/sky blue
+  };
+
+  const DEBUG_CLASS = 'funicular-debug-highlight';
+
+  // Get color dynamically (called each time we need it)
+  const getHighlightColor = () => {
+    const rubyColor = window.FUNICULAR_DEBUG_COLOR;
+
+    //console.log('[Funicular Debug] Ruby color setting:', rubyColor);
+
+    // If nil/undefined/null, disable the feature
+    if (rubyColor === null || rubyColor === undefined || rubyColor === 'nil') {
+      //console.log('[Funicular Debug] Debug highlighting is disabled (color is nil)');
+      return null;
+    }
+
+    return COLORS[rubyColor] || COLORS.green;
+  };
+
+  function initComponentHighlighter() {
+    const highlightColor = getHighlightColor();
+
+    // Exit early if debug highlighting is disabled
+    if (highlightColor === null) {
+      //console.log('[Funicular Debug] Component highlighting disabled');
+      return;
+    }
+
+    //console.log('[Funicular Debug] Initializing component highlighter with color:', highlightColor);
+
+    // Find all elements with data-component attribute
+    const components = document.querySelectorAll('[data-component]');
+    //console.log(`[Funicular Debug] Found ${components.length} components with data-component`);
+
+    components.forEach(element => {
+      highlightElement(element, highlightColor);
+    });
+  }
+
+  // Use MutationObserver to watch for dynamic DOM changes
+  function watchForComponents() {
+    //console.log('[Funicular Debug] Starting MutationObserver...');
+
+    const observer = new MutationObserver((mutations) => {
+      const highlightColor = getHighlightColor();
+      if (highlightColor === null) return;
+
+      mutations.forEach((mutation) => {
+        mutation.addedNodes.forEach((node) => {
+          if (node.nodeType === 1) { // Element node
+            // Check if the added node itself has data-component
+            if (node.hasAttribute && node.hasAttribute('data-component')) {
+              //console.log('[Funicular Debug] New component detected:', node.getAttribute('data-component'));
+              highlightElement(node, highlightColor);
+            }
+            // Check children
+            const children = node.querySelectorAll ? node.querySelectorAll('[data-component]') : [];
+            children.forEach(child => {
+              //console.log('[Funicular Debug] New child component detected:', child.getAttribute('data-component'));
+              highlightElement(child, highlightColor);
+            });
+          }
+        });
+      });
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+  }
+
+  function highlightElement(element, highlightColor) {
+    const componentName = element.getAttribute('data-component');
+
+    let tooltipText = componentName;
+    if (element.id) {
+      tooltipText += ` id=${element.id}`;
+    }
+
+    // Check if indicator already exists
+    const existingIndicator = element.querySelector('.funicular-debug-indicator');
+    if (existingIndicator) {
+      // Update tooltip if it's different
+      if (existingIndicator.getAttribute('data-tooltip') !== tooltipText) {
+        existingIndicator.setAttribute('data-tooltip', tooltipText);
+      }
+      return;
+    }
+
+    // Add debug class
+    if (!element.classList.contains(DEBUG_CLASS)) {
+      element.classList.add(DEBUG_CLASS);
+      // Apply color to the element
+      element.style.setProperty('--funicular-highlight-color', highlightColor);
+    }
+
+    // Create corner triangle indicator
+    const indicator = document.createElement('div');
+    indicator.className = 'funicular-debug-indicator';
+    indicator.setAttribute('data-tooltip', tooltipText);
+    indicator.style.setProperty('--funicular-highlight-color', highlightColor);
+
+    // Position relative wrapper if needed
+    const position = window.getComputedStyle(element).position;
+    if (position === 'static') {
+      element.style.position = 'relative';
+    }
+
+    element.appendChild(indicator);
+
+    // Re-add indicator after a short delay if it gets removed
+    setTimeout(() => {
+      const check = element.querySelector('.funicular-debug-indicator');
+      if (!check) {
+        const newIndicator = document.createElement('div');
+        newIndicator.className = 'funicular-debug-indicator';
+        newIndicator.setAttribute('data-tooltip', tooltipText);
+        newIndicator.style.setProperty('--funicular-highlight-color', highlightColor);
+        element.appendChild(newIndicator);
+      }
+    }, 100);
+  }
+
+  // Initialize on DOM ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+      //console.log('[Funicular Debug] DOMContentLoaded event');
+      initComponentHighlighter();
+      watchForComponents();
+    });
+  } else {
+    //console.log('[Funicular Debug] DOM already loaded');
+    initComponentHighlighter();
+    watchForComponents();
+  }
+
+  // Reinitialize on turbo:load for Turbo/Hotwire apps
+  document.addEventListener('turbo:load', () => {
+    //console.log('[Funicular Debug] turbo:load event');
+    initComponentHighlighter();
+  });
+
+  // Reinitialize on turbolinks:load for older Turbolinks
+  document.addEventListener('turbolinks:load', () => {
+    //console.log('[Funicular Debug] turbolinks:load event');
+    initComponentHighlighter();
+  });
+
+  // Expose a manual trigger function for console debugging
+  window.funicularDebug = {
+    init: initComponentHighlighter,
+    checkDOM: () => {
+      //console.log('Document readyState:', document.readyState);
+      //console.log('Body:', document.body);
+      //console.log('App element:', document.getElementById('app'));
+      const components = document.querySelectorAll('[data-component]');
+      //console.log('Components found:', components.length);
+      //components.forEach(c => console.log('  -', c.getAttribute('data-component'), c));
+    },
+    currentColor: () => {
+      //console.log('Current color from Ruby:', window.FUNICULAR_DEBUG_COLOR);
+      //console.log('Resolved color:', getHighlightColor());
+    }
+  };
+
+  const currentColor = getHighlightColor();
+  //console.log('[Funicular Debug] Current color:', currentColor ? window.FUNICULAR_DEBUG_COLOR : 'disabled');
+})();

data/lib/funicular/commands/routes.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../route_parser"
+
+module Funicular
+  module Commands
+    class Routes
+      def execute
+        # Check if we're in a Rails app
+        unless File.exist?("config/application.rb")
+          puts "Error: Not in a Rails application directory"
+          exit 1
+        end
+
+        # Load Rails environment if not already loaded (CLI usage)
+        unless defined?(Rails)
+          require "./config/environment"
+        end
+
+        source_dir = Rails.root.join("app", "funicular")
+        initializer_file = source_dir.join("initializer.rb")
+
+        unless File.exist?(initializer_file)
+          puts "No Funicular routes found (#{initializer_file} does not exist)"
+          exit 0
+        end
+
+        parser = RouteParser.new(initializer_file)
+        routes = parser.parse
+
+        if routes.empty?
+          puts "No routes defined"
+          exit 0
+        end
+
+        print_routes_table(routes)
+      end
+
+      private
+
+      def print_routes_table(routes)
+        # Calculate column widths
+        method_width = [routes.map { |r| r[:method].length }.max, 6].max
+        path_width = [routes.map { |r| r[:path].length }.max, 4].max
+        component_width = [routes.map { |r| r[:component].length }.max, 9].max
+        helper_width = [routes.map { |r| (r[:helper] || "").length }.max, 10].max
+
+        # Print header
+        puts format_row("Method", "Path", "Component", "Helper",
+                       method_width, path_width, component_width, helper_width)
+        puts "-" * (method_width + path_width + component_width + helper_width + 12)
+
+        # Print routes
+        routes.each do |route|
+          puts format_row(route[:method], route[:path], route[:component],
+                         route[:helper] || "",
+                         method_width, path_width, component_width, helper_width)
+        end
+
+        puts
+        puts "Total: #{routes.length} route#{routes.length == 1 ? '' : 's'}"
+      end
+
+      def format_row(method, path, component, helper, mw, pw, cw, hw)
+        "%-#{mw}s   %-#{pw}s   %-#{cw}s   %-#{hw}s" % [method, path, component, helper]
+      end
+    end
+  end
+end

data/lib/funicular/compiler.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Funicular
+  class Compiler
+    class NodeNotFoundError < StandardError; end
+    class PicorbcMissingError < StandardError; end
+
+    # picorbc.js + picorbc.wasm bundled into the gem at build time by `rake copy_wasm`.
+    PICORBC_DIR = File.expand_path("vendor/picorbc", __dir__)
+    PICORBC_JS  = File.join(PICORBC_DIR, "picorbc.js")
+
+    # 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
+
+    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
+      check_picorbc_availability!
+      gather_source_files
+      compile_to_mrb
+    end
+
+    private
+
+    def check_picorbc_availability!
+      unless File.exist?(PICORBC_JS)
+        raise PicorbcMissingError, <<~ERROR
+          Vendored picorbc not found at #{PICORBC_JS}.
+
+          The funicular gem ships picorbc.js + picorbc.wasm inside the gem
+          package. This file is missing, which likely means the gem was not
+          installed correctly. Try reinstalling:
+
+            bundle install --redownload
+
+        ERROR
+      end
+
+      unless node_command
+        raise NodeNotFoundError, <<~ERROR
+          Node.js executable not found.
+
+          Funicular compiles Ruby to .mrb using a WebAssembly build of picorbc
+          which is run via Node.js. Please install Node.js and ensure `node`
+          is on your PATH (or set the NODE environment variable).
+        ERROR
+      end
+    end
+
+    def node_command
+      @node_command ||= ENV["NODE"] || which("node")
+    end
+
+    def which(cmd)
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        path = File.join(dir, cmd)
+        return path if File.executable?(path) && !File.directory?(path)
+      end
+      nil
+    end
+
+    def gather_source_files
+      all_files = self.class.source_files(source_dir)
+
+      if all_files.empty?
+        raise "No Ruby files found in #{source_dir}"
+      end
+
+      # Create a small temp file for ENV setting
+      env_file = "#{output_file}.env.rb"
+      File.open(env_file, "w") do |f|
+        f.puts "ENV['FUNICULAR_ENV'] = '#{Rails.env}'"
+      end
+
+      @source_files = prepend_source_files + all_files
+      @env_file = env_file
+    end
+
+    def log(message)
+      if logger
+        logger.info(message)
+      else
+        puts message
+      end
+    end
+
+    def compile_to_mrb
+      output_dir = File.dirname(output_file)
+      FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
+
+      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 Ruby..."
+      log "  Source: #{source_dir}" if source_dir
+      log "  Input files:"
+      all_files.each do |file|
+        log "    - #{file}"
+      end
+      log "  Output: #{output_file}"
+      log "  Debug mode: #{debug_mode}"
+      log "  Files: #{all_files.size} files"
+
+      result = system(*argv)
+
+      unless result
+        raise "Failed to compile with picorbc. Command: #{Shellwords.join(argv)}"
+      end
+
+      log "Successfully compiled to #{output_file}"
+    ensure
+      # Keep temp file for debugging - set FUNICULAR_KEEP_TEMP=1 to inspect temp file
+      unless ENV['FUNICULAR_KEEP_TEMP']
+        File.delete(@env_file) if @env_file && File.exist?(@env_file)
+      end
+    end
+  end
+end

data/lib/funicular/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Funicular
+  # Holds runtime configuration for the funicular gem.
+  #
+  # The most important setting is which PicoRuby.wasm artifact the
+  # +picoruby_include_tag+ helper should reference, per Rails environment.
+  #
+  # Possible source values:
+  #
+  #   :local_debug - serve the debug build vendored into the gem and
+  #                  installed under public/picoruby/debug/
+  #   :local_dist  - serve the production (dist) build vendored into the
+  #                  gem and installed under public/picoruby/dist/
+  #   :cdn         - load from jsDelivr at
+  #                  https://cdn.jsdelivr.net/npm/@picoruby/wasm-wasi@VERSION/dist/init.iife.js
+  #
+  # Defaults are sensible for most apps:
+  #
+  #   development -> :local_debug
+  #   test        -> :local_debug
+  #   production  -> :local_dist
+  #
+  # Switch production to :cdn if you would rather not host the wasm yourself.
+  class Configuration
+    SOURCES = %i[local_debug local_dist cdn].freeze
+
+    attr_reader :development_source, :test_source, :production_source
+    attr_writer :cdn_version
+
+    def initialize
+      @development_source = :local_debug
+      @test_source        = :local_debug
+      @production_source  = :local_dist
+      @cdn_version        = nil
+    end
+
+    def development_source=(value)
+      @development_source = validate_source!(value)
+    end
+
+    def test_source=(value)
+      @test_source = validate_source!(value)
+    end
+
+    def production_source=(value)
+      @production_source = validate_source!(value)
+    end
+
+    # Returns the configured source for a given Rails environment name.
+    # Unknown environments fall back to development_source.
+    def source_for(env_name)
+      case env_name.to_s
+      when "production" then @production_source
+      when "test"       then @test_source
+      else                   @development_source
+      end
+    end
+
+    # The @picoruby/wasm-wasi version to use when source is :cdn.
+    # Falls back to the version of the wasm artifacts vendored in this gem.
+    def cdn_version
+      @cdn_version || Funicular.vendored_wasm_version
+    end
+
+    private
+
+    def validate_source!(value)
+      sym = value.to_sym
+      unless SOURCES.include?(sym)
+        raise ArgumentError, "Invalid Funicular source: #{value.inspect}. Expected one of #{SOURCES.inspect}"
+      end
+      sym
+    end
+  end
+end

data/lib/funicular/helpers/picoruby_helper.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Funicular
+  module Helpers
+    # View helpers exposed to ActionView through Funicular::Railtie.
+    module PicorubyHelper
+      CDN_URL_TEMPLATE = "https://cdn.jsdelivr.net/npm/@picoruby/wasm-wasi@%<version>s/dist/init.iife.js"
+
+      LOCAL_PATHS = {
+        local_debug: "/picoruby/debug/init.iife.js",
+        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
+      # current Rails environment, but can be overridden per call:
+      #
+      #   <%= picoruby_include_tag %>
+      #   <%= picoruby_include_tag source: :cdn %>
+      #   <%= picoruby_include_tag source: :local_dist, defer: true %>
+      #
+      # 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)
+        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
+
+      def picoruby_src_for(source)
+        if source == :cdn
+          version = Funicular.configuration.cdn_version
+          if version.nil? || version.empty?
+            raise ArgumentError,
+                  "picoruby_include_tag source :cdn requires a version. " \
+                  "Set Funicular.configuration.cdn_version or vendor the wasm artifacts via `rake funicular:vendor`."
+          end
+          format(CDN_URL_TEMPLATE, version: version)
+        elsif (path = LOCAL_PATHS[source])
+          path
+        else
+          raise ArgumentError,
+                "Unknown picoruby source: #{source.inspect}. Expected one of #{Funicular::Configuration::SOURCES.inspect}"
+        end
+      end
+    end
+  end
+end