brut 0.17.0 → 0.18.0

data/brutrb.com/package.json

@@ -1,11 +0,0 @@
-{
-  "devDependencies": {
-    "vitepress": "^1.6.3",
-    "vue": "^3.5.13"
-  },
-  "scripts": {
-    "docs:dev": "vitepress dev --port 8086 --host=0.0.0.0",
-    "docs:build": "vitepress build",
-    "docs:preview": "vitepress preview --port 8086 --host=0.0.0.0"
-  }
-}

data/brutrb.com/pages.md

@@ -1,290 +0,0 @@
-# Pages
-
-A core abstraction of Brut is the core concept of the web: the web page.
-
-## Overview
-
-To create a web page, you'll need:
-
-* A [Route](/routes) using `page`.
-* A class in `app/src/front_end/pages/` that extends `Brut::FrontEnd::Page`, named [conventionally](/routes#class-naming-conventions) (though in reality, your page willextend `AppPage` in `app/src/front_end/pages/app_page.rb`, which extends `Brut::FrontEnd::Page`).
-* [Optional, but recommended] A test in `specs/front_end/pages`.
-
-You can create all this with `bin/scaffold`, which accepts the route you want:
-
-```shell
-> bin/scaffold page /new_widgets
-# => app/src/front_end/pages/new_widgets_page.rb
-# => specs/front_end/pages/new_widgets_page.spec.rb
-# => add `page "/new_widgets"` to app/src/app.rb
-```
-
-or
-
-```shell
-> bin/scaffold page /widget/:id
-# => app/src/front_end/pages/widget_by_id_page.rb
-# => specs/front_end/pages/widget_by_id_page.spec.rb
-# => add `page "/widget/:id"` to app/src/app.rb
-```
-
-You can also perform these steps manually.
-
-> [!WARNING]
-> Adding a `page` route without the corresponding class may not always
-> work, since Brut may try to load the class.  Brut does its best
-> to avoid problems, but you should create your route and classes
-> all at once
-
-> [!IMPORTANT]
-> Brut cannot currently reload new routes, so you must
-> restart your dev server when you modify or add routes.
-
-### Creating a Page
-
-Pages need a `page_template` method that contains calls to Phlex, which will produce
-the page's HTML.
-
-If you have not used Phlex before, it's relatively straightfoward.  For each HTML
-tag that exists, Phlex provides a method. So, for `<div>`, Phlex provides `div`.
-
-Each method accepts parameters which are converted into attributes.  Methods can
-also accept blocks that can be used to add more HTML by calling more of Phlex's API.
-
-```ruby
-class DashboardPage < AppPage
-  def page_template
-    header do
-      h1 { "Welcome to My App!" }
-      time { Date.today }
-    end
-    main do
-      p(class: "body-text") do
-        "This is my awesome app! I hope you stay awhile!"
-      end
-    end
-  end
-end
-```
-
-By default, this page will be rendered inside `DefaultLayout`, located in
-`app/src/front_end/layouts/default_layout.rb` and discussed in [the layouts
-module](/layouts).  The HTML this page will generate, that would then be inserted
-into the layout's HTML, looks like so:
-
-```html
-<header>
-  <h1>Welcome to My App!</h1>
-  <time>2025-07-05</time>
-</header>
-<main>
-  <p class="body-text">
-    This is my awesome app! I hope you stay awhile!"
-  </p>
-</main>
-```
-
-### Accessing Data in a Page
-
-Building static pages is fine, but not really why we use web app libraries.  Your
-page is a normal class, so you can create instance variables and methods, which can
-do whatever you need.
-
-That being said, the initializer is called by Brut and can be given special
-arguments.  For example, if your route has as placeholder, e.g. `/widgets/:id`, then
-your initializer will be given the value of `:id` if its initializer has a keyword
-argument named `id:`:
-
-```ruby
-def initialize(id:)
-end
-```
-
-Query string parameters are also avaiable this way, but your page can access a wide
-variety of request-level information simply by declaring a keyword argument to its
-initializer.
-
-This mechanism is called [keyword injection](/keyword-injection) and is available to many class you create, including pages.
-
-Here is a list of what is available:
-
-| Keyword Argument | Type | Description |
-|-------|------|-------------|
-`session:` | `Brut::FrontEnd::Session` (or your app's subclass) | The current session, even if it's empty. See [Flash and Session](/flash-and-session)|
-`flash:` | `Brut::FrontEnd::Flash` (or your app's subclass) | The current flash, even if it's empty. See [Flash and Session](/flash-and-session) |
-`xhr:` | `true` or `false` | true if this was an Ajax request|
-`csrf_token:` | `String`| The current CSRF token. |
-`clock:` | `Clock` | Used when you need to access the current date and time, potentially accounting for time zones.   See [Space/Time Continuum](/space-time-continuum)|
-`http_*` | `String` or `nil` | Any parameter that starts with `http_` is assumed to be for an HTTP header. For example, `http_accept_language` would be given the value for the "Accept-Language" header. See [HTTP Headers](/keyword-injection#http-headers) |
-`rack_request_*` | `String` or `nil` | Any parameter that starts with `rack_request_` is assumed to be for a value from the `Rack::Request`. For example, `rack_request_id` would provide the `ip` value from `Rack::Request` |
-`env:` | `Hash` | The Rack env.  You are discouraged from using this directly in your pages, but if you need it, it's available. |
-Placeholders | `String` | Any placeholder value from the route definition |
-Any query string paramter | `String` | the value given is always a string.
-Any object placed into the request context | `Object` | Values you place into the request context. See below for an example.
-
-Thus, if `Admin::WidgetsByIdPage` responds to the `detail_level` query string parameter, needs access to the current time, wants to
-check a value from the session, and responded to the completely made-up header "X-Be-Nice", the initializer would look like so:
-
-```ruby
-def initialize(id:,
-               session:,
-               clock:,
-               http_x_be_nice:,
-               detail_level: nil)
-```
-
-> [!CAUTION]
-> Keyword arguments for query string parameters **must** have default values 
-> or Brut will be unable to instantiate your page class when they are omitted.
-> We recommended that **no other keywords arguments have defaults** to ensure your
-> pages aren't created with `nil` values.
-
-> [!NOTE]
-> Omitting a default for an HTTP header is OK, but you should know what the behavior is. See [the HTTP Headers
-> section](/keyword-injection#http-headers) for details.
-
-
-### Page Hooks
-
-Occasionally, you want to prevent a page from rendering after the visitor has been routed to it.  A common reason for this could be a lack of authorization by that visitor to view the page.
-
-`before_generate` achieves this. It's called after construction, so has access to
-any injected values, and its return value tells Brut what should happen:
-
-* `URI` - the visitor will be redirected to the given URI.  Instead of creating a `URI`, you may use the method `redirect_to`, which
-accepts a page and its parameters.
-* `Brut::FrontEnd::HttpStatus` - the page will not be rendered and this status will be returned. You may use `http_status` to create
-an `HttpStatus` from a number.
-* `Brut::FrontEnd::GenericResponse` - a typed wrapper around the standard Rack response.
-* Anything else - page rendering will proceed as usual.
-
-## Testing
-
-See [Unit Testing](/unit-tests) for some basic assumptions and configuration available for all Brut unit tests.
-
-Although pages are Plain Old Ruby Objects, you likely want to test the HTML they
-generate.  Brut provides convenience methods to do this based on Nokogiri.
-
-### Generating a Response
-
-* If your page has no before hook, or you aren't testing that, call `generate_and_parse(page_instance)`.  This returns a `Brut::SpecSupport::EnhancedNode`, which is a delegate to Nokogiri's `Nokogiri::XML::Node` (see below for why this exists)
-* If you want to assert behavior of the before hook, call `generate_result`, which
-will return whatever the page's internal `handle!` method called.
-will use one of these matchers on the result:
-
-### Asserting Results
-
-When using `generate_and_parse`, you have access to all of Nokogiri, however
-`Brut::SpecSupport::EnhancedNode` provides two methods to simplify your test:
-
-```ruby
-it "should work" do
-  result = generate_and_parse(described_class.new)
-
-  expect(result.e!("h1").text).to include("Welcome")
-  expect(result.e("h2")).to       eq(nil)
-end
-```
-
-* `e!` returns the node matching the given CSS selector, failing the test if there
-is not exactly one matching node.
-* `e` (no bang) returns the node matching the given CSS selector, or `nil` if none matched.  If there is more than one match, the test fails.
-
-When using `generate_result`, you will want to use one of two special purpose
-matchers:
-
-```ruby
-it "redirects" do
-  result = generate_result(described_class.new)
-  expect(result).to have_redirected_to(AuthPage)
-end
-
-it "404's" do
-  result = generate_result(described_class.new)
-  expect(result).to have_returned_http_status(404)
-end
-```
-
-- `have_redirected_to` to check that a redirect happened to the URI you set (see `Brut::SpecSupport::Matchers::HaveRedirectedTo`)
-- `have_returned_http_status` to check that a given HTTP response was returned (see `Brut::SpecSupport::Matchers::HaveReturnedHttpStatus`)
-
-Beyond this, you can use Nokogiri as usual to navigate the DOM that's generated and
-make assertions.  A few additional matchers to help are:
-
-- `be_routing_for` - expect a URI to be a routing for a certain page or
-page/parameter combination. See `Brut::SpecSupport::Matchers::BeRoutingFor`.
-- `have_html_attribute` - check that a node has an attribute or an attribute with a
-specific value. See `Brut::SpecSupport::Matchers::HaveHTMLAttribute`.
-- `have_i18n_string` - check that a node's text has a string from your [I18n](/i18n)
-configuration.  See `Brut::SpecSupport::Matchers::HaveI18nString`.
-
-## Recommended Practices
-
-### Instance variables (ivars) are fine.
-
-Since `page_template` is a method of your class, it has access to your instance variables (ivars).  Feel free to
-use them directly.  Only create `attr_reader` implementations if a subclass should be expected to override
-something or you want something lazily evaluated.  Make them private. Your page's API is just the method `page_template`.
-
-### Don't set ivars in `before_generate`
-
-It's Ruby and you can do whatever you want, but your page class will be easier to understand and test if you set up necessary state in
-your initializer.  Memoization is fine, but don't have your `before_generate` set up additional state if you can avoid it.  As we'll see
-below, you won't need to use `before_generate` as a failsafe check on authorization.
-
-### Leverage Keyword Injection
-
-The list of available data for injection above will always be available to your page, with the exception of query string parameters.  The real power comes when you learn how to [inject your own data](/keyword-injection#injecting-custom-data) into the request context.
-
-A great example of this is in the [recipe for keywords and auth](/recipes/authentication), which results in a much simpler and less error-prone way to prevent unauthorized access to pages when compared to how you might do it in Rails.
-
-### In Tests, It's Fine to Locate Elements Via CSS Selectors
-
-Your page's job is to produce HTML.  To check if it's doing that, it makes sense to manipulate that HTML using standard, battle-tested
-techniques like CSS selectors.  This creates consonance between your in-browser debugging and your test suite.
-
-It also makes it much more obvious what's wrong if something is not where you expect it to be.
-
-### That Said, Avoid Test-Specific Attributes or Classes
-
-When you have a lot of `<div>` elements, it can be tempting to use attributes like `data-testid` on the elements you want to find in
-your tests.  You can often avoid this if you use semantic markup and proper ARIA roles.  For example, a Flash message is likely
-something you'd put in a `role="status"` or `role="alert"`, so you don't need `data-flash` or `class="flash"` in order to find it in a
-test.
-
-Custom Elements can also be helpful here, as that may be how you choose to manage your client-side behavior.
-
-## 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 4, 2025_
-
-### Page Internal API
-
-A Page's core API is the method `handle!`, which can return an HTML-safe string, `URI`, or Rack response.
-Developers should avoid overriding this method, as it also handles the logic related to calling `before_generate`
-as well as the logic required to make layouts work.
-
-This is why we recommend using `Brut::SpecSupport::ComponentSupport#generate_and_parse` or `Brut::SpecSupport::ComponentSupport#generate_result` in a tests.  *They* call `handle!`, thus ensuring your `before_generate` method will be called and that your page class will behave in a test the way it would in production.
-
-### Layouts
-
-Pages do not have to have a layout. You can override Phlex's `view_template` and produce HTML that will not be
-wrapped in any Layout.  It may be a better idea to create a `BlankLayout` class to avoid this, but it's up to
-you.
-
-### Helpers in Templates
-
-`Brut::FrontEnd::Page` is a subclass of `Brut::FrontEnd::Component`, so all your pages will have access to the helpers included there.  This is how, for example, `t` can be called to perform translations.
-
-Note that Brut does *not* include `Brut::FrontEnd::Components` (pluralized).  You
-can include that in `AppPage` to access Brut's builtin components as a Phlex kit.
-
-### So You Don't Like Phlex?
-
-Brut did initially use ERB, but the initial Brut-powered apps ended up having an all-too-common mess of HTML, Ruby, and angle brackets.  It really sucked.  Phlex seems pretty solid and is a very lightweight abstraction over HTML. It keeps everything in Ruby, but still maintains consonance to what you see in your browser.
-
-Support for ERB, Slim, or HAML, is not planned ever.

data/brutrb.com/recipes/alternate-layouts.md

@@ -1,32 +0,0 @@
-# Alternate Layouts
-
-To create an alternate layout, your page can override `layout` to return a string.
-That string will be camel-cased and preped to `Layout` to form a class that is
-expected to exist and provide the layout. That class must extend
-`Brut::FrontEnd::Layout`.
-
-```ruby
-class MyOtherPage < AppPage
-  def layout = "other_design"
-
-  # ...
-
-end
-
-class OtherDesignLayout < Brut::FrontEnd::Layout
-  def view_template
-    doctype
-    html do
-      head do
-        link(rel: "preload", as: "style", href: asset_path("/css/other-styles.css"))
-        link(rel: "stylesheet",           href: asset_path("/css/other-styles.css"))
-        script(defer: true, src: asset_path("/js/app.js"))
-      end
-      body do
-        yield
-      end
-    end
-  end
-end
-```
-

data/brutrb.com/recipes/authentication.md

@@ -1,336 +0,0 @@
-# Authentication Example
-
-It's impossible to account for all types of authentication you may want to use, but
-this recipe will demonstrate all the moving parts:
-
-* How to require authentication for some pages
-* How to design pages that require authentication
-* How to manage the signed-in user in code
-
-## Feature
-
-* Visitors can log in with an email, that is assumed to have been inserted previously (no passwords or signup, just to simplify the recipe)
-* Visitors can access the home page without logging in
-* Visitors cannot access the dashboard page without logging in
-
-## Recipe
-
-### Set up Database and Seed Data
-
-First, we'll make a database table called `accounts` that will have an email field
-and a password hash field.
-
-```
-bin/db new-migration accounts
-```
-
-This will create a file in `app/src/back_end/data_models/migrations`.  We'll edit it
-to create a new table called `accounts`:
-
-```ruby
-Sequel.migration do
-  up do
-    create_table :accounts, comment: "People or systems who can access this system", external_id: true do
-      column :email, :text, unique: true
-      column :deactivated_at, :timestamptz, null: true
-    end
-  end
-end
-```
-
-We'll also create `app/src/back_end/data_models/db/account.rb`:
-
-```ruby
-class DB::Account < AppDataModel
-  has_external_id :a3 # !IMPORTANT: Make sure this is unique amongst your DB models
-end
-```
-
-Next, we'll create a factory for it in `specs/factories/db/account.factory.rb`:
-
-```ruby
-require "bcrypt"
-FactoryBot.define do
-  factory :account, class: "DB::Account" do
-    email         { Faker::Internet.unique.email }
-    trait :inactive do
-      deactivated_at { Time.now }
-    end
-  end
-end
-```
-
-Next, we'll make seed data in `app/src/back_end/data_models/seed/app_seed_data.rb`
-
-```ruby
-require "brut/back_end/seed_data"
-class AppSeedData < Brut::BackEnd::SeedData
-  include FactoryBot::Syntax::Methods
-  def seed!
-    create(:account,            email: "pat@example.com")
-    create(:account, :inactive, email: "chris@example.com")
-  end
-end
-```
-
-Now, let's apply this to the database and load the seed data:
-
-```
-> bin/db migrate
-> bin/db migrate -e test
-> bin/db seed
-```
-
-### Create a Login Page
-
-To make this UI work, we'll need a login page and a dashboard page.
-
-```
-> bin/scaffold page /login
-> bin/scaffold page /dashboard
-```
-
-We'll also need a login form:
-
-```
-> bin/scaffold form /login
-```
-
-We'll add a link on the HomePage to log in:
-
-```ruby
-# app/src/front_end/pages/home_page.rb
-class HomePage < AppPage
-  def page_template
-    h1 { "Welcome!" }
-    a(href: LoginPage.routing) {
-      "Log in"
-    }
-  end
-end
-```
-
-Before building the login page, we'll need the form.  It'll just have one field:
-email:
-
-```ruby
-# app/src/front_end/forms/login_form.rb
-class LoginForm < AppForm
-  input :email # Brut will make this type=email and required
-end
-```
-
-Now, we can create the login page:
-
-```ruby
-# app/src/front_end/pages/login_page.rb
-class LoginPage < AppPage
-
-  include Brut::FrontEnd::Components
-
-  # An existing form can be passed in, so that this
-  # page can be shown with form errors from a previous
-  # login attempt
-  def initialize(form: nil)
-    @form = form || LoginForm.new
-  end
-
-  def page_template
-    h1 { "Login, please!" }
-    brut_form do
-      FormTag(for: @form) do
-        label do
-          Inputs::InputTag(form: @form, input_name: :email)
-          div { "Email" }
-          ConstraintViolations(form: @form, input_name: :email)
-        end
-        button do
-          "Login"
-        end
-      end
-    end
-  end
-end
-```
-
-Let's style the constraint violations in `app/src/front_end/css/index.css`:
-
-```css
-/* app/src/front_end/css/index.css */
-brut-cv {
-  display: none;
-}
-
-brut-cv[server-side],
-brut-form[submitted-invalid] brut-cv {
-  display: block;
-  color var(--red-300);
-}
-```
-
-Now, you can click on "Login", and you should see a client-side error message.
-
-### Handle Logins
-
-Now, we'll build out the login handler.  An email must exist and be active to be
-allowed in.
-
-```ruby
-# app/src/front_end/handlers/login_handler.rb
-class LoginHandler < AppHandler
-  def initialize(form:, session:, flash:)
-    @form    = form
-    @session = session
-    @flash   = flash
-  end
-
-  def handle
-    if !@form.constraint_violations? # no client-side issues
-      account = DB::Account.find(email: @form.email, deactivated_at: nil)
-      if !account
-        @form.server_side_constraint_violation(
-          input_name: :email,
-          key: :no_such_account
-        )
-      end
-    end
-    if @form.constraint_violations?
-      LoginPage.new(form: @form)
-    else
-      @session.login!(account:)
-      redirect_to(DashboardPage)
-    end
-  end
-end
-```
-
-Hopefully, this logic is straightforward.  We'll need to allow `AppSession` to
-implement `login!`.  We'll also need to have it fetch the `DB::Account` from the
-session, we'll add that, too.
-
-```ruby
-# app/src/front_end/support/app_session.rb
-class AppSession < Brut::FrontEnd::Session
-  def login!(account:)
-    self[:account_id] = account.id
-  end
-  def account
-    DB::Account.find(id: self[:account_id])
-  end
-end
-```
-
-Now, we can build the dashboard page to greet them.  Instead of injecting the
-session, however, we're going to inject the account as `current_account:`.  We'll
-set this up in a minute.
-
-```ruby
-# app/src/front_end/pages/dashboard_page.rb
-class DashboardPage < AppPage
-  def initialize(current_account:)
-    @current_account = current_account
-  end
-
-  def page_template
-    h1 { "Dashboard" }
-    h2 { "Hello #{@current_account.email}!" }
-  end
-end
-```
-
-### Injecting the Current Account
-
-We want the current account to be in the `Brut::FrontEnd::RequestContext` if the
-visitor is logged in.  We'll do that in a route hook.
-
-First, we'll declare it in `App`:
-
-```ruby
-# app/src/app.rb
-class App < Brut::Framework::App
-
-  # ...
-
-  before :SetupCurrentAccount
-
-  # ...
-end
-```
-
-Now, we can build the `SetupCurrentAccount` route hook.  Since it'll run after
-`Brut::FrontEnd::RouteHooks::SetupRequestContext`, we can assume a `RequestContext`
-will be available for injection. The session will be, too, of course:
-
-```ruby
-# app/src/front_end/hooks/setup_current_account.rb
-class SetupCurrentAccount < Brut::FrontEnd::RouteHook
-  def before(request_context:, session:)
-    logged_in = !!session.account
-    # NOTE: we do not insert nil. Either insert a value or don't insert.
-    if logged_in
-      request_context[:current_account] = session.account
-    end
-  end
-end
-```
-
-At this point, the code we've written should work.  The only problem is that anyone
-can access the Dashboard page. Granted, doing so without being logged in will cause
-an error, but we don't want that.
-
-### Requiring Login
-
-To require login, we'll add to the `SetupCurrentAccount` hook we created. We want to
-allow access to the login page as well as any Brut-owned paths.  If a logged-out
-user access a restricted page, we'll redirect them to the login page.
-
-```ruby
-# app/src/front_end/hooks/setup_current_account.rb
-class SetupCurrentAccount < Brut::FrontEnd::RouteHook
-  def before(request_context:, session:)
-    logged_in = !!session.account
-    if logged_in
-      request_context[:current_account] = session.account
-    end
-
-    is_login_page      = request.path_info.match(/#{Regexp.escape(LoginPage.routing)}/
-    is_brut_owned_path = env["brut.owned_path"]
-
-    path_requires_login = !is_login_page && 
-                          !is_brut_owned_path
-
-    if !logged_in && path_requires_login
-      redirect_to(LoginPage)
-    end
-  end
-end
-```
-
-And that's it!  The visitor should be redirected if they aren't logged in, but
-should be allowed to restricted pages like the dashboard page if they are.
-
-### You Don't Need Page Hooks for This
-
-Implementing something like this in Rails would usually involve similar code to what
-we just did, but pages requiring login would have some sort of `before_action`:
-
-```ruby{2}
-class WidgetsController < ApplicationController
-  before_action :require_login!
-
-  # ...
-end
-```
-
-This could be shared in a parent page, but you essentially have to remember to do this on every page that requires login (or do the opposite - allow specific pages to be accessed without logging in).
-
-In Rails, this is a good practice, because even though your views won't route a
-logged-out visitor to a logged-in page, URL hacking or bugs could result in an
-attempt to do so.  You need the failsafe.
-
-In Brut, the very definition of the page's class includes the requirement for the
-`current_account`. The page cannot be instantiated without it.
-
-Thus, there is no need for a failsafe.  `SetupCurrentAccount` handles checking the
-routes, and that's it.  If someone hacks a URL or a bug in the code sends a
-logged-out visitor to the dashboard page, Brut literally cannot handle the request, since the `current_account` will be missing.