style_capsule 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a5a88ff582594a22522f2b0349e54bfb235d42839a80b29a9118488a09f82df
+  data.tar.gz: 4bf81ae48a9cfe5ef9e0b7c5f8ae00abeb38dbdf7ea2dc930293036b1c375832
+SHA512:
+  metadata.gz: a75e75f5c7d04616306d2ddaaea7a528eb2d4179071cb96ff6e360d854e940dddcfbfe271bf65fb3e6b4d5957961e5c116708f4017d5e9becd1ee3a76053bce3
+  data.tar.gz: b7981f706126585a59659ed0c6e3ec61c40a85767ac72c16a9908c6739a5956bcd2bb9c24f20593bc42402ecccfc5a747b042f85b13a07268dfe747555cb56c4

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# CHANGELOG
+
+## 1.0.2 (2025-11-21)
+
+- Fix default output directory for CSS files to app/assets/builds/capsules/
+
+## 1.0.1 (2025-11-21)
+
+- Update ViewComponent dependency to version 4.0 and adjust compatibility in tests
+- Enhance error handling in style_capsule Rake task for ViewComponent loading issues
+- Remove Rails 6 support from Appraisals file and update Rails 7.2 dependencies
+- Update Rails and ActiveSupport version requirements
+- Add Codecov badge to README
+
+## 1.0.0 (2025-11-20)
+
+- Initial stable release
+- Attribute-based CSS scoping for Phlex components, ViewComponent, and ERB templates
+- Component-scoped CSS encapsulation using `[data-capsule="..."]` selectors (combined selector format: `[data-capsule="..."].class`)
+- Per-component-type scope IDs (shared across all instances)
+- Automatic HTML wrapping with scoped elements
+- CSS processor with support for regular selectors, pseudo-classes, `@media` queries, `@keyframes`, and component-scoped `:host` selectors
+- Thread-safe stylesheet registry for head rendering with namespace support
+- Multiple caching strategies: no caching, time-based, custom proc, and file-based caching
+- File-based caching with Rails asset pipeline integration and Rake tasks
+- Security features: path traversal protection, CSS size limits (1MB), scope ID validation, filename validation
+- Ruby >= 3.0 requirement
+- Comprehensive test suite with > 93% coverage
+

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,398 @@
+# style_capsule
+
+[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=1.0.1)](https://badge.fury.io/rb/style_capsule) [![Test Status](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/style_capsule.rb/graph/badge.svg?token=2U6NXJOVVM)](https://codecov.io/gh/amkisko/style_capsule.rb)
+
+CSS scoping extension for Rails components. Provides attribute-based style encapsulation for Phlex, ViewComponent, and ERB templates to prevent style leakage between components. Includes configurable caching strategies for optimal performance.
+
+Sponsored by [Kisko Labs](https://www.kiskolabs.com).
+
+<a href="https://www.kiskolabs.com">
+  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
+</a>
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "style_capsule"
+```
+
+Then run `bundle install`.
+
+## Features
+
+- **Attribute-based CSS scoping** (no class name renaming)
+- **Phlex, ViewComponent, and ERB support** with automatic Rails integration
+- **Per-component-type scope IDs** (shared across instances)
+- **CSS Nesting support** (optional, more performant, requires modern browsers)
+- **Stylesheet registry** with thread-safe head rendering, namespace support, and compatibility with Propshaft and other asset bundlers
+- **Multiple cache strategies**: none, time-based, custom proc, and file-based (HTTP caching)
+- **Security protections**: path traversal protection, input validation, size limits
+
+## Usage
+
+### Phlex Components
+
+```ruby
+class MyComponent < ApplicationComponent
+  include StyleCapsule::Component
+
+  def component_styles
+    <<~CSS
+      .section { color: red; }
+      .heading:hover { opacity: 0.8; }
+    CSS
+  end
+
+  def view_template
+    div(class: "section") do
+      h2(class: "heading") { "Hello" }
+    end
+  end
+end
+```
+
+CSS is automatically scoped with `[data-capsule="..."]` attributes and content is wrapped in a scoped element.
+
+### ViewComponent
+
+```ruby
+class MyComponent < ApplicationComponent
+  include StyleCapsule::ViewComponent
+
+  def component_styles
+    <<~CSS
+      .section { color: red; }
+    CSS
+  end
+
+  def call
+    content_tag :div, class: "section" do
+      "Hello"
+    end
+  end
+end
+```
+
+### ERB Templates
+
+```erb
+<%= style_capsule do %>
+  <style>
+    .section { color: red; }
+  </style>
+  <div class="section">Content</div>
+<% end %>
+```
+
+## CSS Scoping Strategies
+
+StyleCapsule supports two CSS scoping strategies:
+
+1. **Selector Patching (default)**: Adds `[data-capsule="..."]` prefix to each selector
+   - Better browser support (all modern browsers)
+   - Output: `[data-capsule="abc123"] .section { color: red; }`
+
+2. **CSS Nesting (optional)**: Wraps entire CSS in `[data-capsule="..."] { ... }`
+   - More performant (no CSS parsing needed)
+   - Requires CSS nesting support (Chrome 112+, Firefox 117+, Safari 16.5+)
+   - Output: `[data-capsule="abc123"] { .section { color: red; } }`
+
+### Configuration
+
+**Per-component:**
+
+```ruby
+class MyComponent < ApplicationComponent
+  include StyleCapsule::Component
+  css_scoping_strategy :nesting  # Use CSS nesting
+end
+```
+
+**Global (in base component class):**
+
+```ruby
+class ApplicationComponent < Phlex::HTML
+  include StyleCapsule::Component
+  css_scoping_strategy :nesting  # Enable for all components
+end
+```
+
+**Note:** If you change the strategy and it doesn't take effect, clear the CSS cache:
+
+```ruby
+MyComponent.clear_css_cache
+```
+
+## Stylesheet Registry
+
+For better performance, register styles for head rendering instead of rendering `<style>` tags in the body:
+
+```ruby
+class MyComponent < ApplicationComponent
+  include StyleCapsule::Component
+  stylesheet_registry namespace: :admin  # Optional namespace
+
+  def component_styles
+    <<~CSS
+      .section { color: red; }
+    CSS
+  end
+end
+```
+
+With cache strategy:
+
+```ruby
+class MyComponent < ApplicationComponent
+  include StyleCapsule::Component
+  stylesheet_registry namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+
+  def component_styles
+    <<~CSS
+      .section { color: red; }
+    CSS
+  end
+end
+```
+
+Then in your layout:
+
+```erb
+<head>
+  <%= stylesheet_registrymap_tags %>
+  <%= stylesheet_registrymap_tags(namespace: :admin) %>
+</head>
+```
+
+Or in Phlex (requires including `StyleCapsule::PhlexHelper`):
+
+```ruby
+head do
+  stylesheet_registrymap_tags
+end
+```
+
+### Registering Stylesheet Files
+
+You can also register external stylesheet files (not inline CSS) for head rendering:
+
+**In ERB:**
+
+```erb
+<% register_stylesheet("stylesheets/user/order_select_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" }
+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")
+end
+```
+
+Registered files are rendered via `stylesheet_registrymap_tags` in your layout, just like inline CSS.
+
+## Caching Strategies
+
+### No Caching (Default)
+
+```ruby
+class MyComponent < ApplicationComponent
+  include StyleCapsule::Component
+  stylesheet_registry  # No cache strategy set (default: :none)
+end
+```
+
+### Time-Based Caching
+
+```ruby
+stylesheet_registry 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
+```
+
+### Custom Proc Caching
+
+```ruby
+stylesheet_registry cache_strategy: ->(css, capsule_id, namespace) {
+  cache_key = "css_#{capsule_id}_#{namespace}"
+  should_cache = css.length > 100
+  expires_at = Time.now + 1800
+  [cache_key, should_cache, expires_at]
+}
+```
+
+**Note:** `cache_strategy` accepts Symbol (`:time`), String (`"time"`), or Proc. Strings are automatically converted to symbols.
+
+### File-Based Caching (HTTP Caching)
+
+Writes CSS to files for HTTP caching. **Requires class method `def self.component_styles`**:
+
+```ruby
+class MyComponent < ApplicationComponent
+  include StyleCapsule::Component
+  stylesheet_registry cache_strategy: :file
+
+  # Must use class method for file caching
+  def self.component_styles
+    <<~CSS
+      .section { color: red; }
+    CSS
+  end
+end
+```
+
+**Configuration:**
+
+```ruby
+# config/initializers/style_capsule.rb
+StyleCapsule::CssFileWriter.configure(
+  output_dir: Rails.root.join("app/assets/builds/capsules"),
+  filename_pattern: ->(component_class, capsule_id) {
+    "capsule-#{capsule_id}.css"
+  }
+)
+```
+
+**Precompilation:**
+
+```bash
+bin/rails style_capsule:build  # Build CSS files
+bin/rails style_capsule:clear  # Clear generated files
+```
+
+Files are automatically built during `bin/rails assets:precompile`.
+
+**Compatibility:** The stylesheet registry works with Propshaft, Sprockets, and other Rails asset bundlers. Static file paths are collected in a process-wide manifest (similar to Propshaft's approach), while inline CSS is stored per-request.
+
+## Advanced Usage
+
+### Database-Stored CSS
+
+For CSS stored in a database (e.g., user-generated styles, themes), use StyleCapsule's CSS processor directly:
+
+```ruby
+# app/models/theme.rb
+class Theme < ApplicationRecord
+  def generate_capsule_id
+    return capsule_id if capsule_id.present?
+    scope_key = "theme_#{id}_#{name}"
+    self.capsule_id = "a#{Digest::SHA1.hexdigest(scope_key)}"[0, 8]
+    save! if persisted?
+    capsule_id
+  end
+
+  def scoped_css
+    return scoped_css_cache if scoped_css_cache.present? && 
+                               scoped_css_updated_at == updated_at
+    
+    current_capsule_id = generate_capsule_id
+    scoped = StyleCapsule::CssProcessor.scope_selectors(css_content, current_capsule_id)
+    
+    update_columns(
+      scoped_css_cache: scoped,
+      scoped_css_updated_at: updated_at,
+      capsule_id: current_capsule_id
+    )
+    
+    scoped
+  end
+end
+```
+
+**Usage:**
+
+```erb
+<div data-capsule="<%= theme.capsule_id %>">
+  <style><%= raw theme.scoped_css %></style>
+  <div class="header">Content</div>
+</div>
+```
+
+## CSS Selector Support
+
+- Regular selectors: `.section`, `#header`, `div.container`
+- Pseudo-classes and pseudo-elements: `.button:hover`, `.item::before`
+- Multiple selectors: `.a, .b, .c { color: red; }`
+- Component-scoped selectors: `:host`, `:host(.active)`, `:host-context(.theme-dark)`
+- Media queries: `@media (max-width: 768px) { ... }`
+
+## How It Works
+
+1. **Scope ID Generation**: Each component class gets a unique scope ID based on its class name (shared across all instances)
+2. **CSS Rewriting**: CSS selectors are rewritten to include `[data-capsule="..."]` attribute selectors
+3. **HTML Wrapping**: Component content is automatically wrapped in a scoped element
+4. **No Class Renaming**: Class names remain unchanged (unlike Shadow DOM)
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0, < 9.0
+- ActiveSupport >= 7.0, < 9.0
+
+## Development
+
+```bash
+bundle install
+bundle exec appraisal install
+
+# Run tests
+bundle exec rspec
+
+# Run tests for all Rails versions
+bundle exec appraisal rails72 rspec
+bundle exec appraisal rails8ruby34 rspec
+
+# Linting
+bundle exec standardrb --fix
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/amkisko/style_capsule.rb
+
+Contribution policy:
+- New features are not necessarily added to the gem
+- Pull requests should have test coverage and changelog entry
+
+Review policy:
+- Critical fixes: up to 2 calendar weeks
+- Pull requests: up to 6 calendar months
+- Issues: up to 1 calendar year
+
+## Publishing
+
+```sh
+rm style_capsule-*.gem
+gem build style_capsule.gemspec
+gem push style_capsule-*.gem
+```
+
+## Security
+
+StyleCapsule includes security protections:
+- Path traversal protection
+- Input validation
+- Size limits (1MB per component)
+- XSS prevention via Rails' HTML escaping
+
+For detailed security information, see [SECURITY.md](SECURITY.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.md).

data/SECURITY.md

@@ -0,0 +1,55 @@
+# SECURITY
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Security Guidelines
+
+StyleCapsule provides minimal security protections to assist with automated CSS scoping. The gem does not validate, sanitize, or secure CSS content itself—this is the application's responsibility.
+
+### What StyleCapsule Protects
+
+- **Path Traversal**: Filenames are validated when writing CSS files to prevent directory traversal attacks
+- **Input Size Limits**: CSS content is limited to 1MB per component to prevent resource exhaustion
+- **Scope ID Validation**: Capsule IDs are validated to prevent injection into HTML attributes
+
+### What StyleCapsule Does NOT Control
+
+**Developer Responsibility:**
+- **CSS Content**: StyleCapsule does not validate or sanitize CSS content. Malicious CSS (e.g., data exfiltration via `@import`, CSS injection attacks) is not prevented by the gem
+- **User Input**: Applications must validate and sanitize user-provided CSS before passing it to StyleCapsule
+- **Developer Intent**: The gem trusts that developers provide safe CSS content from trusted sources
+
+**Rails Framework:**
+- HTML escaping is handled by Rails' built-in helpers (`content_tag`, etc.)
+- Content Security Policy (CSP) must be configured at the application level
+- File system permissions and access control are managed by the application
+
+### Security Best Practices
+
+1. **Validate User Input**: Never pass untrusted CSS content to StyleCapsule without validation
+2. **Use Content Security Policy**: Configure CSP headers to restrict inline styles and external resources
+3. **Sanitize User-Generated CSS**: If allowing user input, sanitize CSS before processing
+4. **Keep Dependencies Updated**: Use supported Ruby (>= 3.0) and Rails versions with security patches
+5. **Review Generated Files**: Periodically review files in `app/assets/builds/capsules/` if using file-based caching
+
+### Reporting a Vulnerability
+
+If you discover a security vulnerability, please **do not** open a public issue. Instead:
+
+1. **Email**: contact@kiskolabs.com
+2. **Subject**: `[SECURITY] style_capsule vulnerability report`
+3. **Include**: Description, steps to reproduce, potential impact, and suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and provide an initial assessment within 7 days.
+
+### Security Updates
+
+Security updates are released as patch versions (e.g., 1.0.1, 1.0.2) and announced via:
+- GitHub Security Advisories
+- RubyGems release notes
+- CHANGELOG.md