classlist 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0623abc0509ba65bd66bc3147ee059f7d6424f082e21867031998fa66469b1f7
-  data.tar.gz: b9c6713cebf59a58ab5a436db88249601e04fe24b8bc553775675ffdebb44361
+  metadata.gz: 3b46ec60d2055c6c957a429f49af57adf78b063f933334cdac92d9b62a669f6f
+  data.tar.gz: b1ead5e0df053f41a9faf85d4b02345910e9efe5479ec5cb483eba116aae0975
 SHA512:
-  metadata.gz: 4fec82f539a407cf44e97beb4b83d60caf72c48ed3818e56c3900e19d53a31497729887a1f14f62fe4ffd68a7e7bb32665893d15d2fe2d9777b7469f7f9fcbb1
-  data.tar.gz: c8bc4baae23c82f8291fb78ed0da3a251aace747016a510304021413b8e6855bcf192fe38703eb47fd213107ae6dd82b02509b3be2bf6ebf34346c963a773af7
+  metadata.gz: 2012cbfeea055153c58050c0e6061157bca4228c97372cddb5b7c0072abac3969c9fb20be3ef8e30c56d58845aa9c521e2b4f2b787d3c0a9c8d3bfc7afa28a41
+  data.tar.gz: 84a6d60146e626e2e0cef6cc6b4b31a72e459d1dcbe01848ebeb5bf4907d0eb04c78c50564c10dfdab53099aecd18a9055b447f13c88be9aaa890c1c36cfdc21

data/CHANGELOG.md

@@ -9,4 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Everything :)
+-
+
+## [1.0.0]
+
+### Added
+
+- Classlist::Reset that replaces all entries when merged
+- Classlist::Remove that removes entries when merged
+- DOMTokenList compatible Classlist class.

data/README.md

@@ -1,8 +1,6 @@
 # Classlist
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/classlist`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Serverside manipulation of CSS class lists. Works especially well with Tailwind and View Components.
 
 ## Installation
 
@@ -22,7 +20,93 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Imagine having a component that outputs the following markup when you render it:
+
+```erb
+<%= render(CardComponent.new) %>
+```
+
+```html
+<div class="card float-left">...</div>
+```
+
+Now you're tasked with implementing a card with another background color. That's easy, you think, I'll just add an option that adds more classes to the component:
+
+```erb
+<%= render(CardComponent.new(:classes => "bg-grey")) %>
+<!-- card.html.erb -->
+<div class="card float-left <%= classes %>">
+```
+
+That works and all is well. But next day the task is to make a card that isn't floated left. You could remove `float-left` from the template and move it to all calls to render:
+
+```erb
+<%= render(CardComponent.new(:classes => "float-left bg-grey")) %>
+<!-- card.html.erb -->
+<div class="card <%= classes %>">
+```
+
+Depending on the number of classes and the number of render calls that could work. But how about if you were able to write
+
+```erb
+<%= render(CardComponent.new(:classes => Classlist::Remove.new("float-left"))) %>
+```
+
+With Classlist you can:
+
+```ruby
+# card_component.rb
+def classes
+  Classlist.new("card float-left") + @classes
+end
+```
+
+```erb
+<!-- card.html.erb -->
+<div class="<%= classes %>">
+```
+
+The resulting markup will be
+
+```html
+<div class="card">
+```
+
+because
+
+```ruby
+Classlist.new("card float-left") + Classlist::Remove.new("float-left") == Classlist.new("card")
+```
+
+### Basic usage
+
+```ruby
+# Create a new classlist - these are equivalent:
+classes = Classlist.new("pt-6 space-y-4")
+classes = Classlist.new(["pt-6", "space-y-4"])
+
+# Add classes
+classes.add("md:p-8 text-center")
+classes.to_s #=> "pt-6 space-y-4 md:p-8 text-center"
+
+# Remove classes
+classes.remove("md:p-8")
+classes.to_s #=> "pt-6 space-y-4 text-center"
+
+# Toggle classes
+classes.toggle("hidden")
+classes.to_s #=> "pt-6 space-y-4 text-center hidden"
+classes.toggle("text-center")
+classes.to_s #=> "pt-6 space-y-4 hidden"
+
+# Replace classes
+classes.replace("hidden", "block")
+classes.to_s #=> "pt-6 space-y-4 block"
+```
+
+## DOM compatibility
+
+While Classlist aims to be a feature-compatible version of [`DOMTokenList`](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList) that doesn't always make for particularily Ruby'esque methods. In cases where Ruby has similar methods named differently than the DOM, we'll prefer Ruby-style method names while keeping aliases with the names from `DOMTokenList`.
 
 ## Development
 
@@ -32,4 +116,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/koppen/classlist.
+Bug reports and pull requests are welcome on GitHub at https://github.com/substancelab/classlist.

data/lib/classlist/remove.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "classlist"
+
+# Classlist::Remove is a classlist that removes tokens from the original
+# classlist when added to it.
+class Classlist::Remove < Classlist
+  def merge(original)
+    original.entries - entries
+  end
+end

data/lib/classlist/reset.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "classlist"
+
+# Classlist::Reset is a classlist that removes all tokens from the original
+# classlist when merged.
+class Classlist::Reset < Classlist
+  def merge(original)
+    original.entries.replace(entries)
+  end
+end

data/lib/classlist/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Classlist
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/lib/classlist.rb

@@ -1,12 +1,36 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 require_relative "classlist/version"
 
 class Classlist
+  class ArgumentError < ::ArgumentError; end
+
   class Error < StandardError; end
 
+  extend Forwardable
+  def_delegators :@entries, :each
+
   attr_reader :entries
 
+  # Returns the Classlist resulting from adding other to this classlist.
+  def +(other)
+    result = if other.is_a?(Classlist)
+      other.merge(self)
+    else
+      entries + build_entries(other)
+    end
+
+    Classlist.new(result)
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    entries == other.entries
+  end
+
   # Adds the given tokens to the list, omitting any that are already present.
   def add(tokens)
     entries = build_entries(tokens)
@@ -15,10 +39,33 @@ class Classlist
     end
   end
 
+  def include?(token)
+    entries.include?(token)
+  end
+  alias_method :contains, :include?
+
   def initialize(entries = [])
     @entries = build_entries(entries)
   end
 
+  # Returns the item in the list by its index, or null if the index is greater
+  # than or equal to the list's length.
+  def item(index)
+    return nil if index.negative?
+
+    entries[index]
+  end
+
+  # An integer representing the number of objects stored in the object.
+  def length
+    entries.length
+  end
+
+  # Returns a list of tokens in this classlist merged with the given classlist.
+  def merge(classlist)
+    (classlist.entries + entries).uniq
+  end
+
   # Removes the specified tokens from the classlist, ignoring any that are not
   # present.
   def remove(tokens)
@@ -32,10 +79,10 @@ class Classlist
   # exist, #replace returns false immediately, without adding the new token to
   # the token list.
   def replace(old_token, new_token)
-    return false unless entries.include?(old_token)
+    return false unless include?(old_token)
 
-    if entries.include?(new_token)
-      entries.delete(old_token)
+    if include?(new_token)
+      remove(old_token)
     else
       index = entries.index(old_token)
       entries[index] = new_token
@@ -51,6 +98,7 @@ class Classlist
   def to_s
     entries.join(" ")
   end
+  alias_method :value, :to_s
 
   # Removes an existing token from the list and returns false. If the token
   # doesn't exist it's added and the function returns true.
@@ -59,11 +107,13 @@ class Classlist
   # set to false, then token will only be removed, but not added. If set to
   # true, then token will only be added, but not removed.
   def toggle(token, force = nil)
+    raise ArgumentError, "The token can not contain whitespace." if token.to_s.include?(" ")
+
     if entries.include?(token)
-      entries.delete(token) unless force == true
+      remove(token) unless force == true
       result = false
     else
-      entries.push(token) unless force == false
+      add(token) unless force == false
       result = true
     end
 
@@ -90,6 +140,6 @@ class Classlist
       entries.split(" ")
     else
       raise Error, "Invalid entries: #{entries.inspect}"
-    end
+    end.uniq
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: classlist
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Jakob Skjerning
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-29 00:00:00.000000000 Z
+date: 2022-11-04 00:00:00.000000000 Z
 dependencies: []
 description: Serverside manipulation of lists of CSS classnames that play nicely with
   View Components.
@@ -28,6 +28,8 @@ files:
 - bin/setup
 - classlist.gemspec
 - lib/classlist.rb
+- lib/classlist/remove.rb
+- lib/classlist/reset.rb
 - lib/classlist/version.rb
 - sig/classlist.rbs
 homepage: https://github.com/substancelab/classlist