namespace.rb in phlexi-form-0.3.0

- old
+ new

@@ -1,17 +1,22 @@
 # frozen_string_literal: true
 
 module Phlexi
   module Form
     module Structure
-      # A Namespace maps and object to values, but doesn't actually have a value itself. For
+      # A Namespace maps an object to values, but doesn't actually have a value itself. For
       # example, a `User` object or ActiveRecord model could be passed into the `:user` namespace.
-      # To access the values on a Namespace, the `field` can be called for single values.
       #
-      # Additionally, to access namespaces within a namespace, such as if a `User has_many :addresses` in
-      # ActiveRecord, the `namespace` method can be called which will return another Namespace object and
-      # set the current Namespace as the parent.
+      # To access single values on a Namespace, #field can be used.
+      #
+      # To access nested objects within a namespace, two methods are available:
+      #
+      # 1. #nest_one: Used for single nested objects, such as if a `User belongs_to :profile` in
+      #    ActiveRecord. This method returns another Namespace object.
+      #
+      # 2. #nest_many: Used for collections of nested objects, such as if a `User has_many :addresses` in
+      #    ActiveRecord. This method returns a NamespaceCollection object.
       class Namespace < Structure::Node
         include Enumerable
 
         attr_reader :builder_klass, :object
 
@@ -27,25 +32,25 @@
           create_child(key, attributes.delete(:builder_klass) || builder_klass, object: object, **attributes).tap do |field|
             yield field if block_given?
           end
         end
 
-        def submit_button(key = nil, **attributes, &)
-          field(key || SecureRandom.hex).submit_button_tag(**attributes, &)
+        def submit_button(key = :submit_button, **, &)
+          field(key).submit_button_tag(**, &)
         end
 
         # Creates a `Namespace` child instance with the parent set to the current instance, adds to
         # the `@children` Hash to ensure duplicate child namespaces aren't created, then calls the
         # method on the `@object` to get the child object to pass into that namespace.
         #
         # For example, if a `User#permission` returns a `Permission` object, we could map that to a
         # form like this:
         #
         # ```ruby
-        # Superform :user, object: User.new do |form|
-        #   form.nest_one :permission do |permission|
-        #     form.field :role
+        # Phlexi::Form(User.new, as: :user) do
+        #   nest_one :profile do |profile|
+        #     render profile.field(:gender).input_tag
         #   end
         # end
         # ```
         def nest_one(key, object: nil, &)
           object ||= object_value_for(key: key)
@@ -54,13 +59,13 @@
 
         # Wraps an array of objects in Namespace classes. For example, if `User#addresses` returns
         # an enumerable or array of `Address` classes:
         #
         # ```ruby
-        # Phlexi::Form.new User.new do |form|
-        #   render form.field(:email).input_tag
-        #   render form.field(:name).input_tag
-        #   form.nest_many :addresses do |address|
+        # Phlexi::Form(User.new) do
+        #   render field(:email).input_tag
+        #   render field(:name).input_tag
+        #   nest_many :addresses do |address|
         #     render address.field(:street).input_tag
         #     render address.field(:state).input_tag
         #     render address.field(:zip).input_tag
         #   end
         # end