classlist 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0623abc0509ba65bd66bc3147ee059f7d6424f082e21867031998fa66469b1f7
-  data.tar.gz: b9c6713cebf59a58ab5a436db88249601e04fe24b8bc553775675ffdebb44361
+  metadata.gz: 13b03b38d0d38240cdabd34d10b534b811b5b292eea5c4e43eabd24f5ab199dc
+  data.tar.gz: d83e6fac0aacdb375188e2d5b633bc0a3e7f2f758ef1ff6262ac93ca544b8b5a
 SHA512:
-  metadata.gz: 4fec82f539a407cf44e97beb4b83d60caf72c48ed3818e56c3900e19d53a31497729887a1f14f62fe4ffd68a7e7bb32665893d15d2fe2d9777b7469f7f9fcbb1
-  data.tar.gz: c8bc4baae23c82f8291fb78ed0da3a251aace747016a510304021413b8e6855bcf192fe38703eb47fd213107ae6dd82b02509b3be2bf6ebf34346c963a773af7
+  metadata.gz: 00bff560b1cd9064b353dd1979f0d5644bbe1e861d6ea0d646e4a25cb16c7eb3ae51b66e49bbcf13fb15531065a6b9d5d4818879088ceca8434174bffc082075
+  data.tar.gz: 418764901609311aea4f245cda2d297110a932402a61aa4999f79955e37e4221f8509b6a91a5f86e168ca7cff62c8b1455b8156be3a97b517d4c81ec3ec92311

data/CHANGELOG.md

@@ -9,4 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Everything :)
+- Support for chains of operations longer than the most simple cases.
+- Introduce Classlist::Operation as a common super class for Classlist::Add, Classlist::Remove, Classlist::Reset.
+- Classlist::Add that adds all entries when merged
+
+## [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
 
@@ -10,6 +8,8 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem 'classlist'
+# or if you don't want to manually require stuff:
+gem 'classlist', require: 'classlist/all'
 ```
 
 And then execute:
@@ -22,7 +22,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 +118,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/add.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "classlist/operation"
+
+# Classlist::Add is an operation that adds tokens to the original
+# classlist when added to it.
+class Classlist::Add < Classlist::Operation
+  def merge(original)
+    original.entries + entries
+  end
+
+  # resolve changes the original classlist
+  def resolve(original)
+    entries.each do |entry|
+      original.add(entry)
+    end
+
+    super
+  end
+end

data/lib/classlist/all.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Require this file to load all of Classlist into your application.
+#
+# For example in a Gemfile:
+#
+#   gem "classlist", require: "classlist/all"
+#
+# Or you can just require what you need manually.
+
+require "classlist/add"
+require "classlist/remove"
+require "classlist/reset"

data/lib/classlist/operation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "classlist"
+
+# Classlist::Operations modify the original classlist
+class Classlist::Operation < Classlist
+  # resolve changes the original classlist
+  def resolve(original_classlist)
+    resolve_operations(original_classlist)
+  end
+end

data/lib/classlist/remove.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "classlist/operation"
+
+# Classlist::Remove is an operation that removes tokens from the original
+# classlist when added to it.
+class Classlist::Remove < Classlist::Operation
+  def merge(original)
+    original.entries - entries
+  end
+
+  # #resolve changes the original classlist
+  def resolve(original)
+    entries.each do |entry|
+      original.remove(entry)
+    end
+
+    super
+  end
+end

data/lib/classlist/reset.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "classlist/operation"
+
+# Classlist::Reset is an operation that removes all tokens from the original
+# classlist when merged.
+class Classlist::Reset < Classlist::Operation
+  def merge(original)
+    original.entries.replace(entries)
+  end
+
+  # #resolve changes the original classlist
+  def resolve(original)
+    original.entries.replace(entries)
+
+    super
+  end
+end

data/lib/classlist/version.rb

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

data/lib/classlist.rb

@@ -1,11 +1,42 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 require_relative "classlist/version"
 
 class Classlist
+  class ArgumentError < ::ArgumentError; end
+
   class Error < StandardError; end
 
-  attr_reader :entries
+  extend Forwardable
+  def_delegators :@entries, :each
+
+  attr_reader :entries, :operations
+
+  # Returns the Classlist resulting from adding other to this classlist.
+  def +(other)
+    case other
+    when Classlist::Operation
+      add_operation(other)
+      self
+    when Classlist
+      result = other.merge(self)
+      Classlist.new(result)
+    else
+      result = entries + build_entries(other)
+      Classlist.new(result)
+    end
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+
+    resolve_operations(self)
+    other.resolve_operations
+
+    @entries == other.entries
+  end
 
   # Adds the given tokens to the list, omitting any that are already present.
   def add(tokens)
@@ -15,8 +46,36 @@ class Classlist
     end
   end
 
+  def add_operation(other)
+    @operations << other
+  end
+
+  def include?(token)
+    entries.include?(token)
+  end
+  alias_method :contains, :include?
+
   def initialize(entries = [])
     @entries = build_entries(entries)
+    @operations = []
+  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
@@ -32,10 +91,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
@@ -44,13 +103,21 @@ class Classlist
     true
   end
 
+  def resolve_operations(original_classlist = self)
+    operations.each do |operation|
+      operation.resolve(original_classlist)
+    end
+  end
+
   def to_a
-    entries
+    resolve_operations(self)
+    @entries
   end
 
   def to_s
-    entries.join(" ")
+    to_a.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 +126,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 +159,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.1.0
 platform: ruby
 authors:
 - Jakob Skjerning
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-29 00:00:00.000000000 Z
+date: 2022-11-07 00:00:00.000000000 Z
 dependencies: []
 description: Serverside manipulation of lists of CSS classnames that play nicely with
   View Components.
@@ -28,6 +28,11 @@ files:
 - bin/setup
 - classlist.gemspec
 - lib/classlist.rb
+- lib/classlist/add.rb
+- lib/classlist/all.rb
+- lib/classlist/operation.rb
+- lib/classlist/remove.rb
+- lib/classlist/reset.rb
 - lib/classlist/version.rb
 - sig/classlist.rbs
 homepage: https://github.com/substancelab/classlist