compony 0.11.8 → 0.11.9

data/lib/compony/component_mixins/default/standalone/standalone_dsl.rb

@@ -16,16 +16,27 @@ module Compony
             @scope = scope
             @scope_args = scope_args
             @verbs = {}
-            @skip_authentication = false
-            @skip_forgery_protection = false
-            @layout = true # can be overriden by false or a string
+            # These default to nil so that, on subsequent `standalone` calls (e.g. subclass overrides), they are stripped
+            # by `compact` and thus do NOT clobber values inherited via `deep_merge!`. The actual defaults are only injected
+            # when `provide_defaults` is true (i.e. the first `standalone` call). This mirrors VerbDsl#to_conf.
+            @skip_authentication = nil
+            @skip_forgery_protection = nil
+            @layout = nil # can be overriden by false or a string
           end
 
+          # Defaults injected only on the first `standalone` call. Kept out of subsequent calls so inherited values survive.
+          DEFAULT_CONFIG = {
+            skip_authentication:     false,
+            skip_forgery_protection: false,
+            layout:                  true
+          }.freeze
+
           # For internal usage only, processes the block and returns a config hash.
           def to_conf(&block)
             evaluate(&block)
             @component = block.binding.eval('self') # Fetches the component holding this DSL call (via the block)
-            return {
+            base_config = @provide_defaults ? DEFAULT_CONFIG.dup : {}
+            return base_config.merge({
               name:                    @name,
               path:                    @path,
               constraints:             @constraints,
@@ -37,13 +48,16 @@ module Compony
               skip_authentication:     @skip_authentication,
               skip_forgery_protection: @skip_forgery_protection,
               layout:                  @layout
-            }.compact
+            }.compact)
           end
 
           protected
 
-          # DSL call for defining a config for a verb. The block runs within the verb DSL, positional and named arguments are passed to the verb DSL.
-          # @param verb [Symbol] The HTTP verb the config is for (e.g. :get, :post etc.)
+          # DSL method. Defines the config for one HTTP verb. The block runs within the verb DSL; positional and named
+          # arguments are forwarded to it. Call at most once per verb per standalone.
+          # @param verb [Symbol] The HTTP verb (one of `:get :head :post :put :delete :connect :options :trace :patch`).
+          # @return [void]
+          # @api public
           # @see Compony::ComponentMixins::Default::Standalone::VerbDsl
           def verb(verb, *, **nargs, &)
             verb = verb.to_sym
@@ -61,22 +75,25 @@ module Compony
             end
           end
 
-          # DSL
-          # Defines that for this component, no authentication should be performed.
+          # DSL method. Disables app authentication for this standalone (an `authorize` block is still mandatory).
+          # @return [void]
+          # @api public
           def skip_authentication!
             @skip_authentication = true
           end
 
-          # DSL
-          # Defines that for this component, no forgery protection (CSRF) should be performed.
+          # DSL method. Disables forgery protection (CSRF) for this standalone's controller action.
+          # @return [void]
+          # @api public
           def skip_forgery_protection!
             @skip_forgery_protection = true
           end
 
-          # DSL
-          # Speficies the Rails layout (under `app/views/layouts`) that should be used to render this component.
-          # Defaults to Rails' default (`layouts/application`) if the method is never called.
-          # @param layout [String] name of the layout as you would give it to a Rails controller's `render` method
+          # DSL method. Sets the Rails layout (under `app/views/layouts`) used to render this component.
+          # Defaults to Rails' default (`layouts/application`) if never called.
+          # @param layout [String,Symbol] Layout name, as passed to a Rails controller's `render`.
+          # @return [void]
+          # @api public
           def layout(layout)
             @layout = layout.to_s
           end

data/lib/compony/component_mixins/default/standalone/verb_dsl.rb

@@ -35,14 +35,22 @@ module Compony
           protected
 
           # DSL
-          # This block is expected to return true if and only if current_ability has the right to access the component over the given verb.
+          # Mandatory. The block must return truthy iff `current_ability` may access the component over this verb;
+          # a falsy result raises `CanCan::AccessDenied`.
+          # @yield Runs in the component's request context; returns truthy to grant access.
+          # @return [void]
+          # @api public
           def authorize(&block)
             @authorize_block = block
           end
 
           # DSL
-          # This is the last step in the life cycle. It may redirect or render. If omitted, the default is standalone_render.
-          # @param format [String, Symbol] Format this block should respond to, defaults to `nil` which means "all other formats".
+          # Last step in the lifecycle. May redirect or render. If omitted, the default is `render_standalone`.
+          # NOTE: overriding `respond` replaces the default, which is where `authorize` is evaluated - re-check authorization yourself.
+          # @param format [String,Symbol,nil] Format this block responds to; `nil` means "all other formats".
+          # @yield Runs in the component's request context; renders or redirects.
+          # @return [void]
+          # @api public
           def respond(format = nil, &block)
             @respond_blocks[format&.to_sym] = block
           end

data/lib/compony/component_mixins/resourceful.rb

@@ -25,8 +25,13 @@ module Compony
         super(*, **nargs, &)
       end
 
+      # @!group DSL
+
       # DSL method
-      # Sets or calculates the model class based on the component's family name
+      # Sets or calculates the model class. Defaults to the component's family name, singularized and constantized.
+      # @param new_data_class [Class,nil] If given, the model class to use (e.g. a {Compony::VirtualModel} subclass).
+      # @return [Class] The resolved data class.
+      # @api public
       def data_class(new_data_class = nil)
         @data_class ||= new_data_class || family_name.singularize.camelize.constantize
       end
@@ -38,27 +43,32 @@ module Compony
       protected
 
       # DSL method
-      # Sets a default load_data block for all standalone paths and verbs.
-      # Can be overwritten for a specific path and verb in the
-      # {Compony::ComponentMixins::Default::Standalone::VerbDsl}.
-      # The block is expected to assign `@data`.
+      # Sets the default `load_data` block for all standalone paths and verbs (overridable per verb in the VerbDsl).
+      # Runs before authorization. The block is expected to assign `@data`.
+      # @yield Runs in the component's request context; must assign `@data`.
+      # @return [void]
+      # @api public
       # @see Compony::ComponentMixins::Default::Standalone::VerbDsl#load_data
       def load_data(&block)
         @global_load_data_block = block
       end
 
       # DSL method
-      # Runs after loading data and before authorization for all standalone paths and verbs.
-      # Example use case: if `load_data` produced an AR collection proxy, can still refine result here before `to_sql` is called.
+      # Runs after `load_data` and before authorization for all standalone paths and verbs.
+      # Example: refine an AR collection produced by `load_data` before it is read.
+      # @yield Runs in the component's request context; may refine `@data`.
+      # @return [void]
+      # @api public
       def after_load_data(&block)
         @global_after_load_data_block = block
       end
 
       # DSL method
-      # Sets a default default assign_attributes block for all standalone paths and verbs.
-      # Can be overwritten for a specific path and verb in the
-      # {Compony::ComponentMixins::Default::Standalone::VerbDsl}.
-      # The block is expected to assign suitable `params` to attributes of `@data`.
+      # Sets the default `assign_attributes` block for all standalone paths and verbs (overridable per verb in the VerbDsl).
+      # The block is expected to assign validated `params` to attributes of `@data`.
+      # @yield Runs in the component's request context; assigns params onto `@data`.
+      # @return [void]
+      # @api public
       # @see Compony::ComponentMixins::Default::Standalone::VerbDsl#assign_attributes
       def assign_attributes(&block)
         @global_assign_attributes_block = block
@@ -66,16 +76,20 @@ module Compony
 
       # DSL method
       # Runs after `assign_attributes` and before `store_data` for all standalone paths and verbs.
-      # Example use case: prefilling some fields for a form
+      # Example: prefill or derive fields before validation.
+      # @yield Runs in the component's request context; may mutate `@data`.
+      # @return [void]
+      # @api public
       def after_assign_attributes(&block)
         @global_after_assign_attributes_block = block
       end
 
       # DSL method
-      # Sets a default store_data block for all standalone paths and verbs.
-      # Can be overwritten for a specific path and verb in the
-      # {Compony::ComponentMixins::Default::Standalone::VerbDsl}.
-      # The block is expected save `@data` to the database.
+      # Sets the default `store_data` block for all standalone paths and verbs (overridable per verb in the VerbDsl).
+      # The block is expected to persist `@data` (override e.g. for virtual models or custom persistence).
+      # @yield Runs in the component's request context; persists `@data`.
+      # @return [void]
+      # @api public
       # @see Compony::ComponentMixins::Default::Standalone::VerbDsl#store_data
       def store_data(&block)
         @global_store_data_block = block

data/lib/compony/components/destroy.rb

@@ -78,21 +78,41 @@ module Compony
         end
       end
 
+      # @!group DSL
+
       # DSL method
-      # Sets a block that is evaluated with backfire in the successful case after storing, but before responding.
+      # Sets an optional hook evaluated (with backfire) after a successful destroy but before responding.
+      # Suitable for post-destroy side effects (like an `after_destroy` that only fires when this component destroyed the record).
+      # Do not redirect or render here - use {#on_destroyed_respond} / {#on_destroyed_redirect_path} for that.
+      # @yield Runs in the component's request context after `@data` was destroyed.
+      # @return [void]
+      # @api public
       def on_destroyed(&block)
         @on_destroyed_block = block
       end
 
       # DSL method
+      # Overrides the response issued after a successful destroy. The default shows a flash and redirects to
+      # {#on_destroyed_redirect_path} with HTTP 303 (forces a GET, required for Turbo). If you override this,
+      # {#on_destroyed_redirect_path} is no longer called.
+      # @yield Runs in the component's request context; expected to render or redirect.
+      # @return [void]
+      # @api public
       def on_destroyed_respond(&block)
         @on_destroyed_respond_block = block
       end
 
       # DSL method
+      # Overrides the redirect target used by the default {#on_destroyed_respond} (keeping the default flash).
+      # Defaults to the owner's Show (if owned) or the data's Index.
+      # @yield Runs in the component's request context; expected to return a Rails path (e.g. via `Compony.path`).
+      # @return [void]
+      # @api public
       def on_destroyed_redirect_path(&block)
         @on_destroyed_redirect_path_block = block
       end
+
+      # @!endgroup
     end
   end
 end

data/lib/compony/components/edit.rb

@@ -90,26 +90,50 @@ module Compony
         end
       end
 
+      # @!group DSL
+
       # DSL method
-      # Sets a block that is evaluated with backfire in the successful case after storing, but before responding.
+      # Sets an optional hook evaluated (with backfire) after a successful update but before responding.
+      # Suitable for post-update side effects (like an `after_update` that only fires when this component updated the record).
+      # Do not redirect or render here - use {#on_updated_respond} / {#on_updated_redirect_path} for that.
+      # @yield Runs in the component's request context after `@data` was saved successfully.
+      # @return [void]
+      # @api public
       def on_updated(&block)
         @on_updated_block = block
       end
 
       # DSL method
+      # Overrides the response issued after a successful update. The default shows a flash and redirects to
+      # {#on_updated_redirect_path}. If you override this, {#on_updated_redirect_path} is no longer called.
+      # @yield Runs in the component's request context; expected to render or redirect.
+      # @return [void]
+      # @api public
       def on_updated_respond(&block)
         @on_updated_respond_block = block
       end
 
       # DSL method
+      # Overrides the redirect target used by the default {#on_updated_respond} (keeping the default flash).
+      # Defaults to the data's Show, the owner's Show, or the data's Index.
+      # @yield Runs in the component's request context; expected to return a Rails path (e.g. via `Compony.path`).
+      # @return [void]
+      # @api public
       def on_updated_redirect_path(&block)
         @on_updated_redirect_path_block = block
       end
 
       # DSL method
+      # Overrides the response issued when the update failed (`@update_succeeded` is not true).
+      # The default logs the errors with level `warn` and re-renders the component with HTTP 422 so the form shows errors.
+      # @yield Runs in the component's request context; expected to render or redirect.
+      # @return [void]
+      # @api public
       def on_update_failed(&block)
         @on_update_failed_block = block
       end
+
+      # @!endgroup
     end
   end
 end

data/lib/compony/components/form.rb

@@ -52,7 +52,13 @@ module Compony
         end
       end
 
-      # DSL method, use to set the form content
+      # @!group DSL
+
+      # DSL method, use to set the form content (mandatory).
+      # The block holds the form inputs and is instance-exec'd in the form's request context where `field`, `pw_field` and `f` are available.
+      # @yield Builds the form body using Dyny + the form field helpers.
+      # @return [Proc,nil] When called without a block, returns the stored block.
+      # @api public
       def form_fields(&block)
         return @form_fields unless block_given?
         @form_fields = block
@@ -97,9 +103,13 @@ module Compony
         @controller = nil
       end
 
-      # Called inside the form_fields block. This makes the method `field` available in the block.
-      # See also notes for `with_simpleform`.
-      # If multilang is true, a suffixed field is generated for every available locale (useful with gem "mobility"). Render the array as you wish.
+      # DSL method (inside `form_fields`). Renders a simple_form input inferred from the model field `name`.
+      # Respects per-field CanCanCan authorization; skipped fields render nothing.
+      # @param name [Symbol,String] The model field (use the association name, not the `_id`, for associations).
+      # @param multilang [Boolean] If true, generates one suffixed input per available locale and returns the array (useful with the "mobility" gem).
+      # @param input_opts [Hash] Passed to simple_form. Notable keys: `as:` (input type), `hidden: true`, `autofocus:`.
+      # @return [String,Array<String>] The input HTML (array when `multilang`).
+      # @api public
       def field(name, multilang: false, **input_opts)
         fail("The `field` method may only be called inside `form_fields` for #{inspect}.") unless @simpleform
 
@@ -134,9 +144,12 @@ module Compony
         end
       end
 
-      # Called inside the form_fields block. This makes the method pw_field available in the block.
-      # This method should be called for the fields :password and :password_confirmation
-      # Note that :hidden is not supported here, as this would make no sense in conjunction with :password or :password_confirmation.
+      # DSL method (inside `form_fields`). Renders a password input; should be used for `:password` and `:password_confirmation`.
+      # Checks the `:set_password` CanCanCan ability; `:hidden` is intentionally unsupported here.
+      # @param name [Symbol,String] The password field name.
+      # @param input_opts [Hash] Passed to simple_form.
+      # @return [String,nil] The input HTML, or nil if not permitted.
+      # @api public
       def pw_field(name, **input_opts)
         fail("The `pw_field` method may only be called inside `form_fields` for #{inspect}.") unless @simpleform
         name = name.to_sym
@@ -156,8 +169,10 @@ module Compony
         return @simpleform.input name, **input_opts
       end
 
-      # Called inside the form_fields block. This makes the method `f` available in the block.
-      # See also notes for `with_simpleform`.
+      # DSL method (inside `form_fields`). Returns the underlying simple_form builder, e.g. for `f.rich_text_area`
+      # or `f.simple_fields_for` (nested attributes).
+      # @return [SimpleForm::FormBuilder] The simple_form builder for the current form.
+      # @api public
       def f
         fail("The `f` method may only be called inside `form_fields` for #{inspect}.") unless @simpleform
         return @simpleform
@@ -168,27 +183,41 @@ module Compony
         Compony::ModelFields::Anchormodel.collect(...)
       end
 
-      # DSL method, disables all inputs
+      # DSL method, disables all inputs.
+      # @return [void]
+      # @api public
       def disable!
         @form_disabled = true
       end
 
-      # DSL method, allows to customize parameters given to simple_form_for
+      # DSL method, customizes the parameters given to `simple_form_for`.
+      # @param new_form_params [Hash] Extra kwargs forwarded to `simple_form_for`.
+      # @return [void]
+      # @api public
       def form_params(**new_form_params)
         @form_params = new_form_params
       end
 
+      # @!endgroup
+
       protected
 
-      # DSL method, adds a new line to the schema whitelisting a single param inside the schema's wrapper
-      # The block should be something like `str? :foo` and will run in a Schemacop3 context.
+      # @!group DSL
+
+      # DSL method, adds a Schemacop3 line whitelisting param(s) inside the schema's wrapper.
+      # @yield Runs in a Schemacop3 context, e.g. `str? :foo`.
+      # @return [void]
+      # @api public
       def schema_line(&block)
         @schema_lines_for_data << proc { |_data, _controller| block }
       end
 
-      # DSL method, adds a new field to the schema whitelisting a single field of data_class
-      # This auto-generates the correct schema line for the field.
-      # If multilang is true, a suffixed field is generated for every available locale (useful with gem "mobility")
+      # DSL method, whitelists a single field of `data_class` in the param schema, auto-generating the correct schema line.
+      # Respects per-field CanCanCan authorization.
+      # @param field_name [Symbol,String] The model field (association name, not `_id`, for associations).
+      # @param multilang [Boolean] If true, whitelists one suffixed field per available locale (useful with the "mobility" gem).
+      # @return [void]
+      # @api public
       def schema_field(field_name, multilang: false)
         if multilang
           I18n.available_locales.each { |locale| schema_field("#{field_name}_#{locale}") }
@@ -209,8 +238,10 @@ module Compony
         end
       end
 
-      # DSL method, adds a new password field to the schema whitelisting
-      # This checks for the permission :set_password and auto-generates the correct schema line for the field.
+      # DSL method, whitelists a password param in the schema (checks the `:set_password` permission).
+      # @param field_name [Symbol,String] The password field name.
+      # @return [void]
+      # @api public
       def schema_pw_field(field_name)
         # This runs upon component setup.
         @schema_lines_for_data << proc do |data, controller|
@@ -226,12 +257,19 @@ module Compony
         end
       end
 
-      # DSL method, mass-assigns schema fields
+      # DSL method, whitelists several fields at once (see {#schema_field}).
+      # @param field_names [Array<Symbol,String>] The model fields to whitelist.
+      # @return [void]
+      # @api public
       def schema_fields(*field_names)
         field_names.each { |field_name| schema_field(field_name) }
       end
 
-      # DSL method, use to replace the form's schema and wrapper key for a completely manual schema
+      # DSL method, replaces the form's schema and wrapper key with a completely manual Schemacop3 schema.
+      # @param wrapper_key [Symbol,String] The top-level params wrapper key (e.g. the model's singular name).
+      # @yield Runs in a Schemacop3 context defining the wrapped params.
+      # @return [void]
+      # @api public
       def schema(wrapper_key, &block)
         if block_given?
           @schema_wrapper_key = wrapper_key
@@ -241,10 +279,14 @@ module Compony
         end
       end
 
-      # DSL method, skips adding autofocus to the first field
+      # DSL method, skips adding autofocus to the first field.
+      # @return [void]
+      # @api public
       def skip_autofocus
         @skip_autofocus = true
       end
+
+      # @!endgroup
     end
   end
 end

data/lib/compony/components/list.rb

@@ -163,7 +163,7 @@ module Compony
       end
 
       # DSL method
-      # If a block is given: Enters the DSL where row intents can be added or removed (use from {Component#setup} within the component).
+      # If a block is given: Enters the DSL where row intents can be added or removed (use from {Compony::Component.setup} within the component).
       # If no block is given: Builds the declared intents for the given record and returns them (use in `content` or `before_render`, pass kwarg `:data`).
       def row_intents(**intent_opts, &block)
         if block_given?

data/lib/compony/components/new.rb

@@ -78,26 +78,50 @@ module Compony
         end
       end
 
+      # @!group DSL
+
       # DSL method
-      # Sets a block that is evaluated with backfire in the successful case after storing, but before responding.
+      # Sets an optional hook evaluated (with backfire) after a successful create but before responding.
+      # Suitable for post-create side effects (like an `after_create` that only fires when this component created the record).
+      # Do not redirect or render here - use {#on_created_respond} / {#on_created_redirect_path} for that.
+      # @yield Runs in the component's request context after `@data` was saved successfully.
+      # @return [void]
+      # @api public
       def on_created(&block)
         @on_created_block = block
       end
 
       # DSL method
+      # Overrides the response issued after a successful create. The default shows a flash and redirects to
+      # {#on_created_redirect_path}. If you override this, {#on_created_redirect_path} is no longer called.
+      # @yield Runs in the component's request context; expected to render or redirect.
+      # @return [void]
+      # @api public
       def on_created_respond(&block)
         @on_created_respond_block = block
       end
 
       # DSL method
+      # Overrides the redirect target used by the default {#on_created_respond} (keeping the default flash).
+      # Defaults to the data's Show, the owner's Show, or the data's Index.
+      # @yield Runs in the component's request context; expected to return a Rails path (e.g. via `Compony.path`).
+      # @return [void]
+      # @api public
       def on_created_redirect_path(&block)
         @on_created_redirect_path_block = block
       end
 
       # DSL method
+      # Overrides the response issued when the create failed (`@create_succeeded` is not true).
+      # The default logs the errors with level `warn` and re-renders the component with HTTP 422 so the form shows errors.
+      # @yield Runs in the component's request context; expected to render or redirect.
+      # @return [void]
+      # @api public
       def on_create_failed_respond(&block)
         @on_create_failed_respond_block = block
       end
+
+      # @!endgroup
     end
   end
 end

data/lib/compony/components/with_form.rb

@@ -22,8 +22,13 @@ module Compony
         )
       end
 
+      # @!group DSL
+
       # DSL method
-      # Sets or returns the previously set submit verb
+      # Sets or returns the HTTP verb the twinned form submits with (`:post` for New, `:patch` for Edit).
+      # @param new_submit_verb [Symbol,nil] If given, sets the submit verb; must be a known HTTP verb.
+      # @return [Symbol] The (possibly just set) submit verb.
+      # @api public
       def submit_verb(new_submit_verb = nil)
         if new_submit_verb.present?
           new_submit_verb = new_submit_verb.to_sym
@@ -35,13 +40,19 @@ module Compony
       end
 
       # DSL method
-      # Overrides the form comp class that is instanciated to render the form
+      # Overrides the Form component class instantiated by {#form_comp} (defaults to the same-family `Form`).
+      # @param new_form_comp_class [Class,nil] The Form component class to use.
+      # @return [Class,nil] The configured form component class.
+      # @api public
       def form_comp_class(new_form_comp_class = nil)
         @form_comp_class ||= new_form_comp_class
       end
 
       # DSL method
-      # Sets and gets the form's cancancan action (for cancancan's accessible_attributes)
+      # Sets and gets the form's CanCanCan action, used for per-field `permitted_attributes`. Pass `nil` to disable per-field auth.
+      # @param new_form_cancancan_action [Symbol,nil] The CanCanCan action (e.g. `:edit`); omit to read the current value.
+      # @return [Symbol,nil] The configured CanCanCan action.
+      # @api public
       def form_cancancan_action(new_form_cancancan_action = :missing)
         if new_form_cancancan_action != :missing
           @form_cancancan_action = new_form_cancancan_action
@@ -50,11 +61,15 @@ module Compony
       end
 
       # DSL method
-      # Overrides the submit path which would otherwise default to this component
-      # This takes a block that will be called and given a controller
+      # Overrides the submit path, which otherwise defaults to this component's own path.
+      # @yield [controller] Called with the controller; expected to return the Rails path the form submits to.
+      # @return [void]
+      # @api public
       def submit_path(&new_submit_path_block)
         @submit_path_block = new_submit_path_block
       end
+
+      # @!endgroup
     end
   end
 end

data/lib/compony/intent.rb

@@ -144,7 +144,7 @@ module Compony
     # Renders this intent into a button defined by `style`.
     # @param controller [ApplicationController] The controller from the request context, needed to render the button.
     # @param parent_comp [Compony::Component] If called from within a component, pass the component to inform the button that it is nested within.
-    # @param style [Symbol] If present, overrides the class of the generated  button component, defaults to {Compony#default_button_style}.
+    # @param style [Symbol] If present, overrides the class of the generated  button component, defaults to {Compony.default_button_style}.
     # @param button_arg_overrides [Hash] Any further kwargs are passed to the button component's initializer.
     def render(controller, parent_comp = nil, style: nil, **button_arg_overrides)
       # Abort if not authorized