classy-yaml 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b91dad78932d510d2299faae67a08584bad33501c3a048435603a6e673049090
-  data.tar.gz: c3d9d4e2c543e3f3b70b94260f2293d5d3f6a24474e228690aa5c97f5a80666f
+  metadata.gz: 352e03027c4cfd4154d22f4d26aa5cc0faa040a9815476505a3167487adcd0ab
+  data.tar.gz: 5f80b9e47137978a7d252f6ff8a83a6d43cbaa658d424af5c8bab962b8c1fc56
 SHA512:
-  metadata.gz: 1bc0b46c0d2f9fb2a49eedada6e497c7aebf14bc6f95f75609461620f44d5df12066dd8437fe8be90240053670dad19bf6cf1a80a1d8a3f08f0a54ea8e1ce6ad
-  data.tar.gz: bcf8f2d58c819e91a935076eb920094e27b2855e30d13038fd26ad3942447d1c5c14f646427e18d3787a6c39774da89bc63443995cf0373935eceb28db0186b4
+  metadata.gz: 243dca26cd467edbbc0d1df13fbdd297491015779cdab12f8c339bec63186cb234957a88d9b00e341fd83b6f96994a4f9761716d9b9aaf25992020bc561a1aef
+  data.tar.gz: b2e9b69ae589341503b21ce6f57b999029ebebaf77ef5b794c9759a93a37efdf5d7a98fd416d76dd6a3b4e41511c37d453994134d01e3794d9c40b2edc7dd270

data/README.md

@@ -1,72 +1,119 @@
 # Classy::Yaml
-This was created to provide convenient utility class grouping for environments without a bundler (or any situation where you might not want to add custom css classes). YAML files are a perfect structure for these situations.
+This was created to provide convenient utility class grouping for environments without a bundler (or any situation where you might not want to add custom css classes). 
 
 ## Usage
 After installing the gem, the helper method `yass` will be available from anywhere. It looks for the definitions in the YAML file `config/utility_classes.yml` (note: you must add this yourself).
 
-The YAML structure should follow this format:
+## Installation
+
+Add this line to your application's Gemfile:
 
+```ruby
+gem "classy-yaml"
 ```
-btn:
-  blue: "text-blue-200 bg-blue-500"
-  yellow: "text-yellow-200 bg-blue-500"
+
+And then execute:
+```bash
+$ bundle install
 ```
 
-Then, you can add these classes to any element by calling `yass(btn: :blue)` or `yass(btn: :yellow)`.
+Or install it yourself as:
+```bash
+$ gem install classy-yaml
+```
 
-You may wonder though, what about shared classes you want all nested definitions to inherit? There is a special syntax for this type of inheritance:
+## Usage
 
+### Default Settings
+
+You can override any of the following settings in an initializer such as `config/initializers/classy_yaml.rb`:
+
+```ruby
+Classy::Yaml.setup do |config|
+  config.default_file = "config/utility_classes.yml"
+  config.extra_files = []
+  config.override_tag_helpers = false  # Process all ERB tag helper class: attribute through `yass` when it is a non-string
+end
 ```
-btn:
-  base: "px-3 py-2"
-  blue: "text-blue-200 bg-blue-500"
-  yellow: "text-yellow-200 bg-blue-500"
-```
 
-Now, calling `yass(btn: :blue)` or `yass(btn: :yellow)` will ALSO pull in the classes from `btn: :base`.
+### YAML Configuration
+
+Create your utility classes YAML file (`config/utility_classes.yml`):
 
-### Optionally Skipping Base
+```yaml
+btn:
+  base: "px-4 py-2 rounded font-medium" # Base class is automatically applied when referencing a sibling of base
+  primary: "bg-blue-500 text-white hover:bg-blue-600"
+  secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300"
+  danger: "bg-red-500 text-white hover:bg-red-600"
 
-You can optionally skip including the base on a `yass` call by including the key/value `skip_base: true`. So, using the example above,
-we can perform:
+card:
+  compact: "m-4"
 ```
+
+You can also define classes as YAML arrays
+
+```yaml
 btn:
-  base: "px-3 py-2"
-  blue: "text-blue-200 bg-blue-500"
-  yellow: "text-yellow-200 bg-blue-500"
+  base: "px-4 py-2 rounded font-medium" # Base class is automatically applied when referencing a sibling of base
+  primary: "bg-blue-500 text-white hover:bg-blue-600"
+  secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300"
+  danger: "bg-red-500 text-white hover:bg-red-600"
+  warning: # Hideous example
+    - "bg-yellow-200"
+    - "text-gray-100"
 ```
 
-Now, calling `yass(btn: :blue, skip_base: true)` and this will skip pulling in the classes from `btn: :base`. This is helpful
-when defining animation classes and you only want to include the different classes, such as `active` and `inactive` for instance.
+> [!WARNING]
+> If using tailwind, be sure to point the tailwind configuration to your yaml files for parsing 
 
-### ViewComponent
-There is a special helper built for ViewComponent and sidecar assets. In your `example_component.rb`, add the line `include Classy::Yaml::ComponentHelpers`. This helper will tell `yass` to check if there is a `example_component.yml` file, and first use that for definitions. If the definitions aren't found in the `example_component.yml`, then it will fallback to `config/utility_classes.yml`.
+### Using the Helper
 
-So, it may look like this
+In your views or components:
 
-```
-# config/utility_classes.yml
-btn:
-  base: "px-3 py-2"
-  blue: "text-blue-200 bg-blue-500"
-  yellow: "text-yellow-200 bg-blue-500"
-  
-  
-# app/components/example_component/example_component.yml
-btn:
-  purple: "text-purple-200 bg-blue-500"
-  
+```erb
+<!-- Basic usage -->
+<button class="<%= yass(btn: :primary) %>">
+  Click me
+</button>
 
-# app/components/example_component/example_component.html.erb
+<!-- <button class="px-4 py-2 rounded font-medium bg-blue-500 text-white hover:bg-blue-600">Click me</button> -->
+
+<!-- Multiple classes -->
+<button class="<%= yass(btn: :primary, card: :compact) %>">
+  Button in card
+</button>
+
+<!-- <button class="px-4 py-2 rounded font-medium bg-blue-500 text-white hover:bg-blue-600 m-4">Click me</button> -->
+
+<!-- Skip base classes -->
+<button class="<%= yass(btn: :primary, skip_base: true) %>">
+  Button without base
+</button>
 
-<button class="<%=yass(btn: :purple)%>">Classy Button</button>
+<!-- <button class="bg-blue-500 text-white hover:bg-blue-600">Click me</button> -->
 
-# will add the classes "px-3 py-2 text-purple-200 bg-blue-500"
+<!-- With config.override_tag_helpers = true -->
+<%= tag.div class: { btn: :primary, card: :compact } do %>
+  Automatic class processing
+<% end %>
+
+<div class="px-4 py-2 rounded font-medium bg-blue-500 text-white hover:bg-blue-600 m-4"></div>
 ```
 
-As you can see, this will merge definitions found in the `ExampleComponent`'s sidecar asset with the main application's definitions. Not only will it merge, but it will overwrite them as well, allowing for true customization on a per-component basis:
+### ViewComponent Integration
+
+Include the component helpers in your ViewComponent:
 
+```ruby
+class ExampleComponent < ViewComponent::Base
+  include Classy::Yaml::ComponentHelpers
+end
 ```
+
+This will automatically look for a sidecar file `example_component.yml` file alongside your component. For example:
+
+```yaml
 # config/utility_classes.yml
 btn:
   base: "px-3 py-2"
@@ -76,73 +123,38 @@ btn:
   
 # app/components/example_component/example_component.yml
 btn:
-  blue: "text-blue-50"
-  
+  purple: "text-purple-200 bg-blue-500"
+
 
 # app/components/example_component/example_component.html.erb
 
-<button class="<%=yass(btn: :purple)%>">Classy Button</button>
+<button class="<%= yass(btn: :purple) %>">Classy Button</button>
 
-# will add the classes "px-3 py-2 text-blue-50"
+# <button class="px-3 py-2 text-purple-200 bg-blue-500">Click me</button> 
 ```
 
-yass(:button, :primary) # => "btn btn-primary"
-yass(:button, :secondary) # => "btn btn-secondary"
-yass(:button, :large) # => "btn btn-lg"
-yass(:button, :primary, :large) # => "btn btn-primary btn-lg"
-
-### Array style definition
+## Tailwind Merge Integration
 
-```
-array:
-  - "px-3 py-2"
-  - "bg-gray"
-  - "text-purple"
-```
+Classy YAML detects if [tailwind_merge](https://github.com/gjtorikian/tailwind_merge) is installed and will leverage it when fetching classes with `yass`. Please read their documentation for installation and benefits.
 
-yass(:array) # => "px-3 py-2 bg-gray text-purple"
 
-## Configuration
-You can configure the gem by creating an initializer in your Rails app. The following options are available:
+## Configuration Options
 
-```ruby
-Classy::Yaml.setup do |config|
-  # The default path for the utility classes YAML file 
-  config.default_path = "config/utility_classes.yml"
-  
-  # Any extra files you want to load in addition to the default file. The last file loaded will overwrite any previous definitions
-  config.extra_files = [
-    "app/yamls/extra_styles.yml"
-  ]
-end
-```
+| Option | Default | Description |
+|--------|---------|-------------|
+| `default_file` | `"config/utility_classes.yml"` | Path to the main YAML file |
+| `extra_files` | `[]` | Array of additional YAML files (highest priority) |
+| `engine_files` | `[]` | Array of engine YAML files (lowest priority) |
+| `override_tag_helpers` | `false` | Automatically process class symbols/hashes in Rails tag helpers |
 
-## Installation
-Add this line to your application's Gemfile:
+## Contributing
 
-```ruby
-gem 'classy-yaml'
-```
+Bug reports and pull requests are welcome on GitHub at https://github.com/Tonksthebear/classy-yaml. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
 
-And then execute:
-```bash
-$ bundle
-```
+## License
 
-Or install it yourself as:
-```bash
-$ gem install classy-yaml
-```
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-If using purging for styles, be sure to add the YAML files to the purge directories. For example, below is a tailwind.config.js:
-```
-purge: [
-   "./config/utility_classes.yml",
-   "./app/components/**/*.yml" // If using view component sidecar assets
-]
-```
-## Contributing
-This is my first attempt at an actual gem usable for all. Any and all suggestions are absolutely welcome. I'm not the cleanest programmer, so code quality suggestions are welcome too 👍 I extracted this logic from my private work and I felt it was useful enough to be worth publishing.
+## Code of Conduct
 
-## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Everyone interacting in the Classy::Yaml project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/lib/classy/yaml/helpers.rb

@@ -34,11 +34,39 @@ module Classy
         keys, classes = flatten_args(values: args)
         classes += fetch_classes(keys, classy_yamls: classy_yamls, skip_base: skip_base_hash[:skip_base])
 
-        classes.flatten.uniq.join(" ")
+        # Use tailwind_merge if available, otherwise fall back to simple join
+        merge_classes(classes.flatten.uniq)
       end
 
       private
 
+      # Merges CSS classes using tailwind_merge if available, otherwise uses simple join
+      # @param classes [Array] Array of CSS class strings
+      # @return [String] Merged CSS classes
+      def merge_classes(classes)
+        return "" if classes.blank?
+
+        if tailwind_merge_available?
+          # Use tailwind_merge for intelligent class merging
+          TailwindMerge::Merger.new.merge(classes)
+        else
+          # Fall back to simple space-joined classes
+          classes.join(" ")
+        end
+      end
+
+      # Checks if tailwind_merge gem is available
+      # @return [Boolean] True if tailwind_merge is available
+      def tailwind_merge_available?
+        return @tailwind_merge_available if defined?(@tailwind_merge_available)
+        @tailwind_merge_available = begin
+          require "tailwind_merge"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
       # Loads a YAML file and adds its contents to the classy_yamls array
       # @param file_path [String, Pathname] Path to the YAML file
       # @param classy_yamls [Array] Array to add the parsed YAML to

data/lib/classy/yaml/version.rb

@@ -1,5 +1,5 @@
 module Classy
   module Yaml
-    VERSION = "1.5.0"
+    VERSION = "1.6.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: classy-yaml
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Tonksthebear
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6'
+- !ruby/object:Gem::Dependency
+  name: tailwind_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement