tailwind-sorter 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee5b0b99b5a652053bd30aa564181ff1d80e620ee224d2bafcf494bd55d6c891
+  data.tar.gz: 827baa288658e2d5ff141fad55b4325ac8ae8b176feb8ce5fd7de5b68793b4b0
+SHA512:
+  metadata.gz: b98372d3ead957a4dd5da63259868f8557d96a31200e92ae3f0a0c2ad862e9f00f57d4be784df5f649bbedb03cc493ff3394a44321a37272e26627c13a1a0773
+  data.tar.gz: f867b88d892c3412547d8c24eaa6b819f1735c828c15f950e01cd4ede39526b2a6b42b39b54d1c7af3953414af13b2022a4b4881dca7fba5d4cffde6b542c687

data/README.md

@@ -0,0 +1,176 @@
+# Tailwind sorter
+
+**A ruby gem to sort the [Tailwind CSS](https://tailwindcss.com) classes in your templates _the custom way_.**
+
+The gem contains a standalone executable script that can work in two ways:
+
+- it can edit the given file in place (especially useful when hooked up to a file changes watcher) or
+- it can just generate warning messages suitable for [Overcommit](https://github.com/sds/overcommit),
+  [Lefthook](https://github.com/evilmartians/lefthook) or any other similar system (or people, if that’s what you
+  prefer).
+
+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>
+
+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.
+
+## Why?
+
+We are aware of the other good solutions to sorting Tailwind classes but we’ve hit some limit in each of them:
+
+- [The official Tailwind Prettier plugin](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) is great but does
+  not support all template formats, such as [Slim](http://slim-lang.com/).
+- [Headwind](https://github.com/heybourn/headwind) is VS Code-only but we needed something in RubyMine and Overcommit,
+  too.
+- There are ports to the environments we need
+  ([Tailwind Formatter](https://plugins.jetbrains.com/plugin/13376-tailwind-formatter/) JetBrains plugin,
+  [RustyWind](https://github.com/avencera/rustywind) CLI tool) but none of these support non-standard template formats.
+  Also, we like to sort our Tailwind classes a bit differently than Headwind et al. default to.
+
+In our opinion, especially since the [JIT mode](https://tailwindcss.com/docs/just-in-time-mode) has been introduced to
+Tailwind, sorters operating over a huge static list of "default" pre-ordered classes are becoming less useful as each
+developer will inevitably come to their **own unique set of classes** making it almost impossible to hard-wire a common
+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**.
+
+## 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).
+
+
+### Installing the gem
+
+Install it directly:
+
+```
+gem install tailwind-sorter
+```
+
+or put it in your gemfile
+
+```
+# Gemfile
+group :development do
+  gem "tailwind-sorter"
+end
+```
+
+Create a binstub, i.e. a standalone executable script for the sorter:
+
+```sh
+$ 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.
+
+## Configuration
+
+Without customizing, the script will – somehow – work but its full potential will be available only when properly
+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")`,
+
+- **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.
+
+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).
+
+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
+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
+the `default_classes.txt` file and your own (unordered) classes in `our_classes.txt`. Then the sorting could go along these lines:
+
+```ruby
+head = File.readlines("default_classes.txt").map(&:strip)
+our = File.readlines("our_classes.txt").map(&:strip)
+sorted_classes = our.sort_by { |css_class| head.index(css_class) || 10_000 }
+File.open("sorted_classes.txt", "w") { |f| f.write(sorted_classes.join("\n")) }
+```
+
+Then, you can grab these sorted classes, update the position of your own custom classes (you’ll find them near the end of
+the `sorted_classes.txt` file) and move all of them to the appropriate sections of the YAML config file.
+
+## Running the script
+
+Of course, you can run the script manually, like so:
+
+```sh
+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:
+
+```sh
+bin/tailwind_sorter -c path/to/my/config_file.yml app/views/my_template.html.slim
+```
+
+## Running automatically via your IDE / editor
+
+Perhaps the best way to run the script is using your editor or IDE. Many editors provide the possibility to watch your
+edited files and **run arbitrary command when they are changed / saved**.
+
+We use Tailwind sorter this way, the script is triggered by ”file watchers“ configured in RubyMine and it works great.
+Have a look at [the wiki](https://github.com/NejRemeslnici/tailwind-sorter/wiki) for a guide to set up such integration.
+
+## Guarding sort order via Overcommit
+
+We use [Overcommit](https://github.com/sds/overcommit) to guard a common set of rules configured in our project during
+each commit. Here, we provide
+a [simple pre-commit hook](https://github.com/NejRemeslnici/tailwind-sorter/blob/main/.git-hooks/pre_commit/check_css_classes_order.rb)
+and a sample
+[configuration in the `.overcommit.yml` file](https://github.com/NejRemeslnici/tailwind-sorter/blob/main/.overcommit.yml#L31)
+. The hook calls Tailwind sorter with the `-w` argument, asking it to not change the file but only print the ordering
+problems found.
+
+## Running the sorter from ruby code
+
+To run the sorter from ruby code, use the following line:
+
+```ruby
+TailwindSorter::Sorter.run("app/views/my_template.html.slim")
+```
+
+You can also optionally pass in ome arguments such as `warn_only: true` to only show  warning instead of overwriting the file or `config_file: "path/to/my/config_file.yml"` for custom config path.
+
+## Running tests
+
+```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
+```
+
+## Answers for the curious
+
+### But I heard ruby is slow. Is this fast enough?
+
+When we initially reordered CSS classes in all our templates (~900 Slim files) with the script changing nearly 4000
+lines, the whole process took less than 30 seconds. This makes the processing speed of approximately 30 files per
+second. Judge for yourself if this is fast enough for your needs or not.

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/exe/tailwind_sorter

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require "tailwind_sorter/sorter"
+
+warn_only = false
+config_file = "config/tailwind_sorter.yml"
+
+while (arg = ARGV.shift)
+  case arg
+  when "-w"
+    warn_only = true
+  when "-c"
+    config_file = ARGV.shift
+  else
+    file_name = arg
+  end
+end
+
+begin
+  TailwindSorter::Sorter.run(file_name, warn_only: warn_only, config_file: config_file)
+rescue ArgumentError => e
+  STDERR.puts e.message
+  exit 1
+end

data/lib/tailwind_sorter/sorter.rb

@@ -0,0 +1,116 @@
+require "tempfile"
+require "yaml"
+
+module TailwindSorter
+  class Sorter
+    # 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(":")
+      return css_class_with_variants if variants.length <= 1
+
+      variants.sort_by! { |variant| variants_order.index(variant) }
+      "#{variants.join(':')}:#{css_class}"
+    end
+
+    # 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)
+      *variants, css_class = css_class_with_variants.split(":")
+      key = [
+        format("%02d", class_groups.index { |group| classes_order[group].include?(css_class) } || 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)
+      ].join(",")
+
+      # puts "#{css_class_with_variants} #{key}"
+      key
+    end
+
+    def sort_classes(file, regexps:, variants_order:, classes_order:, default_index: 0, warn_only: false)
+      class_groups = classes_order.keys
+      sort_order = classes_order.values.flatten
+
+      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:)
+      end
+
+      changed = false
+      infile.each_line do |line|
+        line_number = infile.lineno
+
+        regexps.each do |_regexp_name, regexp_config|
+          regexp = regexp_config["regexp"]
+          prefix = regexp_config["class_prefix"]
+          split_by = "#{regexp_config['class_splitter']}#{prefix}"
+
+          next unless (match = line.match(regexp))
+
+          matched_classes = match["classes"]
+          # puts "#{line_number}: #{matched_classes}"
+
+          classes = matched_classes.split(split_by).map(&:strip).reject(&:empty?).uniq.map do |css_class_with_variants|
+            sort_variants(css_class_with_variants, variants_order: variants_order)
+          end
+
+          sorted_classes = classes.sort_by { |css_class| calculate_sorting_key.call(css_class) }
+          # puts sorted_classes.join('.')
+
+          if warn_only
+            orig_keys = classes.map { |css_class| calculate_sorting_key.call(css_class) }
+            sorted_keys = sorted_classes.map { |css_class| calculate_sorting_key.call(css_class) }
+            # 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}'.")
+            end
+          else
+            orig_line = line.dup unless changed
+            line.sub!(regexp, "\\k<before>#{prefix}#{sorted_classes.join(split_by)}")
+            changed = true if !changed && line != orig_line
+          end
+        end
+
+        outfile.puts line
+      end
+
+      success = true
+
+    rescue StandardError
+      success = false
+
+    ensure
+      infile.close
+      outfile.close
+
+      success && changed ? FileUtils.mv(outfile, file) : File.unlink(outfile)
+    end
+
+    def run(file_name, warn_only: false, config_file: "config/tailwind_sorter.yml")
+      raise ArgumentError, "File '#{file_name}' does not exist" unless file_name && File.exist?(file_name)
+      raise ArgumentError, "Configuration file '#{config_file}' does not exist" unless config_file && File.exist?(config_file)
+
+      config = YAML.load_file(config_file)
+      file_extension = File.extname(file_name)
+
+      regexps = config["regexps"].select { |_k, v| v["file_extension"] == file_extension }
+      regexps.each { |_k, v| v["regexp"] = Regexp.new(v["regexp"]) }
+
+      sort_classes(file_name, regexps:,
+                              classes_order: config["classes_order"],
+                              variants_order: config["variants_order"],
+                              warn_only:)
+    end
+
+    def self.run(...)
+      new.run(...)
+    end
+  end
+end

data/lib/tailwind_sorter/version.rb

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

data/lib/tailwind_sorter.rb

@@ -0,0 +1,5 @@
+require "tailwind_sorter/sorter"
+require "tailwind_sorter/version"
+
+module TailwindSorter
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: tailwind-sorter
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- NejŘemeslníci.cz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-10-17 00:00:00.000000000 Z
+dependencies: []
+description: Simple but customizable sorter for TailwindCSS classes
+email:
+- support@nejremeslnici.cz
+executables:
+- tailwind_sorter
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- exe/tailwind_sorter
+- lib/tailwind_sorter.rb
+- lib/tailwind_sorter/sorter.rb
+- lib/tailwind_sorter/version.rb
+homepage: https://github.com/NejRemeslnici/tailwind-sorter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/NejRemeslnici/tailwind-sorter
+  source_code_uri: https://github.com/NejRemeslnici/tailwind-sorter
+  changelog_uri: https://github.com/NejRemeslnici/tailwind-sorter
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Customizable TailwindCSS classes sorter
+test_files: []