view_component-scoped_styles 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 206f58f9f063b3311d866937c80bcd1a1566621102ebf7135d2aa373f89d32e4
-  data.tar.gz: f0ac0545c6cb63d6dd6739e9e4356ee6b0ba465025e39920345724afa2ce396e
+  metadata.gz: cbe5f5accd78d4f725e75db0267dad949175cbe53ed68bb003dccc4745c294f4
+  data.tar.gz: 2f90b7dd291d0b5b3910a8c4e5e8be1e9c5000d8a69b07315582afac30abd2df
 SHA512:
-  metadata.gz: fae7281bb414c6329bd19c5a58a4c0b23e0ac2eb11f24262ac34e6bbe278b7542de58b186f8838030eb3db9b439b0d618a4db12f4691cbe62ffe6b3daefe25f0
-  data.tar.gz: 0ff154a44d59306b1e9c793656b45696fd91be6715036ee3eebd62c1bb3f8c1fb988130f4877afe72c9630783a70dd8d55cc8b7d2e27f522817746d9e520316c
+  metadata.gz: 89c318654efd8e5dbba628f5aade499754d32588b35fee364c7e91a45bc3fb0ae2001c1e1b3fdd390ede8890f081d060ed221551e513ee021c5639aafc708b4b
+  data.tar.gz: 0d6adc27535b6ab7219935e78964b305cc13fd5b8590a82487b9dbc2d418deaddc15d0d870cd87bf8d1a4d62e96a993437909f4fe807d0a413dda3851a5eb05d

data/README.md

@@ -15,8 +15,9 @@ E.g. `.button` becomes `.button_a1b2c3d4`
     - [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)
+    - [Global classes](#global-classes)
     - [Using the scoped CSS](#using-the-scoped-css)
+    - [Multiple stylesheets](#multiple-stylesheets)
   - [Configuration](#configuration)
   - [Related projects](#related-projects)
   - [Development](#development)
@@ -248,36 +249,76 @@ 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
+### Global classes
 
-Ignored classes are left unchanged in generated CSS:
+Use CSS Modules-style `:global(...)` to leave class selectors unchanged in a sidecar stylesheet or `styles` block:
 
-```ruby
-class ExampleComponent < ViewComponent::Base
-  include ViewComponent::ScopedStyles
+```css
+.component:global(.is-open) {
+  display: block;
+}
 
-  ignored_css_classes "is-open", "active"
+:global(.active) .label {
+  font-weight: bold;
+}
+```
 
-  styles do
-    <<~CSS
-      .component { ... }
-      .is-open { ... }  # stays .is-open in components.scoped.css
-    CSS
-  end
-end
+The compiler removes `:global(...)` and leaves its contents unscoped. In these examples, `.component` and `.label` get scoped names, while `.is-open` and `.active` stay unchanged. Nested selector functions work too:
+
+```css
+.component:has(:global(.external:not(.disabled))) {
+  border-color: green;
+}
+```
+
+Bare `:global` makes the rest of the current selector global. Use `:local(...)` for a local selector within it, or bare `:local` to switch back. Scope resets at each comma, at the end of a selector function, and for each new rule.
+
+```css
+.component :global .external .icon :local(.label) {
+  color: red;
+}
 ```
-In your view, you can either reference the class directly:
+
+For selector lists, write `:global(.first), :global(.second)`. Lists inside a single `:global(...)` are not supported.
+
+Global scope applies to each occurrence. A class can be global in one selector and local in another. `component_class("name")` returns the scoped name when there is a local occurrence, or the original name when every occurrence is global. The root helper uses the configured root class when present, otherwise the first local class, or the first global class if there are no local classes.
+
+In your view, reference a global class directly:
+
 ```erb
 <div class="<%= component_class %> is-open">
 ```
-or via the `component_class` helper:
+
+Or use the helper for a class that appears only in global scope:
+
 ```erb
 <div class="<%= component_class %> <%= component_class("is-open") %>">
 ```
 
+#### Migrating from ignored_css_classes
+
+`ignored_css_classes` is deprecated and emits an ActiveSupport deprecation warning. It continues to leave every occurrence of the listed classes unchanged, including their helper results.
+
+Remove the Ruby declaration and wrap each occurrence of those classes in `:global(...)`:
+
+```ruby
+# Remove this from your component:
+ignored_css_classes "is-open", "active"
+```
+
+```css
+/* Before */
+.component.is-open .active { color: red; }
+
+/* After */
+.component:global(.is-open) :global(.active) { color: red; }
+```
+
+Regenerate the bundled stylesheet after migrating. Scoped names are content-derived, so changing the CSS changes their hashes.
+
 ### Using the scoped CSS
 
-All scoped CSS will be compiled into a single bundled stylesheet. By default that is `app/assets/stylesheets/components.scoped.css`; both the directory and filename are configurable (see [Configuration](#configuration)).
+Scoped CSS is compiled into `app/assets/stylesheets/components.scoped.css` by default. Components can select a different output bundle with `stylesheet`. The default stylesheet is `app/assets/stylesheets/components.scoped.css`; both the directory and filename are configurable (see [Configuration](#configuration)).
 
 You should import this stylesheet within your app:
 
@@ -287,6 +328,38 @@ You should import this stylesheet within your app:
 @import url("./components.scoped.css");
 ```
 
+### Multiple stylesheets
+
+Set `stylesheet` before declaring a `styles` block to choose the component's output bundle. The gem appends `.scoped.css` to the name. This also works with sidecar CSS:
+
+```ruby
+class Admin::ButtonComponent < ViewComponent::Base
+  include ViewComponent::ScopedStyles
+
+  stylesheet "admin"
+
+  styles do
+    ".component { color: blue; }"
+  end
+end
+
+class Admin::CardComponent < ViewComponent::Base
+  include ViewComponent::ScopedStyles
+
+  stylesheet "admin"
+end
+```
+
+Both components compile into `app/assets/stylesheets/admin.scoped.css`. Any number of components can use the same bundle name. Components without a selection use `config.stylesheet_name`. Subclasses inherit their parent's selection and can override it.
+
+All output files use `config.assets_path` and, when configured, `config.components_layer`. Include each bundle where you need it:
+
+```erb
+<%= stylesheet_link_tag "admin.scoped", "data-turbo-track": "reload" %>
+```
+
+Cross-component class references still work across bundles. Load both bundles when both components' styles are needed. When moving an existing component between bundles, remove its marked CSS block from the old generated file, since registration updates the selected file only.
+
 ## Configuration
 
 Run the install generator in your Rails app:

data/lib/view_component/scoped_styles/concern.rb

@@ -7,7 +7,7 @@ module ViewComponent
     extend ActiveSupport::Concern
 
     CACHED_VARIABLES = %i[@component_styles @component_id @component_class_map].freeze
-    CLASS_SELECTOR_PATTERN = /\.([a-zA-Z_][\w-]*)\b/
+    DEPRECATOR = ActiveSupport::Deprecation.new("a future release", "ViewComponent::ScopedStyles")
     COMPONENT_REFERENCE_PATTERN = /
       :component\(
         \s*
@@ -23,6 +23,21 @@ module ViewComponent
     IGNORED_CSS_CLASSES = [].freeze
 
     class_methods do
+      # Selects an output bundle, written as <name>.scoped.css in assets_path.
+      # Subclasses inherit this choice unless they specify their own bundle.
+      def stylesheet(name = nil)
+        if name
+          @scoped_stylesheet = name.to_s
+          register_styles_if_rails_loaded
+        end
+
+        if defined?(@scoped_stylesheet)
+          @scoped_stylesheet
+        elsif superclass.respond_to?(:stylesheet)
+          superclass.stylesheet
+        end
+      end
+
       # Sets which CSS class is the root for +component_class+ (no argument).
       # Also triggers style registration in development when Rails is loaded
       # (registration also runs via the Railtie for all styled components).
@@ -52,7 +67,12 @@ module ViewComponent
       # Clears cached generated styles when the list changes.
       #
       # @param classes [String, Symbol] selector names without a leading dot
+      # @deprecated Wrap selectors in +:global(...)+ in the stylesheet instead.
       def ignored_css_classes(*classes)
+        DEPRECATOR.warn(
+          "ignored_css_classes is deprecated. Use :global(...) in your CSS instead, " \
+          "for example :global(.active)."
+        )
         if classes.any?
           names = classes.flatten.map { |css_class| css_class.to_s.delete_prefix(".") }
           const_set(:IGNORED_CSS_CLASSES, names.freeze)
@@ -134,13 +154,15 @@ module ViewComponent
         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)
+        selectors = CssSelectors.new(styles_content)
+        css_classes = selectors.local_classes
+        primary_class = primary_css_class(css_classes + selectors.global_classes)
 
-        @component_id = component_id_for(primary_class, styles_content)
         @component_class_map = build_component_class_map(styles_content, css_classes, primary_class)
+        selectors.global_classes.each { |name| @component_class_map[name] ||= name }
+        @component_id = @component_class_map[primary_class]
         @component_styles = replace_component_references(
-          replace_css_classes(styles_content, @component_class_map)
+          selectors.render(@component_class_map)
         )
       ensure
         component_resolution_stack.pop if pushed
@@ -150,10 +172,6 @@ module ViewComponent
         @styles_block ? @styles_block.call : File.read(stylesheet_path)
       end
 
-      def extract_css_classes(styles_content)
-        styles_content.scan(CLASS_SELECTOR_PATTERN).flatten.uniq
-      end
-
       def primary_css_class(css_classes)
         configured = self::COMPONENT_CSS_CLASS.delete_prefix(".")
         css_classes.include?(configured) ? configured : css_classes.first
@@ -169,20 +187,6 @@ module ViewComponent
         end
       end
 
-      def replace_css_classes(styles_content, class_map)
-        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|
-          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]
@@ -194,14 +198,6 @@ module ViewComponent
         end
       end
 
-      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
-
       def ignored_css_class?(css_class)
         self::IGNORED_CSS_CLASSES.include?(css_class)
       end
@@ -275,7 +271,8 @@ module ViewComponent
     # Scoped CSS class for a selector (e.g. +"c-99d08d5a"+).
     #
     # With no argument, returns the scoped root class ({COMPONENT_CSS_CLASS} when it
-    # appears in the CSS, otherwise the first class in the stylesheet).
+    # appears in the CSS, otherwise the first local class, or the first global
+    # class when the stylesheet has no local classes).
     #
     # @param name [String, Symbol] CSS class without a leading dot (e.g. +"input-box"+)
     # @param from [Class] component class to read scoped CSS classes from

data/lib/view_component/scoped_styles/css_selectors.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module ViewComponent
+  module ScopedStyles
+    # Records each class occurrence with its scope, preserving non-selector CSS.
+    class CssSelectors
+      COMMENT = %r{/\*.*?\*/}m
+      PROTECTED = %r{/\*.*?\*/|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\\.}m
+      CLASS_SELECTOR = /\.([a-zA-Z_][\w-]*)\b/
+      ClassSelector = Struct.new(:name, :local)
+
+      attr_reader :local_classes, :global_classes
+
+      def initialize(css)
+        @local_classes = []
+        @global_classes = []
+        @parts = parse_stylesheet(css)
+        @local_classes.uniq!
+        @global_classes.uniq!
+      end
+
+      def render(class_map)
+        @parts.map do |part|
+          if part.is_a?(ClassSelector)
+            name = part.local ? class_map.fetch(part.name) : part.name
+            ".#{CssClassPrefix.escape_for_css_selector(name)}"
+          else
+            part
+          end
+        end.join
+      end
+
+      private
+
+      # A rule's prelude ends at an opening brace. Semicolons and closing
+      # braces flush declarations without interpreting them as selectors.
+      def parse_stylesheet(css)
+        scanner = StringScanner.new(css)
+        parts = []
+        prelude = +""
+        depth = 0
+
+        until scanner.eos?
+          if (literal = scanner.scan(PROTECTED))
+            prelude << literal
+            next
+          end
+
+          char = scanner.getch
+          case char
+          when "(", "["
+            depth += 1
+          when ")", "]"
+            depth -= 1
+          end
+
+          if depth.zero? && "{};".include?(char)
+            if char == "{"
+              parts.concat(parse_prelude(prelude))
+            else
+              parts << prelude
+            end
+            parts << char
+            prelude = +""
+          else
+            prelude << char
+          end
+        end
+
+        parts << prelude
+      end
+
+      def parse_prelude(prelude)
+        rule = prelude.gsub(COMMENT, "").lstrip
+        scanner = StringScanner.new(prelude)
+        return parse_selector(scanner) unless rule.start_with?("@") && !rule.match?(/\A@scope\b/)
+        return [prelude] unless rule.match?(/\A@supports\b/)
+
+        parts = []
+        until scanner.eos?
+          if (literal = scanner.scan(PROTECTED))
+            parts << literal
+          elsif scanner.scan(/\bselector\(/)
+            parts << "selector("
+            parts.concat(parse_selector(scanner, closing: ")"))
+            parts << ")"
+          else
+            parts << scanner.getch
+          end
+        end
+        parts
+      end
+
+      def parse_selector(scanner, local: true, closing: nil, scope_function: false)
+        parts = []
+        initial_scope = local
+
+        until scanner.eos?
+          if closing && scanner.scan(/#{Regexp.escape(closing)}/)
+            return parts
+          elsif (literal = scanner.scan(PROTECTED))
+            parts << literal
+          elsif scanner.scan(/\[/)
+            parts << "[" << read_attribute(scanner)
+          elsif scanner.scan(/:(global|local)\(/)
+            scope = scanner[1] == "local"
+            parts.concat(parse_selector(scanner, local: scope, closing: ")", scope_function: true))
+          elsif scanner.scan(/:(global|local)(?=\s)/)
+            local = scanner[1] == "local"
+            scanner.scan(/\s+/)
+          elsif scanner.scan(CLASS_SELECTOR)
+            name = scanner[1]
+            (local ? @local_classes : @global_classes) << name
+            parts << ClassSelector.new(name, local)
+          elsif scanner.scan(/\(/)
+            parts << "("
+            parts.concat(parse_selector(scanner, local: local, closing: ")"))
+            parts << ")"
+          elsif scanner.scan(/,/)
+            raise ArgumentError, "Use a separate :global(...) or :local(...) for each selector" if scope_function
+
+            local = initial_scope
+            parts << ","
+          else
+            parts << scanner.getch
+          end
+        end
+
+        raise ArgumentError, "Unclosed selector function in scoped CSS" if closing
+
+        parts
+      end
+
+      def read_attribute(scanner)
+        value = +""
+        until scanner.eos?
+          if (literal = scanner.scan(PROTECTED))
+            value << literal
+          else
+            char = scanner.getch
+            value << char
+            break if char == "]"
+          end
+        end
+        value
+      end
+    end
+  end
+end

data/lib/view_component/scoped_styles/stylist/writer.rb

@@ -9,6 +9,9 @@ module ViewComponent
         end
 
         def print!(component_class)
+          bundle = component_class.stylesheet
+          filename = bundle ? "#{bundle}.scoped.css" : config.stylesheet_name
+          @stylesheet_path = Rails.root.join(config.assets_path, filename)
           component_name = component_class.name
           component_class.instance_variable_get(:@component_id)
           styles = component_class.component_styles
@@ -29,6 +32,7 @@ module ViewComponent
 
         def update_stylesheet_with(component_name, styles)
           content = File.read(stylesheet_path)
+          content = content.sub(/\n\}\s*\z/, "\n") if config.components_layer
           updated_content = merge_styles_into(content, component_name, styles)
 
           write_atomically(updated_content)
@@ -91,11 +95,7 @@ module ViewComponent
           content
         end
 
-        def stylesheet_path
-          @stylesheet_path ||= begin
-            Rails.root.join(config.assets_path, config.stylesheet_name)
-          end
-        end
+        attr_reader :stylesheet_path
 
         def config
           @config ||= ViewComponent::ScopedStyles.configuration

data/lib/view_component/scoped_styles/version.rb

@@ -2,6 +2,6 @@
 
 module ViewComponent
   module ScopedStyles
-    VERSION = "0.6.1"
+    VERSION = "0.8.0"
   end
 end

data/lib/view_component/scoped_styles.rb

@@ -3,7 +3,9 @@
 require_relative "scoped_styles/version"
 require_relative "scoped_styles/configuration"
 require_relative "scoped_styles/css_class_prefix"
+require_relative "scoped_styles/css_selectors"
 require "active_support/concern"
+require "active_support/deprecation"
 require "active_support/core_ext/enumerable"
 require_relative "scoped_styles/concern"
 require_relative "scoped_styles/stylist"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: view_component-scoped_styles
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Chris Edwards
@@ -119,6 +119,7 @@ files:
 - 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/css_selectors.rb
 - lib/view_component/scoped_styles/railtie.rb
 - lib/view_component/scoped_styles/stylist.rb
 - lib/view_component/scoped_styles/stylist/writer.rb