brut 0.0.29 → 0.2.0

data/brutrb.com/dir-structure.md

@@ -0,0 +1,120 @@
+# Directory Structure
+
+```
+.
+├── app
+│   ├── config
+│   │   └── i18n
+│   │       └── en
+│   ├── public
+│   │   ├── css
+│   │   ├── js
+│   │   └── static
+│   │       └── images
+│   └── src
+│       ├── back_end
+│       │   ├── data_models
+│       │       ├── db
+│       │       ├── migrations
+│       │       └── seed
+│       ├── cli
+│       └── front_end
+│           ├── components
+│           ├── css
+│           ├── fonts
+│           ├── forms
+│           ├── handlers
+│           ├── images
+│           ├── js
+│           ├── layouts
+│           ├── pages
+│           ├── route_hooks
+│           ├── support
+│           └── svgs
+├── bin
+├── deploy
+├── dx
+└── specs
+    ├── back_end
+    │   ├── data_models
+    │       └── db
+    ├── e2e
+    ├── factories
+    │   └── db
+    └── front_end
+        ├── components
+        ├── handlers
+        ├── js
+        ├── pages
+        └── support
+```
+
+## Top Level
+
+| Directory | Purpose |
+|-----------|---------|
+| `app/`    | Contains all configuration and source code specific to your app |
+| `bin/`    | Contains tasks and other CLIs to do development of your app, such as `bin/test` |
+| `dx/`     | Contains scripts to manage your development environment |
+| `specs/`  | Contains all tests |
+
+## Inside `app`/
+
+| Directory | Purpose |
+|-----------|---------|
+| `bootstrap.rb` | A ruby file that sets up your app and ensures everything is `require`d in the right way. |
+| `config/` | Configuration for your app, such as localizations and translations. Brut tries very hard to make sure there is no YAML in here at all. YAML is not good for you. |
+| `public/` | Root of public assets served by the app. |
+| `src/` | All source code for your app |
+
+Inside `app/src`
+
+| Directory | Purpose |
+|-----------|---------|
+| `app.rb` | The core of your app, mostly configuration, such as routes, hooks, middleware, etc. |
+| `back_end/` | Back end classes for your app including database schema, DB models, seed data, and your domain logic |
+| `cli/` | Any CLIs or tasks for your app |
+| `front_end/` | The front-end for your app, including pages, components, forms, handlers, JavaScript, and assets |
+
+Inside `app/src/back_end`
+
+| Directory | Purpose |
+|-----------|---------|
+| `data_models/app_data_model.rb` | Base class for all DB model classes |
+| `data_models/db` | DB model classes |
+| `data_models/db.rb` | Namespace module for DB model classes |
+| `data_models/migrations` | Database schema migrations |
+| `data_models/seed` | Seed data used for local development |
+
+Inside `app/src/front_end`
+
+|Directory       | Purpose |
+|----------------|---------|
+| `components/`  | Component classes |
+| `css/`         | CSS, managed by esbuild and `bin/build-assets` |
+| `fonts/`       | Custom fonts, managed by esbuild and `bin/build-assets` |
+| `forms/`       | Form classes |
+| `handlers/`    | Handler classes |
+| `images/`      | Images, copied to `app/public` by `bin/build-assets` |
+| `js/`          | JavaScript, managed by esbuild and `bin/build-assets` |
+| `layouts/`     | Layout classes |
+| `middlewares/` | Rack Middleware, if any |
+| `pages/`       | Page classes |
+| `route_hooks/` | Route hooks, if any |
+| `support/`     | General support classes/junk drawer. |
+| `svgs/`        | SVGs you want to render inline |
+
+## Inside `specs/`
+
+`specs/` is intended to mirror `app/src`, but has a few extra directories:
+
+
+|Directory       | Purpose |
+|----------------|---------|
+| `specs/back_end` | tests for all back-end code, organized the same as `app/src/back_end` |
+| `specs/back_end/data_models/db` | tests for all DB classes, if needed |
+| `specs/e2e` | End-to-end tests, organized however you like |
+| `specs/factories` | Root of all factories for FactoryBot. You can create subdirectories here for non-DB classes you may want to be able to create |
+| `specs/factories/db` | Factories to create DB records |
+| `specs/front_end` | tests for all front-end code, organized the same as `app/src/front_end` |
+| `specs/js`| *JavaScript* code to test any autonomous custom elements you have created |

data/brutrb.com/doc-conventions.md

@@ -2,32 +2,34 @@
 
 ## Terminology
 
-Brut attempts to use existing terminology where possible, particularly where that technology applies to the web platform.  For example, there is not a thing called "CSS variables", rather the term is "custom properties". HTML entities are *elements* or *tags* that have *attributes*. As another example, HTML doesn't have *validations*, rather it as *constraints*, which can be *violated*.
+Brut attempts to use existing terminology where possible, particularly where that technology applies to the web platform.  For example, there is not a thing called "CSS variables", rather the term is "custom properties".
 
-When speaking about Ruby, we prefer the term *initializer* over constructor, *parameters* over arguments, and *methods* over messages.  We also prefer *tests* over specs, however test files *are* located in `specs/` and named `*.spec.rb` to be consistent with RSpec's nomenclature.  We prefer *end-to-end* or *e2e* tests instead of browser tests or request specs. 
+Here are some common exampels:
 
-Further, Brut doesn't render HTML, it *generates* it.  The browser renders the HTML for the website's visitor. One exception is Phlex, which uses the term *render* to mean "generate HTML to an internal buffer that will be delivered to the client later".  Thus, you will need to call Phlex's `render` method from time to time, even though it is not rendering HTML but helping to generate it.
 
-Lastly, the documentation tries to talk about the person accessing a website as a "vistor" not a "user". Though the "user" nomenclature is near-ossified in software development, we feel "visitor" is more apt.
+- HTML entities are **elements** or **tags**
+- HTML elements have **attributes**.
+- Forms don't have validations, they have **constraints** which are **violated** by invalid data.
+- Ruby classes don't have constructors, they have **initializers**.
+- Invoking behavior on a Ruby object is **calling a method**, not sending a message.
+- Despite being in `specs/`, the files in there are **tests**, not specifications or "specs".
+- Tests that use a browser are **end to end** or **e2e** tests.
+- HTML is not rendered, but **generated**. The browser renders the HTML sent to it by the server, along with the CSS.
+- Your app or site doesn't have users, it has **visitors**.
 
 ## Structure of These Documents
 
 Each page here documents on aspect of Brut, called a *module*, and these pages are organized along four sections:
 
-* **Overview** - provides detailed information on how this part of Brut works, with minimal examples to orient you to
-the terms and design of that module.  Links to reference documentation are provided inline as needed.
-* **Testing** - information about how to write tests for the code in this module.  For example, in [Pages](/pages), we detail how you are intended to test page classes.
-* **Recommended Practices** - this section outlines what we believe is the best way to use the module, along with
-justifications for the recommended approach.  While you are free to ignore this advice, it's often useful to
-understand the intention of the authors.
-* **Technical Notes** - where appropriate, technical details about how or why the module works the way it does
-are provided.  This section should be marked with a date to allow you to understand the recency of the
-information. It may not always be up to date, but this can help further clarify what is happening under the
-covers and why.
+* **Overview** - What the module does, how it works, and a brief example.
+* **Testing** - How to test the code you write in this module.
+* **Recommended Practices** - Opinions from the creators about how best to think about the code in this module.
+* **Technical Notes** - details about the technical implementations that may be
+useful as context.
 
 ## Names of the Library and Associated Modules
 
-This framework is called "Brut" though may be called "BrutRB".  It lives at `brutrb.com`.
+This framework is called "Brut" though may be called "BrutRB" or "brut-rp".  It lives at `brutrb.com`.  Never use "brutRB", "brut_rb", etc.
 
 The JavaScript library is called "BrutJS", but is `brut-js` in code or the filesystem. "Brut-JS" is wrong, as is `brut_js`.
 

data/brutrb.com/dx

@@ -0,0 +1 @@
+../dx

data/brutrb.com/end-to-end-tests.md

@@ -55,7 +55,7 @@ RSpec.describe "logging into the website" do
 end
 ```
 
-`playwright-ruby-client` provides excellent documentation on how it has adapter Playwright's API for use
+`playwright-ruby-client` provides excellent documentation on how it has adapted Playwright's API for use
 in Ruby.
 
 ### Test Setup
@@ -70,9 +70,15 @@ jobs, but rather assert the effects those jobs will have. Redis is flushed betwe
 
 Inside your test, `t` is available to produce translations. You can also access all your page and handler classes, so you can (and should) use `.routing`, e.g. `DashboardPage.routing`, to generate or access routes for your app.
 
-You can set `e2e_timeout` on any test to override the default amount of time Playwright will wait for a
+You can set the `e2e_timeout` metadata on any test to override the default amount of time Playwright will wait for a
 locator to locate an element. The default is 5 seconds.
-`, to generate or access routes for your app.
+
+```ruby
+RSpec.describe "Test for login", e2e_timeout: 10 do
+  # ...
+end
+```
+
 You can also configure behavior with environment variables:
 
 | Variable            | Default | Purpose                                                                                           |
@@ -122,12 +128,9 @@ The main Playwright documentation encourages you to locate elements by "accessib
 indirect ways of finding elements.  In practice, this is error prone and tedious.  Determining the
 accessible name of an element is not always easy.
 
-We recommend you assess your app's accssibility in another way than trying to do it while performing
-end-to-end tests.  Instead, locate elements with CSS selectors—this is what you'd use to debug your app so
-it makes sense as a testing technique.
+We recommend you assess your app's accessibility in another way than trying to do it while performing end-to-end tests.  Instead, locate elements with CSS selectors—this is what you'd use to debug your app so it makes sense as a testing technique.
 
-Insulating your end-to-end tests from markup changes does not produce significant savinsg and can make
-tests more difficult to write.
+Insulating your end-to-end tests from markup changes does not produce significant savings and can make tests more difficult to write.
 
 ### Testing Must Inform your HTML
 
@@ -170,5 +173,4 @@ make sure it's still needed.
 
 _Last Updated June 13, 2025_
 
-The test server is run bin `bin/test-server`, which is why Sidekiq will be running when your app is
-running for an e2e test.
+The test server is run via `bin/test-server`.

data/brutrb.com/features.md

@@ -0,0 +1,373 @@
+# Quick Tour of Brut's Features
+
+## Pages
+
+A [*Page*](/pages) models, well, a web page. It's a class that holds all the data
+necessary to generate its HTML as well as a method called `page_template`, which
+generates the HTML via Phlex.
+
+A page's routing is convention-based and starts with a URL:
+
+```ruby{6}
+class App < Brut::Framework::App
+  def id           = "my-app"
+  def organization = "my-org"
+
+  routes do
+    page "/dashboard"
+  end
+end
+```
+
+This URL means our page class is expected in `DashboardPage`.
+
+```ruby
+class DashboardPage < AppPage
+  def initialize
+    @now     = Time.now
+  end
+
+  def page_template
+    main do
+     h1 { "Hello!" }
+     h2 do
+       plain("It's ")
+       time(datetime: l(@now, format: iso_8601)) do
+         l(@now, format: date)
+       end
+     end
+    end
+  end
+end
+```
+
+This would all produce HTML like so, depending on the value of 
+
+```html [/dashboard]
+<main>
+  <h1>Hello!</h1>
+  <h2>It's
+    <time datetime="2025-02-17">
+      Monday, Feb 17
+    </time>
+  </h2>
+</main>
+```
+
+Note that the actual HTML delivered would include the code for a layout.
+
+## Layouts
+
+Brut includes the concept of [layouts](/layouts), and they work similar to Rails.
+Layouts are classes, however, and implement the Phlex-standard `view_template`
+method:
+
+```ruby
+class DefaultLayout < Brut::FrontEnd::Layout
+  def initialize(page_name:)
+    @page_name = page_name
+  end
+
+  def view_template
+    doctype
+    html(lang: "en") do
+      head do
+        meta(charset: "utf-8")
+        link(rel: "preload", as: "style", href: asset_path("/css/styles.css"))
+        link(rel: "stylesheet",           href: asset_path("/css/styles.css"))
+        script(defer: true, src: asset_path("/js/app.js"))
+        title { app_name }
+      end
+      body do
+        yield
+      end
+    end
+  end
+end
+```
+
+This produces this HTML:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <link rel="preload" as="style" href="/css/styles-«HASH».css">
+    <link rel="stylesheet" href="/css/styles-«HASH».css">
+    <script defer src="/js/app-«HASH».js">
+    <title>My Awesome App</title>
+  </head>
+  <body>
+    <-- page HTML here -->
+  </body>
+</html>
+```
+
+
+## Components
+
+*Components* are a way to manage the complexity of HTML generation. The are Phlex components, meaning they are a class that implements `view_template`.
+
+Here's an example of a flash message component:
+
+```ruby
+# components/flash_component.rb
+class FlashComponent < AppComponent
+  def initialize(flash:)
+    if flash.notice?
+      @message_key = flash.notice
+      @role = :info
+    elsif flash.alert?
+      @message_key = flash.alert
+      @role = :alert
+    end
+  end
+
+  def any_message? = !@message_key.nil?
+
+  def view_template
+    if any_message?
+      div(role: @role) do
+        t([ :flash, @message_key ])
+      end
+    end
+  end
+end
+```
+
+You can then use this in any other view using `render`, provided by Phlex.
+
+```ruby
+def page_template
+  header do
+    render FlashComponent.new(flash:)
+  end
+end
+```
+
+## Forms
+
+[*Forms*](/forms) are a major concept like pages, since they are the way a browser
+submits data to the server.
+
+In Brut, a form does three things:
+
+* Describes the data in the `<form>` tag
+* Implies a route where its data is submitted via HTTP POST
+* Provides access to the submitted data (via an object with methods, not a Hash of Whatever)
+
+Like `page`, `form` declares a form's route:
+
+```ruby{2}
+routes do
+  form "/login"
+end
+```
+
+Brut is convention-based, so it will expect a class named `LoginForm` to exist. It
+will also expect `LoginHandler` to exist, which is a class that will receive the
+form submission and process it. More on handlers below.
+
+`LoginForm` uses class methods to declare its inputs.  These class methods mirror
+the various form element tags in HTML (`input`, `select`, etc.), and the methods
+attributes allow you to declare names and client-side constraints:
+
+```ruby [forms/login_form.rb]
+class LoginForm < AppForm
+  input :email
+  input :password, minlength: 8
+end
+```
+
+An instance of this class can be used to create HTML:
+
+```ruby
+def view_template
+  FormTag(for: @form) do
+    Inputs::InputTag(form: @form, input_name: :email)
+    Inputs::InputTag(form: @form, input_name: :password)
+    button { "Login" }
+  end
+end
+```
+
+> [!NOTE]
+> We'll explain what `FormTag` and `Inputs::InputTag` are in the [forms
+> section](/forms)
+
+This generates this HTML:
+
+```html
+<form action="/login" method="POST">
+  <input type="email" name="email" required>
+  <input type="password" name="password" required minlength="8">
+  <button>Login</button>
+</form>
+```
+
+When the form is submitted, an instance of `LoginForm` is created and made available
+to `LoginHandler`
+
+## Handlers
+
+A handler is like a controller in Rails, except it only has one method: `handle`.
+Unlike a Rails controller, a handler class is given its arguments explicitly, and
+`handle`'s return value dictates what will happen next.
+
+```ruby
+class LoginHandler < AppHandler
+  def initialize(form:)
+    @form = form
+  end
+  def handle
+    if @form.email == "secret@example.com" &&
+       @form.password = "sup3rs3cret!"
+       redirect_to(DashboardPage)
+    else
+      form.server_side_constraint_violation(
+        input_name: :email,
+        key: :no_such_user
+      )
+      LoginPage.new(form:)
+    end
+  end
+end
+```
+
+Note that we access the form's values as methods, not by digging into a Hash of
+Whatever.  Also note that returning an instance of a page will generate that page's
+HTML, much like Rails' `render :edit` might.  Lastly, `redirect_to` is a
+convenience to generate a URL to `DashboardPage`, and ultimately causes `handle` to
+return a `URI`, which Brut interprets as a redirect.
+
+
+## JavaScript
+
+Brut doesn't include a front-end framework, however you can certainly use one.  All
+JavaScript is bundled into a single bundle by [esbuild](https://esbuild.github.io/).
+
+Brut includes [BrutJS](/brut-js), which is a collection of autonomous custom
+elements AKA Web Components that provide convenient features like autosubmit, form
+submission confirmation and more:
+
+```ruby{5,7}
+def view_template
+  FormTag(for: @form) do
+    Inputs::InputTag(form: @form, input_name: :email)
+    Inputs::InputTag(form: @form, input_name: :password)
+    brut_confirm_submit(message: "Really login? In this economy?!") do
+      button { "Login" }
+    end
+  end
+end
+```
+
+When "Login" is pressed, `window.confirm` will ask if the visitor wants to proceed.
+This custom element can also use a `<dialog>` that you style, and works even better
+if that `<dialog>` makes use of `<brut-confirmation-dialog>`.
+
+## CSS
+
+Brut includes [BrutCSS](/css#using-brut-css), which is a lightweight utility-based
+CSS library to let you get started quickly. It's *not* TailwindCSS, nor will it ever
+be.
+
+You can replace it with whatever you like easily enough.
+
+
+## Database Schema
+
+Brut provides access to an SQL database via Sequel.  Brut uses Sequel's database schema management, however it is enhanced to
+encourage good practices by default.
+
+> [!NOTE]
+> Brut currently *only supports* PostgreSQL.  It may support all RDBMSes that Sequel supports, but as of now,
+> it's just Postgres.
+
+Consider a `households` table that relates to an `accounts` table.
+
+```ruby
+create_table :households,
+             comment: "Family unit managing the data" do
+  column :timezone, :text
+  column :dinner_time_of_day, :text
+  constraint(
+    :time_must_be_time,
+    %{
+      (dinner_time_of_day ~ '^[01][0-9]:[0-5][0-9]$') OR
+      (dinner_time_of_day ~ '^2[0-3]:[0-5][0-9]$')
+    }
+  )
+end
+
+create_table :accounts,
+             comment: "People or systems who can access this system",
+             external_id: true do
+
+  column :email,             :email_address, unique: true
+  column :deactivated_at,    :timestamptz, null: true
+  foreign_key :household_id, :households
+end
+```
+
+This is mostly using [Sequel's built-in migrations API](https://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html).  But, a few additional behaviors are happening:
+
+* Columns default to `NOT NULL`
+* Tables require comments
+* Foreign keys default to having constraints and indexes
+
+There are other quality-of-life features of Brut's migration system, all designed to default to a good practice, with a way to do it
+however you want when needed.
+
+## Database Access
+
+Brut uses `Sequel::Model` to access data in your database.  To discourage the conflation of "models of database tables" with "models
+of your application's domain", these classes are in the `DB` namespace.  Thus, the class `DB::Household` would be able to access the
+`households` table defined above. This frees you up to create a `Household` class to model your domain's logic without being coupled
+to how you store some data in a database.
+
+```ruby
+class DB::Account < AppDataModel
+  has_external_id :ac
+  many_to_one :household
+end
+
+class DB::Household < AppDataModel
+  one_to_many :accounts
+end
+```
+
+## Domain and Business Logic
+
+Brut uses Zeitwerk for code loading, so any directories you create will be auto-loaded and refreshed during development.  This means that you can create a class named `Household` in `app/src/back_end/domain/household.rb` and it would be loaded.  Or, you could create `HouseholdService` in `app/src/back_end/services/household_service.rb` if you like.
+
+> [!TIP]
+> Providing a generally-useful abstraction for business or domain logic is not usually feasible.
+> Thus, Brut doesn't provide much beyond Zeitwerk's auto-loading feature.  It may provide more
+> assistance in  the future, but for now, Brut's approach is to free you from any prescription
+> or moral imperative. Manage your domain and business logic how you see fit. You know your domain
+> and team better than we do.
+
+## Testing
+
+Brut provides support for three types of tests:
+
+* Unit Tests, using RSpec
+* End-to-end tests, using RSpec and Playwright
+* Custom Element tests, written in JavaScript, using Mocha
+
+Since Brut is based on classes, objects, and methods, your unit tests will usually
+be straightforward, however Brut provides helpers to test your Page and Component
+HTML using Nokogiri.  FactoryBot is included and configured to manage test data.
+
+## Tasks
+
+Brut doesn't use Rake tasks. It uses CLI apps powered by Ruby's `OptionParser`.  Brut provides bootstrapping classes to make your own CLIs, as well as some light abstractions to make `OptionParser` a little more ergonomic.  Brut's dev and production management CLIs are built using this support.
+
+## Observability
+
+Brut has built-in support for [OpenTelemetry](https://opentelemetry.io/).  Brut includes configuration for the [otel-desktop-viewer](https://github.com/CtrlSpice/otel-desktop-viewer) or a text-based viewer suitable for development.  For production, most observability vendors provide OpenTelemetry ingestion any many have free tiers.
+
+Brut does support logging, however you are encouraged to use OpenTelemetry instead.
+