scoped_css 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4cc56b9cf9562506d46c2afe9e006ba1b97150e1451a47b6b9c908252bfdbfe6
+  data.tar.gz: de380cffe066073f85e6d661b9b2ccf29c17094aba9671085ee85965e0534206
+SHA512:
+  metadata.gz: b89122d003f20e56b8fab45906a18fa24ca5fea48353db7bc43a6f4f1b967038863a6a69fa7f75489f779e0a622e6050efc3204982d6530173217bb39817a0ac
+  data.tar.gz: 3210446f837e4ec5900615b6d4a085e3f33aa5c1c652f08920f20edb3097af208635d48739981bb815b8942fe7332687fce1c61be13a989a546ee719a223b747

data/README.md

@@ -0,0 +1,268 @@
+# Scoped CSS
+
+
+## Installation
+
+  1. Add to your Gemfile:
+  `gem 'scoped_css'`
+  2. Run `bundle install`
+  3. Include the helper in your views:
+  ```ruby
+  module ApplicationHelper
+    include ScopedCss::Helper
+    # other helpers...
+  end 
+  ```
+  4. Use the helper in templates:
+  ```erb
+  <% style_string, styles = scoped_css do %>
+  <style>
+    .header { font-weight: bold; }
+    .content { margin: 10px; }
+  <style>
+  <% end %>
+
+  <h1 class="<%= styles[:header] %>">Title</h1>
+  <main class="<%= styles[:content] %>">Content here</main>
+
+  <%= style_string %>
+  ```
+
+## Usage with ViewComponent  
+
+_app/components/section_component.rb_
+```ruby
+class SectionComponent < ViewComponent::Base
+end
+```
+
+_app/components/section_component.html.erb_
+```erb
+<% style_string, styles = helpers.scoped_css do %>
+<style>
+  .section { 
+    border: none;
+    scroll-snap-align: center;
+    color: purple;
+  }
+  .heading {
+    font-size: 2rem;
+  }
+</style>
+<% end %>
+
+<section class="<%= styles[:section] %>">
+  <h2 class="<%= styles[:heading] %>">Section</h2>
+  <%= content %>
+</section>
+
+<%= style_string %>
+```
+
+## Attribute Splatting
+
+Sometimes you want to apply html attributes to a component from the parent template.
+
+
+_app/components/section_component.rb_
+```ruby
+class SectionComponent < ViewComponent::Base
+  def initialize(attributes: {})
+    @attributes = attributes
+  end
+end
+```
+
+_app/views/home/index.html.erb_
+```erb
+
+<% style_string, styles = scoped_css do %>
+<style>
+  .section {
+    margin: 10px;
+  }
+  .heading {
+    font-size: 3rem;
+  }
+</style>
+<% end %>
+
+<h1 class="<%= styles[:heading] %>">Title</h1>
+<%= render SectionComponent.new(attributes: { id: "important-section", class: styles[:section] }) do %>
+  <p>Section 1</p>
+<% end %>
+
+<%= style_string %>
+```
+
+_app/components/section_component.html.erb_
+```erb
+<% style_string, styles = helpers.scoped_css do %>
+<style>
+  .section { 
+    border: none;
+    scroll-snap-align: center;
+    color: purple;
+  }
+  .heading {
+    font-size: 2rem;
+  }
+</style>
+<% end %>
+
+<section <%= helpers.splat_attributes(@attributes, styles[:section]) %>>
+  <h2 class="<%= styles[:heading] %>">Section</h2>
+  <%= content %>
+</section>
+
+<%= style_string %>
+```
+
+:info: Note that `<section class="<%= styles[:heading] %>" <%= helpers.splat_attributes(@attributes, styles[:section]) %>>` is not used. Instead, the `splat_attributes` helper is used to apply the class attribute to the component. The `splat_attributes` helper takes CSS class names after the attributes argument and concatenates these CSS class names with any class names in the attributes hash.
+
+This will generate the following HTML:
+
+```html
+<!-- app/views/home/index.html.erb -->
+
+<h1 class=".atge5q2e-heading">Title</h1>
+
+<!-- app/components/section_component.html.erb -->
+
+<section class="agkd94j4-section atge5q2e-section" id="important-section">
+  <h2 class="agkd94j4-heading">
+</section>
+
+<section class="agkd94j4-section">
+  <h2 class="agkd94j4-heading">
+  <p>Section</p>
+</section>
+
+<style>
+  .agkd94j4-section {
+    border: none;
+    scroll-snap-align: center;
+    color: purple;
+  }
+  .agkd94j4-heading {
+    font-size: 2rem;
+  }
+</style>
+
+<!-- app/views/home/index.html.erb -->
+
+<style>
+  .atge5q2e-section {
+    margin: 10px;
+  }
+  .atge5q2e-heading {
+    font-size: 3rem;
+  }
+</style>
+
+```
+
+### CSS Specificity
+
+In previous examples, we applied the CSS class `.section` to the `<section>` element. It has the property `color: purple;`. But what if we want one instance of the SectionComponent to have a different color? In the parent template we can define a CSS class for the section component with the different color and apply it to the component.
+
+_app/components/section_component.rb_
+```ruby
+class SectionComponent < ViewComponent::Base
+  def initialize(attributes: {})
+    @attributes = attributes
+  end
+end
+```
+
+_app/components/section_component.html.erb_
+```erb
+<% style_string, styles = helpers.scoped_css do %>
+<style>
+  .section { 
+    border: none;
+    scroll-snap-align: center;
+    color: purple;
+  }
+  .heading {
+    font-size: 2rem;
+  }
+</style>
+<% end %>
+
+<section <%= helpers.splat_attributes(@attributes, styles[:section]) %>>
+  <h2 class="<%= styles[:heading] %>">Section</h2>
+  <%= content %>
+</section>
+
+<%= style_string %>
+```
+
+_app/views/home/index.html.erb_
+```erb
+<% style_string, styles = scoped_css do %>
+<style>
+  .section {
+    margin: 10px;
+    color: darkgreen;
+  }
+  .heading {
+    font-size: 3rem;
+  }
+</style>
+<% end %>
+
+<h1 class="<%= styles[:heading] %>">Title</h1>
+<%= render SectionComponent.new(attributes: { class: styles[:section] }) do %>
+  <p>Section 1</p>
+<% end %>
+
+<%= render SectionComponent.new() do %>
+  <p>Section 2</p>
+<% end %>
+
+<%= style_string %>
+```
+
+The reason this works is because the we render the style_string in each template at the bottom of the template. Any nested components style tag will be rendered before the parent style tag. The last declared selector has precedence. And because a scoped CSS class name is passed to the component only that instance of the component will use the new color.  
+
+```html
+<!-- app/views/home/index.html.erb -->
+
+<h1 class=".atge5q2e-heading">Title</h1>
+
+<!-- app/components/section_component.html.erb -->
+
+<section class="agkd94j4-section atge5q2e-section">
+  <h2 class="agkd94j4-heading">
+  <p>Section 1</p>
+</section>
+
+<section class="agkd94j4-section atge5q2e-section">
+  <h2 class="agkd94j4-heading">
+  <p>Section 2</p>
+</section>
+
+<style>
+  .agkd94j4-section {
+    border: none;
+    scroll-snap-align: center;
+    color: purple;
+  }
+  .agkd94j4-heading {
+    font-size: 2rem;
+  }
+</style>
+
+<!-- app/views/home/index.html.erb -->
+
+<style>
+  .atge5q2e-section {
+    margin: 10px;
+    color: darkgreen;
+  }
+  .atge5q2e-heading {
+    font-size: 3rem;
+  }
+</style>
+```

data/lib/scoped_css.rb

@@ -0,0 +1,96 @@
+require_relative "version"
+require "digest/sha2"
+require "erb"
+
+module ScopedCss
+  module Helper
+    def scoped_css(&css_block)
+      @per_template_outputs ||= Hash.new
+
+      css_block_content = ""
+      if block_given?
+        css_block_content = capture(&css_block)
+      end
+
+      prefix = "a#{Digest::SHA1.hexdigest(css_block_content)}"[0,8]
+
+      styles = Hash.new
+      prefixed_css_block_content = Rails.env.local? ? ' <!-- previously output --> ' : ''
+
+      if @per_template_outputs.has_key?(prefix)
+        styles = @per_template_outputs[prefix]
+      else
+       prefixed_css_block_content, styles =   prefix_css_classes(css_block_content, prefix)
+        @per_template_outputs[prefix] = styles
+      end
+
+      result = prefixed_css_block_content.respond_to?(:html_safe) ? prefixed_css_block_content.html_safe : prefixed_css_block_content
+      return [result, styles, prefix]
+    end
+
+    # Helper to take attribute hashes (or strings for classes) and format them
+    # into a string suitable for direct HTML attribute "splatting".
+    #
+    # Example usage in ERB:
+    # <section <%= splat_attributes(@attributes, styles[:section]) %>>
+    #   <%= content %>
+    # </section>
+    #
+    # @param args [Array<Hash, String>] One or more attribute hashes or class strings
+    # @return [String] A string of HTML attributes (e.g., 'class="foo bar" id="my-id"')
+    def splat_attributes(*args)
+      combined_attributes = merge_classes(*args)
+
+      # Convert the combined hash into an HTML attribute string
+      result = combined_attributes.map do |key, value|
+        html_key = key.to_s.gsub('_', '-')
+        escaped_value = ERB::Util.html_escape(value.to_s)
+
+        # Handle boolean attributes (e.g., 'disabled' instead of 'disabled="true"')
+        if value.is_a?(TrueClass) && !html_key.empty?
+          html_key
+        elsif value.is_a?(FalseClass)
+          # Don't render attributes that are explicitly false
+          nil
+        elsif !escaped_value.empty?
+          "#{html_key}=\"#{escaped_value}\""
+        else
+          nil # Don't render attributes with empty values
+        end
+      end.compact.join(" ").strip
+
+      result.respond_to?(:html_safe) ? result.html_safe : result
+    end
+
+    private
+
+    def prefix_css_classes(css_string, prefix)
+      updated_css_string = css_string.dup
+      class_name_map = {}
+      class_selector_regex = /\.([_a-zA-Z][_a-zA-Z0-9-]*)/
+
+      updated_css_string.gsub!(class_selector_regex) do |full_match|
+        original_class_name = Regexp.last_match[1]
+        prefixed_class_name = "#{prefix}-#{original_class_name}"
+        class_name_map[original_class_name.to_sym] = prefixed_class_name
+        ".#{prefixed_class_name}"
+      end
+
+      return updated_css_string, class_name_map
+    end
+
+    def merge_classes(attributes, *css_classes)
+      merged_attributes = attributes.dup
+
+      css_class_string = css_classes.compact.join(" ").strip
+
+      if merged_attributes[:class].nil? || merged_attributes[:class].empty?
+        merged_attributes[:class] = css_class_string
+      else
+        merged_attributes[:class] = "#{css_class_string} #{merged_attributes[:class]}".strip
+      end
+
+      merged_attributes
+    end
+  end
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module ScopedCss
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: scoped_css
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ewan McDougall
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Scope CSS to templates and ViewComponents
+email: ewan@mrloop.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/scoped_css.rb
+- lib/version.rb
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Scoped CSS
+test_files: []