brut 0.0.1 → 0.0.2

data/lib/brut/framework/errors.rb

@@ -1,13 +1,31 @@
 module Brut
   module Framework
+    # Include this in your class to access some helpful methods that throw commonly-needed
+    # errors
     module Errors
       autoload(:Bug,"brut/framework/errors/bug")
+      autoload(:NotImplemented,"brut/framework/errors/not_implemented")
       autoload(:NotFound,"brut/framework/errors/not_found")
+      autoload(:MissingParameter,"brut/framework/errors/missing_parameter")
       autoload(:AbstractMethod,"brut/framework/errors/abstract_method")
+      autoload(:NoClassForPath,"brut/framework/errors/no_class_for_path")
+      # Raises {Brut::Framework::Errors::Bug}
+      #
+      # @param message Message to include in the error
+      # @raise [Brut::Framework::Errors::Bug]
       def bug!(message=nil)
         raise Brut::Framework::Errors::Bug,message
       end
+
+      # Raises {Brut::Framework::Errors::AbstractMethod}
+      # @raise [Brut::Framework::Errors::AbstractMethod]
+      def abstract_method!
+        raise Brut::Framework::Errors::AbstractMethod
+      end
     end
+    # Base class for errors thrown by Brut classes. Generally, Brut will not create its own version
+    # of an error that exists in the standard library, e.g. `ArgumentError`, so this is only a base class
+    # for Brut-specific error conditions.
     class Error < StandardError
     end
   end

data/lib/brut/framework/fussy_type_enforcement.rb

@@ -1,17 +1,22 @@
-# Include this to enable methods to help with type checking.  Generally, you should not use this
-# unless there is a real concern that someone will pass the wrong type in and it would not be obvious
-# that they made this mistake.  Of note, this is preferred for widely used classes instead of trying
-# to convert arguments to whatever type the class needs.
+# Include this to enable methods to help with type checking.  Generally, you should not use this.
+# You should only really use this if all of the following are true:
+#
+# * Passing in the wrong type Would Be Bad.
+# * The developer passing it in would not easily be able to figure out what went wrong.
 module Brut::Framework::FussyTypeEnforcement
-  # Perform basic type checking, ideally inside a constructor when assigning ivars
+  # Perform basic type checking, ideally inside a constructor when assigning ivars.  This is really intended for internal
+  # classes that will not be exposed to user input, but rather to catch programmer bugs and programmer mis-use.
   #
-  # value:: the value that was given
-  # type_descriptor:: a class or an array of allowed values. If a class, value must be kind_of? that class. If an array,
-  #                   value must be one of the values in the array.
-  # variable_name_for_error_message:: the name of the variable so that error messages make sense
-  # required:: if true, the value may not be nil. If false, nil values are allowed and no real type checking is done. Note that a
-  #            string that is blank counts as nil, so a require string must not be blank.
-  # coerce:: if given, this is the symbol that will be used to coerce the value before type checking
+  # @param [Object] value the value that is to be type-checked
+  # @param [Class|Array<Object>] type_descriptor a class or an array of allowed values. If a class, `value` must be `kind_of?`
+  #                                              that class. If an array, `value` must be one of the values in the array.
+  # @param [String] variable_name_for_error_message the name of the variable begin type-checked so that error messages make sense
+  # @param [true|false] required if true, the value may not be nil. If false, nil values are allowed. Note that in this context
+  #                              a blank string counts as `nil`, so required strings may not be blank.
+  # @param [Symbol|false] coerce if set, this is the symbol that will be used to coerce the value before type checking.
+  #                              For example, if you accept a string but know it should be a number, pass in `:to_i`.
+  # @return [Object] the value, if it matches the expectations of its type
+  # @raise [ArgumentError] if the value doesn't confirm to the described type
   def type!(value,type_descriptor,variable_name_for_error_message, required: false, coerce: false)
 
     value_blank = value.nil? || ( value.kind_of?(String) && value.strip == "" )

data/lib/brut/framework/mcp.rb

@@ -6,10 +6,17 @@ require "sequel"
 require "semantic_logger"
 require "i18n"
 require "zeitwerk"
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
 
-# Represents the Brut framework and its behavior for the app that requires it.
-# Essentially, this handles all default configuration and default setup behavior.
+
+# The Master Control Program of Brut.  This handles all the bootstrapping and setup of your app. You are not
+# intended to use or interact with this class at all. End of line.
 class Brut::Framework::MCP
+
+  # Create the MCP.
+  #
+  # @param [Class] app_klass subclass of {Brut::Framework::App} representing the Brut app being started up and managed.
   def initialize(app_klass:)
     @config    = Brut::Framework::Config.new
     @booted    = false
@@ -18,6 +25,8 @@ class Brut::Framework::MCP
     self.configure!
   end
 
+  # Configure Brut and initialize the {Brut::Framework::App} subclass. This should, in theory, only set up values and other
+  # ancillary data needed to start the app. It should not connect to databases.
   def configure!
     @config.configure!
 
@@ -37,11 +46,11 @@ class Brut::Framework::MCP
     end
     SemanticLogger["Brut"].info("Logging set up")
 
-    i18n_locales_path = Brut.container.config_dir / "i18n"
-    locales = Dir[i18n_locales_path / "*"].map { |_|
+    i18n_locales_dir = Brut.container.i18n_locales_dir
+    locales = Dir[i18n_locales_dir / "*"].map { |_|
       Pathname(_).basename
     }
-    ::I18n.load_path += Dir[i18n_locales_path / "**/*.rb"]
+    ::I18n.load_path += Dir[i18n_locales_dir / "**/*.rb"]
     ::I18n.available_locales = locales.map(&:to_s).map(&:to_sym)
 
     Brut.container.store(
@@ -71,6 +80,7 @@ class Brut::Framework::MCP
     else
       SemanticLogger["Brut"].info("Classes will not be auto-reloaded")
     end
+
     @loader.setup
     @app = @app_klass.new
   end
@@ -87,11 +97,30 @@ class Brut::Framework::MCP
     end
     Kernel.at_exit do
       begin
-      Brut.container.sequel_db_handle.disconnect
+        Brut.container.sequel_db_handle.disconnect
       rescue Sequel::DatabaseConnectionError
         SemanticLogger["Sequel::Database"].info "Not connected to database, so not disconnecting"
       end
     end
+    OpenTelemetry::SDK.configure do |c|
+      c.service_name = @app.id
+      if ENV["OTEL_TRACES_EXPORTER"]
+        SemanticLogger[self.class].info "OTEL_TRACES_EXPORTER was set (to '#{ENV['OTEL_TRACES_EXPORTER']}'), so Brut's OTel logging is disabled"
+      else
+        c.add_span_processor(
+          OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
+            Brut::Instrumentation::LoggerSpanExporter.new
+          )
+        )
+      end
+    end
+
+    Brut.container.store(
+      "tracer",
+      OpenTelemetry::SDK::Trace::Tracer,
+      "Tracer for Open Telemetry",
+      OpenTelemetry.tracer_provider.tracer(@app.id)
+    )
 
     Sequel::Database.extension :pg_array
     Sequel::Database.extension :brut_instrumentation
@@ -100,9 +129,10 @@ class Brut::Framework::MCP
 
     Sequel::Model.db = sequel_db
 
-
     Sequel::Model.plugin :find_bang
     Sequel::Model.plugin :created_at
+    Sequel::Model.plugin :table_select
+    Sequel::Model.plugin :skip_saving_columns
 
     if !Brut.container.external_id_prefix.nil?
       Sequel::Model.plugin :external_id, global_prefix: Brut.container.external_id_prefix
@@ -113,9 +143,6 @@ class Brut::Framework::MCP
     else
       SemanticLogger["Brut"].info("Lazily loading app's classes")
     end
-    Brut.container.instrumentation.subscribe do |event:,start:,stop:,exception:|
-      SemanticLogger["Instrumentation"].info("#{event.category}/#{event.subcategory}/#{event.name}: #{start}/#{stop} = #{stop-start}: #{exception&.message} (#{event.details})")
-    end
     @app.boot!
 
     require "sinatra/base"
@@ -123,14 +150,39 @@ class Brut::Framework::MCP
     @sinatra_app = Class.new(Sinatra::Base)
     @sinatra_app.include(Brut::SinatraHelpers)
 
+    message = if Brut.container.project_env.development?
+                "Form submission did not include an authenticity token. All forms must include one. To add one, use the `form_tag` helper, or include <%= component(Brut::FrontEnd::Components::Inputs::CsrfToken) %> somewhere inside your <form> tag"
+              else
+                "Forbidden"
+              end
     default_middlewares = [
-      [ Rack::Protection::AuthenticityToken, [ { allow_if: ->(env) { env["PATH_INFO"] =~ /^\/__brut\// } } ] ],
+      [ Brut::FrontEnd::Middlewares::OpenTelemetrySpan ],
+      [ Brut::FrontEnd::Middlewares::AnnotateBrutOwnedPaths ],
+      [ Brut::FrontEnd::Middlewares::Favicon ],
+      [
+        Rack::Protection::AuthenticityToken,
+        [
+          {
+            allow_if: ->(env) { env["brut.owned_path"] },
+            message: message,
+          }
+        ]
+      ],
     ]
     if Brut.container.auto_reload_classes?
       default_middlewares << Brut::FrontEnd::Middlewares::ReloadApp
     end
 
-    middlewares = default_middlewares + @app.class.middleware
+    middlewares = default_middlewares + @app.class.middleware.map { |(middleware,args,block)|
+      if !middleware.kind_of?(Class)
+        klass = middleware.to_s.split(/::/).reduce(Module) { |mod,part|
+          mod.const_get(part)
+        }
+        [ klass, args, block ]
+      else
+        [ middleware, args, block ]
+      end
+    }
 
     middlewares.each do |(middleware,args,block)|
       @sinatra_app.use(middleware,*args,&block)
@@ -158,47 +210,51 @@ class Brut::Framework::MCP
         @sinatra_app.send(method) do
           args = {}
 
-          hook_method.parameters.each do |(type,name)|
-            if name.to_s == "**" || name.to_s == "*"
-              raise ArgumentError,"#{method.class}##{method.name} accepts '#{name}' and not keyword args. Define it in your class to accept the keyword arguments your method needs"
-            end
-            if ![ :key,:keyreq ].include?(type)
-              raise ArgumentError,"#{name} is not a keyword arg, but is a #{type}"
+          Brut.container.instrumentation.span("#{klass_name}.#{method}") do |span|
+            hook_method.parameters.each do |(type,name)|
+              if name.to_s == "**" || name.to_s == "*"
+                raise ArgumentError,"#{method.class}##{method.name} accepts '#{name}' and not keyword args. Define it in your class to accept the keyword arguments your method needs"
+              end
+              if ![ :key,:keyreq ].include?(type)
+                raise ArgumentError,"#{name} is not a keyword arg, but is a #{type}"
+              end
+
+              if name == :request_context
+                args[name] = Thread.current.thread_variable_get(:request_context)
+              elsif name == :session
+                args[name] = Brut.container.session_class.new(rack_session: session)
+              elsif name == :request
+                args[name] = request
+              elsif name == :response
+                args[name] = response
+              elsif name == :env
+                args[name] = env
+              elsif type == :keyreq
+                raise ArgumentError,"#{method} argument '#{name}' is required, but it's not available in a #{method} hook"
+              else
+                # this keyword arg has a default value which will be used
+              end
             end
 
-            if name == :request_context
-              args[name] = Thread.current.thread_variable_get(:request_context)
-            elsif name == :app_session
-              args[name] = Brut.container.session_class.new(rack_session: session)
-            elsif name == :request
-              args[name] = request
-            elsif name == :response
-              args[name] = response
-            elsif name == :env
-              args[name] = env
-            elsif type == :keyreq
-              raise ArgumentError,"#{method} argument '#{name}' is required, but it's not available in a #{method} hook"
+            hook = klass.new
+            span.add_prefixed_attributes("#{method}.args",args.map { |k,v| [ k,v.class] }.to_h )
+            result = hook.send(method,**args)
+            span.add_attributes(result:)
+            case result
+            in URI => uri
+              redirect to(uri.to_s)
+            in Brut::FrontEnd::HttpStatus => http_status
+              halt http_status.to_i
+            in FalseClass
+              halt 500
+            in NilClass
+              nil
+            in TrueClass
+              nil
             else
-              # this keyword arg has a default value which will be used
+              raise NoMatchingPatternError, "Result from #{method} hook #{klass}'s #{method} method was a #{result.class} (#{result.to_s} as a string), which cannot be used to understand the response to generate. Return nil or true if processing should proceed"
             end
           end
-
-          hook = klass.new
-          result = hook.send(method,**args)
-          case result
-          in URI => uri
-            redirect to(uri.to_s)
-          in Brut::FrontEnd::HttpStatus => http_status
-            halt http_status.to_i
-          in FalseClass
-            halt 500
-          in NilClass
-            nil
-          in TrueClass
-            nil
-          else
-            raise NoMatchingPatternError, "Result from #{method} hook #{klass}'s #{method} method was a #{result.class} (#{result.to_s} as a string), which cannot be used to understand the response to generate. Return nil or true if processing should proceed"
-          end
         end
       end
     end
@@ -208,8 +264,9 @@ class Brut::Framework::MCP
 
     @booted = true
   end
+  # @!visibility private
   def sinatra_app = @sinatra_app
+  # @!visibility private
   def app = @app
 
-
 end

data/lib/brut/framework/project_environment.rb

@@ -1,4 +1,9 @@
+# Manages the interpretation of dev/test/prod. The canonical instance is available via `Brut.container.project_env`.  Generally, you
+# should avoid basing logic on this, or at least contain the conditional behavior to the configuration values. But, you do you.
 class Brut::Framework::ProjectEnvironment
+  # Create the project environment based on the string
+  # @param [String] string_value value from e.g. `ENV["RACK_ENV"]` to use to set the environment
+  # @raise [ArgumentError] if the string does not map to a known environment.
   def initialize(string_value)
     @value = case string_value
     when "development" then "development"
@@ -9,10 +14,14 @@ class Brut::Framework::ProjectEnvironment
     end
   end
 
+  # @return [true|false] true is this is development
   def development? = @value == "development"
+  # @return [true|false] true is this is test
   def test?        = @value == "test"
+  # @return [true|false] true is this is production
   def production?  = @value == "production"
 
+  # @return [String] the string value (which should be suitable for the constructor)
   def to_s = @value
 end
 

data/lib/brut/framework.rb

@@ -1,4 +1,5 @@
 module Brut
+  # The Framework module holds a lot of Brut's internals, or classes that cut across the back end and front end.
   module Framework
     autoload(:App,"brut/framework/app")
     autoload(:Config,"brut/framework/config")

data/lib/brut/front_end/asset_metadata.rb

@@ -1,5 +1,10 @@
-
+# Class to provide access to the asset metadata used to serve up hashed assets. Generally, you will not interact with this class.
+#
+# @!visibility private
 class Brut::FrontEnd::AssetMetadata
+
+  # @param [String] asset_metadata_file to the asset metadata file
+  # @param [IO] out IO on which to write messaging
   def initialize(asset_metadata_file:,out:$stdout)
     @asset_metadata_file = asset_metadata_file
     @out = out
@@ -49,6 +54,7 @@ class Brut::FrontEnd::AssetMetadata
     end
   end
 
+  # @!visibility private
   class ESBuildMetafile
     def initialize(metafile:)
       @metafile = metafile

data/lib/brut/front_end/component.rb

@@ -2,46 +2,40 @@ require "json"
 require "rexml"
 require_relative "template"
 
+# Components holds Brut-provided components that are of general use to any web app
 module Brut::FrontEnd::Components
   autoload(:FormTag,"brut/front_end/components/form_tag")
   autoload(:Input,"brut/front_end/components/input")
   autoload(:Inputs,"brut/front_end/components/input")
   autoload(:I18nTranslations,"brut/front_end/components/i18n_translations")
-  autoload(:Timestamp,"brut/front_end/components/timestamp")
+  autoload(:Time,"brut/front_end/components/time")
   autoload(:PageIdentifier,"brut/front_end/components/page_identifier")
   autoload(:LocaleDetection,"brut/front_end/components/locale_detection")
+  autoload(:ConstraintViolations,"brut/front_end/components/constraint_violations")
+  autoload(:Traceparent,"brut/front_end/components/traceparent")
 end
+
 # A Component is the top level class for managing the rendering of 
 # content.  A component is essentially an ERB template and a class whose
-# instance servces as it's binding.
+# instance servces as it's binding. It is very similar to a View Component, though
+# not quite as fancy.
+#
+# When subclassing this to create a component, your initializer's signature will determine what data
+# is required for your component to work.  It can be anything, just keep in mind that any page or component
+# that uses your component must be able to provide those values.
+#
+# If your component does not override {#render} (which, generally, it won't), an ERB file is expected to exist alongside it in the
+# app.  For example, if you have a component named `Auth::LoginButtonComponent`, it would expected to be in
+# `app/src/front_end/components/auth/login_button_component.rb`.  Thus, Brut will also expect
+# `app/src/front_end/components/auth/login_button_component.html.erb` to exist as well. That ERB file is used with an instance of your
+# component's class to render the component's HTML.
 #
-# The component has a few more smarts and helpers.
+# @see Brut::FrontEnd::Component::Helpers
 class Brut::FrontEnd::Component
   using Brut::FrontEnd::Templates::HTMLSafeString::Refinement
 
-  class TemplateLocator
-    def initialize(paths:, extension:)
-      @paths     = Array(paths).map { |path| Pathname(path) }
-      @extension = extension
-    end
-
-    def locate(base_name)
-      paths_to_try = @paths.map { |path|
-        path / "#{base_name}.#{@extension}"
-      }
-      paths_found = paths_to_try.select { |path|
-        path.exist?
-      }
-      if paths_found.empty?
-        raise "Could not locate template for #{base_name}. Tried: #{paths_to_try.map(&:to_s).join(', ')}"
-      end
-      if paths_found.length > 1
-        raise "Found more than one valid pat for #{base_name}.  You must rename your files to disambiguate them. These paths were all found: #{paths_found.map(&:to_s).join(', ')}"
-      end
-      return paths_found[0]
-    end
-  end
 
+  # @!visibility private
   class AssetPathResolver
     def initialize(metadata_file:)
       @metadata_file = metadata_file
@@ -58,8 +52,10 @@ class Brut::FrontEnd::Component
     end
   end
 
+  # Allows helpers that create components to pass the block they were given to the component
   attr_writer :yielded_block
 
+  # Intended to be called by subclasses to render the yielded block wherever it makes sense in their markup.
   def render_yielded_block
     if @yielded_block
       @yielded_block.().html_safe!
@@ -69,17 +65,25 @@ class Brut::FrontEnd::Component
 	end
 
   # The core method of a component. This is expected to return
-  # a string to be sent as a response to an HTTP request.
+  # a string to be sent as a response to an HTTP request. Generally, you should not call this method
+  # as it is intended to be called from {Brut::FrontEnd::Component::Helpers#component}.
   #
   # This implementation uses the associated template for the component
   # and sends it through ERB using this component as
   # the binding.
+  #
+  # You may override this method to provide your own HTML for the component. In doing so, you can add
+  # keyword args for data from the `RequestContext` you wish to receive. See {Brut::FrontEnd::RequestContext#as_method_args}.
+  #
+  # @return [Brut::FrontEnd::Templates::HTMLSafeString] string containing the component's HTML.
   def render
     Brut.container.component_locator.locate(self.template_name).
       then { |erb_file| Brut::FrontEnd::Template.new(erb_file) }.
       then { |template| template.render_template(self).html_safe! }
   end
 
+  # For components that are private to a page, this returns the name of the page they are a part of.
+  # This is used to allow a component to render a page's I18n strings.
   def page_name
     @page_name ||= begin
                      page = self.class.name.split(/::/).reduce(Module) { |accumulator,class_path_part|
@@ -97,7 +101,9 @@ class Brut::FrontEnd::Component
                    end
   end
 
+  # Used when an I18n string needs access to component-specific translations
   def self.component_name = self.name
+  # (see .component_name)
   def component_name = self.class.component_name
 
   # Helper methods that subclasses can use.
@@ -110,27 +116,45 @@ class Brut::FrontEnd::Component
 
     # Render a component. This is the primary way in which
     # view re-use happens.  The component instance will be able to locate its
-    # HTML template and render itself.
+    # HTML template and render itself.  {#render} is called with variables from the `RequestContext`
+    # as described in {Brut::FrontEnd::RequestContext#as_method_args}
+    #
+    # @param [Brut::FrontEnd::Component|Class] component_instance instance of the component to render. If a `Class`
+    #                                          is passed, it must extend {Brut::FrontEnd::Component}. It will created
+    #                                          based on the logic described in {Brut::FrontEnd::RequestContext#as_constructor_args}.
+    #                                          You would do this if your component needs to be injected with information 
+    #                                          not available to the page or component that is using it.
+    # @yield this block is passed to the `component_instance` via {#yielded_block=}.
+    #
+    # @return [Brut::FrontEnd::Templates::HTMLSafeString] of the rendered component.
     def component(component_instance,&block)
+      component_name = component_instance.kind_of?(Class) ? component_instance.name : component_instance.class.name
+      Brut.container.instrumentation.span(component_name) do |span|
       if component_instance.kind_of?(Class)
         if !component_instance.ancestors.include?(Brut::FrontEnd::Component)
           raise ArgumentError,"#{component_instance} is not a component and cannot be created"
         end
-        Thread.current.thread_variable_get(:request_context).
+        component_instance = Thread.current.thread_variable_get(:request_context).
           then { |request_context| request_context.as_constructor_args(component_instance,request_params: nil)
-        }.then { |constructor_args| component_instance.new(**constructor_args)
-        } => component_instance
+        }.then { |constructor_args| component_instance.new(**constructor_args) }
+        span.add_attributes("global_component" => true, "class" => component_instance.class.name)
+      else
+        span.add_attributes("global_component" => false, "class" => component_instance.class.name)
       end
       if !block.nil?
         component_instance.yielded_block = block
       end
-      request_context = Thread.current.thread_variable_get(:request_context).
-        then { |request_context| request_context.as_method_args(component_instance,:render,request_params: nil, form: nil)
-      }.then { |render_args| component_instance.render(**render_args).html_safe!
+      Thread.current.thread_variable_get(:request_context).then {
+        it.as_method_args(component_instance,:render,request_params: nil, form: nil)
+      }.then { |render_args|
+        component_instance.render(**render_args).html_safe!
       }
+      end
     end
 
     # Inline an SVG into the page.
+    #
+    # @param [String] svg name of an SVG file, relative to where SVGs are stored.
     def svg(svg)
       Brut.container.svg_locator.locate(svg).then { |svg_file|
         File.read(svg_file).html_safe!
@@ -141,19 +165,67 @@ class Brut::FrontEnd::Component
     # the same value, but with any content hashes that are part of the filename.
     def asset_path(path) = Brut.container.asset_path_resolver.resolve(path)
 
-    # Render a form that should include CSRF protection.
-    def form_tag(**attributes,&block)
-      component(Brut::FrontEnd::Components::FormTag.new(**attributes,&block))
+    # 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.
+    #
+    # @example Route without parameters
+    #   <%= form_tag(for: NewWidgetForm, class: "new-form") do %>
+    #     <input type="text" name="name">
+    #     <button>Create</button>
+    #   <% end %>
+    #
+    # @example Route with parameters
+    #   <%= form_tag(for: SaveWidgetWithIdForm, route_params: { id: widget.external_id }, class: "new-form") do %>
+    #     <input type="text" name="name">
+    #     <button>Save</button>
+    #   <% end %>
+    #
+    # @param route_params [Hash] if the form requires route parameters, their values must be passed here so that the HTML `action`
+    # attribute can be constructed properly.
+    # @param html_attributes [Hash] any additional attributes for the `<form>` tag
+    # @option html_attributes [Class|Brut::FrontEnd::Form] :for the form object or class representing this HTML form. If you pass this, you may not pass the HTML attributes `:action` or `:method`. Both will be derived from this object.
+    # @option html_attributes [String] «any-other-key» attributes to set on the `<form>` tag
+    # @yield No parameters given. This is expected to return additional markup to appear inside the `<form>` element.
+    def form_tag(route_params: {}, **html_attributes,&contents)
+      component(Brut::FrontEnd::Components::FormTag.new(route_params:, **html_attributes,&contents))
+    end
+
+    # Creates a {Brut::FrontEnd::Components::Time}.
+    #
+    # @param timestamp [Time] the timestamp to format/render. Mutually exclusive with `date`.
+    # @param date [Date] the date to format/render. Mutually exclusive with `timestamp`.
+    # @param component_options [Hash] keyword arguments to pass to {Brut::FrontEnd::Components::Time#initialize}
+    def time_tag(timestamp:nil,date:nil, **component_options)
+      args = component_options.merge(timestamp:,date:)
+      component(Brut::FrontEnd::Components::Time.new(**args))
+    end
+
+    # Render the {Brut::FrontEnd::Components::ConstraintViolations} component for the given form's input.
+    def constraint_violations(form:, input_name:, message_html_attributes: {}, **html_attributes)
+      component(
+        Brut::FrontEnd::Components::ConstraintViolations.new(
+          form:,
+          input_name:,
+          message_html_attributes:,
+          **html_attributes
+        )
+      )
     end
 
-    def timestamp(timestamp, **component_options)
-      component(Brut::FrontEnd::Components::Timestamp.new(**(component_options.merge(timestamp:))))
+    # Create an HTML input tag for the given input of a form.  This is a convieniece method
+    # that calls {Brut::FrontEnd::Components::Input::TextField.for_form_input}.
+    def input_tag(form:, input_name:, index: nil, **html_attributes)
+      component(Brut::FrontEnd::Components::Inputs::TextField.for_form_input(form:,input_name:,index:,html_attributes:))
     end
 
+    # Indicates a given string is safe to render directly as HTML. No escaping will happen.
+    #
+    # @param [String] string a string that should be marked as HTML safe
     def html_safe!(string)
       string.html_safe!
     end
 
+    # @!visibility private
     VOID_ELEMENTS = [
       :area,
       :base,
@@ -170,6 +242,25 @@ class Brut::FrontEnd::Component
       :wbr,
     ]
 
+    # Generate an HTML element safely in code.  This is useful if you don't want to create
+    # a separate ERB file, but still want to create a component.
+    #
+    # @param [String|Symbol] tag_name the name of the HTML tag to create.
+    # @param [Hash] html_attributes all the HTML attributes you wish to include in the element that is generated.  Values that
+    #                                 are `true` will be included without a value, and values that are `false` will be omitted.
+    # @yield Called to get any contents that should be put into this tag.  Void elements as defined by W3C may not have a block.
+    #
+    # @example Void element
+    #
+    #     html_tag(:img, src: "trellick.png") # => <img src="trellic.png">
+    #
+    # @example Nested elements
+    #
+    #     html_tag(:nav, class: "flex items-center") do
+    #       html_tag(:a, href="/") { "Home" } + 
+    #       html_tag(:a, href="/about") { "About" } + 
+    #       html_tag(:a, href="/contact") { "Contact" }
+    #     end
     def html_tag(tag_name, **html_attributes, &block)
       tag_name = tag_name.to_s.downcase.to_sym
       attributes_string = html_attributes.map { |key,value|