flash_unified 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7063ee3fc735eb8fcf88ca5562119d948fc68464e2c7be0696b1e7fbc1542a87
-  data.tar.gz: bdddb50bb03254d0d1ddf07d18dae37d48a4623d02a2f7bed83243e3c6920ca4
+  metadata.gz: 1ff9e758b822e2e06c38f1543fc5e2be3b4aa101879bdd1137ab70f01b0cc350
+  data.tar.gz: 1df992f44cd7c2db0992b4130d9047af5c7017a26e3367aa395597a884adbddb
 SHA512:
-  metadata.gz: 399bbe669d11e36909ea54d022ea1365c8f69cccad30ae3d2f2d8e1535e927f204dbcc05e32e184553bb718b5496cfec12d72e79c28bc4c4f4d210af1df8777a
-  data.tar.gz: 133059a7460e3cff955b47a187ce42f27300e87774a2890b174a0597a729d7d2c6ea1b5ccf425fc17853183a3a822c9469978f41894d37005f556fcb8ecb71aa
+  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 into the page as data, and a lightweight client-side JavaScript reads those embeddings and renders them onto the page.
+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
 
-Two concerns motivated this work.
+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.
+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 applications messages are shown 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 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 agree on how to embed data. This gem defines a DOM structure for the embedding, which we refer to as "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 agree on how to embed data.
 </div>
 ```
 
-Because storage is hidden, 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. In other words, even when storage is inside a Turbo Frame, the rendering can target a container outside the frame.
-
-For client-detected cases (for example, when a proxy returns 413 on form submission), instead of rendering an error message directly from JavaScript, embed the message into a container element and let the same templates and flow render it as a 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,279 +50,71 @@ else
 end
 ```
 
-Introducing this gem does not require changes to existing controllers. Layout changes are minimal since storage elements are hidden; usually you only need to adjust the container area for Flash messages.
-
-The main implementation task when using this gem is deciding when the embedded data should be rendered as Flash messages. Typically this is done with events. The gem provides helpers that automatically set up event handlers, but you may call rendering methods directly where appropriate.
-
-## Main features
-
-This gem provides rules for embedding data and helper tools for 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 ES Module in `flash_unified.js`. 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. Place files
-
-Run the installer generator:
-
+Or install it directly:
 ```bash
-bin/rails generate flash_unified:install
+gem install flash_unified
 ```
 
-### 2. Add JavaScript
-
-**Importmap:**
-
-`config/importmap.rb` should pin the JavaScript modules you use. The installer generator and sandbox templates pin all shipped modules, but if you manage pins manually, include at least the following:
+### 2. Client-side setup (Importmap)
 
+Add to `config/importmap.rb`:
 ```ruby
-pin "flash_unified/auto", to: "flash_unified/auto.js"
-pin "flash_unified", to: "flash_unified/flash_unified.js"
-pin "flash_unified/turbo_helpers", to: "flash_unified/turbo_helpers.js"
-pin "flash_unified/network_helpers", to: "flash_unified/network_helpers.js"
-```
-
-If you want the library to set up rendering timing automatically, use `auto.js`. `auto.js` will register Turbo integration events, custom event listeners, and perform initial render handling automatically.
-
-If you prefer to control those events yourself, import the core `flash_unified` module and call the provided helpers (for example, `installInitialRenderListener()` for initial render, `installTurboRenderListeners()` from `flash_unified/turbo_helpers` for Turbo lifecycle hooks, and `installCustomEventListener()` to subscribe to `flash-unified:messages`). `turbo_helpers.js` and `network_helpers.js` are optional—pin only the ones you will use.
-
-**Asset pipeline (Propshaft / Sprockets):**
-
-This gem's JavaScript is provided as ES modules. Instead of `pin`ning, add the following to an appropriate place in your layout:
-```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 (simple case):**
-
-Import `auto.js` in your JS entry (e.g. `app/javascript/application.js`):
-
-```js
-import "flash_unified/auto";
-```
-
-`auto.js` runs initialization when loaded. Its behavior can be controlled with data attributes on `<html>` (described below).
-
-**Semi-automatic (Turbo events are set automatically):**
-
-When using `turbo_helpers.js`, initialization is not run automatically after import. Call the provided functions:
-
-```js
-import { installInitialRenderListener } from "flash_unified";
-import { installTurboRenderListeners } from "flash_unified/turbo_helpers";
-
-installTurboRenderListeners();
-installInitialRenderListener();
-```
-
-This ensures Flash messages are rendered when page changes occur (Turbo events).
-
-**Manual (implement your own handlers):**
-
-If you implement event registration yourself, at minimum call `renderFlashMessages()` on initial page load. A helper `installInitialRenderListener()` is provided for this purpose:
-
-```js
-import { installInitialRenderListener } from "flash_unified";
-installInitialRenderListener();
-```
-
-Decide an appropriate timing to call `renderFlashMessages()`—typically within an event handler.
-
-## Server setup
-
-### Helpers
-
-Server-side view helpers render the DOM fragments the client expects. Most partials do not need changes other than the `flash_templates` partial.
-
-- `flash_global_storage` — a global storage element (includes `id="flash-storage"`).
-- `flash_storage` — a storage element; include it inside the content you return.
-- `flash_templates` — templates (`<template>` elements) used by the client.
-- `flash_container` — the container where Flash messages are displayed.
-- `flash_general_error_messages` — a node with messages for HTTP status codes.
-
-Important: the JavaScript relies on specific DOM contracts (for example, a global storage element with `id="flash-storage"` and template IDs in the form `flash-message-template-<type>`). Changing these IDs/selectors without updating the JavaScript will break integration.
-
-### Minimal layout example
-
-Storage elements can be placed anywhere. Typically they are included near the top of the body:
-
-```erb
-<%= flash_general_error_messages %>
-<%= flash_global_storage %>
-<%= flash_templates %>
+pin "flash_unified/all", to: "flash_unified/all.bundle.js"
 ```
 
-Place the visible container where users should see messages:
-
-```erb
-<%= flash_container %>
+Import in your JavaScript entry point (e.g., `app/javascript/application.js`):
+```javascript
+import "flash_unified/all";
 ```
 
-Embed `flash_storage` inside the response content (for Turbo Frame responses, render it inside the frame):
+### 3. Server-side setup
 
+Place the "sources" with the helper right after `<body>` in your layout:
 ```erb
-<%= flash_storage %>
+<body>
+  <%= flash_unified_sources %>
+  ...
 ```
 
-### Template customization
-
-To customize the appearance and markup of Flash messages, edit the partial template `app/views/flash_unified/_templates.html.erb` that is copied into your host Rails application by the installer generator.
-
-Here is a partial example:
-
+Place the "container" with the helper at the location where you want to display messages:
 ```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>
+<div class="notify">
+  <%= flash_container %>
+  ...
 ```
 
-Template IDs like `flash-message-template-notice` map to Flash types (`:notice`, `:alert`, `:warning`). The client inserts the message string into `.flash-message-text`. Otherwise the templates are free-form; add elements such as 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.
+That's it — event handlers that monitor page changes will scan storages and render messages into containers.
 
-Use `appendMessageToStorage()` and `renderFlashMessages()` to produce client-originated Flash messages:
+As mentioned earlier, no changes are required in your controllers for setting Flash messages.
 
-```js
-import { appendMessageToStorage, renderFlashMessages } from "flash_unified";
+**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.
 
-appendMessageToStorage("File size too large.", "notice");
-renderFlashMessages();
-```
-
-### Custom event
-
-To use custom events, run `installCustomEventListener()` during initialization:
-
-```js
-import { installCustomEventListener } from "flash_unified";
-installCustomEventListener();
-```
-
-Then, at any desired timing, dispatch a `flash-unified:messages` event on 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, partial updates require rendering at the appropriate events. Use the helper to register these listeners:
-
-- `installTurboRenderListeners()` — register Turbo lifecycle listeners.
-- `installTurboIntegration()` — a convenience that combines `installTurboRenderListeners()` and `installCustomEventListener()` (used by `auto.js`).
-
-```js
-import { installTurboRenderListeners } from "flash_unified/turbo_helpers";
-installTurboRenderListeners();
-```
-
-### Network/HTTP helpers (`flash_unified/network_helpers`)
-
-Use these helpers to set messages for network/HTTP errors:
-
-```js
-import { notifyNetworkError, notifyHttpError } from "flash_unified/network_helpers";
-
-notifyNetworkError();
-notifyHttpError(413);
-```
-
-The messages used here are output as hidden elements by the server-side view helper `flash_general_error_messages`. The original message strings are installed as I18n translation files in `config/locales` by the generator. To change these messages, edit the translations in the corresponding locale file.
-
-### Auto initialization entry (`flash_unified/auto`)
-
-Importing `flash_unified/auto` runs initialization after DOM ready. The behavior can be controlled with data attributes on `<html>`:
+## Development
 
-- `data-flash-unified-auto-init="false"` — disable automatic initialization.
-- `data-flash-unified-enable-network-errors="true"` — also enable network/HTTP error listeners.
+For detailed development and testing procedures, see [DEVELOPMENT.md](DEVELOPMENT.md).
 
-```erb
-<html data-flash-unified-enable-network-errors="true">
-```
-
-## Development
+## Changelog
 
-See [DEVELOPMENT.md](DEVELOPMENT.md) or [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) for development and testing instructions.
+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

@@ -1,66 +1,164 @@
-/*
-  Flash Unified — Minimal Core API
+/**
+ * flash_unified — Core utilities for reading and rendering embedded flash messages.
+ *
+ * See README.md for full usage examples and integration notes.
+ *
+ * @module flash_unified
+ */
 
-  Purpose
-  - Provide core utilities for flash message rendering.
-  - Users control when and how to trigger rendering via their own event handlers.
+/**
+ * Custom renderer function set by user. When null, defaultRenderer is used.
+ * @type {Function|null}
+ */
+let customRenderer = null;
 
-  Core API:
-  - renderFlashMessages(): render all messages from storage into containers
-  - appendMessageToStorage(message, type): add a message to hidden storage
-  - clearFlashMessages(message?): clear displayed messages
-  - processMessagePayload(payload): handle message arrays from custom events
-  - startMutationObserver(): watch for dynamically inserted storage/templates
+/**
+ * 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;
+}
 
-  Required DOM (no Rails helpers needed)
-  1) Display container (required)
-     <div data-flash-message-container></div>
+/**
+ * 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;
+}
 
-  2) Hidden storage (optional; any number; removed after render)
-     <div data-flash-storage style="display:none;">
-       <ul>
-         <li data-type="notice">Saved</li>
-         <li data-type="alert">Oops</li>
-       </ul>
-     </div>
+/**
+ * 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;
 
-  3) Message templates, one per type (root should have role="alert" and include
-     a .flash-message-text node for insertion)
-     <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-alert">
-       <div class="flash-alert" role="alert"><span class="flash-message-text"></span></div>
-     </template>
+  // Fixed selector by gem convention
+  let list = Array.from(document.querySelectorAll('[data-flash-message-container]'));
 
-  4) Global storage (required by appendMessageToStorage)
-     <div id="flash-storage" style="display:none;"></div>
+  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;
+}
 
-  Usage Examples:
-    // Manual control with Stimulus
-    import { renderFlashMessages, appendMessageToStorage } from "flash_unified";
-    export default class extends Controller {
-      connect() { renderFlashMessages(); }
-      error() {
-        appendMessageToStorage('Error occurred', 'alert');
-        renderFlashMessages();
-      }
-    }
+/**
+ * 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')
+  };
+}
 
-    // Custom event listener
-    import { renderFlashMessages } from "flash_unified";
-    document.addEventListener('turbo:load', renderFlashMessages);
-    document.addEventListener('my-app:show-message', (event) => {
-      appendMessageToStorage(event.detail.message, event.detail.type);
-      renderFlashMessages();
+/**
+ * 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));
     });
-*/
+  });
+}
 
-/* 初回描画リスナーをセットします。
-   DOMContentLoaded 時に renderFlashMessages() を一度だけ呼びます。
-   ---
-   Install a listener to render flash messages on DOMContentLoaded (once).
-*/
+/**
+ * Install a one-time listener that calls `renderFlashMessages()` on initial page load.
+ *
+ * @example
+ * import { installInitialRenderListener } from 'flash_unified';
+ * installInitialRenderListener();
+ *
+ * @returns {void}
+ */
 function installInitialRenderListener() {
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', function() { renderFlashMessages(); }, { once: true });
@@ -69,19 +167,39 @@ function installInitialRenderListener() {
   }
 }
 
-/* ストレージにあるメッセージを表示させます。
-  すべての [data-flash-storage] 内のリスト項目を集約し、各項目ごとにテンプレートを用いて
-  フラッシュメッセージ要素を生成し、[data-flash-message-container] に追加します。
-  処理後は各ストレージ要素を取り除きます。
-  ---
-  Render messages found in all [data-flash-storage] lists, create elements via templates,
-  and append them into [data-flash-message-container]. Each storage is removed after processing.
-*/
+/**
+ * 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';
+ * renderFlashMessages();
+ *
+ * @returns {void}
+ */
 function renderFlashMessages() {
-  const storages = document.querySelectorAll('[data-flash-storage]');
-  const containers = document.querySelectorAll('[data-flash-message-container]');
+  const messages = consumeFlashMessages(false);
+
+  if (typeof customRenderer === 'function') {
+    customRenderer(messages);
+  } else {
+    defaultRenderer(messages);
+  }
+}
 
-  // Aggregated messages list
+/**
+ * Collect messages from all `[data-flash-storage]` elements.
+ * By default, removes each storage after reading; pass `keep = true` to preserve them.
+ *
+ * @param {boolean} [keep=false] - When true, do not remove storage elements after reading.
+ * @returns {{type: string, message: string}[]} Array of message objects.
+ *
+ * @example
+ * const msgs = consumeFlashMessages(true);
+ */
+function consumeFlashMessages(keep = false) {
+  const storages = document.querySelectorAll('[data-flash-storage]');
   const messages = [];
   storages.forEach(storage => {
     const ul = storage.querySelector('ul');
@@ -90,33 +208,38 @@ function renderFlashMessages() {
         messages.push({ type: li.dataset.type || 'notice', message: li.textContent.trim() });
       });
     }
-    // Remove storage after consuming
-    storage.remove();
+    if (!keep) storage.remove();
   });
+  return messages;
+}
 
-  containers.forEach(container => {
-    messages.forEach(({ type, message }) => {
-      if (message) container.appendChild(createFlashMessageNode(type, message));
-    });
-  });
+/**
+ * Return messages without removing the storage elements.
+ * Thin wrapper over `consumeFlashMessages(true)`.
+ *
+ * @returns {{type: string, message: string}[]}
+ *
+ * @example
+ * const msgs = aggregateFlashMessages();
+ */
+function aggregateFlashMessages() {
+  return consumeFlashMessages(true);
 }
 
-/* フラッシュ・メッセージ項目として message をデータとして埋め込みます。
-  埋め込まれた項目は renderFlashMessages を呼び出すことによって表示されます。
-  ---
-  Append a message item into the hidden storage.
-  Call renderFlashMessages() to display it.
-*/
+/**
+ * Append a message to the global storage element (`#flash-storage`).
+ *
+ * @param {string} message - The message text to append.
+ * @param {string} [type='notice'] - The flash type (e.g. 'notice', 'alert').
+ * @returns {void}
+ *
+ * @example
+ * appendMessageToStorage('Saved', 'notice');
+ */
 function appendMessageToStorage(message, type = 'notice') {
   const storageContainer = document.getElementById("flash-storage");
   if (!storageContainer) {
     console.error('[FlashUnified] #flash-storage not found. Define <div id="flash-storage" style="display:none"></div> in layout.');
-    // TODO: あるいは自動生成して document.body.appendChild しますか？
-    // ユーザの目に見えない部分で要素が増えることを避けたいと考え、警告に留めています。
-    // 下で storage を生成する部分は、ユーザが設定するコンテナの中なので問題ありません。
-    // ---
-    // Alternatively we could auto-create it on document.body, but we avoid hidden side-effects.
-    // Creating the inner [data-flash-storage] below is safe since it's inside the user-provided container.
     return;
   }
 
@@ -140,12 +263,17 @@ function appendMessageToStorage(message, type = 'notice') {
   ul.appendChild(li);
 }
 
-/* カスタムイベントリスナーを設定します（オプション）。
-  サーバーや他のJSからのカスタムイベントを受け取ります。
-  ---
-  Setup custom event listener for programmatic message dispatch.
-  Listen for "flash-unified:messages" events from server or other JS.
-*/
+/**
+ * Install a listener for `flash-unified:messages` CustomEvent and process its payload.
+ * The event's `detail` should be either an array of message objects or an object with a `messages` array.
+ *
+ * @example
+ * document.dispatchEvent(new CustomEvent('flash-unified:messages', {
+ *   detail: [{ type: 'notice', message: 'Hi' }]
+ * }));
+ *
+ * @returns {void}
+ */
 function installCustomEventListener() {
   const root = document.documentElement;
   if (root.hasAttribute('data-flash-unified-custom-listener')) return; // idempotent
@@ -160,22 +288,20 @@ function installCustomEventListener() {
   });
 }
 
-/* フラッシュ・メッセージの表示をクリアします。
-  message が指定されている場合は、そのメッセージを含んだフラッシュ・メッセージのみを削除します。
-  省略された場合はすべてのフラッシュ・メッセージが対象です。
-  ---
-  Clear flash messages. If message is provided, remove only matching ones;
-  otherwise remove all flash message nodes in the containers.
-*/
+/**
+ * Clear rendered flash messages from message containers.
+ * If `message` is provided, only remove elements whose text exactly matches it.
+ *
+ * @param {string} [message] - Exact message text to remove (optional).
+ * @returns {void}
+ */
 function clearFlashMessages(message) {
   document.querySelectorAll('[data-flash-message-container]').forEach(container => {
-    // メッセージ指定なし: メッセージ要素のみ全削除（コンテナ内の他要素は残す）
     if (typeof message === 'undefined') {
       container.querySelectorAll('[data-flash-message]')?.forEach(n => n.remove());
       return;
     }
 
-    // 指定メッセージに一致する要素だけ削除
     container.querySelectorAll('[data-flash-message]')?.forEach(n => {
       const text = n.querySelector('.flash-message-text');
       if (text && text.textContent.trim() === message) n.remove();
@@ -183,15 +309,14 @@ function clearFlashMessages(message) {
   });
 }
 
-// --- ユーティリティ関数 / Utility functions ---
-
-/* テンプレートからフラッシュ・メッセージ要素を生成します。
-  type に対応する <template id="flash-message-template-<type>"> を利用し、
-  .flash-message-text に文言を挿入します。テンプレートが無い場合は簡易的な要素を生成します。
-  ---
-  Create a flash message DOM node using <template id="flash-message-template-<type>">.
-  Inserts the message into .flash-message-text. Falls back to a minimal element when template is missing.
-*/
+/**
+ * Create a DOM node for a flash message using the `flash-message-template-<type>` template.
+ * Falls back to a minimal element when the template is missing.
+ *
+ * @param {string} type
+ * @param {string} message
+ * @returns {Element}
+ */
 function createFlashMessageNode(type, message) {
   const templateId = `flash-message-template-${type}`;
   const template = document.getElementById(templateId);
@@ -212,7 +337,7 @@ function createFlashMessageNode(type, message) {
     return root;
   } else {
     console.error(`[FlashUnified] No template found for type: ${type}`);
-    // テンプレートがない場合は生成 / Fallback element when template is missing
+    // Fallback element when template is missing
     const node = document.createElement('div');
     node.setAttribute('role', 'alert');
     node.setAttribute('data-flash-message', 'true');
@@ -224,10 +349,11 @@ function createFlashMessageNode(type, message) {
   }
 }
 
-/* 何らかのストレージにメッセージが存在するかを判定します。
-  ---
-  Return true if any [data-flash-storage] contains at least one <li> item.
-*/
+/**
+ * Return true if any `[data-flash-storage]` contains at least one `<li>`.
+ *
+ * @returns {boolean}
+ */
 function storageHasMessages() {
   const storages = document.querySelectorAll('[data-flash-storage]');
   for (const storage of storages) {
@@ -239,11 +365,15 @@ function storageHasMessages() {
   return false;
 }
 
-/* メッセージの配列（または { messages: [...] }）を受け取り、ストレージに追加して描画します。
-  ---
-  Handle a payload of messages and render them.
-  Accepts either an array of { type, message } or an object { messages: [...] }.
-*/
+/**
+ * Accept either:
+ *   - an array of message objects [{ type, message }, ...], or
+ *   - an object { messages: [...] } where messages is such an array.
+ * Append each message to storage and trigger rendering.
+ *
+ * @param {Array|Object} payload
+ * @returns {void}
+ */
 function processMessagePayload(payload) {
   if (!payload) return;
   const list = Array.isArray(payload)
@@ -257,13 +387,12 @@ function processMessagePayload(payload) {
   renderFlashMessages();
 }
 
-/* 任意: MutationObserver を有効化し、動的に挿入されたストレージ/テンプレートを検出して描画します。
-  サーバーレスポンス側でカスタムイベントを発火できない場合の代替となります。
-  ---
-  Optional: Enable a MutationObserver that watches for dynamically inserted
-  flash storage or templates and triggers rendering. Useful when you cannot
-  or do not want to dispatch a custom event from server responses.
-*/
+/**
+ * Enable a MutationObserver that watches for dynamically inserted storages, templates,
+ * or message containers and triggers rendering. Useful when server responses cannot dispatch events.
+ *
+ * @returns {void}
+ */
 function startMutationObserver() {
   const root = document.documentElement;
   if (root.hasAttribute('data-flash-unified-observer-enabled')) return;
@@ -297,11 +426,16 @@ function startMutationObserver() {
 
 export {
   renderFlashMessages,
+  setFlashMessageRenderer,
+  getFlashMessageContainers,
+  getHtmlContainerOptions,
   appendMessageToStorage,
   clearFlashMessages,
   processMessagePayload,
   startMutationObserver,
   installCustomEventListener,
   installInitialRenderListener,
-  storageHasMessages
+  storageHasMessages,
+  consumeFlashMessages,
+  aggregateFlashMessages
 };

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

@@ -4,45 +4,25 @@ require "rails/generators/base"
 module FlashUnified
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      desc "Copies FlashUnified javascript, view partials, locales and prints setup instructions (Importmap / asset pipeline)."
+      desc <<~DESC
+        Copies FlashUnified javascript, view partials, locales and prints setup instructions (Importmap / asset pipeline).
 
-      class_option :force, type: :boolean, default: false, desc: "Overwrite existing files"
-
-      # Print a clear start message so users see the generator run boundary.
-      # Using `say_status :run` follows the Rails generator convention (colored label).
-      # Print a start message once per generator run. An optional `note` will be
-      # appended to the message to provide context (e.g. "copy javascript").
-      def start_message(note = nil)
-        return if @flash_unified_started
-        message = "Installing FlashUnified"
-        message += " — #{note}" if note
-        say_status :run, message, :blue
-        @flash_unified_started = true
-      end
-
-      def copy_javascript
-        start_message("copy javascript")
-        installer = FlashUnified::Installer.new(source_root: File.expand_path('../../../../', __dir__), target_root: Dir.pwd, force: options[:force])
-        installer.copy_javascript do |status, path|
-          say_status status, display_path(path)
-        end
-      end
+        By default (no options), only templates and locales are copied.
+        Use --all to copy all groups (javascript, templates, views, locales, helpers).
+        Use --templates or --locales for fine-grained control.
+      DESC
 
-      # View partials are copied into your host app so you can customize them.
-      def copy_view_partials
-        start_message("copy view partials")
-        installer = FlashUnified::Installer.new(source_root: File.expand_path('../../../../', __dir__), target_root: Dir.pwd, force: options[:force])
-        installer.copy_views do |status, path|
-          say_status status, display_path(path)
-        end
-      end
-
-      def copy_locales
-        start_message("copy locales")
-        installer = FlashUnified::Installer.new(source_root: File.expand_path('../../../../', __dir__), target_root: Dir.pwd, force: options[:force])
-        installer.copy_locales do |status, path|
-          say_status status, display_path(path)
-        end
+      class_option :force, type: :boolean, default: false, desc: "Overwrite existing files"
+      class_option :all, type: :boolean, default: false, desc: "Install all files"
+      class_option :templates, type: :boolean, default: false, desc: "Install only _templates.html.erb partial"
+      class_option :views, type: :boolean, default: false, desc: "Install all view partials (views/flash_unified/*)"
+      class_option :javascript, type: :boolean, default: false, desc: "Install only JavaScript files"
+      class_option :locales, type: :boolean, default: false, desc: "Install only locale files"
+      class_option :helpers, type: :boolean, default: false, desc: "Install only helper files"
+
+      # Rails generator entrypoint (only task that performs copying)
+      def install
+        handle_installation
       end
 
       def show_importmap_instructions
@@ -50,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/all", to: "flash_unified/all.bundle.js"
+
+          2) Import once in your JavaScript entry point (e.g. `app/javascript/application.js`):
 
-              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"
+              import "flash_unified/all";
 
-            Quick start (auto init):
+          3) In your layout (inside `<body>`):
 
-              Importing `flash_unified/auto` sets up Turbo listeners and triggers an initial render.
+              <%= flash_unified_sources %>
+              <%= flash_container %>
 
-              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)
+          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
 
@@ -128,6 +95,96 @@ module FlashUnified
 
       private
 
+      no_tasks do
+        # Print a clear start message so users see the generator run boundary.
+        # Using `say_status :run` follows the Rails generator convention (colored label).
+        # Print a start message once per generator run. An optional `note` will be
+        # appended to the message to provide context (e.g. "copy javascript").
+        def start_message(note = nil)
+          return if @flash_unified_started
+          message = "Installing FlashUnified"
+          message += " — #{note}" if note
+          say_status :run, message, :blue
+          @flash_unified_started = true
+        end
+
+        # Resolve gem root robustly by walking up until we find the gemspec
+        def gem_root
+          return @gem_root if defined?(@gem_root)
+          path = Pathname.new(__dir__)
+          path.ascend do |p|
+            if (p + 'flash_unified.gemspec').exist?
+              @gem_root = p
+              break
+            end
+          end
+          @gem_root ||= Pathname.new(File.expand_path('../../../../', __dir__))
+        end
+
+        def installer
+          @installer ||= FlashUnified::Installer.new(source_root: gem_root.to_s, target_root: destination_root, force: options[:force])
+        end
+
+        def handle_installation
+          # Determine which groups to install
+          groups = []
+          groups << :javascript if options[:javascript]
+          groups << :templates if options[:templates]
+          groups << :views if options[:views]
+          groups << :locales if options[:locales]
+          groups << :helpers if options[:helpers]
+          # If --all was provided, install every group. Otherwise, when no
+          # explicit groups are requested, install a sensible minimal set:
+          # templates + locales. This avoids unexpectedly copying JavaScript,
+          # helpers or full view partial sets into the host app when the user
+          # runs the generator without options.
+          if options[:all]
+            groups = [:javascript, :templates, :views, :locales, :helpers]
+          elsif groups.empty?
+            groups = [:templates, :locales]
+          end
+
+          groups.each do |group|
+            send("copy_#{group}")
+          end
+        end
+
+        def copy_javascript
+          start_message("copy javascript")
+          installer.copy_javascript do |status, path|
+            say_status status, display_path(path)
+          end
+        end
+
+        def copy_templates
+          start_message("copy _templates.html.erb")
+          installer.copy_templates do |status, path|
+            say_status status, display_path(path)
+          end
+        end
+
+        def copy_views
+          start_message("copy all view partials")
+          installer.copy_views do |status, path|
+            say_status status, display_path(path)
+          end
+        end
+
+        def copy_locales
+          start_message("copy locales")
+          installer.copy_locales do |status, path|
+            say_status status, display_path(path)
+          end
+        end
+
+        def copy_helpers
+          start_message("copy helpers")
+          installer.copy_helpers do |status, path|
+            say_status status, display_path(path)
+          end
+        end
+      end
+
       # Return a user-friendly path for display in generator output. If the
       # provided path is under the current working directory (Rails root), show
       # it as a relative path; otherwise show the original path.

data/lib/flash_unified/installer.rb

@@ -8,8 +8,9 @@ module FlashUnified
   class Installer
     attr_reader :source_root, :target_root, :force
 
-    def initialize(source_root:, target_root:, force: false)
-      @source_root = Pathname.new(source_root)
+    def initialize(source_root: nil, target_root:, force: false)
+      # When source_root is not given, assume the gem root two levels up from this file (lib/flash_unified)
+      @source_root = Pathname.new(source_root || File.expand_path('../..', __dir__))
       @target_root = Pathname.new(target_root)
       @force = !!force
     end
@@ -20,16 +21,20 @@ module FlashUnified
       copy_tree(src, dst, &block)
     end
 
+    # Copy only _templates.html.erb
+    def copy_templates(&block)
+      src_dir = source_root.join('app', 'views', 'flash_unified')
+      dst_dir = target_root.join('app', 'views', 'flash_unified')
+      files = %w[_templates.html.erb]
+      copy_files(files, src_dir, dst_dir, &block)
+    end
+
+    # Copy all files in views/flash_unified/ directory
     def copy_views(&block)
       src_dir = source_root.join('app', 'views', 'flash_unified')
       dst_dir = target_root.join('app', 'views', 'flash_unified')
-      files = %w[
-        _templates.html.erb
-        _storage.html.erb
-        _global_storage.html.erb
-        _container.html.erb
-        _general_error_messages.html.erb
-      ]
+      raise "source missing: #{src_dir}" unless src_dir.directory?
+      files = Dir.children(src_dir).select { |f| File.file?(src_dir.join(f)) }
       copy_files(files, src_dir, dst_dir, &block)
     end
 
@@ -41,6 +46,15 @@ module FlashUnified
       copy_files(files, src_dir, dst_dir, &block)
     end
 
+    def copy_helpers(&block)
+      src_dir = source_root.join('app', 'helpers', 'flash_unified')
+      dst_dir = target_root.join('app', 'helpers', 'flash_unified')
+      files = %w[
+        view_helper.rb
+      ]
+      copy_files(files, src_dir, dst_dir, &block)
+    end
+
     private
 
     def copy_tree(src, dst, &block)

data/lib/flash_unified/version.rb

@@ -1,3 +1,3 @@
 module FlashUnified
-  VERSION = "0.1.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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - hiroaki
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-13 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