brut 0.17.0 → 0.18.0

data/brutrb.com/components.md

@@ -1,265 +0,0 @@
-# Components
-
-Components in Brut are Phlex Components: a class that can hold data and use that to generate HTML.  Components are the primary way you achieve re-use of markup or view logic.
-
-## Overview
-
-`Brut::FrontEnd::Component` inherits from `Phlex::HTML`, which means that to create a component you must do three things:
-
-1. Create a class in `app/src/front_end/components` that inherites from `AppComponent` (which is part of your app and inherits from `Brut::FrontEnd::Component`)
-2. Implement an initializer that receives anything your component needs to do its job.  It is recommended (but not required) that your initializer use only keyword arguments.
-3. Implement `view_template` in which you make calls to Phlex' API.
-
-### Simple Component
-
-
-For example, suppose you want a re-usable button that can be gray, green, or red, and have an optional `formaction`.
-
-
-You can create a component with `bin/scaffold component`:
-
-```
-bin/scaffold component button
-# => app/src/front_end/components/button_component.rb
-# => specs/front_end/components/button_component.spec.rb
-```
-
-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_component.rb
-class ButtonComponent < AppComponent
-  def initialize(color: :gray,
-                 formaction: nil)
-    @color      = color
-    @formaction = formaction
-  end
-end
-```
-
-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_component.rb
-class ButtonComponent < AppComponent
-
-  # ...
-
-  def view_template
-    attributes = {
-      class: [
-        "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
-    }
-
-    button(**attributes) do
-      yield
-    end
-  end
-end
-```
-
-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>
-```
-
-:::
-
-::: code-group
-
-```ruby
-render ButtonComponent(color: :red, formaction: DeleteWidget.routing) do
-  "Delete Widget"
-end
-```
-
-```html
-<button class="tc br-3 bn f-3 ph-4 pv-2 bg-red-800 green-300"
-        formaction="/delete_widget">
-  Delete Widget
-<button>
-```
-:::
-
-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
-
-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.
-
-This provides a partial solution to so-called "prop drilling".
-
-In [the features overview](/features), we saw a basic component for rendering a
-flash:
-
-```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
-```
-
-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
-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
-> be created explicitly by the page or component. You cannot have a component
-> receive request-level keyword injection for some parameters with the page
-> providing the rest.
-
-Components can also be scoped to a page.
-
-### Page Private Components
-
-Often, components are helpful to simplifying a page's template or managing re-use within a page, but such a component isn't designed for use outside that page.  For example, if the page renders a table, but the logic for each row is complex, you may want that in a separate component, even though it would be useless outside the page.
-
-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.
-
-They can be created with `bin/scaffold`:
-
-```
-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
-    h1 { "Check out these Widgets!" }
-    end
-    main do
-      ul do
-        DB::Widget.all.each do |widget|
-          render(HomePage::WidgetListItem.new(widget:))
-        end
-      end
-    end
-  end
-end
-```
-
-```ruby [Page Private Component]
-class HomePage::WidgetListItem < AppComponent
-  def initialize(widget:)
-    @widget = widget
-  end
-
-  def view_template
-    li do
-      h2 { @widget.name }
-      p { @widget.description }
-    end
-  end
-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:
-
-```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.
-
-## Recommended Practices
-
-The [recommended practices for pages](/pages#recommended-practices) all apply to components, too.
-
-Beyond that, components are intended to be lightweight, so use them liberally.  Any page or component that has complex markup can be extracted to another component and more easily unit-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 5, 2025_
-
-As mentioned, components are Phlex components, but have various helpers mixed-into them.  Components are currently tightly coupled to Phlex and there is no plan to allow alternate implementations of view logic that isn't supported by Phlex.

data/brutrb.com/configuration.md

@@ -1,256 +0,0 @@
-# Configuration
-
-Brut strives to avoid configuration and flexibility.  Much of Brut's behavior is convention-based, however
-several aspects of Brut's behavior relate to literal values like file paths.  Some of this set up is designed to
-be overridden.
-
-## Overview
-
-Any configured value, or value otherwise intended to be abstracted from its literal value, is available via
-`Brut.container`, which returns an instance of `Brut::Framework::Container`.  This class uses `method_missing` to
-provide direct access to configured values. It can also be used to store or override configured values.
-
-An instance of `Brut::Framework::Config` is used to set up all of Brut's initial values.  This file is a good
-reference for determining the literal values of various configuration options.
-
-### Basics of Configuration
-
-The configuration system can be used to set literal values, or lazily-derived values.  The method `store` is used
-for both purposes.  Lazy values are managed by calling `store` with a block.
-
-::: code-group
-
-```ruby [Storing Litral Values]
-Brut.container.store(
-  "database_url",
-  String,
-  "URL to the primary database"
-  ENV.fetch("DATABASE_URL")
-)
-```
-
-```ruby [Storing Lazy Values]
-Brut.container.store(
-  "database_url",
-  String,
-  "URL to the primary database"
-) do
-  # Only evaluated when Brut.container.database_url is called
-  ENV.fetch("DATABASE_URL")
-end
-```
-:::
-
-The configuration system also enables dependencies between values.  For example, the Sequel connection to the database requires the URL to the database.  Since `database_url` is configured seperately, `sequel_db_handle` depends on its value.  It declares this by declaring a block parameter with the same name as the configuration option, `database_url` in this case.
-
-```ruby
-Brut.container.store(
-  "sequel_db_handle",
-  Object,
-  "Handle to the database",
-) do |database_url|
-  Sequel.connect(database_url)
-end
-```
-
-When `Brut.container.sequel_db_handle` is called, the block is examined. Brut sees that it has a parameter named
-`"database_url"`, and will then call `Brut.container.database_url` to fetch the value and pass it in.
-
-This reduces repetition amongst the various configuration options.
-
-### Special Types of Configuration
-
-Brut's configuration system enforces some rules, and may enforce more in the future.  It's a strong desire that no
-Brut app even boot if the configuration is not usable.
-
-Many of Brut's configuration options are paths.  To avoid having to have a bunch of `.keep` files all over the
-plces, Brut allows storing an *ensured path*, which Brut will created when needed.
-
-```ruby
-Brut.container.store_ensured_path(
-  "images_src_dir",
-  "Path to where images are stored"
-) do |front_end_src_dir|
-  front_end_src_dir / "images"
-end
-```
-
-If your Brut app has no images at all, when `Brut.container.images_src_dir` is accessed, the path to where the
-images should go will be created.
-
-Some paths *must* exist in advance.  For those, `store_required_path` can be used. It throws an error if the path
-does not exist:
-
-```ruby
-Brut.container.store_required_path(
-  "pages_src_dir",
-  "Path to where page classes and templates are stored"
-) do |front_end_src_dir|
-  front_end_src_dir / "pages"
-end
-```
-
-### Type and Name Enforcement
-
-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`.
-
-Brut may add more constraints or conversions over time.
-
-### Overridable and `nil`able Values
-
-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 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(
-  "flash_class",
-  Class,
-  "Class to use to represent the Flash",
-  Brut::FrontEnd::Flash,
-  allow_app_override: true,
-)
-```
-
-Since `allow_app_override` is true, you can call `override` in your `App`:
-
-```ruby
-Brut.container.override("flash_class",AppFlash)
-```
-
-Calling `override` for parameters where `allow_app_override` is not true results in an error. Further, calling
-`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 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
-prefix.
-
-Here is how Brut sets this up by default:
-
-```ruby {5-7}
-Brut.container.store(
-  "external_id_prefix",
-  String,
-  "String to use as a prefix for external ids in tables using the external_id feature. Nil means the feature is disabled",
-  nil,
-  allow_app_override: true,
-  allow_nil: true,
-)
-```
-
-Brut defaults this to `nil`, meaning there is no external ID prefix to be used.  Apps can opt into this behavior
-by overriding the value:
-
-```ruby
-Brut.container.override("external_id_prefix","cc")
-```
-
-Conversly, apps can opt *out* of [Content Security Policy Reporting](/security). By default, Brut sets up its own
-reporting hook:
-
-```ruby
-Brut.container.store(
-  "csp_reporting_class",
-  Class,
-  "Route Hook to use for setting the Content-Security-Policy-Report-Only header",
-  Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts::ReportOnly,
-  allow_app_override: true,
-  allow_nil: true,
-)
-```
-
-If you don't want this, you can override it and set it to `nil`:
-
-```ruby
-Brut.container.override("csp_reporting_class",nil)
-```
-
-`allow_nil` is a good indicator that Brut can handle a `nil` value for that configuration parameter—it wouldn't
-allow it if couldn't.
-
-### Setting Your Own Configuration Values
-
-In your `App` class, you can call `store` as needed to setup configuration values relevant to your app.  For
-example, if you are using SendGrid to send emails, you may want to set the client up during startup:
-
-```ruby
-# app/src/app.rb
-class App < Brut::Framework::App
-
-  # ...
-
-  def initialize
-
-    # ...
-
-    Brut.container.store(
-      "send_grid_client",
-      SendGrid::API,
-      "SendGrid API Client",
-      SendGrid::API.new(api_key: ENV["SENDGRID_API_KEY"])
-    )
-
-    # ...
-
-  end
-end
-```
-
-Then, elsewhere in your app, you can call `Brut.container.send_grid_client` to access this object. Because
-`allow_nil` is not specified (and therefore false), your app can confidently rely on a value being returned.
-
-## Testing
-
-Do not test configuration.  Ideally, the configuration values for production are the same as for dev and test.
-If you really cannot use the production value for something in dev or test, you can have your value depend on
-`project_env`, which is a `Brut::Framework::ProjectEnvironment`:
-
-```ruby {4-10}
-Brut.container.store(
-  "send_grid_client",
-  SendGrid::API,
-  "SendGrid API Client") do |project_env|
-    if project_env.testing?
-      FakeSendGrid.new
-    else
-      SendGrid::API.new(api_key: ENV["SENDGRID_API_KEY"])
-    end
-  end
-end
-```
-
-## Recommended Practices
-
-Try to avoid project environment-specific behavior.  The less of that you have, the more confidence you will have
-that your app will boot in production.
-
-In genreal, configure custom parameters only when you want them to be a check on app startup.  For example, we
-don't want our app to even start if `SENDGRID_API_KEY` is not in the environment. If we defered instantiating
-`send_grid_client` until the first time we tried to send email, we wouldn't notice things were broken.
-
-Conversely, do not place every object you could ever imagine into the container.  `Brut::Framework::Container` is
-not intended as a fully armed and operational dependency injection container. Perhaps someday, but not today.
-
-Lastly, do not `store` or `override` outside of your `App` class' initializer. It will be confusing and
-`override` may not work as expected.
-
-## 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_
-
-`Brut::Framework::Config` is created and executed in the initializer of `Brut::Framework::MCP`, which happens
-before your `App`'s initializer is run.  This also happens when CLI apps run.  Brut tries very hard not to make
-network connections inside `Brut::Framework::Config#configure!` for just this reason.
-
-`Brut::Framework::Container` does not really check for circular dependeices, so please try to avoid making them.
-If this happens, there will be a stack overflow.

data/brutrb.com/css.md

@@ -1,103 +0,0 @@
-# CSS
-
-Brut provides basic bundling using [esbuild](https://esbuild.github.io/). You can organize your CSS across
-multiple files, and you can bring in third party CSS libraries, as long as they are available from NPM (though you can always just download `.css` files manually)
-
-## Managing Your App's CSS
-
-All your app's CSS lives in `app/src/front_end/css`, or in modules you bring in via `package.json`.  Brut
-will *bundle* all of that up into a single `.css` file that is served up with your app.  Brut does this by using
-esbuild, a stable and standardized tool for bundling CSS.
-
-The way esbuild works is to be given an *entry point* that requires, or transitively requires, all of your
-CSS by using the standard [`@import` directive](https://developer.mozilla.org/en-US/docs/Web/CSS/@import). `app/src/front_end/css/index.css` is the entry point for your app.
-
-> [!NOTE]
-> The reason to bundle CSS instead of allowing browsers to manage the `@import`
-> directives is to create a single download that is hashed for use with CDNs.  This simplifies 
-> deployment and ensures all your CSS is available everywhere.  The trade-off is that you cannot
-> easily fine-tune each page's CSS.
-
-Let's see an example.  Let's say you are using the "foobar-css" CSS framework, and have placed some of your CSS in `app/src/front_end/css/pages/HomePage.css`.
-
-First, `package.json` (in your app's root) would include `"foobar-css"`:
-
-```json {6}
-{
-  "name": "your-app",
-  "type": "module",
-  "license": "UNLICENSED",
-  "dependencies": {
-    "foobar-css": "^0.0.11"
-  },
-  "devDependencies": {
-    "chokidar-cli": "^3.0.0",
-    "esbuild": "^0.20.2",
-    "jsdom": "^25.0.1",
-    "mocha": "^10.7.3",
-    "playwright": "^1.50.1"
-  },
-}
-```
-
-Next, `app/src/front_end/css/index.css` would import both `"foobar-css"` and `"pages/HomePage.css"`.
-
-```css
-@import "foobar-css/everything.css";
-@import "pages/HomePage.css";
-```
-
-In the browser `@import` accepts any URL and will resolve it when the file is loaded.  In Brut, when bundled using esbuild, these strings are relative paths to files in either `node_modules/` or `app/src/front_end/css/`.  Unlike JavaScript imports, you don't need `"./"` to differentiate the two. Also unlike JavaScript imports, these must be the first lines of your `index.css` file or they will be ignored. All imports must come before any CSS.
-
-## Importing Third Party CSS
-
-Because there are so many ways to use NPM modules, it's not common to find reliable documentation on how to use a CSS library you bring in via NPM/`package.json`.
-
-The key to figuring out what to use with `@import` is that the value is relative to `node_modules` and should an actual filename, including path and extension. You can figure this out by looking inside `node_modules` after you've done `bin/setup` (or `npm install`).
-
-Suppose "foobar-css" has this directory structure:
-
-```
-node_modules/
-  foobar-css/
-    css/
-      foobar-all.css
-      foobar-thin.css
-```
-
-To use `foobar-thin.css`, you'd write this `@import` directive:
-
-```css
-@import "foobar-css/css/foobar-thin.css";
-```
-
-## Using Brut-CSS
-
-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)`.
-
-To remove it, remove this line from `index.css`
-
-```css
-@import "brut-css/brut.css"; /* [!code --] */
-@import "your/css/here.css";
-```
-
-## Using TailwindCSS
-
-TBD
-
-## 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 8, 2025_
-
-Currently, Brut only supports a single entry point and bundle.  This could be easily made more flexible if there
-is a desire to finely tweak the CSS loaded on specific pages.
-
-Brut also does not expose any esbuild configuration.  This could be provided in the future, but for now, it is
-hard-coded.