action_form 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a83d578e9d0fbf58ccb568473d8a94e1ccb087df4b8f8e5ee2871f2a4689c7b0
-  data.tar.gz: e155e0fada05ece59a1e501fe6d6e52ca0cbd652292f0b243e7e59999760562d
+  metadata.gz: 0211bd706504ef28c1045cc72f33a2408b554ca0a2b3e922436491a1865a16b9
+  data.tar.gz: 87c0249ed1b139d6fea7d26fb9e9d2e220cafa3a045b129530e94b9afb8ef545
 SHA512:
-  metadata.gz: 91b6b047b9ac52d7e1d9162ed4b555456466fa7f59e94d54242492f2e515ad352f145aa179027d51753ec78ed1f12150628e23ab156a56de29b29998e1ae968a
-  data.tar.gz: e64a656d32e8d9ddc91d37d4913c30c513e37854d8f77e368a0acf27e66a1a12a579b8c81bdd4ffd79f4c1ff508850834a256ad93728d762963c8bd317a9c612
+  metadata.gz: 817ea2221b6780ed40c769fd37416fae7e2051256b7084b4d4cb612c60fac7288a4dad38316a9af0eba543bf712e07afce8185f33e1d3768e7172cfd81de8103
+  data.tar.gz: 32a63869d603e1117ac6bacaf4cd526c7127ba23a703343f537507e31e5739ef9bdce5d6701529413f23f0cd9e8794c3d01b5a4d2954070051eecdcd10a7d881

data/README.md

@@ -621,6 +621,313 @@ expect(params).to be_invalid
 
 This feature provides a powerful way to customize and extend form definitions while maintaining the declarative nature of ActionForm.
 
+### Composition and Owner Delegation
+
+ActionForm includes a composition system that allows form components (elements, subforms, and `many` collections) to access methods from their owner (typically the parent form or a custom host object). This promotes code reuse and reduces redundancy by allowing shared logic to be defined in a central location and accessed by multiple form components.
+
+#### **How Composition Works**
+
+When you create a form, all nested elements and subforms automatically have access to their owner through the `owner` accessor. Methods called on elements or subforms that are not defined locally are automatically delegated up the ownership chain, allowing you to access methods from the parent form or a custom host object.
+
+#### **Automatic Ownership Chain**
+
+Ownership is automatically established when forms are built:
+
+```ruby
+class ProductForm < ActionForm::Base
+  element :name do
+    input(type: :text)
+    output(type: :string)
+
+    # This method can call methods on the owner (ProductForm)
+    def render?
+      name_render?  # Delegates to owner.name_render?
+    end
+  end
+
+  many :variants, default: [{}] do
+    subform do
+      element :name do
+        input(type: :text)
+        output(type: :string)
+
+        def render?
+          variants_name_render?  # Delegates to owner.variants_name_render?
+        end
+      end
+
+      def render?
+        variants_subform_render?  # Delegates to owner.variants_subform_render?
+      end
+    end
+  end
+
+  subform :manufacturer, default: {} do
+    element :name do
+      input(type: :text)
+      output(type: :string)
+
+      def render?
+        manufacturer_name_render?  # Delegates to owner.manufacturer_name_render?
+      end
+    end
+  end
+
+  # Methods accessible by nested components
+  def name_render?
+    true
+  end
+
+  def variants_name_render?
+    true
+  end
+
+  def variants_subform_render?
+    true
+  end
+
+  def manufacturer_name_render?
+    true
+  end
+end
+```
+
+#### **Custom Host Object**
+
+You can pass a custom host object when initializing a form, allowing you to separate form logic from business logic:
+
+```ruby
+class HostObject
+  def name_render?
+    current_user.admin? || form_context == :edit
+  end
+
+  def variants_subform_render?
+    feature_enabled?(:variants)
+  end
+
+  def variants_name_render?
+    true
+  end
+
+  def variants_price_render?
+    pricing_enabled?
+  end
+
+  def manufacturer_name_render?
+    manufacturer_feature_enabled?
+  end
+end
+
+class ProductForm < ActionForm::Base
+  element :name do
+    input(type: :text)
+    output(type: :string)
+
+    def render?
+      name_render?  # Calls HostObject#name_render?
+    end
+  end
+
+  many :variants, default: [{}] do
+    subform do
+      element :name do
+        input(type: :text)
+        output(type: :string)
+
+        def render?
+          variants_name_render?  # Calls HostObject#variants_name_render?
+        end
+      end
+
+      element :price do
+        input(type: :number)
+        output(type: :float)
+
+        def render?
+          variants_price_render?  # Calls HostObject#variants_price_render?
+        end
+      end
+
+      def render?
+        variants_subform_render?  # Calls HostObject#variants_subform_render?
+      end
+    end
+  end
+
+  subform :manufacturer, default: {} do
+    element :name do
+      input(type: :text)
+      output(type: :string)
+
+      def render?
+        manufacturer_name_render?  # Calls HostObject#manufacturer_name_render?
+      end
+    end
+  end
+end
+
+# Use the form with a custom host object
+host = HostObject.new
+product = Product.new(name: "Product 1")
+form = ProductForm.new(object: product, owner: host)
+```
+
+#### **Ownership Chain Traversal**
+
+The composition system supports multi-level ownership chains. When a method is called on an element or subform, it searches up the ownership chain until it finds the method:
+
+```ruby
+class GrandparentForm < ActionForm::Base
+  def shared_helper
+    "grandparent"
+  end
+end
+
+class ParentForm < ActionForm::Base
+  def shared_helper
+    "parent"
+  end
+end
+
+class ChildForm < ActionForm::Base
+  element :field do
+    input(type: :text)
+
+    def render?
+      shared_helper  # Will find ParentForm#shared_helper first
+    end
+  end
+end
+
+# If ChildForm has ParentForm as owner, and ParentForm has GrandparentForm as owner:
+# The method lookup order is: ChildForm -> ParentForm -> GrandparentForm
+```
+
+#### **Accessing Owner Directly**
+
+You can access the owner directly using the `owner` accessor:
+
+```ruby
+class ProductForm < ActionForm::Base
+  element :discount_code do
+    input(type: :text)
+    output(type: :string)
+
+    def disabled?
+      # Access owner's methods directly
+      owner.current_user && !owner.current_user.admin?
+    end
+
+    def placeholder
+      owner.discount_placeholder_text
+    end
+  end
+
+  def current_user
+    @current_user ||= User.find(session[:user_id])
+  end
+
+  def discount_placeholder_text
+    "Enter discount code"
+  end
+end
+```
+
+#### **Ownership Hierarchy**
+
+The ownership hierarchy is automatically established as follows:
+
+- **Top-level form**: Can have a custom `owner` passed during initialization
+- **Elements**: Owner is the form or subform that contains them
+- **Subforms**: Owner is the form that contains them
+- **SubformsCollection (many)**: Owner is the form that contains them
+- **Nested elements in subforms**: Owner is the subform that contains them
+- **Nested subforms**: Owner is the parent form or subform
+
+#### **Practical Use Cases**
+
+**Conditional Rendering Based on Context:**
+```ruby
+class OrderForm < ActionForm::Base
+  element :admin_notes do
+    input(type: :textarea)
+    output(type: :string)
+
+    def render?
+      owner.current_user&.admin?
+    end
+  end
+
+  def current_user
+    @current_user
+  end
+end
+```
+
+**Shared Validation Logic:**
+```ruby
+class RegistrationForm < ActionForm::Base
+  element :email do
+    input(type: :email)
+    output(type: :string)
+
+    def disabled?
+      owner.email_locked?
+    end
+  end
+
+  element :email_confirmation do
+    input(type: :email)
+    output(type: :string)
+
+    def disabled?
+      owner.email_locked?
+    end
+  end
+
+  def email_locked?
+    @user.persisted? && @user.email_verified?
+  end
+end
+```
+
+**Feature Flags:**
+```ruby
+class SettingsForm < ActionForm::Base
+  many :advanced_settings do
+    subform do
+      element :feature_flag do
+        input(type: :checkbox)
+        output(type: :bool)
+
+        def render?
+          owner.feature_enabled?(:advanced_settings)
+        end
+      end
+    end
+
+    def render?
+      owner.feature_enabled?(:advanced_settings)
+    end
+  end
+
+  def feature_enabled?(feature)
+    FeatureFlags.enabled?(feature, current_user)
+  end
+end
+```
+
+#### **Benefits**
+
+- **Code Reuse**: Share common logic across multiple form components
+- **Separation of Concerns**: Keep business logic in host objects, form logic in forms
+- **Flexibility**: Support conditional rendering and behavior based on context
+- **Maintainability**: Centralize shared logic instead of duplicating it
+- **Testability**: Test host objects separately from form definitions
+
+The composition system provides a powerful mechanism for creating flexible, maintainable forms that can adapt to different contexts and requirements.
+
 ### Tagging system
 
 ActionForm includes a flexible tagging system that allows you to add custom metadata to form elements and control rendering behavior. Tags serve multiple purposes:

data/lib/action_form/base.rb

@@ -7,6 +7,7 @@ module ActionForm
     include ActionForm::SchemaDSL
     include ActionForm::ElementsDSL
     include ActionForm::Rendering
+    include ActionForm::Composition
 
     attr_reader :elements_instances, :scope, :object, :html_options, :errors
 
@@ -30,13 +31,14 @@ module ActionForm
       end
     end
 
-    def initialize(object: nil, scope: self.class.scope, params: nil, **html_options)
+    def initialize(object: nil, scope: self.class.scope, params: nil, owner: nil, **html_options)
       super()
       @object = object
       @scope ||= scope
       @params = @scope && params.respond_to?(@scope) ? params.public_send(@scope) : params
       @html_options = html_options
       @elements_instances = []
+      @owner = owner
       build_from_object
     end
 
@@ -48,7 +50,7 @@ module ActionForm
         elsif element_definition < ActionForm::Subform
           @elements_instances << build_subform(name, element_definition)
         elsif element_definition < ActionForm::Element
-          @elements_instances << element_definition.new(name, @params || @object, parent_name: @scope)
+          @elements_instances << element_definition.new(name, @params || @object, parent_name: @scope, owner: self)
         end
       end
     end
@@ -73,6 +75,7 @@ module ActionForm
 
     def build_many_subforms(name, collection_definition)
       collection = collection_definition.new(name)
+      collection.owner = self
       Array(subform_value(name)).each.with_index do |item, index|
         collection << build_subform(name, collection_definition.subform_definition, value: item, index: index)
       end
@@ -93,7 +96,8 @@ module ActionForm
 
     def build_subform(name, form_definition, value: subform_value(name), index: nil)
       html_name = subform_html_name(name, index: index)
-      form_definition.new(name: name, scope: html_name, model: value, index: index).tap do |subform|
+      form_definition.new(name: name, scope: html_name, model: value, index: index,
+                          owner: self).tap do |subform|
         subform.helpers = helpers
       end
     end
@@ -103,7 +107,8 @@ module ActionForm
       elements_keys = form_definition.elements.keys.push(:persisted?)
       values = form_definition.elements.values.map(&:default)
       value = Struct.new(*elements_keys).new(*values)
-      form_definition.new(name: name, scope: html_name, model: value, template: true).tap do |subform|
+      form_definition.new(name: name, scope: html_name, model: value, template: true,
+                          owner: self).tap do |subform|
         subform.helpers = helpers
       end
     end

data/lib/action_form/composition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ActionForm
+  # Provides host–guest association helpers for ActionForm components.
+  # When included, it exposes `host_object` and `host_association_name` accessors
+  # and delegates `host_*` method calls to the associated host via `method_missing`.
+  module Composition
+    def self.included(base)
+      base.attr_accessor :owner
+      base.include(InstanceMethods)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods # rubocop:disable Style/Documentation
+      def part_of(owner_name)
+        @owner_name = owner_name
+        alias_method owner_name, :owner
+      end
+    end
+
+    module InstanceMethods # rubocop:disable Style/Documentation
+      def method_missing(name, *attrs, **kwargs, &block)
+        if (handler = owners_chain.lazy.detect { |o| o.public_methods.include?(name) })
+          handler.public_send(name, *attrs, **kwargs, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, _include_private = false)
+        public_methods.detect { |m| m == :owner } || super
+      end
+
+      def owners_chain
+        obj = self
+        Enumerator.new do |y|
+          y << obj = obj.owner while obj.public_methods.include?(:owner)
+        end
+      end
+    end
+  end
+end

data/lib/action_form/element.rb

@@ -4,10 +4,12 @@ module ActionForm
   # Represents a form element with input/output configuration and HTML attributes
   # rubocop:disable Metrics/ClassLength
   class Element
+    include ActionForm::Composition
+
     attr_reader :name, :input_options, :output_options, :html_name, :html_id, :select_options, :tags, :errors_messages
     attr_accessor :helpers
 
-    def initialize(name, object, parent_name: nil)
+    def initialize(name, object, parent_name: nil, owner: nil)
       @name = name
       @object = object
       @html_name = build_html_name(name, parent_name)
@@ -15,6 +17,7 @@ module ActionForm
       @tags = self.class.tags_list.dup
       @errors_messages = extract_errors_messages(object, name)
       tags.merge!(errors: errors_messages.any?)
+      @owner = owner
     end
 
     class << self

data/lib/action_form/subform.rb

@@ -8,6 +8,7 @@ module ActionForm
     include ActionForm::Rendering
     include ActionForm::SchemaDSL
     include ActionForm::ElementsDSL
+    include ActionForm::Composition
 
     class << self
       attr_accessor :default
@@ -23,7 +24,7 @@ module ActionForm
     attr_reader :elements_instances, :tags, :name, :object
     attr_accessor :helpers
 
-    def initialize(name:, scope: nil, model: nil, params: nil, **tags)
+    def initialize(name:, scope: nil, model: nil, params: nil, owner: nil, **tags) # rubocop:disable Metrics/ParameterLists
       super()
       @name = name
       @scope = scope
@@ -31,6 +32,7 @@ module ActionForm
       @params = params
       @elements_instances = []
       @tags = tags
+      @owner = owner
       build_from_object
     end
 
@@ -38,6 +40,7 @@ module ActionForm
       self.class.elements.each do |element_name, element_definition|
         @elements_instances << element_definition.new(element_name, @params || @object, parent_name: @scope)
         @elements_instances.last.tags.merge!(subform: @name)
+        @elements_instances.last.owner = self
       end
     end
 

data/lib/action_form/subforms_collection.rb

@@ -5,6 +5,7 @@ module ActionForm
   class SubformsCollection < ::Phlex::HTML
     extend Forwardable
     include ActionForm::Rendering
+    include ActionForm::Composition
 
     def_delegators :@subforms, :last, :first, :length, :size, :[], :<<
 

data/lib/action_form/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionForm
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/action_form.rb

@@ -4,6 +4,7 @@ require "phlex"
 require "easy_params"
 require "forwardable"
 require_relative "action_form/version"
+require_relative "action_form/composition"
 require_relative "action_form/schema_dsl"
 require_relative "action_form/elements_dsl"
 require_relative "action_form/input"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_form
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andrii Baran
@@ -67,6 +67,7 @@ files:
 - Rakefile
 - lib/action_form.rb
 - lib/action_form/base.rb
+- lib/action_form/composition.rb
 - lib/action_form/element.rb
 - lib/action_form/elements_dsl.rb
 - lib/action_form/input.rb