brut 0.13.0 → 0.15.0

data/brut-js/src/Message.js

@@ -23,10 +23,16 @@ class Message extends BaseCustomElement {
     "key",
   ]
 
+  /*
+   * Creates a new `<brut-message>` element with the given attributes.
+   */
   static createElement(document,attributes) {
     const element = document.createElement(Message.tagName)
-    element.setAttribute("key",attributes.key)
-    element.setAttribute("show-warnings",attributes["show-warnings"])
+    Object.entries(attributes).forEach(([name,value]) => {
+      if (value !== null && value !== undefined) {
+        element.setAttribute(name,value)
+      }
+    })
     return element
   }
 
@@ -49,7 +55,7 @@ class Message extends BaseCustomElement {
       return
     }
 
-    this.textContent = RichString.fromString(translation.translation()).capitalize().toString()
+    this.textContent = RichString.fromString(translation.translation(), {allowBlank: true }).capitalize().toString()
   }
 }
 

data/brut-js/src/RichString.js

@@ -13,10 +13,13 @@ class RichString {
    *
    * @param {null|undefined|String|RichString} possiblyDefinedStringOrRichString - if `null`, `undefined`, or otherwise falsey, this method returns `null`. If a String, returns a new `RichString` wrapping it. If a `RichString`, returns the `RichString` unchanged.
    */
-  static fromString(possiblyDefinedStringOrRichString) {
+  static fromString(possiblyDefinedStringOrRichString, {allowBlank=false} = {}) {
     if (possiblyDefinedStringOrRichString instanceof RichString) {
       return possiblyDefinedStringOrRichString
     }
+    if (allowBlank && possiblyDefinedStringOrRichString === "") {
+      return new RichString("")
+    }
     if (!possiblyDefinedStringOrRichString) {
       return null
     }

data/brut-js/src/Toast.js

@@ -0,0 +1,102 @@
+import { BaseCustomElement, RichString, Message } from "brut-js"
+
+/**
+ * Support for a toast component, which is a momentary message shown to the user, for example
+ * if an aynchronous update has occured.
+ *
+ * To use this element, you should set up your CSS so that the element is hidden if there is no `key`
+ * attribute set.  When the `key` attribute *is* set, the element should be shown.  You can use CSS animations
+ * for this as needed, but the main thing to remember is that, without a `key` attribute, this element
+ * should not be visible.
+ *
+ * The `key` attribute is expected to be an i18n key that references a `<brut-i18n-message>` on
+ * the page, which contains the actual message to show the visitor.  When the `key` attribute is
+ * set, this component will find an `<output>` inside itself, and replace the entire contents
+ * with a `<brut-message>` component, using the same `key`.  This will cause the `<brut-message>`
+ * to look up the key and put that text into the element.
+ *
+ * In addition to this lookup, this element will set appropriate ARIA attributes on the
+ * created `<brut-message>` element.
+ *
+ * Further, if there is a `<button>` inside this element, it will be used to close the toast by removing the
+ * `key` attribute (which, assuming your CSS is correct, will hide the element).
+ *
+ * @property {string} key - an I18n key of the message to show in the toast.  When you generate
+ *                          the toast's HTML on the server, do not set key.  Then, when you need
+ *                          to display the toast, use JavaScript to set the key. This will
+ *                          trigger its behavior as described above.
+ *
+ * @example
+ * <style>
+ *   brut-toast {
+ *     display: none;
+ *   }
+ *   brut-toast[key] {
+ *     display: block;
+ *   }
+ * </style>
+ * <brut-i18n-translation key="toast.saved">Save successful</brut-i18n-translation>
+ * <brut-toast>
+ *   <div>
+ *   <output></output>
+ *   <button>Close</button>
+ *   </div>
+ * </brut-toast>
+ * <!-- now, if you set the key to "toast.saved", the HTML will be changed as follows: -->
+ * <brut-toast key="toast.saved">
+ *   <div>
+ *   <output>
+ *     <brut-message key="toast.saved" role="status" aria-live="polite" aria-atomic="true">
+ *       Save successful
+ *     </brut-message>
+ *   </output>
+ *   <button>Close</button>
+ *   </div>
+ * </brut-toast>
+ */
+class Toast extends BaseCustomElement {
+  static tagName = "brut-toast"
+
+  static observedAttributes = [
+    "show-warnings",
+    "key",
+  ]
+
+  #key = null
+  #closeListener = (event) => {
+    event.preventDefault()
+    this.removeAttribute("key")
+  }
+
+  keyChangedCallback({newValue}) {
+    this.#key = RichString.fromString(newValue)
+  }
+
+  update() {
+    const closeButton = this.querySelector("button")
+
+    if (closeButton) {
+      closeButton.addEventListener("click", this.#closeListener)
+    }
+
+    if (!this.#key) {
+      return
+    }
+    const output = this.querySelector("output")
+    if (!output) {
+      this.logger.warn("No <output> element found, so toast will not be displayed")
+      return
+    }
+    const messageNode = Message.createElement(document,{
+      "key": this.#key,
+      "role": "status",
+      "aria-live": "polite",
+      "aria-atomic": "true"
+    })
+    output.replaceChildren(messageNode)
+    this.style.animation = "none"
+    this.offsetWidth // Trigger reflow to restart the animation
+    this.style.animation = ""
+  }
+}
+export default Toast

data/brut-js/src/index.js

@@ -12,6 +12,7 @@ import LocaleDetection             from "./LocaleDetection"
 import Message                     from "./Message"
 import RichString                  from "./RichString"
 import Tabs                        from "./Tabs"
+import Toast                       from "./Toast"
 import Tracing                     from "./Tracing"
 
 /**
@@ -105,6 +106,7 @@ BrutCustomElements.addElementClasses(
   AjaxSubmit,
   ConstraintViolationMessage,
   Tabs,
+  Toast,
   LocaleDetection,
   Autosubmit,
   Tracing,
@@ -125,6 +127,7 @@ export {
   Message,
   RichString,
   Tabs,
+  Toast,
   Tracing
 }
 

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/brut-js.md

@@ -52,6 +52,7 @@ of what each one does.
 | `<brut-locale-detection>`    | Sends an Ajax request to the server with the browser's reported locale and timezone.  See [space-time continuum](/space-time-continuum#getting-timezone-from-the-browser) for more details.        |
 | `<brut-message>`             | Shows a message using an [i18n](/i18n) key to dynamically pull a localized message for client-side constraint violations. |
 | `<brut-tabs>`                | Uses ARIA roles related to a tab control and implements it client-side. |
+| `<brut-toast>`               | Support for managing i18-capable [toast notifications](https://en.wikipedia.org/wiki/Pop-up_notification) |
 | `<brut-tracing>`             | Sends observability data back to the server to unify a server-side request with client-side tracing.|
 
 > [!NOTE]

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.
-
-