brut 0.0.21 → 0.0.23

data/lib/brut/front_end/component.rb

@@ -28,7 +28,6 @@ end
 #
 # Becuase this is a Phlex component, you must implement `view_template` and make calls to Phlex's API to create
 # the markup for your component.
-#
 class Brut::FrontEnd::Component < Phlex::HTML
 
   include Brut::Framework::Errors
@@ -51,96 +50,72 @@ class Brut::FrontEnd::Component < Phlex::HTML
   register_element :brut_tabs
   register_element :brut_tracing
 
-  # Inline an SVG that is part of your app.
-  #
-  # @param [String] svg path to the SVG file, relative to where SVGs are
-  #        stored, which is `app/src/front_end/svgs` or where `Brut.container.svg_locator` is
-  #        looking
-  #
-  # @see Brut::FrontEnd::InlineSvgLocator
-  def inline_svg(svg)
-    Brut.container.svg_locator.locate(svg).then { |svg_file|
-      File.read(svg_file)
-    }.then { |svg_content|
-      raw(safe(svg_content))
-    }
-  end
-
-  # Include a {Brut::FrontEnd::Components::TimeTag} in your markup.
-  def time_tag(timestamp:nil,**component_options, &contents)
-    args = component_options.merge(timestamp:)
-    render Brut::FrontEnd::Components::TimeTag.new(**args,&contents)
-  end
-
-  # Include a {Brut::FrontEnd::Components::FormTag} in your markup.
-  def form_tag(**args, &block)
-    render Brut::FrontEnd::Components::FormTag.new(**args,&block)
-  end
-
-  # Include a component in your markup that you would like Brut to instantiate.
-  # This will use keyword injection to create the component, which means that if the component
-  # doesn't require any data from this component, you do not need to pass through those values.
-  # For example, you may have a component that renders the flash message.  To avoid requiring your component to
-  # be passed the flash, a global component can be injected with it from Brut.
-  def global_component(component_klass)
-    render Brut::FrontEnd::RequestContext.inject(component_klass)
-  end
+  # Module for the various "free methods" available to all components.
+  # Generally, we don't want to build up mega-classes with lots of modules, but
+  # this provides a nice, singular namespace to document the helpers as apart
+  # from the various methods of the component.
+  module Helpers
+    # Render an inline an SVG that is part of your app. **Note** this does not
+    # return the SVG's contents, but it renders it into the current Phlex
+    # context.
+    #
+    # @param [String] svg path to the SVG file, relative to where SVGs are
+    #        stored, which is `app/src/front_end/svgs` or where `Brut.container.svg_locator` is
+    #        looking
+    #
+    # @see Brut::FrontEnd::InlineSvgLocator
+    def inline_svg(svg)
+      Brut.container.svg_locator.locate(svg).then { |svg_file|
+        File.read(svg_file)
+      }.then { |svg_content|
+        raw(safe(svg_content))
+      }
+    end
 
-  # include a {Brut::FrontEnd::Components::ConstraintViolations} in your markup.
-  def constraint_violations(form:, input_name:, index: nil, message_html_attributes: {}, **html_attributes)
-    render(
-      Brut::FrontEnd::Components::ConstraintViolations.new(
-        form:,
-        input_name:,
-        index:,
-        message_html_attributes:,
-        **html_attributes
-      )
-    )
-  end
-
-  # Create an HTML input tag for the given input of a form.  This is a convieniece method
-  # that calls {Brut::FrontEnd::Components::Inputs::TextField.for_form_input}.
-  def input_tag(form:, input_name:, index: nil, **html_attributes)
-    render(
-      Brut::FrontEnd::Components::Inputs::TextField.for_form_input(
-        form:,
-        input_name:,
-        index:,
-        html_attributes:)
-    )
+    # Return a component that you would like Brut to instantiate.
+    # This will use keyword injection to create the component, which means that if the component
+    # doesn't require any data from this component, you do not need to pass through those values.
+    # For example, you may have a component that renders the flash message.  To avoid requiring your component to
+    # be passed the flash, a global component can be injected with it from Brut.
+    #
+    # @return [Object] instance of `component_klass`, as created by Brut. This will
+    #         not render the component.
+    def global_component(component_klass)
+      Brut::FrontEnd::RequestContext.inject(component_klass)
+    end
   end
+  include Helpers
 
   # The name of this component, used for debugging and other purposes. Do not
   # override this.
   def self.component_name = self.name
-
-  # Calls {.component_name} as a convienience. Do not override this.
+  # Convenience method to get the component name. This just calls the class
+  # method {.component_name}.
   def component_name = self.class.component_name
 
-  # For page components (components that are private/nested to a page), this returns
-  # the name of the page in which they are nested. This is mostly useful for
-  # locating page-specific I18n translations.
-  #
-  # @raise If this component is not nested inside a page
-  # @see Brut::I18n::BaseMethods#t
-  def page_name
-    @page_name ||= begin
-                     page = self.class.name.split(/::/).reduce(Module) { |accumulator,class_path_part|
-                       if accumulator.ancestors.include?(Brut::FrontEnd::Page)
-                         accumulator
-                       else
-                         accumulator.const_get(class_path_part)
-                       end
-                     }
-                     if page.ancestors.include?(Brut::FrontEnd::Page)
-                       page.name
-                     elsif page.respond_to?(:page_name)
-                       page.page_name
-                     else
-                       raise "#{self.class} is not nested inside a page, so #page_name should not have been called"
-                     end
-                   end
-  end
+  # True if this component is page private.
+  # @!visibility private
+  def page_private? = !!self.containing_page_class
 
+  # Returns the {Brut::FrontEnd::Page.page_name} of the page containing this component, 
+  # if it is {#page_private?}. Do not call if it's not.
+  # @!visibility private
+  def containing_page_name = self.containing_page_class.page_name
+
+private
+
+  def containing_page_class
+    page_class = self.class.name.split(/::/).reduce(Module) { |accumulator,class_path_part|
+      if accumulator.ancestors.include?(Brut::FrontEnd::Page)
+        accumulator
+      else
+        accumulator.const_get(class_path_part)
+      end
+    }
+    if page_class.ancestors.include?(Brut::FrontEnd::Page)
+      page_class
+    else
+      nil
+    end
+  end
 end

data/lib/brut/front_end/components/constraint_violations.rb

@@ -14,10 +14,7 @@
 # </brut-cv-messages>
 # ```
 #
-# Note that if you are using `<brut-form>` then `<brut-cv>` elements will be inserted into the `<brut-cv-messages>` element, however
-# they will not have the `server-side` attribute.
-#
-# You will most commonly use this component via {Brut::FrontEnd::Component#constraint_violations}.
+# Note that if you are using `<brut-form>` then `<brut-cv>` elements will be inserted into the `<brut-cv-messages>` element, however they will not have the `server-side` attribute.
 class Brut::FrontEnd::Components::ConstraintViolations < Brut::FrontEnd::Component
   # Create a new ConstraintViolations component
   #

data/lib/brut/front_end/components/form_tag.rb

@@ -1,4 +1,4 @@
-# Represents a `<form>` HTML element that includes a CSRF token as needed. You likely want to use this class via the {Brut::FrontEnd::Component#form_tag} method.
+# Represents a `<form>` HTML element that includes a CSRF token as needed.
 class Brut::FrontEnd::Components::FormTag < Brut::FrontEnd::Component
   # Creates the form surrounding the contents of the block yielded to it. If the form's action is a POST, it will include a CSRF token.
   # If the form's action is GET, it will not.

data/lib/brut/front_end/components/input.rb

@@ -2,10 +2,10 @@ module Brut::FrontEnd::Components
 
   # Holds components designed to render HTML `<input>` and other form components.
   module Inputs
-    autoload(:TextField,"brut/front_end/components/inputs/text_field")
+    autoload(:InputTag,"brut/front_end/components/inputs/input_tag")
     autoload(:RadioButton,"brut/front_end/components/inputs/radio_button")
-    autoload(:Select,"brut/front_end/components/inputs/select")
-    autoload(:Textarea,"brut/front_end/components/inputs/textarea")
+    autoload(:SelectTagWithOptions,"brut/front_end/components/inputs/select_tag_with_options")
+    autoload(:TextareaTag,"brut/front_end/components/inputs/textarea_tag")
     autoload(:CsrfToken,"brut/front_end/components/inputs/csrf_token")
   end
 

data/lib/brut/front_end/components/inputs/csrf_token.rb

@@ -1,5 +1,5 @@
 # Renders a hidden field for a form that contains the current CSRF token. You only need
-# to use this directly if you are building a form without {Brut::FrontEnd::Component#form_tag}.
+# to use this directly if you are building a form without {Brut::FrontEnd::Components::FormTag}
 class Brut::FrontEnd::Components::Inputs::CsrfToken < Brut::FrontEnd::Components::Input
   def initialize(csrf_token:)
     @csrf_token = csrf_token

data/lib/brut/front_end/components/inputs/{text_field.rb → input_tag.rb}

@@ -1,5 +1,5 @@
 # Generates an HTML `<input>` field.
-class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components::Input
+class Brut::FrontEnd::Components::Inputs::InputTag < Brut::FrontEnd::Components::Input
   # Creates the appropriate input for the given {Brut::FrontEnd::Form} and input name.
   # Generally, you want to use this method over the initializer.
   #
@@ -7,10 +7,10 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
   # @param [String] input_name the name of the input, which should be a member of `form`
   # @param [Integer] index if this input is part of an array, this is the index into that array. This is used to get the input's value.
   # @param [Hash] html_attributes any additional HTML attributes to include on the `<input>` element.
-  def self.for_form_input(form:, input_name:, index: nil, html_attributes: {})
+  def self.for_form_input(form:, input_name:, index: nil, **html_attributes)
+    input = form.input(input_name, index:)
     default_html_attributes = {}
     html_attributes = html_attributes.map { |key,value| [ key.to_sym, value ] }.to_h
-    input = form.input(input_name, index:)
 
     default_html_attributes[:required] = input.required
     default_html_attributes[:pattern]  = input.pattern
@@ -45,13 +45,11 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
     end
     if !form.new? && !input.valid?
       default_html_attributes["data-invalid"] = true
-      input.validity_state.each do |constraint,violated|
-        if violated
-          default_html_attributes["data-#{constraint}"] = true
-        end
+      input.validity_state.each do |constraint|
+        default_html_attributes["data-#{constraint}"] = true
       end
     end
-    Brut::FrontEnd::Components::Inputs::TextField.new(default_html_attributes.merge(html_attributes))
+    Brut::FrontEnd::Components::Inputs::InputTag.new(default_html_attributes.merge(html_attributes))
   end
 
   def invalid? = @attributes["data-invalid"] == true

data/lib/brut/front_end/components/inputs/radio_button.rb

@@ -3,7 +3,7 @@
 # internal to the {Brut::FrontEnd::Form} treat the radio button group as a single input with
 # a single name and value.  When it comes time to generate HTML, this class is used
 # to generate a single radio button from a group.
-class Brut::FrontEnd::Components::Inputs::RadioButton < Brut::FrontEnd::Components::Inputs::TextField
+class Brut::FrontEnd::Components::Inputs::RadioButton < Brut::FrontEnd::Components::Inputs::InputTag
   # Creates a radio button that is part of a radio button group.  You should call this
   # method once for each radio button in the group.
   #

data/lib/brut/front_end/components/inputs/select_tag_with_options.rb

@@ -0,0 +1,187 @@
+# Renders an HTML `<select>`.
+class Brut::FrontEnd::Components::Inputs::SelectTagWithOptions < Brut::FrontEnd::Components::Input
+  # Creates the appropriate select input for the given {Brut::FrontEnd::Form} and input name.
+  # Generally, you want to use this method over the initializer.
+  #
+  # @param [Brut::FrontEnd::Form} form The form that is being rendered.
+  #        This method will consult this class to understand the requirements
+  #        on this select so its HTML is generated correctly.
+  # @param [String] input_name the name of the input, which should be a member of `form`
+  # @param [Array<Object>] options An array of objects represented what is being selected.
+  #        These can be any object and are ideally whatever domain object or
+  #        data type you want on the backend to represent this selection.
+  # @param [Symbol|String] value_attribute the name of an attribute to determine an option's value.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        `value` attribute.  The value returned by `value_attribute` should be unique amongst the
+  #        `options` provided *and* be distinct from whatever `value` is used for `include_blank`.
+  # @param [Symbol|String] option_text_attribute the name of an attribute to determine the text for an option.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        text content.  The value returned by `option_text_attribute` need not be unique, though if it
+  #        is not unique, it will certainly be confusing.
+  # @param [Integer] index if this input is part of an array, this is the index into that array.
+  #        This is used to get the input's value.
+  # @param [Hash] html_attributes any additional HTML attributes to include on the `<select>` element.
+  # @param [false|true|Hash] include_blank configure how and if to include a blank element in the select.
+  #        If this is false, there will be no blank element. If it's `true`, there will be one with
+  #        no value or text.  If this is a `Hash` it must contain a `value:` key and a `text_content:` key
+  #        to be used as the `value` attribute and option text content, respectively.
+  #
+  # @return [Brut::FrontEnd::Components::Inputs::SelectTagWithOptions] the select input ready to be placed into a view.
+  def self.for_form_input(form:,
+                          input_name:,
+                          options:,
+                          include_blank: false,
+                          value_attribute:,
+                          option_text_attribute:,
+                          index: nil,
+                          html_attributes: {})
+    html_attributes = html_attributes.map { |key,value| [ key.to_sym, value ] }.to_h
+    default_html_attributes = {}
+    index ||= 0
+    input = form.input(input_name, index:)
+    default_html_attributes[:required] = input.required
+    if !form.new? && !input.valid?
+      default_html_attributes["data-invalid"] = true
+      input.validity_state.each do |constraint,violated|
+        if violated
+          default_html_attributes["data-#{constraint}"] = true
+        end
+      end
+    end
+    name = if input.array?
+             "#{input.name}[]"
+           else
+             input.name
+           end
+
+    Brut::FrontEnd::Components::Inputs::SelectTagWithOptions.new(
+      name: name,
+      options:,
+      selected_value: input.value,
+      value_attribute:,
+      option_text_attribute:,
+      include_blank:,
+      html_attributes: default_html_attributes.merge(html_attributes)
+    )
+  end
+
+  # Create the element.
+  #
+  # @param [String] name the name of the input
+  # @param [Array<Object>] options An array of objects represented what is being selected.
+  #        These can be any object and are ideally whatever domain object or
+  #        data type you want on the backend to represent this selection.
+  # @param [Symbol|String] value_attribute the name of an attribute to determine an option's value.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        `value` attribute.  The value returned by `value_attribute` should be unique amongst the
+  #        `options` provided *and* be distinct from whatever `value` is used for `include_blank`.
+  # @param [String] selected_value the value of the selected option. Note that this is the *value*
+  #        of the selected option, not the selected option itself. To set the selected value
+  #        based on a selected option, omit this and use `selected_option`
+  # @param [String] selected_option the selected option. Note that `value_attribute` will be called
+  #        on this to determine the selected value to use when generating HTML. Also note that
+  #        this object must be in `options` or an exeception is raised.
+  # @param [Symbol|String] option_text_attribute the name of an attribute to determine the text for an option.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        text content.  The value returned by `option_text_attribute` need not be unique, though if it
+  #        is not unique, it will certainly be confusing.
+  # @param [Hash] html_attributes any additional HTML attributes to include on the `<select>` element.
+  # @param [false|true|Hash] include_blank configure how and if to include a blank element in the select.
+  #        If this is false, there will be no blank element. If it's `true`, there will be one with
+  #        no value or text.  If this is a `Hash` it must contain a `value:` key and a `text_content:` key
+  #        to be used as the `value` attribute and option text content, respectively.
+  #
+  # @raise ArgumentError if `selected_option` is present, but not in `options` or if `selected_value` is
+  #        present, but no option's value for `value_attribute` is that value.
+  #
+  # XXX: Why does this not ask the form for the selected_value?
+  # XXX: This doesn't do well when values are strings
+  def initialize(name:,
+                 options:,
+                 value_attribute:,
+                 selected_value: nil,
+                 selected_option: nil,
+                 option_text_attribute:,
+                 include_blank: false,
+                 html_attributes:)
+    @options                = options
+    @include_blank          = IncludeBlank.from_param(include_blank)
+    @value_attribute        = value_attribute
+    @option_text_attribute  = option_text_attribute
+    @html_attributes        = html_attributes
+    @html_attributes[:name] = name
+
+    if selected_value.nil?
+      if selected_option.nil?
+        @selected_value = nil # explicitly nothing is selected
+      else
+        option = options.detect { |option|
+          option.send(@value_attribute) == selected_option.send(@value_attribute)
+        }
+        if option.nil?
+          raise ArgumentError, "selected_option #{selected_option} (with #{value_attribute} '#{selected_option.send(value_attribute)}') was not found in options"
+        end
+        @selected_value = option.send(@value_attribute)
+      end
+    else
+      if selected_value.kind_of?(Array)
+        raise "WTF: #{name}"
+      end
+      option = options.detect { |option|
+        selected_value == option.send(@value_attribute)
+      }
+      if option.nil?
+        raise ArgumentError, "selected_value #{selected_value} was not the value for #{value_attribute} on any of the options: #{options.map { |option| option.send(value_attribute) }.join(', ')}"
+      end
+      @selected_value = option.send(@value_attribute)
+    end
+  end
+
+  def view_template
+    select(**@html_attributes) {
+      if @include_blank
+        option(**@include_blank.option_attributes) {
+          @include_blank.text_content
+        }
+      end
+      options = @options.each do |option|
+        value = option.send(@value_attribute)
+        option_attributes = { value: value }
+        if value == @selected_value
+          option_attributes[:selected] = true
+        end
+        option(**option_attributes) {
+          option.send(@option_text_attribute)
+        }
+      end
+    }
+  end
+private
+
+  # @!visibility private
+  class IncludeBlank
+    attr_reader :text_content, :option_attributes
+    def self.from_param(include_blank)
+      if !include_blank
+        return nil
+      else
+        self.new(include_blank)
+      end
+    end
+    def initialize(include_blank)
+      if include_blank == true
+        @text_content = ""
+        @option_attributes = {}
+      elsif include_blank.kind_of?(Hash)
+        if include_blank.key?(:value) && include_blank.key?(:text_content)
+          @text_content = include_blank[:text_content]
+          @option_attributes = { value: include_blank[:value] }
+        else
+          raise ArgumentError, "when include_blank: is a Hash, it must include both :value and :text_content as keys. Got: #{include_blank.keys.join(", ")}"
+        end
+      else
+        raise ArgumentError,"include_blank: was a #{include_blank.class}. It should be true, false, nil, or a Hash"
+      end
+    end
+  end
+end

data/lib/brut/front_end/components/inputs/{textarea.rb → textarea_tag.rb}

@@ -1,5 +1,5 @@
 # Generates an HTML `<textarea>` field.
-class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components::Input
+class Brut::FrontEnd::Components::Inputs::TextareaTag < Brut::FrontEnd::Components::Input
   # Creates the appropriate textarea for the given {Brut::FrontEnd::Form} and input name.
   # Generally, you want to use this method over the initializer.
   #
@@ -35,7 +35,7 @@ class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components:
       end
     end
     value = input.value
-    Brut::FrontEnd::Components::Inputs::Textarea.new(default_html_attributes.merge(html_attributes), value)
+    Brut::FrontEnd::Components::Inputs::TextareaTag.new(default_html_attributes.merge(html_attributes), value)
   end
   # Create an instance
   #

data/lib/brut/front_end/components/time_tag.rb

@@ -1,4 +1,5 @@
-# Renders a date or timestamp accessibly, using the `<time>` element. Likely you will use this via the {Brut::FrontEnd::Component#time_tag} method. This will account for the current request's time zone. See {Clock}.
+# Renders a date or timestamp accessibly, using the `<time>` element.
+# This will account for the current request's time zone. See {Clock}.
 class Brut::FrontEnd::Components::TimeTag < Brut::FrontEnd::Component
   include Brut::I18n::ForHTML
   # Creates the component

data/lib/brut/front_end/form.rb

@@ -68,12 +68,12 @@ class Brut::FrontEnd::Form
     @inputs = self.class.input_definitions.map { |name,input_definition|
       value = @params[name] || @params[name.to_sym]
       inputs = if value.kind_of?(Array)
-                 value.map { |one_value|
-                   input_definition.make_input(value: one_value)
+                 value.map.with_index { |one_value, index|
+                   input_definition.make_input(value: one_value, index:)
                  }
                else
                  [
-                   input_definition.make_input(value:)
+                   input_definition.make_input(value:, index: nil)
                  ]
                end
 
@@ -98,7 +98,7 @@ class Brut::FrontEnd::Form
     input = inputs[index]
     if input.nil?
       input_definition = self.class.input_definitions.fetch(input_name.to_s)
-      input = input_definition.make_input(value:"")
+      input = input_definition.make_input(value:"", index:)
       inputs[index] = input
     end
     input

data/lib/brut/front_end/forms/input.rb

@@ -13,9 +13,10 @@ class Brut::FrontEnd::Forms::Input
   # Create the input with the given definition and value
   # @param [Brut::FrontEnd::Forms::InputDefinition] input_definition
   # @param [String] value
-  def initialize(input_definition:, value:)
+  def initialize(input_definition:, value:, index:)
     @input_definition = input_definition
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new
+    @index = index
     self.value=(value)
   end
 

data/lib/brut/front_end/forms/input_definition.rb

@@ -109,7 +109,10 @@ class Brut::FrontEnd::Forms::InputDefinition
 
 
   # Create an Input based on this definition, initializing it with the given value.
-  def make_input(value:)
-    Brut::FrontEnd::Forms::Input.new(input_definition: self, value: value)
+  # @param [String] value the value to give this input initially.
+  # @param [Integer] index the index of this input, if it is part of an array of
+  # inputs. `nil` is allowed only if the input definition is not for an array.
+  def make_input(value:, index:)
+    Brut::FrontEnd::Forms::Input.new(input_definition: self, value:, index:)
   end
 end

data/lib/brut/front_end/forms/radio_button_group_input.rb

@@ -8,9 +8,10 @@ class Brut::FrontEnd::Forms::RadioButtonGroupInput
   attr_reader :validity_state
 
   # (see Brut::FrontEnd::Forms::Input#initialize)
-  def initialize(input_definition:, value:)
+  def initialize(input_definition:, value:, index:)
     @input_definition = input_definition
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new
+    @index = index
     if input_definition.array?
       value ||= []
     end

data/lib/brut/front_end/forms/radio_button_group_input_definition.rb

@@ -23,7 +23,7 @@ class Brut::FrontEnd::Forms::RadioButtonGroupInputDefinition
   def array? = @array
 
   # Create an Input based on this defitition, initializing it with the given value.
-  def make_input(value:)
-    Brut::FrontEnd::Forms::RadioButtonGroupInput.new(input_definition: self, value: value)
+  def make_input(value:, index:)
+    Brut::FrontEnd::Forms::RadioButtonGroupInput.new(input_definition: self, value:, index:)
   end
 end

data/lib/brut/front_end/forms/select_input.rb

@@ -9,12 +9,10 @@ class Brut::FrontEnd::Forms::SelectInput
   attr_reader :validity_state
 
   # (see Brut::FrontEnd::Forms::Input#initialize)
-  def initialize(input_definition:, value:)
+  def initialize(input_definition:, value:, index:)
     @input_definition = input_definition
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new
-    if input_definition.array?
-      value ||= []
-    end
+    @index = index
     self.value=(value)
   end
 

data/lib/brut/front_end/forms/select_input_definition.rb

@@ -21,7 +21,7 @@ class Brut::FrontEnd::Forms::SelectInputDefinition
   def array? = @array
 
   # Create an Input based on this defitition, initializing it with the given value.
-  def make_input(value:)
-    Brut::FrontEnd::Forms::SelectInput.new(input_definition: self, value: value)
+  def make_input(value:, index:)
+    Brut::FrontEnd::Forms::SelectInput.new(input_definition: self, value:, index:)
   end
 end

data/lib/brut/front_end/handler.rb

@@ -1,12 +1,24 @@
 module Brut::FrontEnd
-  # A handler responds to all HTTP requests other than those that render a page. It will be given any data it needs
-  # to handle the request to its {#handle} method, which you must implement. 
-  # You define this method to accept the parameters you expect. See {Brut::FrontEnd::RequestContext} for how that works.
+  # A handler responds to all HTTP requests other than those that render a page.
+  # Like a page, the handler is initialized with any of the data it needs.  The {#handle} method will
+  # be called to perform whatever action is needed, and its return value will determine what
+  # ther esponse will be.
   #
-  # You may also define `before_handle` which will be given any subset of those parameters and can perform logic before
-  # handle is called.  This is most useful in a base class to check for permissions or other cross-cutting concerns.
+  # To create a handler, after defining a route or form,
+  # subclass this class (or, more likely, your app's `AppHandler`) and
+  # provide an initializer that accepts keyword arguments.  The names of these arguments will be used
+  # to locate the values that Brut will pass in when creating your page object. If your handler
+  # is for a form, be sure to include the `form:` keyword argument.
   #
-  # The primary method of this class is {#handle!} which you should not override, but *should* call in a test.
+  # Consult Brut's documentation on keyword injection to know what values you may use and how values are located.
+  #
+  # Then, implement {#handle} to perform whatever logic is needed to handle the request.
+  #
+  # You may also define `before_handle` which will be called before {#handle} to potentially abort
+  # the request.  This is mostly useful if you have a base class for some of your handlers and want to
+  # share cross-cutting logic.
+  #
+  # Note that the public API for handlers is {#handle!}, which is what you should call in a test.
   class Handler
     include Brut::FrontEnd::HandlingResults
     include Brut::Framework::Errors
@@ -27,32 +39,22 @@ module Brut::FrontEnd
       abstract_method!
     end
 
+    # Override this to performa any checks before {#handle} is called.  This should
+    # return `nil` if {#handle} should proceed to be called. Generally, you don't need to override
+    # this as {#handle} can include the logic.  Where this is useful is to share cross-cutting logic
+    # across other handlers.
+    #
+    # @return [URI|Brut::FrontEnd::Component,Array,Brut::FrontEnd::HttpStatus,Brut::FrontEnd::Download] See
+    #         {#handle} for what each return value means.
+    def before_handle = nil
+
     # Called by Brut to handle the request. Do not override this. If your handler responds to `before_handle` that is called with the
     # same args as you have defined for {#handle}. If `before_handle` returns anything other than `nil`, that value is returned and
     # should be one of the values documented in {#handle}.  If `before_handle` returns `nil`, {#handle} is called and whatever it
     # returns is returned here.
     def handle!(**args)
       result = nil
-      if self.respond_to?(:before_handle)
-        before_handle_args = self.method(:before_handle).parameters.map { |(type,name)|
-          if type == :keyreq
-            if args.key?(name)
-              [ name, args[name] ]
-            else
-              raise ArgumentError,"before_handle requires keyword arg '#{name}' but `handle` did not receive it. It must"
-            end
-          elsif type == :key
-            if args.key?(name)
-              [ name, args[name] ]
-            else
-              nil
-            end
-          else
-            raise ArgumentError,"before_handle must only have keyword args. Got '#{name}' of type '#{type}'"
-          end
-        }.compact.to_h
-        result = self.before_handle(**before_handle_args)
-      end
+      result = self.before_handle
       if result.nil?
         result = self.handle(**args)
       end