phlex_kit 0.2.0

data/lib/generators/phlex_kit/install/templates/phlex_kit.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+PhlexKit.configure do |c|
+  # Enable phlex-reactive integration. :auto turns it on iff the gem is loaded;
+  # set true to require it, false to force it off.
+  c.reactive = :auto
+
+  # Alias `UI` to `PhlexKit` so you can write `UI::Button` instead of
+  # `PhlexKit::Button`. Off by default to avoid claiming a generic constant.
+  c.define_ui_alias = false
+end

data/lib/phlex_kit/base_component.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PhlexKit
+  # Base for every PhlexKit component: a plain Phlex::HTML subclass. It stays free
+  # of any Rails-runtime coupling (no route helpers, no booted-app assumptions) so
+  # the components load and render anywhere Phlex does — that also keeps the unit
+  # suite bootable without a Rails app. A host component that needs route helpers
+  # includes `Phlex::Rails::Helpers::Routes` itself.
+  #
+  # Reactivity is deliberately NOT baked in. Components pass **attrs straight
+  # through `mix`, so a phlex-reactive `**on(:event)` bundle composes onto the
+  # root element with zero coupling. `on` here is a safe no-op unless the host has
+  # opted into reactivity AND the component includes Phlex::Reactive::Component
+  # (which provides the real `on`).
+  class BaseComponent < Phlex::HTML
+    # No-op fallback. A reactive component includes Phlex::Reactive::Component,
+    # whose own `on` shadows this and returns the real attribute bundle.
+    def on(*, **)
+      {}
+    end
+  end
+end

data/lib/phlex_kit/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PhlexKit
+  # Runtime configuration. Everything has a sane default so the gem works with
+  # zero setup; hosts tune it in an initializer:
+  #
+  #   PhlexKit.configure do |c|
+  #     c.reactive = true          # opt into phlex-reactive integration
+  #     c.define_ui_alias = true   # expose `UI::Button` as an alias for `PhlexKit::Button`
+  #   end
+  class Configuration
+    # :auto (default) enables reactive helpers only when phlex-reactive is
+    # loaded; true forces on (raises if the gem is absent); false forces off.
+    attr_accessor :reactive
+
+    # When true, `UI` is aliased to `PhlexKit`, so revue-style `UI::Button`
+    # call sites work unchanged. Off by default to avoid owning a generic const.
+    attr_accessor :define_ui_alias
+
+    def initialize
+      @reactive = :auto
+      @define_ui_alias = false
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # True when reactive helpers should be active. :auto follows availability.
+    def reactive?
+      case config.reactive
+      when :auto then defined?(Phlex::Reactive)
+      when true
+        defined?(Phlex::Reactive) or
+          raise "PhlexKit.config.reactive = true but phlex-reactive is not loaded — add it to your Gemfile"
+      else false
+      end
+    end
+  end
+end

data/lib/phlex_kit/engine.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module PhlexKit
+  # Turns the four hand-wired pieces from revue (asset path, Zeitwerk collapse,
+  # Propshaft source-skip, JS registration) into engine behavior every host gets
+  # for free.
+  class Engine < ::Rails::Engine
+    # (1) Co-locate CSS beside the .rb: put the component + stylesheet dirs on
+    #     Propshaft's load path so `@import url("phlex_kit/button/button.css")`
+    #     and the manifest resolve and get fingerprinted.
+    initializer "phlex_kit.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/components")
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        # The Stimulus controllers must be servable too, or every importmap pin
+        # from (4) resolves to a missing asset and gets silently skipped.
+        app.config.assets.paths << root.join("app/javascript")
+      end
+    end
+
+    # (2) Collapse component folders so app/components/phlex_kit/button/button.rb
+    #     autoloads as PhlexKit::Button (not PhlexKit::Button::Button), and a part
+    #     like card/card_header.rb is PhlexKit::CardHeader.
+    initializer "phlex_kit.zeitwerk" do
+      autoloader = Rails.autoloaders.main
+      autoloader.collapse(root.join("app/components/phlex_kit/*"))
+    end
+
+    # (3) Keep Propshaft from serving our Ruby source out of public/assets/.
+    initializer "phlex_kit.propshaft_guard" do
+      require "phlex_kit/propshaft_skip_source" if defined?(Propshaft)
+    end
+
+    # (4) Register the Stimulus controllers for interactive components when the
+    #     host uses importmap-rails. Bundler users import from the gem path.
+    initializer "phlex_kit.importmap", before: "importmap" do |app|
+      if app.respond_to?(:config) && app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
+    # (5) Optional convenience alias so revue-style `UI::Button` keeps working.
+    config.after_initialize do
+      Object.const_set(:UI, PhlexKit) if PhlexKit.config.define_ui_alias && !Object.const_defined?(:UI)
+    end
+  end
+end

data/lib/phlex_kit/propshaft_skip_source.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# The gem puts app/components on Propshaft's asset load path so component CSS can
+# sit beside its .rb (see PhlexKit::Engine). Propshaft indexes EVERY non-dotfile
+# in a path directory — it only skips dotfiles, with no extension allowlist — so
+# it would otherwise digest our Ruby source into public/assets/ and serve it as a
+# static file. Teach the load path to skip source files as well as dotfiles.
+#
+# This hooks a PRIVATE Propshaft method; test/assets/asset_load_path_test.rb (and
+# the same guard in a host app) fails loudly if a Propshaft upgrade breaks it.
+module PhlexKit
+  module PropshaftSkipSourceFiles
+    SOURCE_EXTENSIONS = %w[.rb .erb .haml .slim .rbi].freeze
+
+    private def without_dotfiles(files)
+      super.reject { |file| SOURCE_EXTENSIONS.include?(file.extname) }
+    end
+  end
+end
+
+require "propshaft/load_path"
+Propshaft::LoadPath.prepend(PhlexKit::PropshaftSkipSourceFiles)

data/lib/phlex_kit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PhlexKit
+  VERSION = "0.2.0"
+end

data/lib/phlex_kit.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "json" # Carousel serializes its options value standalone (no Rails to_json)
+require "securerandom" # DatePicker generates a default input id
+require "cgi" # DataTable sort/pagination build query strings standalone
+require "phlex"
+require "phlex-rails"
+
+require "phlex_kit/version"
+require "phlex_kit/configuration"
+require "phlex_kit/base_component"
+
+# The Rails engine (asset path, Zeitwerk collapse, Propshaft guard, JS) is only
+# needed inside a Rails app. Load it when Rails is present; the components
+# themselves are plain Phlex classes and work without it.
+require "phlex_kit/engine" if defined?(::Rails::Engine)
+
+module PhlexKit
+  # Components live under app/components/phlex_kit and are autoloaded by the host
+  # app's Zeitwerk (via the engine). Nothing else to require here.
+end