brut 0.17.0 → 0.18.0

data/brutrb.com/hooks.md

@@ -1,176 +0,0 @@
-# Route Hooks
-
-Route hooks are similar to [Middleware](/middleware), but have a richer API and aren't as low-level. Route
-hooks can happen before a page or handler is called, or after.
-
-## Overview
-
-We've seen examples thusfar of using a route hook to place the authenticated user or account into the
-request context for later injection into pages or handlers. Brut uses route hooks for locale detection and for content security policies.
-
-At its core, a *before* hook is a class that extends `Brut::FrontEnd::RouteHook` and implements `before`
-and an *after* hook implements `after`.  Both `before` and `after` can be [injected](/keyword-injection) with request-time information.
-
-To register a hook, you'd call `before` or `after` in your `App`:
-
-```ruby
-class App < Brut::Framework::App
-
-  # ...
-
-  before :RequireAuthBeforeHook
-
-  # ...
-
-end
-```
-
-The value can be a string or symbol, but should not be the class itself, as this can mess with load order.
-
-Let's implement a realistic hook that checks for authenticated users.  Our hook will
-detect if a user is logged in. If not, we'll redirect to a login page. 
-
-Of course, the login page will need to be accessible without logging in.  We also
-don't want Brut-owned paths to require login, either.
-
-`before` will need access to the request context, session, Rack request, and Rack environment:
-
-
-```ruby
-# app/src/front_end/route_hooks/require_auth_before_hook.rb
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:,request:,env:)
-     # ...
-  end
-end
-```
-
-We'll use the Rack request's `path_info` to check for allowed routes.  Brut will set `"brut.owned_path"` in the Rack environment for any path that it owns. We can check that to allow access to those paths.
-
-```ruby {4-6}
-# app/src/front_end/route_hooks/require_auth_before_hook.rb
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:,request:,env:)
-    is_home_page       = request.path_info.match(/^\/?$/)
-    is_auth_route      = request.path_info.match?(/^\/auth\//)
-    is_brut_owned_path = env["brut.owned_path"]
-
-    # ...
-
-  end
-end
-```
-
-Now, we can use this local variables to figure out if the route requires a user to be logged-in:
-
-```ruby {8-10}
-# app/src/front_end/route_hooks/require_auth_before_hook.rb
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:,request:,env:)
-    is_home_page       = request.path_info.match(/^\/?$/)
-    is_auth_route      = request.path_info.match?(/^\/auth\//)
-    is_brut_owned_path = env["brut.owned_path"]
-
-    requires_login = !is_home_page  &&
-                     !is_auth_route && 
-                     !is_brut_owned_path
-
-    # ...
-
-  end
-end
-```
-
-Now, we'll check if someone *is* logged in. If they are, we'll set the `authenticated_account` in the request context.
-
-```ruby {12-15}
-# app/src/front_end/route_hooks/require_auth_before_hook.rb
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:,request:,env:)
-    is_home_page       = request.path_info.match(/^\/?$/)
-    is_auth_route      = request.path_info.match?(/^\/auth\//)
-    is_brut_owned_path = env["brut.owned_path"]
-
-    requires_login = !is_home_page  &&
-                     !is_auth_route && 
-                     !is_brut_owned_path
-
-    if session.logged_in?
-      request_context[:authenticated_account] = session.authenticated_account
-      requires_login = false
-    end
-
-    # ...
-
-  end
-end
-```
-
-Now, we can test if the visitor needs to log in before proceeding.  The return value of `before` controls
-what will happen, similar to how handlers work.
-
-
-* `URI` - the browser will be redirected to this URI. This can be done by using the `redirect_to` helper.
-* `Brut::FrontEnd::HttpStatus` - the request will be terminated with this status. This can be done using the `http_status` helper.
-* `false` - the request is terminated with a 500
-* `true` or `nil` - the request will continue to the next hook or to the route handler. You are encouraged to use the `continue` helper to more clearly indicate that the request will proceed.
-
-In our case, if the visitor requires a login, we'll `redirect_to` the `LoginPage`.  Otherwise, we'll
-`continue`.
-
-```ruby {17-21}
-# app/src/front_end/route_hooks/require_auth_before_hook.rb
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:,request:,env:)
-    is_home_page       = request.path_info.match(/^\/?$/)
-    is_auth_route      = request.path_info.match?(/^\/auth\//)
-    is_brut_owned_path = env["brut.owned_path"]
-
-    requires_login = !is_home_page  &&
-                     !is_auth_route && 
-                     !is_brut_owned_path
-
-    if session.logged_in?
-      request_context[:authenticated_account] = session.authenticated_account
-      requires_login = false
-    end
-
-    if requires_login
-      redirect_to(Auth::LoginPage)
-    else
-      continue
-    end
-
-  end
-end
-```
-
-## Testing
-
-Route hooks are normal classes, you could test them as you would a handler or other class.  This may be advisable for complex hooks, however it may be more realistic to test their behavior through end-to-end tests as this will ensure they are configured correctly in the context of the app.
-
-## Recommended Practices
-
-Route hooks and [page hooks](/pages#hooks) serve similar purposes, so logic in one can be placed in other
-other at your discretion.  We recommend you use route hooks for cross-cutting issues across the entire
-app, such as login checks or for adding context to a request.
-
-For page- or use-case-specific behavior, it may be better to put the logic in a page hook.
-
-## 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 12, 2025_
-
-Route hooks and Middlewares do not share implementations, however they are similar in concept.  These concepts may be unified in the future.
-
-Hooks are applied in `Brut::Framework::MCP` usiung Sinatra's hooks mechanism.  While
-Brut may not always be based on Sinatra, it is now. You should not rely on it.
-
-Lastly, there is some dissonance in how keyword injection works.  Pages and Handlers
-have initializer injection, while hooks use method injection.  This may change -
-Hooks may be re-designed to use initializer injection, and even changed so that
-before and after hooks have different base classes.

data/brutrb.com/i18n.md

@@ -1,190 +0,0 @@
-# Internationaliztion and Localization
-
-Brut uses Ruby's i18n gem to provide support for localization and internationalization.
-
-## Overview
-
-`Brut::I18n::BaseMethods` provides the core implementation of Brut's i18n support, and it largely wraps the `t`
-and `l` methods of the i18n gem.
-
-
-Consider this:
-
-```ruby
-t("my.key", foo: "Bar")
-```
-
-This will locate the string with the key `my.key` and return it, replacing `%{foo}` with `"Bar"`, if `%{foo}` is
-present in the string.
-
-The keys are located in files in `app/config/i18n`.  The directories there correspond to the locales your app
-supports, e.g .`app/config/i18n/en` would hold translations for English.
-
-The translation files themselves are 🎉**NOT YAML**🎊.  They are Ruby files.  By default, there are two files: `app/config/i18n/en/1_defaults.rb` and `app/config/i18n/en/2_app.rb` (noting that `/en/` is for English and other langauges are obviously supported).
-
-`1_defaults.rb` provides values for keys Brut may require or use, such as for front-end constraint violations.
-`2_app.rb` provides your app's keys. If this file contains the same keys as `1_defaults.rb`, your file's values
-will be used.
-
-The file is a giant Hash, so the key above might look like so:
-
-```ruby
-{
-  my: {
-    key: "Hello there %{foo}",
-  },
-}
-```
-
-### Enhancements
-
-Brut's `t` tries to balance predictability with flexibility. It will always try to tell you what keys it was
-checking when it cannot find a translation or what interpolated values were missing.
-
-#### Basic Usage
-
-Often, keys contain dynamic elements.  Rather that creating a key like `widget.status.#{widget.status}`, you can
-pass an array in and it'll be joined for you:
-
-```ruby
-t([ :widget, :status, widget.status ]) #=> widget.status.active e.g.
-```
-
-`t` can also take a block that will be evaluated and substituted into the `block` interpolation value:
-
-```ruby
-{
-  supportlink: "To contact support %{block}',
-}
-
-t(:supportlink) do
-  "<a href='https://support.example.com'>Contact Support</a>"
-end
-```
-
-See below for how this affects HTML generation.
-
-#### Page- and Component-specific Values
-
-If you call `t` inside `page_template`, or inside `view_template` of a [page private
-component](/components#page-private-components), you can simplify the key specification.
-
-```ruby
-t(:nevermind)
-```
-
-If this is used on, say, `NewWidgetPage`, Brut will try to locate the key `pages.NewWidgetPage.nevermind`.  This works on page private components as well.
-
-Inside a normal component, it works simliarly.  Suppose `FlashComponent` had this:
-
-```ruby
-if !flash
-  t(:default_message)
-end
-```
-
-This would locate `components.FlashComponent.default_message`.
-
-This saves some typing, but it can also assist refactoring. If you rename a page or component, calls to `t` will blow up, reminding you to move the translations inside `2_app.rb`.
-
-### HTML Escaping
-
-`Brut::I18n::BaseMethods` cannot be used directly.  One of three submodules must be used: `ForHTML`, `ForCLI`, or
-`ForBackend`.  This is to allow the `ForHTML` module to properly escape HTML.
-
-When a translation accepts a block, that block could be HTML and you would want that HTML be included in the
-page, un-escaped.  Brut achieves this by first using Phlex's `capture` method, then marking it as HTML safe using
-`safe`.
-
-Thus, as long as you aren't introducing injections in your translations file or source code, it is safe to do the following:
-
-```ruby
-def view_template
-  div do
-    raw(
-      t(page: :contact_support) do
-        a(href: "https://support.example.com") do
-          t(page: :support_link_name)
-        end
-      end
-    )
-  end
-end
-```
-
-The result of `t` is safe HTML, so you must use `raw` to avoid escaping it.
-
-In a CLI or back-end context, HTML escaping is not relevant and can actually create problems, so `ForCLI` and
-`ForBackend` no-op `safe` and `capture`.
-
-When using `ForHTML`, all interpolated values are HTML-escaped.  `ForCLI` and `ForBackend` are not.
-
-### Localizing Dates and Times
-
-`l` can be called and this defers to the Ruby I18n library.
-
-Date and time formats can be configured in the translation files.  `l` does not accept a full key for the format.
-It is created dynamically by the library, so you must take care in which one you use.  If you pass a `Date` into
-`l`, `date.formats.«format»` is used. If you pass a `Time` in, `time.formats.«format»` is used.
-
-The values of the formats are strings suitable for
-[`strftime`](https://www.man7.org/linux/man-pages/man3/strftime.3.html).  The site [strif.me](https://www.strfti.me/) can be helpful in conjuring the right value.
-
-Brut includes translations for various formats that you can inspect in `app/config/i18n/«lang»/1_defaults.rb`.
-
-### Displaying Dates and Times in HTML
-
-While `l` will return a string you can use anywhere, you are most likely going to show dates and times in HTML.
-For that, you should use a `<time>` element.  Brut provides `Brut::FrontEnd::Components::TimeTag` (remember that if you `include Brut::FrontEnd::Components`, it's a Phlex *kit* and thus you can use `TimeTag(...)` directly) to do this. It contains additional behavior to make friendly dates and times.
-
-* You can give it a `timestamp:` or `date:` to control which formatting style is used.
-* `skip_year_if_same`, if true, will omit the year from any format if the current year is the same as the year being displayed. This is true by default
-* `skip_dow_if_not_this_week`, if true, will omit the day of week if the date or time is more than 7 days in the past.  This is true by default.
-
-The way `skip_year_if_same` and `skip_dow_if_not_this_week` work is to append `no_year` and/or `no_dow` to
-existing format strings which are assumed to omit this elements.
-
-If you wish to create your own formats, you can add them as well.
-
-### Constraint Violations and Field Names
-
-The interpolated value `{field}` is special. It is assumed to be the name of a field in a constraint violation
-message, e.g. `"%{field} is required"`.  It is the only interpolated value that can be omitted without causing an
-error.
-
-If included, it will work as normal:
-
-```ruby
-t("cv.ss.required", field: "Email") # => Email is required
-```
-
-If omitted, the value of `"cv.this_field"` is used. This is included in `1_default.rb`, but if it's
-missing, Brut will raise.  Assuming the value is `"This field"`:
-
-```ruby
-t("cv.ss.required") # => This field is required
-```
-
-## Testing
-
-In tests, you can call `t` and `l` to examine values as needed. You may find the
-`have_i18n_string` matcher usefult to check generated HTML for I18n values (see `Brut::SpecSupport::Matchers::HaveI18nString`).
-
-> [!WARNING]
-> Brut hardcodes English for tests, which you may not want.  This will be addressed
-> in the future.
-
-## Recommended Practices
-
-None at this time, however Brut's I18n has not been battle-tested.
-
-
-## 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_
-
-None at this time.

data/brutrb.com/images/Makefile

@@ -1,10 +0,0 @@
-DOT_FILES = *.dot
-PNG_FILES = $(patsubst %.dot,%.png,$(DOT_FILES))
-
-%.png : %.dot
-	dot -Gdpi=300 -Tpng $< -o$@
-
-%.svg : %.dot
-	dot -Gdpi=300 -Tsvg $< -o$@
-
-all: $(PNG_FILES)

data/brutrb.com/images/dev-env-overview.dot

@@ -1,54 +0,0 @@
-digraph G {
-  rankdir="LR"
-  Node[fontname=Baskerville]
-  subgraph cluster_docker {
-    label="Docker Container"
-    labeljust=left
-    fontname=Avenir
-    Ruby
-    NodeJS
-    OS
-    Filesystem
-    BrutApp
-  }
-
-  subgraph cluster_host {
-    label="Your Computer"
-    labeljust=left
-    fontname=Avenir
-    ProjectFiles
-    Editor
-    VersionControl
-    Browser
-  } 
-  
-  subgraph cluster_postgres {
-      label="Postgres\l«Docker Container»"
-      labeljust=left
-      fontname=Avenir
-      Postgres
-  }
-  Filesystem[shape=tab label="File system"]
-  ProjectFiles[shape=tab label="Project Files"]
-  OS[shape=box]
-  NodeJS[shape=component]
-  Ruby[shape=component]
-  Editor[shape=Msquare]
-  VersionControl[shape=Msquare label="Version\nControl"]
-  Postgres[shape=cylinder]
-  BrutApp[shape=box3d]
-  Browser[shape="Msquare" label="Web\nBrowser"]
-  
-  BrutApp -> Ruby
-  BrutApp -> NodeJS
-  BrutApp -> Filesystem
-  BrutApp -> Postgres
-  
-  Filesystem -> ProjectFiles[ dir=both label="synced"]
-  Editor -> ProjectFiles
-  Ruby -> Filesystem
-  NodeJS -> Filesystem
-  OS -> Filesystem
-  VersionControl -> ProjectFiles
-  Browser -> BrutApp
-}

data/brutrb.com/images/dev-env-protocol.dot

@@ -1,37 +0,0 @@
-digraph G {
-
-  rankdir="LR"
-  nodesep=0.55
-  compound=true
-  
-  node[shape=box fontname=avenir]
-
-  Shutdown[label=<
-    <FONT face="avenir">Shutdown</FONT>
-    <br/>
-    <FONT face="Courier New">dx/stop</FONT>
-  >]
-  Build[label=<
-    <FONT face="avenir">Build</FONT>
-    <br/>
-    <FONT face="Courier New">dx/build</FONT>
-  >]
-  Start[label=<
-    <FONT face="avenir">Start</FONT>
-    <br/>
-    <FONT face="Courier New">dx/start</FONT>
-  >]
-  Exec[label=<
-    <FONT face="avenir">Execute</FONT>
-    <br/>
-    <FONT face="Courier New">dx/exec</FONT>
-  >]
-  DevCommands[label=<
-    <FONT face="avenir">Workspace</FONT>
-    <br/>
-    <FONT face="Courier New">bin/\*</FONT>
-  >]
-  Build -> Start -> Exec -> Shutdown
-  Exec -> DevCommands[style=dotted dir=none]
-  { rank=same; Exec; DevCommands }
-}

data/brutrb.com/images/spa.dot

@@ -1,19 +0,0 @@
-digraph G {
-
-  Node[fontname="Helvetica"]
-  Edge[fontname="Baskerville"]
-
-  ShouldBeSPA              -> SessionMoreThan10Minutes
-  SessionMoreThan10Minutes -> No [label="No"]
-  SessionMoreThan10Minutes -> TenUpdatesPrimaryData [label="Yes"]
-  TenUpdatesPrimaryData    -> No [label="No"]
-  TenUpdatesPrimaryData    -> Maybe [label="Yes"]
- 
-  ShouldBeSPA              [ shape=rect label="Should this App\nby a Single-Page-App (SPA)?"]
-  No                       [ shape=octagon]
-  Maybe                    [ shape=circle]
-  SessionMoreThan10Minutes [ shape=diamond label="Sessions last\nlonger than\n10 minutes?\n"]
-  TenUpdatesPrimaryData    [ shape=diamond label="More than 10\nupdates to primary\nuser data?"]
-  
-  { rank=same; SessionMoreThan10Minutes; No }
-}

data/brutrb.com/images/workspace-protocol.dot

@@ -1,44 +0,0 @@
-digraph G {
-
-  rankdir="LR"
-  nodesep=0.55
-  compound=true
-  node[shape=box fontname=avenir]
-
-  Setup[label=<
-    <FONT face="avenir">Setup</FONT>
-    <br/>
-    <FONT face="Courier New">bin/setup</FONT>
-  >]
-  Run[label=<
-    <FONT face="avenir">Run</FONT>
-    <br/>
-    <FONT face="Courier New">bin/dev</FONT>
-  >]
-  Test[label=<
-    <FONT face="avenir">Test</FONT>
-    <br/>
-    <FONT face="Courier New">bin/test</FONT>
-  >]
-  CI[label=<
-    <FONT face="avenir">Test</FONT>
-    <br/>
-    <FONT face="Courier New">bin/ci</FONT>
-  >]
-  Code[label=<
-    <FONT face="avenir">Code</FONT>
-    <br/>
-    <FONT face="Baskerville">Write Code</FONT>
-    <br/>
-    <FONT face="Courier New">bin/db</FONT>
-    <br/>
-    <FONT face="Courier New">bin/scaffold</FONT>
-  >]
-  Setup -> Run
-  Setup -> Code
-  Run   -> Code
-  Code  -> Test
-  Test  -> Code
-  Test  -> CI
-  { rank=same; Run; Code; }
-}

data/brutrb.com/index.md

@@ -1,34 +0,0 @@
----
-# https://vitepress.dev/reference/default-theme-home-page
-layout: home
-
-hero:
-  name: "Brut RB"
-  text: "Raw Ruby Web Apps"
-  tagline: Standards-based, No-nonsense, HTML-first, Low Ceremony
-  ximage:
-    src: /images/LogoTall.png
-    alt: "A Ruby gemstone embedded into a concrete, brutalist building"
-  actions:
-    - theme: brand
-      text: "Getting Started"
-      link: /getting-started
-    - theme: alt
-      text: Conceptual Overview
-      link: /overview
-
-xfeatures:
-  - title: Standards-Based
-    icon:  📄
-    details: "Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"
-  - title: Convention-Oriented
-    icon: 🎚️
-    details: "In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."
-  - title: Objects and Methods
-    icon: 💻
-    details: "Author classes to create objects on which to call methods. Nothing fancy."
-  - title: Builds on Community Libraries
-    icon: 🏘️
-    details: "Sequel, Phlex, I18n, RSpec. They do it best"
----
-![logo](/images/LogoStop.png)