flash_unified 0.1.0

data/flash_unified.gemspec

@@ -0,0 +1,61 @@
+require_relative 'lib/flash_unified/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "flash_unified"
+  spec.version       = FlashUnified::VERSION
+  spec.authors       = ["hiroaki"]
+  spec.email         = ["176736+hiroaki@users.noreply.github.com"]
+
+  spec.summary       = %q{Unified server/client flash messages for Rails with consistent templates}
+  spec.description   = %q{Unified server/client flash messages for Rails with consistent templates—Turbo-ready, customizable, easy to integrate.}
+  spec.homepage      = "https://github.com/hiroaki/flash-unified"
+  spec.license       = "0BSD"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
+
+  #spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
+  # Encourage MFA for publishing
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # Use a whitelist approach: explicitly include only the files and folders
+  # that are needed at runtime by the gem. This prevents accidentally
+  # packaging development-only files such as CI workflows, Appraisals and tests.
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    files = Dir[
+      "lib/**/*",
+      "app/**/*",
+      "config/locales/*",
+      "app/views/**/*",
+      "app/javascript/**/*",
+      "LICENSE",
+      "README.md",
+      "CHANGELOG.md",
+      "flash_unified.gemspec"
+    ].reject { |f| File.directory?(f) }
+    # Ensure version file is included
+    files << "lib/flash_unified/version.rb" unless files.include?("lib/flash_unified/version.rb")
+    files.uniq
+  end
+  spec.require_paths = ["lib"]
+
+  # Supported Rails versions: tested against 7.1, 7.2, 8.0
+  spec.add_dependency "rails", ">= 7.1"
+
+  # turbo-rails is used by host apps to provide Turbo/Hotwire integration; include
+  # it as a runtime dependency so the gem's JS + helpers work out of the box.
+  spec.add_dependency "turbo-rails", ">= 2.0"
+
+  #
+  spec.add_development_dependency "appraisal", ">= 2.5"
+  spec.add_development_dependency "capybara", ">= 3.40"
+  spec.add_development_dependency "cuprite", ">= 0.17"
+  spec.add_development_dependency "minitest", ">= 5.0"
+  spec.add_development_dependency "puma", ">= 7.0"
+  spec.add_development_dependency "rake", ">= 13.0"
+  spec.add_development_dependency "sprockets-rails", ">= 3.5"
+  spec.add_development_dependency "sqlite3", ">= 1.4"
+end

data/lib/flash_unified/engine.rb

@@ -0,0 +1,37 @@
+module FlashUnified
+  class Engine < ::Rails::Engine
+    isolate_namespace FlashUnified
+
+    initializer "flash_unified.helpers" do
+      # Ensure the view helper is registered with ActionController so
+      # views in the host app (including the dummy app used for tests)
+      # can call helpers like `flash_container`.
+      # Use `config.to_prepare` so the helper is re-registered on each
+      # code reload in development.
+      config.to_prepare do
+        ActionController::Base.helper FlashUnified::ViewHelper
+      end
+    end
+
+    # Make the engine's `app/javascript` visible to asset pipelines like
+    # Propshaft or Sprockets by adding it to the assets paths and
+    # registering files for precompile if necessary.
+    initializer "flash_unified.assets" do |app|
+      js_path = root.join("app", "javascript").to_s
+      if app.config.respond_to?(:assets)
+        # Sprockets / Propshaft style
+        app.config.assets.paths << js_path
+        # Expose ES module entry points for production precompile
+        app.config.assets.precompile += %w[
+          flash_unified/flash_unified.js
+          flash_unified/auto.js
+          flash_unified/turbo_helpers.js
+          flash_unified/network_helpers.js
+        ]
+      else
+        # Fallback: still add to assets paths if available
+        app.config.assets.paths << js_path if app.config.respond_to?(:assets)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,147 @@
+require "rails/generators"
+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)."
+
+      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
+
+      # 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
+      end
+
+      def show_importmap_instructions
+        message = <<~MSG
+
+          === FlashUnified installation instructions ===
+
+          Importing the JavaScript
+          - Importmap: 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"
+
+            Quick start (auto init):
+
+              Importing `flash_unified/auto` sets up Turbo listeners and triggers an initial render.
+
+              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)
+
+            Manual control:
+
+              import { renderFlashMessages, appendMessageToStorage } from "flash_unified";
+              import { installTurboRenderListeners } from "flash_unified/turbo_helpers";
+              installTurboRenderListeners();
+
+            Network helpers (optional, framework-agnostic):
+
+              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.
+
+              <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>
+
+              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):
+
+            <%= 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.
+
+        MSG
+
+        say message
+      end
+
+      private
+
+      # 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.
+      def display_path(path)
+        path = Pathname.new(path.to_s)
+        begin
+          root = Pathname.new(Dir.pwd)
+          relative = path.relative_path_from(root)
+          relative.to_s
+        rescue ArgumentError
+          # Path not under Dir.pwd — fall back to full path
+          path.to_s
+        end
+      end
+    end
+  end
+end

data/lib/flash_unified/installer.rb

@@ -0,0 +1,95 @@
+require 'fileutils'
+require 'pathname'
+
+module FlashUnified
+  # Pure-Ruby installer logic extracted from the generator so it can be
+  # unit-tested without loading Rails. Responsible for copying javascript,
+  # view partials and locale files from the gem source into a target app.
+  class Installer
+    attr_reader :source_root, :target_root, :force
+
+    def initialize(source_root:, target_root:, force: false)
+      @source_root = Pathname.new(source_root)
+      @target_root = Pathname.new(target_root)
+      @force = !!force
+    end
+
+    def copy_javascript(&block)
+      src = source_root.join('app', 'javascript', 'flash_unified')
+      dst = target_root.join('app', 'javascript', 'flash_unified')
+      copy_tree(src, dst, &block)
+    end
+
+    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
+      ]
+      copy_files(files, src_dir, dst_dir, &block)
+    end
+
+    def copy_locales(&block)
+      src_dir = source_root.join('config', 'locales')
+      dst_dir = target_root.join('config', 'locales')
+      FileUtils.mkdir_p(dst_dir) unless dst_dir.exist?
+      files = Dir.glob(src_dir.join('*.yml')).map { |p| File.basename(p) }
+      copy_files(files, src_dir, dst_dir, &block)
+    end
+
+    private
+
+    def copy_tree(src, dst, &block)
+      raise "source missing: #{src}" unless src.directory?
+      status = :skip
+      if dst.exist?
+        if force
+          FileUtils.rm_rf(dst)
+          FileUtils.mkdir_p(dst)
+          FileUtils.cp_r(File.join(src, '.'), dst)
+          status = :overwrite
+        else
+          status = :skip
+        end
+      else
+        FileUtils.mkdir_p(dst)
+        FileUtils.cp_r(File.join(src, '.'), dst)
+        status = :create
+      end
+      # Report status for the whole directory
+      block.call(status, dst) if block
+      status
+    end
+
+    def copy_files(list, src_dir, dst_dir, &block)
+      raise "source missing: #{src_dir}" unless src_dir.directory?
+      FileUtils.mkdir_p(dst_dir) unless dst_dir.exist?
+      status = :skip
+      list.each do |fname|
+        src = src_dir.join(fname)
+        next unless src.file?
+        dst = dst_dir.join(fname)
+        file_status = :skip
+        if dst.exist?
+          if force
+            FileUtils.cp(src, dst)
+            file_status = :overwrite
+          else
+            file_status = :skip
+          end
+        else
+          FileUtils.cp(src, dst)
+          file_status = :create
+        end
+        block.call(file_status, dst) if block
+        # Track overall status for return value
+        status = file_status if file_status == :create || (file_status == :overwrite && status != :create)
+      end
+      status
+    end
+  end
+end

data/lib/flash_unified/railtie.rb

@@ -0,0 +1,13 @@
+require "rails/railtie"
+
+module FlashUnified
+  class Railtie < Rails::Railtie
+    # Ensure the gem's generators are required so `rails generate` lists
+    # them when the gem is installed into a host application. Using the
+    # `generators` block defers the `require` until generator loading
+    # time and avoids loading Rails-only code during normal gem require.
+    generators do
+      require_relative "generators/install/install_generator"
+    end
+  end
+end

data/lib/flash_unified/version.rb

@@ -0,0 +1,3 @@
+module FlashUnified
+  VERSION = "0.1.0"
+end

data/lib/flash_unified.rb

@@ -0,0 +1,19 @@
+require "flash_unified/version"
+
+# Load the engine when running inside Rails. Using `require` (library
+# path) is the conventional approach for gems; guard with
+# `defined?(Rails)` so loading the gem in non-Rails contexts won't
+# attempt to load the engine.
+require "flash_unified/engine" if defined?(Rails)
+
+# Load Railtie to register generators when running `rails generate`.
+require "flash_unified/railtie" if defined?(Rails)
+
+# Installer is a small, framework-agnostic helper used by the generator
+# and needs to be available when running generator code outside of Rails.
+require "flash_unified/installer"
+
+module FlashUnified
+  class Error < StandardError; end
+  # Your code goes here...
+end

metadata

@@ -0,0 +1,209 @@
+--- !ruby/object:Gem::Specification
+name: flash_unified
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- hiroaki
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.40'
+- !ruby/object:Gem::Dependency
+  name: cuprite
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sprockets-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: Unified server/client flash messages for Rails with consistent templates—Turbo-ready,
+  customizable, easy to integrate.
+email:
+- 176736+hiroaki@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/helpers/flash_unified/view_helper.rb
+- app/javascript/flash_unified/auto.js
+- app/javascript/flash_unified/flash_unified.js
+- app/javascript/flash_unified/network_helpers.js
+- app/javascript/flash_unified/turbo_helpers.js
+- app/views/flash_unified/_container.html.erb
+- app/views/flash_unified/_general_error_messages.html.erb
+- app/views/flash_unified/_global_storage.html.erb
+- app/views/flash_unified/_storage.html.erb
+- app/views/flash_unified/_templates.html.erb
+- config/locales/http_status_messages.en.yml
+- config/locales/http_status_messages.ja.yml
+- flash_unified.gemspec
+- lib/flash_unified.rb
+- lib/flash_unified/engine.rb
+- lib/flash_unified/generators/install/install_generator.rb
+- lib/flash_unified/installer.rb
+- lib/flash_unified/railtie.rb
+- lib/flash_unified/version.rb
+homepage: https://github.com/hiroaki/flash-unified
+licenses:
+- 0BSD
+metadata:
+  homepage_uri: https://github.com/hiroaki/flash-unified
+  source_code_uri: https://github.com/hiroaki/flash-unified
+  changelog_uri: https://github.com/hiroaki/flash-unified/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Unified server/client flash messages for Rails with consistent templates
+test_files: []