brut 0.12.1 → 0.14.0

data/brut-js/src/AjaxSubmit.js

@@ -9,7 +9,8 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  *
  * 1. When the button is clicked, the form's validity is checked. If it's not valid, nothing happens.
  * 2. If the form is valid, this element will be given the `requesting` attribute.
- * 3. The request will be initiated, set to abort after `request-timeout` ms (see below).
+ * 3. The request will be initiated, set to abort after `request-timeout` ms as well
+ *    as to abort on an externally-provided AbortSignal (see below).
  *    The data submitted will be the contents of `new FormData(form)`, along with the 
  *    name/value of the button that was clicked, if it has a name and value.
  * 4. If the request returns OK:
@@ -28,8 +29,7 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  *    - otherwise, the operation is aborted.
  * 7. If fetch throws an error, the operation is aborted.
  *
- * Aborting the operation will submit the form in the normal way, allowing the browser to deal with whatever the issue is. You can set
- * `log-request-errors` to introspect this process.
+ * ## 422 Responses
  *
  * For a 422 response (where `no-server-side-error-parsing` is *not* set),
  * this element assumes the response is `text/html` and contains one or more `<brut-cv>`
@@ -56,6 +56,20 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  *   - the response body will be `text/html`
  *   - the response body will contain one or more `<brut-cv>` elements
  *
+ * ## Aborting the `fetch` Request
+ *
+ * By default, the call to `fetch` will be aborted after the value of `request-timeout` ms (default is 5,000).
+ * When this happens, the **form is submitted through the browser** without Ajax.  This is currently
+ * not configurable.
+ *
+ * You *can* set an additional `AbortSignal` by setting the `abortSignal` property.  When this is done, then
+ * either a timeout or your custom abort will abort the request and **submit the form through the browser**.
+ *
+ * For your custom abort signal, you can prevent browser submission by providing a reason
+ * with the value `AjaxSubmit.doNotSubmitThroughBrowser`. This can be useful when you are debouncing
+ * requests. See the examples. You will also find it useful to set `log-request-errors` on the element
+ * so you can see what is happening.
+ *
  * @property {boolean} no-server-side-error-parsing - if set, the response body for a 422 will not be parsed and inserted into the DOM. Instead, the body will be part of the detail of the `brut:submitinvalid` event.
  * @property {number} request-timeout - number of ms that the entire operation is expected to complete within. Default is 5000
  * @property {number} submitted-lifetime - number of ms that "submitted" should remain on the element after the form has completed. Default is 2000
@@ -67,23 +81,29 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  * @fires brut:submitok Fired when the AJAX request initated by this returns OK and all processing has completed. The detail will include the *parsed document* of the HTML returned in the response.
  * @fires brut:submitinvalid Fired when the AJAX request initated by this returns a 422 and all logic around managing the reponse has completed. The detail will be null unless `no-server-side-error-parsing` is set, in which case it will be the parsed document of the HTML returned in the response.
  *
- * @example
+ * @example <caption>Typical use</caption>
  * <form action="/widgets" method="post">
  *   <input type="text" name="name">
  *
  *   <brut-ajax-submit>
  *     <button name="button" value="save">Save</button>
-*    </brut-ajax-submit>
+ *   </brut-ajax-submit>
  *   <brut-ajax-submit>
  *     <button name="button" value="analyze">Analyze</button>
-*    </brut-ajax-submit>
+ *   </brut-ajax-submit>
  * </form>
- *
  * <!-- When "Save" is clicked, "name" will have the value from the text field,
  *      and "button" will have the value "save".
  *      When "Analyze" is clicked, "name" will have the value from the text
  *      field, and "button" will have the value "analyze". -->
  *
+ * @example <caption>Using a custom abort signal</caption>
+ * const ajaxSubmit = document.querySelector("brut-ajax-submit")
+ * const controller = new AbortController()
+ * ajaxSubmit.abortSignal = controller.signal
+ * // later, when you want to abort the request
+ * controller.abort(AjaxSubmit.doNotSubmitThroughBrowser)
+ *
  * @customelement brut-ajax-submit
  */
 class AjaxSubmit extends BaseCustomElement {
@@ -99,12 +119,28 @@ class AjaxSubmit extends BaseCustomElement {
     "no-server-side-error-parsing",
   ]
 
-  #requestErrorLogger = () => {}
-  #formSubmitDelay    = 0
-  #submittedLifetime  = 2000
-  #requestTimeout     = 5000
-  #maxRetryAttempts   = 25
+  /* Use this when calling abort() to indicate that the form 
+   * should be sub submitted through the browser.
+   */
+  static doNotSubmitThroughBrowser = "doNotSubmitThroughBrowser"
+
+  #requestErrorLogger     = () => {}
+  #formSubmitDelay        = 0
+  #submittedLifetime      = 2000
+  #requestTimeout         = 5000
+  #maxRetryAttempts       = 25
   #serverSideErrorParsing = true
+  #abortSignal            = null
+
+  /* Set an additional abort signal to be used when
+   * the form is submitted via Ajax.  This allows you to 
+   * control the fetch request beyond the built-in timeout.
+   *
+   * @param {AbortSignal} value the AbortSignal to add to the fetch request.
+   */
+  set abortSignal(value) {
+    this.#abortSignal = value
+  }
 
   constructor() {
     super()
@@ -205,18 +241,36 @@ class AjaxSubmit extends BaseCustomElement {
     }
     const urlSearchParams = new URLSearchParams(formData)
 
-    const timeoutSignal = AbortSignal.timeout(this.#requestTimeout)
+    const signals = [
+      AbortSignal.timeout(this.#requestTimeout),
+    ]
+    if (this.#abortSignal) {
+      signals.push(this.#abortSignal)
+    }
+    const abortSignals = AbortSignal.any(signals)
+
+    let url  = form.action
+    let body = null
+
+    if (form.method.toLowerCase() == "get") {
+      const sep = url.includes("?") ? "&" : "?"
+      url += sep + urlSearchParams.toString()
+    }
+    else {
+      body = urlSearchParams
+    }
 
     const request = new Request(
-      form.action,
+      url,
       {
         headers: headers,
         method: form.method,
-        body: urlSearchParams,
-        signal: timeoutSignal,
+        body: body,
+        signal: abortSignals,
       }
     )
 
+
     if (numAttempts > this.#maxRetryAttempts) {
       this.#requestErrorLogger("%d attempts. Giving up",numAttempts)
       this.#submitFormThroughBrowser(form)
@@ -273,8 +327,13 @@ class AjaxSubmit extends BaseCustomElement {
         }
       }
     }).catch( (error) => {
-      this.#requestErrorLogger("Got %o, which cannot be retried",error)
-      this.#submitFormThroughBrowser(form)
+      if (error == AjaxSubmit.doNotSubmitThroughBrowser) {
+        this.#requestErrorLogger("Error indicates we should not submit through browser: %o",error)
+      }
+      else {
+        this.#requestErrorLogger("Got %o, which cannot be retried",error)
+        this.#submitFormThroughBrowser(form)
+      }
     })
   }
 

data/brutrb.com/.vitepress/config.mjs

@@ -133,7 +133,6 @@ export default defineConfig({
           { text: "Styling Form Errors", link: "/recipes/form-errors" },
           { text: "Authentication", link: "/recipes/authentication" },
           { text: "Alternate Layouts", link: "/recipes/alternate-layouts" },
-          { text: "Blank Layouts", link: "/recipes/blank-layouts" },
           { text: "Custom Flash Class", link: "/recipes/custom-flash" },
           { text: "Indexed Form Elements", link: "/recipes/indexed-forms" },
           { text: "Text Field Component", link: "/recipes/text-field-component" },

data/brutrb.com/layouts.md

@@ -12,14 +12,16 @@ Your app should include `app/src/front_end/layouts/default_layout.rb`. The name
 A layout is a Phlex component that's expected to have a single call to `yield` in
 its `view_template` method.
 
+### Default Layout and Common Layout Needs
+
 Here is the `DefaultLayout` provided to new Brut apps:
 
 ```ruby {33}
 class DefaultLayout < Brut::FrontEnd::Layout
   include Brut::FrontEnd::Components
 
-  def initialize(page_name:)
-    @page_name = page_name
+  def initialize(page:)
+    @page = page
   end
 
   def view_template
@@ -34,7 +36,7 @@ class DefaultLayout < Brut::FrontEnd::Layout
         link(rel: "stylesheet",           href: asset_path("/css/styles.css"))
         script(defer: true, src: asset_path("/js/app.js"))
         title { app_name }
-        PageIdentifier(@page_name)
+        PageIdentifier(page)
         I18nTranslations("cv.cs")
         I18nTranslations("cv.this_field")
         Traceparent()
@@ -46,7 +48,7 @@ class DefaultLayout < Brut::FrontEnd::Layout
       end
       body do
         brut_tracing url: "/__brut/instrumentation", show_warnings: true
-        main class: @page_name do
+        main class: page.page_name do
           yield
         end
       end
@@ -65,8 +67,69 @@ included by default are important for other features of Brut:
 | `Brut::FrontEnd::Components::Traceparent` | Includes the OpenTelemetry *traceparent* on the page so that client-side telemetry is reported back to the server.  See `<brut-tracing>` and [observability](/instrumentation) |
 | `<brut-tracing>` / `brut_tracing` | Custom element that collects the client-side telemetry and sends it back to the server. See [observability](/instrumentation) |
 
-See [creating alternate layouts](/recipes/alternate-layouts) and [blank
-layouts](/recipes/blank-layouts) for customization options.
+### Adding Logic/Dynamic Behavior to Layouts
+
+Often, your pages will need to make slight tweaks to the layout that don't apply to all pages. For example, you may wish for a certain page to refresh on a schedule and you want to do that with a [meta refresh](https://en.wikipedia.org/wiki/Meta_refresh), which must appear in the `<head>` of the page.
+
+Unlike Rails, which uses named blocks to render optional or dynamic content, Brut allows you to use methods and normal Ruby-based flow logic.  Since your layouts have access to the page they are laying out, you can use your pages' APIs to do whatever it is you need.
+
+Taking the meta refresh example, suppose your `AppPage` defines a method, `auto_refresh_seconds` that, if non-`nil` means your page should automatically reload itself after that many seconds.  By default, you don't refresh, so it returns `nil`:
+
+```ruby
+class AppPage < Brut::FrontEnd::page
+
+  # ...
+
+  def auto_refresh_seconds = nil
+
+  # ...
+end
+```
+
+Your layout can refrence this API, since it's just a method on a class:
+
+```ruby
+class DefaultLayout < Brut::FrontEnd::Layout
+
+  # ...
+
+  def view_template
+    doctype
+    html(lang: "en") do
+      head do
+        if page.auto_refresh_seconds
+          meta(http_equiv: safe("refresh"), content: page.auto_refresh_seconds)
+        end
+
+        # ...
+  end
+  # ...
+end
+```
+
+Since your pages are a class hierarchy, you can override `auto_refresh_seconds` in any page, and that page will automatically refresh itself:
+
+```ruby
+class DashboardPage < AppPage
+
+  def auto_refresh_seconds = 60 * 60
+
+  # ...
+
+end
+```
+
+### Alternate Layouts
+
+If you used `mkbrut`, you should have access to a `BlankLayout` that is useful for allowing a page to respond to Ajax requests:
+
+```ruby
+class SomePage < AppPage
+  def layout = "blank"
+end
+```
+
+See [creating alternate layouts](/recipes/alternate-layouts) for more information on creating alternate layouts based on your needs.
 
 ## Testing
 
@@ -87,12 +150,7 @@ be [global components](/components#global-components)
 > 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 July 1, 2025_
+_Last Updated Sep 9, 2025_
 
 Layouts work due to the implementation of the method `view_template` in `Brut::FrontEnd::Page`. This is why a page class must provide `page_template` instead.
 
-While you could override `view_template` in your page to provide a "blank layout",
-this is discouraged, as the use of `view_template` should be considered a
-private implementation detail.
-
-