brut 0.17.0 → 0.18.0

data/brutrb.com/recipes/custom-flash.md

@@ -1,51 +0,0 @@
-# Custom Flash Class
-
-If you want to have a more sophisticated [Flash](/flash-and-session), you can do
-this by overriding Brut's [configuration](/configuration).
-
-## Recipe
-
-First, create your new class in `app/support/app_flash.rb`. You can implement your
-new methods using `[]` and `[]=`.
-
-```ruby
-class AppFlash < Brut::FrontEnd::Flash
-  def debug  =   self[:debug]
-  def debug? = !!self.debug
-
-  def debug=(debug_message)
-    self[:debug] = debug_message
-  end
-end
-```
-
-Now, in `app/src/app.rb`'s initializer, use `Brut.container.override`:
-
-```ruby {6}
-class App < Brut::Framework::App
-  def initialize
-
-    # ...
-
-    Brut.container.override("flash_class",AppFlash)
-  end
-end
-```
-
-Now, any time you inject `flash:` into a component, it'll be an instance of
-`AppFlash`:
-
-```ruby
-class HomePage < AppPage
-  def initialize(flash:)
-    @flash = flash
-  end
-
-  def page_template
-    h1 { "Welcome!" }
-    if @flash.debug?
-      aside { @flash.debug }
-    end
-  end
-end
-```

data/brutrb.com/recipes/dev-env-secrets.md

@@ -1,87 +0,0 @@
-# Managing Secrets in the Dev Environment
-
-Often, you need API keys like GitHub or Heroku tokens in order to perform development tasks. These should not be checked into version
-control, however you can still manage them.
-
-## Feature - API Keys
-
-* Developers need do use the Heroku command-line app inside the dev container.
-* Develoeprs do not want to have to perform a daily, browser-based authentication via `heroku auth:login`
-
-### Recipe
-
-The file `dx/bash_customizations.local` is set up for exactly this.  It is not checked into version control (see your `.gitignore`), and it
-is included when the development environment is built.
-
-```bash
-# dx/bash_customizations.local
-HEROKU_API_KEY=xxxxxx
-```
-
-When you change this file, you must rebuild your dev environment:
-
-1. `Ctrl-C` wherever you ran `dx/start`
-2. `dx/build`
-3. `dx/start`
-4. `dx/exec bash`, then `bin/setup`, then continue where you left off
-
-#### How This Works
-
-Here is a snippet of how this works.  In the first `RUN` directlive, the non-root user is created. When that is completed, `~/.profile` and
-`~/.bashrc` are modified to source both `bash_customizations` (per-project customizations that should **not** contain secrets) and
-`bash_customizations.local`, which is the file we are discussing.
-
-After that, the files are copied into the image via the `COPY` directives.
-
-```dockerfile
-# Snippet from Dockerfile.dx
-RUN useradd --uid ${user_uid} --gid ${user_gid} --groups ${sadly_user_must_be_added_to_root}${docker_gid} --create-home --home-dir /home/appuser appuser && \
-    echo ". ~/.bash_customizations" >> /home/appuser/.profile && \
-    echo ". ~/.bash_customizations.local" >> /home/appuser/.profile && \
-    echo ". ~/.bash_customizations" >> /home/appuser/.bashrc && \
-    echo ". ~/.bash_customizations.local" >> /home/appuser/.bashrc
-
-COPY --chown=appuser:${user_gid} dx/show-help-in-app-container-then-wait.sh /home/appuser
-COPY --chown=appuser:${user_gid} dx/bash_customizations /home/appuser/.bash_customizations
-COPY --chown=appuser:${user_gid} dx/bash_customizations.local /home/appuser/.bash_customizations.local
-```
-
-> [!WARNING]
-> The resulting image **will** contain the secrets from `bash_customizations.local`, so it's
-> **very important** you never push that image to a regsitry.
-
-## Feature - SSH Keys
-
-* You need an SSH key in order to push to GitHub from the dev container
-* You do not want to creata new key every time
-
-### Recipe
-
-Ultimately, you want the SSH key to be copied into the container and set up as if you'd created the key there.  The recipe below is an
-example of how you could do this, and should demonstrate the various seams in Brut's dev environment to allow you to craft it how you like.
-
-1. Choose a directory in the project where each developer will store their keys. **This directory should be excluded from version control**
-
-   ```
-   mkdir dx/credentials
-   echo "/dx/credetials" >> .gitignore
-   ```
-
-2. Assuming you create an SSH key already, place `id_ed25519` (private key) and `id_ed25519.pub` (public key) into `dx/credentials`.
-3. Create `dx/credentials/known_hosts` using `id_ed25519.pub`:
-
-   ```
-   github.com ssh-ed25519 «key from id_ed25519.pub here»
-   ```
-4. Your dev container will have access to `dx/credentials` already, so you can use `bin/setup` to copy them to the right place. How
-   you do this depends on how complicated you want to get.  You can examine Brut's `bin/setup` to see how it manages it.  You will
-   see that ti uses `ssh-agent` to avoid requiring the passcode every time, and that it uses `chmod` to make sure the SSH
-   directories are the right permissions.
-
-> [!WARNING]
-> The resulting image **will** contain your SSH key, so it's
-> **very important** you never push that image to a regsitry.
-
-
-This recipe is scant on details, since each credential is highly specific. The key points to know are that you can store information in the
-project, but not checked in, then rely on that information being available to `bin/setup` inside the container.

data/brutrb.com/recipes/form-errors.md

@@ -1,148 +0,0 @@
-# Styling Form Errors
-
-Brut makes it as easy as possible to unify client-side and server-side constraint violation handling, including
-how you style those messages.
-
-## Requirements
-
-What you want:
-
-* When a form is rendered for the first time, there should be errors shown.
-* When a visitor interacts with a form before submissions, no errors are shown.
-* When the form is submitted, client-side constraint violations should be shown.
-* When JavaScript is circumvented and the form is submitted with client-side constraint violations, the form should be re-generated, showing those violations the same is if JavaScripts was *not* circumvented
-* When there are no client-side constraint violations, but there *are* server-side violations, the form should be re-generated, showing those violations the same is if JavaScripts was *not* circumvented
-
-This can be achieved through CSS.
-
-## Recipe
-
-### Create Pages and HTML
-
-First, create a form and handler:
-
-```
-bin/scaffold form /new_widget
-```
-
-Edit `app/src/front_end/forms/new_widget_form.rb`
-
-```ruby
-class NewWidgetForm < AppForm
-  input :name, minlength: 3
-  input :description
-end
-```
-
-Now, implement the handler in `app/src/front_end/handlers/new_widget_handler.rb` to check for client-side violations *and* require that the description have at
-least 5 words in it.
-
-```ruby
-class NewWidgetHandler < AppHandler
-  def initialize(form:)
-    @form = form
-  end
-
-  def handle
-    if @form.valid?
-      if @form.description.split(/\s+/).length < 5
-      @form.server_side_constraint_violation(
-        input_name: :description,
-        key: :not_enough_words
-      )
-    end
-
-    if @form.constraint_violations?
-      NewWidgetPage.new(form: @form)
-    else
-      redirect_to(HomePage)
-    end
-  end
-end
-```
-
-Add the new error message to `app/config/i18n/en/2_app.rb`
-
-```ruby {6}
-{
-  en: {
-    nevermind: "Nevermind",
-    cv: {
-      ss: {
-        not_enough_words: "%{field} must have at least %{minwords} words",
-      },
-      # ...
-```
-
-Now, build a minimal `NewWidgetPage`:
-
-```
-bin/scaffold page /new_widget`
-```
-
-We'll create the bare minimum in `app/src/front_end/pages/new_widget_page.rb`
-
-```ruby
-class NewWidgetPage < AppPage
-  def initialize(form: nil)
-    @form = form || NewWidgetForm.new
-  end
-
-  def page_template
-    brut_form do
-      FormTag(for: @form) do
-        label do
-          Inputs::InputTag(form: @form, input_name: :name)
-          ConstraintViolations(form: @form, input_name: :name)
-          span { "Name" }
-        end
-        label do
-          Inputs::TextareaTag(form: @form, input_name: :name)
-          ConstraintViolations(form: @form, input_name: :name)
-          span { "Description" }
-        end
-      end
-    end
-  end
-end
-```
-
-### Create CSS
-
-The most minimal CSS would be as followed, which you can place in `app/src/front_end/css/index.css`
-
-```css
-brut-cv {
-  display: none;
-}
-
-brut-form[submitted-invalid] brut-cv,
-brut-cv[server-generated] {
-  display: block;
-  color: red;
-}
-```
-
-This will show the messages in `<brut-cv>` *only* if:
-
-* Form submission was attempted (`submitted-invalid` would be set on `<brut-form>`)
-* The server generated via `ConstraintViolations` (only if the handler was triggered)
-
-Because more than one `<brut-cv>` could be generated or inserted, you may want to style the
-`<brut-cv-messages>` that contains them, but you only want it to show up if it has contents.
-
-You can't just do `brut-cv-messages:has(brut-cv)`, because your container would show up before the form
-submission was attempted.
-
-Here is what you want instead. This will put the error messages in a red box:
-
-```css
-brut-form[submitted-invalid] brut-cv-messages:has(brut-cv),
-brut-cv-messages:has(brut-cv[server-generated]) {
-  color: red;
-  background-color: pink;
-  border: solid thin red;
-  border-radius: 1rem;
-}
-```
-

data/brutrb.com/recipes/indexed-forms.md

@@ -1,149 +0,0 @@
-# Indexed Forms
-
-HTTP allows a form to have any number of elements with the same name.  HTTP will
-make all values available to you. Rack supports this, too, but not in a standard
-way.
-
-This recipe will show a form that has more than one set of text fields for the same
-conceptual field.
-
-## Feature
-
-Allow editing a single form that has 10 sets of name/quantity fields, in order to
-bulk create up to 10 widgets at a time.
-
-## Recipe
-
-We'll create a form, a handler, and a page to do this.
-
-### Creating a Form with Indexes
-
-First, we'll scaffold the form and handler:
-
-```
-bin/scaffold form /bulk_create_widgets
-```
-
-Next, we'll create the form in `app/src/front_end/forms/bulk_create_widgets_form.rb`
-This will look like a normal form except each field will have `array: true`, to
-indicate there will be an arbitrary number of these fields.  Since they are not all
-going to be required, we'll set `required: false`.
-
-When you specify `array:true`, the method created by `input` accepts an index as an
-argument. For example,  `form.name(3)` would retrieve the fourth name submitted.
-
-We'll also implement the method `each_widget` that will yield each name/quantity
-pair.  The reason Brut doesn't provide this is that your form could have non-array
-values as well, so there is no obvious implementation.
-
-Brut *does* provide an `_each` method for every array field. We can use that to
-iterate over however many values were submitted.
-
-```ruby
-class BulkCreateWidgetsForm < AppForm
-  input :name,                    array: true, required: false
-  input :quantity, type: :number, array: true, required: false,
-                                               min: 1
-
-  def each_widget(&block)
-    name_each do |name, index|
-      block.(name, self.quantity(index), index)
-    end
-  end
-end
-```
-
-### Processing a Form with Array Values
-
-When Brut sends this data to us, each field will be an array of values. We'll see
-how to generate the HTML for that in a moment.  Before that, let's implement the
-handler.
-
-We want to require a name and quantity if either is present.  If not, it's fine.
-When we detect a problem, we'll use the `index:` parameter on
-`server_side_constraint_violation` to indicate which index has the issue.
-
-```ruby
-# app/src/front_end/handlers/bulk_create_widgets_handledr.rb
-class BulkCreateWidgetsHandler < AppHandler
-  def initialize(form:)
-    @form = form
-  end
-
-  def handle
-    @form.each_widget(name, quantity, index)
-      name_blank     = name.to_s.strip == ""
-      quantity_blank = name.to_s.strip == ""
-      if name_blank && quantity_blank
-        # fine
-      elsif !name_blank && !quantity_blank
-        # fine
-      elsif name_blank
-        @form.server_side_constraint_violation(
-          input_name: :name,
-          key: :required_with_quantity,
-          index: index
-        )
-      else
-        @form.server_side_constraint_violation(
-          input_name: :quantity,
-          key: :required_with_name,
-          index: index
-        )
-      end
-    end
-    if @form.constraint_violations?
-      BulkCreateWidgetsPage.new(form: @form)
-    else
-      redirect_to(WidgetsPage)
-    end
-  end
-end
-```
-
-### Generating a Form with Array Values
-
-Whew!  Now, let's see our HTML for the form. Note the use
-of the `index:` parameter when creating the form elements.
-
-```ruby
-# app/src/front_end/pages/bulk_create_widgets_page.rb
-class BulkCreateWidgetsPage < AppPage
-
-  include Brut::FrontEnd::Components
-
-  def initialize(form:)
-    @form = form || BulkCreateWidgetsForm.new
-    @num_widgets = 10
-  end
-
-  def page_template
-    brut_form do
-      FormTag(for: @form) do
-        @num_widgets.each do |index|
-          label do
-            Inputs::TextField(form: @form, input_name: :name, index: index)
-            div { "Name #{index + 1}" }
-            ConstraintViolations(form: @form, input_name: :name, index: index)
-          end
-          label do
-            Inputs::TextField(form: @form, input_name: :quantity, index: index)
-            div { "Quantity for Widget #{index + 1}" }
-            ConstraintViolations(form: @form, input_name: :quantity, index: index)
-          end
-        end
-        button { "Save Widgets }
-      end
-    end
-  end
-end
-```
-
- Even if the form doesn't have 10 entries, the code above will create 10 pairs of
- fields.  If there are server-side constraint violations, they will be shown for the
- appropriate index. Lastly, Brut's components (like `TextField`) will use the Rack
- non-standard HTML for arrays of values. Instead of `name="quantity"`, Brut will
- render `name="quantity[]"`.
-
-
-

data/brutrb.com/recipes/migrations.md

@@ -1,210 +0,0 @@
-# Migration Example
-
-If you've not used [Sequel](https://sequel.jeremyevans.net/) before, this recipe will show you the basics of creating [migrations](https://sequel.jeremyevans.net/rdoc/files/doc/migration_rdoc.html),
-which are how the database schema is managed in Brut.
-
-## Feature
-
-* An accounts table will store an email and a deactivated date
-* A blog posts table will store a title and content, and be attributed to an
-account.
-
-## Recipe
-
-We'll create the migration, create data models, create and lint factories, then create seed data.
-
-### Create the Migration
-
-Create the migration file with `bin/db new_migration`:
-
-```
-> bin/db new_migration Accounts and Blog Posts
-[ bin/db ] Migration created:
-   app/src/back_end/data_models/migrations/20250711215310_Accounts-and-Blog-Posts.rb
-```
-
-> [!NOTE]
-> Your filename will be different, since it embeds a timestamp for when `bin/db new_migration` was run.
-
-Now, use Sequel's migrations API, keeping in mind [Brut's augmentations](/database-schema), to create our tables.
-
-Our tables will use [an external ids](/database-schema#external-ids).  Note that
-Brut will ensure both tables have primary keys and have `created_at` fields.
-
-```ruby
-# app/src/back_end/data_models/migrations/20250711215310_Accounts-and-Blog-Posts.rb
-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
-    
-    create_table :blog_posts,
-                  comment: "Posts on our amazing blog",
-                  external_id: true do
-
-      column :title, :text
-      column :content, :text
-
-      foreign_key :account_id, :accounts
-    end
-  end
-end
-```
-
-You can apply this migration with `bin/db migrate`:
-
-```
-bin/db migrate
-```
-
-> [!IMPORTANT]
-> This only applied migrations to the dev database.  `bin/ci` and `bin/test e2e`
-> will apply them to the test database, but you may need to do it yourself via
-> `bin/db migrate -e test`
-
-> [!NOTE]
-> There is no down migration. If you need to change and re-apply this before
-> you have promoted it to production, rebuild your dev database with `bin/db
-> rebuild`.  It will apply all migrations from a fresh, empty database.
-
-You can examine the tables with `psql`, via `bin/dbconsole`:
-
-```
-> bin/dbconsole
-development=# \d accounts
-                                       Table "public.accounts"
-     Column     |           Type           | Collation | Nullable |             Default              
-----------------+--------------------------+-----------+----------+----------------------------------
- id             | integer                  |           | not null | generated by default as identity
- email          | text                     |           | not null | 
- deactivated_at | timestamp with time zone |           |          | 
- created_at     | timestamp with time zone |           | not null | 
- external_id    | citext                   |           | not null | 
-Indexes:
-    "accounts_pkey" PRIMARY KEY, btree (id)
-    "accounts_email_key" UNIQUE CONSTRAINT, btree (email)
-    "accounts_external_id_key" UNIQUE CONSTRAINT, btree (external_id)
-Referenced by:
-    TABLE "blog_posts" CONSTRAINT "blog_posts_account_id_fkey" FOREIGN KEY (account_id) REFERENCES accounts(id)
-
-development=# \d blog_posts
-                                    Table "public.blog_posts"
-   Column    |           Type           | Collation | Nullable |             Default              
--------------+--------------------------+-----------+----------+----------------------------------
- id          | integer                  |           | not null | generated by default as identity
- title       | text                     |           | not null | 
- content     | text                     |           | not null | 
- account_id  | integer                  |           | not null | 
- created_at  | timestamp with time zone |           | not null | 
- external_id | citext                   |           | not null | 
-Indexes:
-    "blog_posts_pkey" PRIMARY KEY, btree (id)
-    "blog_posts_account_id_index" btree (account_id)
-    "blog_posts_external_id_key" UNIQUE CONSTRAINT, btree (external_id)
-Foreign-key constraints:
-    "blog_posts_account_id_fkey" FOREIGN KEY (account_id) REFERENCES accounts(id)
-```
-
-Note that all columns are `NOT NULL` except `deactivated_at`, which we explicitly
-set as nullable.  Note that the foreign key on `account_id` has an index and is
-non-nullable.  And note that both tables have `external_id` and `created_at`
-columns. Brut will manage their contents.
-
-### Create Data Models
-
-Brut doesn't create your data models for you, since it assumes you prefer writing
-code in your editor and not on the command line.  Your data models will initially be
-pretty short.
-
-```ruby
-# app/src/back_end/data_models/db/account.rb
-class DB::Account < AppDataModel
-  has_external_id :ac
-  one_to_many :blog_posts
-end
-
-# app/src/back_end/data_models/db/blog_post.rb
-class DB::BlogPost < AppDataModel
-  many_to_one :account
-end
-```
-
-You can run `bin/console` to try to test these, but it's easier to create factories
-and use the `specs/lint_factories.spec.rb` to do that for us.
-
-### Create Factories
-
-Factories go in `specs/factories/db` and have a `.factory.db` suffix:
-
-```ruby
-# specs/factories/db/account.factory.rb
-FactoryBot.define do
-  factory :account, class: "DB::Account" do
-    email         { Faker::Internet.unique.email }
-
-    trait :inactive do
-      deactivated_at { Time.now }
-    end
-  end
-end
-
-# specs/factories/db/blog_post.factory.rb
-FactoryBot.define do
-  factory :blog_post, class: "DB::BlogPost" do
-    title { Faker::Lorem.sentence }
-    content { Faker::Lorem.paragraphs.join("\n\n") }
-
-    account
-  end
-end
-```
-
-Note that the blog post factory creates an account.  This is so that
-`create(:blog_post)` will always succeeed in creating valid data.
-
-To prove it, we'll lint our factories:
-
-```
-bin/test run specs/lint_factories.spec.rb
-```
-
-This will create every combination of every factory and fail if doing so raises an
-error.
-
-### Create Seed Data
-
-Now, we'll set up seed data.  `mkbrut` should've created
-`app/src/back_end/data_models/seed/seed_data.rb`, so we'll use that.
-
-```ruby
-require "brut/back_end/seed_data"
-class SeedData < Brut::BackEnd::SeedData
-  include FactoryBot::Syntax::Methods
-  def seed!
-    pat   = create(:account,            email: "pat@example.com")
-    chris = create(:account, :inactive, email: "chris@example.com")
-
-    5.times do
-      create(:blog_post, account: pat)
-      create(:blog_post, account: chris)
-    end
-  end
-end
-```
-
-We can apply this with `bin/db seed`:
-
-```
-bin/db seed
-```
-
-> [!IMPORTANT]
-> `bin/db rebuild` will *not* apply seed data, however `bin/setup` should.
-> For now, if you want to totally reset your database, you will need to do `bin/db
-> rebuild && bin/db seed && bin/db rebuild -e test`