view_component-scoped_styles 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a23828ee0e2dafc7e52ccb67a8a319391af70a50777701d5090e66626d159c3
-  data.tar.gz: b5a87e35910c84ae1a95914af878506b6fdd3c155071fca950f2fa8d76b61a8c
+  metadata.gz: c1612f1fbc0f2b03fa6930fd04b2749a914795ec7c4c23dd3d9f3a6b09ac0666
+  data.tar.gz: 443a89edf71c93e6af8bea761c77c4ed1c9d8788005fcfe21a90cf8371bd118f
 SHA512:
-  metadata.gz: 026faad956f24fd8638fa4834b3d428d9363ed9e9d5d43de724df68e189edc998cd268140a3094881fb51b77677c5cb1e627b1819bbd8d3d4dfa5d349a778604
-  data.tar.gz: d947bece5e61141621b4674c91b947afcb8782103af7938ca5b3a2f57208258dea9333af44e2c8d85b2b67e354bd0710bbd8c33eef47518b411776d7ec99e5de
+  metadata.gz: 84893c6c973b772ed5780eebb9400201ea01b1e3e9db1489dff02eb03ce7e9c5591dd6ab34cf6528c63136ddfe69a392bd6def73904057389493115f35d6c487
+  data.tar.gz: 69d6aad3940294c2a3a809926594a9f081115c244d6fe19ef23f3ccd8126ff9fc87d5bb81e9c50edeb046c936e61a03eb387255bbf5d014ebad42c08c8909628

data/README.md

@@ -4,7 +4,7 @@ Scoped, colocated CSS for [ViewComponent](https://viewcomponent.org/).
 
 Avoids collisions by rewriting class selectors to stable, content-derived names.
 
-E.g. `.button` becomes `.c-a1b2c3d4`
+E.g. `.button` becomes `.button_a1b2c3d4`
 
 ## Table of Contents
 
@@ -60,6 +60,21 @@ CSS can be written in two ways:
 
 Learn more about sidecar [here](https://viewcomponent.org/guide/generators.html#place-the-view-in-a-sidecar-directory).
 
+```bash
+bin/rails generate view_component:component Example title --sidecar
+```
+
+With automatic stylesheet generation enabled in `config/application.rb`, `config/ENVIRONMENT.rb`, or wherever you configure ViewComponent:
+
+```ruby
+# Ensure sidebar is enabled
+config.view_component.generate.sidecar = true
+# Then generate stylesheets via
+config.view_component.generate.stylesheet = true
+```
+
+`view_component:component` also creates the sidecar `.css` file, adds `include ViewComponent::ScopedStyles` to the component class, and sets `class="<%= component_class %>"` on the generated ERB template. You can pass `--no-stylesheet` to skip CSS generation for a single component.
+
 ```bash
 bin/rails generate view_component:component Example title --sidecar
 
@@ -68,10 +83,12 @@ bin/rails generate view_component:component Example title --sidecar
       create    test/components/example_component_test.rb
       invoke  erb
       create    app/components/example_component/example_component.html.erb
+      invoke  stylesheet
+      create    app/components/example_component/example_component.css
 
 ```
 
-Then add a matching stylesheet in the sidecar directory:
+Or add a matching stylesheet manually in the sidecar directory:
 
 ```css
 /* app/components/example_component/example_component.css */
@@ -161,22 +178,76 @@ 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`:
+You can also reference scoped classes from another component by passing the component class with `from:`:
+
+```erb
+<div class="<%= component_class(from: ButtonComponent) %>">
+  Button root class
+</div>
+
+<div class="<%= component_class("icon", from: ButtonComponent) %>">
+  Button icon class
+</div>
+```
+
+Inside sidecar stylesheets or `styles` blocks, use `:component(...)` as a compile-time reference to another component's scoped classes:
+
+```css
+.component:has(:component(ButtonComponent, icon)) {
+  padding-inline-end: 2rem;
+}
+
+:where(:component(CardComponent), :component(PanelComponent)) .title {
+  margin: 0;
+}
+```
+
+The first argument is the component constant, and the optional second argument is the class selector without a leading dot. When the class name is omitted, the referenced component's root class is used. `:component(...)` is replaced while scoped CSS is generated, so it can be used inside more complex selectors like `:where()`, `:is()`, `:not()`, and `:has()`.
+
+Scoped class names are prefixed by default using the class name (e.g. `.component` → `component_a1b2c3d4`). Set a global prefix in configuration, or override per component with `css_class_prefix`.
+
+The prefix is a template string. Use `{class_name}` for the CSS class being scoped and `{component_name}` for the component name (namespaces joined by `/`, with a trailing `Component` suffix removed):
+
+```ruby
+ViewComponent::ScopedStyles.configure do |config|
+  config.css_class_prefix = "{class_name}_"  # default
+end
+```
 
 ```ruby
 class ExampleComponent < ViewComponent::Base
   include ViewComponent::ScopedStyles
 
-  css_class_prefix "vc-"
+  css_class_prefix "vc-{class_name}_"
+
+  styles do
+    <<~CSS
+      .component { ... }  # becomes .vc-component_a1b2c3d4 in components.scoped.css
+    CSS
+  end
+end
+```
+
+Namespaced components can include the component name in the prefix:
+
+```ruby
+class Admin::UserCardComponent < ViewComponent::Base
+  include ViewComponent::ScopedStyles
+
+  css_class_prefix "{component_name}_{class_name}_"
 
   styles do
     <<~CSS
-      .component { ... }  # becomes .vc-a1b2c3d4 in components.scoped.css
+      .component { ... }
+      # Admin/UserCardComponent_component_a1b2c3d4 in templates;
+      # Admin\/UserCardComponent_component_a1b2c3d4 in components.scoped.css
     CSS
   end
 end
 ```
 
+**Upgrading from 0.4.x:** set `config.css_class_prefix = "c-"` (and per-component overrides) to keep the previous `c-a1b2c3d4` class names without updating templates.
+
 ### Ignoring classes
 
 Ignored classes are left unchanged in generated CSS:
@@ -242,8 +313,8 @@ ViewComponent::ScopedStyles.configure do |config|
   # Optional @layer name for the bundled scoped stylesheet (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-"
+  # Prefix for scoped class names. Supports {component_name} and {class_name}. Default: "{class_name}_"
+  config.css_class_prefix = "{class_name}_"
 end
 ```
 
@@ -253,7 +324,7 @@ end
 | `assets_path` | `"app/assets/stylesheets"` | Directory where the bundled scoped stylesheet is written, relative to `Rails.root`. |
 | `stylesheet_name` | `"components.scoped.css"` | Filename of the bundled scoped stylesheet within `assets_path`. |
 | `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"`). |
+| `css_class_prefix` | `"{class_name}_"` | Prefix template for scoped class names. Supports `{class_name}` and `{component_name}` (namespaces joined by `/`, `Component` suffix stripped; e.g. `.component` → `component_a1b2c3d4`). Use `"c-"` to match 0.4.x behavior. |
 
 ## Related projects
 

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

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Optional ViewComponent generator settings (in config/application.rb, config/ENVIRONMENT.rb, or wherever you configure ViewComponent):
+# Ensure sidebar is enabled
+# config.view_component.generate.sidecar = true
+# Then generate stylesheets via
+# config.view_component.generate.stylesheet = true
+
 ViewComponent::ScopedStyles.configure do |config|
   # Where ViewComponent classes live (relative to Rails.root). Default: "app/components"
   config.components_path = <%= components_path_expression %>
@@ -13,6 +19,6 @@ ViewComponent::ScopedStyles.configure do |config|
   # Optional @layer name for the bundled scoped stylesheet (e.g. "components"). Default: nil.
   config.components_layer = <%= components_layer_value %>
 
-  # Prefix for scoped class names (e.g. "c-" produces "c-a1b2c3d4"). Default: "c-"
+  # Prefix for scoped class names. Supports {component_name} and {class_name} variables. Default: "{class_name}_"
   config.css_class_prefix = <%= css_class_prefix_value %>
 end

data/lib/generators/view_component/stylesheet/stylesheet_generator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "generators/view_component/abstract_generator"
+
+module ViewComponent
+  module Generators
+    class StylesheetGenerator < ::Rails::Generators::NamedBase
+      include ViewComponent::AbstractGenerator
+
+      source_root File.expand_path("templates", __dir__)
+      class_option :sidecar, type: :boolean, default: false
+      class_option :skip_suffix, type: :boolean, default: false
+
+      def create_stylesheet
+        template "component.css", stylesheet_destination
+      end
+
+      def inject_scoped_styles_module
+        return unless File.exist?(absolute_component_rb_path)
+
+        content = File.read(absolute_component_rb_path)
+        return if content.include?("ViewComponent::ScopedStyles")
+
+        class_name_pattern = component_class_name.split("::").last
+        match = content.match(/^(\s*)class #{Regexp.escape(class_name_pattern)}\b[^\n]*\n/)
+        return unless match
+
+        indent = "#{match[1]}  "
+        inject_into_file component_rb_path,
+          "#{indent}include ViewComponent::ScopedStyles\n",
+          after: match[0]
+      end
+
+      def update_view_template
+        return if options["inline"] || options["call"]
+
+        path = view_template_path
+        return unless File.exist?(File.join(destination_root, path))
+
+        gsub_file path, /<div/, '<div class="<%= component_class %>"', verbose: false
+      end
+
+      private
+
+      def absolute_component_rb_path
+        File.join(destination_root, component_rb_path)
+      end
+
+      def component_file_name
+        "#{file_name}#{"_component" unless options[:skip_suffix]}"
+      end
+
+      def component_class_name
+        "#{class_name}#{"Component" unless options[:skip_suffix]}"
+      end
+
+      def component_rb_path
+        File.join(component_path, class_path, "#{component_file_name}.rb")
+      end
+
+      def stylesheet_destination
+        if sidecar?
+          File.join(
+            component_path, class_path, component_file_name, "#{component_file_name}.css"
+          )
+        else
+          File.join(component_path, class_path, "#{component_file_name}.css")
+        end
+      end
+
+      def view_template_path
+        File.join(destination_directory, "#{destination_file_name}.html.erb")
+      end
+    end
+  end
+end

data/lib/generators/view_component/stylesheet/templates/component.css.tt

@@ -0,0 +1,3 @@
+.component {
+  /* TODO: add component styles */
+}

data/lib/view_component/scoped_styles/component_generator_hook.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "generators/view_component/component/component_generator"
+
+module ViewComponent
+  module Generators
+    class ComponentGenerator
+      class_option :stylesheet, type: :boolean,
+        default: ViewComponent::Base.config.generate.stylesheet
+
+      hook_for :stylesheet, type: :boolean
+    end
+  end
+end

data/lib/view_component/scoped_styles/concern.rb

@@ -8,6 +8,15 @@ module ViewComponent
 
     CACHED_VARIABLES = %i[@component_styles @component_id @component_class_map].freeze
     CLASS_SELECTOR_PATTERN = /\.([a-zA-Z_][\w-]*)\b/
+    COMPONENT_REFERENCE_PATTERN = /
+      :component\(
+        \s*
+        (?<component_name>[A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)
+        \s*
+        (?:,\s*(?<css_class>[a-zA-Z_][\w-]*)\s*)?
+      \)
+    /x
+    COMPONENT_RESOLUTION_STACK_KEY = :view_component_scoped_styles_component_resolution_stack
 
     # Default root class for +component_class+ when it matches a selector in the CSS.
     COMPONENT_CSS_CLASS = "component".freeze
@@ -52,13 +61,14 @@ module ViewComponent
         register_styles_if_rails_loaded
       end
 
-      # Sets the prefix for scoped class names on this component (e.g. +"vc-"+ → +"vc-a1b2c3d4"+).
+      # Sets the prefix template for scoped class names on this component.
       #
       # Overrides {ViewComponent::ScopedStyles.configuration}.css_class_prefix for this component.
+      # Supports +{component_name}+ and +{class_name}+ template variables.
       #
       # Clears cached generated styles when +prefix+ changes.
       #
-      # @param prefix [String, nil] prefix without a hash suffix (e.g. +"c-"+, +"vc-"+)
+      # @param prefix [String, nil] prefix template without a hash suffix (e.g. +"{class_name}_"+)
       def css_class_prefix(prefix = nil)
         if prefix
           const_set(:CSS_CLASS_PREFIX, prefix.to_s)
@@ -114,13 +124,26 @@ module ViewComponent
       end
 
       def generate_component_styles
+        pushed = false
+
+        if component_resolution_stack.include?(self)
+          names = (component_resolution_stack + [self]).map { |component| component.name || component.inspect }
+          raise ArgumentError, "Circular scoped style component reference: #{names.join(" -> ")}"
+        end
+
+        component_resolution_stack.push(self)
+        pushed = true
         styles_content = generate_styles_content
         css_classes = extract_css_classes(styles_content)
         primary_class = primary_css_class(css_classes)
 
         @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)
+        @component_styles = replace_component_references(
+          replace_css_classes(styles_content, @component_class_map)
+        )
+      ensure
+        component_resolution_stack.pop if pushed
       end
 
       def generate_styles_content
@@ -154,7 +177,20 @@ module ViewComponent
         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]}")
+          scoped = class_map[css_class]
+          escaped = CssClassPrefix.escape_for_css_selector(scoped)
+          content.gsub(/\.#{Regexp.escape(css_class)}\b/, ".#{escaped}")
+        end
+      end
+
+      def replace_component_references(styles_content)
+        styles_content.gsub(COMPONENT_REFERENCE_PATTERN) do
+          component_name = Regexp.last_match[:component_name]
+          css_class = Regexp.last_match[:css_class]
+          component_class = resolve_component_reference(component_name)
+          scoped_class = scoped_component_class(component_class, css_class)
+
+          ".#{CssClassPrefix.escape_for_css_selector(scoped_class)}"
         end
       end
 
@@ -175,7 +211,20 @@ module ViewComponent
         input = is_primary ? styles_content : "#{styles_content}:#{css_class}"
         hash = ::Digest::MD5.hexdigest(input)[0..7]
 
-        "#{scoped_css_class_prefix}#{hash}"
+        prefix = CssClassPrefix.interpolate(
+          scoped_css_class_prefix,
+          component_name: scoped_component_name,
+          class_name: css_class
+        )
+        "#{prefix}#{hash}"
+      end
+
+      def scoped_component_name
+        return "" unless name
+
+        parts = name.split("::")
+        parts[-1] = parts[-1].delete_suffix("Component")
+        parts.join("/")
       end
 
       def scoped_css_class_prefix
@@ -186,6 +235,36 @@ module ViewComponent
         end
       end
 
+      def resolve_component_reference(component_name)
+        component_name.to_s.split("::").inject(Object) do |namespace, constant_name|
+          namespace.const_get(constant_name)
+        end
+      rescue NameError
+        raise ArgumentError, "Unable to resolve scoped style component reference: #{component_name}"
+      end
+
+      def scoped_component_class(component_class, css_class = nil)
+        unless component_class.respond_to?(:component_styles)
+          raise ArgumentError, "#{component_class} does not include ViewComponent::ScopedStyles"
+        end
+
+        component_class.component_styles
+
+        if css_class
+          scoped = component_class.instance_variable_get(:@component_class_map)[css_class.to_s.delete_prefix(".")]
+
+          raise ArgumentError, "#{component_class.name || component_class} does not define .#{css_class}" unless scoped
+
+          scoped
+        else
+          component_class.instance_variable_get(:@component_id)
+        end
+      end
+
+      def component_resolution_stack
+        Thread.current[COMPONENT_RESOLUTION_STACK_KEY] ||= []
+      end
+
       def clear_component_style_cache
         CACHED_VARIABLES.each do |ivar|
           remove_instance_variable(ivar) if instance_variable_defined?(ivar)
@@ -199,28 +278,30 @@ module ViewComponent
     # appears in the CSS, otherwise the first class in the stylesheet).
     #
     # @param name [String, Symbol] CSS class without a leading dot (e.g. +"input-box"+)
-    def component_class(name = nil)
-      return nil unless component_has_styles? || component_has_stylesheet?
+    # @param from [Class] component class to read scoped CSS classes from
+    def component_class(name = nil, from: self.class)
+      return nil unless from.respond_to?(:component_styles)
+      return nil unless component_has_styles?(from) || component_has_stylesheet?(from)
 
-      self.class.component_styles
+      from.component_styles
 
       if name
-        class_map = self.class.instance_variable_get(:@component_class_map)
+        class_map = from.instance_variable_get(:@component_class_map)
         class_map[name.to_s.delete_prefix(".")]
       else
-        self.class.instance_variable_get(:@component_id)
+        from.instance_variable_get(:@component_id)
       end
     end
 
     private
 
-    def component_has_stylesheet?
-      self.class.has_stylesheet?
+    def component_has_stylesheet?(component_class = self.class)
+      component_class.has_stylesheet?
     end
 
-    def component_has_styles?
-      self.class.instance_variable_defined?(:@styles_block) &&
-        self.class.instance_variable_get(:@styles_block)
+    def component_has_styles?(component_class = self.class)
+      component_class.instance_variable_defined?(:@styles_block) &&
+        component_class.instance_variable_get(:@styles_block)
     end
   end
 end

data/lib/view_component/scoped_styles/configuration.rb

@@ -36,9 +36,20 @@ 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"+).
+      # Prefix prepended to scoped class names.
       #
-      # @return [String] default: +"c-"+
+      # Supports template variables:
+      #
+      # * +{component_name}+ — component name with namespaces joined by +/+,
+      #   and a trailing +Component+ suffix removed
+      # * +{class_name}+ — the CSS class being scoped
+      #
+      # Example: +"{class_name}_"+ with +.component+ → +"component_a1b2c3d4"+.
+      #
+      # To maintain compatibility with versions < 0.5.0 and avoid rewriting
+      # existing stylesheets, set this to +"c-"+.
+      #
+      # @return [String] default: +"{class_name}_"+
       attr_accessor :css_class_prefix
 
       def initialize
@@ -46,7 +57,7 @@ module ViewComponent
         @assets_path = File.join("app", "assets", "stylesheets")
         @stylesheet_name = "components.scoped.css"
         @components_layer = nil
-        @css_class_prefix = "c-"
+        @css_class_prefix = "{class_name}_"
       end
     end
 

data/lib/view_component/scoped_styles/css_class_prefix.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module ScopedStyles
+    # Interpolates +css_class_prefix+ template variables and escapes scoped class
+    # names for use in compiled CSS selectors.
+    class CssClassPrefix
+      VARIABLES = %w[component_name class_name].freeze
+      VARIABLE_PATTERN = /\{(#{VARIABLES.join("|")})\}/
+
+      class << self
+        # Replaces +{component_name}+ and +{class_name}+ in +template+.
+        #
+        # @param template [String] prefix template (e.g. +"{class_name}_"+)
+        # @param component_name [String] component name with namespaces joined by +/+,
+        #   and a trailing +Component+ suffix removed
+        # @param class_name [String] CSS class being scoped
+        # @return [String]
+        def interpolate(template, component_name:, class_name:)
+          template.gsub(VARIABLE_PATTERN) do
+            case ::Regexp.last_match(1)
+            when "component_name" then component_name
+            when "class_name" then class_name
+            end
+          end
+        end
+
+        # Escapes characters that are invalid in unescaped CSS class selectors.
+        #
+        # @param class_name [String]
+        # @return [String]
+        def escape_for_css_selector(class_name)
+          class_name.gsub("/", '\/')
+        end
+      end
+    end
+  end
+end

data/lib/view_component/scoped_styles/railtie.rb

@@ -6,6 +6,10 @@ require "rails/railtie"
 module ViewComponent
   module ScopedStyles
     class Railtie < Rails::Railtie
+      initializer "view_component.scoped_styles.component_generator_hook" do
+        require_relative "component_generator_hook"
+      end
+
       config.after_initialize do
         next unless Rails.env.development?
 

data/lib/view_component/scoped_styles/version.rb

@@ -2,6 +2,6 @@
 
 module ViewComponent
   module ScopedStyles
-    VERSION = "0.4.1"
+    VERSION = "0.6.0"
   end
 end

data/lib/view_component/scoped_styles.rb

@@ -2,7 +2,9 @@
 
 require_relative "scoped_styles/version"
 require_relative "scoped_styles/configuration"
+require_relative "scoped_styles/css_class_prefix"
 require "active_support/concern"
+require "active_support/core_ext/enumerable"
 require_relative "scoped_styles/concern"
 require_relative "scoped_styles/stylist"
 require_relative "scoped_styles/railtie"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_component-scoped_styles
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Chris Edwards
@@ -112,9 +112,13 @@ files:
 - Rakefile
 - lib/generators/view_component/scoped_styles/install_generator.rb
 - lib/generators/view_component/scoped_styles/templates/view_component_scoped_styles.rb.tt
+- lib/generators/view_component/stylesheet/stylesheet_generator.rb
+- lib/generators/view_component/stylesheet/templates/component.css.tt
 - lib/view_component/scoped_styles.rb
+- lib/view_component/scoped_styles/component_generator_hook.rb
 - lib/view_component/scoped_styles/concern.rb
 - lib/view_component/scoped_styles/configuration.rb
+- lib/view_component/scoped_styles/css_class_prefix.rb
 - lib/view_component/scoped_styles/railtie.rb
 - lib/view_component/scoped_styles/stylist.rb
 - lib/view_component/scoped_styles/stylist/writer.rb
@@ -141,7 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Scoped, colocated CSS for ViewComponent components.
 test_files: []