brut 0.0.13 → 0.0.21

data/lib/brut.rb

@@ -1,60 +1,17 @@
 require_relative "brut/framework"
 
-# Brut is a way to make web apps with Ruby. It focuses on web standards, object-orientation, and other fundamentals. Brut seeks to
-# minimize abstractions where possible.
+# Brut is a way to make web apps with Ruby. It focuses on web standards, object-orientation, and other
+# fundamentals. Brut seeks to minimize abstractions where possible.
 #
-# Brut encourages the use of the browser's technology and encourages you to build a web app based on good practices that are set up by
-# default.  Brut may not look easy, but it aims to be simple.  It attempts to minimize dependencies and complexity, while leveraging
+# Brut encourages the use of the browser's technology and encourages you to build a web app based
+# on good practices that are set up by default.  Brut may not look easy, but it aims to be simple.
+# It attempts to minimize dependencies and complexity, while leveraging
 # common tested Ruby libraries related to web development.
 #
 # Have fun!
 module Brut
-  # 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.
-  #
-  # You {Brut::App} defines pages, forms, and actions. A page is backed by a subclass of {Brut::FrontEnd::Page}, which provides
-  # dynamic data for rendering. A page can reference {Brut::FrontEnd::Component} subclasses to allow functional decomposition of front
-  # end logic and markup, as well as re-use.  Both pages and components have ERB files that describe the HTML to be rendered.
-  #
-  # A {Brut::FrontEnd::Form} subclass defines a form that a browser will submit to your app. That
-  # submission is processed by a {Brut::FrontEnd::Handler} subclass.  Handlers can also respond to other HTTP requests.
-  #
-  # In addition to responding to requests, you can subclass {Brut::FrontEnd::RouteHook} or {Brut::FrontEnd::Middleware} to perform
-  # further manipulation of the request.
-  #
-  # The entire front-end is based on Rack, so you should be able to achieve anything you need to.
-  module FrontEnd
-    autoload(:AssetMetadata, "brut/front_end/asset_metadata")
-    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(: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(:GenericResponse, "brut/front_end/generic_response")
-    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
-  # 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 BackEnd
-    autoload(:Validators, "brut/back_end/validator")
-    autoload(:Sidekiq, "brut/back_end/sidekiq")
-    # Do not put SeedData here - it must be loaded only when needed
-  end
-  # I18n is where internationalization and localization support lives.
+  autoload(:FrontEnd, "brut/front_end")
+  autoload(:BackEnd, "brut/back_end")
   autoload(:I18n, "brut/i18n")
   autoload(:Instrumentation,"brut/instrumentation")
   autoload(:SinatraHelpers, "brut/sinatra_helpers")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brut
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.21
 platform: ruby
 authors:
 - David Bryant Copeland
@@ -80,7 +80,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: prism
+  name: phlex
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -94,7 +94,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rack-protection
+  name: prism
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -108,7 +108,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rackup
+  name: rack-protection
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -122,7 +122,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rexml
+  name: rackup
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -177,34 +177,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: temple
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: tilt
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
@@ -434,14 +406,6 @@ files:
 - bin/rake
 - bin/setup
 - brut.gemspec
-- doc-src/architecture.md
-- doc-src/assets.md
-- doc-src/forms.md
-- doc-src/handlers.md
-- doc-src/javascript.md
-- doc-src/keyword-injection.md
-- doc-src/pages.md
-- doc-src/route-hooks.md
 - docker-compose.dx.yml
 - docs-todo.md
 - dx/build
@@ -454,6 +418,7 @@ files:
 - dx/start
 - dx/stop
 - lib/brut.rb
+- lib/brut/back_end.rb
 - lib/brut/back_end/seed_data.rb
 - lib/brut/back_end/sidekiq.rb
 - lib/brut/back_end/sidekiq/middlewares.rb
@@ -491,7 +456,9 @@ files:
 - lib/brut/framework/mcp.rb
 - lib/brut/framework/patch_semantic_logger.rb
 - lib/brut/framework/project_environment.rb
+- lib/brut/front_end.rb
 - lib/brut/front_end/asset_metadata.rb
+- lib/brut/front_end/asset_path_resolver.rb
 - lib/brut/front_end/component.rb
 - lib/brut/front_end/components/constraint_violations.rb
 - lib/brut/front_end/components/form_tag.rb
@@ -504,7 +471,7 @@ files:
 - lib/brut/front_end/components/inputs/textarea.rb
 - lib/brut/front_end/components/locale_detection.rb
 - lib/brut/front_end/components/page_identifier.rb
-- lib/brut/front_end/components/time.rb
+- lib/brut/front_end/components/time_tag.rb
 - lib/brut/front_end/components/traceparent.rb
 - lib/brut/front_end/download.rb
 - lib/brut/front_end/flash.rb
@@ -527,6 +494,8 @@ files:
 - lib/brut/front_end/handling_results.rb
 - lib/brut/front_end/http_method.rb
 - lib/brut/front_end/http_status.rb
+- lib/brut/front_end/inline_svg_locator.rb
+- lib/brut/front_end/layout.rb
 - lib/brut/front_end/layouts/_internal.html.erb
 - lib/brut/front_end/middleware.rb
 - lib/brut/front_end/middlewares/annotate_brut_owned_paths.rb
@@ -545,15 +514,9 @@ files:
 - lib/brut/front_end/route_hooks/setup_request_context.rb
 - lib/brut/front_end/routing.rb
 - lib/brut/front_end/session.rb
-- lib/brut/front_end/template.rb
-- lib/brut/front_end/templates/block_filter.rb
-- lib/brut/front_end/templates/erb_engine.rb
-- lib/brut/front_end/templates/erb_parser.rb
-- lib/brut/front_end/templates/escapable_filter.rb
-- lib/brut/front_end/templates/html_safe_string.rb
-- lib/brut/front_end/templates/locator.rb
 - lib/brut/i18n.rb
 - lib/brut/i18n/base_methods.rb
+- lib/brut/i18n/for_back_end.rb
 - lib/brut/i18n/for_cli.rb
 - lib/brut/i18n/for_html.rb
 - lib/brut/i18n/http_accept_language.rb
@@ -565,6 +528,7 @@ files:
 - lib/brut/spec_support.rb
 - lib/brut/spec_support/clock_support.rb
 - lib/brut/spec_support/component_support.rb
+- lib/brut/spec_support/e2e_support.rb
 - lib/brut/spec_support/e2e_test_server.rb
 - lib/brut/spec_support/enhanced_node.rb
 - lib/brut/spec_support/flash_support.rb
@@ -581,6 +545,7 @@ files:
 - lib/brut/spec_support/matchers/have_redirected_to.rb
 - lib/brut/spec_support/matchers/have_rendered.rb
 - lib/brut/spec_support/matchers/have_returned_http_status.rb
+- lib/brut/spec_support/matchers/have_returned_rack_response.rb
 - lib/brut/spec_support/rspec_setup.rb
 - lib/brut/spec_support/session_support.rb
 - lib/brut/version.rb

data/doc-src/architecture.md

@@ -1,102 +0,0 @@
-# Brut's High Level Architecture
-
-Brut attempts to have parity with the web platform in general, and how web browsers work.  For example, a web browser shows you a web
-page, thus to do this in Brut, you create a page class.
-
-Brut's core ethos is to captialize on fundamental knowledge you must already posses to build a web app, such as HTML, JavaScript, the
-Web Platform, SQL, etc.
-
-The best way to understand Brut is to break down how a request is handled.
-
-## HTTP Requests at a High Level
-
-1. HTTP Request is received
-2. If the request's route is mapped, handle it and return the result
-3. Otherwise, 404
-
-This pretty much describes every web app server in the world.  Let's dig into step 2
-
-## Pages, Forms, Actions
-
-HTML allows for exactly two ways to interact with a server: Issuing a `GET` for a resource (like a web page), or submitting a form via
-a `GET` or `POST`.
-
-1. HTTP Request is received
-2. If the route is a mapped page, render that page
-3. If the route is a configured form, submit that form handle it
-4. If the route is an asset like CSS or an image, send that.
-5. Otherwise, 404
-
-A browser can use JavaScript to submit other requests, and Brut handles those, too:
-
-1. HTTP Request is received
-2. If the route is a mapped page, render that page (See {file:doc-src/pages.md})
-3. If the route is a configured form, submit that form handle it (See {file:doc-src/forms.md})
-4. If the route is a configured action, perform it and return the results. (See {file:doc-src/handlers.md})
-5. If the route is an asset like CSS or an image, send that. (See {file:doc-src/assets.md})
-6. Otherwise, 404
-
-Before we dig deeper, it's worth pointing out at this point that *Brut is not an MVC framework*, mostly because there are no
-controllers.  *Models* in the MVC sense are instead *pages* or *components*—classes that provide all dynamic behavior and data needed
-to render some HTML.  Brut uses ERB templates to generate HTML and you could think of this as the view, if you want.
-
-## Back End
-
-Most of Brut is concerned with what it calls the *front end*, which is everything about receiving an HTTP request and producing the
-reponse.  But you can almost never make a web app with no back end.  You almost always need a database and a place to execute logic
-outside of a web browser.  Brut refers to this as the *back end*.
-
-Since web back ends are less constrained to protocols, like a front end is to HTTP and other Web APIs, Brut provides a lot less for
-the back end and puts many fewer restrictions on it.  This ends up being a good thing, since the back-end of most web apps are were
-most of the differentiation in behavior and logic tend to be.
-
-Brut provides access to a SQL database via the Sequel Ruby library.  Brut provides some integration with Sidekiq, to allow running
-background jobs. Brut also provides a CLI library for creating one-off tasks (like you'd use Rake for in a Rail apps).
-
-### SQL
-
-Almost all web apps that have a database use SQL.  And Postgres is a great choice.  This is the SQl database that Brut supports,
-though support for other databases may be added later. This is because almost all of Brut's SQL integration is via the Sequel library
-and it supports many databases.
-
-Brut provides some configuration for Sequel to make managing your data easier and to better-support practices that you often want
-to follow.  For example:
-
-* All tables have a primary key of type `int` by default.
-* All tables have a `created_at` field that is set on row insertion.
-* Timestamps use `timestamp with time zone`.
-* You must provide a comment to document all tables.
-* You can have Brut manage an external unique key for each table, so you can keep your primary keys private.
-* `find!` is available on Sequel models, working like `find` does in Rails.
-
-See {file:doc-src/sql.md} for more details.
-
-Brut also uses Sequel's model support to provide access to your database.  It is configured to namespace all models in the `DB::`
-namespace, so if you have a table named `widgets`, Brut will expect `DB::Widget` to be defined to access that table.
-
-The reason for this is that it is often confusing when an app conflates the concept of a database table and a domain model, it can be
-difficult to manage the code.  If the model to access the `widgets` table were called, simply, `Widget`, then you would lose a great
-class name to use for modeling the widget as a domain object.
-
-### Sidekiq
-
-Sidekiq can be added to any app without much fanfare.  That said, Brut provides a few convieniences:
-
-* `bin/run-sidekiq` is provided to run Sidekiq alongside your web app
-* {Brut::SpecSupport::RSpecSetup} well arrange for Sidekiq to be set up in a useful way during tests:
-  - For non-E2E tests, jobs are cleared between test runs.
-  - During E2E tests, actual Sidekiq is used, as started by `/bin/run-sidekiq`, and jobs are cleared between tests.
-
-### CLI / Tasks
-
-Rake is not a great tool for task automation, mostly because it exposes a cumbersome command line interface that relies on environment
-variables, square brackets, and commas.  It's often easier to create a full-blown command line app.
-
-Brut's {Brut::CLI::App} can form the basis for any command line app or task you need for your system.  It provides access to Brut
-internals and your app, as needed, and shares much of its startup code with your web app, ensuring parity for all code shared.
-
-Brut's CLI support also allows for an expedient definition of a subcommand-style UI that behaves like a canonical UNIX command line
-app, without having to write a lot of code.  It wraps `OptionParser`, so if you are familiar with this library that's part of Ruby,
-you will be familiar with Brut's CLI API.
-
-See {file:doc-src/cli.md}.

data/doc-src/assets.md

@@ -1,98 +0,0 @@
-# Assets - CSS, JavaScript, Images
-
-To learn about Brut's JavaScript API support, see {file:doc-src/javascript.md}. This page is about how requests for assets are
-managed.
-
-At a high level, all assets are served out of the *public folder*, which is in `app/public`.  Brut copies files into this folder as
-part of the build and development process.
-
-Currently, Brut supports JavaScript, CSS, Fonts, and Images.  These are all copied and/or processed from a source location into
-`app/public` via {Brut::CLI::Apps::BuildAssets}:
-
-* JavaScript - From `app/src/front_end/js`, bundled to `app/public/js`.
-* CSS - From `app/src/front_end/css`, bundled to `app/public/css`.
-* Fonts - From `app/src/front_end/fonts`, bundled to `app/public/css` (yes, they are bundled to `css` as that is the only reason to have a built step for fonts - see below).
-* Images - From `app/src/front_end/iamges` to `app/public/images`.
-
-## Images
-
-Images are the simplest.  Images in Brut are not hashed, so they are essentially synced from `app/src/front_end/images` to
-`app/public/images`.  Your CDN should arrange for cache invalidation.
-
-## SVGs
-
-SVGs are treated specially.  They are located in `app/src/front_end/svgs`.  To use an svg, your ERB should use the
-{Brut::FrontEnd::Component::Helpers#svg} to inline the SVG into the page.  You can put SVGs intended to be linked-to in
-`app/src/front_end/images`, but for SVGs to be used as icons, for example, place them in `app/src/front_end/svgs` and use the `svg`
-helper.
-
-## JavaScript
-
-JavaScript is currently managed by ESBuild.  No fancy options are used nor currently possible.  By default, there is a single entry
-point for all your JavaScript, located in `app/src/front_end/javascript/index.js`.  This is compiled into `app/public/js/app-«HASH».js`, for example `app/public/js/app-EAALH2IQ.js`. A sourcemap is included.  Third party JS can be referenced and is assumed to be in `node_modules`.
-
-This should be sufficient for most apps, however you can use additional entry points. See {file:doc-src/javascript.md} for how to set
-this up. Also see "Hashing" below for how hashing works and is managed.
-
-## CSS
-
-CSS is also managed by ESBuild.  There is a single entry point located in `app/src/front_end/css/index.css`, and this is compiled into
-`app/public/css/styles-«HASH».css`, for example `app/public/css/styles-EAALH2IQ.css`. A sourcemap is included. Third party CSS can be
-referenced and is assumed to be in `node_modules`.
-
-Currently, there is no support for multiple CSS entry points - your entire app's CSS is expected to be in (or referenced by)
-`index.css`.
-
-To do that, Brut assumes you will use standard APIs, namely `@import`, and this is how you can bring in third party CSS as well as to
-manage your app's CSS in multiple files:
-
-    @import "bootstrap/index.css";
-    @import "colors.css";
-
-    html { font-size: 20px; }
-
-## Fonts
-
-ESBuild will handle fonts when CSS is built.  Fonts are hashed.  You should place fonts in `app/src/front_end/fonts`, however this is
-merely a convention.  ESBuild will find your font as long as you properly use `url(...)` to reference it.
-
-To follow the convention, here is how you might write your CSS:
-
-    /* index.css */
-    @font-face {
-      font-family: "Monaspace Xenon";
-      src: url("../fonts/monaspace-xenon.ttf") format("truetype");
-      font-display: swap;
-    }
-
-ESBuild treats the relative path in `url` as relative to where the file being procssed is, thus it will expect to find
-`app/src/front_end/fonts/monaspace-xenon.ttf`.  While it's not relevant to you where it's copied, the file will be hashed and copied
-to `app/public/css` and the `url(..)` will be adjusted, for example:
-
-    @font-face {
-      font-family: "Monaspace Xenon";
-      src: url("./monaspace-xenon-VZ5IIHXZ.ttf") format("truetype");
-      font-display: swap;
-    }
-
-## Hashing
-
-Hashing is on in development, testing, and production, as a way to minimize differences between the three environments.  The way Brut
-manages this is via the file `app/config/asset_metadata.json`.  This file maps the logical name of an asset to its hashed name. For
-example:
-
-    {
-      "asset_metadata": {
-        ".js": {
-          "/js/app.js": "/js/app-L6VPFHLG.js"
-        },
-        ".css": {
-          "/css/styles.css": "/css/styles-PHUHEJY3.css"
-        }
-      }
-    }
-
-{Brut::FrontEnd::Component::Helpers#asset_path} accepts the logical name (`/js/app.js`) and returns the actual name
-`/js/app-L6VPFHLG.js`).  `asset_metadata.json` is managed by `bin/build-assets`.
-
-Note that the fonts are not present in this file since they are only needed by CSS, and ESBuild handles the translation there.

data/doc-src/forms.md

@@ -1,214 +0,0 @@
-# Forms
-
-Brut's form support is designed to have parity with the Web Platform and allow you to both generate HTML and pasrse the results of a
-form submission from a single source of truth.  Brut's forms also allow the unification of client-side and server-side constraint
-violations so that you can provide client-side validations but not require JavaScript for all validations.
-
-## High Level Overview of Forms
-
-The purpose of a form is to allow the website visitor to submit data to you.  The Web Platform and web browser have deep support for
-this, but the core way this works is that you have a `<form>` element that contains form elements like `<input>` or `<select>` elements and, when this form is submitted, your server can access the values of each element and take whatever action is necessary.
-
-The lifecycle of this process looks like so:
-
-1. HTML is generated, including a form with elements based on a definition you provide.
-2. The visitor submits the form.
-3. If there are constraint violations that the browser can detect, the form will not be submitted to your server.
-4. If all constraints are satisfied (or the visitor bypasses client-side constraints), the server receives the form submission.
-5. A {Brut::FrontEnd::Handler} is triggered to process that submission.  The handler should re-check the client-side constraints and
-   can perform further server-side checks.
-6. The handler will decide what the website visitor will experience next (e.g. re-render the form, proceed to another page, etc).
-
-As a developer, you must write four pieces of code:
-
-* Call {Brut::SinatraHelpers::ClassMethods.form} to declare the route.
-* Create a subclass of {Brut::FrontEnd::Form} (whose name is determined by the route name). This class declares the inputs of your
-form.
-* Create a subclass of {Brut::FrontEnd::Handler} (whose name is determined by the route name). This class processes the form.
-* ERB to generate the form.  The classes in {Brut::FrontEnd::Components::Inputs} have methods like {Brut::FrontEnd::Components::Inputs::TextField.for_form_input} that will generate HTML for you.
-
-## Concepts
-
-Brut tries to create concepts that have a direct analog to the web platform.
-
-These basic concepts form the basis for Brut's form support:
-
-* *Form* is an HTML `<form>`
-* *Input* is an HTML `<input>`, `<select>`, `<textarea>`, etc.
-* *Input Name* is the name of an input, as defined by the `name` attribute.
-* *Submitting a form* is when the browser submits a form to the form's action. This is done with an HTTP GET or HTTP POST only. No
-other HTTP methods can submit a form.
-* *Constraint Violation* describes invalid data in an input.
-
-Building on these, Brut specifies how it manages Forms, Inputs, and Submission:
-
-* *Form Class* defines the inputs a specific form will have.
-* *Input Definition* defines the input for a given input name.
-* *Form Object* holds the values and constraint violations of all inputs.
-* *Handler* is a class that processes a form submission. It's `handle!` method can access the Form Object representing a submission.
-* *Server-Side Constraint Violation* describes invalid data that required server processing to determine.
-
-## Basic Workflow for Handling a Form
-
-### Define Your Form
-
-In Brut, a *form* class (or *form object*) holds metadata about the form in question. Namely, it defines all of the inputs and any
-client-side constraints. For example, here is a form to create a new widget, where the name must be at least 3 characters and is
-required, and there is an optional description:
-
-    class NewWidgetForm < AppForm
-      input :name, minlength: 3
-      input :description, required: false
-    end
-
-This form class provides a few features:
-
-* It can be used to generate HTML. For example, the "name" field will generate `<input type="text" name="name" required minlength="3">`
-* It holds the data submitted to the server, serving as an allowlist of which parameters are accepted. For example, if the browser
-submits "name", "description", and "price", since "price" is not an input of this form, the server will discard that value. Your code
-will only have access to "name" and "description"
-* It can validate the client-side constraints on the server.  If a visitor submits the form, bypassing client-side constraint
-validations, and "name" is only two characters, the form object will see that the "name" field has a violation.
-
-### Define Your Handler
-
-Handlers are like controller methods in Rails - they receive the data from a request and process it.  Unlike a Rails controller, a
-Handler is a normal class. It implements the method `handle`.  The method signature you use for `handle` determines what data will
-be passed into it.  The return value of `handle` determines what happens after processing is complete.
-
-Suppose that creating a widget requires that the name be unique.  If it's not, we re-render the page containing the form and show the
-user the errors.  Suppose that the page in question is `/new_widget`, which would be the class `NewWidgetPage`.
-
-    class NewWidgetHandler < AppHandler
-      def handle(form:)
-        if !form.constraint_violations?
-          if DB::Widget[name: form.name]
-            form.server_side_constraint_violation(input_name: :name, key: :not_unique)
-          end
-        end
-
-        if form.constraint_violations?
-          return NewWidgetPage.new(form:)
-        end
-
-        DB::Widget.create(name: form.name, description: form.description)
-        redirect_to(WidgetsPage)
-      end
-    end
-         
-
-{file:doc-src/pages.md Pages} provides more information about what `NewWidgetPage` and `WidgetsPage` might be or do, but the logic in
-the handler is, hopefully, clear.  If our form is free of client-side constraint violations, we check to see if there is another
-widget with the name from the form. If there is, we set a server-side constraint violation.
-
-After that, if the form has any constraint violations (server-side or client-side), we return `NewWidgetPage` initialized with our
-existing form.  This will allow that page to generate HTML that includes information about the constraint violations detected.
-
-If there aren't constraint violations, we create a widget in the database, then redirect to `WidgetsPage`.  {Brut::FrontEnd::HandlingResults#redirect_to} is a convienience method for figuring out the URL for a given page.
-
-### Generate HTML
-
-In this example, `NewWidgetPage` would be generating the HTML form.  It's class might look like so:
-
-    class NewWidgetPage < AppPage
-
-      attr_reader :form
-
-      def initialize(form: nil)
-        @form ||= NewWidgetForm.new
-      end
-    end
-
-Here is the most direct way to use the form object to render HTML.
-
-      <%= form_tag for: form do %>
-        <%= component(Brut::FrontEnd::Components::TextField.for_form_input(form:, input_name: :name)) %>
-        <%= component(Brut::FrontEnd::Components::Textarea.for_form_input(form:, input_name: :description)) %>
-        <button>Save</button>
-      <% end %>
-
-`for_form_input` uses the metadata in the form, along with the name of the field, to generate the appropriate HTML.  This will only
-generate an `<input>` tag, so you have complete flexibility to style it however you like.
-
-You can also use `constraint_violations` to render any errors:
-
-      <%= form_tag for: form do %>
-
-        <%= component(Brut::FrontEnd::Components::TextField.for_form_input(form:, input_name: :name)) %>
-        <%= constraint_violations(form:, input_name: :name) %>
-
-        <%= component(Brut::FrontEnd::Components::Textarea.for_form_input(form:, input_name: :description)) %>
-        <%= constraint_violations(form:, input_name: :description) %>
-
-        <button>Save</button>
-      <% end %>
-
-## Multiple Inputs with the Same Name
-
-The HTTP spec allows for any number of inputs with the same name. All values are submitted.  Rack, upon which Brut is based, further
-provides a way to access such duplicate names as an array, using a naming convention.
-
-Brut forms support this via `array: true` when defining an input:
-
-    class NewWidgetForm < AppForm
-      input :name, minlength: 3, array: true
-      input :description, required: false, array: true
-    end
-
-When you do this, a call to `for_form_input` will require an index, as will any other method you use to interact with the form, such
-as `server_side_constraint_violation`.  When the HTML is generated, the `name=` of the `<input>` will use Rack's naming convention:
-
-    <input type="text" name="name[]" ...>
-
-To access the values, you can pass an index to the generated method name, or use the `_each` form:
-
-    def handle!(form:)
-      form.name(1) # get the second value for the 'name' input
-      form.name_each do |value,i|
-        value # is the value of the input, empty string if omitted
-        i     # is the zero-based index
-      end
-    end
-
-When generating HTML, the form object will generate any number of inputs that you request:
-
-      <%= form_tag for: form do %>
-
-        <% 10.times do |index| %>
-            <%= component(Brut::FrontEnd::Components::TextField.for_form_input(form:, input_name: :name, index:)) %>
-            <%= constraint_violations(form:, input_name: :name) %>
-        <% end %>
-
-        <button>Save</button>
-      <% end %>
-
-## Styling and Client-Side Behavior
-
-While browsers have long-supported client-side constraint validations, there are a few complications that make them hard to use in
-practice.  Brut provides solutions for most of these issues and allows you to unify your error reporting into a single user experien
-ce, regardless of where the constraint violation was identified. This does, however, require JavaScript.  But, it is entirely opt-in.
-
-### Issue: Blank Forms Match `:invalid` Pseudo-Class
-
-If an input is required, it will match the `:invalid` pseudo class if it has no value, even if a user has not interacted with the
-input.  While Brut cannot change this behavior, it *does* allow you to have better control.
-
-If you surround your `<form>` with the `<brut-form>` custom element, that element will add `data-submitted` to the `<form>` element
-when submission is attempted. This means that your CSS can target something like `form[data-submitted] input:invalid` so that any
-styling for constraint violations will only show up if the user has attempted to submit the form.
-
-### Issue: App-Controled Messaging for Client-Side Constraint Violations
-
-While it's not currently possible to control the browser's UI around client-side constraint violations, Brut does allow you to provide
-your own error messages and UX when this happens. This means you can unify your client-side and server-side messaging so it looks the
-same no matter what.
-
-When a field is detected to be invalid, `<brut-form>` will locate a `<brut-cv-messages>` custom element and provide it with the
-`ValidityState` of the input. This will create one `<brut-cv>` custom element for each constraint violation.  The `<brut-cv>` custom
-element will use its `key=` attribute to locate the appropriate `<brut-i18n-translation>` custom element, which your server should've
-rendered with the appropriate error messages.
-
-This has the effect of inserting a localized message you control into the DOM wherever you want it for reporting the error to the
-user.
-
-