brut 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c756b30db51ff455ac587492ee974356c0dbe4084483fc562854ce682cca8014
-  data.tar.gz: 7ce5250e1bfac5f9cd61f3329399a5896f83ce4af9457882190a9e089cf35fcd
+  metadata.gz: c1fd649346396f27b70064c601a639187c08fec7d38f4efc973c3a9839d2c163
+  data.tar.gz: a06518da1bb198c89acfd13dca787fabb302546097e08d8917bf1c500d399f39
 SHA512:
-  metadata.gz: 35f7f592155864b2bc178c2c8267967c95a141da0105c07e2969c3a646435fb23101a3070e686aebd5fc797e1938155e7e8d4f6af029bb93eb208350f4774014
-  data.tar.gz: db78b9b4ac1be3561a599cae098a2ae4c005a027d0f9c768e8d766add2c736ee87614505bc131750cb1b3af8d99b916054c427c48556ba8d2f5422c002125de8
+  metadata.gz: 0ecde01ea2f1cdc821e24e835fe18a7420848601d469435c74abe3d020187fccc73004ce063f7c242f663796d2470145981e6ace8a742ae885568abb0533eb74
+  data.tar.gz: da0e5c69737041a6ff25366c4fd4cb41214f97b1ada9c78f878544f380f8370bcd155f8f7e6b77d52b50a77b6270b08847e5b1e10bec657b464d289d84747c4f

data/.gitignore

@@ -5,3 +5,9 @@
 # from inside the dev environment. As such, these are real secrets and 
 # should never be checked in
 /dx/credentials
+
+# Don't know what this is for, so not checking it in.
+/.yardoc
+
+# Ignore the docs for now
+/docs

data/Gemfile.lock

@@ -1,12 +1,16 @@
 PATH
   remote: .
   specs:
-    brut (0.0.1)
+    brut (0.0.2)
+      concurrent-ruby
       dotenv
       factory_bot
       faker
       i18n
+      irb
       nokogiri
+      opentelemetry-exporter-otlp
+      opentelemetry-sdk
       ostruct
       prism
       rack-protection
@@ -42,6 +46,7 @@ GEM
     bigdecimal (3.1.8)
     concurrent-ruby (1.3.4)
     connection_pool (2.4.1)
+    date (3.4.1)
     diff-lcs (1.5.1)
     dotenv (3.1.4)
     drb (2.2.1)
@@ -49,8 +54,33 @@ GEM
       activesupport (>= 5.0.0)
     faker (3.5.1)
       i18n (>= 1.8.11, < 2)
+    google-protobuf (4.29.3)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.29.3-aarch64-linux)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.29.3-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.29.3-x86-linux)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.29.3-x86_64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.29.3-x86_64-linux)
+      bigdecimal
+      rake (>= 13)
+    googleapis-common-protos-types (1.18.0)
+      google-protobuf (>= 3.18, < 5.a)
     i18n (1.14.6)
       concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.1)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
     logger (1.6.1)
     minitest (5.25.1)
     mustermann (3.0.3)
@@ -67,8 +97,33 @@ GEM
       racc (~> 1.4)
     nokogiri (1.16.7-x86_64-linux)
       racc (~> 1.4)
+    opentelemetry-api (1.4.0)
+    opentelemetry-common (0.21.0)
+      opentelemetry-api (~> 1.0)
+    opentelemetry-exporter-otlp (0.29.1)
+      google-protobuf (>= 3.18)
+      googleapis-common-protos-types (~> 1.3)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-sdk (~> 1.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-registry (0.3.1)
+      opentelemetry-api (~> 1.1)
+    opentelemetry-sdk (1.7.0)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-registry (~> 0.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-semantic_conventions (1.10.1)
+      opentelemetry-api (~> 1.0)
     ostruct (0.6.1)
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
     prism (1.2.0)
+    psych (5.2.3)
+      date
+      stringio
     racc (1.8.1)
     rack (3.1.8)
     rack-protection (4.0.0)
@@ -79,6 +134,11 @@ GEM
     rackup (2.2.1)
       rack (>= 3)
     rake (13.2.1)
+    rdiscount (2.2.7.3)
+    rdoc (6.12.0)
+      psych (>= 4.0.0)
+    reline (0.6.0)
+      io-console (~> 0.5)
     rexml (3.3.9)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
@@ -105,6 +165,7 @@ GEM
       rack-protection (= 4.0.0)
       rack-session (>= 2.0.0, < 3)
       tilt (~> 2.0)
+    stringio (3.1.3)
     temple (0.10.3)
     tilt (2.4.0)
     tzinfo (2.0.6)
@@ -112,6 +173,7 @@ GEM
     tzinfo-data (1.2024.2)
       tzinfo (>= 1.0.0)
     uri (1.0.2)
+    yard (0.9.37)
     zeitwerk (2.7.1)
 
 PLATFORMS
@@ -127,7 +189,10 @@ DEPENDENCIES
   brut!
   bundler
   rake
+  rdiscount
+  rdoc
   rspec (~> 3.0)
+  yard
 
 BUNDLED WITH
    2.5.23

data/README.md

@@ -19,3 +19,39 @@ Or install it yourself as:
 
     $ gem install brut
 
+## Developing
+
+The dev environment is managed by Docker and you are encouraged to use this. It's set up so you can edit your code on your computer
+with your editor, but all commands are run inside Docker, which should be more consistent across developer workstations.
+
+1. On Windows, setup WSL2
+2. Install Docker
+3. Build the image(s) you will use to start containers where development happens:
+
+        dx/build
+4. Start up the dev environment
+
+        dx/start
+5. At this point, you can "log in" to the virtual machine/docker container via:
+
+        dx/exec bash
+6. From there, you have a UNIX prompt where you can run all commands.  You can also run any command via:
+
+        dx/exec ls -l # or whatever
+
+   This is how you can configure your editor to issue commands and access their output.
+
+7. To set everything up:
+
+        dx/exec bin/setup --no-credentials
+
+   The `--no-credentials` means that you will not be able to push to GitHub or RubyGems from within the Docker container. This
+   ability is only needed by maintainers to push new versions of the gem. You can push to GitHub from your computer.
+
+## Docs
+
+* See {file:doc-src/architecture.md Architecture}
+* See {file:doc-src/pages.md Pages and Components}
+* See {file:doc-src/forms.md Forms}
+* See {file:docs-src/keyword-injection.md Keyword Injection}
+* See {file:docs-src/route-hooks.md Route Hooks}

data/Rakefile

@@ -1 +1,23 @@
 require "bundler/gem_tasks"
+
+require "pathname"
+
+docs_dir = (Pathname(__FILE__).dirname / "docs").expand_path.to_s
+desc "Generate YARD doc"
+task :docs do
+  files = Dir["doc-src/*.md"].map { |file|
+    "--files #{file}"
+  }.join(" ")
+  system "bundle exec yard doc -o '#{docs_dir}' #{files} -m markdown -M rdiscount --backtrace"
+end
+
+desc "Show YARD status"
+task :stats do
+  system "bundle exec yard stats --list-undoc"
+end
+
+desc "Clean up droppings"
+task :clean do
+  FileUtils.rm_rf docs_dir, verbose: true
+end
+

data/brut.gemspec

@@ -34,9 +34,11 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_runtime_dependency "irb"
   spec.add_runtime_dependency "dotenv"
   spec.add_runtime_dependency "ostruct" # squelch some warning - this is not used
   spec.add_runtime_dependency "factory_bot"
+  spec.add_runtime_dependency "concurrent-ruby"
   spec.add_runtime_dependency "faker"
   spec.add_runtime_dependency "i18n"
   spec.add_runtime_dependency "nokogiri"
@@ -52,9 +54,14 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "tzinfo"
   spec.add_runtime_dependency "tzinfo-data"
   spec.add_runtime_dependency "zeitwerk"
+  spec.add_runtime_dependency "opentelemetry-sdk"
+  spec.add_runtime_dependency "opentelemetry-exporter-otlp"
 
   spec.add_development_dependency "activesupport"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "rdiscount"
+  spec.add_development_dependency "rdoc"
 end

data/doc-src/architecture.md

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

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

@@ -0,0 +1,214 @@
+# 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.
+
+