brut 0.0.21 → 0.0.23

data/brutrb.com/getting-started.md

@@ -0,0 +1,66 @@
+# Getting Started
+
+To make a new app with Brut, you'll need to clone a template app, initialize it, then set up your dev environment.
+
+## Clone the App Template
+
+To get started, clone the Brut app template:
+
+```
+> git clone https://github.com/thirdtank/brut-app-template your-app-name
+```
+
+## Init Your App
+
+The template includes `init`, which will ask you a few questions to get everything set up.
+
+```
+> cd your-app-name
+> ./init
+```
+
+You'll need to provide four pieces of info:
+
+* Your app's name, suitable has a hostname or identifier
+* A prefix for your app's externalizable ids
+* A prefix for your app's custom elements
+* An organization name, needed for deployment
+
+::: tip
+Choose your app's name wisely, however everything else can be easily changed later, so don't stress!
+:::
+
+## Set Up Your Dev Environment
+
+Brut includes a dev environment based on Docker.
+
+1. [Install Docker](https://docs.docker.com/get-started/get-docker/)
+2. Build Your images
+
+   ```
+   > dx/build
+   ```
+3. Start up the environment
+
+   ```
+   > dx/start
+   ```
+4. Install gems and modules for your app. In another terminal:
+
+   ```
+   > dx/exec bin/setup
+   ```
+
+Now, you're ready to go
+
+## Run the App
+
+```
+> dx/exec bin/dev
+```
+
+You can now visit your app at `localhost:6502`
+
+## 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.

data/brutrb.com/handlers.md

@@ -0,0 +1,153 @@
+# 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`.
+
+### Declaring Routes
+
+`form` and `action` are intended to be used when an HTTP form is being submitted. The latter—`action`—is for when your form has no user-editable elements.  This is akin to Rails' `button_to` helper, where the contents of the URL contains everything needed to service the request.
+
+`path` is for arbitrary HTTP requests and methods, so to create a webhook that responds to a PUT, you'd use:
+
+```ruby
+# inside app/src/app.rb
+path "/webhooks/stripe", method: :put
+```
+
+In all cases, the class to receive and process these requests is a handler, whose name is conventional based on the route. For example, the webhook above would be handled by `Webhooks::StripeHandler`.
+
+### Implementing Handlers
+
+A handler works like a page, in that its initializer can receive any injectible arguments.  These would include a form object, dynamic elements of the route, or anything else available from the request.  See [Keyword Injection](/keyword-injection) for the details, noting that your handler can be inejcted with custom objects you've configured in a route hook.
+
+After the handler is created, it's `before_handle` method is called. If it returns `nil`, `handle` is called to trigger whatever logic the handler needs to trigger.
+
+Both `handle` and `before_handle` can return a variety of objects that determine what will happen:
+
+* An instance of a page or component means that page or component is rendered.  This is not a redirect to the page, so it is more like Rails' `render :new` and **not** a `redirect_to(new_widgets_path)`.
+* A `Brut::FrontEnd::HttpStatus` which sends that status and an empty body back.  This object can be created from
+an integer using the `http_status` helper, available to all handlers.
+* A `URI`, which will cause a redirect to that URI.  You can create the `URI` yourself, or use the helper
+`redirect_to`, which accepts a string.
+* A two-element array with a page or component as the first element and an `Brut::FrontEnd::HttpStatus` as the
+second.  This will render that page  or component's HTML, but use the given status instead of 200.  This can be useful for Ajax requests where you want to use HTML your respond format, but also, say, a 422 status to indicate a constraint violation has occured.
+* A `Brut::FrontEnd::Download`, which encapsulates a file to be downloaded.
+* A `Brut::FrontEnd::GenericResponse`, which wraps any Rack response with a defined type.
+
+`before_handle` may also return `nil` to indicate that `handle` should be called. `handle` may not return `nil`.
+
+Supposing our `LoginForm` and `LoginHandler` wanted to use a common pattern of re-rendering `LoginPage` on constraint violations, and forwarding on to, say, a `DashboardPage`.  Your handler might look like so:
+
+```ruby {23-27}
+# app/src/front_end/handlers/login_handler.rb
+class LoginHandler < AppHandler
+  def initialize(form:, session:) # We'll discuss the session later
+    @form    = form
+    @session = session
+  end
+
+  def handle
+    if !@form.constraint_violations?
+      authorized_user = AuthorizedUser.login(
+        email: form.email,
+        password: form.password
+      )
+      if authorized_user.nil?
+        @form.server_side_constraint_violation(
+          input_name: :email,
+          key: :login_not_found
+        )
+      else
+        session.authorized_user = authorized_user
+      end
+    end
+    if @form.constraint_violations?
+      LoginPage.new(form: @form)
+    else
+      redirect_to(DashboardPage.routing)
+    end
+  end
+end
+```
+
+> [!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.
+
+## Testing
+
+Testing handlers requires calling their *public API*, which is `handle!`.  This is not the method you implement (which is the non-bang `handle`).  The reason is that `handle!` manages the logic around calling `before_handle`, which allows your tests to always call `handle!` and know they are testing how the  handler would be used in produciton.
+
+Each handler spec includes `Brut::SpecSupport::HandlerSupport`, which allows you to create production-like flash, clock, and session objects. To assert the results of calling `handle!`, there are several RSpec matchers you can use to make your tests easier to write.
+
+* `have_redirected_to` will check that the handler redirected to a give URI.
+* `have_rendered` will check that the handler rendered a specific page
+* `have_returned_http_status` will check that the handler returned an HTTP status
+* `have_constraint_violation` will check if a form had a particular constraint violation set on it
+
+```ruby
+require "spec_helper"
+
+RSpec.describe LoginPage do
+  describe "#handle!" do
+    context "when login is not valid" do
+      it "re-renders LoginPage" do
+        form = LoginForm.new(params: {
+          email: "nonexistent@example.com",
+          password: "not a password",
+        })
+        result = described_class.new(
+          form:,
+          session: empty_session # empty_session provided by HandlerSupport
+        )
+        expect(result).to have_rendered(LoginPage)
+        expect(form).to have_constraint_violation(:email, key: :login_not_found)
+      end
+    end
+    context "when login is valid" do
+      it "forward to the DashboardPage" do
+        user = create(:user, # Assume this is set up via FactoryBot
+                      email: "pat@example.com",
+                      password: "1q2w3e4r5t6y7u8i9o")
+
+        form = LoginForm.new(params: {
+          email: "pat@example.com",
+          password: "1q2w3e4r5t6y7u8i9o",
+        })
+        session = empty_session
+        result = described_class.new(
+          form:,
+          session:,
+        )
+        expect(result).to have_redirected_to(DashboardPage.routing)
+        expect(session.authorized_user).not_to eq(nil)
+        # Session will be explained later
+      end
+    end
+  end
+end
+```
+
+## Recommended Practices
+
+You should avoid having business logic in your 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.
+

data/brutrb.com/hooks.md

@@ -0,0 +1,178 @@
+# Route Hooks
+
+Route hooks are similar to [Middleware](/middleware), but have a richer API and aren't as low-level. Route
+hooks can happen before a page or handler is called, or after.
+
+## Overview
+
+We've seen examples thusfar of using a route hook to place the authenticated user or account into the
+request context for later injection into pages or handlers. Brut uses route hooks to locale detection and
+for content security policies.
+
+At its core, a before hook is a class that extends `Brut::FrontEnd::RouteHook` and implements `before`
+and an after hook implements `after`.  Both `before` and `after` can be [injected](/keyword-injection) with request-time information.
+
+To register a hook, you'd call `before` or `after` in your `App`:
+
+```ruby
+class App < Brut::Framework::App
+
+  # ...
+
+  before :RequireAuthBeforeHook
+
+  # ...
+
+end
+```
+
+The value can be a string or symbol, but should not be the class itself, as this can mess with load order.
+
+The code for `RequireAuthBeforeHook` we saw before was marked with a red warning that it wasn't production ready.  Let's
+see what a more realistic hook would look like.
+
+The purpose of `RequireAuthBeforeHook` is to detect if a user is logged in.  If they are, all is well. If they are not,
+we want to redirect them to a login page unless the page they've requested is allowed for logged-out users.
+
+Let's suppose that the home page (`/`) and any page starting with `/auth/` are allowed for logged-out users (`/auth/` being pages related to logging in).
+
+Brut also reserves some routes for its own, and we want those to be allowed to logged-out users as well. Brut sets
+`"brut.owned_path"` in the Rack environment if the requested URL is one it is managing.
+
+`before` will need access to the request context, session, Rack request, and Rack environment:
+
+
+```ruby
+# app/src/front_end/route_hooks/require_auth_before_hook.rb
+class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:,request:,env:)
+     # ...
+  end
+end
+```
+
+We'll use the Rack request's `path_info` to check for allowed routes, and the aforementioned `env["brut.owned_path"]` to
+check for a Brut-owned path:
+
+```ruby {4-6}
+# app/src/front_end/route_hooks/require_auth_before_hook.rb
+class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:,request:,env:)
+    is_home_page       = request.path_info.match(/^\/?$/)
+    is_auth_route      = request.path_info.match?(/^\/auth\//)
+    is_brut_owned_path = env["brut.owned_path"]
+
+    # ...
+
+  end
+end
+```
+
+Now, we can use this local variables to figure out if the route requires a user to be logged-in:
+
+```ruby {8-10}
+# app/src/front_end/route_hooks/require_auth_before_hook.rb
+class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:,request:,env:)
+    is_home_page       = request.path_info.match(/^\/?$/)
+    is_auth_route      = request.path_info.match?(/^\/auth\//)
+    is_brut_owned_path = env["brut.owned_path"]
+
+    requires_login = !is_home_page  &&
+                     !is_auth_route && 
+                     !is_brut_owned_path
+
+    # ...
+
+  end
+end
+```
+
+Now, we'll check if someone *is* logged in. If they are, we'll set the `authenticated_account` in the request context.
+
+```ruby {12-15}
+# app/src/front_end/route_hooks/require_auth_before_hook.rb
+class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:,request:,env:)
+    is_home_page       = request.path_info.match(/^\/?$/)
+    is_auth_route      = request.path_info.match?(/^\/auth\//)
+    is_brut_owned_path = env["brut.owned_path"]
+
+    requires_login = !is_home_page  &&
+                     !is_auth_route && 
+                     !is_brut_owned_path
+
+    if session.logged_in?
+      request_context[:authenticated_account] = session.authenticated_account
+      requires_login = false
+    end
+
+    # ...
+
+  end
+end
+```
+
+Now, we can test if the visitor needs to log in before proceeding.  The return value of `before` controls
+what will happen, similar to how handlers work.
+
+
+* `URI` - the browser will be redirected to this URI. This can be done by using the `redirect_to` helper.
+* `Brut::FrontEnd::HttpStatus` - the request will be terminated with this status. This can be done using the `http_status` helper.
+* `false` - the request is terminated with a 500
+* `true` or `nil` - the request will continue to the next hook or to the route handler. You are encouraged to use the `continue` helper to more clearly indicate that the request will proceed.
+
+In our case, if the visitor requires a login, we'll `redirect_to` the `LoginPage`.  Otherwise, we'll
+`continue`.
+
+```ruby {17-21}
+# app/src/front_end/route_hooks/require_auth_before_hook.rb
+class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
+  def before(request_context:,session:,request:,env:)
+    is_home_page       = request.path_info.match(/^\/?$/)
+    is_auth_route      = request.path_info.match?(/^\/auth\//)
+    is_brut_owned_path = env["brut.owned_path"]
+
+    requires_login = !is_home_page  &&
+                     !is_auth_route && 
+                     !is_brut_owned_path
+
+    if session.logged_in?
+      request_context[:authenticated_account] = session.authenticated_account
+      requires_login = false
+    end
+
+    if requires_login
+      redirect_to(Auth::LoginPage)
+    else
+      continue
+    end
+
+  end
+end
+```
+
+## Testing
+
+Route hooks are normal classes, you could test them as you would a handler or other class.  This may be
+advisable for complex hooks, however it may be more realistic to test their behavior through end-to-end
+tests as this will ensure they are configured correctly in the context of the app.
+
+## Recommended Practices
+
+Route hooks and [page hooks](/pages#hooks) serve similar purposes, so logic in one can be placed in other
+other at your discretion.  We recommend you use route hooks for cross-cutting issues across the entire
+app, such as login checks or for adding context to a request.
+
+For page- or use-case-specific behavior, it may be better to put the logic in a page hook.
+
+## 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 June 12, 2025_
+
+Route hooks and Middlewares do not share implementations, however they are similar in concept.  These
+concepts may be unified in the future.

data/brutrb.com/i18n.md

@@ -0,0 +1,188 @@
+# Internationaliztion and Localization
+
+Brut uses Ruby's i18n gem to provide support for localization and internationalization.
+
+## Overview
+
+`Brut::I18n::BaseMethods` provides the core implementation of Brut's i18n support, and it largely wraps the `t`
+and `l` methods of the i18n gem.
+
+
+Consider this:
+
+```ruby
+t("my.key", foo: "Bar")
+```
+
+This will locate the string with the key `my.key` and return it, replacing `%{foo}` with `"Bar"`, if `%{foo}` is
+present in the string.
+
+The keys are located in files in `app/config/i18n`.  The directories there correspond to the locales your app
+supports, e.g .`app/config/i18n/en` would hold translations for English.
+
+The translation files themselves are 🎉**NOT YAML**🎊.  They are Ruby files.  By default, there are two files: `app/config/i18n/en/1_defaults.rb` and `app/config/i18n/en/2_app.rb` (noting that `/en/` is for English and other langauges are obviously supported).
+
+`1_defaults.rb` provides values for keys Brut may require or use, such as for front-end constraint violations.
+`2_app.rb` provides your app's keys. If this file contains the same keys as `1_defaults.rb`, your file's values
+will be used.
+
+The file is a giant Hash, so the key above might look like so:
+
+```ruby
+{
+  my: {
+    key: "Hello there %{foo}",
+  },
+}
+```
+
+### Enhancements
+
+Brut's `t` tries to balance predictability with flexibility. It will always try to tell you what keys it was
+checking when it cannot find a translation or what interpolated values were missing.
+
+#### Basic Usage
+
+Often, keys contain dynamic elements.  Rather that creating a key like `widget.status.#{widget.status}`, you can
+pass an array in and it'll be joined for you:
+
+```ruby
+t([ :widget, :status, widget.status ]) #=> widget.status.active e.g.
+```
+
+`t` can also take a block that will be evaluated and substituted into the `block` interpolation value:
+
+```ruby
+{
+  supportlink: "To contact support %{block}',
+}
+
+t(:supportlink) do
+  "<a href='https://support.example.com'>Contact Support</a>"
+end
+```
+
+See below for how this affects HTML generation.
+
+#### Page- and Component-specific Values
+
+If you call `t` inside `page_template`, or inside `view_template` of a [page private
+component](/components#page-private-components), you can simplify the key specification.
+
+```ruby
+t(:nevermind)
+```
+
+If this is used on, say, `NewWidgetPage`, Brut will try to locate the key `pages.NewWidgetPage.nevermind`.  This works on page private components as well.
+
+Inside a normal component, it works simliarly.  Suppose `FlashComponent` had this:
+
+```ruby
+if !flash
+  t(:default_message)
+end
+```
+
+This would locate `components.FlashComponent.default_message`.
+
+This saves some typing, but it can also assist refactoring. If you rename a page or component, calls to `t` will blow up, reminding you to move the translations inside `2_app.rb`.
+
+### HTML Escaping
+
+`Brut::I18n::BaseMethods` cannot be used directly.  One of three submodules must be used: `ForHTML`, `ForCLI`, or
+`ForBackend`.  This is to allow the `ForHTML` module to properly escape HTML.
+
+When a translation accepts a block, that block could be HTML and you would want that HTML be included in the
+page, un-escaped.  Brut achieves this by first using Phlex's `capture` method, then marking it as HTML safe using
+`safe`.
+
+Thus, as long as you aren't introducing injections in your translations file or source code, it is safe to do the following:
+
+```ruby
+def view_template
+  div do
+    raw(
+      t(page: :contact_support) do
+        a(href: "https://support.example.com") do
+          t(page: :support_link_name)
+        end
+      end
+    )
+  end
+end
+```
+
+The result of `t` is safe HTML, so you must use `raw` to avoid escaping it.
+
+In a CLI or back-end context, HTML escaping is not relevant and can actually create problems, so `ForCLI` and
+`ForBackend` no-op `safe` and `capture`.
+
+When using `ForHTML`, all interpolated values are HTML-escaped.  `ForCLI` and `ForBackend` are not.
+
+### Localizing Dates and Times
+
+`l` can be called and this defers to the Ruby I18n library.
+
+Date and time formats can be configured in the translation files.  `l` does not accept a full key for the format.
+It is created dynamically by the library, so you must take care in which one you use.  If you pass a `Date` into
+`l`, `date.formats.«format»` is used. If you pass a `Time` in, `time.formats.«format»` is used.
+
+The values of the formats are strings suitable for
+[`strftime`](https://www.man7.org/linux/man-pages/man3/strftime.3.html).  The site [strif.me](https://www.strfti.me/) can be helpful in conjuring the right value.
+
+Brut includes translations for various formats that you can inspect in `app/config/i18n/«lang»/1_defaults.rb`.
+
+### Displaying Dates and Times in HTML
+
+While `l` will return a string you can use anywhere, you are most likely going to show dates and times in HTML.
+For that, you should use a `<time>` element.  Brut provides `Brut::FrontEnd::Components::TimeTag` (remember that if you `include Brut::FrontEnd::Components`, it's a Phlex *kit* and thus you can use `TimeTag(...)` directly) to do this. It contains additional behavior to make friendly dates and times.
+
+* You can give it a `timestamp:` or `date:` to control which formatting style is used.
+* `skip_year_if_same`, if true, will omit the year from any format if the current year is the same as the year being displayed. This is true by default
+* `skip_dow_if_not_this_week`, if true, will omit the day of week if the date or time is more than 7 days in the past.  This is true by default.
+
+The way `skip_year_if_same` and `skip_dow_if_not_this_week` work is to append `no_year` and/or `no_dow` to
+existing format strings which are assumed to omit this elements.
+
+If you wish to create your own formats, you can add them as well.
+
+### Constraint Violations and Field Names
+
+The interpolated value `{field}` is special. It is assumed to be the name of a field in a constraint violation
+message, e.g. `"%{field} is required"`.  It is the only interpolated value that can be omitted without causing an
+error.
+
+If included, it will work as normal:
+
+```ruby
+t("cv.be.required", field: "Email") # => Email is required
+```
+
+If omitted, the value of `"cv.this_field"` is used. This is included in `1_default.rb`, but if it's
+missing, Brut will raise.  Assuming the value is `"This field"`:
+
+```ruby
+t("cv.be.required") # => This field is required
+```
+
+## Testing
+
+In tests, you can call `t` and `l` to examine values as needed.
+
+> [!WARNING]
+> This aspect of Brut could use improvement. It likely will not work for non-English locales.
+
+## Recommended Practices
+
+Could use help here - The implementation feels like a bare minium
+
+
+## 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 7, 2025_
+
+TBD

data/brutrb.com/images/Makefile

@@ -0,0 +1,10 @@
+DOT_FILES = *.dot
+PNG_FILES = $(patsubst %.dot,%.png,$(DOT_FILES))
+
+%.png : %.dot
+	dot -Gdpi=300 -Tpng $< -o$@
+
+%.svg : %.dot
+	dot -Gdpi=300 -Tsvg $< -o$@
+
+all: $(PNG_FILES)

data/brutrb.com/images/dev-env-overview.dot

@@ -0,0 +1,54 @@
+digraph G {
+  rankdir="LR"
+  Node[fontname=Baskerville]
+  subgraph cluster_docker {
+    label="Docker Container"
+    labeljust=left
+    fontname=Avenir
+    Ruby
+    NodeJS
+    OS
+    Filesystem
+    BrutApp
+  }
+
+  subgraph cluster_host {
+    label="Your Computer"
+    labeljust=left
+    fontname=Avenir
+    ProjectFiles
+    Editor
+    VersionControl
+    Browser
+  } 
+  
+  subgraph cluster_postgres {
+      label="Postgres\l«Docker Container»"
+      labeljust=left
+      fontname=Avenir
+      Postgres
+  }
+  Filesystem[shape=tab label="File system"]
+  ProjectFiles[shape=tab label="Project Files"]
+  OS[shape=box]
+  NodeJS[shape=component]
+  Ruby[shape=component]
+  Editor[shape=Msquare]
+  VersionControl[shape=Msquare label="Version\nControl"]
+  Postgres[shape=cylinder]
+  BrutApp[shape=box3d]
+  Browser[shape="Msquare" label="Web\nBrowser"]
+  
+  BrutApp -> Ruby
+  BrutApp -> NodeJS
+  BrutApp -> Filesystem
+  BrutApp -> Postgres
+  
+  Filesystem -> ProjectFiles[ dir=both label="synced"]
+  Editor -> ProjectFiles
+  Ruby -> Filesystem
+  NodeJS -> Filesystem
+  OS -> Filesystem
+  VersionControl -> ProjectFiles
+  Browser -> BrutApp
+}

data/brutrb.com/images/dev-env-protocol.dot

@@ -0,0 +1,37 @@
+digraph G {
+
+  rankdir="LR"
+  nodesep=0.55
+  compound=true
+  
+  node[shape=box fontname=avenir]
+
+  Shutdown[label=<
+    <FONT face="avenir">Shutdown</FONT>
+    <br/>
+    <FONT face="Courier New">dx/stop</FONT>
+  >]
+  Build[label=<
+    <FONT face="avenir">Build</FONT>
+    <br/>
+    <FONT face="Courier New">dx/build</FONT>
+  >]
+  Start[label=<
+    <FONT face="avenir">Start</FONT>
+    <br/>
+    <FONT face="Courier New">dx/start</FONT>
+  >]
+  Exec[label=<
+    <FONT face="avenir">Execute</FONT>
+    <br/>
+    <FONT face="Courier New">dx/exec</FONT>
+  >]
+  DevCommands[label=<
+    <FONT face="avenir">Workspace</FONT>
+    <br/>
+    <FONT face="Courier New">bin/\*</FONT>
+  >]
+  Build -> Start -> Exec -> Shutdown
+  Exec -> DevCommands[style=dotted dir=none]
+  { rank=same; Exec; DevCommands }
+}