brut 0.0.13 → 0.0.21

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

@@ -21,10 +21,11 @@ class Brut::FrontEnd::Components::Inputs::Select < Brut::FrontEnd::Components::I
                           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
+    default_html_attributes[:required] = input.required
     if !form.new? && !input.valid?
       default_html_attributes["data-invalid"] = true
       input.validity_state.each do |constraint,violated|
@@ -61,36 +62,28 @@ class Brut::FrontEnd::Components::Inputs::Select < Brut::FrontEnd::Components::I
     @selected_value        = selected_value
     @value_attribute       = value_attribute
     @option_text_attribute = option_text_attribute
+    @html_attributes      = html_attributes
 
-    html_attributes["name"] = name
-    @sanitized_attributes  = html_attributes.map { |key,value|
-        [
-          key.to_s.gsub(/[\s\"\'>\/=]/,"-"),
-          value
-        ]
-    }.select { |key,value|
-      !value.nil?
-    }.to_h
+    @html_attributes[:name] = name
   end
 
-  def render
-    html_tag(:select,**@sanitized_attributes) {
-      options = @options.map { |option|
+  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
-        html_tag(:option,**option_attributes) {
+        option(**option_attributes) {
           option.send(@option_text_attribute)
         }
-      }
-      if @include_blank
-        options.unshift(html_tag(:option,**@include_blank.option_attributes) {
-          @include_blank.text_content
-        })
       end
-      options.join("\n")
     }
   end
 private

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

@@ -9,40 +9,39 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
   # @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 = {}
-    html_attributes = html_attributes.map { |key,value| [ key.to_s, value ] }.to_h
+    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
-    default_html_attributes["type"]     = input.type
-    default_html_attributes["name"]     = if input.array?
+    default_html_attributes[:required] = input.required
+    default_html_attributes[:pattern]  = input.pattern
+    default_html_attributes[:type]     = input.type
+    default_html_attributes[:name]     = if input.array?
                                             "#{input.name}[]"
                                           else
                                             input.name
                                           end
 
     if input.max
-      default_html_attributes["max"] = input.max
+      default_html_attributes[:max] = input.max
     end
     if input.maxlength
-      default_html_attributes["maxlength"] = input.maxlength
+      default_html_attributes[:maxlength] = input.maxlength
     end
     if input.min
-      default_html_attributes["min"] = input.min
+      default_html_attributes[:min] = input.min
     end
     if input.minlength
-      default_html_attributes["minlength"] = input.minlength
-    end
+      default_html_attributes[:minlength] = input.minlength end
     if input.step
-      default_html_attributes["step"] = input.step
+      default_html_attributes[:step] = input.step
     end
     value = input.value
 
     if input.type == "checkbox"
-      default_html_attributes["value"] = (index || true).to_s
-      default_html_attributes["checked"] = value == "true"
+      default_html_attributes[:value] = (index || true).to_s
+      default_html_attributes[:checked] = value == "true"
     else
-      default_html_attributes["value"] = value
+      default_html_attributes[:value] = value.nil? ? nil : value.to_s
     end
     if !form.new? && !input.valid?
       default_html_attributes["data-invalid"] = true
@@ -55,30 +54,16 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
     Brut::FrontEnd::Components::Inputs::TextField.new(default_html_attributes.merge(html_attributes))
   end
 
+  def invalid? = @attributes["data-invalid"] == true
+
   # Create an instance
   #
   # @param [Hash] attributes HTML attributes to put on the element.
   def initialize(attributes)
-    @sanitized_attributes = attributes.map { |key,value|
-        [
-          key.to_s.gsub(/[\s\"\'>\/=]/,"-"),
-          value
-        ]
-    }.select { |key,value|
-      !value.nil?
-    }.to_h
+    @attributes = attributes
   end
 
-  def render
-    attribute_string = @sanitized_attributes.map { |key,value|
-      if value == true
-        key
-      elsif value == false
-        ""
-      else
-        REXML::Attribute.new(key,value).to_string
-      end
-    }.join(" ")
-    "<input #{attribute_string}>"
+  def view_template
+    input(**@attributes)
   end
 end

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

@@ -8,22 +8,23 @@ class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components:
   # @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: {})
+    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
-    default_html_attributes["name"]     = if input.array?
+    default_html_attributes[:required] = input.required
+    default_html_attributes[:name]     = if input.array?
                                             "#{input.name}[]"
                                           else
                                             input.name
                                           end
     if input.maxlength
-      default_html_attributes["maxlength"] = input.maxlength
+      default_html_attributes[:maxlength] = input.maxlength
     end
     if input.minlength
-      default_html_attributes["minlength"] = input.minlength
+      default_html_attributes[:minlength] = input.minlength
     end
     if !form.new? && !input.valid?
       default_html_attributes["data-invalid"] = true
@@ -41,31 +42,15 @@ class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components:
   # @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|
-        [
-          key.to_s.gsub(/[\s\"\'>\/=]/,"-"),
-          value
-        ]
-    }.select { |key,value|
-      !value.nil?
-    }.to_h
-    @value = value
+    @attributes = attributes
+    @value      = value
   end
 
-  def sanitized_attributes = @sanitized_attributes
+  def invalid? = @attributes["data-invalid"] == true
 
-  def render
-    attribute_string = @sanitized_attributes.map { |key,value|
-      if value == true
-        key
-      elsif value == false
-        ""
-      else
-        REXML::Attribute.new(key,value).to_string
-      end
-    }.join(" ")
-    %{
-      <textarea #{attribute_string}>#{ @value }</textarea>
+  def view_template
+    textarea(**@attributes) {
+      @value
     }
   end
 end

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

@@ -13,7 +13,7 @@ class Brut::FrontEnd::Components::LocaleDetection < Brut::FrontEnd::Component
     @url      = Brut::FrontEnd::Handlers::LocaleDetectionHandler.routing
   end
 
-  def render
+  def view_template
     attributes = {
       "url" => @url,
     }
@@ -27,6 +27,6 @@ class Brut::FrontEnd::Components::LocaleDetection < Brut::FrontEnd::Component
       attributes["show-warnings"] = true
     end
 
-    html_tag("brut-locale-detection",**attributes)
+    brut_locale_detection(**attributes)
   end
 end

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

@@ -1,15 +1,13 @@
-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
   end
 
-  def render
+  def view_template
     if Brut.container.project_env.production?
-      return ""
+      return nil
     end
-    html_tag(:meta, name: "class", content: @page_name)
+    meta(name: "class", content: @page_name)
   end
 end

data/lib/brut/front_end/components/{time.rb → time_tag.rb}

@@ -1,6 +1,5 @@
-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
+# 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
   # @param timestamp [Time] the timestamp you wish to render. Mutually exclusive with `date`.
@@ -21,13 +20,18 @@ class Brut::FrontEnd::Components::Time < Brut::FrontEnd::Component
     skip_year_if_same: true,
     skip_dow_if_not_this_week: true,
     attribute_format: :iso_8601,
-    **only_contains_class,
-    &contents
+    clock: :from_request_context,
+    **only_contains_class
   )
     require_exactly_one!(timestamp:,date:)
 
     @date_only = timestamp.nil?
     @timestamp = timestamp || date
+    @clock     = if clock == :from_request_context
+                   Brut::FrontEnd::RequestContext.current[:clock]
+                 else
+                   clock
+                 end
 
     formats = [ format ]
     use_no_year = skip_year_if_same && @timestamp.year == Time.now.year
@@ -69,21 +73,20 @@ class Brut::FrontEnd::Components::Time < Brut::FrontEnd::Component
     @format           = found_format.to_sym
     @attribute_format = attribute_format.to_sym
     @class_attribute  = only_contains_class[:class] || ""
-    @contents         = contents
   end
 
-  def render(clock:)
+  def view_template
     adjusted_value = if @date_only
                        @timestamp
                      else
-                       clock.in_time_zone(@timestamp)
+                       @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
-      if @contents
-        @contents.()
+    time(class: @class_attribute, datetime: datetime_attribute) do
+      if block_given?
+        yield
       else
         ::I18n.l(adjusted_value,format: @format)
       end

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

@@ -8,15 +8,14 @@ class Brut::FrontEnd::Components::Traceparent < Brut::FrontEnd::Component
     @traceparent = carrier["traceparent"]
   end
 
-  def render
+  def view_template
     attributes = {
-      name: "traceparent"
+      name: "traceparent",
+      content: @traceparent,
     }
-    if @traceparent
-      attributes[:content] = @traceparent
-    else
+    if !@traceparent
       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)
+    meta(**attributes)
   end
 end

data/lib/brut/front_end/http_method.rb

@@ -1,5 +1,9 @@
+require "phlex"
+
 # Wrapper around an HTTP Method, ensuring it contains only a valid value.
 class Brut::FrontEnd::HttpMethod
+  include Phlex::SGML::SafeObject
+
   # Create an HTTP method from a string.
   #
   # @param [String|Symbol] string a string containing an HTTP method name. Case insensitive, and can be a symbol.

data/lib/brut/front_end/inline_svg_locator.rb

@@ -0,0 +1,21 @@
+class Brut::FrontEnd::InlineSvgLocator
+  def initialize(paths:)
+    @paths = Array(paths).map { |path| Pathname(path) }
+  end
+
+  def locate(base_name)
+    paths_to_try = @paths.map { |path|
+      path / "#{base_name}.svg"
+    }
+    paths_found = paths_to_try.select { |path|
+      path.exist?
+    }
+    if paths_found.empty?
+      raise "Could not locate SVG for #{base_name}. Tried: #{paths_to_try.map(&:to_s).join(', ')}"
+    end
+    if paths_found.length > 1
+      raise "Found more than one valid path 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

data/lib/brut/front_end/layout.rb

@@ -0,0 +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

data/lib/brut/front_end/page.rb

@@ -1,73 +1,71 @@
-# A page backs a web page.  A page renders everything in the browser window.  Technically, it is exactly like a component except that
-# it can have a layout.
+# A Page backs a web page, which handles rendering everything in a browser window when a URL is requested.
+# Technically, a page is identical to a {Brut::FrontEnd::Component}, except that a page has a layout.
+# A {Brut::FrontEnd::Layout} is common HTML that surrounds your page's HTML.
+# Your page is a Phlex component, but instead of implementing `view_template`, you
+# implement {#page_template} to ensure the layout is used.
 #
-# When subclassing this to create a page, your initializer's signature will determine what data
-# is required for your page to work.  It can be anything, just keep in mind that any component your page uses may
-# require additional data.
+# To create a page, after defining a route, subclass this class (or, more likely, your app's `AppPage`) 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 page 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 page named `Auth::LoginPage`, it would expected to be in
-# `app/src/front_end/pages/auth/login_page.rb`.  Thus, Brut will also expect
-# `app/src/front_end/pages/auth/login_page.html.erb` to exist as well. That ERB file is used with an instance of your
-# pages's class to render the page's HTML.
+# Consult Brut's documentation on keyword injection to know what values you may use and how values are located.
 #
 # @see Brut::FrontEnd::Component
+# @see Brut::FrontEnd::Layout
 class Brut::FrontEnd::Page < Brut::FrontEnd::Component
   include Brut::FrontEnd::HandlingResults
-  using Brut::FrontEnd::Templates::HTMLSafeString::Refinement
 
-  # Returns the name of the layout for this page.  This string is used to find an ERB file in `app/src/front_end/layouts`. Every page
-  # must have a layout. If you wish to render a page with no layout, create an empty layout in your app and use that.
+  # Returns the name of the layout for this page.  This string is used to find a class named
+  # `«camelized-layout»Layout` in your app.  The default value is "default", meaning that the class
+  # `DefaultLayout` will be used.
   #
-  # Note that the layout can be dynamic. It is requested when {#render} is called, so you can override this
+  # Note that the layout can be dynamic. It is requested when {#page_template} is called, so you can override this
   # method and use any ivar set in your constructor to change what layout is used.
   #
+  # If your page does not need a layout, you have two options:
+  #
+  # * Create your own blank layout named, e.g. `BlankLayout` and have this method return `"blank"`.
+  # * Implement `view_template` instead of `page_template`, thus overriding this class' implementation that uses
+  #   layouts.
+  #
   # @return [String] The name of the layout. May not be `nil`.
   def layout = "default"
 
-  # Called after the page is created, but before {#render} is called.  This allows you to do any pre-flight checks and potentially
+  # Called after the page is created, but before {#page_template} is called.  This allows you to do any pre-flight checks and potentially
   # redirect the user or produce an error.
   #
-  # @return [URI|Brut::FrontEnd::HttpStatus|Object] If you return a `URI` (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#redirect_to}), the user is redirected and {#render} is never called. If you return a {Brut::FrontEnd::HttpStatus} (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#http_status}), {#render} is skipped and that status is returned with no content.  If anything else is returned, {#render} is called as normal.
+  # @return [URI|Brut::FrontEnd::HttpStatus|Object] If you return a `URI` (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#redirect_to}), the user is redirected and no HTML is generated. If you return a {Brut::FrontEnd::HttpStatus} (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#http_status}), HTML generation is skipped and that status is returned with no content.  If anything else is returned, HTML is generated normal.
   def before_render = nil
 
-  # @!visibility private
+  # Core method of this class. Do not override. This handles the use of {#before_render} and is what Brut
+  # calls to possibly render the page.
   def handle!
     case before_render
     in URI => uri
-      Brut.container.instrumentation.add_event("before_render got a URI", uri: uri)
       uri
     in Brut::FrontEnd::HttpStatus => http_status
-      Brut.container.instrumentation.add_event("before_render got status", http_status: http_status)
       http_status
     else
-      render
+      self.call
     end
   end
 
-  # The core method of a page, which overrides {Brut::FrontEnd::Component#render}. This is expected to return
-  # a string to be sent as a response to an HTTP request. Generally, you should not call this method as it is
-  # called by Brut when your page is requested.
-  #
-  # Also, generally don't override this unles you need to do something unusual.  Overriding this will completely bypass the layout
-  # system and skip all ERB processing. Unlike {Brut::FrontEnd::Component#render}, overriding this method does not provide access to injected data from the request context.
-  #
-  # @return [Brut::FrontEnd::Templates::HTMLSafeString] string containing the page's full HTML.
-  def render
-    layout_template = Brut.container.layout_locator.locate(self.layout).
-      then { |layout_erb_file| Brut::FrontEnd::Template.new(layout_erb_file) }
-
-    template = Brut.container.page_locator.locate(self.template_name).
-      then { |erb_file| Brut::FrontEnd::Template.new(erb_file) }
-
-    Brut.container.instrumentation.add_event("templates found", layout: layout_template.template_file_path, page: template.template_file_path)
+  # Override this method to produce your page's HTML. You are intended to call Phlex
+  # methods here. Anything you can do inside the Phlex-standard `view_template` method, you can 
+  # do here. The only difference is that this will all be rendered in the context of your configured
+  # {#layout}.
+  def page_template = abstract_method!
 
-    page = template.render_template(self).html_safe!
-    layout_template.render_template(self) do
-      page
+  # Phlex's API to produce markup. Do not override this or you will lose your layout.
+  # This implementation locates the configured layout, renders it, and renders {#page_template}
+  # inside.
+  def view_template
+    with_layout do
+      page_template
     end
   end
 
+
   # @return [String] name of this page for use in debugging or for whatever reason you may want to dynamically refer to the page's name.  The default value is the class name.
   def self.page_name = self.name
 
@@ -79,7 +77,21 @@ class Brut::FrontEnd::Page < Brut::FrontEnd::Component
 
 private
 
-  def template_name = RichString.new(self.class.name).underscorized.to_s.gsub(/^pages\//,"")
+  # Locates the layout class and uses it to render itself, along
+  # with the block given.
+  #
+  # @!visibility private
+  def with_layout(&block)
+    layout_class = Module.const_get(
+      layout_class = RichString.new([
+        self.layout,
+        "layout"
+      ].join("_")).camelize
+    )
+    render layout_class.new(page_name:,&block)
+  end
+
+
 
 end
 

data/lib/brut/front_end/request_context.rb

@@ -8,6 +8,19 @@
 # and create an initializer for it that accepts the `clock:` keyword argument, the managed instance of {Clock} will be passed into it
 # when Brut creates an instance of the class.
 class Brut::FrontEnd::RequestContext
+
+  def self.current
+    Thread.current.thread_variable_get(:request_context)
+  end
+
+  # Create an instance of klass injected with the request context.
+  def self.inject(klass, request_params: nil)
+    self.current.then { |request_context|
+      request_context.as_constructor_args(klass,request_params:)
+    }.then { |constructor_args|
+      klass.new(**constructor_args) 
+    }
+  end
   # Create a new RequestContext based on some of the information provided by Rack
   #
   # @param [Hash] env the Rack `env` object, as available to any middleware

data/lib/brut/front_end/routing.rb

@@ -1,4 +1,5 @@
 require "uri"
+require "phlex"
 
 # Holds the registered routes for this app.
 class Brut::FrontEnd::Routing
@@ -217,12 +218,16 @@ private
         joined_path = joined_path + "#" + URI.encode_uri_component(anchor)
       end
       uri = URI(joined_path)
-      uri.query = URI.encode_www_form(query_string_params)
-      uri
+      query_string = URI.encode_www_form(query_string_params)
+      if query_string.to_s.strip != ""
+        uri.query = query_string
+      end
+
+      uri.extend(Phlex::SGML::SafeObject)
     end
 
     def url(**query_string_params)
-      request_context = Thread.current.thread_variable_get(:request_context)
+      request_context = Brut::FrontEnd::RequestContext.current
       path = self.path(**query_string_params)
       host = if request_context
                request_context[:host]

data/lib/brut/front_end.rb

@@ -0,0 +1,32 @@
+# In Brut, the _front end_ is considered anything that interacts directly 
+# with a web browser or HTTP.  This includes rendering HTML, managing 
+# JavaScript and CSS, and processing form submissions.  It contrasts to 
+# {Brut::BackEnd}, which handles the business logic and database.
+#
+# The entire front-end is based on Rack, so you should be able to achieve anything you need to.
+module Brut::FrontEnd
+  autoload(:AssetMetadata, "brut/front_end/asset_metadata")
+  autoload(:AssetPathResolver, "brut/front_end/asset_path_resolver")
+  autoload(:Component, "brut/front_end/component")
+  autoload(:Components, "brut/front_end/component")
+  autoload(:Download, "brut/front_end/download")
+  autoload(:Flash, "brut/front_end/flash")
+  autoload(:Form, "brut/front_end/form")
+  autoload(:GenericResponse, "brut/front_end/generic_response")
+  autoload(:Handler, "brut/front_end/handler")
+  autoload(:Handlers, "brut/front_end/handler")
+  autoload(:HandlingResults, "brut/front_end/handling_results")
+  autoload(:HttpMethod, "brut/front_end/http_method")
+  autoload(:HttpStatus, "brut/front_end/http_status")
+  autoload(:InlineSvgLocator, "brut/front_end/inline_svg_locator")
+  autoload(:Layout, "brut/front_end/layout")
+  autoload(:Middleware, "brut/front_end/middleware")
+  autoload(:Middlewares, "brut/front_end/middleware")
+  autoload(:Page, "brut/front_end/page")
+  autoload(:Pages, "brut/front_end/page")
+  autoload(:RequestContext, "brut/front_end/request_context")
+  autoload(:RouteHook, "brut/front_end/route_hook")
+  autoload(:RouteHooks, "brut/front_end/route_hook")
+  autoload(:Routing, "brut/front_end/routing")
+  autoload(:Session, "brut/front_end/session")
+end