brut 0.0.1 → 0.0.2

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

@@ -0,0 +1,57 @@
+# Renders the custom elements used to manage both client- and server-side constraint violations via the `<brut-cv-messages>` and `<brut-cv>` tags. Each constraint violation on the input's {Brut::FrontEnd::Forms::ValidityState} will generate a `<brut-cv server-side>` tag that will contain the I18n translation of the violation's {Brut::FrontEnd::Forms::ConstraintViolation#key} prefixed with `"cv.be"`.
+#
+# The general form of this component will be:
+#
+# ```html
+# <brut-cv-messages input-name="«input_name»">
+#   <brut-cv server-side>
+#     «message»
+#   </brut-cv>
+#   <brut-cv server-side>
+#     «message»
+#   </brut-cv>
+#   <!- ... ->
+# </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::Helpers#constraint_violations}.
+class Brut::FrontEnd::Components::ConstraintViolations < Brut::FrontEnd::Component
+  # Create a new ConstraintViolations component
+  #
+  # @param [Brut::FrontEnd::Form] form the form in which this component is being rendered.
+  # @param [String|Symbol] input_name the name of the input, based on what was used in the form object.
+  # @param [Hash] html_attributes attributes to be placed on the outer `<brut-cv-messages>` element.
+  # @param [Integer] index index of the input, for array-based inputs
+  # @param [Hash] message_html_attributes attributes to be placed on each inner `<brut-cv>` element.
+  def initialize(form:, input_name:, index: nil, message_html_attributes: {}, **html_attributes)
+    @form                    =  form
+    @input_name              =  input_name
+    @array                   = !index.nil?
+    @index                   =  index || 0
+    @html_attributes         =  html_attributes
+    @message_html_attributes =  message_html_attributes
+  end
+
+  def render
+    html_attributes = {
+      "input-name": @array ? "#{@input_name}[]" : @input_name
+    }.merge(@html_attributes)
+
+    message_html_attributes = {
+      "server-side": true,
+    }.merge(@message_html_attributes)
+
+    html_tag("brut-cv-messages", **html_attributes) do
+      @form.input(@input_name, index: @index).validity_state.select { |constraint|
+        !constraint.client_side?
+      }.map { |constraint|
+        html_tag("brut-cv",**message_html_attributes) do
+          t("cv.be.#{constraint}", **constraint.context).capitalize
+        end
+      }.join("\n")
+    end
+  end
+end

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

@@ -1,48 +1,39 @@
 require "rexml"
-# Represents a <form> HTML component
+# Represents a `<form>` HTML element that includes a CSRF token as needed. You likely want to use this class via the {Brut::FrontEnd::Component::Helpers#form_tag} method.
 class Brut::FrontEnd::Components::FormTag < Brut::FrontEnd::Component
-  def initialize(**attributes,&contents)
-    form_class = attributes.delete(:for)
+  # (see Brut::FrontEnd::Component::Helpers#form_tag)
+  def initialize(route_params: {}, **html_attributes,&contents)
+    form_class = html_attributes.delete(:for) # Cannot be a keyword arg, since for is a reserved word
     if !form_class.nil?
-      if attributes[:action]
-        raise ArgumentError, "You cannot specify both for: (#{form_class}) and and action: (#{attributes[:action]}) to a form_tag"
+      if form_class.kind_of?(Brut::FrontEnd::Form)
+        form_class = form_class.class
       end
-      if attributes[:method]
-        raise ArgumentError, "You cannot specify both for: (#{form_class}) and and method: (#{attributes[:method]}) to a form_tag"
+      if html_attributes[:action]
+        raise ArgumentError, "You cannot specify both for: (#{form_class}) and and action: (#{html_attributes[:action]}) to a form_tag"
+      end
+      if html_attributes[:method]
+        raise ArgumentError, "You cannot specify both for: (#{form_class}) and and method: (#{html_attributes[:method]}) to a form_tag"
+      end
+      begin
+        route = Brut.container.routing.route(form_class)
+        html_attributes[:method] = route.http_method
+        html_attributes[:action] = route.path(**route_params)
+      rescue Brut::Framework::Errors::MissingParameter
+        raise ArgumentError, "You specified #{form_class} (or an instance of it), but it requires more url parameters than were found in route_params: (or route_params: was omitted). Please add all required parameters to route_params: or use `action: #{form_class}.routing(..params..), method: [:get|:post]` instead"
       end
-      route = Brut.container.routing.route(form_class)
-      attributes[:method] = route.http_method
-      attributes[:action] = route.path
     end
 
-    @include_csrf_token = true
     @csrf_token_omit_reasoning = nil
 
-    http_method = Brut::FrontEnd::HttpMethod.new(attributes[:method])
+    http_method = Brut::FrontEnd::HttpMethod.new(html_attributes[:method])
 
-    if http_method.get?
-      if attributes.key?(:no_csrf_token)
-        raise ArgumentError,":no_csrf_token is not allowed for form_tag when the HTTP method is a GET"
-      end
-      force_csrf_token = attributes.delete(:force_csrf_token)
-      if !force_csrf_token
-        @include_csrf_token = false
-        @csrf_token_omit_reasoning = "because this form's action is GET"
-      end
-    else
-      if attributes.key?(:force_csrf_token)
-        raise ArgumentError,":force_csrf_token is not allowed for form_tag when the HTTP method is not a GET"
-      end
-      no_csrf_token = attributes.delete(:no_csrf_token)
-      if no_csrf_token
-        @include_csrf_token = false
-        @csrf_token_omit_reasoning = "because :no_csrf_token was passed to form_tag"
-      end
-    end
-    @attributes = attributes
+    @include_csrf_token = http_method.post?
+    @csrf_token_omit_reasoning = http_method.get? ? "because this form's action is a GET" : nil
+    @attributes = html_attributes
     @contents = contents
   end
 
+  # @!visibility private
   def render
     attribute_string = @attributes.map { |key,value|
       key = key.to_s

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

@@ -1,11 +1,44 @@
 require "rexml"
 
-# Produces `<brut-i18n-translation>` entries for the given values
+# Produces `<brut-i18n-translation>` entries for the given values. This is used for client-side constraint violation messaging with
+# JavaScript.  The `<brut-constraint-violation-message>` tag uses these keys to produce messages on the client.
+#
+# The default layout included in new Brut apps includes this:
+#
+# ```html
+# <%= component(
+#       Brut::FrontEnd::Components::I18nTranslations.new(
+#         "general.cv.fe"
+#       )
+# ) %>
+# ```
+#
+# At runtime, this will produce this:
+#
+# ```html
+# <brut-i18n-translation
+#   key="general.cv.fe.badInput"
+#   value="%{field} is the wrong type of data">
+# </brut-i18n-translation>
+# <brut-i18n-translation
+#   key="general.cv.fe.patternMismatch"
+#   value="%{field} isn't in the right format">
+# </brut-i18n-translation>
+# <!-- etc -->
+# ```
+#
+# Thus, it will render the translations for all client side errors supported by the browser.  This means that if a
+# client side `ValidityState` returns true for, say, `badInput`, JavaScript can look up by the `key` 
+# `general.cv.fe.badInput` and find the `value` to produce the string "This field is the wrong type of data".
 class Brut::FrontEnd::Components::I18nTranslations < Brut::FrontEnd::Component
+
+  # Create the component for all keys under the given root
+  # @param [String] i18n_key_root A prefix or full key for the i18n messages to render.  For example, if you have `en.cv.fe.valueMissing` and `en.cv.fe.badInput`, an `i18n_key_root` value of `"en.cv.fe"` will result in both of those keys being rendered.
   def initialize(i18n_key_root)
     @i18n_key_root = i18n_key_root
   end
 
+  # @!visibility private
   def render
     values = ::I18n.t(@i18n_key_root)
     if values.kind_of?(String)

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

@@ -1,13 +1,16 @@
 require "rexml"
 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(: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(:CsrfToken,"brut/front_end/components/inputs/csrf_token")
   end
 
+  # Base class for all inputs
   class Input < Brut::FrontEnd::Component
   end
 end

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

@@ -1,3 +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::Helpers#form_tag}.
 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/radio_button.rb

@@ -0,0 +1,41 @@
+# Renders an HTML `<input type="radio">`. Unlike other form fields, radio
+# button groups require several HTML elements to present the visitor a choice.  All of the classes
+# 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
+  # 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.
+  #
+  # @param [Brut::FrontEnd::Form} form The form that is being rendered. This method will consult this class to understand the requirements on this input so its HTML is generated correctly.
+  # @param [String] input_name the name of the input, which should be a member of `form`
+  # @param [String] value the value for this radio button.  The {Brut::FrontEnd::Forms::RadioButtonGroupInput} value is compared
+  # against this value to determine if this `<input>` will have the `checked` attribute.
+  # @param [Hash] html_attributes any additional HTML attributes to include on the `<input>` element.
+  def self.for_form_input(form:, input_name:, value:, html_attributes: {})
+    default_html_attributes = {}
+    html_attributes = html_attributes.map { |key,value| [ key.to_s, value ] }.to_h
+    input = form.input(input_name)
+
+    default_html_attributes["required"] = input.required
+    default_html_attributes["type"]     = "radio"
+    default_html_attributes["name"]     = input.name
+    default_html_attributes["value"]    = value
+
+    selected_value = input.value
+
+    if selected_value == value
+      default_html_attributes["checked"] = true
+    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
+      end
+    end
+    Brut::FrontEnd::Components::Inputs::RadioButton.new(default_html_attributes.merge(html_attributes))
+  end
+end

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

@@ -1,13 +1,29 @@
+# Renders an HTML `<select>`.
 class Brut::FrontEnd::Components::Inputs::Select < 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 [Object] selected_value The currently-selected value for the select. Can be `nil` if nothing is selected.
+  # @param [Symbol|String] value_attribute the name of an attribute or no-parameter method that can be called on objects inside `options` to get the value to use in the select input.  This should be unique amongst the options, and is usually an id.
+  # @param [Symbol|String] option_text_attribute the name of an attribute or no-parameter method that can be called on objects inside `options` to get the actual text of the option shown to the user.  This should probably allow for I18n.
+  # @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 nor text.  If this is a `Hash` it must contain a `value:` key and `text_content:` key to be used as the `value` attribute and option text content, respectively.
   def self.for_form_input(form:,
                           input_name:,
                           options:,
                           selected_value:,
+                          include_blank: false,
                           value_attribute:,
                           option_text_attribute:,
+                          index: nil,
                           html_attributes: {})
     default_html_attributes = {}
-    input = form[input_name]
+    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
@@ -17,15 +33,22 @@ class Brut::FrontEnd::Components::Inputs::Select < Brut::FrontEnd::Components::I
         end
       end
     end
+    name = if input.array?
+             "#{input.name}[]"
+           else
+             input.name
+           end
     Brut::FrontEnd::Components::Inputs::Select.new(
-      name: input.name,
+      name: name,
       options:,
       selected_value:,
       value_attribute:,
       option_text_attribute:,
+      include_blank:,
       html_attributes: default_html_attributes.merge(html_attributes)
     )
   end
+  # Create the element. See {.for_form_input} for documentation on these parameters.
   def initialize(name:,
                  options:,
                  include_blank: false,
@@ -72,6 +95,7 @@ class Brut::FrontEnd::Components::Inputs::Select < Brut::FrontEnd::Components::I
   end
 private
 
+  # @!visibility private
   class IncludeBlank
     attr_reader :text_content, :option_attributes
     def self.from_param(include_blank)

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

@@ -1,11 +1,27 @@
+# Generates an HTML `<input>` field.
 class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components::Input
-  def self.for_form_input(form:, input_name:, html_attributes: {})
+  # Creates the appropriate 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 input so its HTML is generated correctly.
+  # @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: {})
     default_html_attributes = {}
-    input = form[input_name]
+    html_attributes = html_attributes.map { |key,value| [ key.to_s, value ] }.to_h
+    index ||= 0
+    input = form.input(input_name, index:)
+
     default_html_attributes["required"] = input.required
     default_html_attributes["pattern"]  = input.pattern
     default_html_attributes["type"]     = input.type
-    default_html_attributes["name"]     = input.name
+    default_html_attributes["name"]     = if input.array?
+                                            "#{input.name}[]"
+                                          else
+                                            input.name
+                                          end
+
     if input.max
       default_html_attributes["max"] = input.max
     end
@@ -21,11 +37,13 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
     if input.step
       default_html_attributes["step"] = input.step
     end
+    value = input.value
+
     if input.type == "checkbox"
       default_html_attributes["value"] = "true"
-      default_html_attributes["checked"] = input.value == "true"
+      default_html_attributes["checked"] = value == "true"
     else
-      default_html_attributes["value"] = input.value
+      default_html_attributes["value"] = value
     end
     if !form.new? && !input.valid?
       default_html_attributes["data-invalid"] = true
@@ -37,6 +55,10 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
     end
     Brut::FrontEnd::Components::Inputs::TextField.new(default_html_attributes.merge(html_attributes))
   end
+
+  # Create an instance
+  #
+  # @param [Hash] attributes HTML attributes to put on the element.
   def initialize(attributes)
     @sanitized_attributes = attributes.map { |key,value|
         [

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

@@ -1,9 +1,24 @@
+# Generates an HTML `<textarea>` field.
 class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components::Input
-  def self.for_form_input(form:, input_name:, html_attributes: {})
+  # Creates the appropriate textarea 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 textarea so its HTML is generated correctly.
+  # @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 `<textarea>` element.
+  def self.for_form_input(form:, input_name:, index: nil, html_attributes: {})
     default_html_attributes = {}
-    input = form[input_name]
+
+    index ||= 0
+    input = form.input(input_name, index:)
+
     default_html_attributes["required"] = input.required
-    default_html_attributes["name"]     = input.name
+    default_html_attributes["name"]     = if input.array?
+                                            "#{input.name}[]"
+                                          else
+                                            input.name
+                                          end
     if input.maxlength
       default_html_attributes["maxlength"] = input.maxlength
     end
@@ -18,8 +33,13 @@ class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components:
         end
       end
     end
-    Brut::FrontEnd::Components::Inputs::Textarea.new(default_html_attributes.merge(html_attributes), input.value)
+    value = input.value
+    Brut::FrontEnd::Components::Inputs::Textarea.new(default_html_attributes.merge(html_attributes), value)
   end
+  # Create an instance
+  #
+  # @param [Hash] attributes HTML attributes to put on the element.
+  # @param [String] value the value to place inside the text area
   def initialize(attributes, value)
     @sanitized_attributes = attributes.map { |key,value|
         [

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

@@ -1,4 +1,11 @@
-# Produces `<brut-locale-detection>`
+# Produces the `<brut-locale-detection>` custom element, with attributes set as appropriate based on the server's
+# understanding of the current session's locale.
+#
+# The `<brut-locale-detection>` element exists to send a JSON payload back to the server
+# (handled by {Brut::FrontEnd::Handlers::LocaleDetectionHandler}), with information about the browser's time zone and locale.
+#
+# This element doesn't need to do this if the server has this information.  This component handles creating the right HTML to either
+# ask the browser to send it, or not.
 class Brut::FrontEnd::Components::LocaleDetection < Brut::FrontEnd::Component
   def initialize(session:)
     @timezone = session.timezone_from_browser

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

@@ -1,4 +1,6 @@
 require "rexml"
+
+# Renders a `<meta>` tag that contains the name of the page.  This is useful for end to end tests to assert that they are on a specific page before continuing with the test.  It can eliminate a lot of confusion when a test fails.
 class Brut::FrontEnd::Components::PageIdentifier < Brut::FrontEnd::Component
   def initialize(page_name)
     @page_name = page_name

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

@@ -0,0 +1,95 @@
+require "rexml"
+# Renders a date or timestamp accessibly, using the `<time>` element. Likely you will use this via the {Brut::FrontEnd::Component::Helpers#time_tag} method. This will account for the current request's time zone. See {Clock}.
+class Brut::FrontEnd::Components::Time < Brut::FrontEnd::Component
+  include Brut::I18n::ForHTML
+  # Creates the component
+  # @param timestamp [Time] the timestamp you wish to render. Mutually exclusive with `date`.
+  # @param date [Date] the date you wish to render. Mutually exclusive with `timestamp`.
+  # @param format [Symbol] the I18n format key fragment to use to locate the strftime format for formatting the timestamp.  This is appended to `"time.formats."` to form the full string. If `skip_year_if_same` is true *and* the year of this timestamp is this year, `"_no_year"` is further appended.  For example, if this value is `:full` and `skip_year_if_same` is false, the I18n key used will be `"time.formats.full"`.  If `skip_year_if_same` is true, the key would be `"time.formats.full_no_year"` only if this year is the year of the timestamp. Otherwise `"time.formats.full"` would be used.
+  # @param skip_year_if_same [true|false] if true, and this year is the same year as the timestamp, `"_no_year"` is appened to the value of `format` to form the I18n key to use.  This is applied before `skip_dow_if_not_this_week`'s suffix is.
+  # @param skip_dow_if_not_this_week [true|false] if true, and the date/timestamp is within 7 days of now, appends `"no_dow"` to the format string. If this matches a configured format, it's assumed that would be just like `format` but without the day of the week.  This is applied after `skip_year_if_same`'s suffix is.
+  # @param attribute_format [Symbol] the I18n format key fragment to use to locate the strftime format for formatting *the `datetime` attribute* of the HTML element that this component renders. Generally, you want to leave this as the default of `:iso_8601`, however if you need to change it, you can.  This value is appeneded to `"time.formats."` to form the complete key. `skip_year_if_same` is not used for this value.
+  # @param only_contains_class [Hash] exists because `class` is a reserved word
+  # @option only_contains_class [String] :class the value to use for the `class` attribute.
+  def initialize(
+    timestamp: nil,
+    date: nil,
+    format: :full,
+    skip_year_if_same: true,
+    skip_dow_if_not_this_week: true,
+    attribute_format: :iso_8601,
+    **only_contains_class
+  )
+    require_exactly_one!(timestamp:,date:)
+
+    @date_only = timestamp.nil?
+    @timestamp = timestamp || date
+
+    formats = [ format ]
+    use_no_year = skip_year_if_same && @timestamp.year == Time.now.year
+    use_no_dow  = if skip_dow_if_not_this_week
+                    $seven_days_ago = (Date.today - 7).to_time
+                    $timestamp      = @timestamp.to_time
+                    $timestamp < $seven_days_ago
+                  else
+                    false
+                  end
+    if use_no_year
+      formats.unshift("#{format}_no_year")
+    end
+
+    if use_no_dow
+      if use_no_year
+        formats.unshift("#{format}_no_year_no_dow")
+      else
+        formats.unshift("#{format}_no_dow")
+      end
+    end
+
+    assumed_key_base = if @date_only
+                         "date.formats"
+                       else
+                         "time.formats"
+                       end
+
+    format_keys = formats.map { |f| "#{assumed_key_base}.#{f}" }
+
+    found_format,_value = formats.zip( ::I18n.t(format_keys) ).detect { |(_key,value)|
+      value !~ /^Translation missing/
+    }
+
+    if found_format.nil?
+      raise ArgumentError,"format #{format} is not a known time format (checked #{format_keys})"
+    end
+
+    @format           = found_format.to_sym
+    @attribute_format = attribute_format.to_sym
+    @class_attribute  = only_contains_class[:class] || ""
+  end
+
+  def render(clock:)
+    adjusted_value = if @date_only
+                       @timestamp
+                     else
+                       clock.in_time_zone(@timestamp)
+                     end
+
+    datetime_attribute = ::I18n.l(adjusted_value,format: @attribute_format)
+
+    html_tag(:time, class: @class_attribute, datetime: datetime_attribute) do
+      ::I18n.l(adjusted_value,format: @format)
+    end
+  end
+
+private
+
+  def require_exactly_one!(timestamp:,date:)
+    if timestamp.nil? && date.nil?
+      raise ArgumentError,"one of timestamp: or date: are required"
+    elsif !timestamp.nil? && !date.nil?
+      raise ArgumentError,"only one of timestamp: or date: may be given"
+    end
+  end
+
+
+end

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

@@ -0,0 +1,22 @@
+# Renders the traceparent value for the current trace so that the front-end can add additional spans.
+class Brut::FrontEnd::Components::Traceparent < Brut::FrontEnd::Component
+  def initialize
+    propagator = OpenTelemetry::Trace::Propagation::TraceContext::TextMapPropagator.new
+    carrier = {}
+    current_context = OpenTelemetry::Context.current
+    propagator.inject(carrier, context: current_context)
+    @traceparent = carrier["traceparent"]
+  end
+
+  def render
+    attributes = {
+      name: "traceparent"
+    }
+    if @traceparent
+      attributes[:content] = @traceparent
+    else
+      attributes["data-no-traceparent"] = "no traceparent was available - this component may have been rendered outside of an existing OpenTelemetry context"
+    end
+    html_tag(:meta, **attributes)
+  end
+end

data/lib/brut/front_end/download.rb

@@ -1,7 +1,17 @@
+# Represents a file the browser is going to download. This can be returned from a handler to initiate a download instead of rendering
+# content.
 class Brut::FrontEnd::Download
 
+  # @return [Object] the data to be sent in the download
   attr_reader :data
 
+  # Create a download
+  #
+  # @param [String] filename The name (or base name) of the file name that will be downloaded.
+  # @param [Object] data the data/contents of the file to download
+  # @param [String] content_type the MIME content type to let the browser know what type of file this is.
+  # @param [Time] timestamp if given, will be used with `filename` to set the filename of the file.  This is useful if your users will
+  #               download the same file mulitple times but you want to make each name different and meaningful.
   def initialize(filename:,data:,content_type:,timestamp: false)
     @filename     = filename
     @data         = data
@@ -9,6 +19,7 @@ class Brut::FrontEnd::Download
     @timestamp    = timestamp
   end
 
+  # Access the necessary HTTP headers to allow this file to be downloaded
   def headers
     filename = if @timestamp
                  Time.now.strftime("%Y-%m-%dT%H-%M-%S") + "-" + @filename

data/lib/brut/front_end/flash.rb

@@ -1,4 +1,12 @@
+# A hash that can be used to pass short-lived information across requests. Generally, this is useful for storing error and status
+# messages.  Generally, you won't create instances of this class. You may subclass it, to provide your own additional API for your
+# app's needs. To do that, you must call `Brut.container.override("flash_class",«your class»)`.
 class Brut::FrontEnd::Flash
+
+  # Create a flash from a hash of values.
+  #
+  # @param [Hash] hash the values that should comprise the hash.  Note that this hash is not exactly how the flash stores itself
+  # internally.
   def self.from_h(hash)
     hash ||= {}
     self.new(
@@ -6,6 +14,11 @@ class Brut::FrontEnd::Flash
       messages: hash[:messages] || {}
     )
   end
+
+  # Create a new flash of a given age with the given messages initialized
+  #
+  # @param [Integer] age the age of this flash. See {#age!}.
+  # @param [Hash] messages the flash messages to use. Note that `:notice` and `:alert` are special. See {#notice=} and {#alert=}.
   def initialize(age: 0, messages: {})
     @age = age.to_i
     if !messages.kind_of?(Hash)
@@ -14,23 +27,39 @@ class Brut::FrontEnd::Flash
     @messages = messages
   end
 
+  # Clear the flash and reset its age to 0.
   def clear!
     @age = 0
     @messages = {}
   end
 
+  # Set the "notice", which is an informational message.  The value is intended to be an I18N key.
+  #
+  # @param [String] notice the I18n key of the notice.  You can use any value you like, but you should decide one way or the other,
+  # because it will be confusing to use an I18n key sometimes and sometimes a message.
   def notice=(notice)
     self[:notice] = notice
   end
+  # Access the notice. See {#notice=}
   def notice = self[:notice]
+
+  # True if there is a notice
   def notice? = !!self.notice
 
+  # Set the "alert", which is an important error message.  The value is intended to be an I18N key.
+  #
+  # @param [String] alert the I18n key of the notice.  You can use any value you like, but you should decide one way or the other,
+  # because it will be confusing to use an I18n key sometimes and sometimes a message.
   def alert=(alert)
     self[:alert] = alert
   end
+  # Access the alert. See {#alert=}
   def alert = self[:alert]
+  # True if there is an alert
   def alert? = !!self.alert
 
+  # Age this flash.  The flash's age is the number of requests in the session it has existed for.  This implementation prevents a
+  # flash from being more than 1 request old.  This is usually sufficient for a handler to send information across a redirect.
   def age!
     @age += 1
     if @age > 1
@@ -39,15 +68,18 @@ class Brut::FrontEnd::Flash
     end
   end
 
+  # Access an arbitrary flash message
   def [](key)
     @messages[key]
   end
 
+  # Set an arbitrary flash message. This resets the flash's age by one request.
   def []=(key,message)
     @messages[key] = message
     @age = [0,@age-1].max
   end
 
+  # Conver this flash into a hash, suitable for passing to {.from_h}
   def to_h
     {
       age: @age,