brut 0.17.0 → 0.18.0

data/brutrb.com/forms.md

@@ -1,238 +0,0 @@
-# Forms
-
-In HTML, forms are the way data is submit to the server.  Forms attract complexity
-since they interact with user experience, data validation, and interaction with a
-back-end database.
-
-## Overview
-
-Forms in Brut accomplish three things:
-
-* Forms model the data elements of a `<form>`, including client-side constraints (which Brut can check server-side as well).
-* Forms assist in HTML generation, to ensure the HTML elements are consistent and
-correct.
-* Forms hold data submitted to the server. No need for strong parameters or digging
-into a Hash of Whatever.
-
-Since forms can lead to a lot of complexity, this module will stick to the very
-basics.  There are several recipes we'll link to that explain more complex
-interactions with forms.
-
-### Declaring Form Data/Elements
-
-When you [create a form route](/routes), this imlplies a form class exists to
-specify the data:
-
-```ruby
-# app/src/app.rb
-routes do
-  form "new_widget"
-end
-
-# app/src/front_end/forms/new_widget_form.rb
-class NewWidgetForm < AppForm
-end
-```
-
-`AppForm` extends `Brut::FrontEnd::Form`, which provides class methods you can use
-to declare your form's elements.  Let's say our form has a name (that must be at least 3 characters), a quantity (integer greater than 0), and an optional description.
-
-```ruby
-class NewWidgetForm < AppForm
-  input :name, minlength: 3
-  input :quantity, type: :number, min: 0, step: 1
-  input :description, required: true
-end
-```
-
-`input` declares a form element that will ultimately be handled by an `<input>` or
-`<textarea>` tag.  `select` and `radio_button_group` are also avaiable, and are
-discussed in recipes.
-
-`input` accepts an input name used for `<input>`'s `name` attribute.  It also
-accepts keyword arguments that match the initializer of
-`Brut::FrontEnd::Forms::InputDefinition`.  You'll notice those values mirror the
-various attributes related to client-side constraint validations, for example
-`minlength:` and `pattern:`.
-
-Form elements have some defaults, as described below:
-
-| Declaration | Default Behavior |
-|---|---|
-| `input :email` | `type: :email` |
-| `input :password` | `type: :password` |
-| `input :password_confirmation` | `type: :password` |
-| `input «any other name»` | `type: :text` |
-| `input «name», type: :checkbox` | `required: false` |
-| `input «name» type: «not checkbox»` | `required: true` |
-
-### Using Forms to Generate HTML
-
-One reason Brut models forms as classes with declared inputs is that you can then
-use an instance of that class to generate HTML.  Brut will generate appropriate
-HTML, optionally configured to show a pre-existing value from the form.
-
-The classes that do this are in `Brut::FrontEnd::Components`
-
-| Class | Purpose |
-|---|---|
-|`Brut::FrontEnd::Components::FormTag` | Creates a `<form>` tag that submits to the form's configured route and includes [CSRF protection](/security). |
-|`Brut::FrontEnd::Components::InputTag` | Creates an `<input>` tag |
-|`Brut::FrontEnd::Components::RadioButton` | Creates an `<input type="radio">` tag
-for use in a radio button group. |
-|`Brut::FrontEnd::Components::SelectTagWithOptions` | Creates a `<select>` tag with
-`<option>` tags inside. |
-|`Brut::FrontEnd::Components::TextareaTag` | Creates a `<textarea>` tag. |
-|`Brut::FrontEnd::Components::ButtonTag` | Creates a `<button>` tag to submit the form. |
-
-All of these classes have an initializer that accepts:
-
-* `form:` the form object, used to figure out the HTML attributes and current value of the element.
-* `input_name:` to know which input is being generated.
-* `index:` for [indexed form elements](/recipes/indexed-forms.md).
-* `**html_attributes` any other HTML attributesyou'd like to include.
-
-These class names are quite long, but since these are Phlex components, you can
-`include` `Brut::FrontEnd::Components` and access their initializers as a [Phlex
-kit](https://phlex.fun):
-
-```ruby
-class NewWidgetPage < AppPage
-  include Brut::FrontEnd::Components
-
-  def initialize(form: nil)
-    @form = form || NewWidgetForm.new
-  end
-
-  private attr_reader :form
-
-  def page_template
-    FormTag(for: form) do
-      Components::InputTag(form:,    input_name: :name)
-      Components::InputTag(form:,    input_name: :quantity)
-      Components::TextareaTag(form:, input_name: :description)
-    end
-  end
-end
-```
-
-Phlex kits provides a methods named for the class that call that class' constructor.
-
-The code above will generate this HTML
-
-```html
-<form action="/new_widgets" method="post">
-  <input type="hidden" name="authenticity_token" value=«value»>
-  <input type="text"   name="name"     required minlength="3">
-  <input type="number" name="quantity" required min="0" step="1">
-  <textarea name="description">
-  </textarea>
-</form>
-```
-
-Forms accept a single initializer parameter, `params` that is a `Hash`.
-`Brut::FrontEnd::Form` implements this initializer, and will pluck values from the
-hash to initialize the inputs:
-
-::: code-group
-
-```ruby [Form Class] {5-8}
-class NewWidgetPage < AppPage
-  include Brut::FrontEnd::Components
-
-  def initialize(form: nil)
-    @form = form || NewWidgetForm.new( params: {
-      name: "My New Widget",
-      quantity: 10,
-    })
-  end
-
-  # ...
-
-end
-```
-
-```html [HTML Generated] {3,5}
-<form action="/new_widgets" method="post">
-  <input type="hidden" name="authenticity_token" value=«value»>
-  <input type="text"   value="My New Widget"
-         name="name"     required minlength="3">
-  <input type="number" value="10"
-         name="quantity" required min="0" step="1">
-  <textarea name="description">
-  </textarea>
-</form>
-```
-
-:::
-
-### Accessing Data in a Submitted Form
-
-As mentioned in [routes](/routes), a `form` route implies not just a form class, but
-a [handler](/handlers) class to receive the submitted data.
-
-We'll discuss handlers in the next section, but they demonstrate how you can access
-a form's data:
-
-```ruby
-class NewWidgetHandler < AppHandler
-  def initialize(form:)
-    @form = form
-  end
-
-  def handle
-    form.name        # => whatever name was submitted
-    form.quantity    # => whatever quantity was submitted
-    form.description # => description provided
-  end
-end
-```
-
-A few things to note about how this works:
-
-* Only those inputs declared in the form class can be accessed. All other values are
-discarded. No need for "strong parameters".
-* All values are strings, because this is what HTML provides.
-* Blank values are coerced to `nil`.
-
-The next module will deal with form constraints and validations, in particular how
-to manage the user experience around client-side constraint violations, how to
-re-check them server side, and how to perform server-side checks.
-
-## Testing
-
-Form classes don't need any logic on them, but they can be given helper methods or other logic if it makes sense. To test them, test them like any other class - instantiate an object and examine the behavior of its methods.
-
-## Recommended Practices
-
-### Create Components to Generate Form Controls
-
-`Brut::FrontEnd::Components::Inputs` will generate the basic tags like `<input>` or
-`<select>`.  Everything else like `<label>` is up to you.  We recommend that you
-create [components](/components) to generate the markup required for *your* inputs
-and controls.
-
-The recipe ["Creating a Text Field"](/recipes/text-field-component) will walk you
-through the steps and considerations.
-
-### Take Advantage of Client Side Constraints
-
-Even though client-side constraints can sometimes be awkward in certain browsers,
-they are going to be eminently usable and accessible, and you can easily
-re-validate them on the server side.
-
-## Technical Notes
-
-> [!IMPORTANT]
-> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
-> internals, the source code is always more correct.
-
-_Last Updated May 13, 2025_
-
-For HTML generation, there are few classes that work together:
-
-* *input definitions* define an input and tend to provide an API similar to HTML's. See `Brut::FrontEnd::Forms::InputDefinition`.
-* *inputs* represent the runtime state of an input from the browser.  Whereas an input definition has no state, the input does. It delegates much of its behavior to the underlying input definition. It's `value=` method performs client-side constraint validations by creating a `Brut::FrontEnd::Forms::ValidityState` internally. See `Brut::FrontEnd::Forms::Input`.
-* `Brut::FrontEnd::Forms::InputDeclarations` is a module that allows creating input definitions inside your form
-class.  It implements the class methods like `input`.
-* `Brut::FrontEnd::Components::Inputs` contains components used to generate `<input>` fields.  These classes will coerce the value of the `input` they are given to generate the correct HTML.

data/brutrb.com/getting-started.md

@@ -1,142 +0,0 @@
-# Getting Started
-
-Brut is developed alongside a separate gem called `mkbrut`, which allows you to
-create a new Brut app. It will set up your dev environment as well.
-
-## Get `mkbrut`
-
-The simplest way to use `mkbrut` is to use an existing [Docker image](https://hub.docker.com/repository/docker/thirdtank/mkbrut/general).  You don't have to install or configure Ruby:
-
-```
-docker run \
-       --pull always \
-       -v "$PWD":"$PWD" \
-       -w "$PWD" \
-       -u $(id -u):$(id -g) \
-       -it \
-       thirdtank/mkbrut \
-       mkbrut my-new-app
-```
-
-If you already have Ruby 3.4 installed, you can install `mkbrut` directly:
-
-```
-> gem install mkbrut
-> mkbrut my-new-app
-```
-
-## Init Your App
-
-A Brut app just needs a name, which will be used to derive a few more useful values.
-For now:
-
-::: code-group
-
-``` [Docker-based]
-docker run \
-       --pull always \
-       -v "$PWD":"$PWD" \
-       -w "$PWD" \
-       -u $(id -u):$(id -g) \
-       -it \
-       thirdtank/mkbrut \
-       mkbrut my-new-app
-```
-
-``` [RubyGems-based]
-mkbrut my-new-app
-```
-
-:::
-
-This will create your new app, along with some demo routes, components, handlers, and tests. If this is your first time using Brut, we recommend you examine these demo components.
-
-To create your app without the demo components:
-
-::: code-group
-
-``` [Docker-based]
-docker run \
-       --pull always \
-       -v "$PWD":"$PWD" \
-       -w "$PWD" \
-       -u $(id -u):$(id -g) \
-       -it \
-       thirdtank/mkbrut \
-       mkbrut my-new-app --no-demo
-```
-
-``` [RubyGems-based]
-mkbrut my-new-app --no-demo
-```
-
-:::
-
-## Start Your Dev Environment
-
-Brut includes a dev environment based on Docker.  It uses Docker compose to run a
-Docker container where your app will run, a Docker container for Postgres, and a
-Docker container for local observability via OpenTelemetry.
-
-1. [Install Docker](https://docs.docker.com/get-started/get-docker/)
-2. Build the image used to create you app's container:
-
-   ```
-   > dx/build
-   ```
-3. Start up all the containers:
-
-   ```
-   > dx/start
-   ```
-4. Now, install your aps gems and set it all up:
-
-   ```
-   > dx/exec bin/setup
-   ```
-
-Now, you're ready to go.  See [Dev Environemnt](/dev-environment) for details on how
-this all works.
-
-> [!NOTE]
-> Instead of running `dx/exec` in front of your commands, you
-> can instead do `dx/exec bash` to "log in" to the running container.
-> You'll have a normal prompt and can issue commands directly from there.
-
-## Run the App
-
-```
-dx/exec bin/dev
-```
-
-You can now visit your app at `localhost:6502`
-
-You can make changes and see them when you reload.  Open up `app/src/front_end/pages/home_page.rb` *in your editor running on your computer* and change the `h1` to look like so:
-
-```ruby {6}
-class HomePage < AppPage
-  def page_template
-    div(class: "flex flex-column items-center justify-center h-80vh") do
-      img(src: "/static/images/icon.png", class: "h-50")
-      h1(class: "ff-sans ma-0 lh-title f-5") do
-        "Welcome to My New App!"
-      end
-
-      # ...
-```
-
-When you reload your browser, you'll see your change
-
-## Run the Tests
-
-There are a few tests you can run, as well as some checks that you aren't using
-RubyGems with security vulnerabilities.  Run it all now with `bin/ci`:
-
-```
-dx/exec bin/ci
-```
-
-## Now Build The Rest of Your App 🦉
-
-You can [follow the tutorial](/tutorial), check out the [conceptual overview](/overview), or dive straight into the [API docs](/api/index.html).  You might also want to check out the docs for [LSP Support](/lsp).
-

data/brutrb.com/handlers.md

@@ -1,177 +0,0 @@
-# Handlers & Actions
-
-Handlers process form submissions, and *actions* work similarly to process any arbitrary HTTP request.
-
-## Overview
-
-Where a [page](/pages) renders a web page in HTML, a *handler* responds to all other HTTP requests.  To respond to such HTTP requests, you'd first create a [route](/routes), using `form`, `action`, or `path`.
-
-### Handler Structure
-
-A handler's initializer is subject to [keyword injection](/keyword-injection), with
-the addition of the `form:` keyword, which, if present, will be an instance of the
-associated form class, populated with the data in the form submission (not available for `path` or `action` routes).
-
-You must implement `handle` to process the form.  **A handler's public API, as
-called by Brut and your tests, is `handle!`**, however you implement `handle`, which
-`handle!` calls.
-
-`handle`'s return value dictates what will happen next:
-
-| Return Value | Behavior |
-|---|---|
-|Instance of a page or component | That page or component's HTML is generated and returned.  This is not a redirect, but more like `render :new` in a Rails controller |
-|`Brut::FrontEnd::HttpStatus` | This HTTP status is returned with no body. Use `http_status` from `Brut::FrontEnd::HandlingResults` (included in all handlers) to create an instance from a number |
-| `URI` | Redirect to the URI.  Use `redirect_to` from `Brut::FrontEnd::HandlingResults` (included in all handlers) to generate a URI from a page class and parameters |
-| Two element array with *element 0* being a `Brut::FrontEnd::HttpStatus`, and *element 1* being a page or component instance | Generates the page or component's HTML, but sets the given status instead of 200. Useful for Ajax responses where the HTTP status affects client-side behavior |
-| `Brut::FrontEnd::Download` | Download a file |
-| `Brut::FrontEnd::GenericResponse` | wrap any Rack response |
-
-> [!IMPORTANT]
-> The only way to render something other than HTML is to do so as a
-> `GenericResponse`, which is basically the low-level Rack API. Brut
-> encourages Ajax responses to be HTML and for you to use the browser's
-> APIs to interact with that HTML.  Brut may make it easier to work
-> with other types of content in the future.
-
-### Handling a Form Submission
-
-A common pattern when handling a form submisssion is to check for any constraint
-violations. If there are some, re-generate the HTML for the page containing the
-form, highlighting the violations. Otherwise, save the data and redirect to another
-page.
-
-Here's how that looks:
-
-```ruby
-class NewWidgetHandler < AppHandler
-  def initialize(form:)
-    @form = form
-  end
-
-  def handle
-    # if no client-side violations were submitted
-    if @form.valid?
-      widget = DB::Widget.find(name: form.name)
-      if widget
-        @form.server_side_constraint_violation(
-          input_name: :name,
-          key: :name_is_taken
-        )
-      end
-    end
-
-    if @form.constraint_violations?
-      NewWidgetPage.new(form: @form)
-    else
-      DB::Widget.create(name: form.name,
-                        quantity: form.quantity,
-                        description: form.description)
-      redirect_to(WidgetsPage)
-    end
-  end
-end
-```
-
-Unlike a Rails controller, the return value of `handle` controls the behavior.  As
-we saw in [Form Constraints](/form-constraints), the HTML generated by
-`NewWidgetPage` will show constraint violations, so by returning
-`NewWidgetPage.new(form: @form)`, the page has the same form instance, including all
-the constraint violations, and the visitor will see the problems.
-
-### Handling Other Requests
-
-Non-form submissions work similarly, however there is no form available.  If the
-request could potentially involve a visitor-initiated error, you can use the
-[flash](/flash-and-session) to communicate back.  The flash is available for injection into the
-initializer and, assuming your page uses it to show messages, can allow for
-communication when something is wrong:
-
-```ruby
-class App
-  # ...
-
-  routes do
-    action "/delete_widget/:widget_id"
-
-    # ...
-  end
-end
-
-class DeleteWidgetByIdHandler < AppHandler
-  def initialize(widget_id:, flash:)
-    @widget_id = widget_id
-    @flash     = flash
-  end
-
-  def handle
-    widget = DB::Widget.find!(id: @widget_id)
-    if widget.can_delete?
-      widget.delete
-      @flash.notice = :widget_deleted
-      redirect_to(WidgetsPage)
-    else
-      @flash.alert = :widget_cannot_be_deleted
-      WidgetsPage.new
-    end
-  end
-end
-```
-
-### Hooks
-
-A handler's public API is `handle!`, because it first calls `before_handle`. This
-operates as a before hook, and has the same return values as `handle`, with the
-exception of also recognizing `nil`, which indicates processing should proceed to
-`handle`.
-
-Generally, you don't need to implement hooksd on a per-handler  basis, but may find
-it useful in a shared super class to implement cross-cutting behavior.
-
-## Testing
-
-See [Unit Testing](/unit-tests) for some basic assumptions and configuration available for all Brut unit tests.
-
-Handler tests should be straightforward: you create your handler, call `handle!`
-(remember, `handle!` is the public API, and will call your hooks, which you want in
- a test), then examine the result returned and any ancillary behavior, such as
-updated database records.
-
-Some matchers are available to make assertions about `handle!`'s return value:
-
-* `have_redirected_to` will check that the handler redirected to a give URI. See `Brut::SpecSupport::Matchers::HaveRedirectedTo`.
-* `have_generated` will check that the handler generated a specific page or component's HTML. See `<D-f>Brut::SpecSupport::Matchers::HaveGenerated`.
-* `have_returned_http_status` will check that the handler returned an HTTP status. See `Brut::SpecSupport::Matchers::HaveReturnedHttpStatus`.
-* `have_constraint_violation` will check if a form had a particular constraint violation set on it. See `Brut::SpecSupport::Matchers::HaveConstraintViolation`.
-
-## Recommended Practices
-
-### You Don't Always Need Resourceful or RESTful Routes
-
-For any code where the browser is performing a submission, use either `form` or
-`action` to declare your route. These will both use an HTTP `POST` to your server and handler.  In the example above, we had a `POST` to `/delete_widget/:widget_id`, and not, say, a `DELETE` to it.
-
-The main reason is that a browser can only submit to a server using `GET` or `POST`, so there's little value in "tunneling" another verb of POST. It doesn't really matter.  And, even though you may use Ajax to submit such data, having it degrade to normal browser-based HTTP is a good practice.
-
-For API-like calls where a browser will never directly interact with the route, and
-it would only be via a server-to-server call, RESTful routes makes sense. But they
-don't need to be the default.
-
-### Avoid Business Logic in Handlers
-
-
-Since handlers bridge the gap between HTTP and your app, their API is naturally simplistic and String-based.  The handler should defer to business logic (which can be done by either passing the form object directly, or extracting its data and passing that).  Based on the response, the handler will then decide what HTTP response is approriate.
-
-This means that your handlers will be relatively simple and their tests will as well.  It does mean that their tests may require the use of mocks or stubs, but that's fine.  Mocks and stubs exist for a reason.
-
-
-## Technical Notes
-
-> [!IMPORTANT]
-> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
-> internals, the source code is always more correct.
-
-_Last Updated May 5, 2025_
-
-None at this time.
-