brut 0.0.20 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a6e2324291c72fa3b3012b38b604104ce6d00af875326c20df00cfc42d16a9c
-  data.tar.gz: c16981e60940c676e21590f9a3db5845c8cc77ee2c7dd86eba9cfb8777ac7a32
+  metadata.gz: 13ef62dae2d2a40f20fce1aa2f5df7809fc41ae99b75b2a9aefd25423ef51fb3
+  data.tar.gz: 65b9e0b2b77a441210d0047da5c6c8f77d01d97a954d64626683d11fa7f2f1d1
 SHA512:
-  metadata.gz: b41d3231c6e589b06deb3f668ff42983bf1021757961e1edf5c0b040f8e64dc4c4d4e481bf9feb34a3104371eecd11e5e0a63414a221f8748eca4982cebccec9
-  data.tar.gz: 5896d743754d4e9538a85268a3b72856b3b07ca940798e3732db577d67691fc819b7e927aa2a15a309c4440c7ea10beca45df5473d9ca7247b75e6f83678e4e8
+  metadata.gz: 4a524485b78b02dd2fee75c540b8cef83fc1c79e8ffa6ec8b214995000c42c6e41db5dbfe8ab65fe28b3e9f08eb9edb63f9156e4208618750f3165bf548995ee
+  data.tar.gz: af71268d9598c889731db3cbff39c47d14173ae4112b4eb9e723ff917bf036da93ee4efb3bdffc7f0fc1136abc71b089ab64fe0f8e503226f61e1b0511ffa9f1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.0.20)
+    brut (0.0.21)
       concurrent-ruby
       i18n
       irb

data/lib/brut/back_end/seed_data.rb

@@ -1,10 +1,19 @@
 require_relative "../factory_bot"
 module Brut
   module BackEnd
-    # Base class and manager of Seed Data for the app.  Seed Data is data used for development. It is not for populating e.g.
-    # reference data or other stuff in production.
+    # Base class and manager of Seed Data for the app.  Seed Data is data used for development.
+    # It is not for populating e.g. reference data or other stuff in production, nor is it for
+    # managing test data.
     #
     # Seed Data uses FactoryBot.
+    #
+    # To create your own seed data:
+    #
+    # 1. Inherit from this class.  Doing so will register your class with an internal data structure
+    #    Brut will use to create all seed data.
+    # 2. Provide a no-arg initializer (although you are unlikely to need any initializer at all).
+    # 3. Implement {#seed!} to use Factory Bot to create all the seed data.  This method should be self-contained
+    #    and not rely on other seed data classes.  It need not be idempotent.
     class SeedData
       def self.inherited(seed_data_klass)
         @classes ||= []
@@ -12,10 +21,13 @@ module Brut
       end
       def self.classes = @classes || []
 
+      # Sets up anything needed before seed data can be created. Do not override this method.
       def setup!
         Brut::FactoryBot.new.setup!
       end
 
+      # Loads all seed data registered with this class.  Seed data is registered when a class
+      # extends this one.  Do not override this method.
       def load_seeds!
         DB.transaction do
           self.class.classes.each do |klass|
@@ -23,6 +35,11 @@ module Brut
           end
         end
       end
+
+      # Implement this to create your seed data.
+      def seed!
+        raise Brut::Framework::Errors::AbstractMethod
+      end
     end
   end
 end

data/lib/brut/back_end/sidekiq/middlewares/server.rb

@@ -1,3 +1,4 @@
-class Brut::BackEnd::Sidekiq::Middlewares::Server
+# Useful server middlewares for Sidekiq
+module Brut::BackEnd::Sidekiq::Middlewares::Server
   autoload(:FlushSpans, "brut/back_end/sidekiq/middlewares/server/flush_spans")
 end

data/lib/brut/back_end/sidekiq/middlewares.rb

@@ -1,3 +1,4 @@
-class Brut::BackEnd::Sidekiq::Middlewares
+# Useful middlewares for Sidekiq jobs
+module Brut::BackEnd::Sidekiq::Middlewares
   autoload(:Server, "brut/back_end/sidekiq/middlewares/server")
 end

data/lib/brut/back_end/sidekiq.rb

@@ -1,3 +1,4 @@
-class Brut::BackEnd::Sidekiq
+# Namespace for Sidekiq-related support.
+module Brut::BackEnd::Sidekiq
   autoload(:Middlewares, "brut/back_end/sidekiq/middlewares")
 end

data/lib/brut/back_end/validator.rb

@@ -1,3 +1,7 @@
-class Brut::BackEnd::Validators
+# Namespace for back-end validation support.  Note that in Brut, validators
+# are not a mechanism for ensuring data integrity.  Validators are for helping
+# a website visitor or app user to understand data entry mistakes.  To ensure
+# data integrity, use your databases constraints and other features.
+module Brut::BackEnd::Validators
   autoload(:FormValidator, "brut/back_end/validators/form_validator")
 end

data/lib/brut/back_end.rb

@@ -1,5 +1,7 @@
-# The _back end_ of a Brut app is where your app's business logic and database are managed.  While the bulk of your Brut app's code
-# will be in the back end, Brut is far less prescriptive about how to manage that than it is the front end.
+# The _back end_ of a Brut app is where your app's business logic and
+# database are managed.  While the bulk of your Brut app's code
+# will be in the back end, Brut is far less prescriptive about how to manage
+# that than it is the front end.
 module Brut::BackEnd
   autoload(:Validators, "brut/back_end/validator")
   autoload(:Sidekiq, "brut/back_end/sidekiq")

data/lib/brut/cli.rb

@@ -6,9 +6,10 @@ module Brut
   # that your CLI will respond to. See {Brut::CLI::app}.
   module CLI
 
-    # Execute your CLI based on its command line invocation.  You would call this method inside the executable file placed in `bin/`
-    # in your project.  For example, if you have `YourApp::CLI::CleanOldFiles` and you wish to execute it via `bin/clean-files`, you'd
-    # create `bin/clean-files` like so:
+    # Execute your CLI based on its command line invocation.  You would call this method inside the
+    # executable file placed in `bin/` in your project. 
+    # For example, if you have `YourApp::CLI::CleanOldFiles` and you wish to execute
+    # it via `bin/clean-files`, you'd create `bin/clean-files` like so:
     #
     # ```
     # #!/usr/bin/env ruby

data/lib/brut/factory_bot.rb

@@ -1,7 +1,3 @@
-# Because FactoryBot 6.4.6 has a bug where it is not properly
-# requiring active support, active supporot must be required first,
-# then factory bot.  When 6.4.7 is released, this can be removed. See Gemfile
-require "active_support"
 require "factory_bot"
 require "faker"
 
@@ -17,6 +13,5 @@ class Brut::FactoryBot
       to_create { |instance| instance.save }
     end
     FactoryBot.find_definitions
-
   end
 end

data/lib/brut/framework/app.rb

@@ -1,9 +1,10 @@
 # An "App" in Brut paralance is the collection of source code and configuration that is needed to operate
 # a website. This includes everything needed to serve HTTP requests, but also includes ancillary
-# tasks and any related files required for the app to exist and function.  Your app will have an `App` class that subclasses this
-# class.
+# tasks and any related files required for the app to exist and function.
+# Your app will have an `App` class that subclasses this class.
 #
-# When your app is initialized, Brut will have been configured, but access to internal resources may not be available.  It is here
+# When your app is initialized, Brut will have been configured,
+# but access to internal resources may not be available.  It is here
 # that you can override configuration values or do any other setup before everything boots.
 class Brut::Framework::App
   include Brut::Framework::Errors
@@ -18,7 +19,8 @@ class Brut::Framework::App
   # actions where an app needs to exist inside some organizational context.
   def organization = id
 
-  # Call this in your app's definition to define your app's routes. The contents of the block will be evaluated in the context of
+  # Call this in your app's definition to define your app's routes.
+  # The contents of the block will be evaluated in the context of
   # {Brut::SinatraHelpers::ClassMethods}, and the methods there are generally the ones you should be calling.
   #
   # You can call this multiple times and the routes will be concatenated together.
@@ -31,6 +33,69 @@ class Brut::Framework::App
     end
   end
 
+  # Call this to specify what happens when an unhandled exception occurs.  You may call this mulitple times,
+  # however note that if an error is caught that matches more than one block's condition, the one that is called
+  # will be the first one declared.
+  #
+  # The only deviation from this rule is when you call this
+  # without any condition.  Doing that establishes the behavior for a "catch all" handler, which is
+  # only called when no other configured block can handle the exception. You can declare
+  # this at any time. **Do note** the "catch all" handler is more of a best effort. Brut is currently
+  # based on Sinatra which provides no way to arbitrarily catch all exceptions.  What Brut does here is to 
+  # explicitly catch the range of http status codes from 400 to 999.
+  #
+  # Note that Brut will record the exception via OpenTelemetry so you should not do this in your handlers.  It
+  # would be preferable to instead record an event if you want to have observability from your error handlers.
+  #
+  # @param [Class|Integer|Range<Integer>] condition if given this specifies the conditions under which the given
+  #        block will handle the error.  If omitted, this block will handle any error that doesn't have a more
+  #        specific handler configured.  Meaning of values:
+  #        * A class - this is an exception class that, if caught, triggers the handler
+  #        * An integer - this is an HTTP status code that, if returned, triggers the handler
+  #        * A range of integers - this is a range of HTTP status codes that, if returned, triggers the handler
+  # @yield [Exception] the block is given two named parameters: `exception:` and `http_status_code:`. Your block
+  #        can declare both, either, or none.  Any that are declared will be given values.  At least one
+  #        will be non-`nil`, however are encouraged to code defensively inside this block.
+  # @yieldparam [Exception] exception: the exception that was raised. This will be `nil`
+  #             if the error was caused by an HTTP status code.
+  # @yieldparam [Integer] http_status_code: the HTTP status code that was returned. If `exception:` is
+  #             not `nil`, this value is highly likely to be 500.
+  # @yieldreturn The block should return a valid Rack response. For now.
+  def self.error(condition=:catch_all, &block)
+    @error_blocks ||= {}
+    if block.nil?
+      raise ArgumentError, "You must provide a block to error"
+    end
+    parameters = block.parameters.reject { |type,name|
+      type == :keyreq && [ :http_status_code, :exception ].include?(name)
+    }
+    if parameters.any?
+      messages = parameters.map { |type,name|
+        case type
+        when :keyreq
+          "required keyword parameter '#{name}:'"
+        when :key
+          "optional keyword parameter '#{name}:'"
+        when :rest
+          "rest parameter '#{name}'"
+        when :opt
+          "optional parameter '#{name}'"
+        when :req
+          "required parameter '#{name}'"
+        else
+          "unknown parameter '#{name}'"
+        end
+      }
+      raise ArgumentError, "Your error handler block may only accept exception: and http_status_code: as required keyword parameters.  The following parameters were found:\n  #{messages.join("\n  ")}"
+    end
+    if @error_blocks[condition]
+      raise ArgumentError, "You have already configured error handling for condition '#{condition.to_s}'"
+    end
+    @error_blocks[condition] = block
+  end
+
+  def self.error_blocks = @error_blocks || {}
+
   # Add a Rack middleware to your app. Middlewares are configured in the order in which you call this method.
   #
   # @param [Class] middleware a class that implements [Rack Middleware](https://github.com/rack/rack/blob/main/SPEC.rdoc).
@@ -81,7 +146,7 @@ class Brut::Framework::App
   # code required *after* Brut has been set up and started.  You can rely on the
   # database being available. Any attempts to override configuration values
   # may not succeed.  This is called after the framework has booted, but before
-  # your apps' routes are set up.
+  # your app's routes are set up.
   def boot!
   end
 

data/lib/brut/framework/config.rb

@@ -1,11 +1,13 @@
 require_relative "project_environment"
 require "pathname"
 
-# Holds configuration for the framework and your app.  In general, you should not interact with this class, however it's source code
-# is a good reference for what is configured by default by Brut.
+# Holds configuration for the framework and your app.  In general, you 
+# should not interact with this class, however it's source code is a good 
+# reference for what is configured by default by Brut.
 class Brut::Framework::Config
 
-  # Configures all defaults.  In general, this attempts to be lazy in setting things up, so calling this should not attempt to make a
+  # Configures all defaults.  In general, this attempts to be lazy in
+  # setting things up, so calling this should not attempt to make a
   # connection to your database.
   def configure!
     Brut.container do |c|

data/lib/brut/framework/container.rb

@@ -21,7 +21,8 @@ end
 #
 # There is no namespacing/hierarchy.
 #
-# In general, you should not create instances of this class, but you may need to access it via {Brut.container} in order to obtain
+# In general, you should not create instances of this class, but you may
+# need to access it via {Brut.container} in order to obtain
 # configuration values or set your own.
 class Brut::Framework::Container
   def initialize
@@ -92,7 +93,7 @@ class Brut::Framework::Container
   end
 
   # Called by your app to override an existing value.  The value must be overridable (see {#store}).  Generally, you should call this
-  # in the initializer of your {Brut::Framework::App} subclass.  Calling this after the fact may not have the affect you want.
+  # in the initializer of your {Brut::Framework::App} subclass.  Calling this after the fact may not have the effect you want.
   #
   # @param [String|Symbol] name name of the value to override. Will be coerced to a String. This name must have been previously
   #                             configured.

data/lib/brut/framework/errors.rb

@@ -1,7 +1,7 @@
 module Brut
   module Framework
-    # Include this in your class to access some helpful methods that throw commonly-needed
-    # errors
+    # Namespace for Brut-specific error classes, and a holder of several error-related convienience 
+    # methods.  Include this module to gain access to those methods.
     module Errors
       autoload(:Bug,"brut/framework/errors/bug")
       autoload(:NotImplemented,"brut/framework/errors/not_implemented")
@@ -10,7 +10,12 @@ module Brut
       autoload(:MissingConfiguration,"brut/framework/errors/missing_configuration")
       autoload(:AbstractMethod,"brut/framework/errors/abstract_method")
       autoload(:NoClassForPath,"brut/framework/errors/no_class_for_path")
-      # Raises {Brut::Framework::Errors::Bug}
+      # Raises {Brut::Framework::Errors::Bug}, used to indicate a codepath is a bug.  "But, why write a
+      # bug in the first place?" you may be asking.  Sometimes, a code path exists, but external factors
+      # mean that it should never be executed.  Or, sometimes an API can be mis-used, but the current
+      # state of the system is such that it would never be misused.
+      #
+      # This method allows you to indicate such situations and provide a meaningful explanation.
       #
       # @param message Message to include in the error
       # @raise [Brut::Framework::Errors::Bug]
@@ -18,7 +23,10 @@ module Brut
         raise Brut::Framework::Errors::Bug,message
       end
 
-      # Raises {Brut::Framework::Errors::AbstractMethod}
+      # Raises {Brut::Framework::Errors::AbstractMethod}, which is useful if you need to document
+      # a method that a subclass must implement, but for which there is no useful default
+      # implementation.
+      #
       # @raise [Brut::Framework::Errors::AbstractMethod]
       def abstract_method!
         raise Brut::Framework::Errors::AbstractMethod

data/lib/brut/framework/mcp.rb

@@ -116,8 +116,69 @@ class Brut::Framework::MCP
     @sinatra_app = Class.new(Sinatra::Base)
     @sinatra_app.include(Brut::SinatraHelpers)
 
+    safely_record_exception = ->(exception,http_status_code) {
+      begin
+      if exception.nil?
+        Brut.container.instrumentation.add_event("error triggered without exception", http_status_code:)
+      else
+        Brut.container.instrumentation.record_exception(exception, http_status_code:)
+      end
+      rescue => ex
+        begin
+          SemanticLogger[self.class].error(
+            "Error recording exception",
+            original_excerption: exception, 
+            exception: ex)
+        rescue => ex2
+          $stderr.puts "While handling an error recording an exception, we get another error from SemanticLogger." + [
+            [ :original_exception,  exception,  ].join(": "),
+            [ :exception_from_recording_exception,  ex, ].join(": "),
+            [ :exception_from_semantic_logger,  ex2 ].join(": "),
+
+          ].join(", ")
+        end
+      end
+    }
+
+    @app.class.error_blocks.each do |condition,block|
+      puts "Setting up error handling for #{condition}"
+      if condition != :catch_all
+        @sinatra_app.error(condition) do
+          puts "Error block triggered"
+          exception = request.env["sinatra.error"]
+          safely_record_exception.(exception, response.status)
+          block_args = if exception
+                         puts "Exception: #{exception.class}"
+                         { exception: }
+                       else
+                         puts "HTTP: #{response.status}"
+                         { http_status_code: response.status }
+                       end
+          block.(**block_args)
+        end
+      end
+    end
+    if @app.class.error_blocks[:catch_all]
+      block = @app.class.error_blocks[:catch_all]
+      block_args = block.parameters.map { |(type,name)|
+        [ name, nil ]
+      }.to_h
+      @sinatra_app.error(400..999) do
+        exception = request.env["sinatra.error"]
+        safely_record_exception.(exception, response.status)
+        if block_args.key?(:exception)
+          block_args[:exception] = exception
+        end
+        if block_args.key?(:http_status_code)
+          block_args[:http_status_code] = response.status
+        end
+        block.(**block_args)
+      end
+    else
+    end
+
     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"
+                "Form submission did not include an authenticity token. All forms must include one. To add one, use the `form_tag` helper, or include Brut::FrontEnd::Components::Inputs::CsrfToken somewhere inside your <form> tag"
               else
                 "Forbidden"
               end

data/lib/brut/framework/project_environment.rb

@@ -1,5 +1,7 @@
-# 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.
+# 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
@@ -21,6 +23,8 @@ class Brut::Framework::ProjectEnvironment
   # @return [true|false] true is this is production
   def production?  = @value == "production"
 
+  def staging? = raise "Staging is a lie, please consider feature flags or literally any other way to manage in-development features of your app. I promise you, you will regret ever having to do anything with a staging server"
+
   # @return [String] the string value (which should be suitable for the constructor)
   def to_s = @value
 end

data/lib/brut/framework.rb

@@ -1,5 +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.
+  # Namespace for Brut's internals as well as classes that aren't strictly front or back end.
   module Framework
     autoload(:App,"brut/framework/app")
     autoload(:Config,"brut/framework/config")

data/lib/brut/front_end/component.rb

@@ -16,21 +16,19 @@ module Brut::FrontEnd::Components
 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. It is very similar to a View Component, though
-# not quite as fancy.
+# content.  It is a Phlex component with additional features.
+# Components are the primary mechanism for managing view complexity and managing
+# markup re-use in Brut.
 #
-# 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.
+# To create a component, subclass this class (or, more likely, your app's `AppComponent`) 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 component object.
 #
-# 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.
+# Consult Brut's documentation on keyword injection to know what values you may use and how values are located.
+#
+# 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.
 #
-# @see Brut::FrontEnd::Component::Helpers
 class Brut::FrontEnd::Component < Phlex::HTML
 
   include Brut::Framework::Errors
@@ -53,6 +51,13 @@ 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)
@@ -61,19 +66,27 @@ class Brut::FrontEnd::Component < Phlex::HTML
     }
   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
 
+  # 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(
@@ -98,9 +111,19 @@ class Brut::FrontEnd::Component < Phlex::HTML
     )
   end
 
+  # 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.
   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|

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

@@ -17,7 +17,7 @@
 # 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}.
+# You will most commonly use this component via {Brut::FrontEnd::Component#constraint_violations}.
 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::Helpers#form_tag} method.
+# 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.
 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/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::Helpers#form_tag}.
+# to use this directly if you are building a form without {Brut::FrontEnd::Component#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/text_field.rb

@@ -41,7 +41,7 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
       default_html_attributes[:value] = (index || true).to_s
       default_html_attributes[:checked] = value == "true"
     else
-      default_html_attributes[:value] = value.to_s
+      default_html_attributes[:value] = value.nil? ? nil : value.to_s
     end
     if !form.new? && !input.valid?
       default_html_attributes["data-invalid"] = true

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

@@ -1,4 +1,4 @@
-# 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}.
+# 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}.
 class Brut::FrontEnd::Components::TimeTag < Brut::FrontEnd::Component
   include Brut::I18n::ForHTML
   # Creates the component

data/lib/brut/front_end/layout.rb

@@ -1,3 +1,19 @@
+# A layout is common HTML that surrounds different pages. For example, it would hold your 
+# DOCTYPE, `<head>`, and possibly any common `<body>` elements that every page needs. 
+#
+# A layout is a Phlex component but it must contain a call to `yield` somewhere in the 
+# implementation of `view_template`.
+#
+# This base class contains helper methods needed for implementing a layout.
 class Brut::FrontEnd::Layout < Brut::FrontEnd::Component
+  # Get the actual path of an asset managed by Brut. This handles
+  # locating the asset's URL as well as ensuring the hash is properly
+  # inserted into the filename.
+  #
+  # @param [String] path the path to an asset, such as `/css/styles.css`.
+  #
+  # @return [String] the actual path to the current version of that asset.
+  #
+  # @see Brut::FrontEnd::AssetPathResolver
   def asset_path(path) = Brut.container.asset_path_resolver.resolve(path)
 end