Module: StyleCapsule::ComponentClassMethods Private

Included in:
StyleCapsule::Component::ClassMethods, ViewComponent::ClassMethods
Defined in:
lib/style_capsule/component_class_methods.rb,
sig/style_capsule.rbs

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Shared class-level DSL for Component and ViewComponent.

Constant Summary collapse

MAX_CSS_CACHE_ENTRIES =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Returns:

  • (Integer) 
256

Instance Method Summary collapse

Instance Method Details

#capsule_id(capsule_id = nil) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set or get a custom capsule ID for this component class (useful for testing)

Examples:

Setting a custom capsule ID

class MyComponent < ApplicationComponent
  include StyleCapsule::Component
  capsule_id "test-capsule-123"
end

Getting the current capsule ID

MyComponent.capsule_id  # => "test-capsule-123" or nil

Parameters:

  • capsule_id (String, nil) (defaults to: nil) —

    The custom capsule ID to use (nil to get current value)

Returns:

  • (String, nil) —

    The current capsule ID if no argument provided



67
68
69
70
71
72
73
 
# File 'lib/style_capsule/component_class_methods.rb', line 67

def capsule_id(capsule_id = nil)
  if capsule_id.nil?
    @custom_capsule_id if defined?(@custom_capsule_id)
  else
    @custom_capsule_id = capsule_id.to_s
  end
end

#clear_css_cache ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Clear the CSS cache for this component class

Useful for testing or when you want to force CSS reprocessing. In development, this is automatically called when classes are reloaded.

Examples:

MyComponent.clear_css_cache


36
37
38
39
 
# File 'lib/style_capsule/component_class_methods.rb', line 36

def clear_css_cache
  @css_cache = {}
  @css_cache_order = []
end

#css_cache ⇒ Hash[String, String]

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Class-level cache for scoped CSS per component class

Returns:

  • (Hash[String, String]) 


11
12
13
 
# File 'lib/style_capsule/component_class_methods.rb', line 11

def css_cache
  @css_cache ||= {}
end

#css_scoping_strategy ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get CSS scoping strategy (checks instance variable, then parent class, defaults to :selector_patching)

Returns:

  • (Symbol) —

    The current scoping strategy (default: :selector_patching)



254
255
256
257
258
259
260
261
262
 
# File 'lib/style_capsule/component_class_methods.rb', line 254

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

#custom_capsule_id ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the custom scope ID if set (alias for capsule_id getter)

Returns:

  • (String, nil) 


212
213
214
 
# File 'lib/style_capsule/component_class_methods.rb', line 212

def custom_capsule_id
  @custom_capsule_id if defined?(@custom_capsule_id)
end

#head_rendering? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if component uses head rendering (checks instance variable, then parent class, defaults to false)

Returns:

  • (Boolean) —

    Whether head rendering is enabled (default: false)



137
138
139
140
141
142
143
144
145
 
# File 'lib/style_capsule/component_class_methods.rb', line 137

def head_rendering?
  if defined?(@head_rendering)
    @head_rendering
  elsif superclass.respond_to?(:head_rendering?, true)
    superclass.head_rendering?
  else
    false
  end
end

#inline_cache_proc ⇒ Proc?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get inline cache proc (checks instance variable, then parent class, defaults to nil)

Returns:

  • (Proc, nil) —

    The cache proc (default: nil)



241
242
243
244
245
246
247
 
# File 'lib/style_capsule/component_class_methods.rb', line 241

def 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

#inline_cache_strategy ⇒ Symbol?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get inline cache strategy (checks instance variable, then parent class, defaults to nil)

Parameters:

  • strategy (Symbol)
  • ttl: (Integer, nil)
  • cache_proc: (Proc, nil)

Returns:

  • (Symbol, nil) —

    The cache strategy (default: nil)



219
220
221
222
223
224
225
 
# File 'lib/style_capsule/component_class_methods.rb', line 219

def 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

#inline_cache_ttl ⇒ Integer, ...

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get inline cache TTL (checks instance variable, then parent class, defaults to nil)

Returns:

  • (Integer, ActiveSupport::Duration, nil) —

    The cache TTL (default: nil)



230
231
232
233
234
235
236
 
# File 'lib/style_capsule/component_class_methods.rb', line 230

def 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

#store_css_cache(cache_key, scoped_css) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Store scoped CSS in the bounded class-level cache

Parameters:

  • cache_key (String)
  • scoped_css (String)

Returns:

  • (String) —

    scoped_css



20
21
22
23
24
25
26
27
 
# File 'lib/style_capsule/component_class_methods.rb', line 20

def store_css_cache(cache_key, scoped_css)
  cache = css_cache
  order = css_cache_order
  evict_css_cache_if_full!(cache, order)
  cache[cache_key] = scoped_css
  order << cache_key
  scoped_css
end

#style_capsule(namespace: nil, cache_strategy: nil, cache_ttl: nil, cache_proc: nil, scoping_strategy: nil, head_rendering: nil, tag: nil) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

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.

rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- DSL configures multiple optional class settings

Parameters:

  • namespace (Symbol, String, nil) (defaults to: nil) —

    Default namespace for stylesheets

  • cache_strategy (Symbol, String, Proc, nil) (defaults to: nil) —

    Cache strategy: :none (default), :time, :proc, :file

  • cache_ttl (Integer, ActiveSupport::Duration, nil) (defaults to: nil) —

    Time-to-live in seconds (for :time strategy)

  • cache_proc (Proc, nil) (defaults to: nil) —

    Custom cache proc (for :proc strategy)

  • scoping_strategy (Symbol, nil) (defaults to: nil) —

    CSS scoping strategy: :selector_patching (default) or :nesting

  • head_rendering (Boolean, nil) (defaults to: nil) —

    Enable head rendering (default: true if any option is set, false otherwise)

  • tag (Symbol, String, nil) (defaults to: nil) —

    HTML tag name for wrapper element (default: :div)

  • namespace: (Symbol, String, nil) (defaults to: nil)
  • cache_strategy: (Symbol, String, Proc, nil) (defaults to: nil)
  • cache_ttl: (Integer, ActiveSupport::Duration, nil) (defaults to: nil)
  • cache_proc: (Proc, nil) (defaults to: nil)
  • scoping_strategy: (Symbol, nil) (defaults to: nil)
  • head_rendering: (bool, nil) (defaults to: nil)
  • tag: (Symbol, String, nil) (defaults to: nil) 


174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/style_capsule/component_class_methods.rb', line 174

def style_capsule(namespace: nil, cache_strategy: nil, cache_ttl: nil, cache_proc: nil, scoping_strategy: nil, head_rendering: nil, tag: 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

  # Configure wrapper tag if provided
  if tag
    @wrapper_tag = tag
  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

#stylesheet_link_options(options = nil) ⇒ Hash?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set or get options for stylesheet_link_tag when using file-based caching

Parameters:

  • options (Hash, nil) (defaults to: nil) —

    Options to pass to stylesheet_link_tag (e.g., "data-turbo-track": "reload", omit to get current value)

Returns:

  • (Hash, nil) —

    The current stylesheet link options if no argument provided



285
286
287
288
289
290
291
 
# File 'lib/style_capsule/component_class_methods.rb', line 285

def stylesheet_link_options(options = nil)
  if options.nil?
    @stylesheet_link_options if defined?(@stylesheet_link_options)
  else
    @stylesheet_link_options = options
  end
end

#stylesheet_namespace ⇒ Symbol, ...

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the namespace for stylesheet registry (checks instance variable, then parent class, defaults to nil)

Returns:

  • (Symbol, String, nil) —

    The namespace identifier (default: nil)



152
153
154
155
156
157
158
 
# File 'lib/style_capsule/component_class_methods.rb', line 152

def stylesheet_namespace
  if defined?(@stylesheet_namespace) && @stylesheet_namespace
    @stylesheet_namespace
  elsif superclass.respond_to?(:stylesheet_namespace, true)
    superclass.stylesheet_namespace
  end
end

#stylesheet_registry(namespace: nil, cache_strategy: :none, cache_ttl: nil, cache_proc: nil) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Prefer #style_capsule, which configures namespace, cache, scoping, and head rendering in one place. This method remains for backward compatibility.

This method returns an undefined value.

Configure stylesheet registry for head rendering

Enables head rendering and configures namespace and cache strategy in a single call. All parameters are optional - calling without arguments enables head rendering with defaults.

Parameters:

  • namespace (Symbol, String, nil) (defaults to: nil) —

    Namespace identifier (nil/blank uses default)

  • cache_strategy (Symbol, String, Proc, nil) (defaults to: :none) —

    Cache strategy: :none (default), :time, :proc, :file

    • Symbol or String: :none, :time, :proc, :file (or "none", "time", "proc", "file")
    • Proc: Custom cache proc (automatically uses :proc strategy) Proc receives: (css_content, capsule_id, namespace) and should return [cache_key, should_cache, expires_at]
  • cache_ttl (Integer, ActiveSupport::Duration, nil) (defaults to: nil) —

    Time-to-live in seconds (for :time strategy). Supports ActiveSupport::Duration (e.g., 1.hour, 30.minutes)

  • cache_proc (Proc, nil) (defaults to: nil) —

    Custom cache proc (for :proc strategy, ignored if cache_strategy is a Proc) Proc receives: (css_content, capsule_id, namespace) and should return [cache_key, should_cache, expires_at]

  • namespace: (Symbol, String, nil) (defaults to: nil)
  • cache_strategy: (Symbol) (defaults to: :none)
  • cache_ttl: (Integer, ActiveSupport::Duration, nil) (defaults to: nil)
  • cache_proc: (Proc, nil) (defaults to: nil) 


92
93
94
95
96
97
98
99
100
101
 
# File 'lib/style_capsule/component_class_methods.rb', line 92

def stylesheet_registry(namespace: nil, cache_strategy: :none, cache_ttl: nil, cache_proc: nil)
  @head_rendering = true
  @stylesheet_namespace = namespace unless namespace.nil?

  # Normalize cache_strategy: convert strings to symbols, handle Proc
  normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy, cache_proc)
  @inline_cache_strategy = normalized_strategy
  @inline_cache_ttl = cache_ttl
  @inline_cache_proc = normalized_proc
end

#wrapper_tag ⇒ Symbol, String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get wrapper tag (checks instance variable, then parent class, defaults to :div)

Returns:

  • (Symbol, String) —

    The wrapper tag (default: :div)



269
270
271
272
273
274
275
276
277
 
# File 'lib/style_capsule/component_class_methods.rb', line 269

def wrapper_tag
  if defined?(@wrapper_tag) && @wrapper_tag
    @wrapper_tag
  elsif superclass.respond_to?(:wrapper_tag, true)
    superclass.wrapper_tag
  else
    :div
  end
end