style_capsule 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a5a88ff582594a22522f2b0349e54bfb235d42839a80b29a9118488a09f82df
-  data.tar.gz: 4bf81ae48a9cfe5ef9e0b7c5f8ae00abeb38dbdf7ea2dc930293036b1c375832
+  metadata.gz: d1fcbe6c03f9675593d6dca7b3d7d70de2b7d471d2d938993b59877614332ff4
+  data.tar.gz: 6aa5feb7ff25ef755084e7754f328e4340a0d4dc620e1ea8298badbb0387f254
 SHA512:
-  metadata.gz: a75e75f5c7d04616306d2ddaaea7a528eb2d4179071cb96ff6e360d854e940dddcfbfe271bf65fb3e6b4d5957961e5c116708f4017d5e9becd1ee3a76053bce3
-  data.tar.gz: b7981f706126585a59659ed0c6e3ec61c40a85767ac72c16a9908c6739a5956bcd2bb9c24f20593bc42402ecccfc5a747b042f85b13a07268dfe747555cb56c4
+  metadata.gz: f06af1e47282aa0220b5ff28e5e0a197a8d76eaa9f3c00639958ca1f9d672c7ad1dd4f672b9de83cc7c521af6a49b9c9f9c9bd0ce476575211b1fc7a7aeb1da2
+  data.tar.gz: 3844dd9da6608b1eff6e495e19b92e3f90d4b41df323118f5fa7c6216603d3b33620c80df8aeb13c2e2506e133e3ab6e424c3dfd76feb16dbbc68b37fac72636

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # CHANGELOG
 
+## 1.2.0 (2025-11-24)
+
+- Added `StyleCapsule::ClassRegistry` for Rails-friendly class tracking without ObjectSpace iteration
+- Fixed development environment bug where `ObjectSpace.each_object(Class)` could trigger errors with gems that override `Class#name` (e.g., Faker)
+- Improved `ComponentBuilder` to use ClassRegistry first, with ObjectSpace fallback for compatibility
+- Classes are now automatically registered when including `StyleCapsule::Component` or `StyleCapsule::ViewComponent`
+- Better performance in development mode by tracking only relevant classes instead of iterating all classes
+- Enhanced error handling for classes that cause issues during iteration
+
+## 1.1.0 (2025-11-21)
+
+- Made Rails dependencies optional: `railties` and `activesupport` moved to development dependencies
+- Core functionality now works without Rails (Sinatra, Hanami, plain Ruby, etc.)
+- Rails integration remains fully supported via Railtie
+- Added `StyleCapsule::StandaloneHelper` for non-Rails frameworks
+- `StylesheetRegistry` now works without `ActiveSupport::CurrentAttributes` using thread-local storage fallback
+- Renamed `stylesheet_registrymap_tags` to `stylesheet_registry_tags` (old name kept as deprecated alias)
+- Extracted CSS building logic from Rake tasks into `StyleCapsule::ComponentBuilder`
+- Fixed XSS vulnerability in `escape_html_attr` by using `CGI.escapeHTML` for proper HTML entity escaping
+- Optimized ActiveSupport require to avoid exception handling overhead in Rails apps
+
 ## 1.0.2 (2025-11-21)
 
 - Fix default output directory for CSS files to app/assets/builds/capsules/
@@ -26,4 +47,3 @@
 - Security features: path traversal protection, CSS size limits (1MB), scope ID validation, filename validation
 - Ruby >= 3.0 requirement
 - Comprehensive test suite with > 93% coverage
-

data/README.md

@@ -1,8 +1,8 @@
 # style_capsule
 
-[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=1.0.1)](https://badge.fury.io/rb/style_capsule) [![Test Status](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/style_capsule.rb/graph/badge.svg?token=2U6NXJOVVM)](https://codecov.io/gh/amkisko/style_capsule.rb)
+[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=1.2.0)](https://badge.fury.io/rb/style_capsule) [![Test Status](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/style_capsule.rb/graph/badge.svg?token=2U6NXJOVVM)](https://codecov.io/gh/amkisko/style_capsule.rb)
 
-CSS scoping extension for Rails components. Provides attribute-based style encapsulation for Phlex, ViewComponent, and ERB templates to prevent style leakage between components. Includes configurable caching strategies for optimal performance.
+CSS scoping extension for Ruby components. Provides attribute-based style encapsulation for Phlex, ViewComponent, and ERB templates to prevent style leakage between components. Works with Rails and can be used standalone in other Ruby frameworks (Sinatra, Hanami, etc.) or plain Ruby scripts. Includes configurable caching strategies for optimal performance.
 
 Sponsored by [Kisko Labs](https://www.kiskolabs.com).
 
@@ -161,8 +161,8 @@ Then in your layout:
 
 ```erb
 <head>
-  <%= stylesheet_registrymap_tags %>
-  <%= stylesheet_registrymap_tags(namespace: :admin) %>
+  <%= stylesheet_registry_tags %>
+  <%= stylesheet_registry_tags(namespace: :admin) %>
 </head>
 ```
 
@@ -170,7 +170,7 @@ Or in Phlex (requires including `StyleCapsule::PhlexHelper`):
 
 ```ruby
 head do
-  stylesheet_registrymap_tags
+  stylesheet_registry_tags
 end
 ```
 
@@ -205,7 +205,7 @@ def call
 end
 ```
 
-Registered files are rendered via `stylesheet_registrymap_tags` in your layout, just like inline CSS.
+Registered files are rendered via `stylesheet_registry_tags` in your layout, just like inline CSS.
 
 ## Caching Strategies
 
@@ -332,6 +332,90 @@ end
 - Component-scoped selectors: `:host`, `:host(.active)`, `:host-context(.theme-dark)`
 - Media queries: `@media (max-width: 768px) { ... }`
 
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 6.0, < 9.0 (optional, for Rails integration)
+- ActiveSupport >= 6.0, < 9.0 (optional, for Rails integration)
+
+**Note**: The gem can be used without Rails! See [Non-Rails Support](#non-rails-support) below.
+
+## Non-Rails Support
+
+StyleCapsule can be used without Rails! The core functionality is framework-agnostic.
+
+### Standalone Usage
+
+```ruby
+require 'style_capsule'
+
+# Direct CSS processing
+css = ".section { color: red; }"
+capsule_id = "abc123"
+scoped = StyleCapsule::CssProcessor.scope_selectors(css, capsule_id)
+# => "[data-capsule=\"abc123\"] .section { color: red; }"
+```
+
+### Phlex Without Rails
+
+```ruby
+require 'phlex'
+require 'style_capsule'
+
+class MyComponent < Phlex::HTML
+  include StyleCapsule::Component
+  
+  def component_styles
+    <<~CSS
+      .section { color: red; }
+    CSS
+  end
+  
+  def view_template
+    div(class: "section") { "Hello" }
+  end
+end
+```
+
+### Sinatra
+
+```ruby
+require 'sinatra'
+require 'style_capsule'
+
+class MyApp < Sinatra::Base
+  helpers StyleCapsule::StandaloneHelper
+  
+  get '/' do
+    erb :index
+  end
+end
+```
+
+```erb
+<!-- views/index.erb -->
+<%= style_capsule do %>
+  <style>
+    .section { color: red; }
+  </style>
+  <div class="section">Content</div>
+<% end %>
+```
+
+### Stylesheet Registry Without Rails
+
+The stylesheet registry automatically uses thread-local storage when ActiveSupport is not available:
+
+```ruby
+require 'style_capsule'
+
+# Works without Rails
+StyleCapsule::StylesheetRegistry.register_inline(".test { color: red; }", namespace: :test)
+stylesheets = StyleCapsule::StylesheetRegistry.request_inline_stylesheets
+```
+
+For more details, see [docs/non_rails_support.md](docs/non_rails_support.md).
+
 ## How It Works
 
 1. **Scope ID Generation**: Each component class gets a unique scope ID based on its class name (shared across all instances)
@@ -339,12 +423,6 @@ end
 3. **HTML Wrapping**: Component content is automatically wrapped in a scoped element
 4. **No Class Renaming**: Class names remain unchanged (unlike Shadow DOM)
 
-## Requirements
-
-- Ruby >= 3.0
-- Rails >= 7.0, < 9.0
-- ActiveSupport >= 7.0, < 9.0
-
 ## Development
 
 ```bash
@@ -395,4 +473,4 @@ For detailed security information, see [SECURITY.md](SECURITY.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE.md).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/style_capsule/class_registry.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Registry for tracking classes that include StyleCapsule modules
+  #
+  # This provides a Rails-friendly way to track classes without using ObjectSpace,
+  # which can be problematic with certain gems (e.g., Faker) that override Class#name.
+  #
+  # Classes are automatically registered when they include StyleCapsule::Component
+  # or StyleCapsule::ViewComponent.
+  #
+  # @example
+  #   # Classes are automatically registered when they include modules
+  #   class MyComponent < ApplicationComponent
+  #     include StyleCapsule::Component  # Automatically registered
+  #   end
+  #
+  #   # Iterate over registered classes
+  #   StyleCapsule::ClassRegistry.each do |klass|
+  #     klass.clear_css_cache if klass.respond_to?(:clear_css_cache)
+  #   end
+  #
+  #   # Clear registry (useful in development when classes are reloaded)
+  #   StyleCapsule::ClassRegistry.clear
+  class ClassRegistry
+    # Use Set for O(1) lookups instead of O(n) with Array#include?
+    @classes = Set.new
+
+    class << self
+      # Register a class that includes a StyleCapsule module
+      #
+      # @param klass [Class] The class to register
+      # @return [void]
+      def register(klass)
+        return if klass.nil?
+        return if klass.singleton_class?
+
+        # Only register classes with names (skip anonymous classes)
+        begin
+          name = klass.name
+          return if name.nil? || name.to_s.strip.empty?
+        rescue
+          # Skip classes that cause errors when calling name (e.g., ArgumentError, NoMethodError, NameError)
+          return
+        end
+
+        @classes.add(klass)
+      end
+
+      # Remove a class from the registry
+      #
+      # @param klass [Class] The class to unregister
+      # @return [void]
+      def unregister(klass)
+        @classes.delete(klass)
+      end
+
+      # Iterate over all registered classes
+      #
+      # @yield [Class] Each registered class
+      # @return [void]
+      def each(&block)
+        # Filter out classes that no longer exist or have been unloaded
+        # Use delete_if for Set (equivalent to reject! for Array)
+        @classes.delete_if do |klass|
+          # Check if class still exists and is valid
+          klass.name.nil? || klass.singleton_class?
+        rescue
+          # Class has been unloaded or causes errors - remove from registry
+          true
+        end
+
+        @classes.each(&block)
+      end
+
+      # Get all registered classes
+      #
+      # @return [Array<Class>] Array of registered classes
+      def all
+        # Filter out invalid classes
+        each.to_a
+      end
+
+      # Clear the registry
+      #
+      # Useful in development when classes are reloaded.
+      #
+      # @return [void]
+      def clear
+        @classes.clear
+      end
+
+      # Get the number of registered classes
+      #
+      # @return [Integer]
+      def count
+        each.count
+      end
+    end
+  end
+end

data/lib/style_capsule/component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "digest/sha1"
-require "active_support/core_ext/string"
+# ActiveSupport string extensions are conditionally required in lib/style_capsule.rb
 
 module StyleCapsule
   # Phlex component concern for encapsulated CSS
@@ -89,6 +89,9 @@ module StyleCapsule
 
       # Use prepend to wrap view_template method
       base.prepend(ViewTemplateWrapper)
+
+      # Register class for Rails-friendly tracking
+      ClassRegistry.register(base)
     end
 
     module ClassMethods

data/lib/style_capsule/component_builder.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Builds CSS files from StyleCapsule components
+  #
+  # This class extracts the logic from the rake task so it can be tested independently.
+  # The rake task delegates to this class.
+  class ComponentBuilder
+    class << self
+      # Check if Phlex is available
+      # This method can be stubbed in tests to test fallback paths
+      def phlex_available?
+        !!defined?(Phlex::HTML)
+      end
+
+      # Check if ViewComponent is available
+      # This method can be stubbed in tests to test fallback paths
+      def view_component_available?
+        !!defined?(ViewComponent::Base)
+      end
+
+      # Find all Phlex components that use StyleCapsule
+      #
+      # Uses ClassRegistry to find registered components (Rails-friendly, avoids expensive ObjectSpace scanning).
+      # Classes are automatically registered when they include StyleCapsule::Component.
+      #
+      # @return [Array<Class>] Array of component classes
+      def find_phlex_components
+        return [] unless phlex_available?
+
+        components = []
+
+        # Use the registry (Rails-friendly, avoids expensive ObjectSpace scanning)
+        ClassRegistry.each do |klass|
+          if klass < Phlex::HTML && klass.included_modules.include?(StyleCapsule::Component)
+            components << klass
+          end
+        rescue
+          # Skip classes that cause errors (inheritance checks, etc.)
+          next
+        end
+
+        components
+      end
+
+      # Find all ViewComponent components that use StyleCapsule
+      #
+      # Uses ClassRegistry to find registered components (Rails-friendly, avoids expensive ObjectSpace scanning).
+      # Classes are automatically registered when they include StyleCapsule::ViewComponent.
+      #
+      # @return [Array<Class>] Array of component classes
+      def find_view_components
+        return [] unless view_component_available?
+
+        components = []
+
+        begin
+          # Use the registry (Rails-friendly, avoids expensive ObjectSpace scanning)
+          ClassRegistry.each do |klass|
+            if klass < ViewComponent::Base && klass.included_modules.include?(StyleCapsule::ViewComponent)
+              components << klass
+            end
+          rescue
+            # Skip classes that cause errors (inheritance checks, etc.)
+            next
+          end
+        rescue
+          # ViewComponent may have loading issues (e.g., version compatibility)
+          # Silently skip ViewComponent components if there's an error
+          # This allows the rake task to continue with Phlex components
+        end
+
+        components
+      end
+
+      # Collect all component classes that use StyleCapsule
+      #
+      # @return [Array<Class>] Array of component classes
+      def collect_components
+        find_phlex_components + find_view_components
+      end
+
+      # Build CSS file for a single component
+      #
+      # @param component_class [Class] Component class to build
+      # @param output_proc [Proc, nil] Optional proc to call with output messages
+      # @return [String, nil] Generated file path or nil if skipped
+      def build_component(component_class, output_proc: nil)
+        return nil unless component_class.inline_cache_strategy == :file
+        # Check for class method component_styles (required for file caching)
+        return nil unless component_class.respond_to?(:component_styles, false)
+
+        begin
+          # Use class method component_styles for file caching
+          css_content = component_class.component_styles
+          return nil if css_content.nil? || css_content.to_s.strip.empty?
+
+          # Create a temporary instance to get capsule
+          # Some components might require arguments, so we catch errors
+          instance = component_class.new
+          capsule_id = instance.component_capsule
+          scoped_css = instance.send(:scope_css, css_content)
+
+          # Write CSS file
+          file_path = CssFileWriter.write_css(
+            css_content: scoped_css,
+            component_class: component_class,
+            capsule_id: capsule_id
+          )
+
+          output_proc&.call("Generated: #{file_path}") if file_path
+          file_path
+        rescue ArgumentError, NoMethodError => e
+          # Component requires arguments or has dependencies - skip it
+          output_proc&.call("Skipped #{component_class.name}: #{e.message}")
+          nil
+        end
+      end
+
+      # Build CSS files for all components
+      #
+      # @param output_proc [Proc, nil] Optional proc to call with output messages
+      # @return [Integer] Number of files generated
+      def build_all(output_proc: nil)
+        require "style_capsule/css_file_writer"
+
+        # Ensure output directory exists
+        CssFileWriter.ensure_output_directory
+
+        # Collect all component classes that use StyleCapsule
+        component_classes = collect_components
+
+        # Generate CSS files for each component
+        generated_count = 0
+        component_classes.each do |component_class|
+          file_path = build_component(component_class, output_proc: output_proc)
+          generated_count += 1 if file_path
+        end
+
+        output_proc&.call("StyleCapsule CSS files built successfully")
+        generated_count
+      end
+    end
+  end
+end

data/lib/style_capsule/css_file_writer.rb

@@ -52,7 +52,7 @@ module StyleCapsule
 
         @output_dir = if output_dir
           output_dir.is_a?(Pathname) ? output_dir : Pathname.new(output_dir.to_s)
-        elsif defined?(Rails) && Rails.root
+        elsif rails_available?
           Rails.root.join(DEFAULT_OUTPUT_DIR)
         else
           Pathname.new(DEFAULT_OUTPUT_DIR)
@@ -154,11 +154,17 @@ module StyleCapsule
         @enabled != false
       end
 
+      # Check if Rails is available
+      # This method can be stubbed in tests to test fallback paths
+      def rails_available?
+        defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      end
+
       private
 
       # Get output directory (with default)
       def output_directory
-        @output_dir ||= if defined?(Rails) && Rails.root
+        @output_dir ||= if rails_available?
           Rails.root.join(DEFAULT_OUTPUT_DIR)
         else
           Pathname.new(DEFAULT_OUTPUT_DIR)
@@ -206,7 +212,7 @@ module StyleCapsule
 
       # Get Rails assets root (app/assets)
       def rails_assets_root
-        if defined?(Rails) && Rails.root
+        if rails_available?
           Rails.root.join("app/assets")
         else
           Pathname.new("app/assets")

data/lib/style_capsule/helper.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "digest/sha1"
-require "active_support/core_ext/string"
+# ActiveSupport string extensions are conditionally required in lib/style_capsule.rb
 
 module StyleCapsule
   # ERB Helper module for use in Rails views
@@ -148,16 +148,20 @@ module StyleCapsule
       StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
     end
 
-    # Render StyleCapsule registered stylesheets (similar to javascript_importmap_tags)
+    # Render StyleCapsule registered stylesheets
     #
     # Usage in ERB:
-    #   <%= stylesheet_registrymap_tags %>
-    #   <%= stylesheet_registrymap_tags(namespace: :admin) %>
+    #   <%= stylesheet_registry_tags %>
+    #   <%= stylesheet_registry_tags(namespace: :admin) %>
     #
     # @param namespace [Symbol, String, nil] Optional namespace to render (nil/blank renders all)
     # @return [String] HTML-safe string with stylesheet tags
-    def stylesheet_registrymap_tags(namespace: nil)
+    def stylesheet_registry_tags(namespace: nil)
       StyleCapsule::StylesheetRegistry.render_head_stylesheets(self, namespace: namespace)
     end
+
+    # @deprecated Use {#stylesheet_registry_tags} instead.
+    #   This method name will be removed in a future version.
+    alias_method :stylesheet_registrymap_tags, :stylesheet_registry_tags
   end
 end

data/lib/style_capsule/phlex_helper.rb

@@ -36,17 +36,17 @@ module StyleCapsule
       StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
     end
 
-    # Render StyleCapsule registered stylesheets (similar to javascript_importmap_tags)
+    # Render StyleCapsule registered stylesheets
     #
     # Usage in Phlex layouts:
     #   head do
-    #     stylesheet_registrymap_tags
-    #     stylesheet_registrymap_tags(namespace: :admin)
+    #     stylesheet_registry_tags
+    #     stylesheet_registry_tags(namespace: :admin)
     #   end
     #
     # @param namespace [Symbol, String, nil] Optional namespace to render (nil/blank renders all)
     # @return [void] Renders stylesheet tags via raw
-    def stylesheet_registrymap_tags(namespace: nil)
+    def stylesheet_registry_tags(namespace: nil)
       output = StyleCapsule::StylesheetRegistry.render_head_stylesheets(view_context, namespace: namespace)
       # Phlex's raw() requires the object to be marked as safe
       # Use Phlex's safe() if available, otherwise fall back to html_safe for test doubles
@@ -62,5 +62,9 @@ module StyleCapsule
       # Always return the output string for testing/compatibility
       output_string
     end
+
+    # @deprecated Use {#stylesheet_registry_tags} instead.
+    #   This method name will be removed in a future version.
+    alias_method :stylesheet_registrymap_tags, :stylesheet_registry_tags
   end
 end

data/lib/style_capsule/railtie.rb

@@ -31,24 +31,16 @@ module StyleCapsule
       # This prevents memory leaks from stale cache entries during code reloading
       if Rails.env.development?
         config.to_prepare do
-          # Clear CSS caches for all classes that include StyleCapsule modules
-          # Skip singleton classes and handle errors gracefully
-          ObjectSpace.each_object(Class) do |klass|
-            # Skip singleton classes and classes without names (they can cause errors)
-            # Singleton classes don't have proper names and can't be safely checked
-            next if klass.name.blank?
-            next if klass.singleton_class?
-
-            # Use method_defined? instead of respond_to? to avoid triggering delegation
-            # that might cause errors with singleton classes or other edge cases
-            begin
-              if klass.method_defined?(:clear_css_cache, false) || klass.private_method_defined?(:clear_css_cache)
-                klass.clear_css_cache
-              end
-            rescue
-              # Skip classes that cause errors (singleton classes, delegation issues, etc.)
-              next
+          # Use Rails-friendly class registry instead of ObjectSpace iteration
+          # This avoids issues with gems that override Class#name (e.g., Faker)
+          StyleCapsule::ClassRegistry.each do |klass|
+            # Clear CSS cache if the class has this method
+            if klass.method_defined?(:clear_css_cache, false) || klass.private_method_defined?(:clear_css_cache)
+              klass.clear_css_cache
             end
+          rescue
+            # Skip classes that cause errors (unloaded classes, etc.)
+            next
           end
 
           # Clear stylesheet manifest to allow re-registration during code reload