tailwind-sorter 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee5b0b99b5a652053bd30aa564181ff1d80e620ee224d2bafcf494bd55d6c891
-  data.tar.gz: 827baa288658e2d5ff141fad55b4325ac8ae8b176feb8ce5fd7de5b68793b4b0
+  metadata.gz: 82b25d2e48c760db25e242cafa14a986831e6ccaff1498ea7fbf638dc22392d9
+  data.tar.gz: dc94b034b7e7922bafc9f618a7db6f839d102eb2c38f916689f538fcfab07d2c
 SHA512:
-  metadata.gz: b98372d3ead957a4dd5da63259868f8557d96a31200e92ae3f0a0c2ad862e9f00f57d4be784df5f649bbedb03cc493ff3394a44321a37272e26627c13a1a0773
-  data.tar.gz: f867b88d892c3412547d8c24eaa6b819f1735c828c15f950e01cd4ede39526b2a6b42b39b54d1c7af3953414af13b2022a4b4881dca7fba5d4cffde6b542c687
+  metadata.gz: 95a45a46c6a5911db7bd2e48fde99b7a752f2de25bc5832b009c0fe5d840912474be6047caf2f7ecb3d2325e894c466bab4ff9f32f71fe88506448ff204bb74c
+  data.tar.gz: 98a11cdfd1bebff6fd7a8a24069326dc26776dffdcb4b37f8271374793c04133823ebd2c3375c5a6192cec5f5f68ac0b61e9322be9757658b102d32898f02358

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+### 0.4.0
+
+- Add support for regular expressions in configuration for class ordering (#3)
+
+  So instead of having to specify all variants of a certain Tailwind class, now you can cover all of them with a
+  regular expression.
+- Cache sorting keys during processing (speeds up sorting a file with repeating CSS classes).
+- Fix LOAD_PATH issues when running tests (#2).
+- Add Github Action for tests, enhance tests.
+- Require ruby 3.1+.
+
+### 0.3.1
+
+Return warnings when called from ruby code in warn_only mode.
+
+### 0.3.0
+
+First public release of the gemified version of Tailwind sorter.
+
+### 0.0.0 - the original script
+
+The repository with the bare-bones sorter script can be found here: https://github.com/NejRemeslnici/tailwind-sorter/tree/original-script

data/README.md

@@ -12,8 +12,11 @@ The gem contains a standalone executable script that can work in two ways:
 Out of the box the script supports sorting classes in [Slim templates](http://slim-lang.com/) but can be configured for
 anything else. The script also removes duplicate classes.
 
-_This is what it looks like when Tailwind sorter is auto-run upon saving a changed template file in the RubyMine IDE:_
-<img src="img/tailwind_sorter_intro.gif" alt="Automatically ordering CSS classes upon file saving"></img>
+_This is what it looks like when Tailwind sorter is auto-run upon saving a changed template file in VS Code:_
+<img src="img/tailwind_sorter_vscode.gif" alt="Automatically ordering CSS classes upon file saving in VS Code"></img>
+
+_And similarly in RubyMine IDE:_
+<img src="img/tailwind_sorter_rubymine.gif" alt="Automatically ordering CSS classes upon file saving in RubyMine"></img>
 
 Please read the [accompanying post on dev.to](https://dev.to/nejremeslnici/tailwind-css-class-sorter-the-custom-way-35g5) for more details, if interested.
 
@@ -37,12 +40,11 @@ solution. This problem is even larger if you’ve added
 [custom utility classes](https://tailwindcss.com/docs/adding-new-utilities) to your project.
 
 Above all, it is **surprisingly easy** to create a custom sorting script – the one we use and present here is only
-~110 lines. So, take this script and config as a **template for you to revise and adapt**.
+~150 lines. So, take this script and especially its config as a **template for you to revise and adapt**.
 
 ## Installation
 
-Since version 0.3, the script has been packed into a gem so that it can be used directly from ruby as well as a standalone script (now a binstub). If you just want to grab the original ruby script, have a look at the [`original-script` tag](https://github.com/NejRemeslnici/tailwind-sorter/tree/original-script).
-
+Since version 0.3, the script has been packed into a gem so that it can be used directly from ruby as well as a standalone script (now a binstub).
 
 ### Installing the gem
 
@@ -69,7 +71,7 @@ $ bundle binstubs tailwind-sorter
 
 This will create a `bin/tailwind_sorter` binstub file.
 
-The gem has **no dependencies**, apart from ruby (tested on ruby 3.0+) and its stdlib.
+The gem has **no dependencies**, apart from ruby (tested on ruby 3.1+) and its stdlib.
 
 ## Configuration
 
@@ -78,28 +80,61 @@ configured.
 
 There are two important places to configure in the YAML file:
 
-- **regular expressions** to match the classes in your files: out of the box, the script matches classes in the Slim
-  format (such as `section#flash-messages.hidden.mt-4`) and classes in the context of the `class` attribute in ruby /
-  Rails helpers (`link_to "E-shop", eshop_path, class: "no-underline font-bold red-100")`,
+- **regular expressions** that tell the Tailwind sorter where to find CSS classes to sort: out of the box, the script
+  matches classes in the Slim format (such as `section#flash-messages.hidden.mt-4`) and classes in the context of the
+  `class` attribute in ruby / Rails helpers (`link_to "E-shop", eshop_path, class: "no-underline font-bold red-100")`,
 
 - **CSS classes order and grouping**: the `classes_order` section in the YAML file determines the order in which the
   classes will be sorted. If you want the classes with Tailwind variants (such as `sm:`, `hover:` etc.) to always be
   ordered towards the end of line, put the classes in one big group, otherwise split them into any groups you want and
   they will be ordered last in the particular group.
 
-Unknown (i.e. custom) classes will be **ordered first by default**. If you want them ordered last, you'll have to resort to using the original script and replacing the [`default_index`](https://github.com/NejRemeslnici/tailwind-sorter/blob/original-script/bin/tailwind_sorter.rb#L20) parameter in it with a big-enough number. We recommend ordering custom classes first though as in our opinion such classes usually bear more important meanings than the Tailwind ones and this setup also makes it easier to spot typos in class names.
+  You have two options when specifying classes in this config section: pure strings and regular expressions:
+
+  -  You can always just **list the CSS class names** in the config. This style gives you a full control over the ordering and it is the fastest option as well. The downside of it is that you'll find yourself having to update the config more often as new Tailwind classes variants emerge in your project and / or Tailwind itself:
+
+      ```yaml
+      classes_order:
+        spacing:
+          ...
+          - py-2
+          - py-4
+          - py-8
+          ...
+      ```
+
+  - Or, you can use **regular expressions** to cover all variants of a Tailwind class at once. A regular expression in
+    this part of the config is specified as a string delimited by slashes. Note that the
+    [`\A` and `\z` boundaries](https://docs.ruby-lang.org/en/master/Regexp.html#class-Regexp-label-Boundary+Anchors) are
+    automatically added to the expression so that it always matches the whole class name, not just part of it. Using regular expressions to sort classes shortens your configuration greatly but makes it a bit harder to understand.
+
+    ```yaml
+    classes_order:
+      spacing:
+        ...
+        - /py-\d+/
+        ...
+    ```
+
+  - And, of course, you can also freely mix these two approaches.
+
+Unknown (e.g. your custom) classes will be **ordered first**. If you want to sort them differently, you will have to add them
+to the config file to their proper place under `classes_order`. We recommend ordering custom classes first though as in
+our opinion such classes usually bear more important meanings than the Tailwind ones and this setup also makes it easier
+to spot typos in class names.
 
-The default sort order of the classes resembles the one of Headwind which, in turn, seems to be inspired by the order of
-the sections in the [official Tailwind documentation](https://tailwindcss.com/docs).
+The default sort order of the classes in the bundled config file resembles the one of Headwind which, in turn, seems to
+be inspired by the order of the sections in the [official Tailwind documentation](https://tailwindcss.com/docs).
 
-More details about the configuration file can be found in [the wiki](https://github.com/NejRemeslnici/tailwind-sorter/wiki/The-config-file-explanation).
+More details about the configuration file can be found in
+[the wiki](https://github.com/NejRemeslnici/tailwind-sorter/wiki/The-config-file-explanation).
 
 ### Adding your unique set of Tailwind classes
 
 The script works best if you only include the classes that you really use in your project. Once you grab all the classes
-e.g. from your [purged](https://tailwindcss.com/docs/optimizing-for-production) / [JIT-ed](https://tailwindcss.com/docs/just-in-time-mode) production CSS bundle, you can initially reorder them using the following ruby snippet. Suppose you
+e.g. from your [JIT-ed](https://tailwindcss.com/docs/just-in-time-mode) production CSS bundle, you can initially reorder them using the following ruby snippet. Suppose you
 have the ”default“ Tailwind classes sorted (taken e.g. from
-[here](https://github.com/avencera/rustywind/blob/master/src/defaults.rs)), one per line, in
+[here](https://github.com/avencera/rustywind/blob/master/rustywind-core/src/defaults.rs), one per line, in
 the `default_classes.txt` file and your own (unordered) classes in `our_classes.txt`. Then the sorting could go along these lines:
 
 ```ruby
@@ -114,7 +149,7 @@ the `sorted_classes.txt` file) and move all of them to the appropriate sections
 
 ## Running the script
 
-Of course, you can run the script manually, like so:
+You can run the script manually like so:
 
 ```sh
 bin/tailwind_sorter app/views/my_template.html.slim
@@ -122,7 +157,7 @@ bin/tailwind_sorter app/views/my_template.html.slim
 
 The script finds all css classes and reorders them in-place in the file.
 
-You can tweak the configuration file path instead of the default `config/tailwind_sorter.yml` with the `-c` parameter:
+The script requires the configuration file to be present in `config/tailwind_sorter.yml` by default. You can tweak the configuration file path with the `-c` parameter:
 
 ```sh
 bin/tailwind_sorter -c path/to/my/config_file.yml app/views/my_template.html.slim
@@ -161,10 +196,10 @@ You can also optionally pass in ome arguments such as `warn_only: true` to only
 ```sh
 bundle install # to install the rspec gem
 bundle exec rspec
-.............
+.................
 
-Finished in 0.34583 seconds (files took 0.07635 seconds to load)
-13 examples, 0 failures
+Finished in 1.08 seconds (files took 0.03424 seconds to load)
+17 examples, 0 failures
 ```
 
 ## Answers for the curious

data/exe/tailwind_sorter

@@ -1,6 +1,9 @@
 #!/usr/bin/env ruby
 
-require "tailwind_sorter/sorter"
+lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require "tailwind_sorter"
 
 warn_only = false
 config_file = "config/tailwind_sorter.yml"

data/lib/tailwind_sorter/sorter.rb

@@ -3,6 +3,10 @@ require "yaml"
 
 module TailwindSorter
   class Sorter
+    def initialize
+      @sorting_keys_cache = {}
+    end
+
     # reorders multiple variants, e.g.: "focus:sm:block" -> "sm:focus:block"
     def sort_variants(css_class_with_variants, variants_order:)
       *variants, css_class = css_class_with_variants.split(":")
@@ -15,31 +19,54 @@ module TailwindSorter
     # Constructs the sorting key for sorting CSS classes in the following way:
     #
     # group_index, variant1_index, variant2_index, class_index
-    # "sm:focus:flex"   "01,01,11,0010"
-    # "flex"            "01,00,00,0010"
-    # "nr-custom-class" "00,00,00,0000"
-    def sorting_key(css_class_with_variants, variants_order:, classes_order:, class_groups:, sort_order:, default_index: 0)
+    # "sm:focus:flex" -> "01,01,11,0010"
+    # "flex"          -> "01,00,00,0010"
+    # "custom-class"  -> "00,00,00,0000"
+    def sorting_key(css_class_with_variants, variants_order:, classes_order:, class_groups:, default_index: 0)
+      return @sorting_keys_cache[css_class_with_variants] if @sorting_keys_cache[css_class_with_variants]
+
       *variants, css_class = css_class_with_variants.split(":")
+
+      matching_index_in_group = nil
+      matching_group = class_groups.find do |group|
+        matching_index_in_group ||= classes_order[group].index { _1 === css_class }
+      end
+
       key = [
-        format("%02d", class_groups.index { |group| classes_order[group].include?(css_class) } || default_index),
+        format("%02d", matching_group && class_groups.index(matching_group) || default_index),
         format("%02d", variants_order.index(variants[0]) || default_index),
         format("%02d", variants_order.index(variants[1]) || default_index),
-        format("%04d", sort_order.index(css_class) || default_index)
+        format("%04d", matching_index_in_group || default_index)
       ].join(",")
 
       # puts "#{css_class_with_variants} #{key}"
-      key
+      @sorting_keys_cache[css_class_with_variants] = key
+    end
+
+    def convert_regexps!(classes_order)
+      classes_order.each do |group, class_patterns|
+        class_patterns.map! do |class_or_pattern|
+          if !(patterns = class_or_pattern.match(%r{\A/(.*)/\z}).to_a).empty?
+            Regexp.new(/\A#{patterns.last}\z/)
+          else
+            class_or_pattern
+          end
+        end
+      end
+
+      classes_order
     end
 
     def sort_classes(file, regexps:, variants_order:, classes_order:, default_index: 0, warn_only: false)
+      convert_regexps!(classes_order)
       class_groups = classes_order.keys
-      sort_order = classes_order.values.flatten
+      warnings = []
 
       infile = File.open(file)
       outfile = Tempfile.create("#{File.basename(file)}.sorted")
 
       calculate_sorting_key = lambda do |css_class_with_variants|
-        sorting_key(css_class_with_variants, variants_order:, classes_order:, class_groups:, sort_order:, default_index:)
+        sorting_key(css_class_with_variants, variants_order:, classes_order:, class_groups:, default_index:)
       end
 
       changed = false
@@ -69,7 +96,9 @@ module TailwindSorter
             # puts orig_keys.inspect
             # puts sorted_keys.inspect
             if orig_keys != sorted_keys
-              puts("#{file}:#{line_number}:CSS classes are not sorted well. Please run 'tailwind_sorter #{file}'.")
+              warning = "#{file}:#{line_number}:CSS classes are not sorted well. Please run 'tailwind_sorter #{file}'."
+              warnings << warning
+              puts(warning)
             end
           else
             orig_line = line.dup unless changed
@@ -83,7 +112,10 @@ module TailwindSorter
 
       success = true
 
-    rescue StandardError
+      warnings
+
+    rescue StandardError => e
+      warn "An error occurred: #{e}"
       success = false
 
     ensure
@@ -113,4 +145,4 @@ module TailwindSorter
       new.run(...)
     end
   end
-end
+end

data/lib/tailwind_sorter/version.rb

@@ -1,3 +1,3 @@
 module TailwindSorter
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/tailwind_sorter.rb

@@ -2,4 +2,4 @@ require "tailwind_sorter/sorter"
 require "tailwind_sorter/version"
 
 module TailwindSorter
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tailwind-sorter
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - NejŘemeslníci.cz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-17 00:00:00.000000000 Z
+date: 2024-08-04 00:00:00.000000000 Z
 dependencies: []
 description: Simple but customizable sorter for TailwindCSS classes
 email:
@@ -18,6 +18,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - Rakefile
 - exe/tailwind_sorter
@@ -39,14 +40,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Customizable TailwindCSS classes sorter