brut 0.0.13 → 0.0.21

data/doc-src/pages.md

@@ -1,210 +0,0 @@
-# Pages and Components
-
-A website is made up of pages.  Even a web *app* has pages.  Thus, the most basic way to create dynamic behavior with Brut is the
-*page*.  In Brut, a page is a URL, a subclass of {Brut::FrontEnd::Page}, and an ERB template.  The template is rendered in the context
-of an instance of the class whenever the URL is requested.
-
-## Overview of Rendering Pages
-
-In your `app.rb`, you first declare a page using the {Brut::SinatraHelpers::ClassMethods#page} method (inside the block given to {Brut::Framework::App.routes}):
-
-    class App < Brut::Framework::App
-
-      routes do
-
-        page "/sign_in"
-      end
-    end
-
-The name of the route must start with a `/` and the rest of the route determines the name of the page.  In the example above, Brut
-will expect to find a class named `SignInPage`, which should be located in `app/src/front_end/pages`.  You can create it with
-`bin/scaffold`:
-
-    > bin/scaffold page SignInPage
-
-The page class must subclass {Brut::FrontEnd::Page}.  You write a constructor to accept whatever your page needs to assemble the data
-needed to render it.
-
-The HTML is generated based on an ERB file located in `app/src/front_end/pages`.  In this example, that's
-`app/src/front_end/pages/sign_in_page.html.erb`.  That ERB is executed with an instance of the page class as context.  That means you
-can references any methods or ivars.
-
-## Creating a Page Class
-
-{Brut::FrontEnd::Page#render} is called by Brut and expects to receive HTML, which it will send as the body of the response. `render`
-manages the ERB rendering, so the bulk of your page's logic will be in other methods.  The constructor is where any data you need is
-provided.
-
-A page's `initialize` method must accept only keyword arguments and those keywords are used by Brut to determine what data needs to be
-passed in.  This technique, called *{file:doc-src/keyword-injection.md Keyword Injection}*, is used in several other places in Brut.
-
-When the page's URL is requested, an instance of your page class is created, passing in the values needed.  Beyond that, however, your page class is a normal Ruby class. You can save data to instance variables, implement attributes or other methods. Basically, whatever logic your page needs to render will exist in the page class.
-
-## Implementing Your ERB
-
-ERB is part of the Ruby standard library that allows the creation of dynamic templates.  Brut's ERB is close to this implementation, but has a few additional features that make working with HTML a bit safer.
-
-### Your Page is the Only Context
-
-The instance of your page class is the only context available to the ERB.  There is no set of global helpers that are injected, nor
-are there any modules added when the page is rendered.  Anything you need to do in your ERB must be available to the page class you've
-created.
-
-The reason for this is to keep things simple.  If your page's HTML needs access to a lot of stuff, your page class will be the source
-of truth as to where that stuff comes from.  You will always be able to figure out where methods are defined by looking at the page
-class or any of its ancestors.  You are free to `include` as many modules as you like, or dump lots of methods into your `AppPage`
-base class. But you don't have to.
-
-### All Strings are HTML-Escaped
-
-Any instance of a `String` is HTML-escaped by Brut before being inserted into the HTML being generated by the ERB.  This is, generally, what you want to have happen.  If you have a string that you believe is safe and does not need to be escaped, you can prevent HTML-escaping in one of two ways:
-
-* Call {Brut::FrontEnd::Component#html_safe!} on the string
-
-        <%= html_safe!(get_value) %>
-
-* Wrap the string in a {Brut::FrontEnd::Templates::HTMLSafeString}.
-
-        def get_value
-          Brut::FrontEnd::Templates::HTMLSafeString.from_string(some_value)
-        end
-
-  This is what `html_safe!` does and this is what Brut does internally. Brut doesn't monkey-patch `String`. A `String` is always
-  considered unsafe, and an `HTMLSafeString` is always considered safe.
-
-Both of these methods are verbose, but this is on purpose.  You generally don't want un-escaped HTML going into your HTML, but if you
-do, you may find it better to create a component (see below), or use {Brut::FrontEnd::Component::Helpers#html_tag} to generate markup.
-
-### Pages Have Layouts
-
-The page's ERB is rendered in the context of a *layout*.  A Layout works similar to how it works in Rails. It's intended to hold HTML
-needed by every page of your app. A minimal layout might look like so:
-
-    <!DOCTYPE html>
-    <html>
-      <head>
-        <meta charset="utf-8">
-        <%= component(Brut::FrontEnd::Components::PageIdentifier.new(self.page_name)) %>
-        <link rel="preload" as="style" href="<%= asset_path('/css/styles.css') %>">
-        <link rel="stylesheet"         href="<%= asset_path('/css/styles.css') %>">
-        <script defer src="<%= asset_path('/js/app.js') %>"></script>
-      </head>
-      <body>
-        <%= yield %>
-      </body>
-    </html>
-
-The layout is rendered in the context of the page class, so every page must provide whatever features are needed by the layout. This
-is usually done by adding globally-used functions to `AppPage`, which is the base class of all your app's pages.
-
-A page can use another layout by overriding {Brut::FrontEnd::Page#layout}.  The string returned must match a file in
-`app/src/front_end/layouts/`.
-
-### There Are No Partials
-
-Rails partials are not part of ERB, and Brut does not include this feature. Instead, you would use *Components*.
-
-## Decompose and Re-Use with Components
-
-*Components* in Brut are very similar to the View Components library, though somewhat simpler.  A component is a class and an ERB
-template.  That template is rendered in the context of an instance of the class.  That class is created the same way a page is and has
-a `render` method that works just like a page's.
-
-This is all because {Brut::FrontEnd::Page} extends {Brut::FrontEnd::Component}.  A page adds the concept of a layout, but generally a
-page and a component are the same thing.
-
-### Using Components
-
-The main difference from your perspective is that generally *you* create instances of components.  This means that your page must have
-access to any data a component needs.  When you've created your component instance, use {Brut::FrontEnd::Component#component} to
-render it:
-
-    <%= component(Button.new(type: :danger, label: "Cancel Subscription")) %>
-
-### Components with Templates
-
-The most common way to use a component is with an ERB template. It is expected to be in `app/src/front_end/components`.  For the
-hypothetical `Button` component above, Brut would expect `app/src/front_end/components/button.html.erb` to exist as a template.
-
-Just like a page, the component's ERB is rendered in the context of the component only.
-
-Sometimes, components are simple enough that you don't need HTML.
-
-### Components That Render Themselves
-
-While overriding `render` in a page is generally discouraged, {Brut::FrontEnd::Component#render} can be overridden if you want to
-generate HTML yourself.  The best way to do that is with {Brut::FrontEnd::Component::Helpers#html_tag}, though you can always return a
-`String` or {Brut::FrontEnd::Templates::HTMLSafeString} that you've created yourself. Just remeber that all `String` instances will be
-HTML-escaped.
-
-As an example, here is how you might have a Markdown component that renders Markdown as HTML:
-
-    class MarkdownComponent < AppComponent
-      def initialize(markdown:)
-        @markdown = markdown
-        @renderer = Redcarpet::Markdown.new(
-          Redcarpet::Render::HTML.new(
-            filter_html: true,
-            no_images: true,
-            no_styles: true,
-            safe_links_only: true,
-          ),
-          fenced_code_blocks: true,
-          autolink: true,
-          quote: true,
-        )
-      end
-
-      def render
-       html_safe!(@renderer.render(@markdown.to_s))
-      end
-    end
-
-
-### Global Components
-
-While a component is just a class with an initializer, sometimes you need a component that is generally useful on any page, but that
-you don't want to initialize.  For example, if your component needs access to the flash, but your page does not, you don't want your
-page to require a flash just to pass to the component.  In that case, a *global component* can be used and Brut will instantiate it.
-
-{Brut::FrontEnd::Component#component} can be given a class, and Brut will use keyword injection to create it.  Consider a generic
-flash component:
-
-    class GlobalFlash < AppComponent
-
-      attr_reader :flash
-
-      def initialize(flash:)
-        @flash = flash
-      end
-    end
-
-You can use this anywhere like so:
-
-    <%= component(GlobalFlash) %>
-
-Because the flash is availble from the {Brut::FrontEnd::RequestContext}, Brut can create this component when needed.
-
-## Testing Pages and Components
-
-Pages and Components are classes with a constructor you create and a well-defined primary method called `render`.  This means you can
-test them conventionally, since they can be directly created in your tests.
-
-That said, you likely want to test the generated HTML and not the methods of the class.  All tests of a page or component have the
-methods in {Brut::SpecSupport::ComponentSupport} available.  Of particular interest is
-{Brut::SpecSupport::ComponentSupport#render_and_parse}.
-
-This method accepts an instance of a page or component, parses the resulting HTML with Nokogiri, and returns a
-{Brut::SpecSupport::EnhancedNode}, which wraps a `Nokogiri::XML::Node` or `Nokogiri::XML::Element`, depending on what was parsed.  You
-can then use Nokogiri's API locate elements and assert on them.
-
-To keep close to the web platform, it's recommended to use CSS selectors either via {Brut::SpecSupport::EnhancedNode#e} or {Brut::SpecSupport::EnhancedNode#e!} (both of which wrap Nokogiri's `css` method).
-
-Instead of creating another API for accessing HTML content, the Nokogiri API should be used directly.  You can create custom matchers
-as needed for common assertions.  Brut includes a few that you will find useful:
-
-* `have_link_to`
-* `have_html_attribute`
-* `have_i18n_string`
-
-

data/doc-src/route-hooks.md

@@ -1,59 +0,0 @@
-# Route and Page Hooks
-
-Route and page hooks allow you to perform logic or redirect the visitor before a page is rendered or action handled.
-
-## Route Hooks
-
-Route hooks are objects that are run before or after a request has been handled. They are useful for setting up cross-cutting code
-that you don't want to have inside a page or handler.
-
-To use one, call either {Brut::Framework::App.before} or {Brut::Framework::App.after}, passing it the *name* of a class to use as the
-hook (i.e. a `String`).
-
-Then, implement that class, extending {Brut::FrontEnd::RouteHook}, and provide either {Brut::FrontEnd::RouteHook#before} or {Brut::FrontEnd::RouteHook#after}.  As discussed in {file:doc-src/keyword-injection.md Keyword Injection}, your hook can be passed some managed values to allow it to work.
-
-In general, a hook will allow the request to continue or not, but using one of the following methods as the return value:
-
-* {Brut::FrontEnd::HandlingResults#redirect_to} to redirect the user instead of rendering the page or handling the request.
-* {Brut::FrontEnd::HandlingResults#http_status} to return an HTTP status instead of rendering the page or handling the request.
-* {Brut::FrontEnd::RouteHook#continue} to proceed with the request.
-
-## Page Hooks
-
-Sometimes, the behavior you want to manage before a page is rendered is specific to a page and not cross-cutting. Because a page
-exepcts to render HTML, you cannot easily put such code in your page class.
-
-If you implement {Brut::FrontEnd::Page#before_render}, you can skip page rendering entirely and redirect the user or send an error.  A
-good example of this would be a set of admin pages where the logged-in site visitor must possess some roles in order to see the page.
-
-A page hook expects one of these return values:
-
-* `URI` - redirect the visitor instead of rendering the page.
-* {Brut::FrontEnd::HttpStatus} - Send the browser this status code instead of rendering the page.
-* Anything else - render the page as normal
-
-Thus, the lifecycle of a page is:
-
-1. "Before" Route Hooks
-2. Page Initializer, injected as described in {file:doc-src/keyword-injection.md}
-3. Page's `before_render`, called with no arguments.
-4. Page's ERB generates HTML
-5. "After" Route Hooks
-
-## Handler Hooks
-
-Like page hooks, handler hooks are called before handling logic.  Implement `before_handle`.  It's arguments must be a subset of the
-arguments passed to `handle`.  Thus, any value needed by `before_handle` must be declared as a keyword argument to `handle` as well.
-
-If `before_handle` returns `nil`, `handle` is then called.  Otherwise, `handle` is skipped and the return value of `before_handle` is
-interpreted as the return value of `handle`. See {Brut::FrontEnd::Handler#handle}.
-
-This makes the lifecycle of a handler as such:
-
-1. "Before" Route Hooks
-2. Handler Initializer, called with no argument.
-3. Handler's `handle!`, injected with arguments as described in {file:doc-src/keyword-injections.md}
-   1. `handle!` calls `before_handle`, passing the arguments in.
-   2. `handle!` calls `handle`, passing the arguments in.
-4. "After" Route Hooks
-

data/lib/brut/front_end/template.rb

@@ -1,47 +0,0 @@
-require "temple"
-
-# Holds code related to rendering ERB templates
-module Brut::FrontEnd::Templates
-  autoload(:HTMLSafeString,"brut/front_end/templates/html_safe_string")
-  autoload(:ERBParser,"brut/front_end/templates/erb_parser")
-  autoload(:EscapableFilter,"brut/front_end/templates/escapable_filter")
-  autoload(:BlockFilter,"brut/front_end/templates/block_filter")
-  autoload(:ERBEngine,"brut/front_end/templates/erb_engine")
-  autoload(:Locator,"brut/front_end/templates/locator")
-end
-
-# Handles rendering HTML templates written in ERB.  This is a light wrapper around `Tilt`.
-# This also configured a few customizations to allow a Rails-like rendering of ERB:
-#
-# * HTML escaping by default
-# * Helpers that return {Brut::FrontEnd::Templates::HTMLSafeString}s won't be escaped
-#
-# @see https://github.com/rtomayko/tilt
-class Brut::FrontEnd::Template
-
-  # @!visibility private
-  # This sets up global state somewhere, even though we aren't using `TempleTemplate`
-  # anywhere.
-  TempleTemplate = Temple::Templates::Tilt(Brut::FrontEnd::Templates::ERBEngine,
-                                           register_as: "html.erb")
-
-  attr_reader :template_file_path
-
-  # Wraps a string that is deemed safe to insert into
-  # HTML without escaping it.  This allows stuff like
-  # <%= component(SomeComponent) %> to work without
-  # having to remember to <%== all the time.
-  def initialize(template_file_path)
-    @template_file_path = template_file_path
-    @tilt_template = Tilt.new(@template_file_path)
-  end
-
-  def render_template(...)
-    @tilt_template.render(...)
-  end
-
-  # Convienience method to escape HTML in the canonical way.
-  def self.escape_html(string)
-    Brut::FrontEnd::Templates::EscapableFilter.escape_html(string)
-  end
-end

data/lib/brut/front_end/templates/block_filter.rb

@@ -1,61 +0,0 @@
-# Allows rendering blocks in ERB the way Rails' helpers like `form_with` do.
-# This is a slightly modified copy of Hanami's `Filters::Block`.
-#
-# @see https://github.com/hanami/view/blob/main/lib/hanami/view/erb/filters/block.rb
-class Brut::FrontEnd::Templates::BlockFilter < Temple::Filter
-  END_LINE_RE = /\bend\b/
-
-  # @!visibility private
-  def on_erb_block(escape, code, content)
-    tmp = unique_name
-
-    # Remove the last `end` :code sexp, since this is technically "outside" the block
-    # contents, which we want to capture separately below. This `end` is added back after
-    # capturing the content below.
-    case content.last
-    in [:code, c] if c =~ END_LINE_RE
-      content.pop
-    end
-
-    [:multi,
-     # Capture the result of the code in a variable. We can't do `[:dynamic, code]` because
-     # it's probably not a complete expression (which is a requirement for Temple).
-     # DBC: an example is that 'code' might be "form_for do" which is not an expression.
-     #      Because we later put an "end" in, the result will be
-     #
-     #      some_var = helper do
-     #      end
-     #
-     #      Which IS valid Ruby.
-     [:code, "#{tmp} = #{code}"],
-     # Capture the content of a block in a separate buffer. This means that `yield` will
-     # not output the content to the current buffer, but rather return the output.
-     [:capture, unique_name, compile(content)],
-     [:code, "end"],
-     # Output the content, without escaping it.
-     # Hanami has this ↴
-     # [:escape, escape, [:dynamic, tmp]]
-     [:escape, escape, [:dynamic, Brut::FrontEnd::Templates.name + "::HTMLSafeString.new(#{tmp})"]]
-    ]
-
-    # Details explaining the change:
-    #
-    # The sexps for template are quite convoluted and highly dynamic, so it is hard
-    # to understand exactly what effect they will have.  Basically, what this [:multi thing is
-    # doing is to capture the result of the block in a variable:
-    #
-    # some_var = form_for(args) do
-    #
-    # It then captures the inside of the block in a new variable:
-    #
-    # some_other_var = «whatever was inside that `do`»
-    #
-    # And follows it with an end.
-    #
-    # The first variable—some_var—now holds the return value of the helper, form_for in this case. To
-    # output this content to the actual view, it must be dereferenced, thus [ :dynamic, "some_var" ].
-    #
-    # We are going to treat the return value of the block helper as HTML safe.  Thus, we'll wrap it
-    # with HTMLSafeString.new(…).
-  end
-end

data/lib/brut/front_end/templates/erb_engine.rb

@@ -1,26 +0,0 @@
-# A temple "engine" that can be used to parse ERB and generate HTML
-# in just the way we need.
-class Brut::FrontEnd::Templates::ERBEngine < Temple::Engine
-  # Parse the ERB into sexps
-  use Brut::FrontEnd::Templates::ERBParser
-
-  # Handle block syntax used in a <%= 
-  use Brut::FrontEnd::Templates::BlockFilter
-
-  # Trim whitespace like ERB does
-  use Temple::ERB::Trimming
-
-  # Escape strings only if they are not HTMLSafeString
-  use Brut::FrontEnd::Templates::EscapableFilter
-  # This filter actually runs the Ruby code
-  use Temple::Filters::StaticAnalyzer
-  # Flattens nested :multi expressions which I'm not sure is needed, but
-  # have cargo-culted from hanami
-  use Temple::Filters::MultiFlattener
-  # merges sequential :static, which again, not sure is needed, but
-  # have cargo-culted from hanami
-  use Temple::Filters::StaticMerger
-
-  # This generates everything into a string
-  use Temple::Generators::ArrayBuffer
-end

data/lib/brut/front_end/templates/erb_parser.rb

@@ -1,84 +0,0 @@
-# Almost verbatim copy of Hanami's parser:
-#
-# https://github.com/hanami/view/blob/main/lib/hanami/view/erb/parser.rb
-#
-# That is licensed MIT and thus so is this file.
-#
-# Avoid changes to this file so it can be kept updated with Hanami.
-class Brut::FrontEnd::Templates::ERBParser < Temple::Parser
-  ERB_PATTERN = /(\n|<%%|%%>)|<%(==?|\#)?(.*?)?-?%>/m
-
-  IF_UNLESS_CASE_LINE_RE = /\A\s*(if|unless|case)\b/
-  BLOCK_LINE_RE = /\s*((\s+|\))do|\{)(\s*\|[^|]*\|)?\s*\Z/
-  END_LINE_RE = /\bend\b/
-
-  def call(input)
-    results = [[:multi]]
-    pos = 0
-
-    input.scan(ERB_PATTERN) do |token, indicator, code|
-      # Capture any text between the last ERB tag and the current one, and update the position
-      # to match the end of the current tag for the next iteration of text collection.
-      text = input[pos...$~.begin(0)]
-      pos  = $~.end(0)
-
-      if token
-        # First, handle certain static tokens picked up by our ERB_PATTERN regexp. These are
-        # newlines as well as the special codes for literal `<%` and `%>` values.
-        case token
-        when "\n"
-          results.last << [:static, "#{text}\n"] << [:newline]
-        when "<%%", "%%>"
-          results.last << [:static, text] unless text.empty?
-          token.slice!(1)
-          results.last << [:static, token]
-        end
-      else
-        # Next, handle actual ERB tags. Start by adding any static text between this match and
-        # the last.
-        results.last << [:static, text] unless text.empty?
-
-        case indicator
-        when "#"
-          # Comment tags: <%# this is a comment %>
-          results.last << [:code, "\n" * code.count("\n")]
-        when %r{=}
-          # Expression tags: <%= "hello (auto-escaped)" %> or <%== "hello (not escaped)" %>
-          if code =~ BLOCK_LINE_RE
-            # See Hanami::View::Erb::Filters::Block for the processing of `:erb, :block` sexps
-            block_node = [:erb, :block, indicator.size == 1, code, (block_content = [:multi])]
-            results.last << block_node
-
-            # For blocks opened in ERB expression tags, push this `[:multi]` sexp
-            # (representing the content of the block) onto the stack of resuts. This allows
-            # subsequent results to be appropriately added inside the block, until its closing
-            # tag is encountered, and this `block_content` multi is subsequently popped off
-            # the results stack.
-            results << block_content
-          else
-            results.last << [:escape, indicator.size == 1, [:dynamic, code]]
-          end
-        else
-          # Code tags: <% if some_cond %>
-          if code =~ BLOCK_LINE_RE || code =~ IF_UNLESS_CASE_LINE_RE
-            results.last << [:code, code]
-
-            # For ERB code tags that will result in a matching `end`, push the last result
-            # back onto the stack of results. This might seem redundant, but it allows
-            # subsequent sexps to continue to be pushed onto the same result while also
-            # allowing it to be safely popped again when the matching `end` is encountered.
-            results << results.last
-          elsif code =~ END_LINE_RE
-            results.last << [:code, code]
-            results.pop
-          else
-            results.last << [:code, code]
-          end
-        end
-      end
-    end
-
-    # Add any text after the final ERB tag
-    results.last << [:static, input[pos..-1]]
-  end
-end

data/lib/brut/front_end/templates/escapable_filter.rb

@@ -1,20 +0,0 @@
-# A temple filter that handles escaping HTML unless it's been wrapped in
-# an HTMLSafeString.
-class Brut::FrontEnd::Templates::EscapableFilter < Temple::Filters::Escapable
-  using Brut::FrontEnd::Templates::HTMLSafeString::Refinement
-
-  # @!visibility private
-  def initialize(opts = {})
-    opts[:escape_code] ||= "::Brut::FrontEnd::Templates::EscapableFilter.escape_html((%s))"
-    super(opts)
-  end
-
-  # @!visibility private
-  def self.escape_html(html)
-    if html.kind_of?(Brut::FrontEnd::Templates::HTMLSafeString)
-      html.string
-    else
-      Temple::Utils.escape_html(html)
-    end
-  end
-end

data/lib/brut/front_end/templates/html_safe_string.rb

@@ -1,68 +0,0 @@
-# A wrapper around a string to indicate it is HTML-safe and
-# can be rendered directly without escaping. This was done to avoid adding methods on `String` and the internal state
-# required to make something like `"foo".html_safe!` work.
-class Brut::FrontEnd::Templates::HTMLSafeString
-  # This can be used via `using` to add `html_safe!` and `html_safe?` method to `String` when they might be more convienient
-  # than using {Brut::FrontEnd::Templates::HTMLSafeString} directly.
-  module Refinement
-    refine String do
-      def html_safe! = Brut::FrontEnd::Templates::HTMLSafeString.from_string(self)
-      def html_safe? = false
-    end
-  end
-  using Refinement
-
-  # @return [String] the underlying string being wrapped
-  attr_reader :string
-
-  # Create an HTML safe string based on the parameter. It's recommended to use {.from_string} instead.
-  #
-  # @param [String] string A string that is considered safe to put directly into a web page without escaping.
-  def initialize(string)
-    @string = string
-  end
-
-  # Creates an HTML Safe string based on the parameter, properly handling if a HTML safe string is being passed.
-  #
-  # @param [String|Brut::FrontEnd::Templates::HTMLSafeString] string_or_html_safe_string the value to turn into an HTML safe string.
-  #
-  # @return [Brut::FrontEnd::Templates::HTMLSafeString] if `string_or_html_safe_string` is already HTML safe, returns it. Otherwise,
-  # wraps the string as HTML safe.
-  def self.from_string(string_or_html_safe_string)
-    if string_or_html_safe_string.kind_of?(self)
-      string_or_html_safe_string
-    else
-      self.new(string_or_html_safe_string)
-    end
-  end
-
-  # This must be convertible to a string
-  def to_s       = @string
-  def to_str     = @string
-  # Matches the protocol in {Brut::FrontEnd::Templates::HTMLSafeString::Refinement}
-  # @return [Brut::FrontEnd::Templates::HTMLSafeString] self
-  def html_safe! = self
-  # Matches the protocol in {Brut::FrontEnd::Templates::HTMLSafeString::Refinement}
-  # @return [true|false] true
-  def html_safe? = true
-
-  # Return a new instance that has called `capitalize` on the underlying string
-  def capitalize = self.class.new(@string.capitalize)
-  # Return a new instance that has called `downcase` on the underlying string
-  def downcase   = self.class.new(@string.downcase)
-  # Return a new instance that has called `upcase` on the underlying string
-  def upcase     = self.class.new(@string.upcase)
-
-  # Returns the concatenation of two strings. If the other is HTML safe, then this returns an HTML safe string.
-  # If the other is not, this returns a normal unsafe string.
-  #
-  # @param [String|Brut::FrontEnd::Templates::HTMLSafeString] other
-  # @return [String|Brut::FrontEnd::Templates::HTMLSafeString] A safe or unsafe string, depending on what was passed.
-  def +(other)
-    if other.html_safe?
-      self.class.new(@string + other.to_s)
-    else
-      @string + other.to_s
-    end
-  end
-end

data/lib/brut/front_end/templates/locator.rb

@@ -1,60 +0,0 @@
-# Locates a template, based on a name, configured paths, and an extension.  This class forms both an API
-# for template location ({#locate}) as well as an implementation that is conventional with Brut apps.
-class Brut::FrontEnd::Templates::Locator
-  # Create a locator that will search the given paths and require that template
-  # files have the given extension
-  #
-  # @param [Pathname|String|Array<Pathname|String>] paths one or more paths that will be searched for templates
-  # @param [String] extension file extension, without the dot, of the name of files that are considered templates
-  def initialize(paths:, extension:)
-    @paths     = Array(paths).map { |path| Pathname(path) }
-    @extension = extension
-  end
-
-  # Given a base name, which may or may not be nested paths, returns the path to the template
-  # for this file.  There must be exactly one template that matches.
-  #
-  # @example
-  #
-  #    locator = Locator.new(
-  #      paths: [
-  #        Brut.container.app_src_dir / "front_end" / "components",
-  #        Brut.container.app_src_dir / "front_end" / "other_components",
-  #      ],
-  #      extension: "html.erb"
-  #    )
-  #
-  #    # Suppose app/src/front_end/components/foo.html.erb exists
-  #    path = locator.locate("foo")
-  #    # => "app/src/front_end/components/foo.html.erb"
-  #
-  #    # Suppose app/src/front_end/components/bar/blah.html.erb exists
-  #    path = locator.locate("bar/blah")
-  #    # => "app/src/front_end/components/bar/blah.html.erb"
-  #
-  #    # Suppose both app/src/front_end/components/bar/blah.html.erb and
-  #    #              app/src/front_end/other_components/bar/blah.html.erb
-  #    # both exist
-  #    path = locator.locate("bar/blah")
-  #    # => raises an error since there are two matches
-  #
-  # @param [String] base_name the base name of a file that is expected to have a template.  This is searched relative to the paths
-  # provided to the constructor, so it may have nested paths
-  # @return [String] path to the template for the given `base_name`
-  # @raise StandardError if zero or more than one templates are found
-  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