brut 0.0.20 → 0.0.22

data/brutrb.com/configuration.md

@@ -0,0 +1,257 @@
+# 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 setting your own custom class for managing 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.
+
+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

@@ -0,0 +1,103 @@
+# 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"`.
+
+```javascript
+@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 "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).
+
+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.

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

@@ -0,0 +1,149 @@
+# Testing Custom Elements
+
+While simple custom elements can be tested as part of an [end-to-end test](/end-to-end-tests), more
+complex custom elements can benefit from a unit test.  Spoiler: this is not going to be pleasant.
+
+## Overview
+
+BrutJS provides a testing module that uses JSDom to allow you to test your custom elements.  There are
+downsides to JSDom, but it's the simplest way to achieve a reasonably-useful unit test.
+
+You can use `bin/scaffold` to create a test, which will create a `.spec.js` file in `specs/front_end/js/`.
+Suppose we the custom element `MyElement`:
+
+```
+> bin/scaffold custom_element_test app/src/front_end/js/MyElement.js
+```
+
+This creates `specs/front_end/js/MyElement.spec.js`:
+
+```javascript
+import { withHTML } from "brut-js/testing/index.js"
+
+describe("<some-element>", () => {
+  withHTML(`
+  <my-element>
+  </my-element>
+  `).test("description here", ({document,window,assert}) => {
+    assert.fail("test goes here")
+  })
+})
+```
+
+`withHTML` creates a JSDom-based document with the given HTML. This HTML is in effect inside the test.
+Mock versions of `document` and `window` are passed to the test, and any other functions you need can be
+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.
+
+This means you'll need three tests, each with a different DOM:
+
+```javascript
+import { withHTML } from "brut-js/testing/index.js"
+
+describe("<some-element>", () => {
+  withHTML(`
+  <my-element>
+    Some Text
+  </my-element>
+  `).test("lower-cases by default", ({document,window,assert}) => {
+    // TBD
+  })
+
+  withHTML(`
+  <my-element transform="lower">
+    Some Text
+  </my-element>
+  `).test("lower-cases explicitly", ({document,window,assert}) => {
+    // TBD
+  })
+
+  withHTML(`
+  <my-element transform="upper">
+    Some Text
+  </my-element>
+  `).test("upper-cases explicitly", ({document,window,assert}) => {
+    // TBD
+  })
+})
+```
+
+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:
+
+```javascript {9,10,18,19,27,28}
+import { withHTML } from "brut-js/testing/index.js"
+
+describe("<some-element>", () => {
+  withHTML(`
+  <my-element>
+    Some Text
+  </my-element>
+  `).test("lower-cases by default", ({document,window,assert}) => {
+    const element = document.querySelector("my-element")
+    assert.equal(element.textContent.trim(),"some text")
+  })
+
+  withHTML(`
+  <my-element transform="lower">
+    Some Text
+  </my-element>
+  `).test("lower-cases explicitly", ({document,window,assert}) => {
+    const element = document.querySelector("my-element")
+    assert.equal(element.textContent.trim(),"some text")
+  })
+
+  withHTML(`
+  <my-element transform="upper">
+    Some Text
+  </my-element>
+  `).test("upper-cases explicitly", ({document,window,assert}) => {
+    const element = document.querySelector("my-element")
+    assert.equal(element.textContent.trim(),"SOME TEXT")
+  })
+})
+```
+
+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
+single line of code.
+
+Note that all of these test run under NodeJS, which is different from a browser.  This means that code
+like `new InputEvent()` will succeed in returning an `InputEvent`, but said object is in no way the
+`InputEvent` you'd use in a browser. You must use `window.`:
+
+```javascript
+// does not work, but doesn't raise an error either
+input.dispatchEvent(new InputEvent("input", {}))        
+
+// works
+input.dispatchEvent(new window.InputEvent("input", {}))
+```
+
+## Recommended Practices
+
+The custom element test library is *very* basic.  Testing asychronous things like `fetch` is extremely
+difficult.  Your best bet is to use these tests for edge cases and error conditions.
+
+
+## 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 13, 2025_
+
+I will be honest with you, this part of Brut needs a lot of work and thinking-through.  It's way to
+DSL-tasitc for my tastes, but it does work for some needs.  JSDom is not ideal and requires a lot of hoops
+when using events or anything browsers support that it does not.
+
+This is highly likely to change.  My current thinking on addressing the need is to run the tests in a real
+browser and to make the test setup and code more like what you'd actually write when using these elements.