view_component-scoped_styles 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 206f58f9f063b3311d866937c80bcd1a1566621102ebf7135d2aa373f89d32e4
-  data.tar.gz: f0ac0545c6cb63d6dd6739e9e4356ee6b0ba465025e39920345724afa2ce396e
+  metadata.gz: 76cfb539bacc159bd6913d32e02fd65f4bdf694e94956fdb9187b68b951badbe
+  data.tar.gz: 6cd273fa833779ed196785c3318ffb79c3c55929c9637aa067d6d2e97a1bbb14
 SHA512:
-  metadata.gz: fae7281bb414c6329bd19c5a58a4c0b23e0ac2eb11f24262ac34e6bbe278b7542de58b186f8838030eb3db9b439b0d618a4db12f4691cbe62ffe6b3daefe25f0
-  data.tar.gz: 0ff154a44d59306b1e9c793656b45696fd91be6715036ee3eebd62c1bb3f8c1fb988130f4877afe72c9630783a70dd8d55cc8b7d2e27f522817746d9e520316c
+  metadata.gz: b7ebb5bd1bbba3ad26b14119f80d54623a0aae174956c178600c130106d23517053ab232b91ba4f516cebca07fb7c08581a34ad4cab83a6cce00c611957110a3
+  data.tar.gz: 0caa033226552ccf3ea15d7a6d8af1240449d37a68d1c18f2cb549882c46ee42145cf0f41434e28af4fe68fe242337c3f4b75af27ee93a917412f337e1c32a98

data/README.md

@@ -15,7 +15,7 @@ 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)
   - [Configuration](#configuration)
   - [Related projects](#related-projects)
@@ -248,33 +248,73 @@ 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)).

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*
@@ -52,7 +52,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 +139,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 +157,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 +172,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 +183,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 +256,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/version.rb

@@ -2,6 +2,6 @@
 
 module ViewComponent
   module ScopedStyles
-    VERSION = "0.6.1"
+    VERSION = "0.7.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.7.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