compony 0.7.1 → 0.8.0

data/doc/top-level-namespace.html

@@ -102,7 +102,7 @@
 </div>
 
       <div id="footer">
-  Generated on Thu Nov 20 12:44:23 2025 by
+  Generated on Thu Nov 27 16:02:21 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.3.5).
 </div>

data/lib/compony/component.rb

@@ -20,24 +20,14 @@ module Compony
       setup_blocks << block
     end
 
-    # Returns the name of the module constant (=family) of this component. Do not override.
-    def self.family_cst
-      module_parent.to_s.demodulize.to_sym
-    end
-
     # Returns the family name
     def self.family_name
-      family_cst.to_s.underscore
-    end
-
-    # Returns the name of the class constant of this component. Do not override.
-    def self.comp_cst
-      name.demodulize.to_sym
+      module_parent.to_s.demodulize.underscore
     end
 
     # Returns the component name
     def self.comp_name
-      comp_cst.to_s.underscore
+      name.demodulize.underscore
     end
 
     def initialize(parent_comp = nil, index: 0, **comp_opts)
@@ -48,11 +38,12 @@ module Compony
       @before_render_blocks = NaturalOrdering.new
       @content_blocks = NaturalOrdering.new
       @actions = NaturalOrdering.new
+      @exposed_intent_blocks = []
       @skipped_actions = Set.new
       @path_block = proc do |model = nil, *args_for_path_helper, standalone_name: nil, **kwargs_for_path_helper|
         kwargs_for_path_helper.merge!(id: model.id) if model
         next Rails.application.routes.url_helpers.send(
-          "#{Compony.path_helper_name(comp_cst, family_cst, standalone_name&.to_sym)}_path",
+          "#{path_helper_name(standalone_name)}_path",
           *args_for_path_helper,
           **kwargs_for_path_helper
         )
@@ -114,21 +105,16 @@ module Compony
     end
 
     # Instanciate a component with `self` as a parent
-    def sub_comp(component_class, **comp_opts)
-      sub = component_class.new(self, index: @sub_comps.count, **comp_opts)
+    def sub_comp(*, **comp_opts)
+      intent = Compony.intent(*)
+      sub = intent.comp(self, index: @sub_comps.count, **comp_opts)
       @sub_comps << sub
       return sub
     end
 
-    # Returns the name of the module constant (=family) of this component. Do not override.
-    delegate :family_cst, to: :class
-
     # Returns the family name
     delegate :family_name, to: :class
 
-    # Returns the name of the class constant of this component. Do not override.
-    delegate :comp_cst, to: :class
-
     # Returns the component name
     delegate :comp_name, to: :class
 
@@ -227,33 +213,18 @@ module Compony
     end
 
     # DSL method
-    # Adds or replaces an action (for action buttons)
-    # If before: is specified, will insert the action before the named action. When replacing, an element keeps its position unless before: is specified.
-    def action(action_name, before: nil, &block)
-      @actions.natural_push(action_name, block, before:)
-    end
-
-    # DSL method
-    # Marks an action for skip
-    def skip_action(action_name)
-      @skipped_actions << action_name.to_sym
-    end
-
-    # Used to render all actions of this component, each button wrapped in a div with the specified class
-    def render_actions(controller, wrapper_class: '', action_class: '')
-      h = controller.helpers
-      h.content_tag(:div, class: wrapper_class) do
-        button_htmls = @actions.map do |action|
-          next if @skipped_actions.include?(action.name)
-          Compony.with_button_defaults(feasibility_action: action.name.to_sym) do
-            action_button = action.payload.call(controller)
-            next unless action_button
-            button_html = action_button.render(controller)
-            next if button_html.blank?
-            h.content_tag(:div, button_html, class: action_class)
-          end
-        end
-        next h.safe_join button_htmls
+    # If a block is given: Enters the DSL where exposed intents can be added or removed (use from {Component#setup} within the component).
+    # If no block is given: Builds the declared intents and returns them (use from a {RequestContest} outside the component).
+    def exposed_intents(&block)
+      if block_given?
+        # Enter DSL
+        @exposed_intent_blocks << block
+      else
+        # Build the declared intents
+        return @exposed_intents if @exposed_intents
+        @exposed_intents = NaturalOrdering.new
+        @exposed_intent_blocks.each { |block| ExposedIntentsDsl.new(@exposed_intents).evaluate(&block) } # alters @exposed_intents
+        return @exposed_intents.map!(&:payload)
       end
     end
 

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

@@ -32,8 +32,8 @@ module Compony
               scope:                   @scope,
               scope_args:              @scope_args,
               verbs:                   @verbs,
-              rails_action_name:       Compony.rails_action_name(comp_name, family_name, @name),
-              path_helper_name:        Compony.path_helper_name(comp_name, family_name, @name),
+              rails_action_name:       rails_action_name(@name),
+              path_helper_name:        path_helper_name(@name),
               skip_authentication:     @skip_authentication,
               skip_forgery_protection: @skip_forgery_protection,
               layout:                  @layout

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

@@ -123,6 +123,22 @@ module Compony
           @standalone_configs = {}
         end
 
+        # Returns the name of the ComponyController action for this component.<br>
+        # Optionally can pass a name for extra standalone configs.
+        # @param name [String,Symbol] If referring to an extra standalone entrypoint, specify its name using this param.
+        # @see Compony#path
+        def rails_action_name(name = nil)
+          [name.presence, comp_name, family_name].compact.join('_')
+        end
+
+        # Returns the name of the Rails URL helper returning the path to this component.<br>
+        # Optionally can pass a name for extra standalone configs.
+        # @param name [String,Symbol] If referring to an extra standalone entrypoint, specify its name using this param.
+        # @see Compony#path
+        def path_helper_name(...)
+          "#{rails_action_name(...)}_comp"
+        end
+
         private
 
         def init_standalone

data/lib/compony/component_mixins/resourceful.rb

@@ -28,7 +28,7 @@ module Compony
       # DSL method
       # Sets or calculates the model class based on the component's family name
       def data_class(new_data_class = nil)
-        @data_class ||= new_data_class || family_cst.to_s.singularize.constantize
+        @data_class ||= new_data_class || family_name.singularize.camelize.constantize
       end
 
       # Instanciate a component with `self` as a parent and render it, having it inherit the resource

data/lib/compony/components/buttons/css_button.rb

@@ -0,0 +1,32 @@
+module Compony
+  module Components
+    module Buttons
+      class CssButton < Link
+        def prepare_opts!
+          super
+          css = [
+            'display:inline-block',
+            'padding:.15rem .35rem',
+            'text-decoration:none',
+            'border-radius:6px',
+            'font-size: 13.333px'
+          ]
+          if @comp_opts[:class]&.split&.include?('disabled')
+            css += [
+              'background:#e9ecef',
+              'color:#6c757d',
+              'cursor: default'
+            ]
+          else
+            css += [
+              'background:#eaeaee',
+              'color:#000000',
+              'border:1px solid #90909e'
+            ]
+          end
+          @comp_opts[:style] = "#{css.join(';')};"
+        end
+      end
+    end
+  end
+end

data/lib/compony/components/buttons/link.rb

@@ -0,0 +1,31 @@
+module Compony
+  module Components
+    module Buttons
+      class Link < Component
+        setup do
+          before_render do
+            prepare_opts!
+          end
+
+          content do
+            concat link_to(@label, @href, **@comp_opts)
+          end
+        end
+
+        protected
+
+        def prepare_opts!
+          @label = @comp_opts.delete(:label).presence
+          @href = @comp_opts.delete(:href).presence || 'javascript:void(0)'
+          @method = @comp_opts.delete(:method).presence
+          if @method && @method.to_sym != :get
+            @comp_opts[:data] = { turbo_method: @method }.merge(@comp_opts[:data] || {})
+          end
+          if @comp_opts[:class]&.split&.include?('disabled')
+            @comp_opts[:style] = 'text-decoration:line-through;cursor: default;color: #6c757d;'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/compony/components/destroy.rb

@@ -32,10 +32,10 @@ module Compony
 
         content :confirm_button, hidden: true do
           div do
-            concat compony_button(comp_cst,
-                                  @data,
-                                  label:  I18n.t('compony.components.destroy.confirm_button'),
-                                  method: :delete)
+            concat render_intent(comp_name,
+                                 @data,
+                                 label:  I18n.t('compony.components.destroy.confirm_button'),
+                                 method: :delete)
           end
         end
 
@@ -44,9 +44,10 @@ module Compony
           content :confirm_button
         end
 
-        action :back_to_owner do
-          next if data_class.owner_model_attr.blank?
-          Compony.button(:show, @data.send(data_class.owner_model_attr), icon: :xmark, color: :secondary, label: I18n.t('compony.cancel'))
+        exposed_intents do
+          if data_class.owner_model_attr
+            add :show, @data.send(data_class.owner_model_attr), icon: :xmark, color: :secondary, label: I18n.t('compony.cancel'), name: :back_to_owner
+          end
         end
 
         store_data do
@@ -72,7 +73,7 @@ module Compony
           if data_class.owner_model_attr.present?
             Compony.path(:show, @data.send(data_class.owner_model_attr))
           else
-            Compony.path(:index, family_cst)
+            Compony.path(:index, family_name)
           end
         end
       end

data/lib/compony/components/edit.rb

@@ -33,9 +33,10 @@ module Compony
 
         form_cancancan_action :edit
 
-        action :back_to_owner do
-          next if data_class.owner_model_attr.blank?
-          Compony.button(:show, @data.send(data_class.owner_model_attr), icon: :xmark, color: :secondary, label: I18n.t('compony.cancel'))
+        exposed_intents do
+          if data_class.owner_model_attr
+            add :show, @data.send(data_class.owner_model_attr), icon: :xmark, color: :secondary, label: I18n.t('compony.cancel'), name: :back_to_owner
+          end
         end
 
         content :label do
@@ -78,7 +79,7 @@ module Compony
           elsif data_class.owner_model_attr.present?
             Compony.path(:show, @data.send(data_class.owner_model_attr))
           else
-            Compony.path(:index, family_cst)
+            Compony.path(:index, family_name)
           end
         end
 

data/lib/compony/components/form.rb

@@ -25,9 +25,15 @@ module Compony
 
         # Override this to provide a custom submit button
         content :submit_button, hidden: true do
+          # Fake submit button rendered by a button component and submitting the form via JS:
           concat Compony.button_component_class.new(
-            label: @submit_label || I18n.t('compony.components.form.submit'), icon: 'arrow-right', type: :submit
+            label:   @submit_label || I18n.t('compony.components.form.submit'),
+            icon:    'arrow-right',
+            href:    '#',
+            onclick: "this.closest('form').requestSubmit(); return false;"
           ).render(controller)
+          # Real (but hidden) submit button to allow Return to submit:
+          button type: :submit, hidden: true
         end
 
         # Override this to provide additional submit buttons.

data/lib/compony/components/index.rb

@@ -18,9 +18,9 @@ module Compony
           @data = data_class.accessible_by(controller.current_ability)
         end
 
-        action :new do
+        exposed_intents do
           if Compony.comp_class_for(:new, data_class)
-            Compony.button(:new, data_class.model_name.plural)
+            add :new, data_class.model_name.plural, name: :new
           end
         end
 

data/lib/compony/components/list.rb

@@ -168,7 +168,7 @@ module Compony
         unless block_given?
           block = proc do |record|
             next if Compony.comp_class_for(name, record).nil?
-            compony_button(name, record, **button_opts)
+            render_intent(name, record, **{ label: { format: :short } }.deep_merge(button_opts))
           end
         end
         @row_actions.natural_push(name, block, **)
@@ -275,9 +275,9 @@ module Compony
         end
 
         # Default row actions (use override or skip_row_action to prevent)
-        row_action(:show)
-        row_action(:edit)
-        row_action(:destroy)
+        row_action(:show) if Compony.comp_class_for(:show, data_class)
+        row_action(:edit) if Compony.comp_class_for(:edit, data_class)
+        row_action(:destroy) if Compony.comp_class_for(:destroy, data_class)
 
         before_render do
           process_data!(controller)

data/lib/compony/components/new.rb

@@ -69,7 +69,7 @@ module Compony
           elsif data_class.owner_model_attr.present?
             Compony.path(:show, @data.send(data_class.owner_model_attr))
           else
-            Compony.path(:index, family_cst)
+            Compony.path(:index, family_name)
           end
         end
 

data/lib/compony/components/show.rb

@@ -16,20 +16,17 @@ module Compony
         label(:short) { |_| I18n.t('compony.components.show.label.short') }
         icon { :eye }
 
-        action :back_to_owner do
-          next if data_class.owner_model_attr.blank?
-          Compony.button(:show, @data.send(data_class.owner_model_attr), icon: :'arrow-left', color: :secondary, label: I18n.t('compony.back'))
-        end
+        exposed_intents do
+          if data_class.owner_model_attr
+            add :show, @data.send(data_class.owner_model_attr), icon: :xmark, color: :secondary, label: I18n.t('compony.back'), name: :back_to_owner
+          end
 
-        if Compony.comp_class_for(:edit, family_cst)
-          action :edit do
-            Compony.button(:edit, @data, label_opts: { format: :short })
+          if Compony.comp_class_for(:edit, family_name)
+            add :edit, @data, label: { format: :short }, name: :edit
           end
-        end
 
-        if Compony.comp_class_for(:destroy, family_cst)
-          action :destroy do
-            Compony.button(:destroy, @data, label_opts: { format: :short })
+          if Compony.comp_class_for(:destroy, family_name)
+            add :destroy, @data, label: { format: :short }, name: :destroy
           end
         end
 

data/lib/compony/components/with_form.rb

@@ -13,7 +13,7 @@ module Compony
       # Returns an instance of the form component responsible for rendering the form.
       # Feel free to override this in subclasses.
       def form_comp
-        @form_comp ||= (form_comp_class || Compony.comp_class_for!(:form, family_cst)).new(
+        @form_comp ||= (form_comp_class || Compony.comp_class_for!(:form, family_name)).new(
           self,
           submit_verb:,
           # If applicable, Rails adds the route keys automatically, thus, e.g. :id does not need to be passed here, as it comes from the request.

data/lib/compony/exposed_intents_dsl.rb

@@ -0,0 +1,29 @@
+module Compony
+  class ExposedIntentsDsl < Dslblend::Base
+    def initialize(previously_exposed_intents)
+      super()
+      @exposed_intents = previously_exposed_intents
+    end
+
+    protected
+
+    # DSL method
+    # Adds or replaces an intent to those exposed by the component based on the intent name (override the name if you need to avoid a naming collision).
+    # Intents specified this way can be retrieved and rendered by the parent component or by calling `root_intents` in case of standalone access.
+    # @param [Symbol] before If specified, will insert the intent before the other.  When replacing, an element keeps its position unless `before:`` is passed.
+    def add(*, before: nil, **)
+      intent = Compony.intent(*, **)
+      @exposed_intents.natural_push(intent.name, intent, before:)
+    end
+
+    # DSL method
+    # Removes an exposed intent previously added to this component
+    # @param [Symbol] intent_name The name of the intent to remove
+    def remove(intent_name)
+      existing_index = @exposed_intents.find_index { |el| el.name == intent_name.to_sym }
+      if existing_index
+        @exposed_intents.delete_at(existing_index)
+      end
+    end
+  end
+end

data/lib/compony/intent.rb

@@ -0,0 +1,145 @@
+module Compony
+  # @api description
+  # An Intent is a a gateway to a component, along with relevant context, such as the comp and family, perhaps a resource, standalone name, feasibility etc.
+  # The class provides tooling used by various Compony helpers used to point to other components in some way.
+  class Intent
+    attr_reader :comp_class
+    attr_reader :data
+
+    # @param comp_name_or_cst_or_class [String,Symbol,Class] The component that should be loaded,
+    #                                                        for instance `ShowForAll`, `'ShowForAll'` or `:show_for_all`,
+    #                                                        or can also pass a component class (such as Components::Users::Show)
+    # @param model_or_family_name_or_cst [String,Symbol,ApplicationRecord] Either the family that contains the requested component, or an
+    #                                                                      instance implementing `model_name` from which the family name is auto-generated.
+    #                                                                      Examples: `Users`, `'Users'`, `:users`, `User.first`
+    # @param standalone_name [Symbol] If given, will override the standalone name for all `path` calls for this intent instance.
+    # @param name [Symbol] If given, will override the name of this intent. Defaults to component and family name joined by underscore.
+    # @param label [String,Hash] If given, will be used for generating the label. If Hash, is given as options to {Intent#label}.
+    # @param path [String,Hash] If given, will be used for generating the path. If Hash, is given as options to {Intent#path}.
+    # @param data [ApplicationRecord,Object] If given, the target component will be instanciated with this argument. Omit if your second pos arg is a model.
+    # @param data_class [Class] If given, the target component will be instanciated with this argument.
+    # @param feasibility_target [ApplicationRecord] If given, will override the feasibility target (prevention framework)
+    # @param feasibility_action [ApplicationRecord] If given, will override the feasibility action (prevention framework)
+    def initialize(comp_name_or_cst_or_class,
+                   model_or_family_name_or_cst = nil,
+                   standalone_name: nil,
+                   name: nil,
+                   label: nil,
+                   path: nil,
+                   method: nil,
+                   data: nil,
+                   data_class: nil,
+                   feasibility_target: nil,
+                   feasibility_action: nil,
+                   **custom_args)
+      # Check for model / data
+      @data = data
+      @data ||= model_or_family_name_or_cst if model_or_family_name_or_cst.respond_to?(:model_name)
+      @data_class = data_class
+
+      # Figure out comp_class
+      if comp_name_or_cst_or_class.is_a?(Class) && (comp_name_or_cst_or_class <= Compony::Component)
+        # A class was given as the first argument
+        @comp_class = comp_name_or_cst_or_class
+      else
+        # Build the constant from the first two arguments
+        family_underscore_str = @data.respond_to?(:model_name) ? @data.model_name.plural : model_or_family_name_or_cst.to_s.underscore
+        constant_str = "::Components::#{family_underscore_str.camelize}::#{comp_name_or_cst_or_class.to_s.camelize}"
+        @comp_class = constant_str.constantize
+      end
+
+      # Store further arguments
+      @name = name&.to_sym
+      @standalone_name = standalone_name
+      @label = label.is_a?(String) ? label : nil
+      @label_opts = label.is_a?(Hash) ? label : {}
+      @path = path.is_a?(String) ? path : nil
+      @path_opts = path.is_a?(Hash) ? path : {}
+      @method = method&.to_sym
+      @feasibility_target = feasibility_target
+      @feasibility_action = feasibility_action
+      @custom_args = custom_args
+    end
+
+    # Returns true for things like User.first, but false for things like :users or User
+    def model?
+      @model = @data.respond_to?(:model_name) && !@data.is_a?(Class) if @model.nil?
+      return @model
+    end
+
+    # Instanciates the component and returns the instance. If `data` and/or `data_class` were specified when instantiating this intent, they are passed.
+    # All given arguments will be given to the component's initializer, also overriding `data` and `data_class` if present.
+    def comp(*, **)
+      return @comp ||= @comp_class.new(*, data: @data, data_class: @data_class, **)
+    end
+
+    # Returns the path to the component.
+    # Additional arguments are passed to the component's path block, which typically passes them to the Rails path helper.
+    # @param model [ApplicationRecord] If given and non-nil, will override the model passed to the component's path block
+    # @param standalone_name [Symbol] If given and non-nil, will override the `standalone_name` passed to the component's path block
+    def path(model = nil, *, standalone_name: nil, **path_opt_overrides)
+      path_opts = @path_opts.deep_merge(path_opt_overrides)
+      comp.path(model || (model? ? @data : nil), standalone_name: standalone_name || @standalone_name, **path_opts)
+    end
+
+    # Returns a name for this intent, consisting of comp and family name. Can be overriden in the constructor.
+    # Example: :show_users, :destroy_sessions
+    def name
+      @name.presence || :"#{comp_class.comp_name}_#{comp_class.family_name}"
+    end
+
+    # Returns the label of buttons produced by this intent.
+    def label(model = nil, *, **label_opt_overrides)
+      label_opts = @label_opts.deep_merge(label_opt_overrides)
+      @label.presence || comp.label(model || (model? ? @data : nil), *, **label_opts)
+    end
+
+    def method
+      @method || :get
+    end
+
+    def feasibility_target
+      @feasibility_target.presence || model? ? @data : nil
+    end
+
+    def feasibility_action
+      @feasibility_action.presence || comp_class.comp_name.to_sym
+    end
+
+    # Returns whether this intent is feasible (no prevention)
+    def feasible?
+      return true if feasibility_target.blank? || feasibility_action.blank?
+      return feasibility_target.feasible?(feasibility_action)
+    end
+
+    # Returns the options that are given to the initializer when creating a button from this intent.
+    def button_comp_opts(label: {})
+      return @custom_args.deep_merge({
+                                       label:  label(**label),
+                                       href:   feasible? ? path : nil,
+                                       method:,
+                                       class:  feasible? ? nil : 'disabled',
+                                       title:  feasible? ? nil : feasibility_target.full_feasibility_messages(feasibility_action).presence
+                                     })
+    end
+
+    # 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 button_comp_opts_overrides [Hash] Any further kwargs are passed to the button component's initializer.
+    def render(controller, parent_comp = nil, style: nil, label: {}, **button_comp_opts_overrides)
+      # Check if permitted
+      return nil unless comp.standalone_access_permitted_for?(controller, standalone_name: @standalone_name, verb: method)
+      # Prepare opts
+      button_comp_class ||= Compony.button_component_class(*[style].compact)
+      button_opts = button_comp_opts(label:).merge(button_comp_opts_overrides)
+      # Perform render
+      if parent_comp
+        return parent_comp.sub_comp(button_comp_class, **button_opts).render(controller)
+      else
+        button_comp_class.new(**button_opts).render(controller)
+      end
+    end
+  end
+end

data/lib/compony/model_fields/association.rb

@@ -12,7 +12,7 @@ module Compony
           return transform_and_join(data.send(@name), controller:) do |el|
             next nil if el.nil?
             if Compony.comp_class_for(link_to_component, el)
-              next controller.helpers.compony_link(link_to_component, el, **link_opts)
+              next controller.helpers.render_intent(link_to_component, el, **{ button: { style: :link } }.deep_merge(link_opts))
             else
               next el.label
             end

data/lib/compony/request_context.rb

@@ -42,7 +42,12 @@ module Compony
       return super
     end
 
+    ################################################
+    # View helpers available only inside components:
+    ################################################
+
     # Renders a content block from the current component.
+    # Does nothing if no such content block exists.
     def content(name) # rubocop:disable Naming/PredicateMethod
       name = name.to_sym
       content_block = component.content_blocks.find { |el| el.name == name }
@@ -59,8 +64,24 @@ module Compony
       return true
     end
 
+    # Like {Compony::RequestContext#content}, but fails if no such content block exists.
+    # @see Compony::RequestContext#content
     def content!(name)
       content(name) || fail("Content block #{name.inspect} not found in #{component.inspect}.")
     end
+
+    # View helper that renders an intent through the default button class.
+    # All non-mentioned parameters are given to the intent initializer.
+    # When inside a request context (`content do...`), this precedes {ViewHelpers#render_intent}.
+    # @param button [Hash] Parameters that will be given to the button component initializer.
+    def render_intent(*, button: {}, **)
+      Compony.intent(*, **).render(controller, component, **button)
+    end
+
+    # View helper that instanciates a sub comp and renders it.
+    # Example usage: `concat render_sub_comp(Components::Something::Nested)`
+    def render_sub_comp(...)
+      sub_comp(...).render(controller)
+    end
   end
 end