style_capsule 1.2.0

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/component_styles_support.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Shared module for component styles support (used by both Component and ViewComponent)
+  #
+  # Provides unified support for both instance and class method component_styles:
+  # - Instance method: `def component_styles` - dynamic rendering, supports all cache strategies except :file
+  # - Class method: `def self.component_styles` - static rendering, supports all cache strategies including :file
+  module ComponentStylesSupport
+    # Check if component defines styles (instance or class method)
+    #
+    # @return [Boolean]
+    def component_styles?
+      instance_styles? || class_styles?
+    end
+
+    # Resolve component styles (from instance or class method)
+    #
+    # @return [String, nil] CSS content or nil if no styles defined
+    def component_styles_content
+      # Prefer instance method for dynamic rendering
+      if instance_styles?
+        component_styles
+      elsif class_styles?
+        self.class.component_styles
+      end
+    end
+
+    # Check if component uses class method styles exclusively (required for file caching)
+    #
+    # Returns true only if class styles are defined and instance styles are not.
+    #
+    # @return [Boolean]
+    def class_styles_only?
+      class_styles? && !instance_styles?
+    end
+
+    # Check if file caching is allowed for this component
+    #
+    # File caching is only allowed for class method component_styles
+    #
+    # @return [Boolean]
+    def file_caching_allowed?
+      cache_strategy = self.class.inline_cache_strategy
+      return false unless cache_strategy == :file
+      class_styles_only?
+    end
+
+    private
+
+    # Check if component defines instance method styles
+    #
+    # @return [Boolean]
+    def instance_styles?
+      return false unless respond_to?(:component_styles, true)
+      styles = component_styles
+      styles && !styles.to_s.strip.empty?
+    end
+
+    # Check if component defines class method styles
+    #
+    # @return [Boolean]
+    def class_styles?
+      return false unless self.class.respond_to?(:component_styles, false)
+      begin
+        styles = self.class.component_styles
+        styles && !styles.to_s.strip.empty?
+      rescue NoMethodError
+        false
+      end
+    end
+  end
+end

data/lib/style_capsule/css_file_writer.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "digest/sha1"
+
+module StyleCapsule
+  # Writes inline CSS to files for HTTP caching
+  #
+  # This allows inline CSS to be cached by browsers and CDNs, improving performance.
+  # Files are written to a configurable output directory and can be precompiled
+  # via Rails asset pipeline.
+  #
+  # @example Configuration
+  #   StyleCapsule::CssFileWriter.configure(
+  #     output_dir: Rails.root.join(StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR),
+  #     filename_pattern: ->(component_class, capsule_id) { "capsule-#{capsule_id}.css" }
+  #   )
+  #
+  # @example Usage
+  #   file_path = StyleCapsule::CssFileWriter.write_css(
+  #     css_content: ".section { color: red; }",
+  #     component_class: MyComponent,
+  #     capsule_id: "abc123"
+  #   )
+  #   # => "capsules/capsule-abc123"
+  class CssFileWriter
+    # Default output directory for CSS files (relative to Rails root)
+    DEFAULT_OUTPUT_DIR = "app/assets/builds/capsules"
+
+    class << self
+      attr_accessor :output_dir, :filename_pattern, :enabled
+
+      # Configure CSS file writer
+      #
+      # @param output_dir [String, Pathname] Directory to write CSS files (relative to Rails root or absolute)
+      #   Default: `StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR`
+      # @param filename_pattern [Proc, nil] Proc to generate filename
+      #   Receives: (component_class, capsule_id) and should return filename string
+      #   Default: `"capsule-#{capsule_id}.css"` (capsule_id is unique and deterministic)
+      # @param enabled [Boolean] Whether file writing is enabled (default: true)
+      # @example
+      #   StyleCapsule::CssFileWriter.configure(
+      #     output_dir: Rails.root.join(StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR),
+      #     filename_pattern: ->(klass, capsule) { "capsule-#{capsule}.css" }
+      #   )
+      # @example Custom pattern with component name
+      #   StyleCapsule::CssFileWriter.configure(
+      #     filename_pattern: ->(klass, capsule) { "#{klass.name.underscore}-#{capsule}.css" }
+      #   )
+      def configure(output_dir: nil, filename_pattern: nil, enabled: true)
+        @enabled = enabled
+
+        @output_dir = if output_dir
+          output_dir.is_a?(Pathname) ? output_dir : Pathname.new(output_dir.to_s)
+        elsif rails_available?
+          Rails.root.join(DEFAULT_OUTPUT_DIR)
+        else
+          Pathname.new(DEFAULT_OUTPUT_DIR)
+        end
+
+        @filename_pattern = filename_pattern || default_filename_pattern
+      end
+
+      # Write CSS content to file
+      #
+      # @param css_content [String] CSS content to write
+      # @param component_class [Class] Component class that generated the CSS
+      # @param capsule_id [String] Capsule ID for the component
+      # @return [String, nil] Relative file path (for stylesheet_link_tag) or nil if disabled
+      def write_css(css_content:, component_class:, capsule_id:)
+        return nil unless enabled?
+
+        ensure_output_directory
+
+        filename = generate_filename(component_class, capsule_id)
+        file_path = output_directory.join(filename)
+
+        # Write CSS to file with explicit UTF-8 encoding
+        File.write(file_path, css_content, encoding: "UTF-8")
+
+        # Return relative path for stylesheet_link_tag
+        # Path should be relative to app/assets
+        # Handle case where output directory is not under rails_assets_root (e.g., in tests)
+        begin
+          file_path.relative_path_from(rails_assets_root).to_s.gsub(/\.css$/, "")
+        rescue ArgumentError
+          # If paths don't share a common prefix (e.g., in tests), return just the filename
+          filename.gsub(/\.css$/, "")
+        end
+      end
+
+      # Check if file exists for given component and capsule
+      #
+      # @param component_class [Class] Component class
+      # @param capsule_id [String] Capsule ID
+      # @return [Boolean]
+      def file_exists?(component_class:, capsule_id:)
+        return false unless enabled?
+
+        filename = generate_filename(component_class, capsule_id)
+        file_path = output_directory.join(filename)
+        File.exist?(file_path)
+      end
+
+      # Get file path for given component and capsule
+      #
+      # @param component_class [Class] Component class
+      # @param capsule_id [String] Capsule ID
+      # @return [String, nil] Relative file path or nil if disabled
+      def file_path_for(component_class:, capsule_id:)
+        return nil unless enabled?
+
+        filename = generate_filename(component_class, capsule_id)
+        file_path = output_directory.join(filename)
+
+        return nil unless File.exist?(file_path)
+
+        # Return relative path for stylesheet_link_tag
+        # Handle case where output directory is not under rails_assets_root (e.g., in tests)
+        begin
+          file_path.relative_path_from(rails_assets_root).to_s.gsub(/\.css$/, "")
+        rescue ArgumentError
+          # If paths don't share a common prefix (e.g., in tests), return just the filename
+          filename.gsub(/\.css$/, "")
+        end
+      end
+
+      # Ensure output directory exists
+      #
+      # @return [void]
+      def ensure_output_directory
+        return unless enabled?
+
+        dir = output_directory
+        FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      end
+
+      # Clear all generated CSS files
+      #
+      # @return [void]
+      def clear_files
+        return unless enabled?
+
+        dir = output_directory
+        return unless Dir.exist?(dir)
+
+        Dir.glob(dir.join("*.css")).each { |file| File.delete(file) }
+      end
+
+      # Check if file writing is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        @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 rails_available?
+          Rails.root.join(DEFAULT_OUTPUT_DIR)
+        else
+          Pathname.new(DEFAULT_OUTPUT_DIR)
+        end
+      end
+
+      # Generate filename using pattern
+      #
+      # @param component_class [Class] Component class
+      # @param capsule_id [String] Capsule ID
+      # @return [String] Validated filename
+      # @raise [SecurityError] If filename contains path traversal or invalid characters
+      def generate_filename(component_class, capsule_id)
+        pattern_result = filename_pattern.call(component_class, capsule_id)
+        # Ensure .css extension
+        filename = pattern_result.end_with?(".css") ? pattern_result : "#{pattern_result}.css"
+
+        # Validate filename to prevent path traversal attacks
+        validate_filename!(filename)
+
+        filename
+      end
+
+      # Default filename pattern
+      #
+      # Uses only the capsule_id since it's unique and deterministic.
+      # The capsule_id is generated from the component class name using SHA1,
+      # ensuring uniqueness while keeping filenames concise and not exposing
+      # internal component structure.
+      #
+      # @return [Proc] Proc that generates filename from (component_class, capsule_id)
+      def default_filename_pattern
+        ->(component_class, capsule_id) do
+          # Validate capsule_id is safe (alphanumeric, hyphens, underscores only)
+          # This ensures the filename is safe even if capsule_id generation changes
+          safe_capsule_id = capsule_id.to_s.gsub(/[^a-zA-Z0-9_-]/, "")
+
+          if safe_capsule_id.empty?
+            raise ArgumentError, "Invalid capsule_id: must contain at least one alphanumeric character"
+          end
+
+          "capsule-#{safe_capsule_id}.css"
+        end
+      end
+
+      # Get Rails assets root (app/assets)
+      def rails_assets_root
+        if rails_available?
+          Rails.root.join("app/assets")
+        else
+          Pathname.new("app/assets")
+        end
+      end
+
+      # Validate filename to prevent path traversal and other security issues
+      #
+      # @param filename [String] Filename to validate
+      # @raise [SecurityError] If filename is invalid
+      def validate_filename!(filename)
+        # Reject path traversal attempts
+        if filename.include?("..") || filename.include?("/") || filename.include?("\\")
+          raise SecurityError, "Invalid filename: path traversal detected in '#{filename}'"
+        end
+
+        # Reject null bytes
+        if filename.include?("\0")
+          raise SecurityError, "Invalid filename: null byte detected"
+        end
+
+        # Ensure filename is reasonable length (filesystem limit is typically 255)
+        if filename.length > 255
+          raise SecurityError, "Invalid filename: too long (max 255 characters, got #{filename.length})"
+        end
+
+        # Ensure filename contains only safe characters (alphanumeric, dots, hyphens, underscores)
+        # Must end with .css extension
+        unless filename.match?(/\A[a-zA-Z0-9._-]+\.css\z/)
+          raise SecurityError, "Invalid filename: contains unsafe characters (only alphanumeric, dots, hyphens, underscores allowed, must end with .css)"
+        end
+      end
+    end
+  end
+end

data/lib/style_capsule/css_processor.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Shared CSS processing logic for scoping selectors with attribute selectors
+  #
+  # Supports two scoping strategies:
+  # 1. Selector patching (default): Adds [data-capsule="..."] prefix to each selector
+  #    - Better browser support (all modern browsers)
+  #    - Requires CSS parsing and transformation
+  # 2. CSS nesting (optional): Wraps entire CSS in [data-capsule="..."] { ... }
+  #    - More performant (no parsing needed)
+  #    - Requires CSS nesting support (Chrome 112+, Firefox 117+, Safari 16.5+)
+  module CssProcessor
+    # Maximum CSS content size (1MB) to prevent DoS attacks
+    MAX_CSS_SIZE = 1_000_000
+
+    # Rewrite CSS selectors to include attribute-based scoping
+    #
+    # Transforms:
+    #   .section { color: red; }
+    #   .heading:hover { opacity: 0.8; }
+    #
+    # Into:
+    #   [data-capsule="a1b2c3d4"] .section { color: red; }
+    #   [data-capsule="a1b2c3d4"] .heading:hover { opacity: 0.8; }
+    #
+    # This approach uses attribute selectors (similar to Angular's Emulated View Encapsulation)
+    # instead of renaming classes, ensuring styles only apply within scoped components.
+    #
+    # Simple approach:
+    # - Strips CSS comments first to avoid interference
+    # - Finds selectors before opening braces and prefixes them
+    # - Handles @media queries (preserves them, scopes inner selectors)
+    # - Handles :host and :host-context (component-scoped selectors)
+    #
+    # @param css_string [String] Original CSS content
+    # @param capsule_id [String] The capsule ID to use in attribute selector
+    # @return [String] CSS with scoped selectors
+    # @raise [ArgumentError] If CSS content exceeds maximum size or capsule_id is invalid
+    def self.scope_selectors(css_string, capsule_id)
+      return css_string if css_string.nil? || css_string.strip.empty?
+
+      # Validate CSS size to prevent DoS attacks
+      if css_string.bytesize > MAX_CSS_SIZE
+        raise ArgumentError, "CSS content exceeds maximum size of #{MAX_CSS_SIZE} bytes (got #{css_string.bytesize} bytes)"
+      end
+
+      # Validate capsule_id
+      validate_capsule_id!(capsule_id)
+
+      css = css_string.dup
+      capsule_attr = %([data-capsule="#{capsule_id}"])
+
+      # Strip CSS comments to avoid interference with selector matching
+      # Simple approach: remove /* ... */ comments (including multi-line)
+      css_without_comments = strip_comments(css)
+
+      # Process CSS rule by rule
+      # Match: selector(s) { ... }
+      # Pattern: (start or closing brace) + (whitespace) + (selector text) + (opening brace)
+      # Note: Uses non-greedy quantifier ([^{}@]+?) to minimize backtracking
+      # MAX_CSS_SIZE limit (1MB) mitigates ReDoS risk from malicious input
+      css_without_comments.gsub!(/(^|\})(\s*)([^{}@]+?)(\{)/m) do |_|
+        prefix = Regexp.last_match(1)  # Previous closing brace or start
+        whitespace = Regexp.last_match(2)  # Whitespace between rules
+        selectors_raw = Regexp.last_match(3)  # The selector group
+        selectors = selectors_raw.strip  # Stripped for processing
+        opening_brace = Regexp.last_match(4)  # The opening brace
+
+        # Skip at-rules (@media, @keyframes, etc.) - they should not be scoped at top level
+        next "#{prefix}#{whitespace}#{selectors_raw}#{opening_brace}" if selectors.start_with?("@")
+
+        # Skip if already scoped (avoid double-scoping)
+        next "#{prefix}#{whitespace}#{selectors_raw}#{opening_brace}" if selectors_raw.include?("[data-capsule=")
+
+        # Skip empty selectors
+        next "#{prefix}#{whitespace}#{selectors_raw}#{opening_brace}" if selectors.empty?
+
+        # Split selectors by comma and scope each one
+        scoped_selectors = selectors.split(",").map do |selector|
+          selector = selector.strip
+          next selector if selector.empty?
+
+          # Handle special component-scoped selectors (:host, :host-context)
+          if selector.start_with?(":host")
+            selector = selector
+              .gsub(/^:host-context\(([^)]+)\)/, "#{capsule_attr} \\1")
+              .gsub(/^:host\(([^)]+)\)/, "#{capsule_attr}\\1")
+              .gsub(/^:host\b/, capsule_attr)
+            selector
+          else
+            # Add capsule attribute with space before selector for descendant matching
+            # This ensures styles apply to elements inside the scoped wrapper
+            "#{capsule_attr} #{selector}"
+          end
+        end.compact.join(", ")
+
+        "#{prefix}#{whitespace}#{scoped_selectors}#{opening_brace}"
+      end
+
+      # Restore comments in their original positions
+      # Since we stripped comments, we need to put them back
+      # For simplicity, we'll just return the processed CSS without comments
+      # (comments are typically removed in production CSS anyway)
+      css_without_comments
+    end
+
+    # Scope CSS using CSS nesting (wraps entire CSS in [data-capsule] { ... })
+    #
+    # This approach is more performant as it requires no CSS parsing or transformation.
+    # However, it requires CSS nesting support in browsers (Chrome 112+, Firefox 117+, Safari 16.5+).
+    #
+    # Transforms:
+    #   .section { color: red; }
+    #   .heading:hover { opacity: 0.8; }
+    #
+    # Into:
+    #   [data-capsule="a1b2c3d4"] {
+    #     .section { color: red; }
+    #     .heading:hover { opacity: 0.8; }
+    #   }
+    #
+    # @param css_string [String] Original CSS content
+    # @param capsule_id [String] The capsule ID to use in attribute selector
+    # @return [String] CSS wrapped in nesting selector
+    # @raise [ArgumentError] If CSS content exceeds maximum size or capsule_id is invalid
+    def self.scope_with_nesting(css_string, capsule_id)
+      return css_string if css_string.nil? || css_string.strip.empty?
+
+      # Validate CSS size to prevent DoS attacks
+      if css_string.bytesize > MAX_CSS_SIZE
+        raise ArgumentError, "CSS content exceeds maximum size of #{MAX_CSS_SIZE} bytes (got #{css_string.bytesize} bytes)"
+      end
+
+      # Validate capsule_id
+      validate_capsule_id!(capsule_id)
+
+      # Simply wrap the entire CSS in the capsule attribute selector
+      # No parsing or transformation needed - much more performant
+      capsule_attr = %([data-capsule="#{capsule_id}"])
+      "#{capsule_attr} {\n#{css_string}\n}"
+    end
+
+    # Strip CSS comments (/* ... */) from the string
+    #
+    # @param css [String] CSS content with comments
+    # @return [String] CSS content without comments
+    def self.strip_comments(css)
+      # Remove /* ... */ comments (including multi-line)
+      # Use non-greedy match to handle multiple comments
+      css.gsub(/\/\*.*?\*\//m, "")
+    end
+
+    # Validate capsule ID to prevent injection attacks
+    #
+    # @param capsule_id [String] Capsule ID to validate
+    # @raise [ArgumentError] If capsule_id is invalid
+    def self.validate_capsule_id!(capsule_id)
+      unless capsule_id.is_a?(String)
+        raise ArgumentError, "capsule_id must be a String (got #{capsule_id.class})"
+      end
+
+      # Must not be empty (check first for clearer error message)
+      if capsule_id.empty?
+        raise ArgumentError, "capsule_id cannot be empty"
+      end
+
+      # Capsule ID should only contain alphanumeric characters, hyphens, and underscores
+      # This prevents injection into HTML attributes
+      unless capsule_id.match?(/\A[a-zA-Z0-9_-]+\z/)
+        raise ArgumentError, "Invalid capsule_id: must contain only alphanumeric characters, hyphens, and underscores (got: #{capsule_id.inspect})"
+      end
+
+      # Reasonable length limit
+      if capsule_id.length > 100
+        raise ArgumentError, "Invalid capsule_id: too long (max 100 characters, got #{capsule_id.length})"
+      end
+    end
+
+    private_class_method :strip_comments, :validate_capsule_id!
+  end
+end