brut 0.0.28 → 0.1.0

data/brutrb.com/components.md

@@ -12,136 +12,159 @@ Components in Brut are Phlex Components: a class that can hold data and use that
 
 ### Simple Component
 
-For example, suppose you want a re-usable button component whose HTML would look like so:
 
-```html
-<button class="button button__small button__red">
-  Delete Files
-</button>
-```
+For example, suppose you want a re-usable button that can be gray, green, or red, and have an optional `formaction`.
 
-Your button can be large (the default) or small, and could be gray (default), green, or red.  Your button could also have an optional `formaction` attribute. Let's also suppose the label could be a string or embedded HTML.
 
-Your constructor would need to accept the size, color, label, and formaction.
-
-You can create a scaffold via `bin/scaffold`:
+You can create a component with `bin/scaffold component`:
 
 ```
-> bin/scaffold component Button
+bin/scaffold component button
+# => app/src/front_end/components/button_component.rb
+# => specs/front_end/components/button_component.spec.rb
 ```
 
-You'll first implement the initializer, like so:
+Component inititalizers are called by you when you use them, so you can define it
+how you like.  Brut uses keyword arguments by convention.
 
 ```ruby
-# app/src/front_end/components/button.rb
-class Button < AppComponent
-  def initialize(
-    size: :large,
-    color: :gray,
-    formaction: nil,
-    label: :use_block
-  )
-    @size       = size
+# app/src/front_end/components/button_component.rb
+class ButtonComponent < AppComponent
+  def initialize(color: :gray,
+                 formaction: nil)
     @color      = color
     @formaction = formaction
-    @label      = label
   end
 end
 ```
 
-This initializer is rather simplistic. You may want to validate the values here to prevent the construction of an invalid component.
-
-Now, implement `view_template`.  This method will receive a block if one is given when the component is used. We'll see an example in a minute.
+Since it's a Phlex component, implement `view_template` to generate the HTML you
+like.  Our `view_template` will `yield` so the button's contents can be controlled
+by the caller.  Note that the CSS here is [BrutCSS](/brut-css/index.html), but it
+can be anything you are using in your oapp.
 
 ```ruby
-# app/src/front_end/components/button.rb
-class Button < AppComponent
+# app/src/front_end/components/button_component.rb
+class ButtonComponent < AppComponent
 
   # ...
 
   def view_template
     attributes = {
       class: [
-        "button",
-        "button__#{@size}",
-        "button__#@{color}",
+        "tc",               # centered text
+        "br-3",             # border radius @ 3rd step of scale
+        "bn",               # no border
+        "f-3",              # font size @ 3rd step of scale
+        "ph-4",             # horizontal padding @ 4th step of scale
+        "pv-2",             # vertical padding @ 2nd step of scale
+        "bg-#{@color}-800", # background is second lighest of scale
+        "#{@color}-300",    # text is third darkest of scale
       ],
-      formaction: @formaction,
+      formaction: @formaction
     }
 
     button(**attributes) do
-      if @label == :use_block
-        yield
-      else
-        @label
-      end
+      yield
     end
   end
 end
 ```
 
-If you've never used Phlex before, it's refreshingly straightforward:
+Here are two examples of how you'd use this component and the HTML that would be
+generated:
+
+::: code-group
+
+```ruby
+render ButtonComponent(color: :green) do
+  "Click Here"
+end
+```
+
+```html
+<button class="tc br-3 bn f-3 ph-4 pv-2 bg-green-800 green-300">
+  Click Here
+<button>
+```
 
-* There's a method for each  HTML element.
-* The method's parameters produce attributes in the HTML that is generated.
-* If a parameter's value is an array (like `class:`), the values are joined with strings to form the atttribute's value in HTML.
-* If the element can have inner content, whatever happens inside a yielded block becomes that inner content.
+:::
 
-To use this component, we can call `render` in either the `view_template` of another component or the `page_template` of a [page](/pages):
+::: code-group
 
 ```ruby
-def view_template
-  form do
-    render Button.new(label: "Submit")
-    render Button.new(label: "Nevermind", size: :small, color: :red)
-    render Button.new(color: :green) do
-      img(src: "/images/ok.png", alt: "OK icon")
-    end
-  end
+render ButtonComponent(color: :red, formaction: DeleteWidget.routing) do
+  "Delete Widget"
 end
 ```
 
-Note that the block passed to `render` is the block available when `yield` is called inside `view_template`.
+```html
+<button class="tc br-3 bn f-3 ph-4 pv-2 bg-red-800 green-300"
+        formaction="/delete_widget">
+  Delete Widget
+<button>
+```
+:::
 
-There are two special types of components beyond what we have just seen.  *Global* Components and *Page private* components.
+One issue with components is that you must pass them all their initializer arguments
+to use them.  This means that if your component needs access to, say, the session,
+any page or component that uses your component must also require the session to
+be passed in.
+
+Brut provides a partial solution to this called *global components*.
 
 ### Global Components
 
-As we saw above, creating a component is just like creating any Ruby class: you call `.new` on it.  If you create a component that uses request-level data, such as the flash or session, it would mean that any page or component that used *that* component would need to accept the flash or session as a parameter to its initializer, even if it it was otherwise not needed.
+A global component can be created by Brut using [keyword
+injection](/keyword-injection). This means that, in our example above, a page that
+uses your component does not need to be given the session.  It can have Brut inject
+it.
 
-In those cases, `global_component` can be used to leverage [keyword injection](/keyword-injection) to have Brut create the component.  That way, its initializer's parameters don't need to be passed into the page or component using the global component.
+This provides a partial solution to so-called "prop drilling".
 
-Suppose we had a component to display the flash:
+In [the features overview](/features), we saw a basic component for rendering a
+flash:
 
 ```ruby
-class FlashMessage < AppComponent
-
+# components/flash_component.rb
+class FlashComponent < AppComponent
   def initialize(flash:)
-    @flash = 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 @flash.notice?
-      div(role: "status") { @flash.notice }
-    elsif @flash.alert?
-      div(role: "alert") { @flash.alert }
+    if any_message?
+      div(role: @role) do
+        t([ :flash, @message_key ])
+      end
     end
   end
 end
 ```
 
-To use it without having to instantiate it, call `global_component` with the component's class:
+Instead of requiring each user of this component to manually inject the flash, we
+can call `global_component`, provided by `Brut::FrontEnd::Component::Helpers`, which
+is included in all pages and components.
 
 ```ruby
-class HomePage < AppPage
-  def page_template
-    header do
-      global_component(FlashMessage) # note: render not required
-    end
+def view_template
+  header do
+    global_component(FlashComponent)
   end
 end
 ```
 
+Components used in layouts will tend to be global components, to avoid creating odd
+dependencies between pages.
+
 > [!IMPORTANT]
 > Brut currently requires an all-or-nothing approach to global components. Either 
 > the component can be injected with all its initializer parameters or it must
@@ -157,9 +180,19 @@ Often, components are helpful to simplifying a page's template or managing re-us
 
 Brut provides a way to create a *page private* component that exists as an inner class of a page.  It's not truly private, since it's still a Ruby class anyone can use, but it's form and source location communicate intent.
 
-Suppose our `HomePage` has a list of widgets on it, but we want each widget's HTML managed by a separate component:
+They can be created with `bin/scaffold`:
 
-```ruby
+```
+bin/scaffold component --page HomePage Widget
+# => app/src/front_end/page/home_page/widget_component.rb
+# => specs/front_end/page/home_page/widget_component.spec.rb
+```
+
+The class will be an inner class of `HomePage` in this example, `HomePage::WidgetComponent`. You build them and use them like normal:
+
+::: code-group
+
+```ruby [Page]
 class HomePage < AppPage
   def page_template
     header do
@@ -176,16 +209,7 @@ class HomePage < AppPage
 end
 ```
 
-`HomePage::WidgetListItem` can be created like so:
-
-```
-bin/scaffold component --page=HomePage WidgetListItem
-```
-
-This will create `app/src/front_end/pages/home_page/widget_list_item.rb`, which you can then implement like a normal component:
-
-```ruby
-# app/src/front_end/pages/home_page/widget_list_item.rb
+```ruby [Page Private Component]
 class HomePage::WidgetListItem < AppComponent
   def initialize(widget:)
     @widget = widget
@@ -200,27 +224,25 @@ class HomePage::WidgetListItem < AppComponent
 end
 ```
 
-The only special thing about a page private component is that it can access the page's I18n translations. As we'll discussion in [I18n](/i18n), The `t` method will try to locate translations based on the page on which `t` is called.  A page private component will also trigger this behavior, but a normal component will not.
-
-For example, the following code will look for `pages.HomePage.status.«status»` when generated the `<h3>`:
+:::
 
-```ruby {10}
-# app/src/front_end/pages/home_page/widget_list_item.rb
-class HomePage::WidgetListItem < AppComponent
-  def initialize(widget:)
-    @widget = widget
-  end
+The main difference between a page-private component and a normal component's
+behavior is how [I18n](/i18n) strings are resolved.  In short, given this:
 
-  def view_template
-    li do
-      h2 { @widget.name }
-      h3 { t([ :status, @widget.status ]) }
-      p { @widget.description }
-    end
-  end
+```ruby
+p do
+  t(:hello)
 end
 ```
 
+In a normal component named `WidgetComponent`, the keys searched for translations
+would be `"components.WidgetComponent.hello"` and `"hello"` .  For the page-private
+component `HomePage::WidgetComponent`, the keys searched would be
+`"pages.HomePage.hello"` and `"hello"`.  This means that page private components can
+access a page's translations.
+
+
+
 ## Testing
 
 Test widgets exactly as you would [pages](/pages#testing). The only difference is that components always render HTML and have no `before_generate` concept.

data/brutrb.com/configuration.md

@@ -92,7 +92,7 @@ end
 
 ### Type and Name Enforcement
 
-You'll note that `store`, accepts a class parameter.  This is mostly used for documentation, with two exceptions:
+You'll note that `store` accepts a class parameter.  This is mostly used for documentation, with two exceptions:
 
 * If the type is `Pathname` (which is what is used by `store_ensured_path` and `store_required_path`), the configuration parameter name *must* end in `_file` or `_dir`.
 * If the type is `"boolean"` or `:boolean`, the configuration parameter name *must* end in a question mark. In this case, the value itself is coerced into `true` or `false`.
@@ -103,8 +103,7 @@ Brut may add more constraints or conversions over time.
 
 By default, Brut configuration values cannot be overridden and they cannot be `nil`.  When calling `store`, `allow_app_override: true` and `allow_nil: true`, can be passed to change this behavior.
 
-In [Flash and Session](/flash-and-session), we discussed setting your own custom class for managing the flash.
-This is possible due to how Brut defines the configuration parameter `flash_class`:
+In [Flash and Session](/flash-and-session), we discussed that you can set your own class for the flash. This is possible due to how Brut defines the configuration parameter `flash_class`:
 
 ```ruby {6}
 Brut.container.store(
@@ -126,7 +125,7 @@ Calling `override` for parameters where `allow_app_override` is not true results
 `store` on a previously `store`-d parameter results in an error.
 
 The idea is to make it extremely clear what values are being set and overridden, and to avoid setting values that
-don't exist.
+don't exist or aren't relevant.
 
 Some values can be `nil`.  Generally, `nil` is a pain and will cause you great hardship.  On occasion, it's
 needed.  For example, [external IDs](/database-schema#external-ids) only work if the app provides an app-wide

data/brutrb.com/css.md

@@ -42,7 +42,7 @@ First, `package.json` (in your app's root) would include `"foobar-css"`:
 
 Next, `app/src/front_end/css/index.css` would import both `"foobar-css"` and `"pages/HomePage.css"`.
 
-```javascript
+```css
 @import "foobar-css/everything.css";
 @import "pages/HomePage.css";
 ```
@@ -73,7 +73,7 @@ To use `foobar-thin.css`, you'd write this `@import` directive:
 
 ## Using Brut-CSS
 
-By default, Brut includes a lightweight functional CSS library called "brut-css".  It provides a basic design system and single-purpose classes to allow you to quickly prototype or build UIs.  It is similar to TailwindCSS by far far smaller and simpler (and less powered).
+By default, Brut includes a lightweight functional CSS library called [BrutCSS](/brut-css/index.html).  It provides a basic design system and single-purpose classes to allow you to quickly prototype or build UIs.  It is similar to TailwindCSS but far far smaller and simpler (and less powered).
 
 It is included so you have something to start with. You can use it by using its various classes like `bg-green-300` and `m-4`, or you can use its provided custom properties like `var(--green-300)` and `var(--sp-4)`.
 

data/brutrb.com/custom-element-tests.md

@@ -37,8 +37,7 @@ as well, such as `assert`.
 The idea is that you use the browser APIs to examine the DOM and assert the behavior of the custom element
 (as opposed to interacting with the custom element's class).
 
-Suppose that `my-element` transform text inside it based on the `transform` attribute. By default, it's
-`lower`, but can be set to `upper` to lower case or upper case, respectively, the text inside.
+Suppose that `my-element` transform text inside it based on the `transform` attribute. By default, it's `lower` (which will lower-case the text), but can be set to `upper` to upper case the text inside.
 
 This means you'll need three tests, each with a different DOM:
 
@@ -72,7 +71,7 @@ describe("<some-element>", () => {
 })
 ```
 
-when the function you give to `test` is executed, the DOM will have been setup, so you can rely on your
+When the function you give to `test` is executed, the DOM will have been setup, so you can rely on your
 custom elements `connectedCallback` having been called.  Assuming the text transformation for `my-element`
 occurs in `connectedCallback`, here is how you'd test all three cases:
 
@@ -109,7 +108,7 @@ describe("<some-element>", () => {
 })
 ```
 
-You'll notice almost all of this uses the browser APIs you (should :) know and (hopefully :) love.
+You'll notice almost all of this uses the browser APIs you (should) know and (hopefully) love.
 
 You can manipulate the DOM inside a test as well, and it should behave as if you are doing it in a
 browser.  Note that many browser APIs are synchronous, so you don't have to add `await` before every

data/brutrb.com/database-access.md

@@ -156,7 +156,7 @@ end
 ### Do Not Put Business Logic On Your Database Models
 
 There's no reason to, or benefit to doing so.  What you'll find is that any app of even moderate complexity will
-not have a strict mapping from page to business concept to database table.  Rather these things will all differ
+not have a strict mapping from page to business concept to database table.  Rather, these things will all differ
 greatly, and each serves a different purpose.
 
 The job of your data models—and the tables they provide access to—is to store reliable and unambiguous data.

data/brutrb.com/database-schema.md

@@ -1,10 +1,6 @@
 # Database Schema / Migrations
 
-Brut provides access to the database via the [Sequel library](https://sequel.jeremyevans.net/).  Sequel is fully featured and provides a lot of ways of interacting with and managing your database.  Brut includes several plugins and extensions to provide opinionated default behavior or additional features.
-
-One thing to keep in mind is that Brut refers to your database layer as *database models* (notably not the un-qualified "models").  Brut treats this layer as a *model* of your database, not a model of your *domain* (though you are free to conflate the two).
-
-This section details how to manage your database schema.
+Brut provides access to the database via the [Sequel library](https://sequel.jeremyevans.net/).  To manage your database schema, Brut uses Sequel's facility for this, with some of its own enhancements.
 
 > [!NOTE]
 > Brut currently only supports Postgres. Sequel supports many database systems, however Brut's extensions are
@@ -12,22 +8,14 @@ This section details how to manage your database schema.
 
 ## Overview
 
-Brut uses *migrations* to control and manage the schema of your database. Migrations are changes to the
-schema that depend on the changes before them.  In a running production database, you will not be able to
-create the database schema from scratch—you will have to modify the existing schema to produce the schema
-you want.
+Your database schema is managed by a series of changes that build upon one another
+called *migrations*.
 
-For example, if you have a table `widgets` that has a `name` and `description`, to add a `status` field,
-you cannot `drop table widgets` and then `create table widgets(...)` with the fields. You must instead
-`alter table widgets(...)` to add the new column.
+For example, if you have a table `widgets` that has a `name` and `description`, to add a `status` field, you cannot `drop table widgets` and then `create table widgets(...)` with the fields. You must instead `alter table widgets(...)` to add the new column.
 
 Thus, each migration file is a change to the schema produced by all previous migration files. 
 
-Brut's provides this via Sequels. See [both](https://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html) [docs](https://sequel.jeremyevans.net/rdoc/files/doc/migration_rdoc.html) for details on the API.  Any schema modification method Sequel documents is available, however some default behavior has changed.
-
-Schema files are located in `app/src/back_end/data_models/migrations` and are named using a timestamp-based
-scheme.  This means that when you create a new migration, its name will be based on the time and date you
-created it, and any migrations that have not been applied will be applied in timestamp order.
+Brut's provides this via Sequel. See [both](https://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html) [docs](https://sequel.jeremyevans.net/rdoc/files/doc/migration_rdoc.html) for details on the API.  Any schema modification method Sequel documents is available, however some default behavior has changed.
 
 ### Creating Migrations
 
@@ -40,6 +28,10 @@ together to form the filename:
     app/src/back_end/data_models/migrations/20250508132646_user-accounts.rb
 ```
 
+Note that the files are located in `app/src/back_end/data_models/migrations` and
+have a name prefixed with a timestamp.  This timestamp determins an ordering of how
+the files are applied to the database.
+
 The file is created mostly blank:
 
 ```ruby
@@ -49,19 +41,17 @@ Sequel.migration do
 end
 ```
 
-Sequels' migration system is similar to Active Record's/Rails' in design and spirit, but the API is different.
-Please consult the documentation and don't assume Active Record's DSL will work. It will not.
+> [!NOTE]
+> Sequels' migration API is similar in concept to Rails', but differs
+> significantly in specifics. Please consult Sequel's documentation and
+> don't assume Railsism will work the same way.
 
-One thing to note is that Brut encourages the creation of only "up" migrations. That is, migrations that change a
-database. "Down" migrations, which revert a change, are discouraged.  See *Recommended Practices* for a detailed
-explanation.
+Brut encourages only "up" migrations.  Since Brut treats your development database
+as ephemeral, there is little value to managing "down" migrations.
 
-This is also why Sequel's `change` method is not included in the scaffolded code.  `change`, like Active Record's
-method of the same name, automagically creates both "up" and "down" migrations, but *only* if you use the DSL. If
-you use raw SQL, `change` doesn't work.  But that doesn't matter for Brut (again, see *Recommended Practices*).
+This is why Sequel's `change` method is not included in the scaffolded code.  `change`, like Active Record's method of the same name, automagically creates both "up" and "down" migrations, but *only* if you use the DSL. If you use raw SQL, `change` doesn't work. By using only `up`, you won't have to worry about this.
 
-Let's create a user accounts table that has an email field, a `deactivated_at` timestamp, and a `created_at`
-timestamp:
+Let's create an accounts table that has an email field, a `deactivated_at` timestamp, and a `created_at` timestamp:
 
 ```ruby
 Sequel.migration do
@@ -90,10 +80,6 @@ To apply this migration use `bin/db migrate`
 > bin/db migrate
 ```
 
-If you create a new migration, it will use a timestamp that is alphanumerically greater than the one we just made
-and thus that migration will be applied after this one.  Thus, you can rely on previous migrations having been
-applied when authoring new ones.
-
 ### Managing Migrations
 
 Sequel uses a special database table to understand which migrations have been run.  This table will exist in
@@ -126,16 +112,19 @@ provides a more helpful error message when no records are found
 #### External IDs
 
 It's often useful to provide a unique identifier for a record that is not the database primary key.  There are
-many advantages to doing so, but the core value Brut has regarding this is that database primary and foreign keys
-are considered private and internal and for developer use only.  It is trivial to produce externalizable keys, as
-you'll see, so there's no reason to expose primary keys.
+many advantages to doing so, the main being that your primary and foreign keys are
+considered private and for developer use only.  Creating additional externalizable
+unique keys is trivial, so Brut provides a way to do that.
 
 > [!NOTE]
-> Take care to differentiate the terms *primary key* and *key*.  In relational database literature, and thus
-> in Brut, a *key* is any value that uniquely identifies a record. `email` in the `accounts` table above
-> is a key.  The *primary key* is single source of truth for identifying records internally in the database.
-> Thus, it can be used as a *foreign key* to create relationships between tables.  Brut further implements
-> this as a *surrogate* or *synthetic* key, which means the value itself has  no business  or domain meaning.
+> **Primary keys** and **keys** are not the same thing.  **Primary keys** are
+> what is used to identify a record for the purposes of referential integrity.
+> A **key** simply uniquely identifies a row or is a unique constraint on a table.
+> Tables have only one primary key, but potentially many keys. Brut uses
+> *synthetic* (sometimes called *surrogate*) keys as primary keys.  This means
+> they have no business meaning and can be safely used for foreighn keys
+> and other cases without conflating them with domain concepts.
+
 
 In Brut, an external ID is automatically generated by the database when a record is created.  By convention, it
 is prefixed with a short string representing your app and a short string representing the table, followed by a
@@ -190,8 +179,7 @@ This means that you can set values explicitly if you like, *and* you can change
 
 ### Brut Migration Changes and Enhancement
 
-Brut attempts to set default behavior for migrations to encourage a modicum of best practices.  This lists out
-the changes and a brief explanation for the purpose of the change.
+Brut attempts to set default behavior for migrations to encourage a modicum of best practices.  These are:
 
 * **Automatic synthetic primary key named `id` of type `int`.**  You almost always want this. You can change the
 primary key configuration per table if you like, but if you do nothing, you get a primary key that works for 99%