flash_unified 0.1.0

data/app/javascript/flash_unified/flash_unified.js

@@ -0,0 +1,307 @@
+/*
+  Flash Unified — Minimal Core API
+
+  Purpose
+  - Provide core utilities for flash message rendering.
+  - Users control when and how to trigger rendering via their own event handlers.
+
+  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
+
+  Required DOM (no Rails helpers needed)
+  1) Display container (required)
+     <div data-flash-message-container></div>
+
+  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>
+
+  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>
+
+  4) Global storage (required by appendMessageToStorage)
+     <div id="flash-storage" style="display:none;"></div>
+
+  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();
+      }
+    }
+
+    // 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();
+    });
+*/
+
+/* 初回描画リスナーをセットします。
+   DOMContentLoaded 時に renderFlashMessages() を一度だけ呼びます。
+   ---
+   Install a listener to render flash messages on DOMContentLoaded (once).
+*/
+function installInitialRenderListener() {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() { renderFlashMessages(); }, { once: true });
+  } else {
+    renderFlashMessages();
+  }
+}
+
+/* ストレージにあるメッセージを表示させます。
+  すべての [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.
+*/
+function renderFlashMessages() {
+  const storages = document.querySelectorAll('[data-flash-storage]');
+  const containers = document.querySelectorAll('[data-flash-message-container]');
+
+  // Aggregated messages list
+  const messages = [];
+  storages.forEach(storage => {
+    const ul = storage.querySelector('ul');
+    if (ul && ul.children.length > 0) {
+      ul.querySelectorAll('li').forEach(li => {
+        messages.push({ type: li.dataset.type || 'notice', message: li.textContent.trim() });
+      });
+    }
+    // Remove storage after consuming
+    storage.remove();
+  });
+
+  containers.forEach(container => {
+    messages.forEach(({ type, message }) => {
+      if (message) container.appendChild(createFlashMessageNode(type, message));
+    });
+  });
+}
+
+/* フラッシュ・メッセージ項目として message をデータとして埋め込みます。
+  埋め込まれた項目は renderFlashMessages を呼び出すことによって表示されます。
+  ---
+  Append a message item into the hidden storage.
+  Call renderFlashMessages() to display it.
+*/
+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;
+  }
+
+  let storage = storageContainer.querySelector('[data-flash-storage]');
+  if (!storage) {
+    storage = document.createElement('div');
+    storage.setAttribute('data-flash-storage', 'true');
+    storage.style.display = 'none';
+    storageContainer.appendChild(storage);
+  }
+
+  let ul = storage.querySelector('ul');
+  if (!ul) {
+    ul = document.createElement('ul');
+    storage.appendChild(ul);
+  }
+
+  const li = document.createElement('li');
+  li.dataset.type = type;
+  li.textContent = message;
+  ul.appendChild(li);
+}
+
+/* カスタムイベントリスナーを設定します（オプション）。
+  サーバーや他のJSからのカスタムイベントを受け取ります。
+  ---
+  Setup custom event listener for programmatic message dispatch.
+  Listen for "flash-unified:messages" events from server or other JS.
+*/
+function installCustomEventListener() {
+  const root = document.documentElement;
+  if (root.hasAttribute('data-flash-unified-custom-listener')) return; // idempotent
+  root.setAttribute('data-flash-unified-custom-listener', 'true');
+
+  document.addEventListener('flash-unified:messages', function(event) {
+    try {
+      processMessagePayload(event.detail);
+    } catch (e) {
+      console.error('[FlashUnified] Failed to handle custom payload', e);
+    }
+  });
+}
+
+/* フラッシュ・メッセージの表示をクリアします。
+  message が指定されている場合は、そのメッセージを含んだフラッシュ・メッセージのみを削除します。
+  省略された場合はすべてのフラッシュ・メッセージが対象です。
+  ---
+  Clear flash messages. If message is provided, remove only matching ones;
+  otherwise remove all flash message nodes in the containers.
+*/
+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();
+    });
+  });
+}
+
+// --- ユーティリティ関数 / 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.
+*/
+function createFlashMessageNode(type, message) {
+  const templateId = `flash-message-template-${type}`;
+  const template = document.getElementById(templateId);
+  if (template && template.content) {
+    const base = template.content.firstElementChild;
+    if (!base) {
+      console.error(`[FlashUnified] Template #${templateId} has no root element`);
+      const node = document.createElement('div');
+      node.setAttribute('role', 'alert');
+      node.setAttribute('data-flash-message', 'true');
+      node.textContent = message;
+      return node;
+    }
+    const root = base.cloneNode(true);
+    root.setAttribute('data-flash-message', 'true');
+    const span = root.querySelector('.flash-message-text');
+    if (span) span.textContent = message;
+    return root;
+  } else {
+    console.error(`[FlashUnified] No template found for type: ${type}`);
+    // テンプレートがない場合は生成 / Fallback element when template is missing
+    const node = document.createElement('div');
+    node.setAttribute('role', 'alert');
+    node.setAttribute('data-flash-message', 'true');
+    const span = document.createElement('span');
+    span.className = 'flash-message-text';
+    span.textContent = message;
+    node.appendChild(span);
+    return node;
+  }
+}
+
+/* 何らかのストレージにメッセージが存在するかを判定します。
+  ---
+  Return true if any [data-flash-storage] contains at least one <li> item.
+*/
+function storageHasMessages() {
+  const storages = document.querySelectorAll('[data-flash-storage]');
+  for (const storage of storages) {
+    const ul = storage.querySelector('ul');
+    if (ul && ul.children.length > 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/* メッセージの配列（または { messages: [...] }）を受け取り、ストレージに追加して描画します。
+  ---
+  Handle a payload of messages and render them.
+  Accepts either an array of { type, message } or an object { messages: [...] }.
+*/
+function processMessagePayload(payload) {
+  if (!payload) return;
+  const list = Array.isArray(payload)
+    ? payload
+    : (Array.isArray(payload.messages) ? payload.messages : []);
+  if (list.length === 0) return;
+  list.forEach(({ type, message }) => {
+    if (!message) return;
+    appendMessageToStorage(String(message), type);
+  });
+  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.
+*/
+function startMutationObserver() {
+  const root = document.documentElement;
+  if (root.hasAttribute('data-flash-unified-observer-enabled')) return;
+  root.setAttribute('data-flash-unified-observer-enabled', 'true');
+
+  const observer = new MutationObserver((mutations) => {
+    let shouldRender = false;
+    for (const m of mutations) {
+      if (m.type === 'childList') {
+        m.addedNodes.forEach((node) => {
+          if (!(node instanceof Element)) return;
+          if (node.matches('[data-flash-storage], [data-flash-message-container], template[id^="flash-message-template-"]')) {
+            shouldRender = true;
+          }
+          if (node.querySelector && node.querySelector('[data-flash-storage]')) {
+            shouldRender = true;
+          }
+        });
+      }
+    }
+    if (shouldRender) {
+      renderFlashMessages();
+    }
+  });
+
+  observer.observe(document.body, {
+    childList: true,
+    subtree: true
+  });
+}
+
+export {
+  renderFlashMessages,
+  appendMessageToStorage,
+  clearFlashMessages,
+  processMessagePayload,
+  startMutationObserver,
+  installCustomEventListener,
+  installInitialRenderListener,
+  storageHasMessages
+};

data/app/javascript/flash_unified/network_helpers.js

@@ -0,0 +1,83 @@
+/*
+  Flash Unified — Network Error Helpers
+
+  Purpose:
+  - Provide optional network and HTTP error handling for Turbo form submissions.
+  - Users can install these listeners if they want automatic error message display.
+
+  Required DOM:
+    <ul id="general-error-messages" style="display:none;">
+      <li data-status="413">Payload Too Large</li>
+      <li data-status="network">Network Error</li>
+      <li data-status="500">Internal Server Error</li>
+    </ul>
+
+  Usage:
+    // Framework-agnostic helpers (call from your own handlers)
+    import { notifyNetworkError, notifyHttpError } from "flash_unified/network_helpers";
+    notifyNetworkError();   // Add generic network error and render
+    notifyHttpError(413);   // Add HTTP-specific message and render
+*/
+
+import { renderFlashMessages, appendMessageToStorage, storageHasMessages } from 'flash_unified';
+
+/* エラーステータスに応じた汎用メッセージをストレージへ追加します。
+  既にストレージにメッセージが存在する場合は何もしません。
+  'network' または 4xx/5xx を対象とし、#general-error-messages から文言を解決します。
+  ---
+  Add a general error message to storage based on status ('network' or 4xx/5xx).
+  If any storage already has messages, this is a no-op. Looks up text in #general-error-messages.
+*/
+function resolveAndAppendErrorMessage(status) {
+  // If any flash storage already contains messages, do not override it
+  if (storageHasMessages()) return;
+
+  // API: resolveAndAppendErrorMessage expects a numeric HTTP status code.
+  // Use 0 to indicate a network-level failure (CORS, network down, file://, etc.).
+  // Non-error codes (< 400) are ignored.
+  const num = Number(status);
+  if (isNaN(num)) return;        // invalid (non-numeric)
+  if (num < 0) return;          // negative numbers not expected
+  if (num > 0 && num < 400) return; // non-error HTTP status codes
+
+  // Determine lookup key
+  let key;
+  if (num === 0) {
+    key = 'network';
+  } else {
+    key = String(num);
+  }
+
+  // Avoid duplicates when container has children
+  const container = document.querySelector('[data-flash-message-container]');
+  if (container && container.querySelector('[data-flash-message]')) return;
+
+  const generalerrors = document.getElementById('general-error-messages');
+  if (!generalerrors) {
+    console.error('[FlashUnified] No general error messages element found');
+    return;
+  }
+
+  const li = generalerrors.querySelector(`li[data-status="${key}"]`);
+  if (li) {
+    appendMessageToStorage(li.textContent.trim(), 'alert');
+  } else {
+    console.error(`[FlashUnified] No error message defined for status: ${status}`);
+  }
+}
+
+function notifyNetworkError() {
+  resolveAndAppendErrorMessage(0);
+  renderFlashMessages();
+}
+
+function notifyHttpError(status) {
+  resolveAndAppendErrorMessage(status);
+  renderFlashMessages();
+}
+
+export {
+  resolveAndAppendErrorMessage,
+  notifyNetworkError,
+  notifyHttpError
+};

data/app/javascript/flash_unified/turbo_helpers.js

@@ -0,0 +1,135 @@
+/*
+  Flash Unified — Turbo Integration Helpers
+
+  Purpose:
+  - Provide optional Turbo event listeners for automatic flash message rendering.
+  - Users can install these listeners if they want automatic integration with Turbo.
+
+  Usage:
+    import { renderFlashMessages } from "flash_unified";
+    import { installTurboRenderListeners } from "flash_unified/turbo_helpers";
+
+    // Install automatic Turbo event listeners
+    installTurboRenderListeners();
+
+    // For the initial render we recommend using the core helper:
+    // import { installInitialRenderListener } from "flash_unified";
+    // installInitialRenderListener();
+*/
+
+import { renderFlashMessages, installCustomEventListener } from 'flash_unified';
+import { resolveAndAppendErrorMessage } from 'flash_unified/network_helpers';
+
+/* Turbo関連のイベントリスナーを設定します。
+  ページ遷移やフレーム更新時に自動的にフラッシュメッセージを描画します。
+  ---
+  Install Turbo event listeners for automatic flash message rendering.
+  Renders messages on page navigation and frame updates.
+*/
+function installTurboRenderListeners() {
+  const root = document.documentElement;
+  if (root.hasAttribute('data-flash-unified-turbo-listeners')) {
+    return; // Already installed
+  }
+  root.setAttribute('data-flash-unified-turbo-listeners', 'true');
+
+  // Turbo page load events
+  document.addEventListener('turbo:load', function() {
+    renderFlashMessages();
+  });
+
+  document.addEventListener('turbo:frame-load', function() {
+    renderFlashMessages();
+  });
+
+  document.addEventListener('turbo:render', function() {
+    renderFlashMessages();
+  });
+
+  // Turbo Stream events
+  installTurboStreamEvents();
+}
+
+/* Turbo Stream更新後のカスタムイベントを設定します。
+  turbo:before-stream-renderをフックして描画完了後にイベントを発火させます。
+  ---
+  Setup custom turbo:after-stream-render event for Turbo Stream updates.
+  Hooks into turbo:before-stream-render to dispatch event after rendering is done.
+*/
+// Internal: used by installTurboRenderListeners
+function installTurboStreamEvents() {
+  // Create custom event for after stream render
+  const afterRenderEvent = new Event("turbo:after-stream-render");
+
+  // Hook into turbo:before-stream-render to add our custom event
+  document.addEventListener("turbo:before-stream-render", (event) => {
+    const originalRender = event.detail.render;
+    event.detail.render = async function (streamElement) {
+      await originalRender(streamElement);
+      document.dispatchEvent(afterRenderEvent);
+    };
+  });
+
+  // Listen for our custom after-stream-render event
+  document.addEventListener("turbo:after-stream-render", function() {
+    renderFlashMessages();
+  });
+}
+
+/* Turboリスナー + カスタムイベントリスナーを一度に設定します。
+  ---
+  Sets up Turbo listeners + custom event listeners in one call.
+*/
+function installTurboIntegration() {
+  const root = document.documentElement;
+  if (root.hasAttribute('data-flash-unified-initialized')) return; // idempotent
+  root.setAttribute('data-flash-unified-initialized', 'true');
+
+  // Delegate to existing installers to avoid duplicating logic.
+  installTurboRenderListeners();
+  installCustomEventListener();
+}
+
+export {
+  installTurboRenderListeners,
+  installTurboIntegration
+};
+
+/* ネットワークエラー関連のイベントリスナーを設定します。
+  Turboフォーム送信時のエラー処理を自動化します。
+  ---
+  Install network error event listeners for automatic error handling.
+  Handles Turbo form submission errors and network issues.
+*/
+function installNetworkErrorListeners() {
+  const root = document.documentElement;
+  if (root.hasAttribute('data-flash-unified-network-listeners')) {
+    return; // Already installed
+  }
+  root.setAttribute('data-flash-unified-network-listeners', 'true');
+
+  document.addEventListener('turbo:submit-end', function(event) {
+    const res = event.detail.fetchResponse;
+    // Determine a numeric status code to pass to the resolver.
+    // Use 0 to represent a network-level failure where no response was received.
+    let statusCode;
+    if (res === undefined) {
+      statusCode = 0;
+      console.warn('[FlashUnified] No response received from server. Possible network or proxy error.');
+    } else {
+      statusCode = res.statusCode;
+    }
+
+    resolveAndAppendErrorMessage(statusCode);
+    renderFlashMessages();
+  });
+
+  document.addEventListener('turbo:fetch-request-error', function(_event) {
+    // Treat fetch-request-error as a network-level failure (status 0)
+    const statusCode = 0;
+    resolveAndAppendErrorMessage(statusCode);
+    renderFlashMessages();
+  });
+}
+
+export { installNetworkErrorListeners };

data/app/views/flash_unified/_container.html.erb

@@ -0,0 +1 @@
+<div data-flash-message-container></div>

data/app/views/flash_unified/_general_error_messages.html.erb

@@ -0,0 +1,12 @@
+<ul id="general-error-messages" style="display: none;">
+  <% status_codes = %w[
+    400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418
+    421 422 423 424 425 426 428 429 431 451
+    500 501 502 503 504 505 506 507 508 510 511
+    network
+  ] %>
+
+  <% status_codes.each do |code| %>
+    <li data-status="<%= code %>"><%= t("http_status_messages.#{code}") %></li>
+  <% end %>
+</ul>

data/app/views/flash_unified/_global_storage.html.erb

@@ -0,0 +1 @@
+<div id="flash-storage" style="display: none;"></div>

data/app/views/flash_unified/_storage.html.erb

@@ -0,0 +1,7 @@
+<div data-flash-storage style="display: none;">
+  <ul>
+    <% flash.each do |type, message| %>
+      <li data-type="<%= type %>"><%= message %></li>
+    <% end %>
+  </ul>
+</div>

data/app/views/flash_unified/_templates.html.erb

@@ -0,0 +1,16 @@
+<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 id="flash-message-template-alert">
+  <div class="flash-alert" role="alert">
+    <span class="flash-message-text"></span>
+  </div>
+</template>
+

data/config/locales/http_status_messages.en.yml

@@ -0,0 +1,43 @@
+en:
+  http_status_messages:
+    "400": "Bad Request"
+    "401": "Unauthorized"
+    "402": "Payment Required"
+    "403": "Forbidden"
+    "404": "Not Found"
+    "405": "Method Not Allowed"
+    "406": "Not Acceptable"
+    "407": "Proxy Authentication Required"
+    "408": "Request Timeout"
+    "409": "Conflict"
+    "410": "Gone"
+    "411": "Length Required"
+    "412": "Precondition Failed"
+    "413": "Payload Too Large"
+    "414": "URI Too Long"
+    "415": "Unsupported Media Type"
+    "416": "Range Not Satisfiable"
+    "417": "Expectation Failed"
+    "418": "I'm a teapot"
+    "421": "Misdirected Request"
+    "422": "Unprocessable Entity"
+    "423": "Locked"
+    "424": "Failed Dependency"
+    "425": "Too Early"
+    "426": "Upgrade Required"
+    "428": "Precondition Required"
+    "429": "Too Many Requests"
+    "431": "Request Header Fields Too Large"
+    "451": "Unavailable For Legal Reasons"
+    "500": "Internal Server Error"
+    "501": "Not Implemented"
+    "502": "Bad Gateway"
+    "503": "Service Unavailable"
+    "504": "Gateway Timeout"
+    "505": "HTTP Version Not Supported"
+    "506": "Variant Also Negotiates"
+    "507": "Insufficient Storage"
+    "508": "Loop Detected"
+    "510": "Not Extended"
+    "511": "Network Authentication Required"
+    network: "Network Error"

data/config/locales/http_status_messages.ja.yml

@@ -0,0 +1,43 @@
+ja:
+  http_status_messages:
+    "400": "不正なリクエスト"
+    "401": "認証が必要です"
+    "402": "支払いが必要です"
+    "403": "アクセスが禁止されています"
+    "404": "見つかりません"
+    "405": "許可されていないメソッドです"
+    "406": "許可されていない形式です"
+    "407": "プロキシ認証が必要です"
+    "408": "リクエストタイムアウト"
+    "409": "競合があります"
+    "410": "消失しました"
+    "411": "長さが必要です"
+    "412": "前提条件に失敗しました"
+    "413": "ペイロードが大きすぎます"
+    "414": "URI が長すぎます"
+    "415": "サポートされていないメディアタイプ"
+    "416": "レンジが満たされません"
+    "417": "期待に失敗しました"
+    "418": "I'm a teapot"
+    "421": "誤った宛先へのリクエスト"
+    "422": "処理できないエンティティ"
+    "423": "ロックされています"
+    "424": "依存関係に失敗しました"
+    "425": "早すぎます"
+    "426": "アップグレードが必要です"
+    "428": "前提条件が必要です"
+    "429": "リクエストが多すぎます"
+    "431": "リクエストヘッダが大きすぎます"
+    "451": "法的理由により利用不可"
+    "500": "サーバ内部エラー"
+    "501": "実装されていません"
+    "502": "不正なゲートウェイ"
+    "503": "サービス利用不可"
+    "504": "ゲートウェイタイムアウト"
+    "505": "HTTP バージョン非サポート"
+    "506": "代替表現も交渉しています"
+    "507": "保存容量が不足しています"
+    "508": "ループ検出"
+    "510": "拡張されていません"
+    "511": "ネットワーク認証が必要です"
+    network: "ネットワークエラー"