funicular 0.0.1 → 0.1.0

data/exe/funicular

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "funicular"
+
+command = ARGV[0]
+
+case command
+when "routes"
+  require_relative "../lib/funicular/commands/routes"
+  Funicular::Commands::Routes.new.execute
+when "version", "-v", "--version"
+  puts Funicular::VERSION
+when "help", "-h", "--help", nil
+  puts <<~HELP
+    Funicular CLI
+
+    Usage:
+      funicular routes         Show all Funicular routes
+      funicular version        Show Funicular version
+      funicular help           Show this help message
+
+    Options:
+      -h, --help              Show help
+      -v, --version           Show version
+  HELP
+else
+  puts "Unknown command: #{command}"
+  puts "Run 'funicular help' for usage"
+  exit 1
+end

data/lib/funicular/assets/funicular.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Exclude app/funicular from autoloading (PicoRuby.wasm code, not for CRuby)
+Rails.autoloaders.main.ignore(Rails.root.join("app/funicular"))
+
+# Choose where picoruby_include_tag loads PicoRuby.wasm from, per environment.
+#
+# Available sources:
+#   :local_debug - public/picoruby/debug/init.iife.js (debug build, larger, with symbols)
+#   :local_dist  - public/picoruby/dist/init.iife.js  (production build, smaller)
+#   :cdn         - https://cdn.jsdelivr.net/npm/@picoruby/wasm-wasi@<version>/dist/init.iife.js
+#
+# Defaults:
+#   development -> :local_debug
+#   test        -> :local_debug
+#   production  -> :local_dist
+#
+# Funicular.configure do |config|
+#   config.production_source = :cdn
+#   # config.cdn_version = "4.0.0"  # defaults to the version vendored in the gem
+# end

data/lib/funicular/assets/funicular_debug.css

@@ -0,0 +1,73 @@
+/* Funicular Component Highlighter - Development Mode Only */
+/* Highlights components with data-component attributes for easier debugging */
+
+.funicular-debug-highlight {
+  outline: 2px solid var(--funicular-highlight-color, #00ff00) !important;
+  outline-offset: -2px !important;
+  position: relative !important;
+  box-shadow: inset 0 0 0 2px rgba(0, 255, 0, 0.2) !important;
+}
+
+.funicular-debug-indicator {
+  position: absolute !important;
+  bottom: 0 !important;
+  right: 0 !important;
+  width: 0 !important;
+  height: 0 !important;
+  border-style: solid !important;
+  border-width: 0 0 14px 14px !important;
+  border-color: transparent transparent var(--funicular-highlight-color, #00ff00) transparent !important;
+  pointer-events: auto !important;
+  z-index: 999999 !important;
+  cursor: help !important;
+}
+
+.funicular-debug-indicator::before {
+  content: attr(data-tooltip) !important;
+  position: absolute !important;
+  bottom: -14px !important;
+  right: 0 !important;
+  background-color: rgba(0, 0, 0, 0.95) !important;
+  color: white !important;
+  padding: 6px 10px !important;
+  border-radius: 4px !important;
+  border: 1px solid var(--funicular-highlight-color, #00ff00) !important;
+  font-size: 13px !important;
+  font-family: 'Courier New', monospace !important;
+  white-space: nowrap !important;
+  opacity: 0 !important;
+  pointer-events: none !important;
+  transform: translateY(8px) !important;
+  transition: opacity 0.2s, transform 0.2s !important;
+  z-index: 1000000 !important;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.5) !important;
+}
+
+.funicular-debug-indicator:hover::before {
+  opacity: 1 !important;
+  transform: translateY(0) !important;
+}
+
+/* PicoRuby DevTools Selected Component Highlight */
+.picoruby-devtools-selected {
+  position: relative !important;
+}
+
+.picoruby-devtools-selected::after {
+  content: '' !important;
+  position: absolute !important;
+  top: 0 !important;
+  left: 0 !important;
+  right: 0 !important;
+  bottom: 0 !important;
+  background-color: rgba(0, 122, 204, 0.1) !important;
+  background-image: repeating-linear-gradient(
+    45deg,
+    transparent,
+    transparent 10px,
+    rgba(0, 122, 204, 0.15) 10px,
+    rgba(0, 122, 204, 0.15) 20px
+  ) !important;
+  pointer-events: none !important;
+  z-index: 999998 !important;
+}

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,135 @@
+# 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")
+
+    attr_reader :source_dir, :output_file, :debug_mode, :logger
+
+    def initialize(source_dir:, output_file:, debug_mode: false, logger: nil)
+      @source_dir = source_dir
+      @output_file = output_file
+      @debug_mode = debug_mode
+      @logger = logger
+    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
+      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
+
+      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 = 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
+    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 + [@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 "  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,50 @@
+# 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
+
+      # 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 %>
+      #
+      # Any extra options are passed straight through as HTML attributes.
+      def picoruby_include_tag(source: nil, **options)
+        resolved_source = source ? source.to_sym : Funicular.configuration.source_for(Rails.env)
+        src = picoruby_src_for(resolved_source)
+        tag.script("", src: src, **options)
+      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