style_capsule 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dc57ce596c8aec7767199f8c57b82db16a8f96b33ac06cba599febd89afa86a
-  data.tar.gz: b4767a7eed2a864357027386452ea6a2da24577be3376388569c8ceb61bff937
+  metadata.gz: 74203df88bc23dc0b1509f0e7adc5978fe327c982026916e990644c92f65a0db
+  data.tar.gz: 7f7783ef50b66e14859e1f7207262279f20e5f28eb29d3373a85fef9ae2f3a7c
 SHA512:
-  metadata.gz: a666c80dc9ddc70179e9992bc4a1c0c9b58a295e21e0fc64441227529c4b401fdc7c7a703af5e87403ca407d0e482a5b97c73b1cc81d385a021cea2e1186c8d5
-  data.tar.gz: 0d8523c1659c5467b6e0a1aa6fc1268f999f669772a2ff22b66b386ec5c6ed19d85a9b9dc2b915f744d691ad2d9ccaa2dd7bc33f5c132a3c7d1fe1df073dcd41
+  metadata.gz: bed787978d271158ca409ffe8445df1f6203e954000d153beae40368861e0077b566557c3f50456373d04998f85ab60ee86b3cd93ed558d31f3d482247fb0b7e
+  data.tar.gz: 22b900ebbf5ce4a219d487f7915b7dcd31ed4552d134af44f056ba79eff8551a4ef62e8070f03887fc4962f2073d06bd3b2d65d35e00f09183d97a730ad24ee2

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 1.4.0 (2025-11-26)
+
+- Added unified `style_capsule` class method for configuring all StyleCapsule settings (namespace, cache strategy, CSS scoping, head rendering) in a single call
+- Added automatic namespace fallback in `register_stylesheet` helper methods - when namespace is not specified, uses the component's configured namespace from `style_capsule`
+- Removed deprecated `head_rendering!` method (use `style_capsule` instead)
+- Removed deprecated `stylesheet_registrymap_tags` alias (use `stylesheet_registry_tags` instead)
+- Refactored namespace configuration to use instance variables instead of constants for better inheritance behavior
+
 ## 1.3.0 (2025-11-26)
 
 - Added comprehensive instrumentation via `StyleCapsule::Instrumentation` using ActiveSupport::Notifications
@@ -29,7 +37,7 @@
 - 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)
+- Renamed `stylesheet_registrymap_tags` to `stylesheet_registry_tags` (deprecated alias removed in 1.4.0)
 - 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

data/README.md

@@ -1,6 +1,6 @@
 # style_capsule
 
-[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=1.3.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)
+[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=1.4.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 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.
 
@@ -103,12 +103,12 @@ StyleCapsule supports two CSS scoping strategies:
 
 ### Configuration
 
-**Per-component:**
+**Per-component (using `style_capsule` - recommended):**
 
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  css_scoping_strategy :nesting  # Use CSS nesting
+  style_capsule scoping_strategy: :nesting  # Use CSS nesting
 end
 ```
 
@@ -117,7 +117,7 @@ end
 ```ruby
 class ApplicationComponent < Phlex::HTML
   include StyleCapsule::Component
-  css_scoping_strategy :nesting  # Enable for all components
+  style_capsule scoping_strategy: :nesting  # Enable for all components
 end
 ```
 
@@ -129,12 +129,12 @@ MyComponent.clear_css_cache
 
 ## Stylesheet Registry
 
-For better performance, register styles for head rendering instead of rendering `<style>` tags in the body:
+For better performance, register styles for head rendering instead of rendering `<style>` tags in the body. Use the unified `style_capsule` method to configure all settings:
 
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry namespace: :admin  # Optional namespace
+  style_capsule namespace: :admin  # Configure namespace and enable head rendering
 
   def component_styles
     <<~CSS
@@ -144,12 +144,17 @@ class MyComponent < ApplicationComponent
 end
 ```
 
-With cache strategy:
+With cache strategy and CSS scoping:
 
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+  style_capsule(
+    namespace: :admin,
+    cache_strategy: :time,
+    cache_ttl: 1.hour,
+    scoping_strategy: :nesting
+  )
 
   def component_styles
     <<~CSS
@@ -159,11 +164,10 @@ class MyComponent < ApplicationComponent
 end
 ```
 
-Then in your layout:
+Then in your layout (render only the namespace you need):
 
 ```erb
 <head>
-  <%= stylesheet_registry_tags %>
   <%= stylesheet_registry_tags(namespace: :admin) %>
 </head>
 ```
@@ -172,42 +176,58 @@ Or in Phlex (requires including `StyleCapsule::PhlexHelper`):
 
 ```ruby
 head do
-  stylesheet_registry_tags
+  stylesheet_registry_tags(namespace: :admin)
 end
 ```
 
+**Namespace Isolation:** Using namespaces prevents stylesheet leakage between different application contexts. For example, login pages can use `namespace: :login`, ActiveAdmin can use `namespace: :active_admin`, and user components can use `namespace: :user`. Each namespace is rendered separately, improving caching efficiency and preventing style conflicts.
+
 ### Registering Stylesheet Files
 
-You can also register external stylesheet files (not inline CSS) for head rendering:
+You can also register external stylesheet files (not inline CSS) for head rendering. When a component has a configured namespace via `style_capsule`, you don't need to specify it every time:
 
 **In ERB:**
 
 ```erb
-<% register_stylesheet("stylesheets/user/order_select_component", "data-turbo-track": "reload") %>
+<% register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload") %>
 <% register_stylesheet("stylesheets/admin/dashboard", namespace: :admin) %>
 ```
 
 **In Phlex (requires including `StyleCapsule::PhlexHelper`):**
 
 ```ruby
-def view_template
-  register_stylesheet("stylesheets/user/order_select_component", "data-turbo-track": "reload")
-  register_stylesheet("stylesheets/admin/dashboard", namespace: :admin)
-  div { "Content" }
+class UserComponent < ApplicationComponent
+  include StyleCapsule::Component
+  include StyleCapsule::PhlexHelper
+  style_capsule namespace: :user  # Set default namespace
+
+  def view_template
+    # Namespace automatically uses :user from style_capsule
+    register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload")
+    # Can still override namespace if needed
+    register_stylesheet("stylesheets/shared/common", namespace: :shared)
+    div { "Content" }
+  end
 end
 ```
 
 **In ViewComponent (requires including `StyleCapsule::ViewComponentHelper`):**
 
 ```ruby
-def call
-  register_stylesheet("stylesheets/user/order_select_component", "data-turbo-track": "reload")
-  register_stylesheet("stylesheets/admin/dashboard", namespace: :admin)
-  content_tag(:div, "Content")
+class UserComponent < ApplicationComponent
+  include StyleCapsule::ViewComponent
+  include StyleCapsule::ViewComponentHelper
+  style_capsule namespace: :user  # Set default namespace
+
+  def call
+    # Namespace automatically uses :user from style_capsule
+    register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload")
+    content_tag(:div, "Content")
+  end
 end
 ```
 
-Registered files are rendered via `stylesheet_registry_tags` in your layout, just like inline CSS.
+Registered files are rendered via `stylesheet_registry_tags` in your layout, just like inline CSS. The namespace is automatically used from the component's `style_capsule` configuration when not explicitly specified.
 
 ## Caching Strategies
 
@@ -216,22 +236,22 @@ Registered files are rendered via `stylesheet_registry_tags` in your layout, jus
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry  # No cache strategy set (default: :none)
+  style_capsule  # No cache strategy set (default: :none)
 end
 ```
 
 ### Time-Based Caching
 
 ```ruby
-stylesheet_registry cache_strategy: :time, cache_ttl: 1.hour  # Using ActiveSupport::Duration
+style_capsule cache_strategy: :time, cache_ttl: 1.hour  # Using ActiveSupport::Duration
 # Or using integer seconds:
-stylesheet_registry cache_strategy: :time, cache_ttl: 3600  # Cache for 1 hour
+style_capsule cache_strategy: :time, cache_ttl: 3600  # Cache for 1 hour
 ```
 
 ### Custom Proc Caching
 
 ```ruby
-stylesheet_registry cache_strategy: ->(css, capsule_id, namespace) {
+style_capsule cache_strategy: ->(css, capsule_id, namespace) {
   cache_key = "css_#{capsule_id}_#{namespace}"
   should_cache = css.length > 100
   expires_at = Time.now + 1800
@@ -248,7 +268,7 @@ Writes CSS to files for HTTP caching. **Requires class method `def self.componen
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry cache_strategy: :file
+  style_capsule cache_strategy: :file
 
   # Must use class method for file caching
   def self.component_styles

data/lib/style_capsule/component.rb

@@ -227,23 +227,104 @@ module StyleCapsule
         end
       end
 
-      # Deprecated: Use stylesheet_registry instead
-      # @deprecated Use {#stylesheet_registry} instead
-      def head_rendering!
-        stylesheet_registry
-      end
-
-      # Check if component uses head rendering
+      # Check if component uses head rendering (checks instance variable, then parent class, defaults to false)
+      #
+      # @return [Boolean] Whether head rendering is enabled (default: false)
       def head_rendering?
-        return false unless defined?(@head_rendering)
-        @head_rendering
+        if defined?(@head_rendering)
+          @head_rendering
+        elsif superclass.respond_to?(:head_rendering?, true)
+          superclass.head_rendering?
+        else
+          false
+        end
       end
 
       public :head_rendering?
 
-      # Get the namespace for stylesheet registry
+      # Get the namespace for stylesheet registry (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Symbol, String, nil] The namespace identifier (default: nil)
       def stylesheet_namespace
-        @stylesheet_namespace if defined?(@stylesheet_namespace)
+        if defined?(@stylesheet_namespace) && @stylesheet_namespace
+          @stylesheet_namespace
+        elsif superclass.respond_to?(:stylesheet_namespace, true)
+          superclass.stylesheet_namespace
+        end
+      end
+
+      # Configure StyleCapsule settings
+      #
+      # All settings support class inheritance - child classes inherit settings from parent classes
+      # and can override them by calling style_capsule again with different values.
+      #
+      # @param namespace [Symbol, String, nil] Default namespace for stylesheets
+      # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy: :none (default), :time, :proc, :file
+      # @param cache_ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in seconds (for :time strategy)
+      # @param cache_proc [Proc, nil] Custom cache proc (for :proc strategy)
+      # @param scoping_strategy [Symbol, nil] CSS scoping strategy: :selector_patching (default) or :nesting
+      # @param head_rendering [Boolean, nil] Enable head rendering (default: true if any option is set, false otherwise)
+      # @return [void]
+      # @example Basic usage with namespace
+      #   class AdminComponent < ApplicationComponent
+      #     include StyleCapsule::Component
+      #     style_capsule namespace: :admin
+      #
+      #     def view_template
+      #       register_stylesheet("stylesheets/admin/dashboard")  # Uses :admin namespace automatically
+      #       div { "Content" }
+      #     end
+      #   end
+      # @example With all options
+      #   class MyComponent < ApplicationComponent
+      #     include StyleCapsule::Component
+      #     style_capsule(
+      #       namespace: :user,
+      #       cache_strategy: :time,
+      #       cache_ttl: 1.hour,
+      #       scoping_strategy: :nesting
+      #     )
+      #   end
+      # @example Inheritance - child class inherits parent settings
+      #   class BaseComponent < ApplicationComponent
+      #     include StyleCapsule::Component
+      #     style_capsule namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+      #   end
+      #
+      #   class ChildComponent < BaseComponent
+      #     # Inherits namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+      #     # Can override specific settings:
+      #     style_capsule namespace: :user  # Overrides namespace, keeps cache settings
+      #   end
+      def style_capsule(namespace: nil, cache_strategy: nil, cache_ttl: nil, cache_proc: nil, scoping_strategy: nil, head_rendering: nil)
+        # Set namespace (stored in instance variable, but getter checks parent class for inheritance)
+        if namespace
+          @stylesheet_namespace = namespace
+        end
+
+        # Configure cache strategy if provided
+        if cache_strategy || cache_ttl || cache_proc
+          normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy || :none, cache_proc)
+          @inline_cache_strategy = normalized_strategy
+          # Explicitly set cache_ttl (even if nil) to override parent's value when cache settings are changed
+          @inline_cache_ttl = cache_ttl
+          @inline_cache_proc = normalized_proc
+        end
+
+        # Configure CSS scoping strategy if provided
+        if scoping_strategy
+          unless [:selector_patching, :nesting].include?(scoping_strategy)
+            raise ArgumentError, "scoping_strategy must be :selector_patching or :nesting (got: #{scoping_strategy.inspect})"
+          end
+          @css_scoping_strategy = scoping_strategy
+        end
+
+        # Enable head rendering if explicitly set or if any option is provided (except scoping_strategy)
+        if head_rendering.nil?
+          @head_rendering = true if namespace || cache_strategy || cache_ttl || cache_proc
+        else
+          @head_rendering = head_rendering
+        end
       end
 
       # Get the custom scope ID if set (alias for capsule_id getter)
@@ -251,22 +332,55 @@ module StyleCapsule
         @custom_capsule_id if defined?(@custom_capsule_id)
       end
 
-      # Get inline cache strategy
+      # Get inline cache strategy (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Symbol, nil] The cache strategy (default: nil)
       def inline_cache_strategy
-        @inline_cache_strategy if defined?(@inline_cache_strategy)
+        if defined?(@inline_cache_strategy) && @inline_cache_strategy
+          @inline_cache_strategy
+        elsif superclass.respond_to?(:inline_cache_strategy, true)
+          superclass.inline_cache_strategy
+        end
       end
 
-      # Get inline cache TTL
+      # Get inline cache TTL (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Integer, ActiveSupport::Duration, nil] The cache TTL (default: nil)
       def inline_cache_ttl
-        @inline_cache_ttl if defined?(@inline_cache_ttl)
+        if defined?(@inline_cache_ttl)
+          @inline_cache_ttl
+        elsif superclass.respond_to?(:inline_cache_ttl, true)
+          superclass.inline_cache_ttl
+        end
       end
 
-      # Get inline cache proc
+      # Get inline cache proc (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Proc, nil] The cache proc (default: nil)
       def inline_cache_proc
-        @inline_cache_proc if defined?(@inline_cache_proc)
+        if defined?(@inline_cache_proc)
+          @inline_cache_proc
+        elsif superclass.respond_to?(:inline_cache_proc, true)
+          superclass.inline_cache_proc
+        end
       end
 
-      public :head_rendering?, :stylesheet_namespace, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
+      public :head_rendering?, :stylesheet_namespace, :style_capsule, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
+
+      # Get CSS scoping strategy (checks instance variable, then parent class, defaults to :selector_patching)
+      #
+      # @return [Symbol] The current scoping strategy (default: :selector_patching)
+      def css_scoping_strategy
+        if defined?(@css_scoping_strategy) && @css_scoping_strategy
+          @css_scoping_strategy
+        elsif superclass.respond_to?(:css_scoping_strategy, true)
+          superclass.css_scoping_strategy
+        else
+          :selector_patching
+        end
+      end
+
+      public :css_scoping_strategy
 
       # Set or get options for stylesheet_link_tag when using file-based caching
       #
@@ -289,58 +403,6 @@ module StyleCapsule
       end
 
       public :stylesheet_link_options
-
-      # Set or get CSS scoping strategy
-      #
-      # @param strategy [Symbol, nil] Scoping strategy: :selector_patching (default) or :nesting (omit to get current value)
-      #   - :selector_patching: Adds [data-capsule="..."] prefix to each selector (better browser support)
-      #   - :nesting: Wraps entire CSS in [data-capsule="..."] { ... } (more performant, requires CSS nesting support)
-      # @return [Symbol] The current scoping strategy (default: :selector_patching)
-      # @example Using CSS nesting (requires Chrome 112+, Firefox 117+, Safari 16.5+)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     css_scoping_strategy :nesting  # More performant, no CSS parsing needed
-      #
-      #     def component_styles
-      #       <<~CSS
-      #         .section { color: red; }
-      #         .heading:hover { opacity: 0.8; }
-      #       CSS
-      #     end
-      #   end
-      #   # Output: [data-capsule="abc123"] { .section { color: red; } .heading:hover { opacity: 0.8; } }
-      # @example Using selector patching (default, better browser support)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     css_scoping_strategy :selector_patching  # Default
-      #
-      #     def component_styles
-      #       <<~CSS
-      #         .section { color: red; }
-      #       CSS
-      #     end
-      #   end
-      #   # Output: [data-capsule="abc123"] .section { color: red; }
-      def css_scoping_strategy(strategy = nil)
-        if strategy.nil?
-          # Check if this class has a strategy set
-          if defined?(@css_scoping_strategy) && @css_scoping_strategy
-            @css_scoping_strategy
-          # Otherwise, check parent class (for inheritance)
-          elsif superclass.respond_to?(:css_scoping_strategy, true)
-            superclass.css_scoping_strategy
-          else
-            :selector_patching
-          end
-        else
-          unless [:selector_patching, :nesting].include?(strategy)
-            raise ArgumentError, "css_scoping_strategy must be :selector_patching or :nesting (got: #{strategy.inspect})"
-          end
-          @css_scoping_strategy = strategy
-        end
-      end
-
-      public :css_scoping_strategy
     end
 
     # Module that wraps view_template to add scoped wrapper

data/lib/style_capsule/helper.rb

@@ -159,9 +159,5 @@ module StyleCapsule
     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

@@ -10,13 +10,18 @@ module StyleCapsule
   #
   # Usage in Phlex layouts:
   #   head do
-  #     stylesheet_registrymap_tags
+  #     stylesheet_registry_tags
   #   end
   #
   # Usage in Phlex components:
-  #   def view_template
-  #     register_stylesheet("stylesheets/user/my_component")
-  #     div { "Content" }
+  #   class MyComponent < ApplicationComponent
+  #     include StyleCapsule::PhlexHelper
+  #     styles_namespace :user  # Set default namespace
+  #
+  #     def view_template
+  #       register_stylesheet("stylesheets/user/my_component")  # Uses :user namespace automatically
+  #       div { "Content" }
+  #     end
   #   end
   module PhlexHelper
     # Register a stylesheet file for head rendering
@@ -28,11 +33,18 @@ module StyleCapsule
     #     div { "Content" }
     #   end
     #
+    # If the component has a default namespace set via styles_namespace or stylesheet_registry,
+    # it will be used automatically when namespace is not explicitly provided.
+    #
     # @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 namespace [Symbol, String, nil] Optional namespace for separation (nil/blank uses component's default or global default)
     # @param options [Hash] Options for stylesheet_link_tag
     # @return [void]
     def register_stylesheet(file_path, namespace: nil, **options)
+      # Use component's default namespace if not explicitly provided
+      if namespace.nil? && respond_to?(:class) && self.class.respond_to?(:stylesheet_namespace)
+        namespace = self.class.stylesheet_namespace
+      end
       StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
     end
 
@@ -62,9 +74,5 @@ 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/standalone_helper.rb

@@ -179,10 +179,6 @@ module StyleCapsule
       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

data/lib/style_capsule/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StyleCapsule
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

data/lib/style_capsule/view_component.rb

@@ -227,23 +227,104 @@ module StyleCapsule
         end
       end
 
-      # Deprecated: Use stylesheet_registry instead
-      # @deprecated Use {#stylesheet_registry} instead
-      def head_rendering!
-        stylesheet_registry
-      end
-
-      # Check if component uses head rendering
+      # Check if component uses head rendering (checks instance variable, then parent class, defaults to false)
+      #
+      # @return [Boolean] Whether head rendering is enabled (default: false)
       def head_rendering?
-        return false unless defined?(@head_rendering)
-        @head_rendering
+        if defined?(@head_rendering)
+          @head_rendering
+        elsif superclass.respond_to?(:head_rendering?, true)
+          superclass.head_rendering?
+        else
+          false
+        end
       end
 
       public :head_rendering?
 
-      # Get the namespace for stylesheet registry
+      # Get the namespace for stylesheet registry (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Symbol, String, nil] The namespace identifier (default: nil)
       def stylesheet_namespace
-        @stylesheet_namespace if defined?(@stylesheet_namespace)
+        if defined?(@stylesheet_namespace) && @stylesheet_namespace
+          @stylesheet_namespace
+        elsif superclass.respond_to?(:stylesheet_namespace, true)
+          superclass.stylesheet_namespace
+        end
+      end
+
+      # Configure StyleCapsule settings
+      #
+      # All settings support class inheritance - child classes inherit settings from parent classes
+      # and can override them by calling style_capsule again with different values.
+      #
+      # @param namespace [Symbol, String, nil] Default namespace for stylesheets
+      # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy: :none (default), :time, :proc, :file
+      # @param cache_ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in seconds (for :time strategy)
+      # @param cache_proc [Proc, nil] Custom cache proc (for :proc strategy)
+      # @param scoping_strategy [Symbol, nil] CSS scoping strategy: :selector_patching (default) or :nesting
+      # @param head_rendering [Boolean, nil] Enable head rendering (default: true if any option is set, false otherwise)
+      # @return [void]
+      # @example Basic usage with namespace
+      #   class AdminComponent < ApplicationComponent
+      #     include StyleCapsule::ViewComponent
+      #     style_capsule namespace: :admin
+      #
+      #     def call
+      #       register_stylesheet("stylesheets/admin/dashboard")  # Uses :admin namespace automatically
+      #       content_tag(:div, "Content")
+      #     end
+      #   end
+      # @example With all options
+      #   class MyComponent < ApplicationComponent
+      #     include StyleCapsule::ViewComponent
+      #     style_capsule(
+      #       namespace: :user,
+      #       cache_strategy: :time,
+      #       cache_ttl: 1.hour,
+      #       scoping_strategy: :nesting
+      #     )
+      #   end
+      # @example Inheritance - child class inherits parent settings
+      #   class BaseComponent < ApplicationComponent
+      #     include StyleCapsule::ViewComponent
+      #     style_capsule namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+      #   end
+      #
+      #   class ChildComponent < BaseComponent
+      #     # Inherits namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+      #     # Can override specific settings:
+      #     style_capsule namespace: :user  # Overrides namespace, keeps cache settings
+      #   end
+      def style_capsule(namespace: nil, cache_strategy: nil, cache_ttl: nil, cache_proc: nil, scoping_strategy: nil, head_rendering: nil)
+        # Set namespace (stored in instance variable, but getter checks parent class for inheritance)
+        if namespace
+          @stylesheet_namespace = namespace
+        end
+
+        # Configure cache strategy if provided
+        if cache_strategy || cache_ttl || cache_proc
+          normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy || :none, cache_proc)
+          @inline_cache_strategy = normalized_strategy
+          # Explicitly set cache_ttl (even if nil) to override parent's value when cache settings are changed
+          @inline_cache_ttl = cache_ttl
+          @inline_cache_proc = normalized_proc
+        end
+
+        # Configure CSS scoping strategy if provided
+        if scoping_strategy
+          unless [:selector_patching, :nesting].include?(scoping_strategy)
+            raise ArgumentError, "scoping_strategy must be :selector_patching or :nesting (got: #{scoping_strategy.inspect})"
+          end
+          @css_scoping_strategy = scoping_strategy
+        end
+
+        # Enable head rendering if explicitly set or if any option is provided (except scoping_strategy)
+        if head_rendering.nil?
+          @head_rendering = true if namespace || cache_strategy || cache_ttl || cache_proc
+        else
+          @head_rendering = head_rendering
+        end
       end
 
       # Get the custom scope ID if set (alias for capsule_id getter)
@@ -251,22 +332,55 @@ module StyleCapsule
         @custom_capsule_id if defined?(@custom_capsule_id)
       end
 
-      # Get inline cache strategy
+      # Get inline cache strategy (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Symbol, nil] The cache strategy (default: nil)
       def inline_cache_strategy
-        @inline_cache_strategy if defined?(@inline_cache_strategy)
+        if defined?(@inline_cache_strategy) && @inline_cache_strategy
+          @inline_cache_strategy
+        elsif superclass.respond_to?(:inline_cache_strategy, true)
+          superclass.inline_cache_strategy
+        end
       end
 
-      # Get inline cache TTL
+      # Get inline cache TTL (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Integer, ActiveSupport::Duration, nil] The cache TTL (default: nil)
       def inline_cache_ttl
-        @inline_cache_ttl if defined?(@inline_cache_ttl)
+        if defined?(@inline_cache_ttl)
+          @inline_cache_ttl
+        elsif superclass.respond_to?(:inline_cache_ttl, true)
+          superclass.inline_cache_ttl
+        end
       end
 
-      # Get inline cache proc
+      # Get inline cache proc (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Proc, nil] The cache proc (default: nil)
       def inline_cache_proc
-        @inline_cache_proc if defined?(@inline_cache_proc)
+        if defined?(@inline_cache_proc)
+          @inline_cache_proc
+        elsif superclass.respond_to?(:inline_cache_proc, true)
+          superclass.inline_cache_proc
+        end
       end
 
-      public :head_rendering?, :stylesheet_namespace, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
+      public :head_rendering?, :stylesheet_namespace, :style_capsule, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
+
+      # Get CSS scoping strategy (checks instance variable, then parent class, defaults to :selector_patching)
+      #
+      # @return [Symbol] The current scoping strategy (default: :selector_patching)
+      def css_scoping_strategy
+        if defined?(@css_scoping_strategy) && @css_scoping_strategy
+          @css_scoping_strategy
+        elsif superclass.respond_to?(:css_scoping_strategy, true)
+          superclass.css_scoping_strategy
+        else
+          :selector_patching
+        end
+      end
+
+      public :css_scoping_strategy
 
       # Set or get options for stylesheet_link_tag when using file-based caching
       #
@@ -289,58 +403,6 @@ module StyleCapsule
       end
 
       public :stylesheet_link_options
-
-      # Set or get CSS scoping strategy
-      #
-      # @param strategy [Symbol, nil] Scoping strategy: :selector_patching (default) or :nesting (omit to get current value)
-      #   - :selector_patching: Adds [data-capsule="..."] prefix to each selector (better browser support)
-      #   - :nesting: Wraps entire CSS in [data-capsule="..."] { ... } (more performant, requires CSS nesting support)
-      # @return [Symbol] The current scoping strategy (default: :selector_patching)
-      # @example Using CSS nesting (requires Chrome 112+, Firefox 117+, Safari 16.5+)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::ViewComponent
-      #     css_scoping_strategy :nesting  # More performant, no CSS parsing needed
-      #
-      #     def component_styles
-      #       <<~CSS
-      #         .section { color: red; }
-      #         .heading:hover { opacity: 0.8; }
-      #       CSS
-      #     end
-      #   end
-      #   # Output: [data-capsule="abc123"] { .section { color: red; } .heading:hover { opacity: 0.8; } }
-      # @example Using selector patching (default, better browser support)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::ViewComponent
-      #     css_scoping_strategy :selector_patching  # Default
-      #
-      #     def component_styles
-      #       <<~CSS
-      #         .section { color: red; }
-      #       CSS
-      #     end
-      #   end
-      #   # Output: [data-capsule="abc123"] .section { color: red; }
-      def css_scoping_strategy(strategy = nil)
-        if strategy.nil?
-          # Check if this class has a strategy set
-          if defined?(@css_scoping_strategy) && @css_scoping_strategy
-            @css_scoping_strategy
-          # Otherwise, check parent class (for inheritance)
-          elsif superclass.respond_to?(:css_scoping_strategy, true)
-            superclass.css_scoping_strategy
-          else
-            :selector_patching
-          end
-        else
-          unless [:selector_patching, :nesting].include?(strategy)
-            raise ArgumentError, "css_scoping_strategy must be :selector_patching or :nesting (got: #{strategy.inspect})"
-          end
-          @css_scoping_strategy = strategy
-        end
-      end
-
-      public :css_scoping_strategy
     end
 
     # Module that wraps call to add scoped wrapper

data/lib/style_capsule/view_component_helper.rb

@@ -10,13 +10,17 @@ module StyleCapsule
   #
   # Usage in ViewComponent layouts:
   #   def call
-  #     helpers.stylesheet_registrymap_tags
+  #     helpers.stylesheet_registry_tags
   #   end
   #
   # Usage in ViewComponent components:
-  #   def call
-  #     register_stylesheet("stylesheets/user/my_component")
-  #     content_tag(:div, "Content")
+  #   class MyComponent < ApplicationComponent
+  #     styles_namespace :user  # Set default namespace
+  #
+  #     def call
+  #       register_stylesheet("stylesheets/user/my_component")  # Uses :user namespace automatically
+  #       content_tag(:div, "Content")
+  #     end
   #   end
   module ViewComponentHelper
     # Register a stylesheet file for head rendering
@@ -28,11 +32,18 @@ module StyleCapsule
     #     content_tag(:div, "Content")
     #   end
     #
+    # If the component has a default namespace set via styles_namespace or stylesheet_registry,
+    # it will be used automatically when namespace is not explicitly provided.
+    #
     # @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 namespace [Symbol, String, nil] Optional namespace for separation (nil/blank uses component's default or global default)
     # @param options [Hash] Options for stylesheet_link_tag
     # @return [void]
     def register_stylesheet(file_path, namespace: nil, **options)
+      # Use component's default namespace if not explicitly provided
+      if namespace.nil? && respond_to?(:class) && self.class.respond_to?(:stylesheet_namespace)
+        namespace = self.class.stylesheet_namespace
+      end
       StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
     end
 
@@ -49,9 +60,5 @@ module StyleCapsule
     def stylesheet_registry_tags(namespace: nil)
       StyleCapsule::StylesheetRegistry.render_head_stylesheets(helpers, 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.rb

@@ -18,6 +18,7 @@ end
 # @example Phlex Component Usage
 #   class MyComponent < ApplicationComponent
 #     include StyleCapsule::Component
+#     style_capsule namespace: :user  # Configure namespace and other settings
 #
 #     def component_styles
 #       <<~CSS
@@ -29,6 +30,7 @@ end
 # @example ViewComponent Encapsulation Usage
 #   class MyComponent < ApplicationComponent
 #     include StyleCapsule::ViewComponent
+#     style_capsule namespace: :admin  # Configure namespace and other settings
 #
 #     def component_styles
 #       <<~CSS
@@ -51,8 +53,10 @@ end
 #   end
 #
 #   class MyComponent < ApplicationComponent
+#     style_capsule namespace: :user  # Configure namespace
+#
 #     def call
-#       register_stylesheet("stylesheets/user/my_component")
+#       register_stylesheet("stylesheets/user/my_component")  # Uses :user namespace automatically
 #       content_tag(:div, "Content", class: "section")
 #     end
 #   end

data/sig/style_capsule.rbs

@@ -43,7 +43,7 @@ module StyleCapsule
       def capsule_id: () -> String | nil
       def capsule_id: (String capsule_id) -> String
       def stylesheet_registry: (?namespace: Symbol | String | nil, ?cache_strategy: Symbol, ?cache_ttl: Integer | ActiveSupport::Duration | nil, ?cache_proc: Proc | nil) -> void
-      def head_rendering!: () -> void  # deprecated
+      def style_capsule: (?namespace: Symbol | String | nil, ?cache_strategy: Symbol | String | Proc | nil, ?cache_ttl: Integer | ActiveSupport::Duration | nil, ?cache_proc: Proc | nil, ?scoping_strategy: Symbol | nil, ?head_rendering: bool | nil) -> void
       def head_rendering?: () -> bool
       def stylesheet_namespace: () -> Symbol | String | nil
       def custom_capsule_id: () -> String | nil
@@ -54,7 +54,6 @@ module StyleCapsule
       def stylesheet_link_options: () -> Hash[untyped, untyped] | nil
       def stylesheet_link_options: (Hash[untyped, untyped] options) -> Hash[untyped, untyped]
       def css_scoping_strategy: () -> Symbol
-      def css_scoping_strategy: (Symbol strategy) -> Symbol
     end
 
     def component_capsule: () -> String
@@ -68,7 +67,7 @@ module StyleCapsule
       def capsule_id: () -> String | nil
       def capsule_id: (String capsule_id) -> String
       def stylesheet_registry: (?namespace: Symbol | String | nil, ?cache_strategy: Symbol, ?cache_ttl: Integer | ActiveSupport::Duration | nil, ?cache_proc: Proc | nil) -> void
-      def head_rendering!: () -> void  # deprecated
+      def style_capsule: (?namespace: Symbol | String | nil, ?cache_strategy: Symbol | String | Proc | nil, ?cache_ttl: Integer | ActiveSupport::Duration | nil, ?cache_proc: Proc | nil, ?scoping_strategy: Symbol | nil, ?head_rendering: bool | nil) -> void
       def head_rendering?: () -> bool
       def stylesheet_namespace: () -> Symbol | String | nil
       def custom_capsule_id: () -> String | nil
@@ -79,7 +78,6 @@ module StyleCapsule
       def stylesheet_link_options: () -> Hash[untyped, untyped] | nil
       def stylesheet_link_options: (Hash[untyped, untyped] options) -> Hash[untyped, untyped]
       def css_scoping_strategy: () -> Symbol
-      def css_scoping_strategy: (Symbol strategy) -> Symbol
     end
 
     def component_capsule: () -> String
@@ -89,7 +87,6 @@ module StyleCapsule
   module ViewComponentHelper
     def register_stylesheet: (String file_path, ?namespace: Symbol | String | nil, **Hash[untyped, untyped] options) -> void
     def stylesheet_registry_tags: (?namespace: Symbol | String | nil) -> String
-    def stylesheet_registrymap_tags: (?namespace: Symbol | String | nil) -> String  # deprecated
   end
 
   module Helper
@@ -98,13 +95,11 @@ module StyleCapsule
     def style_capsule: (?String css_content, ?capsule_id: String | nil) { () -> String } -> String
     def register_stylesheet: (String file_path, ?namespace: Symbol | String | nil, **Hash[untyped, untyped] options) -> void
     def stylesheet_registry_tags: (?namespace: Symbol | String | nil) -> String
-    def stylesheet_registrymap_tags: (?namespace: Symbol | String | nil) -> String  # deprecated
   end
 
   module PhlexHelper
     def register_stylesheet: (String file_path, ?namespace: Symbol | String | nil, **Hash[untyped, untyped] options) -> void
     def stylesheet_registry_tags: (?namespace: Symbol | String | nil) -> void
-    def stylesheet_registrymap_tags: (?namespace: Symbol | String | nil) -> void  # deprecated
   end
 
   class Railtie < Rails::Railtie

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: style_capsule
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Andrei Makarov