view_component-scoped_styles 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43108a25040819bdeee257cd43228632e8de7822b24e96d675625208ff5f1544
-  data.tar.gz: 1023d48e94469ea2db73b971eb0c09440bdfb18167aea8abb461cb45e5bc6ed5
+  metadata.gz: 4518c4426e35b342ba212fb90ab4d5e4692d7427fdf5fdbe5ced923a71cc1e42
+  data.tar.gz: 601433c85c4aad6602831f8c53e662f73080d8bb40f9104f28fc8842411e0569
 SHA512:
-  metadata.gz: e40669a1884ae189bc18edcf04cad923e210875078095d6fd7238b3dd9ff061172253f8c6dd86632ee207cd3e1ae108bf04d1dac1866daedd948c078e0a95e50
-  data.tar.gz: 6f67241201f8e8452e8eec7e316ff4a1259496347bc62f58dc6b2a7739557dc3df7f4e69ce75cc1041843dcd5d95d9a3cc40d590d7108c917f3850ae630e89e0
+  metadata.gz: 8e9a1ab80bf24d000347be17e22d19e684a1ec1f70a08cf95952618c20891b84b8c50d34ab3f08e595c622659d77f5aa423eb5f2f11ebe0213aefa9af75cd9dc
+  data.tar.gz: 3846bc856b99e9be1f416e6616e33e4f0fa9388ddd7a253c714bc56198218543a68e17d5872a3aa1dbe92993691adf4257068f4f6e512aede4015d6c6296bdf1

data/README.md

@@ -1,4 +1,4 @@
-# ViewComponent::ScopedStyles
+# ViewComponent::ScopedStyles [![Gem Version](https://badge.fury.io/rb/view_component-scoped_styles.svg)](https://badge.fury.io/rb/view_component-scoped_styles)
 
 Scoped, colocated CSS for [ViewComponent](https://viewcomponent.org/).
 
@@ -8,13 +8,14 @@ E.g. `.button` becomes `.c-a1b2c3d4`
 
 ## Table of Contents
 
-- [ViewComponent::ScopedStyles](#viewcomponentscopedstyles)
+- [ViewComponent::ScopedStyles ](#viewcomponentscopedstyles-)
   - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
   - [Usage](#usage)
     - [1. Using a sidecar stylesheet](#1-using-a-sidecar-stylesheet)
     - [2. Using a styles block in the component](#2-using-a-styles-block-in-the-component)
     - [Referencing classes](#referencing-classes)
+    - [Ignoring classes](#ignoring-classes)
     - [Using the scoped CSS](#using-the-scoped-css)
   - [Configuration](#configuration)
   - [Related projects](#related-projects)
@@ -160,6 +161,49 @@ end
 </div>
 ```
 
+Scoped class names are prefixed by default (e.g. `c-a1b2c3d4`). Set a global prefix in configuration, or override per component with `css_class_prefix`:
+
+```ruby
+class ExampleComponent < ViewComponent::Base
+  include ViewComponent::ScopedStyles
+
+  css_class_prefix "vc-"
+
+  styles do
+    <<~CSS
+      .component { ... }  # becomes .vc-a1b2c3d4 in components.scoped.css
+    CSS
+  end
+end
+```
+
+### Ignoring classes
+
+Ignored classes are left unchanged in generated CSS:
+
+```ruby
+class ExampleComponent < ViewComponent::Base
+  include ViewComponent::ScopedStyles
+
+  ignored_css_classes "is-open", "active"
+
+  styles do
+    <<~CSS
+      .component { ... }
+      .is-open { ... }  # stays .is-open in components.scoped.css
+    CSS
+  end
+end
+```
+In your view, you can either reference the class directly:
+```erb
+<div class="<%= component_class %> is-open">
+```
+or via the `component_class` helper:
+```erb
+<div class="<%= component_class %> <%= component_class("is-open") %>">
+```
+
 ### Using the scoped CSS
 
 All scoped CSS will be compiled into `app/assets/stylesheets/components.scoped.css`.
@@ -191,6 +235,9 @@ ViewComponent::ScopedStyles.configure do |config|
 
   # Optional @layer name for components.scoped.css (e.g. "components"). Default: nil.
   config.components_layer = nil
+
+  # Prefix for scoped class names (e.g. "c-" produces "c-a1b2c3d4"). Default: "c-"
+  config.css_class_prefix = "c-"
 end
 ```
 
@@ -198,6 +245,7 @@ end
 | --- | --- | --- |
 | `components_path` | `"app/components"` | Where ViewComponent classes live, relative to `Rails.root`. |
 | `components_layer` | `nil` | When set, wraps generated CSS in `@layer <name> { ... }` for cascade control. |
+| `css_class_prefix` | `"c-"` | Prefix prepended to scoped class names (e.g. `"vc-"` → `"vc-a1b2c3d4"`). |
 
 ## Related projects
 

data/lib/generators/view_component/scoped_styles/install_generator.rb

@@ -34,6 +34,10 @@ module ViewComponent
         def components_layer_value
           configuration_defaults.components_layer.inspect
         end
+
+        def css_class_prefix_value
+          configuration_defaults.css_class_prefix.inspect
+        end
       end
     end
   end

data/lib/generators/view_component/scoped_styles/templates/view_component_scoped_styles.rb.tt

@@ -6,4 +6,7 @@ ViewComponent::ScopedStyles.configure do |config|
 
   # Optional @layer name for components.scoped.css (e.g. "components"). Default: nil.
   config.components_layer = <%= components_layer_value %>
+
+  # Prefix for scoped class names (e.g. "c-" produces "c-a1b2c3d4"). Default: "c-"
+  config.css_class_prefix = <%= css_class_prefix_value %>
 end

data/lib/view_component/scoped_styles/concern.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module ViewComponent
   module ScopedStyles
     extend ActiveSupport::Concern
@@ -9,11 +11,12 @@ module ViewComponent
 
     # Default root class for +component_class+ when it matches a selector in the CSS.
     COMPONENT_CSS_CLASS = "component".freeze
+    IGNORED_CSS_CLASSES = [].freeze
 
     class_methods do
       # Sets which CSS class is the root for +component_class+ (no argument).
-      # Also triggers style registration when Rails is loaded (registration also
-      # runs via the Railtie for all styled components).
+      # Also triggers style registration in development when Rails is loaded
+      # (registration also runs via the Railtie for all styled components).
       #
       # All class selectors are rewritten to scoped names in +components.scoped.css+.
       # The primary class uses an id from the full stylesheet (e.g. +.icon+ → +.c-99d08d5a+);
@@ -26,7 +29,39 @@ module ViewComponent
       # @param name [String, nil] selector name without a leading dot (e.g. +"icon"+)
       def component_css_class(name = nil)
         if name
-          const_set(:COMPONENT_CSS_CLASS, name)
+          const_set(:COMPONENT_CSS_CLASS, name.to_s)
+          clear_component_style_cache
+        end
+        register_styles_if_rails_loaded
+      end
+
+      # Declares CSS class selectors that are not rewritten to scoped names.
+      #
+      # Ignored classes stay in +components.scoped.css+ as written (e.g. +.is-open+).
+      # +component_class("is-open")+ returns the original name.
+      #
+      # Clears cached generated styles when the list changes.
+      #
+      # @param classes [String, Symbol] selector names without a leading dot
+      def ignored_css_classes(*classes)
+        if classes.any?
+          names = classes.flatten.map { |css_class| css_class.to_s.delete_prefix(".") }
+          const_set(:IGNORED_CSS_CLASSES, names.freeze)
+          clear_component_style_cache
+        end
+        register_styles_if_rails_loaded
+      end
+
+      # Sets the prefix for scoped class names on this component (e.g. +"vc-"+ → +"vc-a1b2c3d4"+).
+      #
+      # Overrides {ViewComponent::ScopedStyles.configuration}.css_class_prefix for this component.
+      #
+      # Clears cached generated styles when +prefix+ changes.
+      #
+      # @param prefix [String, nil] prefix without a hash suffix (e.g. +"c-"+, +"vc-"+)
+      def css_class_prefix(prefix = nil)
+        if prefix
+          const_set(:CSS_CLASS_PREFIX, prefix.to_s)
           clear_component_style_cache
         end
         register_styles_if_rails_loaded
@@ -40,8 +75,10 @@ module ViewComponent
         generate_component_styles
       end
 
-      # Writes this component's processed styles to the bundled or host stylesheet.
+      # Writes this component's processed styles to +components.scoped.css+.
+      # Only runs in development; production and test use the committed stylesheet.
       def register_styles
+        return unless register_styles_to_stylesheet?
         return unless @styles_block || has_stylesheet?
 
         Stylist.register(self)
@@ -66,18 +103,22 @@ module ViewComponent
       end
 
       def register_styles_if_rails_loaded
-        return unless defined?(Rails) && Rails.root
+        return unless register_styles_to_stylesheet?
         return unless defined?(Rails::Server) # only web server boot path
 
         register_styles
       end
 
+      def register_styles_to_stylesheet?
+        defined?(Rails::Application) && Rails.application && Rails.env.development?
+      end
+
       def generate_component_styles
         styles_content = generate_styles_content
         css_classes = extract_css_classes(styles_content)
         primary_class = primary_css_class(css_classes)
 
-        @component_id = generate_component_id(styles_content)
+        @component_id = component_id_for(primary_class, styles_content)
         @component_class_map = build_component_class_map(styles_content, css_classes, primary_class)
         @component_styles = replace_css_classes(styles_content, @component_class_map)
       end
@@ -97,30 +138,52 @@ module ViewComponent
 
       def build_component_class_map(styles_content, css_classes, primary_class)
         css_classes.index_with do |css_class|
-          if css_class == primary_class
-            @component_id
+          if ignored_css_class?(css_class)
+            css_class
           else
-            generate_scoped_class_id(styles_content, css_class)
+            generate_scoped_class_id(styles_content, css_class, primary_class)
           end
         end
       end
 
       def replace_css_classes(styles_content, class_map)
-        class_map.keys.sort_by(&:length).reverse.reduce(styles_content) do |content, css_class|
+        scoped_map = class_map.reject do |css_class, scoped|
+          css_class == scoped
+        end
+
+        sorted_classes = scoped_map.keys.sort_by(&:length).reverse
+
+        sorted_classes.reduce(styles_content) do |content, css_class|
           content.gsub(/\.#{Regexp.escape(css_class)}\b/, ".#{class_map[css_class]}")
         end
       end
 
-      def generate_component_id(styles_content)
-        hash = Digest::MD5.hexdigest(styles_content)[0..7]
+      def component_id_for(primary_class, styles_content)
+        if ignored_css_class?(primary_class)
+          primary_class
+        else
+          generate_scoped_class_id(styles_content, primary_class, primary_class)
+        end
+      end
 
-        "c-#{hash}"
+      def ignored_css_class?(css_class)
+        self::IGNORED_CSS_CLASSES.include?(css_class)
       end
 
-      def generate_scoped_class_id(styles_content, css_class)
-        hash = Digest::MD5.hexdigest("#{styles_content}:#{css_class}")[0..7]
+      def generate_scoped_class_id(styles_content, css_class, primary_class)
+        is_primary = css_class == primary_class
+        input = is_primary ? styles_content : "#{styles_content}:#{css_class}"
+        hash = ::Digest::MD5.hexdigest(input)[0..7]
 
-        "c-#{hash}"
+        "#{scoped_css_class_prefix}#{hash}"
+      end
+
+      def scoped_css_class_prefix
+        if const_defined?(:CSS_CLASS_PREFIX, false)
+          self::CSS_CLASS_PREFIX
+        else
+          ViewComponent::ScopedStyles.configuration.css_class_prefix
+        end
       end
 
       def clear_component_style_cache

data/lib/view_component/scoped_styles/configuration.rb

@@ -25,9 +25,15 @@ module ViewComponent
       # @return [String, nil] default: +nil+ (no layer wrapper)
       attr_accessor :components_layer
 
+      # Prefix prepended to scoped class names (e.g. +"c-"+ → +"c-a1b2c3d4"+).
+      #
+      # @return [String] default: +"c-"+
+      attr_accessor :css_class_prefix
+
       def initialize
         @components_path = File.join("app", "components")
         @components_layer = nil
+        @css_class_prefix = "c-"
       end
     end
 

data/lib/view_component/scoped_styles/railtie.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/module/delegation"
 require "rails/railtie"
 
 module ViewComponent
   module ScopedStyles
     class Railtie < Rails::Railtie
       config.after_initialize do
+        next unless Rails.env.development?
+
         ViewComponent::ScopedStyles::Railtie.load_and_register_components
       end
 
-      if Rails.env.development?
-        config.to_prepare do
+      initializer "view_component.scoped_styles.reload" do |app|
+        next unless Rails.env.development?
+
+        app.config.to_prepare do
           ViewComponent::ScopedStyles::Railtie.register_components
         end
       end

data/lib/view_component/scoped_styles/version.rb

@@ -2,6 +2,6 @@
 
 module ViewComponent
   module ScopedStyles
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_component-scoped_styles
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chris Edwards