style_capsule 1.2.0

data/lib/style_capsule/helper.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+# ActiveSupport string extensions are conditionally required in lib/style_capsule.rb
+
+module StyleCapsule
+  # ERB Helper module for use in Rails views
+  #
+  # This module is automatically included in ActionView::Base via Railtie.
+  # No manual inclusion is required - helpers are available in all ERB templates.
+  #
+  # Usage in ERB templates:
+  #
+  #   <%= style_capsule do %>
+  #     <style>
+  #       .section { color: red; }
+  #       .heading:hover { opacity: 0.8; }
+  #     </style>
+  #     <div class="section">
+  #       <h2 class="heading">Hello</h2>
+  #     </div>
+  #   <% end %>
+  #
+  # The CSS will be automatically scoped and content wrapped in a scoped div.
+  # The <style> tag will be extracted and processed separately.
+  module Helper
+    # Maximum HTML content size (10MB) to prevent DoS attacks
+    MAX_HTML_SIZE = 10_000_000
+    # Generate capsule ID based on caller location for uniqueness
+    def generate_capsule_id(css_content)
+      # Use caller location + CSS content for uniqueness
+      caller_info = caller_locations(1, 1).first
+      capsule_key = "#{caller_info.path}:#{caller_info.lineno}:#{css_content}"
+      "a#{Digest::SHA1.hexdigest(capsule_key)}"[0, 8]
+    end
+
+    # Scope CSS content and return scoped CSS
+    def scope_css(css_content, capsule_id)
+      # Use thread-local cache to avoid reprocessing
+      cache_key = "style_capsule_#{capsule_id}"
+
+      if Thread.current[cache_key]
+        return Thread.current[cache_key]
+      end
+
+      scoped_css = CssProcessor.scope_selectors(css_content, capsule_id)
+      Thread.current[cache_key] = scoped_css
+      scoped_css
+    end
+
+    # ERB helper: automatically wraps content in scoped div and processes CSS
+    #
+    # Extracts <style> tags from content, processes them, and wraps everything
+    # in a scoped div. CSS can be in <style> tags or as a separate block.
+    #
+    # Usage:
+    #   <%= style_capsule do %>
+    #     <style>
+    #       .section { color: red; }
+    #       .heading:hover { opacity: 0.8; }
+    #     </style>
+    #     <div class="section">
+    #       <h2 class="heading">Hello</h2>
+    #     </div>
+    #   <% end %>
+    #
+    # Or with CSS as separate content:
+    #   <% css_content = capture do %>
+    #     .section { color: red; }
+    #   <% end %>
+    #   <%= style_capsule(css_content) do %>
+    #     <div class="section">Content</div>
+    #   <% end %>
+    #
+    # Or with manual capsule ID (for testing/exact naming):
+    #   <%= style_capsule(capsule_id: "test-123") do %>
+    #     <style>.section { color: red; }</style>
+    #     <div class="section">Content</div>
+    #   <% end %>
+    #
+    # Or with both CSS content and manual capsule ID:
+    #   <% css_content = ".section { color: red; }" %>
+    #   <%= style_capsule(css_content, capsule_id: "test-123") do %>
+    #     <div class="section">Content</div>
+    #   <% end %>
+    def style_capsule(css_content = nil, capsule_id: nil, &content_block)
+      html_content = nil
+
+      # If CSS content is provided as argument, use it
+      # Otherwise, extract from content block
+      if css_content.nil? && block_given?
+        full_content = capture(&content_block)
+
+        # Validate HTML content size to prevent DoS attacks
+        if full_content.bytesize > MAX_HTML_SIZE
+          raise ArgumentError, "HTML content exceeds maximum size of #{MAX_HTML_SIZE} bytes (got #{full_content.bytesize} bytes)"
+        end
+
+        # Extract <style> tags from content
+        # Note: Pattern uses non-greedy matching (.*?) to minimize backtracking
+        # Size limit (MAX_HTML_SIZE) mitigates ReDoS risk from malicious input
+        style_match = full_content.match(/<style[^>]*>(.*?)<\/style>/m)
+        if style_match
+          css_content = style_match[1]
+          # Use sub instead of gsub to only remove first occurrence (reduces backtracking)
+          html_content = full_content.sub(/<style[^>]*>.*?<\/style>/m, "").strip
+        else
+          # No style tag found, treat entire content as HTML
+          css_content = nil
+          html_content = full_content
+        end
+      elsif css_content && block_given?
+        html_content = capture(&content_block)
+      elsif css_content && !block_given?
+        # CSS provided but no content block - just return scoped CSS
+        capsule_id ||= generate_capsule_id(css_content)
+        scoped_css = scope_css(css_content, capsule_id)
+        return content_tag(:style, raw(scoped_css), type: "text/css").html_safe
+      else
+        return ""
+      end
+
+      # If no CSS, just return content
+      return html_content.html_safe if css_content.nil? || css_content.to_s.strip.empty?
+
+      # Use provided capsule_id or generate one
+      capsule_id ||= generate_capsule_id(css_content)
+      scoped_css = scope_css(css_content, capsule_id)
+
+      # Render style tag and wrapped content
+      style_tag = content_tag(:style, raw(scoped_css), type: "text/css")
+      wrapped_content = content_tag(:div, raw(html_content), data: {capsule: capsule_id})
+
+      (style_tag + wrapped_content).html_safe
+    end
+
+    # Register a stylesheet file for head rendering
+    #
+    # Usage in ERB:
+    #   <% register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload") %>
+    #   <% register_stylesheet("stylesheets/admin/dashboard", namespace: :admin) %>
+    #
+    # @param file_path [String] Path to stylesheet (relative to app/assets/stylesheets)
+    # @param namespace [Symbol, String, nil] Optional namespace for separation (nil/blank uses default)
+    # @param options [Hash] Options for stylesheet_link_tag
+    # @return [void]
+    def register_stylesheet(file_path, namespace: nil, **options)
+      StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
+    end
+
+    # Render StyleCapsule registered stylesheets
+    #
+    # Usage in ERB:
+    #   <%= 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_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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Phlex helper module for StyleCapsule stylesheet registry
+  #
+  # Include this in your base Phlex component class (e.g., ApplicationComponent):
+  #   class ApplicationComponent < Phlex::HTML
+  #     include StyleCapsule::PhlexHelper
+  #   end
+  #
+  # Usage in Phlex layouts:
+  #   head do
+  #     stylesheet_registrymap_tags
+  #   end
+  #
+  # Usage in Phlex components:
+  #   def view_template
+  #     register_stylesheet("stylesheets/user/my_component")
+  #     div { "Content" }
+  #   end
+  module PhlexHelper
+    # Register a stylesheet file for head rendering
+    #
+    # Usage in Phlex components:
+    #   def view_template
+    #     register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload")
+    #     register_stylesheet("stylesheets/admin/dashboard", namespace: :admin)
+    #     div { "Content" }
+    #   end
+    #
+    # @param file_path [String] Path to stylesheet (relative to app/assets/stylesheets)
+    # @param namespace [Symbol, String, nil] Optional namespace for separation (nil/blank uses default)
+    # @param options [Hash] Options for stylesheet_link_tag
+    # @return [void]
+    def register_stylesheet(file_path, namespace: nil, **options)
+      StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
+    end
+
+    # Render StyleCapsule registered stylesheets
+    #
+    # Usage in Phlex layouts:
+    #   head do
+    #     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_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
+      # The output from render_head_stylesheets is already html_safe (SafeBuffer)
+      output_string = output.to_s
+
+      if respond_to?(:safe)
+        # Real Phlex component - use raw() for rendering
+        safe_content = safe(output_string)
+        raw(safe_content)
+      end
+
+      # 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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Railtie to automatically include StyleCapsule helpers in Rails
+  if defined?(Rails::Railtie)
+    class Railtie < Rails::Railtie
+      # Automatically include ERB helper in ActionView::Base (standard Rails pattern)
+      # This makes helpers available in all ERB templates automatically
+      ActiveSupport.on_load(:action_view) do
+        include StyleCapsule::Helper
+      end
+
+      # Configure CSS file writer for file-based caching
+      config.after_initialize do
+        # Configure default output directory
+        StyleCapsule::CssFileWriter.configure(
+          output_dir: Rails.root.join(StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR),
+          enabled: true
+        )
+
+        # Add output directory to asset paths if it exists
+        if Rails.application.config.respond_to?(:assets)
+          capsules_dir = Rails.root.join(StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR)
+          if Dir.exist?(capsules_dir)
+            Rails.application.config.assets.paths << capsules_dir
+          end
+        end
+      end
+
+      # Clear CSS caches and stylesheet manifest when classes are unloaded in development
+      # This prevents memory leaks from stale cache entries during code reloading
+      if Rails.env.development?
+        config.to_prepare do
+          # 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
+          StyleCapsule::StylesheetRegistry.clear_manifest
+        end
+      end
+
+      # Load rake tasks for CSS file building
+      rake_tasks do
+        load File.expand_path("../tasks/style_capsule.rake", __dir__)
+      end
+
+      # Note: PhlexHelper should be included explicitly in ApplicationComponent
+      # or your base Phlex component class, not automatically via Railtie
+    end
+  end
+end

data/lib/style_capsule/standalone_helper.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+require "cgi"
+
+module StyleCapsule
+  # Standalone helper module for use without Rails
+  #
+  # This module provides basic HTML generation and CSS scoping functionality
+  # without requiring Rails ActionView helpers. It can be included in any
+  # framework's view context or used directly.
+  #
+  # @example Usage in Sinatra
+  #   class MyApp < Sinatra::Base
+  #     helpers StyleCapsule::StandaloneHelper
+  #   end
+  #
+  # @example Usage in plain Ruby
+  #   class MyView
+  #     include StyleCapsule::StandaloneHelper
+  #   end
+  #
+  # @example Usage in ERB (non-Rails)
+  #   # In your ERB template context
+  #   include StyleCapsule::StandaloneHelper
+  #   style_capsule do
+  #     "<style>.section { color: red; }</style><div class='section'>Content</div>"
+  #   end
+  module StandaloneHelper
+    # Maximum HTML content size (10MB) to prevent DoS attacks
+    MAX_HTML_SIZE = 10_000_000
+
+    # Generate capsule ID based on caller location for uniqueness
+    def generate_capsule_id(css_content)
+      # Use caller location + CSS content for uniqueness
+      caller_info = caller_locations(1, 1).first
+      capsule_key = "#{caller_info.path}:#{caller_info.lineno}:#{css_content}"
+      "a#{Digest::SHA1.hexdigest(capsule_key)}"[0, 8]
+    end
+
+    # Scope CSS content and return scoped CSS
+    def scope_css(css_content, capsule_id)
+      # Use thread-local cache to avoid reprocessing
+      cache_key = "style_capsule_#{capsule_id}"
+
+      if Thread.current[cache_key]
+        return Thread.current[cache_key]
+      end
+
+      scoped_css = CssProcessor.scope_selectors(css_content, capsule_id)
+      Thread.current[cache_key] = scoped_css
+      scoped_css
+    end
+
+    # Generate HTML tag without Rails helpers
+    #
+    # @param tag [String, Symbol] HTML tag name
+    # @param content [String, nil] Tag content (or use block)
+    # @param options [Hash] HTML attributes
+    # @param block [Proc] Block for tag content
+    # @return [String] HTML string
+    def content_tag(tag, content = nil, **options, &block)
+      tag_name = tag.to_s
+      content = capture(&block) if block_given? && content.nil?
+      content ||= ""
+
+      attrs = options.map do |k, v|
+        if v.is_a?(Hash)
+          # Handle nested attributes like data: { capsule: "abc" }
+          v.map { |nk, nv| %(#{k}-#{nk}="#{escape_html_attr(nv)}") }.join(" ")
+        else
+          %(#{k}="#{escape_html_attr(v)}")
+        end
+      end.join(" ")
+
+      attrs = " #{attrs}" unless attrs.empty?
+      "<#{tag_name}#{attrs}>#{content}</#{tag_name}>"
+    end
+
+    # Capture block content (simplified version without Rails)
+    #
+    # @param block [Proc] Block to capture
+    # @return [String] Captured content
+    def capture(&block)
+      return "" unless block_given?
+      block.call.to_s
+    end
+
+    # Mark string as HTML-safe (for compatibility)
+    #
+    # @param string [String] String to mark as safe
+    # @return [String] HTML-safe string
+    def html_safe(string)
+      # In non-Rails context, just return the string
+      # If ActiveSupport is available, use its html_safe
+      if string.respond_to?(:html_safe)
+        string.html_safe
+      else
+        string
+      end
+    end
+
+    # Raw string (no HTML escaping)
+    #
+    # @param string [String] String to return as-is
+    # @return [String] Raw string
+    def raw(string)
+      html_safe(string.to_s)
+    end
+
+    # ERB helper: automatically wraps content in scoped div and processes CSS
+    #
+    # @param css_content [String, nil] CSS content (or extract from block)
+    # @param capsule_id [String, nil] Optional capsule ID
+    # @param content_block [Proc] Block containing HTML content
+    # @return [String] HTML with scoped CSS and wrapped content
+    def style_capsule(css_content = nil, capsule_id: nil, &content_block)
+      html_content = nil
+
+      # If CSS content is provided as argument, use it
+      # Otherwise, extract from content block
+      if css_content.nil? && block_given?
+        full_content = capture(&content_block)
+
+        # Validate HTML content size to prevent DoS attacks
+        if full_content.bytesize > MAX_HTML_SIZE
+          raise ArgumentError, "HTML content exceeds maximum size of #{MAX_HTML_SIZE} bytes (got #{full_content.bytesize} bytes)"
+        end
+
+        # Extract <style> tags from content
+        style_match = full_content.match(/<style[^>]*>(.*?)<\/style>/m)
+        if style_match
+          css_content = style_match[1]
+          html_content = full_content.sub(/<style[^>]*>.*?<\/style>/m, "").strip
+        else
+          css_content = nil
+          html_content = full_content
+        end
+      elsif css_content && block_given?
+        html_content = capture(&content_block)
+      elsif css_content && !block_given?
+        # CSS provided but no content block - just return scoped CSS
+        capsule_id ||= generate_capsule_id(css_content)
+        scoped_css = scope_css(css_content, capsule_id)
+        return content_tag(:style, raw(scoped_css), type: "text/css")
+      else
+        return ""
+      end
+
+      # If no CSS, just return content
+      return html_safe(html_content) if css_content.nil? || css_content.to_s.strip.empty?
+
+      # Use provided capsule_id or generate one
+      capsule_id ||= generate_capsule_id(css_content)
+      scoped_css = scope_css(css_content, capsule_id)
+
+      # Render style tag and wrapped content
+      style_tag = content_tag(:style, raw(scoped_css), type: "text/css")
+      wrapped_content = content_tag(:div, raw(html_content), data: {capsule: capsule_id})
+
+      html_safe(style_tag + wrapped_content)
+    end
+
+    # Register a stylesheet file for head rendering
+    #
+    # @param file_path [String] Path to stylesheet
+    # @param namespace [Symbol, String, nil] Optional namespace
+    # @param options [Hash] Options for stylesheet link tag
+    # @return [void]
+    def register_stylesheet(file_path, namespace: nil, **options)
+      StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
+    end
+
+    # Render StyleCapsule registered stylesheets
+    #
+    # @param namespace [Symbol, String, nil] Optional namespace to render
+    # @return [String] HTML-safe string with stylesheet tags
+    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
+
+    private
+
+    # Escape HTML attribute value
+    #
+    # @param value [String] Value to escape
+    # @return [String] Escaped value
+    def escape_html_attr(value)
+      CGI.escapeHTML(value.to_s)
+    end
+  end
+end