brut 0.17.0 → 0.18.0

data/brutrb.com/brut-js.md

@@ -1,128 +0,0 @@
-# BrutJS
-
-Brut includes the JavaScript library *BrutJS* which provides HTML custom elements that are useful for
-progressively enhancing your HTML.
-
-## Overview
-
-By default, your app is set up to use BrutJS.  This is done by defining all the custom elements it
-provides. Their source code is included in your JavaScript bundle, but they do not do anything until you
-use one of the custom elements.
-
-Here's what `app/src/front_end/js/index.js` looks like initially:
-
-```javascript
-import { BrutCustomElements } from "brut-js"
-
-document.addEventListener("DOMContentLoaded", () => {
-  BrutCustomElements.define()
-})
-``` 
-
-Further, `Brut::FrontEnd::Component` uses Phlex's `register_element` to register all the elements so you
-can use them at will in components or pages:
-
-```ruby
-def view_template
-  form do
-    input type: "text", name: "name"
-    brut_confirm_submit message: "Are you sure?" do
-      button { "Submit" }
-    end
-  end
-end
-```
-
-### Custom Elements
-
-The JSDoc for these elements' classes should provide complete documentation, however this is an overview
-of what each one does.
-
-| Element                      | Purpose |
-|---|---|
-| `<brut-ajax-submit>`         | Allows submitting a form via Ajax. Handles the use of `fetch` and all possible cases, but you still provide the logic for what to do with the response. |
-| `<brut-autosubmit>`          | Auto submits a form when a `<select>`'s option is chosen.        |
-| `<brut-confirmation-dialog>` | Enhances a `<dialog>` to make it easier to use as a generic confirmation with `<brut-confirm-submit>` |
-| `<brut-confirm-submit>`      | Uses `window.confirm` or your owned styled `<dialog>` to confirm a button click. |
-| `<brut-cv>`                  | Like `<brut-message>` but specific to constraint violations, namely having additional logic for subsituting the field name in the message. |
-| `<brut-cv-messages>`         | Wraps `<brut-cv>` elements related to a single form input.        |
-| `<brut-copy-to-clipboard>`   | Allows the button inside it to copy text from another element onto the clipboard.        |
-| `<brut-form>`                | Manages client-side constraint violation UX unified with the server-side, as well as a few quality-of-life improvements for client-side violations and styling. See [Forms](/forms#forms-and-constraint-violations).|
-| `<brut-i18n-translation>`    | Holds the translated value for a single key in the web site visitor's locale.        |
-| `<brut-locale-detection>`    | Sends an Ajax request to the server with the browser's reported locale and timezone.  See [space-time continuum](/space-time-continuum#getting-timezone-from-the-browser) for more details.        |
-| `<brut-message>`             | Shows a message using an [i18n](/i18n) key to dynamically pull a localized message for client-side constraint violations. |
-| `<brut-tabs>`                | Uses ARIA roles related to a tab control and implements it client-side. |
-| `<brut-toast>`               | Support for managing i18-capable [toast notifications](https://en.wikipedia.org/wiki/Pop-up_notification) |
-| `<brut-tracing>`             | Sends observability data back to the server to unify a server-side request with client-side tracing.|
-
-> [!NOTE]
-> BrutJS's elements were created only to solve specific issues in the apps Brut was initially used for.
-> It's hoped that more elements will be added to provide a more feature-complete set of primitives to
-> create client-side enhancements.
-
-### Creating Your Own Custom Elements
-
-BrutJS includes a base class, [`BaseCustomElement`](/brut-js/api/BaseCustomElement.html), you can use to
-create your own custom elements with a bit more help, but not too much.
-
-The documentation for `BaseCustomElement` has an example, but here are the features you get (noting that
-you aren't abandoning the web platform's API, merely gaining a few additional quality-of-life
-improvements):
-
-* The ability to add debugging statements that are disabled via markup, not commenting-out `console.log`
-* Per-attribute change callbacks so you don't have to create `attributeChangedCallback` as a giant `if/else` block.
-* Default implementations of `connectedCallback` and `attributeChangedCallback` that call the template method `update`, thus allowing your element to centralize its logic in one place, regardless of how a state change was triggered.
-* Static `define()` method that defines your element based on its static `tagName` field. This allows richer interaction of elements, as you can do e.g. `document.querySelector(SomeOtherElement.tagName)`  and better navigate changes to your code over time.
-
-If you are familiar with the API for autonomous custom elements, `BaseCustomElement` doesn't require
-learning much more.  What you know already will be leveraged.
-
-### Removing BrutJS
-
-To remove BrutJS from your app, modify `app/src/front_end/js/index.js` to remove the `import` and call to
-`define()`.  You can then remove it from your `package.json`.
-
-> [!NOTE]
-> If you remove it like this, several features will not work, including locale detection, client-side observability, and client-side form validation UX.
-
-## Recommnded Practices
-
-### Leaving BrutJS In Your App
-
-BrutJS provides useful tools unrelated to single-page apps, or reactivity, or
-whatever else you might be concerned with in your client-side code.  These features
-can work alongside whatever framework you want to use. Leave them in unless they are
-causing a specific problem.
-
-### You Probably Don't Need a Single-Page App
-
-Consider this decision tree from Alex Russell's [If Not React, Then
-What?](https://infrequently.org/2024/11/if-not-react-then-what/):
-
-![Tree showing an SPA decision](/images/spa.png)
-
-This is how Brut wants you to consider your app's architecture.  *Many* apps do not have long-running
-sessions where visitors make lots of updates to data.  Most so-called "CRUD" apps do not fall into this
-category. The visitor would be better served by a traditional app with server-side HTML generation and
-minimal interactivity.  Visitors would also be better served with progressively enhanced features instead
-of massive JS payloads that show white screens on low bandwidth/low performance devices.
-
-Thus, Brut recommends you design your app to work in a tranditional multi-page app sort of way, then
-*enhance* as needed using autonomous custom elements.
-
-You can, of course, bring in whatever framework you like and use that in the normal way.  BrutJS's custom
-elements should work with any framework.
-
-## Testing
-
-See [Testing Custom Elements](/custom-element-tests).
-
-## 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 15, 2025_
-
-None.

data/brutrb.com/business-logic.md

@@ -1,55 +0,0 @@
-# Business or Domain Logic
-
-Since business and domain logic is not required, nor encouraged, to go in your data models, where does it go?
-
-It can go anywhere you like - Brut is not currently prescriptive.
-
-## Overview
-
-It's recommended that you place classes in `app/src/back_end`.  Any directory created in there will be
-auto-loaded by Brut/Zeitwerk based on its rules.  This means that classes in any directory in `app/src/back_end`
-should not be namespaced.
-
-For example, if you have *commands* and *queries*, you may want them in `app/src/back_end/commands` and
-`app/src/back_end/queries`, respectively.  In this case, `NewOrganizationCommand` would go in
-`app/src/back_end/commands/new_organization_command.rb` and `AccountQuery` would go in
-`app/src/back_end/queries/account_query.rb`
-
-Or, you could could organize them into `app/src/back_end/business_logic/commands` and `app/src/back_end/business_logic/queries`.  In that case, `Commands::NewOrganization` would be expected in `app/src/back_end/business_logic/commands/new_organization.rb` and `Queries::Account` would be expected in `app/src/back_end/business_logic/queries/account.rb`.
-
-How you organize it is up to you.
-
-## Testing
-
-Tests can be written using RSpec in the usual way.  Spec files should be in
-`specs/back_end/path/to/class.spec.rb`.  Note that Brut expects Spec files to end in `.spec.rb` and *not*
-`_spec.rb`.
-
-There is nothing special about the tests for your domain logic. Write them however you need to.
-
-## Recomended Practices
-
-This could be an entire series of books.  The main recommendation is to take a light approach and don't
-immediately install complex frameworks or libraries unless you know you need them.
-
-Something somewhere in your business logic will need to interface with your front-end.  The simplest way to do
-that is to allow form objects to be passed into your back-end.  The second simplest way is to pass form values
-into your back-end.
-
-You are strongly discouraged from having your front-end locate data models and pass those to your back-end.  This
-can be done while prototyping and for fast iteration on a concept, but generally you do not want to query your
-database from your handlers or pages just to pass the results into a back-end class.
-
-Exposing data models to the front-end is generally OK, as that is sometimes what you need to do.
-
-## 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_
-
-Creating universal abstractions from business logic is difficult. Brut is unlikely to do this. If it does, it
-will be after much analysis of exsiting patterns and *only* if it helps avoid mistakes and increases developer
-throughput.

data/brutrb.com/cli.md

@@ -1,274 +0,0 @@
-# CLI and Tasks
-
-Your app will likely need command-line or non-browser-based tasks.  Outside of standard needs like running a dev server or managing the database, you will have app-specific needs, like transforming data or performing one-time bulk operations.
-
-In Brut, these are done as Ruby CLI apps, powered by the standard library's `OptionParser`.
-
-## Overview
-
-The various commands installed with your Brut app in `bin/` are powered by Brut's CLI support. You can use this support to create your own tasks.
-
-The main feature this provides is a consistent startup of your app's internals and configuration. This startup is almost exactly the same as the web app, so you can safely rely on connections to the database, the ability to queue jobs, or the behavior of your business logic. There's just no web server and no front-end.
-
-### Brut CLI User Interface
-
-All Brut CLI apps produce a user interface that should be familiar if you've used CLI apps that support subcommands, like `git`:
-
-```
-> git status
-> git checkout
-> git commit
-```
-
-Each Brut CLI invocation has six parts:
-
-* The executable, e.g. `bin/db`
-* *Global Options* which are strings that start witih one or two
-dashes and control the behavior of the entire app, e.g. `--log-level=debug` These are optional and there can be any number of them.
-* The subcommand, which is a single string indicating what actual
-function to perform, e.g. `rebuild` in `bin/db rebuild`
-* *Command Options* which are just like global options, but they
-come *after* the command and apply only to that command
-* Arguments, which are any strings left over after the *command
-options* are parsed.
-
-All of this is powered by Ruby's `OptionParser`, which results in a canonical, UNIX-like UI.
-
-```
-> bin/my_cli --global-option list --command-option arg1 arg2
-  \----+---/ \-------+-----/ \-+/ \--------+-----/ \---+---/
-       |             |         |           |           |
-   Executable        |         |           |           |
-                     |         |           |           |
-                Command        |           |           |
-                   Options     |                       |
-                               |           |           |
-                             Subcommand    |           |
-                                           |           |
-                                      Command          |
-                                        Options        |
-                                                       |
-                                                       |
-                                                    Arguments
-        
-```
-
-Brut CLI apps all respond to `-h` and `--help` to view the list of subcommands, global options, and any environment variables that affect the behavior.
-
-```
-> bin/db -h 
-bin/db [global options] commands [command options] [args]
-
-   Manage your database in development, test, and production
-
-GLOBAL OPTIONS
-
-    -h, --help                       Get help
-        --log-level=LEVEL            Set log level. Allowed values: debug, info, warn, error, fatal. Default 'fatal'
-        --verbose                    Set log level to 'debug', which will produce maximum output
-
-ENVIRONMENT VARIABLES
-
-    BRUT_CLI_RAISE_ON_ERROR - if set, shows backtrace on errors
-    LOG_LEVEL               - log level if --log-level or --verbose is omitted
-
-
-COMMANDS
-
-    help          - Get help on a command
-    create        - Create the database if it does not exist
-    drop          - Drop the database if it exists
-    migrate       - Apply any outstanding migrations to the database
-    new_migration - Create a new migration file
-    rebuild       - Drop, re-create, and run migrations, effecitvely rebuilding the entire database
-    seed          - Load seed data into the database
-    status        - Check the status of the database and migrations
-```
-
-Brut CLI apps also support the subcommand `help` which will show help on a given subcommand, including the command options and arguments.
-
-```
->  bin/db help rebuild
-Usage: bin/db [global options] rebuild [command options] 
-
-    Drop, re-create, and run migrations, effecitvely rebuilding the entire database
-
-GLOBAL OPTIONS
-
-    -h, --help                       Get help
-        --log-level=LEVEL            Set log level. Allowed values: debug, info, warn, error, fatal. Default 'fatal'
-        --verbose                    Set log level to 'debug', which will produce maximum output
-
-ENVIRONMENT VARIABLES
-
-    BRUT_CLI_RAISE_ON_ERROR - if set, shows backtrace on errors
-    LOG_LEVEL               - log level if --log-level or --verbose is omitted
-    RACK_ENV                - default project environment when --env is omitted
-
-
-COMMAND OPTIONS
-
-        --env=ENVIRONMENT            Project environment (default 'development')
-```
-
-All of this means that the bulk of CLI-specific code you will write is specifying these options and documentation, then deferring to your business logic.
-
-### Basic CLI
-
-Every CLI app is a class that extends `Brut::CLI::App`. This class should contain one inner class for each subcommand. Those classes should extend `Brut::CLI::App`.
-
-Inside your `Brut::CLI::App` class, you can call a few class methods to declare aspects of the UI. In particular, `opts` returns the `OptionParser` in play that you can use to declare global options.  Unlike `OptionParser`'s `on` method, Brut's does not require providing a block. Brut will store the runtime options in an object (see below).
-
-```ruby
-class MyAppCLI < Brut::CLI::App
-  description "My awesome command line app"
-
-  opts.on("--dry-run", "Only show what would happen; don't change anything")
-  opts.on("--status STATUS", "Set the status you'd like to see")
-end
-```
-
-This code means your app's global options are `--dry-run`, which will not accept an argument, and `--status` which *must* be given an argument.  The arguments to `on` are the same as those for Ruby's `OptionParser`.
-
-Declaring subcommands provides a similar API.  Let's say our app has a "status" subcommand, and a "run" subcommand.
-
-```ruby {7-11,13-16}
-class MyAppCLI < Brut::CLI::App
-  description "My awesome command line app"
-
-  opts.on("--dry-run", "Only show what would happen; don't change anything")
-  opts.on("--status STATUS", "Set the status you'd like to see")
-
-  class Status < Brut::CLI::Command
-    description "Show the status"
-    args "files to get the status of"
-    opts.on("-l", "--long", "Show long-format")
-  end
-
-  class Run < Brut::CLI::Command
-    description "Run any outstanding tasks"
-    opts.on("--exit-status STATUS", "Exit status on success")
-  end
-end
-```
-
-This enables commands like `bin/my_app status -l foo.txt bar.rb` or `bin/my_app status --exit-status=3`.
-
-The names are derived from the class name. You can override them by using `command_name` inside a command class.
-
-```ruby {2}
-class Run < Brut::CLI::Command
-  command_name "exec"
-  
-  # ...
-end
-```
-
-The only thing left is to specify what happens for each subcommand. To do that, implement `execute`.
-
-```ruby {6-8,15-17}
-class Status < Brut::CLI::Command
-  description "Show the status"
-  args "files to get the status of"
-  opts.on("-l", "--long", "Show long-format")
-
-  def execute
-    # ...
-  end
-end
-
-class Run < Brut::CLI::Command
-  description "Run any outstanding tasks"
-  opts.on("--exit-status STATUS", "Exit status on success")
-
-  def execute
-    # ...
-  end
-end
-```
-
-### Implementing `execute`
-
-Once `execute` is called, your app's internals will have been setup and bootstrapped. That means all your data models can access the database, and any other setup will have ocurred. Generally, `execute` can then have whatever code makes sense.
-
-That said, `execute` has access to a few values to understand the command line invocation and to support testing.
-
-* `#options` - the command options passed on the command line, as
-a `Brut::CLI::Options`
-* `#global_options` - the global options passed on the command line, as a `Brut::CLI::Options`
-* `#args` - the args passed on the command line, as an array of
-strings
-* `#out` - an IO you should use to print messages to the standard out.
-* `#err` - on IO you should use to print messages to the standard error.
-* `#system!` - the method you should use to spawn child processes.
-This is preferable to `Kernel.system` because the command executed will be logged, and your app will raise if the command fails.  This makes it more straightfoward to safely script other command line invocations.
-
-### Advanced Options
-
-The API documentation will show you other options for creating your CLI UI, but there are a few aspects to highlight.
-
-* Calling `configure_only!` in your app, will run your app's
-subcommands without starting up Brut. This is generally not needed, but can be useful if you want to do basic scripting without worrying about connecting to the database.
-* `default_command` can be used to specify the command to run if
-none is given.  `bin/test` uses this to run `bin/test run`.
-* `requires_project_env` can be used at the app or command level
-to indicate that `--env` is accepted on the command line to set the project environment for the code to run in. Omitting this means that the actual project env used when the app runs is undefined.
-* Use `env_var` to document environment variables your app will
-use that affect its behavior.
-
-### The file in `bin`
-
-Currently, Brut doesn't provide a way to create this file, but it's relatively straightforward.  It's almost entirely boilerplate except for your class:
-
-```ruby {9}
-#!/usr/bin/env ruby
-
-require "bundler"
-Bundler.require
-require "pathname"
-require "brut/cli/apps/db"
-
-exit Brut::CLI.app(
-      Brut::CLI::Apps::DB,
-      project_root: Pathname($0).dirname / ".."
-     )
-
-```
-
-## Testing
-
-Depending on how your CLI is impelmented, testing it may not be that beneficial.  If `execute` simply defers to your back-end, your tests of that back-end will generally suffice.
-
-That said, your command classes are normal Ruby classes, so you can test them in a conventional way.
-
-The initalizer of each command class looks like so:
-
-```ruby
-def initialize(
-  command_options:,
-  global_options:,
-  args:,
-  out:,
-  err:,
-  executor:
-)
-```
-
-`command_options` and `global_options` accept a `Brut::CLI::Options`, which can be created with a Hash to represent the parsed command line options.
-
-`args` is a list of Strings.  `out` and `err` are IOs, so you can use the standard library's `StringIO` to both capture the output and supress it from your test's standard output/error.
-
-`executor` is a `Brut::CLI::Executor`, which is a wrapper around the standard library's `Open3`.  You can mock this to set expectations on what child processes are launched and how they behave.
-
-## Recommended Practices
-
-`execute` should defer to classes in your back-end, ideally a single method of a single class.  Excessive logic or UI in your CLI will be hard to test and maintain.
-
-
-## 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 9, 2025_