reactive_views 0.1.0

data/lib/reactive_views/component_resolver.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "set"
+
+module ReactiveViews
+  class ComponentResolver
+    EXTENSIONS = %w[.tsx .jsx .ts .js].freeze
+    FILE_EVENT = "reactive_views.file_changed"
+    COMPONENT_EVENT = "reactive_views.component_changed"
+
+    class << self
+      def resolve(component_name, paths = nil)
+        setup_notifications!
+
+        # If caller already passed a concrete file path, accept it.
+        # Some production/performance specs render by absolute component path.
+        if component_name.is_a?(String) && component_name.include?("/")
+          expanded = File.expand_path(component_name)
+          return expanded if File.file?(expanded)
+        end
+
+        search_paths = normalize_paths(paths)
+        cache_key = build_cache_key(component_name, search_paths)
+
+        if (cached = cached_path(cache_key))
+          return cached
+        end
+
+        name_variants = generate_name_variants(component_name)
+
+        search_paths.each do |base_path|
+          next unless Dir.exist?(base_path)
+
+          name_variants.each do |variant|
+            EXTENSIONS.each do |ext|
+              direct_path = File.join(base_path, "#{variant}#{ext}")
+              if (matched = match_file(direct_path))
+                store_cache(cache_key, matched, component_name)
+                log_resolution_success(component_name, matched, variant)
+                return matched
+              end
+
+              index_path = File.join(base_path, variant, "index#{ext}")
+              if (matched = match_file(index_path))
+                store_cache(cache_key, matched, component_name)
+                log_resolution_success(component_name, matched, variant)
+                return matched
+              end
+
+              matches = Dir.glob(File.join(base_path, "**", "#{variant}#{ext}"), File::FNM_CASEFOLD)
+              if matches.any?
+                first_match = matches.first
+                store_cache(cache_key, first_match, component_name)
+                log_resolution_success(component_name, first_match, variant)
+                return first_match
+              end
+            end
+          end
+        end
+
+        log_resolution_failure(component_name)
+        nil
+      end
+
+      def invalidate(component_name: nil, path: nil)
+        cache_mutex.synchronize do
+          invalidate_by_path(path) if path
+          invalidate_by_component(component_name) if component_name
+        end
+      end
+
+      def clear_cache
+        cache_mutex.synchronize do
+          cache_store.clear
+          path_index.clear
+        end
+      end
+
+      # Generate all naming convention variants for a component name
+      # Supports: PascalCase, snake_case, camelCase, kebab-case
+      def generate_name_variants(name)
+        variants = []
+
+        variants << name
+        variants << to_snake_case(name)
+        variants << to_camel_case(name)
+        variants << to_kebab_case(name)
+
+        variants.uniq
+      end
+
+      # Convert PascalCase to snake_case
+      def to_snake_case(name)
+        name
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr("-", "_")
+          .downcase
+      end
+
+      # Convert PascalCase to camelCase
+      def to_camel_case(name)
+        return name if name.empty?
+
+        name[0].downcase + name[1..]
+      end
+
+      # Convert PascalCase to kebab-case
+      def to_kebab_case(name)
+        name
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1-\2')
+          .tr("_", "-")
+          .downcase
+      end
+
+      def log_resolution_success(component_name, path, variant)
+        return unless defined?(Rails) && Rails.logger
+
+        variant_info = variant != component_name ? " (as '#{variant}')" : ""
+        Rails.logger.debug("[ReactiveViews] Resolved #{component_name}#{variant_info} to #{path}")
+      end
+
+      def log_resolution_failure(component_name)
+        return unless defined?(Rails) && Rails.logger
+
+        Rails.logger.error("[ReactiveViews] Component '#{component_name}' not found in search paths.")
+      end
+
+      def match_file(path)
+        Dir.glob(path, File::FNM_CASEFOLD).find { |matched| File.file?(matched) }
+      end
+
+      private
+
+      def setup_notifications!
+        return unless defined?(ActiveSupport::Notifications)
+        return if @notifications_subscribed
+
+        ActiveSupport::Notifications.subscribe(FILE_EVENT) do |_name, _start, _finish, _id, payload|
+          invalidate(path: payload[:path]) if payload.is_a?(Hash) && payload[:path]
+        end
+
+        ActiveSupport::Notifications.subscribe(COMPONENT_EVENT) do |_name, _start, _finish, _id, payload|
+          invalidate(component_name: payload[:component]) if payload.is_a?(Hash) && payload[:component]
+        end
+
+        @notifications_subscribed = true
+      end
+
+      def normalize_paths(paths)
+        paths ||= ReactiveViews.config.component_views_paths + ReactiveViews.config.component_js_paths
+
+        paths.map do |path|
+          if path.is_a?(Pathname) || path.start_with?("/")
+            path.to_s
+          elsif defined?(Rails)
+            Rails.root.join(path).to_s
+          else
+            File.expand_path(path)
+          end
+        end
+      end
+
+      def cached_path(cache_key)
+        cache_mutex.synchronize do
+          entry = cache_store[cache_key]
+          return unless entry
+
+          path = entry[:path]
+          return unless File.exist?(path)
+
+          current_mtime = File.mtime(path)
+          if entry[:mtime] == current_mtime
+            path
+          else
+            remove_entry(cache_key, path)
+            nil
+          end
+        end
+      end
+
+      def store_cache(cache_key, path, component_name)
+        normalized_path = File.expand_path(path)
+        cache_mutex.synchronize do
+          cache_store[cache_key] = {
+            path: normalized_path,
+            mtime: File.mtime(normalized_path),
+            component_name: component_name
+          }
+
+          path_index[normalized_path] ||= Set.new
+          path_index[normalized_path] << cache_key
+        end
+      end
+
+      def remove_entry(cache_key, path)
+        cache_store.delete(cache_key)
+        normalized_path = File.expand_path(path)
+        if path_index[normalized_path]
+          path_index[normalized_path].delete(cache_key)
+          path_index.delete(normalized_path) if path_index[normalized_path].empty?
+        end
+      end
+
+      def invalidate_by_path(path)
+        normalized_path = File.expand_path(path)
+        keys = path_index.delete(normalized_path)
+        return unless keys
+
+        keys.each { |key| cache_store.delete(key) }
+      end
+
+      def invalidate_by_component(component_name)
+        return unless component_name
+
+        keys_to_remove = cache_store.each_with_object([]) do |(key, entry), list|
+          list << [ key, entry[:path] ] if entry && entry[:component_name] == component_name
+        end
+
+        keys_to_remove.each do |key, path|
+          remove_entry(key, path)
+        end
+      end
+
+      def build_cache_key(component_name, search_paths)
+        "#{component_name}::#{search_paths.join("||")}"
+      end
+
+      def cache_store
+        @cache_store ||= {}
+      end
+
+      def path_index
+        @path_index ||= {}
+      end
+
+      def cache_mutex
+        @cache_mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/reactive_views/configuration.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ReactiveViews
+  class Configuration
+    attr_accessor :enabled,
+                  :ssr_url,
+                  :component_views_paths,
+                  :component_js_paths,
+                  :ssr_cache_ttl_seconds,
+                  :boot_module_path,
+                  :ssr_timeout,
+                  :batch_rendering_enabled,
+                  :batch_timeout,
+                  :tree_rendering_enabled,
+                  :max_nesting_depth_warning,
+                  :props_inference_enabled,
+                  :props_inference_cache_ttl_seconds,
+                  :full_page_enabled,
+                  :cache_namespace,
+                  # Asset host for CDN deployments
+                  :asset_host
+
+    attr_reader :cache_store
+
+    # Alias for easier testing
+    alias component_paths component_views_paths
+    alias component_paths= component_views_paths=
+
+    def initialize
+      @enabled = true
+      # RV_SSR_URL is the primary env var, REACTIVE_VIEWS_SSR_URL is kept for backwards compatibility
+      @ssr_url = ENV.fetch("RV_SSR_URL") { ENV.fetch("REACTIVE_VIEWS_SSR_URL", "http://localhost:5175") }
+      @component_views_paths = [ "app/views/components" ]
+      @component_js_paths = [ "app/javascript/components" ]
+      @ssr_cache_ttl_seconds = nil
+      @boot_module_path = nil
+      @ssr_timeout = ENV.fetch("RV_SSR_TIMEOUT") { ENV.fetch("REACTIVE_VIEWS_SSR_TIMEOUT", 5) }.to_i
+      @batch_rendering_enabled = true
+      @batch_timeout = 10
+      @tree_rendering_enabled = true
+      @max_nesting_depth_warning = 3
+      @props_inference_enabled = true
+      @props_inference_cache_ttl_seconds = 300
+      @full_page_enabled = true
+      @cache_namespace = "reactive_views"
+      self.cache_store = :memory
+
+      # Asset host for CDN deployments
+      @asset_host = ENV["ASSET_HOST"]
+    end
+
+    def cache_store=(store)
+      @cache_store = CacheStore.build(store)
+    end
+
+    def cache_for(scope)
+      scope_name = scope.to_s
+      cache_store.namespaced("#{cache_namespace}:#{scope_name}")
+    end
+
+    # Returns true if SSR is available and enabled
+    def ssr_enabled?
+      enabled && ssr_url.present?
+    end
+
+    # Returns true if the application is in production mode
+    def production?
+      defined?(Rails) && Rails.env.production?
+    end
+  end
+end

data/lib/reactive_views/controller_props.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ReactiveViews
+  # Controller mixin for explicit props to pass to full-page TSX rendering
+  module ControllerProps
+    # Deep-merges props to be passed to full-page TSX rendering alongside instance variables
+    # Can be called multiple times; values are deep-merged
+    #
+    # @param hash [Hash] Props to merge
+    # @return [Hash] Current merged props
+    #
+    # @example
+    #   class UsersController < ApplicationController
+    #     before_action -> { reactive_view_props(current_user: current_user) }
+    #
+    #     def index
+    #       @users = User.all
+    #       reactive_view_props(page: { title: "Users" })
+    #     end
+    #   end
+    def reactive_view_props(hash = nil)
+      @_reactive_view_props ||= {}
+      @_reactive_view_props = deep_merge(@_reactive_view_props, hash.deep_symbolize_keys) if hash
+      @_reactive_view_props
+    end
+
+    # Alias for convenience
+    alias reactive_props reactive_view_props
+
+    private
+
+    # Deep merge two hashes
+    def deep_merge(hash, other_hash)
+      hash.merge(other_hash) do |_key, old_val, new_val|
+        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+          deep_merge(old_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+  end
+end

data/lib/reactive_views/css_strategy.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module ReactiveViews
+  # CSS isolation strategies and conflict detection utilities
+  # Helps prevent style conflicts between React components and Rails views
+  module CssStrategy
+    # Common class names that often cause conflicts between React and Rails
+    COMMON_CONFLICT_CLASSES = %w[
+      btn button card container row col form input label
+      header footer nav navbar sidebar menu modal alert
+      badge tooltip popover dropdown tab panel
+      table list item link icon text title
+      primary secondary success danger warning info
+      active disabled selected hidden visible
+      small medium large
+    ].freeze
+
+    # Recommendations for CSS isolation strategies
+    STRATEGIES = {
+      css_modules: {
+        name: "CSS Modules",
+        description: "Automatic class name scoping with .module.css files",
+        pros: [ "Automatic scoping", "Build-time guarantee", "IDE support" ],
+        cons: [ "Requires Vite/bundler setup", "Different syntax from regular CSS" ],
+        setup: <<~SETUP
+          1. Name your CSS files with .module.css extension
+          2. Import styles as objects: import styles from './Component.module.css'
+          3. Use styles.className in your JSX
+        SETUP
+      },
+      tailwind_prefix: {
+        name: "Tailwind Prefix",
+        description: "Configure Tailwind with a prefix for React components",
+        pros: [ "Works with existing Tailwind setup", "Easy to configure" ],
+        cons: [ "Need to remember prefix", "Doesn't help with custom CSS" ],
+        setup: <<~SETUP
+          In tailwind.config.js for React components:
+          module.exports = {
+            prefix: 'rv-',
+            content: ['./app/views/components/**/*.tsx'],
+          }
+        SETUP
+      },
+      bem_convention: {
+        name: "BEM Convention",
+        description: "Use Block-Element-Modifier naming with component prefix",
+        pros: [ "No tooling required", "Clear naming", "Works everywhere" ],
+        cons: [ "Manual discipline required", "Verbose class names" ],
+        setup: <<~SETUP
+          Use component name as block: ComponentName__element--modifier
+          Example: Counter__button--primary
+        SETUP
+      },
+      shadow_dom: {
+        name: "Shadow DOM",
+        description: "Use Web Components with Shadow DOM for true isolation",
+        pros: [ "Complete CSS isolation", "Native browser feature" ],
+        cons: [ "Complex setup", "SSR challenges", "Less React-like" ],
+        setup: <<~SETUP
+          Wrap React components in custom elements with Shadow DOM.
+          Note: This requires additional setup and may affect hydration.
+        SETUP
+      }
+    }.freeze
+
+    class << self
+      # Check for potential CSS conflicts in component HTML
+      # Returns an array of detected conflicts with details
+      #
+      # @param html [String] The HTML content to analyze
+      # @param rails_classes [Array<String>] Known Rails/application CSS classes
+      # @return [Array<Hash>] Array of conflict details
+      def detect_conflicts(html, rails_classes: [])
+        conflicts = []
+        all_classes = extract_classes(html)
+
+        # Check against common conflict patterns
+        common_conflicts = all_classes & COMMON_CONFLICT_CLASSES
+        common_conflicts.each do |class_name|
+          conflicts << {
+            type: :common_name,
+            class_name: class_name,
+            message: "Class '#{class_name}' is a common name that may conflict with Rails styles",
+            severity: :warning
+          }
+        end
+
+        # Check against known Rails classes
+        rails_conflicts = all_classes & rails_classes
+        rails_conflicts.each do |class_name|
+          conflicts << {
+            type: :rails_conflict,
+            class_name: class_name,
+            message: "Class '#{class_name}' conflicts with a known Rails application class",
+            severity: :error
+          }
+        end
+
+        conflicts
+      end
+
+      # Extract all CSS class names from HTML content
+      #
+      # @param html [String] The HTML content
+      # @return [Array<String>] Unique class names found
+      def extract_classes(html)
+        return [] if html.blank?
+
+        # Match class attributes and extract individual class names
+        classes = []
+        html.scan(/class=["']([^"']+)["']/) do |match|
+          classes.concat(match[0].split(/\s+/))
+        end
+
+        # Also match className for JSX
+        html.scan(/className=["']([^"']+)["']/) do |match|
+          classes.concat(match[0].split(/\s+/))
+        end
+
+        classes.uniq.reject(&:blank?)
+      end
+
+      # Generate a scoped class name using the component name as prefix
+      #
+      # @param component_name [String] The component name (e.g., "Counter")
+      # @param class_name [String] The original class name
+      # @return [String] Scoped class name (e.g., "rv-counter-button")
+      def scoped_class(component_name, class_name)
+        prefix = component_name.to_s.underscore.tr("_", "-")
+        "rv-#{prefix}-#{class_name}"
+      end
+
+      # Check if a CSS file uses CSS Modules syntax
+      #
+      # @param file_path [String] Path to the CSS file
+      # @return [Boolean] True if the file uses CSS Modules
+      def uses_css_modules?(file_path)
+        return false unless File.exist?(file_path)
+
+        # CSS Modules files typically have .module.css extension
+        return true if file_path.end_with?(".module.css", ".module.scss")
+
+        # Also check for :local and :global selectors
+        content = File.read(file_path)
+        content.include?(":local(") || content.include?(":global(")
+      end
+
+      # Get recommended strategy based on project setup
+      #
+      # @param options [Hash] Project configuration options
+      # @return [Symbol] Recommended strategy key
+      def recommend_strategy(options = {})
+        return :css_modules if options[:vite] || options[:has_bundler]
+        return :tailwind_prefix if options[:tailwind]
+
+        :bem_convention
+      end
+
+      # Log CSS conflict warnings during development
+      def log_conflicts(conflicts, logger: nil)
+        return if conflicts.empty?
+
+        logger ||= (defined?(Rails) && Rails.logger)
+        return unless logger
+
+        conflicts.each do |conflict|
+          case conflict[:severity]
+          when :error
+            logger.error("[ReactiveViews CSS] #{conflict[:message]}")
+          when :warning
+            logger.warn("[ReactiveViews CSS] #{conflict[:message]}")
+          else
+            logger.info("[ReactiveViews CSS] #{conflict[:message]}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/reactive_views/engine.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ReactiveViews
+  class Engine < ::Rails::Engine
+    isolate_namespace ReactiveViews
+
+    # Mount the engine routes at /reactive_views
+    initializer "reactive_views.routes" do |app|
+      app.routes.prepend do
+        mount ReactiveViews::Engine, at: "/reactive_views"
+      end
+    end
+  end
+end