reactive-actions 0.1.0.pre.alpha.1 → 0.1.0.pre.alpha.2

data/app/assets/javascripts/reactive_actions.js

@@ -1,9 +1,267 @@
 // ReactiveActions JavaScript Client for Rails 8
-// ES Module compatible version
+// ES Module compatible version with manual initialization
 
 class ReactiveActionsClient {
-  constructor() {
-    this.baseUrl = '/reactive_actions/execute';
+  constructor(options = {}) {
+    // Default configuration
+    this.config = {
+      baseUrl: '/reactive_actions/execute',
+      enableAutoBinding: true,
+      enableMutationObserver: true,
+      defaultHttpMethod: 'POST',
+      ...options
+    };
+    
+    this.boundElements = new WeakSet();
+    this.initialized = false;
+  }
+
+  // Update configuration
+  configure(options = {}) {
+    this.config = { ...this.config, ...options };
+    
+    // If baseUrl changed, update it
+    if (options.baseUrl) {
+      this.baseUrl = options.baseUrl;
+    }
+    
+    return this;
+  }
+
+  // Get current configuration
+  getConfig() {
+    return { ...this.config };
+  }
+
+  // Initialize DOM bindings when called - must be called manually
+  initialize(options = {}) {
+    // Update configuration if options provided
+    if (Object.keys(options).length > 0) {
+      this.configure(options);
+    }
+    
+    // Skip if already initialized
+    if (this.initialized) return this;
+    
+    // Only bind if auto-binding is enabled
+    if (this.config.enableAutoBinding) {
+      this.bindExistingElements();
+      
+      if (this.config.enableMutationObserver) {
+        this.setupMutationObserver();
+      }
+    }
+    
+    this.initialized = true;
+    return this;
+  }
+
+  // Force re-initialization (useful after configuration changes)
+  reinitialize() {
+    this.initialized = false;
+    this.boundElements = new WeakSet();
+    this.initialize();
+  }
+
+  // Bind all existing elements with reactive-action attributes
+  bindExistingElements() {
+    const elements = document.querySelectorAll('[reactive-action]');
+    elements.forEach(element => this.bindElement(element));
+  }
+
+  // Set up mutation observer to handle dynamically added elements
+  setupMutationObserver() {
+    const observer = new MutationObserver(mutations => {
+      mutations.forEach(mutation => {
+        mutation.addedNodes.forEach(node => {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            // Check if the node itself has reactive-action
+            if (node.hasAttribute && node.hasAttribute('reactive-action')) {
+              this.bindElement(node);
+            }
+            // Check for child elements with reactive-action
+            const children = node.querySelectorAll ? node.querySelectorAll('[reactive-action]') : [];
+            children.forEach(child => this.bindElement(child));
+          }
+        });
+      });
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+  }
+
+  // Bind a single element to reactive actions
+  bindElement(element) {
+    // Skip if already bound
+    if (this.boundElements.has(element)) return;
+
+    const actionValue = element.getAttribute('reactive-action');
+    if (!actionValue) return;
+
+    // Parse actions - support multiple actions separated by spaces
+    const actions = this.parseActions(actionValue);
+    
+    actions.forEach(({ event, httpMethod, actionName }) => {
+      const listener = this.createActionListener(element, actionName, httpMethod);
+      
+      // Handle special cases for form submission
+      if (event === 'submit' && element.tagName.toLowerCase() === 'form') {
+        element.addEventListener('submit', (e) => {
+          e.preventDefault();
+          listener(e);
+        });
+      } else {
+        element.addEventListener(event, listener);
+      }
+    });
+
+    // Mark as bound
+    this.boundElements.add(element);
+  }
+
+  // Parse action string(s) - supports "click->action_name", "click->post#action_name", or multiple actions
+  parseActions(actionValue) {
+    const actions = [];
+    const actionPairs = actionValue.trim().split(/\s+/);
+    
+    actionPairs.forEach(pair => {
+      // Match patterns: "event->action", "event->method#action"
+      const match = pair.match(/^(\w+)->((?:(\w+)#)?(.+))$/);
+      if (match) {
+        const [, event, , httpMethod, actionName] = match;
+        actions.push({ 
+          event, 
+          httpMethod: httpMethod ? httpMethod.toUpperCase() : this.config.defaultHttpMethod,
+          actionName 
+        });
+      }
+    });
+    
+    return actions;
+  }
+
+  // Create event listener for an action
+  createActionListener(element, actionName, httpMethod = null) {
+    return async (event) => {
+      try {
+        // Add loading state
+        this.setLoadingState(element, true);
+
+        // Extract data attributes
+        const actionParams = this.extractDataAttributes(element);
+        
+        // Add form data if it's a form element
+        if (element.tagName.toLowerCase() === 'form') {
+          const formData = new FormData(element);
+          for (const [key, value] of formData.entries()) {
+            actionParams[key] = value;
+          }
+        }
+        
+        // Add input value for input elements on change events
+        if (['input', 'select', 'textarea'].includes(element.tagName.toLowerCase()) && 
+            ['change', 'input'].includes(event.type)) {
+          actionParams.value = element.value;
+        }
+
+        // Execute the action using the existing method with specified HTTP method
+        const method = httpMethod || this.config.defaultHttpMethod;
+        const response = await this.execute(actionName, actionParams, { method });
+        
+        // Handle response
+        this.handleActionResponse(element, response, event);
+        
+      } catch (error) {
+        this.handleActionError(element, error, event);
+      } finally {
+        this.setLoadingState(element, false);
+      }
+    };
+  }
+
+  // Extract data attributes from element
+  extractDataAttributes(element) {
+    const data = {};
+    const attributes = element.attributes;
+    
+    for (const attr of attributes) {
+      if (attr.name.startsWith('reactive-action-') && 
+          !['reactive-action', 'reactive-action-success', 'reactive-action-error'].includes(attr.name)) {
+        const key = attr.name
+          .replace('reactive-action-', '')
+          .replace(/-/g, '_'); // Convert kebab-case to snake_case
+        data[key] = attr.value;
+      }
+    }
+    
+    return data;
+  }
+
+  // Set loading state on element
+  setLoadingState(element, loading) {
+    if (loading) {
+      element.classList.add('reactive-loading');
+      if (element.tagName.toLowerCase() === 'button' || element.tagName.toLowerCase() === 'input') {
+        element.disabled = true;
+      }
+      // Store original text if it's a button or link
+      if (['button', 'a'].includes(element.tagName.toLowerCase())) {
+        element.dataset.originalText = element.textContent;
+        element.textContent = element.dataset.loadingText || 'Loading...';
+      }
+    } else {
+      element.classList.remove('reactive-loading');
+      if (element.tagName.toLowerCase() === 'button' || element.tagName.toLowerCase() === 'input') {
+        element.disabled = false;
+      }
+      // Restore original text
+      if (element.dataset.originalText) {
+        element.textContent = element.dataset.originalText;
+        delete element.dataset.originalText;
+      }
+    }
+  }
+
+  // Handle successful action response
+  handleActionResponse(element, response, event) {
+    // Dispatch custom event
+    const customEvent = new CustomEvent('reactive-action:success', {
+      detail: { response, element, originalEvent: event },
+      bubbles: true
+    });
+    element.dispatchEvent(customEvent);
+
+    // Handle success callback if specified
+    const successCallback = element.getAttribute('reactive-action-success');
+    if (successCallback && typeof window[successCallback] === 'function') {
+      window[successCallback](response, element, event);
+    }
+
+    // Log successful responses that aren't ok
+    if (!response.ok) {
+      console.warn('ReactiveActions response not ok:', response);
+    }
+  }
+
+  // Handle action errors
+  handleActionError(element, error, event) {
+    console.error('ReactiveActions error:', error);
+    
+    // Dispatch custom event
+    const customEvent = new CustomEvent('reactive-action:error', {
+      detail: { error, element, originalEvent: event },
+      bubbles: true
+    });
+    element.dispatchEvent(customEvent);
+
+    // Handle error callback if specified
+    const errorCallback = element.getAttribute('reactive-action-error');
+    if (errorCallback && typeof window[errorCallback] === 'function') {
+      window[errorCallback](error, element, event);
+    }
   }
 
   // Get CSRF token from meta tag
@@ -14,9 +272,12 @@ class ReactiveActionsClient {
 
   // Execute an action with parameters
   async execute(actionName, actionParams = {}, options = {}) {
-    const method = options.method || 'POST';
+    const method = options.method || this.config.defaultHttpMethod;
     const contentType = options.contentType || 'application/json';
     
+    // Use configured baseUrl
+    const baseUrl = this.config.baseUrl;
+    
     // Build request options
     const requestOptions = {
       method: method,
@@ -34,7 +295,7 @@ class ReactiveActionsClient {
     }
     
     // Build URL or prepare body based on HTTP method
-    let url = this.baseUrl;
+    let url = baseUrl;
     if (['GET', 'HEAD'].includes(method.toUpperCase())) {
       // For GET requests, append parameters to URL
       const params = new URLSearchParams({
@@ -88,13 +349,10 @@ class ReactiveActionsClient {
   }
 }
 
-// Create and export the instance
-const ReactiveActions = new ReactiveActionsClient();
+// ES Module export
+export default ReactiveActionsClient;
 
-// For backward compatibility, also expose as global
+// Global export
 if (typeof window !== 'undefined') {
-  window.ReactiveActions = ReactiveActions;
-}
-
-// ES Module export
-export default ReactiveActions;
+  window.ReactiveActionsClient = ReactiveActionsClient;
+}

data/lib/generators/reactive_actions/install/install_generator.rb

@@ -20,6 +20,14 @@ module ReactiveActions
                                   desc: 'Skip generating example action'
       class_option :mount_path, type: :string, default: '/reactive_actions',
                                 desc: 'Custom mount path for ReactiveActions'
+      class_option :auto_initialize, type: :boolean, default: true,
+                                     desc: 'Auto-initialize ReactiveActions client on page load'
+      class_option :enable_dom_binding, type: :boolean, default: true,
+                                        desc: 'Enable automatic DOM binding'
+      class_option :enable_mutation_observer, type: :boolean, default: true,
+                                              desc: 'Enable mutation observer for dynamic content'
+      class_option :default_http_method, type: :string, default: 'POST',
+                                         desc: 'Default HTTP method for actions'
       class_option :quiet, type: :boolean, default: false,
                            desc: 'Run with minimal output'
 
@@ -67,12 +75,20 @@ module ReactiveActions
 
         if options[:quiet] || yes?('Add ReactiveActions JavaScript client?', :green)
           add_javascript_to_importmap
-          say '✓ Added JavaScript client to importmap', :green unless options[:quiet]
+          add_javascript_initialization
+          say '✓ Added JavaScript client with initialization', :green unless options[:quiet]
         else
           say '✗ Skipped JavaScript configuration', :yellow
         end
       end
 
+      def javascript_configuration_options
+        return if options[:skip_javascript] || options[:quiet]
+        return unless javascript_needed?
+
+        configure_javascript_options
+      end
+
       def configuration_options
         return if options[:quiet]
         return unless yes?('Configure advanced options?', :green)
@@ -164,12 +180,9 @@ module ReactiveActions
         IMPORTMAP
 
         append_to_file 'config/importmap.rb', importmap_content
-
-        # Add the import to application.js to ensure it executes
-        add_import_to_application_js
       end
 
-      def add_import_to_application_js
+      def add_javascript_initialization
         app_js_paths = %w[
           app/javascript/application.js
           app/assets/javascripts/application.js
@@ -179,21 +192,104 @@ module ReactiveActions
         app_js_path = app_js_paths.find { |path| File.exist?(path) }
 
         if app_js_path
-          # Check if import already exists
+          # Check if ReactiveActions is already configured
           app_js_content = File.read(app_js_path)
-          return if app_js_content.include?('import "reactive_actions"')
+          return if app_js_content.include?('ReactiveActions') || app_js_content.include?('reactive_actions')
+
+          # Generate JavaScript initialization code
+          js_config = generate_javascript_config
+
+          js_code = <<~JAVASCRIPT
+
+            // Import and initialize ReactiveActions
+            import ReactiveActionsClient from "reactive_actions"
 
-          import_line = <<~JAVASCRIPT
+            // Create and configure ReactiveActions instance
+            const reactiveActions = new ReactiveActionsClient(#{js_config});
 
-            // Import ReactiveActions to make it globally available
-            import "reactive_actions"
+            #{generate_initialization_code}
+
+            // Make ReactiveActions globally available
+            window.ReactiveActions = reactiveActions;
           JAVASCRIPT
 
-          append_to_file app_js_path, import_line
-          say "✓ Added ReactiveActions import to #{app_js_path}", :green unless options[:quiet]
+          append_to_file app_js_path, js_code
+          say "✓ Added ReactiveActions initialization to #{app_js_path}", :green unless options[:quiet]
+        else
+          say '⚠ Could not find application.js file. Please manually add ReactiveActions initialization.', :yellow
+        end
+      end
+
+      def generate_javascript_config
+        config = {}
+
+        # Add mount path if different from default
+        mount_path = determine_mount_path || options[:mount_path]
+        config[:baseUrl] = "#{mount_path}/execute" if mount_path != '/reactive_actions'
+
+        # Add configuration options
+        config[:enableAutoBinding] = javascript_option_value(:enable_dom_binding)
+        config[:enableMutationObserver] = javascript_option_value(:enable_mutation_observer)
+        config[:defaultHttpMethod] = javascript_option_value(:default_http_method, 'POST')
+
+        # Remove default values to keep config clean
+        config.delete(:enableAutoBinding) if config[:enableAutoBinding] == true
+        config.delete(:enableMutationObserver) if config[:enableMutationObserver] == true
+        config.delete(:defaultHttpMethod) if config[:defaultHttpMethod] == 'POST'
+
+        config.empty? ? '{}' : JSON.pretty_generate(config)
+      end
+
+      def generate_initialization_code
+        if javascript_option_value(:auto_initialize)
+          <<~JAVASCRIPT.strip
+            // Initialize on DOM content loaded and Turbo events
+            document.addEventListener('DOMContentLoaded', () => reactiveActions.initialize());
+            document.addEventListener('turbo:load', () => reactiveActions.initialize());
+            document.addEventListener('turbo:frame-load', () => reactiveActions.initialize());
+          JAVASCRIPT
         else
-          say '⚠ Could not find application.js file. Please manually add: import "reactive_actions"', :yellow
+          <<~JAVASCRIPT.strip
+            // Manual initialization - call reactiveActions.initialize() when ready
+            // Example: reactiveActions.initialize();
+          JAVASCRIPT
+        end
+      end
+
+      def javascript_option_value(option_key, default_value = nil)
+        return options[option_key] if options.key?(option_key)
+        return default_value unless default_value.nil?
+
+        case option_key
+        when :enable_dom_binding, :enable_mutation_observer, :auto_initialize
+          true
+        when :default_http_method
+          'POST'
+        end
+      end
+
+      def configure_javascript_options
+        return unless yes?('Configure JavaScript client options?', :green)
+
+        # Auto-initialize option
+        auto_init = yes?('Auto-initialize ReactiveActions on page load? (recommended)', :green)
+        @javascript_options ||= {}
+        @javascript_options[:auto_initialize] = auto_init
+
+        # DOM binding option
+        enable_dom = yes?('Enable automatic DOM binding? (recommended)', :green)
+        @javascript_options[:enable_dom_binding] = enable_dom
+
+        # Mutation observer option
+        if enable_dom
+          enable_observer = yes?('Enable mutation observer for dynamic content? (recommended)', :green)
+          @javascript_options[:enable_mutation_observer] = enable_observer
         end
+
+        # Default HTTP method
+        http_methods = %w[POST GET PUT PATCH DELETE]
+        default_method = ask('Default HTTP method:', limited_to: http_methods, default: 'POST')
+        @javascript_options[:default_http_method] = default_method unless default_method == 'POST'
       end
 
       def add_to_sprockets_manifest

data/lib/generators/reactive_actions/install/templates/README

@@ -2,31 +2,107 @@
 
 ReactiveActions has been installed successfully!
 
-Routes have been added to your config/routes.rb file:
+SETUP COMPLETED:
+================
+
+✓ Routes added to config/routes.rb:
   mount ReactiveActions::Engine, at: '/reactive_actions'
 
-You can now access the reactive actions functionality at:
-  http://localhost:3000/reactive_actions/execute
+✓ JavaScript client configured with automatic initialization
+  - Added to config/importmap.rb
+  - Initialized in app/javascript/application.js
+  - Available globally as window.ReactiveActions
 
-A sample action has been created at:
+✓ Sample action created:
   app/reactive_actions/example_action.rb
 
-You can try it out with:
-  
-  # Using HTTP
-  curl -X POST http://localhost:3000/reactive_actions/execute \
-    -H "Content-Type: application/json" \
-    -d '{"action_name": "example", "action_params": {"name": "YourName"}}'
-  
-  # Using JavaScript client
-  ReactiveActions.execute('example', { name: 'YourName' })
-    .then(response => console.log(response))
-
-To create your own actions, add more files to the app/reactive_actions directory.
-Each action should inherit from ReactiveActions::ReactiveAction and define
-at least the `action` and `response` methods.
-
-For more information, see the documentation at:
+QUICK START:
+============
+
+1. Test the API endpoint:
+   curl -X POST http://localhost:3000/reactive_actions/execute \
+     -H "Content-Type: application/json" \
+     -d '{"action_name": "example", "action_params": {"name": "YourName"}}'
+
+2. Use JavaScript client:
+   ReactiveActions.execute('example', { name: 'YourName' })
+     .then(response => console.log(response))
+
+3. Use DOM binding (no JavaScript required):
+   <button reactive-action="click->example" 
+           reactive-action-name="YourName">
+     Test Action
+   </button>
+
+JAVASCRIPT CLIENT:
+==================
+
+The ReactiveActions client is automatically initialized and available as:
+- window.ReactiveActions (global)
+- Supports all HTTP methods: get, post, put, patch, delete
+- Automatic CSRF token handling
+- DOM binding with mutation observer
+
+Examples:
+  // Execute actions
+  ReactiveActions.execute('action_name', { param: 'value' })
+  ReactiveActions.post('create_user', { name: 'John' })
+  ReactiveActions.get('fetch_data', { id: 123 })
+
+  // Configuration (if needed)
+  ReactiveActions.configure({
+    baseUrl: '/custom/path/execute',
+    defaultHttpMethod: 'PUT'
+  }).reinitialize()
+
+DOM BINDING:
+============
+
+Add reactive-action attributes to any element:
+
+  <!-- Basic actions -->
+  <button reactive-action="click->update_user">Update</button>
+  <input reactive-action="change->search" type="text">
+  <form reactive-action="submit->create_post">...</form>
+
+  <!-- With HTTP methods -->
+  <button reactive-action="click->put#update_user">Update (PUT)</button>
+  <button reactive-action="click->delete#remove_user">Delete</button>
+
+  <!-- Pass data via attributes -->
+  <button reactive-action="click->update_user"
+          reactive-action-user-id="123"
+          reactive-action-name="John">
+    Update User
+  </button>
+
+CREATING ACTIONS:
+=================
+
+Add files to app/reactive_actions/:
+
+  # app/reactive_actions/update_user_action.rb
+  class UpdateUserAction < ReactiveActions::ReactiveAction
+    def action
+      user = User.find(action_params[:user_id])
+      user.update(name: action_params[:name])
+      @result = { success: true, user: user.as_json }
+    end
+
+    def response
+      render json: @result
+    end
+  end
+
+DOCUMENTATION & SUPPORT:
+========================
+
+For complete documentation and examples:
   https://github.com/IstvanMs/reactive-actions
 
+For troubleshooting and configuration options:
+  Check config/initializers/reactive_actions.rb
+
+Happy coding with ReactiveActions! 🚀
+
 ===============================================================================

data/lib/generators/reactive_actions/install/templates/initializer.rb

@@ -11,3 +11,17 @@ end
 
 # Set the logger for ReactiveActions
 ReactiveActions.logger = Rails.logger
+
+# JavaScript Client Configuration
+# ================================
+# The JavaScript client is automatically initialized in application.js
+# You can reconfigure it at runtime if needed:
+#
+# ReactiveActions.configure({
+#   baseUrl: '/custom/path/execute',
+#   enableAutoBinding: true,
+#   enableMutationObserver: true,
+#   defaultHttpMethod: 'POST'
+# }).reinitialize();
+#
+# Available globally as window.ReactiveActions

data/lib/reactive_actions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReactiveActions
-  VERSION = '0.1.0-alpha.1'
+  VERSION = '0.1.0-alpha.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: reactive-actions
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.1
+  version: 0.1.0.pre.alpha.2
 platform: ruby
 authors:
 - Istvan Meszaros
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-05-30 00:00:00.000000000 Z
+date: 2025-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails