brut 0.0.29 → 0.1.0

data/brutrb.com/pages.md

@@ -1,65 +1,34 @@
 # Pages
 
-The core abstraction of Brut is the core concept of the web: the web page.
-
-A web page is fetched by the browser using an HTTP `GET` request to a URL. When that happens, Brut instantiates an object of a *page class* and uses its `page_template` method to generate its HTML (using calls to Phlex's API).
+A core abstraction of Brut is the core concept of the web: the web page.
 
 ## Overview
 
-You can create everything you need for a page by using `bin/scaffold`:
+To create a web page, you'll need:
 
-```shell
-> bin/scaffold page /new-widgets
-```
+* 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 use `--dry-run` to see what it will do:
+You can create all this with `bin/scaffold`, which accepts the route you want:
 
 ```shell
-> bin/scaffold --dry-run /new-widgets
-bin/scaffold --dry-run page /new-widgets
-[ bin/scaffold ] app/src/app.rb
-[ bin/scaffold ] will contain:
-
-page "/new-widgets"
-
-[ bin/scaffold ] app/src/front_end/pages/new_widgets_page.rb
-[ bin/scaffold ] will contain:
-
-class NewWidgetsPage < AppPage
-  def initialize # add needed arguments here
-  end
-
-  def page_template
-    h1 { "Your page is ready" }
-  end
-end
-
-[ bin/scaffold ] specs/front_end/pages/new_widgets_page.spec.rb
-[ bin/scaffold ] will contain:
-
-require "spec_helper"
-
-RSpec.describe NewWidgetsPage do
-  it "should have tests" do
-    expect(true).to eq(false)
-  end
-end
-
-[ bin/scaffold ] app/config/i18n/en/2_app.rb
-[ bin/scaffold ] will contain:
+> 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
+```
 
-       "NewWidgetsPage": {
-         title: "New widgets page",
-       },
+or
 
-[ bin/scaffold ] Page source is in        app/src/front_end/pages/new_widgets_page.rb
-[ bin/scaffold ] Page HTML template is in app/src/front_end/pages/new_widgets_page.html.erb
-[ bin/scaffold ] Page test is in          specs/front_end/pages/new_widgets_page.spec.rb
-[ bin/scaffold ] Added title to           app/config/i18n/en/2_app.rb
-[ bin/scaffold ] Added route to           app/src/app.rb
+```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, of course, edit `app.rb` and create the classes yourself.
+You can also perform these steps manually.
 
 > [!WARNING]
 > Adding a `page` route without the corresponding class may not always
@@ -73,59 +42,73 @@ You can, of course, edit `app.rb` and create the classes yourself.
 
 ### Creating a Page
 
-Page classes are expected to be in `app/src/front_end/pages`, named conventionally the way Zeitwerk would expect.  For example, `Admin::WidgetsByIdPage` would be expected in `app/src/front_end/pages/admin/widgets_by_id_page.rb`.
+Pages need a `page_template` method that contains calls to Phlex, which will produce
+the page's HTML.
 
-A page class must be a subclass of `Brut::FrontEnd::Page`, however in practice it will be a subclass of `AppPage` in your app, which is a subclass of `Brut::FrontEnd::Page`.  All Brut components have an app-specific base class to allow sharing of logic, if needed.
+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`.
 
-Brut will create the instance of the page class, passing in the keyword
-arguments the initializer specifies (see [Keyword Injection](/keyword-injection)). In particular, any placeholders in the route will be passed-in to the initializer. This is why those placeholders must be valid Ruby keyword argument names.
-
-For example, `Admin::WidgetsByIdPage` and its template might look like so:
-
-```ruby 
-# pages/admin/widgets_by_id_page.rb
-class Admin::WidgetsByIdPage < AppPage
-  def initialize(id:)
-    @widget = DB::Widget.find!(id:)
-  end
-
-  private attr_reader :widget
+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
-    h1 { widget.name }
-    h2 { widget.status }
+    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
 ```
 
-Note that `Admin::WidgetsByIdPage` is a normal Ruby class, so you could implement `#widget` as a method, and lazy-load the widget:
-
-```ruby {13}
-class Admin::WidgetsByIdPage < AppPage
-  def initialize(id:)
-    @widget_id = id
-  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>
+```
 
-  def page_template
-    h1 { widget.name }
-    h2 { widget.status }
-  end
+### Accessing Data in a Page
 
-private
+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.
 
-  def widget = DB::Widget.find!(id: @widget_id)
+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
 ```
 
-A page's initializer can also accept other parameters, provided by Brut.
+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.
 
-### Arguments Available to Initializer
+This mechanism is called [keyword injection](/keyword-injection) and is available to many class you create, including pages.
 
-Brut's [keyword injection](/keyword-injection) is used to create the instance of your page.  You can have Brut inject what you need by
-specifying keyword arguments.
+Here is a list of what is available:
 
-| Value | Type | Description |
+| 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) |
@@ -133,6 +116,7 @@ specifying keyword arguments.
 `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.
@@ -150,23 +134,22 @@ def initialize(id:,
 ```
 
 > [!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.
+> 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.
 
-### 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.
+### Page Hooks
 
-`before_generate` achieves this. If your page class implements it, it will be called after the page is
-initialized, but before the template creationg process starts.  Depending on what `before_generate`
-returns, the visitor may be redirected, an error could be sent, or HTML generation may proceed as normal.
+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.
 
-The return value of `before_generate` determines what will happen:
+`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.
@@ -179,83 +162,63 @@ an `HttpStatus` from a number.
 
 See [Unit Testing](/unit-tests) for some basic assumptions and configuration available for all Brut unit tests.
 
-Since pages are Plain Ole Ruby Objects, you could test them using conventional means.  However, since the ultimate behavior of a
-page is to produce HTML based on its template, it's recommended that your page tests generate HTML and you make assertions about the page's behavior by examining that HTML.
+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.
 
-Brut provides convenience methods for this, based on Nokogiri.  With them, you should be able to access elements of your page using
-the same sorts of CSS selectors you'd use with `document.querySelector` to debug your app in a browser.
+### Generating a Response
 
-### `generate_and_parse` Parses the Generated HTML
+* 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:
 
-Brut uses RSpec, so when a page test is detected, Brut will include `Brut::SpecSupport::ComponentSupport`, which provides useful methods and includes other modules you'll need to make testing more straightforward.
+### Asserting Results
 
-The main method you'll use is `generate_and_parse`, which accepts an instance of your page and returns a
-`Brut::SpecSupport::EnhancedNode`, which is a delegate to a Nokogiri node.
-
-Below, we use the method `e!`, which is provided by `EnhancedNode`. This works just like Nokogiri's `css`, except
-that requires exactly one element to match the selector. If not, the test fails.  This allows a more compact test
-when you know there should only be one element matching the selector you've provided.
+When using `generate_and_parse`, you have access to all of Nokogiri, however
+`Brut::SpecSupport::EnhancedNode` provides two methods to simplify your test:
 
 ```ruby
-RSpec.describe CompanyByCompanyId::LocationsByLocationIdPage do
-  describe "render" do
-    it "shows the company name and location address" do
-      company  = create(:company)  # You must implement
-      location = create(:location) # You must implement
-
-      page = described_class.new(company_id: company.id.to_s,
-                                 location_id: location.id.to_s)
-
-      parsed_html = generate_and_parse(page)
-
-      h1 = parsed_html.e!("h1")
-      h2 = parsed_html.e!("h2")
+it "should work" do
+  result = generate_and_parse(described_class.new)
 
-      expect(h1.text).to include(company.name)
-      expect(h2.text).to include(location.address)
-    end
-  end
+  expect(result.e!("h1").text).to include("Welcome")
+  expect(result.e("h2")).to       eq(nil)
 end
 ```
 
-`e` (without a bang/`!`) is also provided, which will allow zero or one elements to match the selector (i.e. it only fails if there is more than one match).  `e` and `e!` are key methods that allow the use of CSS selectors to be usable in your tests.
-
-See `Brut::SpecSupport::ClockSupport`, `Brut::SpecSupport::FlashSupport`, and `Brut::SpecSupport::SessionSupport` for additional methods you can use to make it easier to work with clocks, flashes, and sessions, respectively.
-
-### `generate_result` Tests `before_generate`
-
-If your page uses `before_generate`, when you call `generate_and_parse`, it will fail unless the page generated
-HTML.  In those cases, you can use `generate_result`, which will return what `before_generate` returned, unless
-it returned `nil`, in which case it will return the unparsed HTML.
+* `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.
 
-```ruby {4,10,12}
-RSpec.describe CompanyByCompanyId::LocationsByLocationIdPage do
-  describe "render" do
-    it "redirects back to the home page for expired companies" do
-      company  = create(:company, :expired)  # You must implement
-      location = create(:location) # You must implement
+When using `generate_result`, you will want to use one of two special purpose
+matchers:
 
-      page = described_class.new(company_id: company.id.to_s,
-                                 location_id: location.id.to_s)
-
-      result = generate_result(page)
-
-      expect(result).to have_redirected_to(HomePage)
+```ruby
+it "redirects" do
+  result = generate_result(described_class.new)
+  expect(result).to have_redirected_to(AuthPage)
+end
 
-    end
-  end
+it "404's" do
+  result = generate_result(described_class.new)
+  expect(result).to have_returned_http_status(404)
 end
 ```
 
-`have_redirected_to` is a matcher provided by Brut. `have_returned_http_status` is also available to assert that
-`before_generate` returned an HTTP status.  The reason to use these matchers and `generate_result` instead of
-calling `before_generate` directly is that you want to use the page in a test the way it's used in your app.  You
-will also get higher-quality test failure messages.
+- `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`)
 
-## Recommended Practices
+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:
 
-You can build your pages however you like, but here are some tips that will make your app more sustainable and
-easier to work with.
+- `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.
 
@@ -273,59 +236,7 @@ below, you won't need to use `before_generate` as a failsafe check on authorizat
 
 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.
 
-Let's take a common example of a page that require that a visitor be logged in.  While your app will have logic to avoid routing a logged-out visitor to any of those pages, it may seem like a good practice to add a failsafe check inside the logic of the page requiring login. This is very common in Rails and might look like so:
-
-```ruby{2}
-class WidgetsController < ApplicationController
-  before_action :require_login!
-
-  # ...
-end
-```
-
-`before_action` is the failsafe - in case someone hacks a URL to find this page, or there is a bug in your app where unauthorized visitors are sent to this page, the `before_action` prevents the page from working.
-
-In Brut, you could mimic this behavior using `before_generate`, however this isn't necessary.  Instead, you can take advantage of keyword injection.
-
-Consider this implementation of `WidgetsByIdPage`:
-
-```ruby
-class WidgetsByIdPage < AppPage
-  def initialize(id:, current_user:)
-    # ...
-  end
-end
-```
-
-`id:` is injected because it is a route placeholder.  `current_user:` however, is completely custom to our app.  We can arrange to
-have it injected.  We'll create a [Route Hook](/hooks) to do this.
-
-> [!CAUTION]
-> This hook is not production-ready. It lacks certain error-handling code and
-> makes an assumption about how the session is managed. It's for demonstration only.
-> The [route hooks](/hooks) section has a more
-> appropriate example.
-
-```ruby{6}
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:)
-    if session.current_user_id
-      user = DB::User.find(id: session.current_user_id)
-      if user
-        request_context[:current_user] = user
-      end
-    end
-  end
-end
-```
-
-Before any route is handled, this before hook is run and passed the `Brut::FrontEnd::RequestContext`.  This is where all the
-injectible values live.  `request_context[:current_user] = user` makes `user` available to be injected into a page or handler.
-
-What this means is that when a visitor is not logged in, there will be no injectible value for `:current_user`.  Brut will not be able
-to instantiate `WidgetsByIdPage`, and an error is generated.  It is literally impossible to route a logged-out visitor to that page.
-
-In practice, this means that any page that requires a logged-in visitor will specify the `current_user:` keyword argument, and **not provide a default value**.  You are still required to make sure no one routes a logged-out visitor to a page requiring authentication, but now you don't have to remember to add logic to each page that requires login—you bake it into the page class' type.
+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
 
@@ -367,9 +278,10 @@ 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, or `time_tag` can be used to create a `<time>` HTML element.
+`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.
 
-If you wish to add helpers to be used in more than one page, you can either add the method to a common base class like `AppPage`, or create a module and `include` it.
+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?
 

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

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