flash_unified 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aea0348851ca5170244e807281bcefa783d5b800f54166546285ec46070d4f6b
-  data.tar.gz: 5d278c86617549ec9dad0e46b7c3167261d4f36dd1188baf81baf6ab9d536263
+  metadata.gz: 1ff9e758b822e2e06c38f1543fc5e2be3b4aa101879bdd1137ab70f01b0cc350
+  data.tar.gz: 1df992f44cd7c2db0992b4130d9047af5c7017a26e3367aa395597a884adbddb
 SHA512:
-  metadata.gz: dbcbe847be1227697340e8973f36e9d00cb823cf9acdcf530c7c5e580b3638f1ec746bad376072a905d3bc305b9a2acc26c96d1b5b71a1af0668725c33a9a7f5
-  data.tar.gz: a6459a4ae27cbaf5c2078e403d70b42f1cbfe631fedd82252f08522d028c6e726135e56128787a11cfeeddc13a11e5d5c89f4849b16691d9e89c5f4be9c4bddb
+  metadata.gz: 1f327a2f3b87d9974b81b1031f5d787cc6b3f03927398030e0e89fb39e8c0e94232cc6ec86195dbe6e56d53a1cb140d07bb5c52d803a34d1f7930c60584aeacc
+  data.tar.gz: fcd91ea10bdeccefc552f5c66e6c6e8e4ddc053acb4f3e638b1c3b8e04db51efd6463478464cc7e308e38bbc7db54fb266ccf21ee7df3782569ffe6664abc575

data/README.md

@@ -2,29 +2,28 @@
 
 FlashUnified provides a unified Flash message rendering mechanism for Rails applications that can be used from both server-side and client-side code.
 
-Server-side view helpers embed Flash messages as hidden DOM elements (`data-flash-storage`), and client-side JavaScript scans, formats, and renders them into containers. This enables consistent Flash UI for server messages, Turbo Frame responses, and client-detected errors (e.g., 413 proxy errors).
+Server-side view helpers embed Flash messages as data in the page, and a lightweight client-side JavaScript library reads those storages and renders messages into visible containers using templates.
 
 ## Current status
 
-This project is considered alpha up to v1.0.0. Public APIs are not stable and may change in future releases.
+This project is considered alpha through v1.0.0. Public APIs are not yet stable and may change in future releases.
 
 ## Motivation
 
-We faced two challenges simultaneously.
+We had two challenges at the same time.
 
-One is to be able to present client-originated messages using the same UI as server-side Flash messages. For example, when a large request is blocked by a proxy and a 413 error occurs, the client must handle it because the request does not reach the Rails server; nevertheless we want to display it using the same Flash UI logic.
+One was to display messages originating from the client-side with the same UI representation as Flash from the server-side. For example, when a large request is blocked by a proxy, we want to display a 413 error as a Flash message. Since the request never reaches the Rails server, this must be handled on the client-side, but we want to display it with the same UI logic as normal Flash.
 
-The other is to support showing Flash messages that originate from Turbo Frames. Displaying Flash inside a frame is straightforward, but in most cases you want to display them outside the frame.
+The other was to display Flash messages from Turbo Frames as well. It's not a problem if Flash is displayed within the frame, but in most cases it will be displayed outside the frame.
 
 ## How it works
 
-The key insight is that rendering must be done on the JavaScript side. We split responsibilities between server and client into two steps:
+The key point to solving these challenges is that rendering needs to be performed on the JavaScript side. Therefore, we devised a two-stage process that divides responsibilities between the server-side and client-side:
 
-1. The server embeds the Flash object into the page as hidden DOM elements and returns the rendered page.
-2. The client-side JavaScript detects page changes, scans those elements, reads the embedded messages, formats them using templates, and inserts them into the specified container element. After rendering, the message elements are removed from the DOM to avoid duplicate displays.
-
-This mechanism is simple; the main requirement is to define rules for how to embed data. This gem defines a DOM structure for the embedding, which we call "storage":
+1. The server embeds the Flash object as a hidden DOM element within the page, renders the page, and returns it.
+2. When the client-side JavaScript detects a page change, it scans those elements, reads the embedded messages, formats them using templates, and inserts (renders) them into the specified container elements. At that time, message elements are removed from the DOM to avoid duplicate displays.
 
+The mechanism is simple, and to implement it, we only need to decide on the rules for how to embed. In this gem, we define the embedded DOM structure as follows and call it "storage":
 ```erb
 <div data-flash-storage style="display: none;">
   <ul>
@@ -35,16 +34,13 @@ This mechanism is simple; the main requirement is to define rules for how to emb
 </div>
 ```
 
-Because storage is a hidden element, it can be placed anywhere in the rendered page. For Turbo Frames, place it inside the frame.
-
-The "container" (where Flash messages are displayed) and the "templates" used for formatting are independent of the storage location and can be placed anywhere. This means that even when storage is inside a Turbo Frame, the rendering can target a Flash display area outside the frame.
-
-For client-side handling of cases like proxy errors on form submission, instead of rendering an error message directly from JavaScript, embed the message into a container element first and let the same templates and processing flow render the Flash message.
+Since storage is a hidden element, it can be placed anywhere in the page rendered by the server. For Turbo Frames, place it inside the frame.
 
-### Controller example
+The "container" where Flash messages are displayed and the "templates" for formatting can be placed anywhere regardless of the storage. This means that even with Turbo Frames, it works with Flash rendering areas placed outside the frame.
 
-Controller-side procedures for setting Flash are unchanged:
+When handling cases on the client-side where a proxy returns an error when a form is submitted, instead of displaying the error message directly from JavaScript, you can render Flash in the same way (using the same templates and processing flow) by temporarily embedding the message as a storage element.
 
+On the other hand, in controllers that set Flash, there is no difference from the normal Flash message display procedure:
 ```ruby
 if @user.save
   redirect_to @user, notice: "Created successfully."
@@ -54,308 +50,71 @@ else
 end
 ```
 
-Introducing this gem does not require changes to existing controllers. There are almost no changes needed to existing page layouts either. The DOM elements to be set in views are hidden elements, and you'll mostly just need to slightly adjust the container area for Flash message display.
-
-The main implementation task when using this gem is determining when the embedded data should be rendered as Flash messages. Typically this is done with events. Specific handling is left to the implementer, but helpers for automatic event setup are also provided. You can also explicitly call display methods within arbitrary processing.
-
-## Main features
-
-This gem provides the mechanism organized according to defined rules and helper tools to support implementation.
+In other words, when introducing this gem, **no changes are required to existing controllers**. Also, there is almost no need to change existing page layouts. The DOM elements to be set in views are hidden elements, and you only need to slightly adjust the container area where Flash messages are displayed.
 
-Server-side:
-- View helpers that render DOM fragments expected by the client:
-  - Hidden storage elements for temporarily saving messages in the page
-  - Templates for the actual display elements
-  - A container element indicating where templates should be inserted
-- Localized messages for HTTP status (for advanced usage)
+The main thing to implement when introducing this gem is the timing to display embedded data as Flash messages. Normally, you will use events. While the specific implementation is left to the implementer, helpers are provided to automatically set up events. You can also explicitly call methods for display within arbitrary processes.
 
-Client-side:
-- A minimal library in `flash_unified.js` (ES Module). Configure via Importmap or the asset pipeline.
-- `auto.js` for automatic initialization (optional)
-- `turbo_helpers.js` for Turbo integration (optional)
-- `network_helpers.js` for network/HTTP error display (optional)
+## Quick Start
 
-Generator:
-- An installer generator that copies the above files into the host application.
-
-## Installation
-
-Add the following to your application's `Gemfile`:
+### 1. Installation
 
+When using Bundler, add the gem entry to your Gemfile:
 ```ruby
 gem 'flash_unified'
 ```
 
-Then run:
-
+Run the command:
 ```bash
 bundle install
 ```
 
-## Setup
-
-### 1. File placement (only if customization is needed)
-
-This gem provides JavaScript, template, and locale translation files from within the engine. Only copy files using the generator if you want to customize them. Details are described below.
-
-### 2. JavaScript library setup
-
-**Importmap:**
-
-Pin the JavaScript modules you use to `config/importmap.rb`:
-
-```ruby
-pin "flash_unified", to: "flash_unified/flash_unified.js"
-pin "flash_unified/network_helpers", to: "flash_unified/network_helpers.js"
-pin "flash_unified/turbo_helpers", to: "flash_unified/turbo_helpers.js"
-pin "flash_unified/auto", to: "flash_unified/auto.js"
-```
-
-Use `auto.js` to set up rendering timing automatically. `auto.js` automatically handles Turbo integration event registration, custom event registration, and initial page rendering.
-
-If you want to control or implement such events yourself, use the core library `flash_unified.js` to implement rendering processing independently. In that case, `auto.js` is not needed. The helpers `turbo_helpers.js` and `network_helpers.js` are optional, so pin only the ones you will use.
-
-**Asset pipeline (Propshaft / Sprockets):**
-
-```erb
-<link rel="modulepreload" href="<%= asset_path('flash_unified/flash_unified.js') %>">
-<link rel="modulepreload" href="<%= asset_path('flash_unified/network_helpers.js') %>">
-<link rel="modulepreload" href="<%= asset_path('flash_unified/turbo_helpers.js') %>">
-<link rel="modulepreload" href="<%= asset_path('flash_unified/auto.js') %>">
-<script type="importmap">
-  {
-    "imports": {
-      "flash_unified": "<%= asset_path('flash_unified/flash_unified.js') %>",
-      "flash_unified/auto": "<%= asset_path('flash_unified/auto.js') %>",
-      "flash_unified/turbo_helpers": "<%= asset_path('flash_unified/turbo_helpers.js') %>",
-      "flash_unified/network_helpers": "<%= asset_path('flash_unified/network_helpers.js') %>"
-    }
-  }
-</script>
-<script type="module">
-  import "flash_unified/auto";
-</script>
-```
-
-### 3. JavaScript initialization
-
-When using helpers, ensure the initialization that registers event handlers runs on page load.
-
-**Automatic initialization (simple implementation case):**
-
-When using `auto.js`, import `auto` in your JavaScript entry point (e.g., `app/javascript/application.js`):
-```js
-import "flash_unified/auto";
+Or install it directly:
+```bash
+gem install flash_unified
 ```
 
-Initialization processing is executed simultaneously with import. The behavior at that time can be controlled with data attributes on `<html>`. Details are described below.
-
-**Semi-automatic control (Turbo events are set up automatically):**
-
-When using `turbo_helpers.js`, initialization is not run automatically after import. Call the methods from the imported module:
-```js
-import { installInitialRenderListener } from "flash_unified";
-import { installTurboRenderListeners } from "flash_unified/turbo_helpers";
+### 2. Client-side setup (Importmap)
 
-installTurboRenderListeners();
-installInitialRenderListener();
+Add to `config/importmap.rb`:
+```ruby
+pin "flash_unified/all", to: "flash_unified/all.bundle.js"
 ```
 
-This ensures Flash messages are rendered when page changes (Turbo events) are detected.
-
-**Manual control (implementing event handlers yourself):**
-
-When implementing event registration and other aspects yourself, you'll typically need to call `renderFlashMessages()` at least on initial page load to process messages that may have been embedded by the server. This has been prepared as `installInitialRenderListener()` since it's a standard procedure:
-
-```js
-import { installInitialRenderListener } from "flash_unified";
-installInitialRenderListener();
+Import in your JavaScript entry point (e.g., `app/javascript/application.js`):
+```javascript
+import "flash_unified/all";
 ```
 
-Set up calls to rendering processing at appropriate timing to handle storage elements containing Flash messages embedded by the server. You'll probably write calls to `renderFlashMessages()` within some event handler:
-
-```js
-renderFlashMessages();
-```
+### 3. Server-side setup
 
-## Server setup
-
-### Helpers
-
-Server-side view helpers render the DOM fragments (templates, storage, containers, etc.) that the client expects. There are corresponding partial templates for each helper, but generally you don't need to change anything except the partial template for `flash_templates`.
-
-- `flash_global_storage` — a globally placed general-purpose storage element (note: includes `id="flash-storage"`).
-- `flash_storage` — a storage element; include it inside the content you return.
-- `flash_templates` — display element templates used by the client (`<template>` elements).
-- `flash_container` — the container element to place at the target location where users will actually see messages.
-- `flash_general_error_messages` — an element that defines messages for HTTP status codes.
-
-Important: the JavaScript relies on specific DOM contracts defined by the gem (for example, adding `id="flash-storage"` to global storage elements and template IDs in the form `flash-message-template-<type>`). Changing these IDs or selectors will break integration, so if you make changes, you must also update the corresponding JavaScript code.
-
-### Minimal layout example
-
-These are hidden elements so they can be placed anywhere. Typically placing them directly under `<body>` is sufficient:
+Place the "sources" with the helper right after `<body>` in your layout:
 ```erb
-<%= flash_general_error_messages %>
-<%= flash_global_storage %>
-<%= flash_templates %>
+<body>
+  <%= flash_unified_sources %>
+  ...
 ```
 
-Place this where you want Flash messages to be displayed:
+Place the "container" with the helper at the location where you want to display messages:
 ```erb
-<%= flash_container %>
+<div class="notify">
+  <%= flash_container %>
+  ...
 ```
 
-Embed the Flash message content in the response content. Since this is a hidden element, it can be placed anywhere within that content. If responding to a Turbo Frame, place it so it renders within the target frame:
-```erb
-<%= flash_storage %>
-```
-
-### Template customization
+That's it — event handlers that monitor page changes will scan storages and render messages into containers.
 
-To customize the appearance and markup of Flash elements, first copy the templates to your host app with:
+As mentioned earlier, no changes are required in your controllers for setting Flash messages.
 
-```bash
-bin/rails generate flash_unified:install --templates
-```
-
-You can freely customize by editing the copied `app/views/flash_unified/_templates.html.erb`.
-
-Here is a partial example:
-
-```erb
-<template id="flash-message-template-notice">
-  <div class="flash-notice" role="alert">
-    <span class="flash-message-text"></span>
-  </div>
-</template>
-<template id="flash-message-template-warning">
-  <div class="flash-warning" role="alert">
-    <span class="flash-message-text"></span>
-  </div>
-</template>
-```
-
-Template IDs like `flash-message-template-notice` correspond to Flash "types" (e.g., `:notice`, `:alert`, `:warning`). The client references the type contained in messages to select the corresponding template.
-
-The client inserts the message string into the `.flash-message-text` element within the template. Otherwise there are no constraints. Feel free to add additional elements (e.g., dismiss buttons) as needed.
-
-## JavaScript API and extensions
-
-The JavaScript is split into a core library and optional helpers. Use only what you need.
-
-### Core (`flash_unified`)
-
-- `renderFlashMessages()` — scan storages, render to containers, and remove storages.
-- `appendMessageToStorage(message, type = 'notice')` — append to the global storage.
-- `clearFlashMessages(message?)` — remove rendered messages (all or exact-match only).
-- `processMessagePayload(payload)` — accept `{ type, message }[]` or `{ messages: [...] }`.
-- `installCustomEventListener()` — subscribe to `flash-unified:messages` and process payloads.
-- `storageHasMessages()` — utility to detect existing messages in storage.
-- `startMutationObserver()` — (optional / experimental) monitor insertion of storages/templates and render them.
- - `consumeFlashMessages(keep = false)` — scan all `[data-flash-storage]` elements on the current page and return an array of messages ({ type, message }[]). By default this operation is destructive and removes the storage elements; pass `keep = true` to read without removing.
-- `aggregateFlashMessages()` — a thin wrapper over `consumeFlashMessages(true)` that returns the aggregated messages without removing storage elements. Useful for forwarding messages to external notifier libraries.
-
-To display client-generated Flash messages at arbitrary timing, embed the message first and then perform rendering:
-
-```js
-import { appendMessageToStorage, renderFlashMessages } from "flash_unified";
-
-appendMessageToStorage("File size too large.", "notice");
-renderFlashMessages();
-```
-
-To pass server-embedded messages to external libraries like toast instead of rendering them in the page, use `aggregateFlashMessages()` to get messages without destroying storage and pass them to your notification library:
-
-```js
-import { aggregateFlashMessages } from "flash_unified";
-
-document.addEventListener('turbo:load', () => {
-  const msgs = aggregateFlashMessages();
-  msgs.forEach(({ type, message }) => {
-    YourNotifier[type](message); // like toastr.info(message)
-  });
-});
-```
-
-### Custom event
-
-When using custom events, run `installCustomEventListener()` during initialization:
-
-```js
-import { installCustomEventListener } from "flash_unified";
-installCustomEventListener();
-```
-
-Then, at any desired timing, dispatch a `flash-unified:messages` event to the document:
-
-```js
-// Example: passing an array
-document.dispatchEvent(new CustomEvent('flash-unified:messages', {
-  detail: [
-    { type: 'notice', message: 'Sent successfully.' },
-    { type: 'warning', message: 'Expires in one week.' }
-  ]
-}));
-
-// Example: passing an object
-document.dispatchEvent(new CustomEvent('flash-unified:messages', {
-  detail: { messages: [ { type: 'alert', message: 'Operation was cancelled.' } ] }
-}));
-```
-
-### Turbo helpers (`flash_unified/turbo_helpers`)
-
-When using Turbo for partial page updates, you need to perform rendering processing triggered by partial update events. A helper is provided to register those event listeners in bulk:
-
-- `installTurboRenderListeners()` — register events for rendering according to Turbo lifecycle.
-- `installTurboIntegration()` — intended for use by `auto.js`, combines `installTurboRenderListeners()` and `installCustomEventListener()`.
-
-```js
-import { installTurboRenderListeners } from "flash_unified/turbo_helpers";
-installTurboRenderListeners();
-```
-
-### Network/HTTP error helpers (`flash_unified/network_helpers`)
-
-When using network/HTTP error helpers:
-```js
-import { notifyNetworkError, notifyHttpError } from "flash_unified/network_helpers";
-
-notifyNetworkError(); // Set and render generic network error message
-notifyHttpError(413); // Set and render HTTP status-specific message
-```
-
-- `notifyNetworkError()` — uses generic network error text from `#general-error-messages` for rendering.
-- `notifyHttpError(status)` — similarly uses HTTP status-specific text for rendering.
-
-The text used here is written as hidden elements by the server-side view helper `flash_general_error_messages`, and the original text is placed as I18n translation files in `config/locales/http_status_messages.*.yml`.
-
-To customize the default translation content, copy translation files to your host app with the following command and edit them:
-
-```bash
-bin/rails generate flash_unified:install --locales
-```
-
-### Auto initialization entry (`flash_unified/auto`)
-
-Importing `flash_unified/auto` automatically runs Turbo integration initialization after DOM ready. The behavior at that time can be controlled with data attributes on `<html>`:
-
-- `data-flash-unified-auto-init="false"` — disable automatic initialization.
-- `data-flash-unified-enable-network-errors="true"` — also enable listeners for network/HTTP errors.
-
-```erb
-<html data-flash-unified-enable-network-errors="true">
-```
+**For detailed usage** (customization, API reference, Turbo/network helpers, templates, locales, generator usage, and examples), see [`ADVANCED.md`](ADVANCED.md). Examples for using asset pipelines like Sprockets are also provided.
 
 ## Development
 
-For detailed development and testing procedures, see [DEVELOPMENT.md](DEVELOPMENT.md) (English) or [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) (Japanese).
+For detailed development and testing procedures, see [DEVELOPMENT.md](DEVELOPMENT.md).
 
 ## Changelog
 
-See all release notes on the [GitHub Releases page](https://github.com/hiroaki/flash-unified/releases).
+See the [GitHub Releases page](https://github.com/hiroaki/flash-unified/releases).
 
 ## License
 
-This project is licensed under 0BSD (Zero-Clause BSD). See `LICENSE` for details.
+This project is released under the 0BSD (Zero-Clause BSD) license. For details, see [LICENSE](LICENSE).

data/app/helpers/flash_unified/view_helper.rb

@@ -27,6 +27,28 @@ module FlashUnified
     def flash_general_error_messages
       render partial: "flash_unified/general_error_messages"
     end
+
+    # Wrapper helper that renders the common flash-unified pieces in a single
+    # call. This is a non-destructive convenience helper which calls the
+    # existing partial-rendering helpers in a sensible default order. Pass a
+    # hash to disable parts, e.g. `flash_unified_sources(container: false)`.
+    def flash_unified_sources(options = {})
+      opts = {
+        global_storage: true,
+        templates: true,
+        general_errors: true,
+        storage: true,
+        container: false
+      }.merge(options.transform_keys(&:to_sym))
+
+      parts = []
+      parts << flash_global_storage if opts[:global_storage]
+      parts << flash_templates if opts[:templates]
+      parts << flash_general_error_messages if opts[:general_errors]
+      parts << flash_storage if opts[:storage]
+      parts << flash_container if opts[:container]
+
+      safe_join(parts, "\n")
+    end
   end
 end
-

data/app/javascript/flash_unified/all.bundle.js

@@ -0,0 +1 @@
+var d=null;function x(e){if(e!==null&&typeof e!="function")throw new TypeError("Renderer must be a function or null");d=e}function S(e){if(!e||!e.isConnected)return!1;let r=window.getComputedStyle(e);return r&&r.display!=="none"&&r.visibility!=="hidden"&&parseFloat(r.opacity)>0}function N(e={}){let{primaryOnly:r=!1,visibleOnly:n=!1,sortByPriority:t=!1,firstOnly:s=!1,filter:o}=e,i=Array.from(document.querySelectorAll("[data-flash-message-container]"));return r&&(i=i.filter(l=>l.hasAttribute("data-flash-primary")&&l.getAttribute("data-flash-primary")!=="false")),n&&(i=i.filter(S)),typeof o=="function"&&(i=i.filter(o)),t&&i.sort((l,v)=>{let c=Number(l.getAttribute("data-flash-message-container-priority")),m=Number(v.getAttribute("data-flash-message-container-priority")),A=Number.isFinite(c)?c:Number.POSITIVE_INFINITY,C=Number.isFinite(m)?m:Number.POSITIVE_INFINITY;return A-C}),s?i.length>0?[i[0]]:[]:i}function L(){let e=document.documentElement,r=n=>{let t=e.getAttribute(n);if(t!==null)return t===""||t.toLowerCase()==="true"||t==="1"?!0:!(t.toLowerCase()==="false"||t==="0")};return{primaryOnly:r("data-flash-unified-container-primary-only"),visibleOnly:r("data-flash-unified-container-visible-only"),sortByPriority:r("data-flash-unified-container-sort-by-priority"),firstOnly:r("data-flash-unified-container-first-only")}}function F(e){N(L()).forEach(n=>{e.forEach(({type:t,message:s})=>{s&&n.appendChild(I(t,s))})})}function h(){document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){a()},{once:!0}):a()}function a(){let e=g(!1);typeof d=="function"?d(e):F(e)}function g(e=!1){let r=document.querySelectorAll("[data-flash-storage]"),n=[];return r.forEach(t=>{let s=t.querySelector("ul");s&&s.children.length>0&&s.querySelectorAll("li").forEach(o=>{n.push({type:o.dataset.type||"notice",message:o.textContent.trim()})}),e||t.remove()}),n}function O(){return g(!0)}function f(e,r="notice"){let n=document.getElementById("flash-storage");if(!n){console.error('[FlashUnified] #flash-storage not found. Define <div id="flash-storage" style="display:none"></div> in layout.');return}let t=n.querySelector("[data-flash-storage]");t||(t=document.createElement("div"),t.setAttribute("data-flash-storage","true"),t.style.display="none",n.appendChild(t));let s=t.querySelector("ul");s||(s=document.createElement("ul"),t.appendChild(s));let o=document.createElement("li");o.dataset.type=r,o.textContent=e,s.appendChild(o)}function y(){let e=document.documentElement;e.hasAttribute("data-flash-unified-custom-listener")||(e.setAttribute("data-flash-unified-custom-listener","true"),document.addEventListener("flash-unified:messages",function(r){try{M(r.detail)}catch(n){console.error("[FlashUnified] Failed to handle custom payload",n)}}))}function T(e){document.querySelectorAll("[data-flash-message-container]").forEach(r=>{if(typeof e>"u"){r.querySelectorAll("[data-flash-message]")?.forEach(n=>n.remove());return}r.querySelectorAll("[data-flash-message]")?.forEach(n=>{let t=n.querySelector(".flash-message-text");t&&t.textContent.trim()===e&&n.remove()})})}function I(e,r){let n=`flash-message-template-${e}`,t=document.getElementById(n);if(t&&t.content){let s=t.content.firstElementChild;if(!s){console.error(`[FlashUnified] Template #${n} has no root element`);let l=document.createElement("div");return l.setAttribute("role","alert"),l.setAttribute("data-flash-message","true"),l.textContent=r,l}let o=s.cloneNode(!0);o.setAttribute("data-flash-message","true");let i=o.querySelector(".flash-message-text");return i&&(i.textContent=r),o}else{console.error(`[FlashUnified] No template found for type: ${e}`);let s=document.createElement("div");s.setAttribute("role","alert"),s.setAttribute("data-flash-message","true");let o=document.createElement("span");return o.className="flash-message-text",o.textContent=r,s.appendChild(o),s}}function p(){let e=document.querySelectorAll("[data-flash-storage]");for(let r of e){let n=r.querySelector("ul");if(n&&n.children.length>0)return!0}return!1}function M(e){if(!e)return;let r=Array.isArray(e)?e:Array.isArray(e.messages)?e.messages:[];r.length!==0&&(r.forEach(({type:n,message:t})=>{t&&f(String(t),n)}),a())}function R(){let e=document.documentElement;if(e.hasAttribute("data-flash-unified-observer-enabled"))return;e.setAttribute("data-flash-unified-observer-enabled","true"),new MutationObserver(n=>{let t=!1;for(let s of n)s.type==="childList"&&s.addedNodes.forEach(o=>{o instanceof Element&&(o.matches('[data-flash-storage], [data-flash-message-container], template[id^="flash-message-template-"]')&&(t=!0),o.querySelector&&o.querySelector("[data-flash-storage]")&&(t=!0))});t&&a()}).observe(document.body,{childList:!0,subtree:!0})}function u(e){if(p())return;let r=Number(e);if(isNaN(r)||r<0||r>0&&r<400)return;let n;r===0?n="network":n=String(r);let t=document.querySelector("[data-flash-message-container]");if(t&&t.querySelector("[data-flash-message]"))return;let s=document.getElementById("general-error-messages");if(!s){console.error("[FlashUnified] No general error messages element found");return}let o=s.querySelector(`li[data-status="${n}"]`);o?f(o.textContent.trim(),"alert"):console.error(`[FlashUnified] No error message defined for status: ${e}`)}function P(){u(0),a()}function B(e){u(e),a()}function q(){let e=document.documentElement;e.hasAttribute("data-flash-unified-turbo-listeners")||(e.setAttribute("data-flash-unified-turbo-listeners","true"),document.addEventListener("turbo:load",function(){a()}),document.addEventListener("turbo:frame-load",function(){a()}),document.addEventListener("turbo:render",function(){a()}),w())}function w(){let e=new Event("turbo:after-stream-render");document.addEventListener("turbo:before-stream-render",r=>{let n=r.detail.render;r.detail.render=async function(t){await n(t),document.dispatchEvent(e)}}),document.addEventListener("turbo:after-stream-render",function(){a()})}function b(){let e=document.documentElement;e.hasAttribute("data-flash-unified-initialized")||(e.setAttribute("data-flash-unified-initialized","true"),q(),y())}function E(){let e=document.documentElement;e.hasAttribute("data-flash-unified-network-listeners")||(e.setAttribute("data-flash-unified-network-listeners","true"),document.addEventListener("turbo:submit-end",function(r){let n=r.detail.fetchResponse,t;n===void 0?(t=0,console.warn("[FlashUnified] No response received from server. Possible network or proxy error.")):t=n.statusCode,u(t),a()}),document.addEventListener("turbo:fetch-request-error",function(r){u(0),a()}))}if(typeof document<"u"){let e=document.documentElement;if(e.getAttribute("data-flash-unified-auto-init")!=="false"){let n=e.getAttribute("data-flash-unified-enable-network-errors")==="true",t=async()=>{b(),h(),n&&E()};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",t,{once:!0}):t()}}export{O as aggregateFlashMessages,f as appendMessageToStorage,T as clearFlashMessages,g as consumeFlashMessages,N as getFlashMessageContainers,L as getHtmlContainerOptions,y as installCustomEventListener,h as installInitialRenderListener,E as installNetworkErrorListeners,b as installTurboIntegration,q as installTurboRenderListeners,B as notifyHttpError,P as notifyNetworkError,M as processMessagePayload,a as renderFlashMessages,u as resolveAndAppendErrorMessage,x as setFlashMessageRenderer,R as startMutationObserver,p as storageHasMessages};

data/app/javascript/flash_unified/flash_unified.js

@@ -6,6 +6,150 @@
  * @module flash_unified
  */
 
+/**
+ * Custom renderer function set by user. When null, defaultRenderer is used.
+ * @type {Function|null}
+ */
+let customRenderer = null;
+
+/**
+ * Set a custom renderer function to replace the default DOM-based rendering.
+ * Pass `null` to reset to default behavior.
+ *
+ * @param {Function|null} fn - A function that receives an array of message objects: [{type, message}, ...]
+ * @returns {void}
+ * @throws {TypeError} If fn is neither a function nor null
+ *
+ * @example
+ * import { setFlashMessageRenderer } from 'flash_unified';
+ * // Use toastr for notifications
+ * setFlashMessageRenderer((messages) => {
+ *   messages.forEach(({ type, message }) => {
+ *     toastr[type === 'alert' ? 'error' : 'info'](message);
+ *   });
+ * });
+ */
+function setFlashMessageRenderer(fn) {
+  if (fn !== null && typeof fn !== 'function') {
+    throw new TypeError('Renderer must be a function or null');
+  }
+  customRenderer = fn;
+}
+
+/**
+ * Return whether an element is visible (basic heuristic).
+ * Considers display/visibility and DOM connection; does not use IntersectionObserver.
+ *
+ * @param {Element} el
+ * @returns {boolean}
+ */
+function isVisible(el) {
+  if (!el || !el.isConnected) return false;
+  const style = window.getComputedStyle(el);
+  return style && style.display !== 'none' && style.visibility !== 'hidden' && parseFloat(style.opacity) > 0;
+}
+
+/**
+ * Collect flash message containers with optional filtering/sorting.
+ * By default, returns all elements matching `[data-flash-message-container]`.
+ * This function is intended for custom renderers to choose target containers.
+ *
+ * Options:
+ * - primaryOnly?: boolean — If true, only include elements with `data-flash-primary` present or set to "true".
+ * - visibleOnly?: boolean — If true, include only elements considered visible.
+ * - sortByPriority?: boolean — If true, sort by numeric `data-flash-message-container-priority` ascending (missing treated as Infinity).
+ * - firstOnly?: boolean — If true, return at most one element after filtering/sorting.
+ * - filter?: (el: Element) => boolean — Additional predicate to include elements.
+ *
+ * @param {Object} [options]
+ * @returns {Element[]} Array of container elements
+ */
+function getFlashMessageContainers(options = {}) {
+  const {
+    primaryOnly = false,
+    visibleOnly = false,
+    sortByPriority = false,
+    firstOnly = false,
+    filter
+  } = options;
+
+  // Fixed selector by gem convention
+  let list = Array.from(document.querySelectorAll('[data-flash-message-container]'));
+
+  if (primaryOnly) {
+    list = list.filter(el => el.hasAttribute('data-flash-primary') && (el.getAttribute('data-flash-primary') !== 'false'));
+  }
+  if (visibleOnly) {
+    list = list.filter(isVisible);
+  }
+  if (typeof filter === 'function') {
+    list = list.filter(filter);
+  }
+  if (sortByPriority) {
+    list.sort((a, b) => {
+      const pa = Number(a.getAttribute('data-flash-message-container-priority'));
+      const pb = Number(b.getAttribute('data-flash-message-container-priority'));
+      const va = Number.isFinite(pa) ? pa : Number.POSITIVE_INFINITY;
+      const vb = Number.isFinite(pb) ? pb : Number.POSITIVE_INFINITY;
+      return va - vb;
+    });
+  }
+  if (firstOnly) {
+    return list.length > 0 ? [list[0]] : [];
+  }
+  return list;
+}
+
+/**
+ * Read default container selection options from <html> data-attributes.
+ * Supported attributes (all optional):
+ * - data-flash-unified-container-primary-only
+ * - data-flash-unified-container-visible-only
+ * - data-flash-unified-container-sort-by-priority
+ * - data-flash-unified-container-first-only
+ *
+ * Each attribute accepts:
+ * - presence with no value → true
+ * - "true"/"1" → true
+ * - "false"/"0" → false
+ * Missing attribute yields undefined (does not override defaults).
+ *
+ * @returns {{ primaryOnly?: boolean, visibleOnly?: boolean, sortByPriority?: boolean, firstOnly?: boolean }}
+ */
+function getHtmlContainerOptions() {
+  const root = document.documentElement;
+  const parse = (name) => {
+    const val = root.getAttribute(name);
+    if (val === null) return undefined;
+    if (val === '' || val.toLowerCase() === 'true' || val === '1') return true;
+    if (val.toLowerCase() === 'false' || val === '0') return false;
+    // Any other non-empty value: treat as true for convenience
+    return true;
+  };
+  return {
+    primaryOnly: parse('data-flash-unified-container-primary-only'),
+    visibleOnly: parse('data-flash-unified-container-visible-only'),
+    sortByPriority: parse('data-flash-unified-container-sort-by-priority'),
+    firstOnly: parse('data-flash-unified-container-first-only')
+  };
+}
+
+/**
+ * Default renderer: renders messages into DOM containers using templates.
+ *
+ * @param {{type: string, message: string}[]} messages - Array of message objects
+ * @returns {void}
+ */
+function defaultRenderer(messages) {
+  // Allow page-wide defaults via <html> data-attributes
+  const containers = getFlashMessageContainers(getHtmlContainerOptions());
+  containers.forEach(container => {
+    messages.forEach(({ type, message }) => {
+      if (message) container.appendChild(createFlashMessageNode(type, message));
+    });
+  });
+}
+
 /**
  * Install a one-time listener that calls `renderFlashMessages()` on initial page load.
  *
@@ -26,6 +170,7 @@ function installInitialRenderListener() {
 /**
  * Render messages found in storages into message containers.
  * Delegates message collection to `consumeFlashMessages(false)`, which removes the storage elements.
+ * Uses custom renderer if set, otherwise uses default DOM-based rendering.
  *
  * @example
  * import { renderFlashMessages } from 'flash_unified';
@@ -34,14 +179,13 @@ function installInitialRenderListener() {
  * @returns {void}
  */
 function renderFlashMessages() {
-  const containers = document.querySelectorAll('[data-flash-message-container]');
-
   const messages = consumeFlashMessages(false);
-  containers.forEach(container => {
-    messages.forEach(({ type, message }) => {
-      if (message) container.appendChild(createFlashMessageNode(type, message));
-    });
-  });
+
+  if (typeof customRenderer === 'function') {
+    customRenderer(messages);
+  } else {
+    defaultRenderer(messages);
+  }
 }
 
 /**
@@ -282,6 +426,9 @@ function startMutationObserver() {
 
 export {
   renderFlashMessages,
+  setFlashMessageRenderer,
+  getFlashMessageContainers,
+  getHtmlContainerOptions,
   appendMessageToStorage,
   clearFlashMessages,
   processMessagePayload,

data/flash_unified.gemspec

@@ -35,7 +35,9 @@ Gem::Specification.new do |spec|
       "README.md",
       "CHANGELOG.md",
       "flash_unified.gemspec"
-    ].reject { |f| File.directory?(f) }
+    ].reject do |f|
+      File.directory?(f) || f == "app/javascript/flash_unified/all.entry.js"
+    end
     # Ensure version file is included
     files << "lib/flash_unified/version.rb" unless files.include?("lib/flash_unified/version.rb")
     files.uniq

data/lib/flash_unified/engine.rb

@@ -27,6 +27,7 @@ module FlashUnified
           flash_unified/auto.js
           flash_unified/turbo_helpers.js
           flash_unified/network_helpers.js
+          flash_unified/all.bundle.js
         ]
       else
         # Fallback: still add to assets paths if available

data/lib/flash_unified/generators/install/install_generator.rb

@@ -30,76 +30,63 @@ module FlashUnified
 
           === FlashUnified installation instructions ===
 
-          Importing the JavaScript
-          - Importmap: add to `config/importmap.rb`:
+          Quick start (Importmap)
+          1) Add to `config/importmap.rb`:
 
-              pin "flash_unified", to: "flash_unified/flash_unified.js"
-              pin "flash_unified/auto", to: "flash_unified/auto.js"
-              pin "flash_unified/turbo_helpers", to: "flash_unified/turbo_helpers.js"
-              pin "flash_unified/network_helpers", to: "flash_unified/network_helpers.js"
+              pin "flash_unified/all", to: "flash_unified/all.bundle.js"
 
-            Quick start (auto init):
+          2) Import once in your JavaScript entry point (e.g. `app/javascript/application.js`):
 
-              Importing `flash_unified/auto` sets up Turbo listeners and triggers an initial render.
+              import "flash_unified/all";
 
-              import "flash_unified/auto";
-              // Configure via <html data-flash-unified-*>:
-              //   data-flash-unified-auto-init="false" (opt-out)
-              //   data-flash-unified-enable-network-errors="true" (install Turbo network error listeners)
+          3) In your layout (inside `<body>`):
 
+              <%= flash_unified_sources %>
+              <%= flash_container %>
+
+          Auto-initialization is enabled by default. Control it via `<html>` attributes:
+            - `data-flash-unified-auto-init="false"` to disable all automatic wiring.
+            - `data-flash-unified-enable-network-errors="true"` to enable network error listeners.
+
+          Advanced usage (optional)
             Manual control:
 
               import { renderFlashMessages, appendMessageToStorage } from "flash_unified";
               import { installTurboRenderListeners } from "flash_unified/turbo_helpers";
               installTurboRenderListeners();
 
-            Network helpers (optional, framework-agnostic):
+            Network helpers:
 
               import { notifyNetworkError, notifyHttpError } from "flash_unified/network_helpers";
               // notifyNetworkError();
               // notifyHttpError(413);
 
-          - Asset pipeline (Propshaft / Sprockets): the engine adds its `app/javascript` to the asset paths; add modulepreload links and an inline importmap in your layout's `<head>` and import the bare specifier.
+          Propshaft / Sprockets quick start
+            Place in `<head>`:
 
-              <link rel="modulepreload" href="<%= asset_path('flash_unified/flash_unified.js') %>">
-              <link rel="modulepreload" href="<%= asset_path('flash_unified/network_helpers.js') %>">
-              <link rel="modulepreload" href="<%= asset_path('flash_unified/turbo_helpers.js') %>">
-              <link rel="modulepreload" href="<%= asset_path('flash_unified/auto.js') %>">
+              <link rel="modulepreload" href="<%= asset_path('flash_unified/all.bundle.js') %>">
               <script type="importmap">
                 {
                   "imports": {
-                    "flash_unified": "<%= asset_path('flash_unified/flash_unified.js') %>",
-                    "flash_unified/auto": "<%= asset_path('flash_unified/auto.js') %>",
-                    "flash_unified/turbo_helpers": "<%= asset_path('flash_unified/turbo_helpers.js') %>",
-                    "flash_unified/network_helpers": "<%= asset_path('flash_unified/network_helpers.js') %>"
+                    "flash_unified/all": "<%= asset_path('flash_unified/all.bundle.js') %>"
                   }
                 }
               </script>
               <script type="module">
-                import "flash_unified/auto";
+                import "flash_unified/all";
               </script>
 
-              Remove the `import "flash_unified/auto";` line if you don't want automatic initialization.
-
-          How to place partials in your layout
-          - The gem's view helpers render engine partials. After running this generator you'll have the partials available under `app/views/flash_unified` and can customize them as needed.
-
-          Recommended layout snippet (inside `<body>`, global helpers):
+            (Optionally map `flash_unified` or other modules if you need manual control APIs.)
 
+          Layout helpers
             <%= flash_general_error_messages %>
             <%= flash_global_storage %>
             <%= flash_templates %>
-
-          Place the visible container wherever messages should appear:
-
             <%= flash_container %>
-
-          Embed per-response storage inside content (e.g. Turbo Frame responses):
-
             <%= flash_storage %>
 
           Documentation
-          - For full details and customization guidance, see README.md / README.ja.md in the gem.
+          - See README.md / README.ja.md for customization guidance and advanced scenarios.
 
         MSG
 

data/lib/flash_unified/version.rb

@@ -1,3 +1,3 @@
 module FlashUnified
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flash_unified
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - hiroaki
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-20 00:00:00.000000000 Z
+date: 2025-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -161,6 +161,7 @@ files:
 - LICENSE
 - README.md
 - app/helpers/flash_unified/view_helper.rb
+- app/javascript/flash_unified/all.bundle.js
 - app/javascript/flash_unified/auto.js
 - app/javascript/flash_unified/flash_unified.js
 - app/javascript/flash_unified/network_helpers.js