brut 0.0.20 → 0.0.21

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.
-
-

data/doc-src/handlers.md

@@ -1,83 +0,0 @@
-# Handlers
-
-In Brut, a *handler* responds to an HTTP request that *isn't* inteded to render a web page.  Primarily, a handler is used to process a
-form submission, but a handler can also respond to an Ajax request.  A handler is like a controller in Rails, however in Brut, a
-handler is a class you implement that has a method that receives arguments and a return value that controls the response (unlike controllers in Rails).
-
-## Defining a Route to be Handled
-
-There are three ways to define a route that requires a handler, `form`, `action`, and `path`.
-
-    
-    class App < Brut::Framework::App
-
-      routes do
-
-        form   "/new_widget"
-        action "/archive_widget/:id"
-        path   "/payment_received", method: :get
-      end
-    end
-
-`form` indicates you have a form you are going to render in HTML and process its submission.  The use of `form` requires that you have
-a {Brut::FrontEnd::Form} defined (see {file:doc-src/forms.md}) as well as a handler.  The names are conventional based on the route.
-In the example above, Brut will expect `NewWidgetForm` and `NewWidgetHandler` to exist.
-
-You can create these with `bin/scaffold`:
-
-    bin/scaffold form NewWidget
-
-`action` is used when you have a form to submit, but it has no user controls to collect the data to submit.  This is akin to Rails'
-`button_to` where the URL describes everything needed to handle a user's action.  In the example above, you can imagine a form with a
-method to `/archive_widget/<%= widget.id %>` that has a button labeled "Archive Widget".  All that's needed is to submit to the
-server.
-
-In that case, only a handler is required.  The name is again conventional. In this case, `ArchiveWidgetWithId`.  You can create this
-with `bin/scaffold`
-
-    bin/scaffold handler ArchiveWidthWithId
-
-The last case, `path`, is for arbitray routes.  It works the same way as `action`, but requires a `method:` to declare the HTTP
-method.
-
-## Implementing a Handler
-
-Regardless of how you declare a route, all handlers must inherit {Brut::FrontEnd::Handler} (though realistically, they will inherit
-`AppHandler`, which inherets `Brut::FrontEnd::Handler`) and implement `handle`.
-
-`handle` can accept keyword arguments that are injected by Brut according to the rules outlined in {file:/doc-src/keyword-injection.md Keyword Injection}.  Note that handlers that process forms should declare `form:` as a keyword argument. They will be given an instantiated instance of their form, based on the values in the form submission from the browser.
-
-The return value of the method determines what will happen:
-
-* `URI` - the visitor is redirected to this URI. Typically, you'd achieve this with the {Brut::FrontEnd::HandlingResults#redirect_to}
-helper.
-* {Brut::FrontEnd::Component} - this component's HTML is rendered. Note that since {Brut::FrontEnd::Page} is a subclass of
-`Brut::FrontEnd::Component}, returning a page instance will render that entire page.  This is useful when re-rendering a page with
-form errors.
-  - You can also return a two-element array with the first element being a component and the second being a `Brut::FrontEnd::HttpStatus`.  This will render the component's HTML but use the given status as the HTTP status.
-* {Brut::FrontEnd::HttpStatus} - this status is returned with no content. Typically, you'd achieve this with the {Brut::FrontEnd::HandlingResults#http_status}
-* {Brut::FrontEnd::Download} - a file will be downloaded
-
-## Hooks
-
-See {file:/doc-src/hooks.md} for more discussiong, but implementing `before_handle` will allow you to run code before `handle` is
-called.  This feature is mostly useful for a base class or module to share re-usable logic.
-
-## Testing Handlers
-
-Since a handler is just a class, you can test it conventionally, but there are a few things to keep in mind that can make testing your
-handler easier.
-
-First is that you should call `handle!`, not `handle`.  The public interface of a handler is `handle!`—`handle` is a template method.
-`handle!` will call `before_render`, so you should still call `handle!`, even if you are testing the logic in `before_render`.
-
-You can also simplify your expectations with the following matchers:
-
-* `have_redirected_to` - asserts that the handler redirected to the given URL. It can be given a `URI` or a page class.
-* `have_rendered`- asserts that the handler renders the given component or page.  It expects the page or component class.
-* `have_returned_http_status` - asserts that the handler returned the given HTTP status.  This works for a lot of return values that
-the handler can return:
-  - If the handler returned a `URI`, the matcher will match on a 302 and fail otherwise
-  - If the handler returns an HTTP status code, the matcher's code must match (or the code must be omitted)
-  - If the handler returns anything else, the matcher will match on a 200 and fail otherwise
-